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