2 * SSL/TLS interface definition
3 * Copyright (c) 2004-2010, Jouni Malinen <j@w1.fi>
5 * This software may be distributed under the terms of the BSD license.
6 * See README for more details.
12 struct tls_connection;
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;
24 TLS_CERT_CHAIN_SUCCESS,
25 TLS_CERT_CHAIN_FAILURE,
31 * Note: These are used as identifier with external programs and as such, the
32 * values must not be changed.
34 enum tls_fail_reason {
35 TLS_FAIL_UNSPECIFIED = 0,
36 TLS_FAIL_UNTRUSTED = 1,
38 TLS_FAIL_NOT_YET_VALID = 3,
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
46 union tls_event_data {
50 enum tls_fail_reason reason;
51 const char *reason_txt;
52 const struct wpabuf *cert;
58 const struct wpabuf *cert;
66 const char *description;
71 const char *opensc_engine_path;
72 const char *pkcs11_engine_path;
73 const char *pkcs11_module_path;
77 void (*event_cb)(void *ctx, enum tls_event ev,
78 union tls_event_data *data);
82 #define TLS_CONN_ALLOW_SIGN_RSA_MD5 BIT(0)
83 #define TLS_CONN_DISABLE_TIME_CHECKS BIT(1)
86 * struct tls_connection_params - Parameters for TLS connection
87 * @ca_cert: File or reference name for CA X.509 certificate in PEM or DER
89 * @ca_cert_blob: ca_cert as inlined data or %NULL if not used
90 * @ca_cert_blob_len: ca_cert_blob length
91 * @ca_path: Path to CA certificates (OpenSSL specific)
92 * @subject_match: String to match in the subject of the peer certificate or
93 * %NULL to allow all subjects
94 * @altsubject_match: String to match in the alternative subject of the peer
95 * certificate or %NULL to allow all alternative subjects
96 * @client_cert: File or reference name for client X.509 certificate in PEM or
98 * @client_cert_blob: client_cert as inlined data or %NULL if not used
99 * @client_cert_blob_len: client_cert_blob length
100 * @private_key: File or reference name for client private key in PEM or DER
101 * format (traditional format (RSA PRIVATE KEY) or PKCS#8 (PRIVATE KEY)
102 * @private_key_blob: private_key as inlined data or %NULL if not used
103 * @private_key_blob_len: private_key_blob length
104 * @private_key_passwd: Passphrase for decrypted private key, %NULL if no
105 * passphrase is used.
106 * @dh_file: File name for DH/DSA data in PEM format, or %NULL if not used
107 * @dh_blob: dh_file as inlined data or %NULL if not used
108 * @dh_blob_len: dh_blob length
109 * @engine: 1 = use engine (e.g., a smartcard) for private key operations
110 * (this is OpenSSL specific for now)
111 * @engine_id: engine id string (this is OpenSSL specific for now)
112 * @ppin: pointer to the pin variable in the configuration
113 * (this is OpenSSL specific for now)
114 * @key_id: the private key's id when using engine (this is OpenSSL
116 * @cert_id: the certificate's id when using engine
117 * @ca_cert_id: the CA certificate's id when using engine
118 * @flags: Parameter options (TLS_CONN_*)
120 * TLS connection parameters to be configured with tls_connection_set_params()
121 * and tls_global_set_params().
123 * Certificates and private key can be configured either as a reference name
124 * (file path or reference to certificate store) or by providing the same data
125 * as a pointer to the data in memory. Only one option will be used for each
128 struct tls_connection_params {
130 const u8 *ca_cert_blob;
131 size_t ca_cert_blob_len;
133 const char *subject_match;
134 const char *altsubject_match;
135 const char *client_cert;
136 const u8 *client_cert_blob;
137 size_t client_cert_blob_len;
138 const char *private_key;
139 const u8 *private_key_blob;
140 size_t private_key_blob_len;
141 const char *private_key_passwd;
146 /* OpenSSL specific variables */
148 const char *engine_id;
152 const char *ca_cert_id;
159 * tls_init - Initialize TLS library
160 * @conf: Configuration data for TLS library
161 * Returns: Context data to be used as tls_ctx in calls to other functions,
162 * or %NULL on failure.
164 * Called once during program startup and once for each RSN pre-authentication
165 * session. In other words, there can be two concurrent TLS contexts. If global
166 * library initialization is needed (i.e., one that is shared between both
167 * authentication types), the TLS library wrapper should maintain a reference
168 * counter and do global initialization only when moving from 0 to 1 reference.
170 void * tls_init(const struct tls_config *conf);
173 * tls_deinit - Deinitialize TLS library
174 * @tls_ctx: TLS context data from tls_init()
176 * Called once during program shutdown and once for each RSN pre-authentication
177 * session. If global library deinitialization is needed (i.e., one that is
178 * shared between both authentication types), the TLS library wrapper should
179 * maintain a reference counter and do global deinitialization only when moving
180 * from 1 to 0 references.
182 void tls_deinit(void *tls_ctx);
185 * tls_get_errors - Process pending errors
186 * @tls_ctx: TLS context data from tls_init()
187 * Returns: Number of found error, 0 if no errors detected.
189 * Process all pending TLS errors.
191 int tls_get_errors(void *tls_ctx);
194 * tls_connection_init - Initialize a new TLS connection
195 * @tls_ctx: TLS context data from tls_init()
196 * Returns: Connection context data, conn for other function calls
198 struct tls_connection * tls_connection_init(void *tls_ctx);
201 * tls_connection_deinit - Free TLS connection data
202 * @tls_ctx: TLS context data from tls_init()
203 * @conn: Connection context data from tls_connection_init()
205 * Release all resources allocated for TLS connection.
207 void tls_connection_deinit(void *tls_ctx, struct tls_connection *conn);
210 * tls_connection_established - Has the TLS connection been completed?
211 * @tls_ctx: TLS context data from tls_init()
212 * @conn: Connection context data from tls_connection_init()
213 * Returns: 1 if TLS connection has been completed, 0 if not.
215 int tls_connection_established(void *tls_ctx, struct tls_connection *conn);
218 * tls_connection_shutdown - Shutdown TLS connection
219 * @tls_ctx: TLS context data from tls_init()
220 * @conn: Connection context data from tls_connection_init()
221 * Returns: 0 on success, -1 on failure
223 * Shutdown current TLS connection without releasing all resources. New
224 * connection can be started by using the same conn without having to call
225 * tls_connection_init() or setting certificates etc. again. The new
226 * connection should try to use session resumption.
228 int tls_connection_shutdown(void *tls_ctx, struct tls_connection *conn);
231 TLS_SET_PARAMS_ENGINE_PRV_VERIFY_FAILED = -3,
232 TLS_SET_PARAMS_ENGINE_PRV_INIT_FAILED = -2
236 * tls_connection_set_params - Set TLS connection parameters
237 * @tls_ctx: TLS context data from tls_init()
238 * @conn: Connection context data from tls_connection_init()
239 * @params: Connection parameters
240 * Returns: 0 on success, -1 on failure,
241 * TLS_SET_PARAMS_ENGINE_PRV_INIT_FAILED (-2) on possible PIN error causing
242 * PKCS#11 engine failure, or
243 * TLS_SET_PARAMS_ENGINE_PRV_VERIFY_FAILED (-3) on failure to verify the
244 * PKCS#11 engine private key.
247 tls_connection_set_params(void *tls_ctx, struct tls_connection *conn,
248 const struct tls_connection_params *params);
251 * tls_global_set_params - Set TLS parameters for all TLS connection
252 * @tls_ctx: TLS context data from tls_init()
253 * @params: Global TLS parameters
254 * Returns: 0 on success, -1 on failure,
255 * TLS_SET_PARAMS_ENGINE_PRV_INIT_FAILED (-2) on possible PIN error causing
256 * PKCS#11 engine failure, or
257 * TLS_SET_PARAMS_ENGINE_PRV_VERIFY_FAILED (-3) on failure to verify the
258 * PKCS#11 engine private key.
260 int __must_check tls_global_set_params(
261 void *tls_ctx, const struct tls_connection_params *params);
264 * tls_global_set_verify - Set global certificate verification options
265 * @tls_ctx: TLS context data from tls_init()
266 * @check_crl: 0 = do not verify CRLs, 1 = verify CRL for the user certificate,
267 * 2 = verify CRL for all certificates
268 * Returns: 0 on success, -1 on failure
270 int __must_check tls_global_set_verify(void *tls_ctx, int check_crl);
273 * tls_connection_set_verify - Set certificate verification options
274 * @tls_ctx: TLS context data from tls_init()
275 * @conn: Connection context data from tls_connection_init()
276 * @verify_peer: 1 = verify peer certificate
277 * Returns: 0 on success, -1 on failure
279 int __must_check tls_connection_set_verify(void *tls_ctx,
280 struct tls_connection *conn,
284 * tls_connection_get_keys - Get master key and random data from TLS connection
285 * @tls_ctx: TLS context data from tls_init()
286 * @conn: Connection context data from tls_connection_init()
287 * @keys: Structure of key/random data (filled on success)
288 * Returns: 0 on success, -1 on failure
290 int __must_check tls_connection_get_keys(void *tls_ctx,
291 struct tls_connection *conn,
292 struct tls_keys *keys);
295 * tls_connection_prf - Use TLS-PRF to derive keying material
296 * @tls_ctx: TLS context data from tls_init()
297 * @conn: Connection context data from tls_connection_init()
298 * @label: Label (e.g., description of the key) for PRF
299 * @server_random_first: seed is 0 = client_random|server_random,
300 * 1 = server_random|client_random
301 * @out: Buffer for output data from TLS-PRF
302 * @out_len: Length of the output buffer
303 * Returns: 0 on success, -1 on failure
305 * This function is optional to implement if tls_connection_get_keys() provides
306 * access to master secret and server/client random values. If these values are
307 * not exported from the TLS library, tls_connection_prf() is required so that
308 * further keying material can be derived from the master secret. If not
309 * implemented, the function will still need to be defined, but it can just
310 * return -1. Example implementation of this function is in tls_prf_sha1_md5()
311 * when it is called with seed set to client_random|server_random (or
312 * server_random|client_random).
314 int __must_check tls_connection_prf(void *tls_ctx,
315 struct tls_connection *conn,
317 int server_random_first,
318 u8 *out, size_t out_len);
321 * tls_connection_handshake - Process TLS handshake (client side)
322 * @tls_ctx: TLS context data from tls_init()
323 * @conn: Connection context data from tls_connection_init()
324 * @in_data: Input data from TLS server
325 * @appl_data: Pointer to application data pointer, or %NULL if dropped
326 * Returns: Output data, %NULL on failure
328 * The caller is responsible for freeing the returned output data. If the final
329 * handshake message includes application data, this is decrypted and
330 * appl_data (if not %NULL) is set to point this data. The caller is
331 * responsible for freeing appl_data.
333 * This function is used during TLS handshake. The first call is done with
334 * in_data == %NULL and the library is expected to return ClientHello packet.
335 * This packet is then send to the server and a response from server is given
336 * to TLS library by calling this function again with in_data pointing to the
337 * TLS message from the server.
339 * If the TLS handshake fails, this function may return %NULL. However, if the
340 * TLS library has a TLS alert to send out, that should be returned as the
341 * output data. In this case, tls_connection_get_failed() must return failure
344 * tls_connection_established() should return 1 once the TLS handshake has been
345 * completed successfully.
347 struct wpabuf * tls_connection_handshake(void *tls_ctx,
348 struct tls_connection *conn,
349 const struct wpabuf *in_data,
350 struct wpabuf **appl_data);
352 struct wpabuf * tls_connection_handshake2(void *tls_ctx,
353 struct tls_connection *conn,
354 const struct wpabuf *in_data,
355 struct wpabuf **appl_data,
356 int *more_data_needed);
359 * tls_connection_server_handshake - Process TLS handshake (server side)
360 * @tls_ctx: TLS context data from tls_init()
361 * @conn: Connection context data from tls_connection_init()
362 * @in_data: Input data from TLS peer
363 * @appl_data: Pointer to application data pointer, or %NULL if dropped
364 * Returns: Output data, %NULL on failure
366 * The caller is responsible for freeing the returned output data.
368 struct wpabuf * tls_connection_server_handshake(void *tls_ctx,
369 struct tls_connection *conn,
370 const struct wpabuf *in_data,
371 struct wpabuf **appl_data);
374 * tls_connection_encrypt - Encrypt data into TLS tunnel
375 * @tls_ctx: TLS context data from tls_init()
376 * @conn: Connection context data from tls_connection_init()
377 * @in_data: Plaintext data to be encrypted
378 * Returns: Encrypted TLS data or %NULL on failure
380 * This function is used after TLS handshake has been completed successfully to
381 * send data in the encrypted tunnel. The caller is responsible for freeing the
382 * returned output data.
384 struct wpabuf * tls_connection_encrypt(void *tls_ctx,
385 struct tls_connection *conn,
386 const struct wpabuf *in_data);
389 * tls_connection_decrypt - Decrypt data from TLS tunnel
390 * @tls_ctx: TLS context data from tls_init()
391 * @conn: Connection context data from tls_connection_init()
392 * @in_data: Encrypted TLS data
393 * Returns: Decrypted TLS data or %NULL on failure
395 * This function is used after TLS handshake has been completed successfully to
396 * receive data from the encrypted tunnel. The caller is responsible for
397 * freeing the returned output data.
399 struct wpabuf * tls_connection_decrypt(void *tls_ctx,
400 struct tls_connection *conn,
401 const struct wpabuf *in_data);
403 struct wpabuf * tls_connection_decrypt2(void *tls_ctx,
404 struct tls_connection *conn,
405 const struct wpabuf *in_data,
406 int *more_data_needed);
409 * tls_connection_resumed - Was session resumption used
410 * @tls_ctx: TLS context data from tls_init()
411 * @conn: Connection context data from tls_connection_init()
412 * Returns: 1 if current session used session resumption, 0 if not
414 int tls_connection_resumed(void *tls_ctx, struct tls_connection *conn);
418 TLS_CIPHER_RC4_SHA /* 0x0005 */,
419 TLS_CIPHER_AES128_SHA /* 0x002f */,
420 TLS_CIPHER_RSA_DHE_AES128_SHA /* 0x0031 */,
421 TLS_CIPHER_ANON_DH_AES128_SHA /* 0x0034 */
425 * tls_connection_set_cipher_list - Configure acceptable cipher suites
426 * @tls_ctx: TLS context data from tls_init()
427 * @conn: Connection context data from tls_connection_init()
428 * @ciphers: Zero (TLS_CIPHER_NONE) terminated list of allowed ciphers
430 * Returns: 0 on success, -1 on failure
432 int __must_check tls_connection_set_cipher_list(void *tls_ctx,
433 struct tls_connection *conn,
437 * tls_get_cipher - Get current cipher name
438 * @tls_ctx: TLS context data from tls_init()
439 * @conn: Connection context data from tls_connection_init()
440 * @buf: Buffer for the cipher name
442 * Returns: 0 on success, -1 on failure
444 * Get the name of the currently used cipher.
446 int __must_check tls_get_cipher(void *tls_ctx, struct tls_connection *conn,
447 char *buf, size_t buflen);
450 * tls_connection_enable_workaround - Enable TLS workaround options
451 * @tls_ctx: TLS context data from tls_init()
452 * @conn: Connection context data from tls_connection_init()
453 * Returns: 0 on success, -1 on failure
455 * This function is used to enable connection-specific workaround options for
456 * buffer SSL/TLS implementations.
458 int __must_check tls_connection_enable_workaround(void *tls_ctx,
459 struct tls_connection *conn);
462 * tls_connection_client_hello_ext - Set TLS extension for ClientHello
463 * @tls_ctx: TLS context data from tls_init()
464 * @conn: Connection context data from tls_connection_init()
465 * @ext_type: Extension type
466 * @data: Extension payload (%NULL to remove extension)
467 * @data_len: Extension payload length
468 * Returns: 0 on success, -1 on failure
470 int __must_check tls_connection_client_hello_ext(void *tls_ctx,
471 struct tls_connection *conn,
472 int ext_type, const u8 *data,
476 * tls_connection_get_failed - Get connection failure status
477 * @tls_ctx: TLS context data from tls_init()
478 * @conn: Connection context data from tls_connection_init()
480 * Returns >0 if connection has failed, 0 if not.
482 int tls_connection_get_failed(void *tls_ctx, struct tls_connection *conn);
485 * tls_connection_get_read_alerts - Get connection read alert status
486 * @tls_ctx: TLS context data from tls_init()
487 * @conn: Connection context data from tls_connection_init()
488 * Returns: Number of times a fatal read (remote end reported error) has
489 * happened during this connection.
491 int tls_connection_get_read_alerts(void *tls_ctx, struct tls_connection *conn);
494 * tls_connection_get_write_alerts - Get connection write alert status
495 * @tls_ctx: TLS context data from tls_init()
496 * @conn: Connection context data from tls_connection_init()
497 * Returns: Number of times a fatal write (locally detected error) has happened
498 * during this connection.
500 int tls_connection_get_write_alerts(void *tls_ctx,
501 struct tls_connection *conn);
504 * tls_connection_get_keyblock_size - Get TLS key_block size
505 * @tls_ctx: TLS context data from tls_init()
506 * @conn: Connection context data from tls_connection_init()
507 * Returns: Size of the key_block for the negotiated cipher suite or -1 on
510 int tls_connection_get_keyblock_size(void *tls_ctx,
511 struct tls_connection *conn);
514 * tls_capabilities - Get supported TLS capabilities
515 * @tls_ctx: TLS context data from tls_init()
516 * Returns: Bit field of supported TLS capabilities (TLS_CAPABILITY_*)
518 unsigned int tls_capabilities(void *tls_ctx);
520 typedef int (*tls_session_ticket_cb)
521 (void *ctx, const u8 *ticket, size_t len, const u8 *client_random,
522 const u8 *server_random, u8 *master_secret);
524 int __must_check tls_connection_set_session_ticket_cb(
525 void *tls_ctx, struct tls_connection *conn,
526 tls_session_ticket_cb cb, void *ctx);