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