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  	TLS_UNSAFE_RENEGOTIATION_DISABLED,
27  };
28  
29  /*
30   * Note: These are used as identifier with external programs and as such, the
31   * values must not be changed.
32   */
33  enum tls_fail_reason {
34  	TLS_FAIL_UNSPECIFIED = 0,
35  	TLS_FAIL_UNTRUSTED = 1,
36  	TLS_FAIL_REVOKED = 2,
37  	TLS_FAIL_NOT_YET_VALID = 3,
38  	TLS_FAIL_EXPIRED = 4,
39  	TLS_FAIL_SUBJECT_MISMATCH = 5,
40  	TLS_FAIL_ALTSUBJECT_MISMATCH = 6,
41  	TLS_FAIL_BAD_CERTIFICATE = 7,
42  	TLS_FAIL_SERVER_CHAIN_PROBE = 8,
43  	TLS_FAIL_DOMAIN_SUFFIX_MISMATCH = 9,
44  	TLS_FAIL_DOMAIN_MISMATCH = 10,
45  	TLS_FAIL_INSUFFICIENT_KEY_LEN = 11,
46  	TLS_FAIL_DN_MISMATCH = 12,
47  };
48  
49  
50  #define TLS_MAX_ALT_SUBJECT 10
51  
52  struct tls_cert_data {
53  	int depth;
54  	const char *subject;
55  	const struct wpabuf *cert;
56  	const u8 *hash;
57  	size_t hash_len;
58  	const char *altsubject[TLS_MAX_ALT_SUBJECT];
59  	int num_altsubject;
60  	const char *serial_num;
61  	int tod;
62  };
63  
64  union tls_event_data {
65  	struct {
66  		int depth;
67  		const char *subject;
68  		enum tls_fail_reason reason;
69  		const char *reason_txt;
70  		const struct wpabuf *cert;
71  	} cert_fail;
72  
73  	struct tls_cert_data peer_cert;
74  
75  	struct {
76  		int is_local;
77  		const char *type;
78  		const char *description;
79  	} alert;
80  };
81  
82  struct tls_config {
83  #ifndef CONFIG_OPENSC_ENGINE_PATH
84  	const char *opensc_engine_path;
85  #endif /* CONFIG_OPENSC_ENGINE_PATH */
86  #ifndef CONFIG_PKCS11_ENGINE_PATH
87  	const char *pkcs11_engine_path;
88  #endif /* CONFIG_PKCS11_ENGINE_PATH */
89  #ifndef CONFIG_PKCS11_MODULE_PATH
90  	const char *pkcs11_module_path;
91  #endif /* CONFIG_PKCS11_MODULE_PATH */
92  	int fips_mode;
93  	int cert_in_cb;
94  	const char *openssl_ciphers;
95  	unsigned int tls_session_lifetime;
96  	unsigned int crl_reload_interval;
97  	unsigned int tls_flags;
98  
99  	void (*event_cb)(void *ctx, enum tls_event ev,
100  			 union tls_event_data *data);
101  	void *cb_ctx;
102  };
103  
104  #define TLS_CONN_ALLOW_SIGN_RSA_MD5 BIT(0)
105  #define TLS_CONN_DISABLE_TIME_CHECKS BIT(1)
106  #define TLS_CONN_DISABLE_SESSION_TICKET BIT(2)
107  #define TLS_CONN_REQUEST_OCSP BIT(3)
108  #define TLS_CONN_REQUIRE_OCSP BIT(4)
109  #define TLS_CONN_DISABLE_TLSv1_1 BIT(5)
110  #define TLS_CONN_DISABLE_TLSv1_2 BIT(6)
111  #define TLS_CONN_EAP_FAST BIT(7)
112  #define TLS_CONN_DISABLE_TLSv1_0 BIT(8)
113  #define TLS_CONN_EXT_CERT_CHECK BIT(9)
114  #define TLS_CONN_REQUIRE_OCSP_ALL BIT(10)
115  #define TLS_CONN_SUITEB BIT(11)
116  #define TLS_CONN_SUITEB_NO_ECDH BIT(12)
117  #define TLS_CONN_DISABLE_TLSv1_3 BIT(13)
118  #define TLS_CONN_ENABLE_TLSv1_0 BIT(14)
119  #define TLS_CONN_ENABLE_TLSv1_1 BIT(15)
120  #define TLS_CONN_ENABLE_TLSv1_2 BIT(16)
121  #define TLS_CONN_TEAP_ANON_DH BIT(17)
122  #define TLS_CONN_ALLOW_UNSAFE_RENEGOTIATION BIT(18)
123  
124  /**
125   * struct tls_connection_params - Parameters for TLS connection
126   * @ca_cert: File or reference name for CA X.509 certificate in PEM or DER
127   * format
128   * @ca_cert_blob: ca_cert as inlined data or %NULL if not used
129   * @ca_cert_blob_len: ca_cert_blob length
130   * @ca_path: Path to CA certificates (OpenSSL specific)
131   * @subject_match: String to match in the subject of the peer certificate or
132   * %NULL to allow all subjects
133   * @altsubject_match: String to match in the alternative subject of the peer
134   * certificate or %NULL to allow all alternative subjects
135   * @suffix_match: Semicolon deliminated string of values to suffix match against
136   * the dNSName or CN of the peer certificate or %NULL to allow all domain names.
137   * This may allow subdomains and wildcard certificates. Each domain name label
138   * must have a full case-insensitive match.
139   * @domain_match: String to match in the dNSName or CN of the peer
140   * certificate or %NULL to allow all domain names. This requires a full,
141   * case-insensitive match.
142   *
143   * More than one match string can be provided by using semicolons to
144   * separate the strings (e.g., example.org;example.com). When multiple
145   * strings are specified, a match with any one of the values is
146   * considered a sufficient match for the certificate, i.e., the
147   * conditions are ORed together.
148   * @client_cert: File or reference name for client X.509 certificate in PEM or
149   * DER format
150   * @client_cert_blob: client_cert as inlined data or %NULL if not used
151   * @client_cert_blob_len: client_cert_blob length
152   * @private_key: File or reference name for client private key in PEM or DER
153   * format (traditional format (RSA PRIVATE KEY) or PKCS#8 (PRIVATE KEY)
154   * @private_key_blob: private_key as inlined data or %NULL if not used
155   * @private_key_blob_len: private_key_blob length
156   * @private_key_passwd: Passphrase for decrypted private key, %NULL if no
157   * passphrase is used.
158   * @dh_file: File name for DH/DSA data in PEM format, or %NULL if not used
159   * @engine: 1 = use engine (e.g., a smartcard) for private key operations
160   * (this is OpenSSL specific for now)
161   * @engine_id: engine id string (this is OpenSSL specific for now)
162   * @ppin: pointer to the pin variable in the configuration
163   * (this is OpenSSL specific for now)
164   * @key_id: the private key's id when using engine (this is OpenSSL
165   * specific for now)
166   * @cert_id: the certificate's id when using engine
167   * @ca_cert_id: the CA certificate's id when using engine
168   * @openssl_ciphers: OpenSSL cipher configuration
169   * @openssl_ecdh_curves: OpenSSL ECDH curve configuration. %NULL for auto if
170   *	supported, empty string to disable, or a colon-separated curve list.
171   * @flags: Parameter options (TLS_CONN_*)
172   * @ocsp_stapling_response: DER encoded file with cached OCSP stapling response
173   *	or %NULL if OCSP is not enabled
174   * @ocsp_stapling_response_multi: DER encoded file with cached OCSP stapling
175   *	response list (OCSPResponseList for ocsp_multi in RFC 6961) or %NULL if
176   *	ocsp_multi is not enabled
177   * @check_cert_subject: Client certificate subject name matching string
178   *
179   * TLS connection parameters to be configured with tls_connection_set_params()
180   * and tls_global_set_params().
181   *
182   * Certificates and private key can be configured either as a reference name
183   * (file path or reference to certificate store) or by providing the same data
184   * as a pointer to the data in memory. Only one option will be used for each
185   * field.
186   */
187  struct tls_connection_params {
188  	const char *ca_cert;
189  	const u8 *ca_cert_blob;
190  	size_t ca_cert_blob_len;
191  	const char *ca_path;
192  	const char *subject_match;
193  	const char *altsubject_match;
194  	const char *suffix_match;
195  	const char *domain_match;
196  	const char *client_cert;
197  	const char *client_cert2;
198  	const u8 *client_cert_blob;
199  	size_t client_cert_blob_len;
200  	const char *private_key;
201  	const char *private_key2;
202  	const u8 *private_key_blob;
203  	size_t private_key_blob_len;
204  	const char *private_key_passwd;
205  	const char *private_key_passwd2;
206  	const char *dh_file;
207  
208  	/* OpenSSL specific variables */
209  	int engine;
210  	const char *engine_id;
211  	const char *pin;
212  	const char *key_id;
213  	const char *cert_id;
214  	const char *ca_cert_id;
215  	const char *openssl_ciphers;
216  	const char *openssl_ecdh_curves;
217  
218  	unsigned int flags;
219  	const char *ocsp_stapling_response;
220  	const char *ocsp_stapling_response_multi;
221  	const char *check_cert_subject;
222  };
223  
224  
225  /**
226   * tls_init - Initialize TLS library
227   * @conf: Configuration data for TLS library
228   * Returns: Context data to be used as tls_ctx in calls to other functions,
229   * or %NULL on failure.
230   *
231   * Called once during program startup and once for each RSN pre-authentication
232   * session. In other words, there can be two concurrent TLS contexts. If global
233   * library initialization is needed (i.e., one that is shared between both
234   * authentication types), the TLS library wrapper should maintain a reference
235   * counter and do global initialization only when moving from 0 to 1 reference.
236   */
237  void * tls_init(const struct tls_config *conf);
238  
239  /**
240   * tls_deinit - Deinitialize TLS library
241   * @tls_ctx: TLS context data from tls_init()
242   *
243   * Called once during program shutdown and once for each RSN pre-authentication
244   * session. If global library deinitialization is needed (i.e., one that is
245   * shared between both authentication types), the TLS library wrapper should
246   * maintain a reference counter and do global deinitialization only when moving
247   * from 1 to 0 references.
248   */
249  void tls_deinit(void *tls_ctx);
250  
251  /**
252   * tls_get_errors - Process pending errors
253   * @tls_ctx: TLS context data from tls_init()
254   * Returns: Number of found error, 0 if no errors detected.
255   *
256   * Process all pending TLS errors.
257   */
258  int tls_get_errors(void *tls_ctx);
259  
260  /**
261   * tls_connection_init - Initialize a new TLS connection
262   * @tls_ctx: TLS context data from tls_init()
263   * Returns: Connection context data, conn for other function calls
264   */
265  struct tls_connection * tls_connection_init(void *tls_ctx);
266  
267  /**
268   * tls_connection_deinit - Free TLS connection data
269   * @tls_ctx: TLS context data from tls_init()
270   * @conn: Connection context data from tls_connection_init()
271   *
272   * Release all resources allocated for TLS connection.
273   */
274  void tls_connection_deinit(void *tls_ctx, struct tls_connection *conn);
275  
276  /**
277   * tls_connection_established - Has the TLS connection been completed?
278   * @tls_ctx: TLS context data from tls_init()
279   * @conn: Connection context data from tls_connection_init()
280   * Returns: 1 if TLS connection has been completed, 0 if not.
281   */
282  int tls_connection_established(void *tls_ctx, struct tls_connection *conn);
283  
284  /**
285   * tls_connection_peer_serial_num - Fetch peer certificate serial number
286   * @tls_ctx: TLS context data from tls_init()
287   * @conn: Connection context data from tls_connection_init()
288   * Returns: Allocated string buffer containing the peer certificate serial
289   * number or %NULL on error.
290   *
291   * The caller is responsible for freeing the returned buffer with os_free().
292   */
293  char * tls_connection_peer_serial_num(void *tls_ctx,
294  				      struct tls_connection *conn);
295  
296  /**
297   * tls_connection_shutdown - Shutdown TLS connection
298   * @tls_ctx: TLS context data from tls_init()
299   * @conn: Connection context data from tls_connection_init()
300   * Returns: 0 on success, -1 on failure
301   *
302   * Shutdown current TLS connection without releasing all resources. New
303   * connection can be started by using the same conn without having to call
304   * tls_connection_init() or setting certificates etc. again. The new
305   * connection should try to use session resumption.
306   */
307  int tls_connection_shutdown(void *tls_ctx, struct tls_connection *conn);
308  
309  enum {
310  	TLS_SET_PARAMS_ENGINE_PRV_BAD_PIN = -4,
311  	TLS_SET_PARAMS_ENGINE_PRV_VERIFY_FAILED = -3,
312  	TLS_SET_PARAMS_ENGINE_PRV_INIT_FAILED = -2
313  };
314  
315  /**
316   * tls_connection_set_params - Set TLS connection parameters
317   * @tls_ctx: TLS context data from tls_init()
318   * @conn: Connection context data from tls_connection_init()
319   * @params: Connection parameters
320   * Returns: 0 on success, -1 on failure,
321   * TLS_SET_PARAMS_ENGINE_PRV_INIT_FAILED (-2) on error causing PKCS#11 engine
322   * failure, or
323   * TLS_SET_PARAMS_ENGINE_PRV_VERIFY_FAILED (-3) on failure to verify the
324   * PKCS#11 engine private key, or
325   * TLS_SET_PARAMS_ENGINE_PRV_BAD_PIN (-4) on PIN error causing PKCS#11 engine
326   * failure.
327   */
328  int __must_check
329  tls_connection_set_params(void *tls_ctx, struct tls_connection *conn,
330  			  const struct tls_connection_params *params);
331  
332  /**
333   * tls_global_set_params - Set TLS parameters for all TLS connection
334   * @tls_ctx: TLS context data from tls_init()
335   * @params: Global TLS parameters
336   * Returns: 0 on success, -1 on failure,
337   * TLS_SET_PARAMS_ENGINE_PRV_INIT_FAILED (-2) on error causing PKCS#11 engine
338   * failure, or
339   * TLS_SET_PARAMS_ENGINE_PRV_VERIFY_FAILED (-3) on failure to verify the
340   * PKCS#11 engine private key, or
341   * TLS_SET_PARAMS_ENGINE_PRV_BAD_PIN (-4) on PIN error causing PKCS#11 engine
342   * failure.
343   */
344  int __must_check tls_global_set_params(
345  	void *tls_ctx, const struct tls_connection_params *params);
346  
347  /**
348   * tls_global_set_verify - Set global certificate verification options
349   * @tls_ctx: TLS context data from tls_init()
350   * @check_crl: 0 = do not verify CRLs, 1 = verify CRL for the user certificate,
351   * 2 = verify CRL for all certificates
352   * @strict: 0 = allow CRL time errors, 1 = do not allow CRL time errors
353   * Returns: 0 on success, -1 on failure
354   */
355  int __must_check tls_global_set_verify(void *tls_ctx, int check_crl,
356  				       int strict);
357  
358  /**
359   * tls_connection_set_verify - Set certificate verification options
360   * @tls_ctx: TLS context data from tls_init()
361   * @conn: Connection context data from tls_connection_init()
362   * @verify_peer: 0 = do not verify peer certificate, 1 = verify peer
363   *	certificate (require it to be provided), 2 = verify peer certificate if
364   *	provided
365   * @flags: Connection flags (TLS_CONN_*)
366   * @session_ctx: Session caching context or %NULL to use default
367   * @session_ctx_len: Length of @session_ctx in bytes.
368   * Returns: 0 on success, -1 on failure
369   */
370  int __must_check tls_connection_set_verify(void *tls_ctx,
371  					   struct tls_connection *conn,
372  					   int verify_peer,
373  					   unsigned int flags,
374  					   const u8 *session_ctx,
375  					   size_t session_ctx_len);
376  
377  /**
378   * tls_connection_get_random - Get random data from TLS connection
379   * @tls_ctx: TLS context data from tls_init()
380   * @conn: Connection context data from tls_connection_init()
381   * @data: Structure of client/server random data (filled on success)
382   * Returns: 0 on success, -1 on failure
383   */
384  int __must_check tls_connection_get_random(void *tls_ctx,
385  					 struct tls_connection *conn,
386  					 struct tls_random *data);
387  
388  /**
389   * tls_connection_export_key - Derive keying material from a TLS connection
390   * @tls_ctx: TLS context data from tls_init()
391   * @conn: Connection context data from tls_connection_init()
392   * @label: Label (e.g., description of the key) for PRF
393   * @context: Optional extra upper-layer context (max len 2^16)
394   * @context_len: The length of the context value
395   * @out: Buffer for output data from TLS-PRF
396   * @out_len: Length of the output buffer
397   * Returns: 0 on success, -1 on failure
398   *
399   * Exports keying material using the mechanism described in RFC 5705. If
400   * context is %NULL, context is not provided; otherwise, context is provided
401   * (including the case of empty context with context_len == 0).
402   */
403  int __must_check tls_connection_export_key(void *tls_ctx,
404  					   struct tls_connection *conn,
405  					   const char *label,
406  					   const u8 *context,
407  					   size_t context_len,
408  					   u8 *out, size_t out_len);
409  
410  /**
411   * tls_connection_get_eap_fast_key - Derive key material for EAP-FAST
412   * @tls_ctx: TLS context data from tls_init()
413   * @conn: Connection context data from tls_connection_init()
414   * @out: Buffer for output data from TLS-PRF
415   * @out_len: Length of the output buffer
416   * Returns: 0 on success, -1 on failure
417   *
418   * Exports key material after the normal TLS key block for use with
419   * EAP-FAST. Most callers will want tls_connection_export_key(), but EAP-FAST
420   * uses a different legacy mechanism.
421   */
422  int __must_check tls_connection_get_eap_fast_key(void *tls_ctx,
423  						 struct tls_connection *conn,
424  						 u8 *out, size_t out_len);
425  
426  /**
427   * tls_connection_handshake - Process TLS handshake (client side)
428   * @tls_ctx: TLS context data from tls_init()
429   * @conn: Connection context data from tls_connection_init()
430   * @in_data: Input data from TLS server
431   * @appl_data: Pointer to application data pointer, or %NULL if dropped
432   * Returns: Output data, %NULL on failure
433   *
434   * The caller is responsible for freeing the returned output data. If the final
435   * handshake message includes application data, this is decrypted and
436   * appl_data (if not %NULL) is set to point this data. The caller is
437   * responsible for freeing appl_data.
438   *
439   * This function is used during TLS handshake. The first call is done with
440   * in_data == %NULL and the library is expected to return ClientHello packet.
441   * This packet is then send to the server and a response from server is given
442   * to TLS library by calling this function again with in_data pointing to the
443   * TLS message from the server.
444   *
445   * If the TLS handshake fails, this function may return %NULL. However, if the
446   * TLS library has a TLS alert to send out, that should be returned as the
447   * output data. In this case, tls_connection_get_failed() must return failure
448   * (> 0).
449   *
450   * tls_connection_established() should return 1 once the TLS handshake has been
451   * completed successfully.
452   */
453  struct wpabuf * tls_connection_handshake(void *tls_ctx,
454  					 struct tls_connection *conn,
455  					 const struct wpabuf *in_data,
456  					 struct wpabuf **appl_data);
457  
458  struct wpabuf * tls_connection_handshake2(void *tls_ctx,
459  					  struct tls_connection *conn,
460  					  const struct wpabuf *in_data,
461  					  struct wpabuf **appl_data,
462  					  int *more_data_needed);
463  
464  /**
465   * tls_connection_server_handshake - Process TLS handshake (server side)
466   * @tls_ctx: TLS context data from tls_init()
467   * @conn: Connection context data from tls_connection_init()
468   * @in_data: Input data from TLS peer
469   * @appl_data: Pointer to application data pointer, or %NULL if dropped
470   * Returns: Output data, %NULL on failure
471   *
472   * The caller is responsible for freeing the returned output data.
473   */
474  struct wpabuf * tls_connection_server_handshake(void *tls_ctx,
475  						struct tls_connection *conn,
476  						const struct wpabuf *in_data,
477  						struct wpabuf **appl_data);
478  
479  /**
480   * tls_connection_encrypt - Encrypt data into TLS tunnel
481   * @tls_ctx: TLS context data from tls_init()
482   * @conn: Connection context data from tls_connection_init()
483   * @in_data: Plaintext data to be encrypted
484   * Returns: Encrypted TLS data or %NULL on failure
485   *
486   * This function is used after TLS handshake has been completed successfully to
487   * send data in the encrypted tunnel. The caller is responsible for freeing the
488   * returned output data.
489   */
490  struct wpabuf * tls_connection_encrypt(void *tls_ctx,
491  				       struct tls_connection *conn,
492  				       const struct wpabuf *in_data);
493  
494  /**
495   * tls_connection_decrypt - Decrypt data from TLS tunnel
496   * @tls_ctx: TLS context data from tls_init()
497   * @conn: Connection context data from tls_connection_init()
498   * @in_data: Encrypted TLS data
499   * Returns: Decrypted TLS data or %NULL on failure
500   *
501   * This function is used after TLS handshake has been completed successfully to
502   * receive data from the encrypted tunnel. The caller is responsible for
503   * freeing the returned output data.
504   */
505  struct wpabuf * tls_connection_decrypt(void *tls_ctx,
506  				       struct tls_connection *conn,
507  				       const struct wpabuf *in_data);
508  
509  struct wpabuf * tls_connection_decrypt2(void *tls_ctx,
510  					struct tls_connection *conn,
511  					const struct wpabuf *in_data,
512  					int *more_data_needed);
513  
514  /**
515   * tls_connection_resumed - Was session resumption used
516   * @tls_ctx: TLS context data from tls_init()
517   * @conn: Connection context data from tls_connection_init()
518   * Returns: 1 if current session used session resumption, 0 if not
519   */
520  int tls_connection_resumed(void *tls_ctx, struct tls_connection *conn);
521  
522  enum {
523  	TLS_CIPHER_NONE,
524  	TLS_CIPHER_RC4_SHA /* 0x0005 */,
525  	TLS_CIPHER_AES128_SHA /* 0x002f */,
526  	TLS_CIPHER_RSA_DHE_AES128_SHA /* 0x0031 */,
527  	TLS_CIPHER_ANON_DH_AES128_SHA /* 0x0034 */,
528  	TLS_CIPHER_RSA_DHE_AES256_SHA /* 0x0039 */,
529  	TLS_CIPHER_AES256_SHA /* 0x0035 */,
530  };
531  
532  /**
533   * tls_connection_set_cipher_list - Configure acceptable cipher suites
534   * @tls_ctx: TLS context data from tls_init()
535   * @conn: Connection context data from tls_connection_init()
536   * @ciphers: Zero (TLS_CIPHER_NONE) terminated list of allowed ciphers
537   * (TLS_CIPHER_*).
538   * Returns: 0 on success, -1 on failure
539   */
540  int __must_check tls_connection_set_cipher_list(void *tls_ctx,
541  						struct tls_connection *conn,
542  						u8 *ciphers);
543  
544  /**
545   * tls_get_version - Get the current TLS version number
546   * @tls_ctx: TLS context data from tls_init()
547   * @conn: Connection context data from tls_connection_init()
548   * @buf: Buffer for returning the TLS version number
549   * @buflen: buf size
550   * Returns: 0 on success, -1 on failure
551   *
552   * Get the currently used TLS version number.
553   */
554  int __must_check tls_get_version(void *tls_ctx, struct tls_connection *conn,
555  				 char *buf, size_t buflen);
556  
557  /**
558   * tls_get_cipher - Get current cipher name
559   * @tls_ctx: TLS context data from tls_init()
560   * @conn: Connection context data from tls_connection_init()
561   * @buf: Buffer for the cipher name
562   * @buflen: buf size
563   * Returns: 0 on success, -1 on failure
564   *
565   * Get the name of the currently used cipher.
566   */
567  int __must_check tls_get_cipher(void *tls_ctx, struct tls_connection *conn,
568  				char *buf, size_t buflen);
569  
570  /**
571   * tls_connection_enable_workaround - Enable TLS workaround options
572   * @tls_ctx: TLS context data from tls_init()
573   * @conn: Connection context data from tls_connection_init()
574   * Returns: 0 on success, -1 on failure
575   *
576   * This function is used to enable connection-specific workaround options for
577   * buffer SSL/TLS implementations.
578   */
579  int __must_check tls_connection_enable_workaround(void *tls_ctx,
580  						  struct tls_connection *conn);
581  
582  /**
583   * tls_connection_client_hello_ext - Set TLS extension for ClientHello
584   * @tls_ctx: TLS context data from tls_init()
585   * @conn: Connection context data from tls_connection_init()
586   * @ext_type: Extension type
587   * @data: Extension payload (%NULL to remove extension)
588   * @data_len: Extension payload length
589   * Returns: 0 on success, -1 on failure
590   */
591  int __must_check tls_connection_client_hello_ext(void *tls_ctx,
592  						 struct tls_connection *conn,
593  						 int ext_type, const u8 *data,
594  						 size_t data_len);
595  
596  /**
597   * tls_connection_get_failed - Get connection failure status
598   * @tls_ctx: TLS context data from tls_init()
599   * @conn: Connection context data from tls_connection_init()
600   *
601   * Returns >0 if connection has failed, 0 if not.
602   */
603  int tls_connection_get_failed(void *tls_ctx, struct tls_connection *conn);
604  
605  /**
606   * tls_connection_get_read_alerts - Get connection read alert status
607   * @tls_ctx: TLS context data from tls_init()
608   * @conn: Connection context data from tls_connection_init()
609   * Returns: Number of times a fatal read (remote end reported error) has
610   * happened during this connection.
611   */
612  int tls_connection_get_read_alerts(void *tls_ctx, struct tls_connection *conn);
613  
614  /**
615   * tls_connection_get_write_alerts - Get connection write alert status
616   * @tls_ctx: TLS context data from tls_init()
617   * @conn: Connection context data from tls_connection_init()
618   * Returns: Number of times a fatal write (locally detected error) has happened
619   * during this connection.
620   */
621  int tls_connection_get_write_alerts(void *tls_ctx,
622  				    struct tls_connection *conn);
623  
624  typedef int (*tls_session_ticket_cb)
625  (void *ctx, const u8 *ticket, size_t len, const u8 *client_random,
626   const u8 *server_random, u8 *master_secret);
627  
628  int __must_check  tls_connection_set_session_ticket_cb(
629  	void *tls_ctx, struct tls_connection *conn,
630  	tls_session_ticket_cb cb, void *ctx);
631  
632  void tls_connection_set_log_cb(struct tls_connection *conn,
633  			       void (*log_cb)(void *ctx, const char *msg),
634  			       void *ctx);
635  
636  #define TLS_BREAK_VERIFY_DATA BIT(0)
637  #define TLS_BREAK_SRV_KEY_X_HASH BIT(1)
638  #define TLS_BREAK_SRV_KEY_X_SIGNATURE BIT(2)
639  #define TLS_DHE_PRIME_511B BIT(3)
640  #define TLS_DHE_PRIME_767B BIT(4)
641  #define TLS_DHE_PRIME_15 BIT(5)
642  #define TLS_DHE_PRIME_58B BIT(6)
643  #define TLS_DHE_NON_PRIME BIT(7)
644  
645  void tls_connection_set_test_flags(struct tls_connection *conn, u32 flags);
646  
647  int tls_get_library_version(char *buf, size_t buf_len);
648  
649  void tls_connection_set_success_data(struct tls_connection *conn,
650  				     struct wpabuf *data);
651  
652  void tls_connection_set_success_data_resumed(struct tls_connection *conn);
653  
654  const struct wpabuf *
655  tls_connection_get_success_data(struct tls_connection *conn);
656  
657  void tls_connection_remove_session(struct tls_connection *conn);
658  
659  /**
660   * tls_get_tls_unique - Fetch "tls-unique" for channel binding
661   * @conn: Connection context data from tls_connection_init()
662   * @buf: Buffer for returning the value
663   * @max_len: Maximum length of the buffer in bytes
664   * Returns: Number of bytes written to buf or -1 on error
665   *
666   * This function can be used to fetch "tls-unique" (RFC 5929, Section 3) which
667   * is the first TLS Finished message sent in the most recent TLS handshake of
668   * the TLS connection.
669   */
670  int tls_get_tls_unique(struct tls_connection *conn, u8 *buf, size_t max_len);
671  
672  /**
673   * tls_connection_get_cipher_suite - Get current TLS cipher suite
674   * @conn: Connection context data from tls_connection_init()
675   * Returns: TLS cipher suite of the current connection or 0 on error
676   */
677  u16 tls_connection_get_cipher_suite(struct tls_connection *conn);
678  
679  /**
680   * tls_connection_get_peer_subject - Get peer subject
681   * @conn: Connection context data from tls_connection_init()
682   * Returns: Peer subject or %NULL if not authenticated or not available
683   */
684  const char * tls_connection_get_peer_subject(struct tls_connection *conn);
685  
686  /**
687   * tls_connection_get_own_cert_used - Was own certificate used
688   * @conn: Connection context data from tls_connection_init()
689   * Returns: true if own certificate was used during authentication
690   */
691  bool tls_connection_get_own_cert_used(struct tls_connection *conn);
692  
693  #endif /* TLS_H */
694