Disconnect hostapd from building in base
[dragonfly.git] / contrib / hostapd / src / crypto / tls.h
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 */