Home | History | Annotate | Download | only in crypto
      1 /*
      2  * SSL/TLS interface definition
      3  * Copyright (c) 2004-2010, Jouni Malinen <j (at) 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