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