1 /* 2 * SSL/TLS interface definition 3 * Copyright (c) 2004-2013, Jouni Malinen <j@w1.fi> 4 * 5 * This software may be distributed under the terms of the BSD license. 6 * See README for more details. 7 */ 8 9 #ifndef TLS_H 10 #define TLS_H 11 12 struct tls_connection; 13 14 struct tls_keys { 15 const u8 *master_key; /* TLS master secret */ 16 size_t master_key_len; 17 const u8 *client_random; 18 size_t client_random_len; 19 const u8 *server_random; 20 size_t server_random_len; 21 }; 22 23 enum tls_event { 24 TLS_CERT_CHAIN_SUCCESS, 25 TLS_CERT_CHAIN_FAILURE, 26 TLS_PEER_CERTIFICATE, 27 TLS_ALERT 28 }; 29 30 /* 31 * Note: These are used as identifier with external programs and as such, the 32 * values must not be changed. 33 */ 34 enum tls_fail_reason { 35 TLS_FAIL_UNSPECIFIED = 0, 36 TLS_FAIL_UNTRUSTED = 1, 37 TLS_FAIL_REVOKED = 2, 38 TLS_FAIL_NOT_YET_VALID = 3, 39 TLS_FAIL_EXPIRED = 4, 40 TLS_FAIL_SUBJECT_MISMATCH = 5, 41 TLS_FAIL_ALTSUBJECT_MISMATCH = 6, 42 TLS_FAIL_BAD_CERTIFICATE = 7, 43 TLS_FAIL_SERVER_CHAIN_PROBE = 8, 44 TLS_FAIL_DOMAIN_SUFFIX_MISMATCH = 9, 45 TLS_FAIL_SERVER_USED_CLIENT_CERT = 10 46 }; 47 48 union tls_event_data { 49 struct { 50 int depth; 51 const char *subject; 52 enum tls_fail_reason reason; 53 const char *reason_txt; 54 const struct wpabuf *cert; 55 } cert_fail; 56 57 struct { 58 int depth; 59 const char *subject; 60 const struct wpabuf *cert; 61 const u8 *hash; 62 size_t hash_len; 63 } peer_cert; 64 65 struct { 66 int is_local; 67 const char *type; 68 const char *description; 69 } alert; 70 }; 71 72 struct tls_config { 73 const char *opensc_engine_path; 74 const char *pkcs11_engine_path; 75 const char *pkcs11_module_path; 76 int fips_mode; 77 int cert_in_cb; 78 79 void (*event_cb)(void *ctx, enum tls_event ev, 80 union tls_event_data *data); 81 void *cb_ctx; 82 }; 83 84 #define TLS_CONN_ALLOW_SIGN_RSA_MD5 BIT(0) 85 #define TLS_CONN_DISABLE_TIME_CHECKS BIT(1) 86 #define TLS_CONN_DISABLE_SESSION_TICKET BIT(2) 87 #define TLS_CONN_REQUEST_OCSP BIT(3) 88 #define TLS_CONN_REQUIRE_OCSP BIT(4) 89 90 /** 91 * struct tls_connection_params - Parameters for TLS connection 92 * @ca_cert: File or reference name for CA X.509 certificate in PEM or DER 93 * format 94 * @ca_cert_blob: ca_cert as inlined data or %NULL if not used 95 * @ca_cert_blob_len: ca_cert_blob length 96 * @ca_path: Path to CA certificates (OpenSSL specific) 97 * @subject_match: String to match in the subject of the peer certificate or 98 * %NULL to allow all subjects 99 * @altsubject_match: String to match in the alternative subject of the peer 100 * certificate or %NULL to allow all alternative subjects 101 * @suffix_match: String to suffix match in the dNSName or CN of the peer 102 * certificate or %NULL to allow all domain names 103 * @client_cert: File or reference name for client X.509 certificate in PEM or 104 * DER format 105 * @client_cert_blob: client_cert as inlined data or %NULL if not used 106 * @client_cert_blob_len: client_cert_blob length 107 * @private_key: File or reference name for client private key in PEM or DER 108 * format (traditional format (RSA PRIVATE KEY) or PKCS#8 (PRIVATE KEY) 109 * @private_key_blob: private_key as inlined data or %NULL if not used 110 * @private_key_blob_len: private_key_blob length 111 * @private_key_passwd: Passphrase for decrypted private key, %NULL if no 112 * passphrase is used. 113 * @dh_file: File name for DH/DSA data in PEM format, or %NULL if not used 114 * @dh_blob: dh_file as inlined data or %NULL if not used 115 * @dh_blob_len: dh_blob length 116 * @engine: 1 = use engine (e.g., a smartcard) for private key operations 117 * (this is OpenSSL specific for now) 118 * @engine_id: engine id string (this is OpenSSL specific for now) 119 * @ppin: pointer to the pin variable in the configuration 120 * (this is OpenSSL specific for now) 121 * @key_id: the private key's id when using engine (this is OpenSSL 122 * specific for now) 123 * @cert_id: the certificate's id when using engine 124 * @ca_cert_id: the CA certificate's id when using engine 125 * @flags: Parameter options (TLS_CONN_*) 126 * @ocsp_stapling_response: DER encoded file with cached OCSP stapling response 127 * or %NULL if OCSP is not enabled 128 * 129 * TLS connection parameters to be configured with tls_connection_set_params() 130 * and tls_global_set_params(). 131 * 132 * Certificates and private key can be configured either as a reference name 133 * (file path or reference to certificate store) or by providing the same data 134 * as a pointer to the data in memory. Only one option will be used for each 135 * field. 136 */ 137 struct tls_connection_params { 138 const char *ca_cert; 139 const u8 *ca_cert_blob; 140 size_t ca_cert_blob_len; 141 const char *ca_path; 142 const char *subject_match; 143 const char *altsubject_match; 144 const char *suffix_match; 145 const char *client_cert; 146 const u8 *client_cert_blob; 147 size_t client_cert_blob_len; 148 const char *private_key; 149 const u8 *private_key_blob; 150 size_t private_key_blob_len; 151 const char *private_key_passwd; 152 const char *dh_file; 153 const u8 *dh_blob; 154 size_t dh_blob_len; 155 156 /* OpenSSL specific variables */ 157 int engine; 158 const char *engine_id; 159 const char *pin; 160 const char *key_id; 161 const char *cert_id; 162 const char *ca_cert_id; 163 164 unsigned int flags; 165 const char *ocsp_stapling_response; 166 }; 167 168 169 /** 170 * tls_init - Initialize TLS library 171 * @conf: Configuration data for TLS library 172 * Returns: Context data to be used as tls_ctx in calls to other functions, 173 * or %NULL on failure. 174 * 175 * Called once during program startup and once for each RSN pre-authentication 176 * session. In other words, there can be two concurrent TLS contexts. If global 177 * library initialization is needed (i.e., one that is shared between both 178 * authentication types), the TLS library wrapper should maintain a reference 179 * counter and do global initialization only when moving from 0 to 1 reference. 180 */ 181 void * tls_init(const struct tls_config *conf); 182 183 /** 184 * tls_deinit - Deinitialize TLS library 185 * @tls_ctx: TLS context data from tls_init() 186 * 187 * Called once during program shutdown and once for each RSN pre-authentication 188 * session. If global library deinitialization is needed (i.e., one that is 189 * shared between both authentication types), the TLS library wrapper should 190 * maintain a reference counter and do global deinitialization only when moving 191 * from 1 to 0 references. 192 */ 193 void tls_deinit(void *tls_ctx); 194 195 /** 196 * tls_get_errors - Process pending errors 197 * @tls_ctx: TLS context data from tls_init() 198 * Returns: Number of found error, 0 if no errors detected. 199 * 200 * Process all pending TLS errors. 201 */ 202 int tls_get_errors(void *tls_ctx); 203 204 /** 205 * tls_connection_init - Initialize a new TLS connection 206 * @tls_ctx: TLS context data from tls_init() 207 * Returns: Connection context data, conn for other function calls 208 */ 209 struct tls_connection * tls_connection_init(void *tls_ctx); 210 211 /** 212 * tls_connection_deinit - Free TLS connection data 213 * @tls_ctx: TLS context data from tls_init() 214 * @conn: Connection context data from tls_connection_init() 215 * 216 * Release all resources allocated for TLS connection. 217 */ 218 void tls_connection_deinit(void *tls_ctx, struct tls_connection *conn); 219 220 /** 221 * tls_connection_established - Has the TLS connection been completed? 222 * @tls_ctx: TLS context data from tls_init() 223 * @conn: Connection context data from tls_connection_init() 224 * Returns: 1 if TLS connection has been completed, 0 if not. 225 */ 226 int tls_connection_established(void *tls_ctx, struct tls_connection *conn); 227 228 /** 229 * tls_connection_shutdown - Shutdown TLS connection 230 * @tls_ctx: TLS context data from tls_init() 231 * @conn: Connection context data from tls_connection_init() 232 * Returns: 0 on success, -1 on failure 233 * 234 * Shutdown current TLS connection without releasing all resources. New 235 * connection can be started by using the same conn without having to call 236 * tls_connection_init() or setting certificates etc. again. The new 237 * connection should try to use session resumption. 238 */ 239 int tls_connection_shutdown(void *tls_ctx, struct tls_connection *conn); 240 241 enum { 242 TLS_SET_PARAMS_ENGINE_PRV_VERIFY_FAILED = -3, 243 TLS_SET_PARAMS_ENGINE_PRV_INIT_FAILED = -2 244 }; 245 246 /** 247 * tls_connection_set_params - Set TLS connection parameters 248 * @tls_ctx: TLS context data from tls_init() 249 * @conn: Connection context data from tls_connection_init() 250 * @params: Connection parameters 251 * Returns: 0 on success, -1 on failure, 252 * TLS_SET_PARAMS_ENGINE_PRV_INIT_FAILED (-2) on possible PIN error causing 253 * PKCS#11 engine failure, or 254 * TLS_SET_PARAMS_ENGINE_PRV_VERIFY_FAILED (-3) on failure to verify the 255 * PKCS#11 engine private key. 256 */ 257 int __must_check 258 tls_connection_set_params(void *tls_ctx, struct tls_connection *conn, 259 const struct tls_connection_params *params); 260 261 /** 262 * tls_global_set_params - Set TLS parameters for all TLS connection 263 * @tls_ctx: TLS context data from tls_init() 264 * @params: Global TLS parameters 265 * Returns: 0 on success, -1 on failure, 266 * TLS_SET_PARAMS_ENGINE_PRV_INIT_FAILED (-2) on possible PIN error causing 267 * PKCS#11 engine failure, or 268 * TLS_SET_PARAMS_ENGINE_PRV_VERIFY_FAILED (-3) on failure to verify the 269 * PKCS#11 engine private key. 270 */ 271 int __must_check tls_global_set_params( 272 void *tls_ctx, const struct tls_connection_params *params); 273 274 /** 275 * tls_global_set_verify - Set global certificate verification options 276 * @tls_ctx: TLS context data from tls_init() 277 * @check_crl: 0 = do not verify CRLs, 1 = verify CRL for the user certificate, 278 * 2 = verify CRL for all certificates 279 * Returns: 0 on success, -1 on failure 280 */ 281 int __must_check tls_global_set_verify(void *tls_ctx, int check_crl); 282 283 /** 284 * tls_connection_set_verify - Set certificate verification options 285 * @tls_ctx: TLS context data from tls_init() 286 * @conn: Connection context data from tls_connection_init() 287 * @verify_peer: 1 = verify peer certificate 288 * Returns: 0 on success, -1 on failure 289 */ 290 int __must_check tls_connection_set_verify(void *tls_ctx, 291 struct tls_connection *conn, 292 int verify_peer); 293 294 /** 295 * tls_connection_get_keys - Get master key and random data from TLS connection 296 * @tls_ctx: TLS context data from tls_init() 297 * @conn: Connection context data from tls_connection_init() 298 * @keys: Structure of key/random data (filled on success) 299 * Returns: 0 on success, -1 on failure 300 */ 301 int __must_check tls_connection_get_keys(void *tls_ctx, 302 struct tls_connection *conn, 303 struct tls_keys *keys); 304 305 /** 306 * tls_connection_prf - Use TLS-PRF to derive keying material 307 * @tls_ctx: TLS context data from tls_init() 308 * @conn: Connection context data from tls_connection_init() 309 * @label: Label (e.g., description of the key) for PRF 310 * @server_random_first: seed is 0 = client_random|server_random, 311 * 1 = server_random|client_random 312 * @out: Buffer for output data from TLS-PRF 313 * @out_len: Length of the output buffer 314 * Returns: 0 on success, -1 on failure 315 * 316 * This function is optional to implement if tls_connection_get_keys() provides 317 * access to master secret and server/client random values. If these values are 318 * not exported from the TLS library, tls_connection_prf() is required so that 319 * further keying material can be derived from the master secret. If not 320 * implemented, the function will still need to be defined, but it can just 321 * return -1. Example implementation of this function is in tls_prf_sha1_md5() 322 * when it is called with seed set to client_random|server_random (or 323 * server_random|client_random). 324 */ 325 int __must_check tls_connection_prf(void *tls_ctx, 326 struct tls_connection *conn, 327 const char *label, 328 int server_random_first, 329 u8 *out, size_t out_len); 330 331 /** 332 * tls_connection_handshake - Process TLS handshake (client side) 333 * @tls_ctx: TLS context data from tls_init() 334 * @conn: Connection context data from tls_connection_init() 335 * @in_data: Input data from TLS server 336 * @appl_data: Pointer to application data pointer, or %NULL if dropped 337 * Returns: Output data, %NULL on failure 338 * 339 * The caller is responsible for freeing the returned output data. If the final 340 * handshake message includes application data, this is decrypted and 341 * appl_data (if not %NULL) is set to point this data. The caller is 342 * responsible for freeing appl_data. 343 * 344 * This function is used during TLS handshake. The first call is done with 345 * in_data == %NULL and the library is expected to return ClientHello packet. 346 * This packet is then send to the server and a response from server is given 347 * to TLS library by calling this function again with in_data pointing to the 348 * TLS message from the server. 349 * 350 * If the TLS handshake fails, this function may return %NULL. However, if the 351 * TLS library has a TLS alert to send out, that should be returned as the 352 * output data. In this case, tls_connection_get_failed() must return failure 353 * (> 0). 354 * 355 * tls_connection_established() should return 1 once the TLS handshake has been 356 * completed successfully. 357 */ 358 struct wpabuf * tls_connection_handshake(void *tls_ctx, 359 struct tls_connection *conn, 360 const struct wpabuf *in_data, 361 struct wpabuf **appl_data); 362 363 struct wpabuf * tls_connection_handshake2(void *tls_ctx, 364 struct tls_connection *conn, 365 const struct wpabuf *in_data, 366 struct wpabuf **appl_data, 367 int *more_data_needed); 368 369 /** 370 * tls_connection_server_handshake - Process TLS handshake (server side) 371 * @tls_ctx: TLS context data from tls_init() 372 * @conn: Connection context data from tls_connection_init() 373 * @in_data: Input data from TLS peer 374 * @appl_data: Pointer to application data pointer, or %NULL if dropped 375 * Returns: Output data, %NULL on failure 376 * 377 * The caller is responsible for freeing the returned output data. 378 */ 379 struct wpabuf * tls_connection_server_handshake(void *tls_ctx, 380 struct tls_connection *conn, 381 const struct wpabuf *in_data, 382 struct wpabuf **appl_data); 383 384 /** 385 * tls_connection_encrypt - Encrypt data into TLS tunnel 386 * @tls_ctx: TLS context data from tls_init() 387 * @conn: Connection context data from tls_connection_init() 388 * @in_data: Plaintext data to be encrypted 389 * Returns: Encrypted TLS data or %NULL on failure 390 * 391 * This function is used after TLS handshake has been completed successfully to 392 * send data in the encrypted tunnel. The caller is responsible for freeing the 393 * returned output data. 394 */ 395 struct wpabuf * tls_connection_encrypt(void *tls_ctx, 396 struct tls_connection *conn, 397 const struct wpabuf *in_data); 398 399 /** 400 * tls_connection_decrypt - Decrypt data from TLS tunnel 401 * @tls_ctx: TLS context data from tls_init() 402 * @conn: Connection context data from tls_connection_init() 403 * @in_data: Encrypted TLS data 404 * Returns: Decrypted TLS data or %NULL on failure 405 * 406 * This function is used after TLS handshake has been completed successfully to 407 * receive data from the encrypted tunnel. The caller is responsible for 408 * freeing the returned output data. 409 */ 410 struct wpabuf * tls_connection_decrypt(void *tls_ctx, 411 struct tls_connection *conn, 412 const struct wpabuf *in_data); 413 414 struct wpabuf * tls_connection_decrypt2(void *tls_ctx, 415 struct tls_connection *conn, 416 const struct wpabuf *in_data, 417 int *more_data_needed); 418 419 /** 420 * tls_connection_resumed - Was session resumption used 421 * @tls_ctx: TLS context data from tls_init() 422 * @conn: Connection context data from tls_connection_init() 423 * Returns: 1 if current session used session resumption, 0 if not 424 */ 425 int tls_connection_resumed(void *tls_ctx, struct tls_connection *conn); 426 427 enum { 428 TLS_CIPHER_NONE, 429 TLS_CIPHER_RC4_SHA /* 0x0005 */, 430 TLS_CIPHER_AES128_SHA /* 0x002f */, 431 TLS_CIPHER_RSA_DHE_AES128_SHA /* 0x0031 */, 432 TLS_CIPHER_ANON_DH_AES128_SHA /* 0x0034 */ 433 }; 434 435 /** 436 * tls_connection_set_cipher_list - Configure acceptable cipher suites 437 * @tls_ctx: TLS context data from tls_init() 438 * @conn: Connection context data from tls_connection_init() 439 * @ciphers: Zero (TLS_CIPHER_NONE) terminated list of allowed ciphers 440 * (TLS_CIPHER_*). 441 * Returns: 0 on success, -1 on failure 442 */ 443 int __must_check tls_connection_set_cipher_list(void *tls_ctx, 444 struct tls_connection *conn, 445 u8 *ciphers); 446 447 /** 448 * tls_get_cipher - Get current cipher name 449 * @tls_ctx: TLS context data from tls_init() 450 * @conn: Connection context data from tls_connection_init() 451 * @buf: Buffer for the cipher name 452 * @buflen: buf size 453 * Returns: 0 on success, -1 on failure 454 * 455 * Get the name of the currently used cipher. 456 */ 457 int __must_check tls_get_cipher(void *tls_ctx, struct tls_connection *conn, 458 char *buf, size_t buflen); 459 460 /** 461 * tls_connection_enable_workaround - Enable TLS workaround options 462 * @tls_ctx: TLS context data from tls_init() 463 * @conn: Connection context data from tls_connection_init() 464 * Returns: 0 on success, -1 on failure 465 * 466 * This function is used to enable connection-specific workaround options for 467 * buffer SSL/TLS implementations. 468 */ 469 int __must_check tls_connection_enable_workaround(void *tls_ctx, 470 struct tls_connection *conn); 471 472 /** 473 * tls_connection_client_hello_ext - Set TLS extension for ClientHello 474 * @tls_ctx: TLS context data from tls_init() 475 * @conn: Connection context data from tls_connection_init() 476 * @ext_type: Extension type 477 * @data: Extension payload (%NULL to remove extension) 478 * @data_len: Extension payload length 479 * Returns: 0 on success, -1 on failure 480 */ 481 int __must_check tls_connection_client_hello_ext(void *tls_ctx, 482 struct tls_connection *conn, 483 int ext_type, const u8 *data, 484 size_t data_len); 485 486 /** 487 * tls_connection_get_failed - Get connection failure status 488 * @tls_ctx: TLS context data from tls_init() 489 * @conn: Connection context data from tls_connection_init() 490 * 491 * Returns >0 if connection has failed, 0 if not. 492 */ 493 int tls_connection_get_failed(void *tls_ctx, struct tls_connection *conn); 494 495 /** 496 * tls_connection_get_read_alerts - Get connection read alert status 497 * @tls_ctx: TLS context data from tls_init() 498 * @conn: Connection context data from tls_connection_init() 499 * Returns: Number of times a fatal read (remote end reported error) has 500 * happened during this connection. 501 */ 502 int tls_connection_get_read_alerts(void *tls_ctx, struct tls_connection *conn); 503 504 /** 505 * tls_connection_get_write_alerts - Get connection write alert status 506 * @tls_ctx: TLS context data from tls_init() 507 * @conn: Connection context data from tls_connection_init() 508 * Returns: Number of times a fatal write (locally detected error) has happened 509 * during this connection. 510 */ 511 int tls_connection_get_write_alerts(void *tls_ctx, 512 struct tls_connection *conn); 513 514 /** 515 * tls_connection_get_keyblock_size - Get TLS key_block size 516 * @tls_ctx: TLS context data from tls_init() 517 * @conn: Connection context data from tls_connection_init() 518 * Returns: Size of the key_block for the negotiated cipher suite or -1 on 519 * failure 520 */ 521 int tls_connection_get_keyblock_size(void *tls_ctx, 522 struct tls_connection *conn); 523 524 /** 525 * tls_capabilities - Get supported TLS capabilities 526 * @tls_ctx: TLS context data from tls_init() 527 * Returns: Bit field of supported TLS capabilities (TLS_CAPABILITY_*) 528 */ 529 unsigned int tls_capabilities(void *tls_ctx); 530 531 typedef int (*tls_session_ticket_cb) 532 (void *ctx, const u8 *ticket, size_t len, const u8 *client_random, 533 const u8 *server_random, u8 *master_secret); 534 535 int __must_check tls_connection_set_session_ticket_cb( 536 void *tls_ctx, struct tls_connection *conn, 537 tls_session_ticket_cb cb, void *ctx); 538 539 #endif /* TLS_H */ 540