contrib/wpa_supplicant/tls.h

   1 #ifndef TLS_H
   2 #define TLS_H
   3
   4 struct tls_connection;
   5
   6 struct tls_keys {
   7         const u8 *master_key;
   8         size_t master_key_len;
   9         const u8 *client_random;
  10         size_t client_random_len;
  11         const u8 *server_random;
  12         size_t server_random_len;
  13 };
  14
  15 /**
  16  * tls_init - initialize TLS library
  17  *
  18  * Returns: Context data to be used as @tls_ctx in calls to other functions,
  19  * or %NULL on failure.
  20  *
  21  * Called once during program startup.
  22  */
  23 void * tls_init(void);
  24
  25 /**
  26  * tls_deinit - deinitialize TLS library
  27  * @tls_ctx: TLS context data from tls_init()
  28  *
  29  * Called once during program shutdown.
  30  */
  31 void tls_deinit(void *tls_ctx);
  32
  33 /**
  34  * tls_get_errors - process pending errors
  35  * @tls_ctx: TLS context data from tls_init()
  36  *
  37  * Returns: Number of found error, 0 if no errors detected.
  38  *
  39  * Process all pending TLS errors.
  40  */
  41 int tls_get_errors(void *tls_ctx);
  42
  43 /**
  44  * tls_connection_init - initialize a new TLS connection
  45  * @tls_ctx: TLS context data from tls_init()
  46  *
  47  * Returns: Connection context data, @conn for other function calls
  48  */
  49 struct tls_connection * tls_connection_init(void *tls_ctx);
  50
  51 /**
  52  * tls_connection_deinit - free TLS connection data
  53  * @tls_ctx: TLS context data from tls_init()
  54  * @conn: Connection context data from tls_connection_init()
  55  *
  56  * Release all resources allocated for TLS connection.
  57  */
  58 void tls_connection_deinit(void *tls_ctx, struct tls_connection *conn);
  59
  60 /**
  61  * tls_connection_established - has the TLS connection been completed?
  62  * @tls_ctx: TLS context data from tls_init()
  63  * @conn: Connection context data from tls_connection_init()
  64  *
  65  * Returns: 1 if TLS connection has been completed, 0 if not.
  66  */
  67 int tls_connection_established(void *tls_ctx, struct tls_connection *conn);
  68
  69 /**
  70  * tls_connection_shutdown - shutdown TLS connection data.
  71  * @tls_ctx: TLS context data from tls_init()
  72  * @conn: Connection context data from tls_connection_init()
  73  *
  74  * Returns: 0 on success, -1 on failure
  75  *
  76  * Shutdown current TLS connection without releasing all resources. New
  77  * connection can be started by using the same @conn without having to call
  78  * tls_connection_init() or setting certificates etc. again. The new
  79  * connection should try to use session resumption.
  80  */
  81 int tls_connection_shutdown(void *tls_ctx, struct tls_connection *conn);
  82
  83 /**
  84  * tls_connection_ca_cert - set trusted CA certificate for TLS connection
  85  * @tls_ctx: TLS context data from tls_init()
  86  * @conn: Connection context data from tls_connection_init()
  87  * @ca_cert: File name for CA certificate in PEM or DER format
  88  * @subject_match: String to match in the subject of the peer certificate or
  89  * %NULL to allow all subjects
  90  *
  91  * Returns: 0 on success, -1 on failure
  92  */
  93 int tls_connection_ca_cert(void *tls_ctx, struct tls_connection *conn,
  94                            const char *ca_cert, const char *subject_match);
  95
  96 /**
  97  * tls_global_ca_cert - set trusted CA certificate for all TLS connections
  98  * @tls_ctx: TLS context data from tls_init()
  99  * @ca_cert: File name for CA certificate in PEM or DER format
 100  * %NULL to allow all subjects
 101  *
 102  * Returns: 0 on success, -1 on failure
 103  */
 104 int tls_global_ca_cert(void *tls_ctx, const char *ca_cert);
 105
 106 /**
 107  * tls_connection_ca_cert - set trusted CA certificate for TLS connection
 108  * @tls_ctx: TLS context data from tls_init()
 109  * @conn: Connection context data from tls_connection_init()
 110  * @verify_peer: 1 = verify peer certificate
 111  * @subject_match: String to match in the subject of the peer certificate or
 112  * %NULL to allow all subjects
 113  *
 114  * Returns: 0 on success, -1 on failure
 115  */
 116 int tls_connection_set_verify(void *tls_ctx, struct tls_connection *conn,
 117                               int verify_peer, const char *subject_match);
 118
 119 /**
 120  * tls_connection_client_cert - set client certificate for TLS connection
 121  * @tls_ctx: TLS context data from tls_init()
 122  * @conn: Connection context data from tls_connection_init()
 123  * @client_cert: File name for client certificate in PEM or DER format
 124  *
 125  * Returns: 0 on success, -1 on failure
 126  */
 127 int tls_connection_client_cert(void *tls_ctx, struct tls_connection *conn,
 128                                const char *client_cert);
 129
 130 /**
 131  * tls_global_client_cert - set client certificate for all TLS connections
 132  * @tls_ctx: TLS context data from tls_init()
 133  * @client_cert: File name for client certificate in PEM or DER format
 134  *
 135  * Returns: 0 on success, -1 on failure
 136  */
 137 int tls_global_client_cert(void *tls_ctx, const char *client_cert);
 138
 139 /**
 140  * tls_connection_private_key - set private key for TLS connection
 141  * @tls_ctx: TLS context data from tls_init()
 142  * @conn: Connection context data from tls_connection_init()
 143  * @private_key: File name for client private key in PEM or DER format
 144  * @private_key_passwd: Passphrase for decrypted private key, %NULL if no
 145  * passphrase is used.
 146  *
 147  * Returns: 0 on success, -1 on failure
 148  */
 149 int tls_connection_private_key(void *tls_ctx, struct tls_connection *conn,
 150                                const char *private_key,
 151                                const char *private_key_passwd);
 152
 153 /**
 154  * tls_global_private_key - set private key for all TLS connections
 155  * @tls_ctx: TLS context data from tls_init()
 156  * @private_key: File name for client private key in PEM or DER format
 157  * @private_key_passwd: Passphrase for decrypted private key, %NULL if no
 158  * passphrase is used.
 159  *
 160  * Returns: 0 on success, -1 on failure
 161  */
 162 int tls_global_private_key(void *tls_ctx, const char *private_key,
 163                            const char *private_key_passwd);
 164
 165 /**
 166  * tls_connection_dh - set DH/DSA parameters for TLS connection
 167  * @tls_ctx: TLS context data from tls_init()
 168  * @conn: Connection context data from tls_connection_init()
 169  * @dh_file: File name for DH/DSA data in PEM format.
 170  *
 171  * Returns: 0 on success, -1 on failure
 172  */
 173 int tls_connection_dh(void *tls_ctx, struct tls_connection *conn,
 174                       const char *dh_file);
 175
 176 /**
 177  * tls_connection_get_keys - get master key and random data from TLS connection
 178  * @tls_ctx: TLS context data from tls_init()
 179  * @conn: Connection context data from tls_connection_init()
 180  * @keys: Structure of key/random data (filled on success)
 181  *
 182  * Returns: 0 on success, -1 on failure
 183  */
 184 int tls_connection_get_keys(void *tls_ctx, struct tls_connection *conn,
 185                             struct tls_keys *keys);
 186
 187 /**
 188  * tls_connection_handshake - process TLS handshake (client side)
 189  * @tls_ctx: TLS context data from tls_init()
 190  * @conn: Connection context data from tls_connection_init()
 191  * @in_data: Input data from TLS peer
 192  * @in_len: Input data length
 193  * @out_len: Length of the output buffer.
 194  *
 195  * Returns: pointer to output data, %NULL on failure
 196  *
 197  * Caller is responsible for freeing returned output data.
 198  */
 199 u8 * tls_connection_handshake(void *tls_ctx, struct tls_connection *conn,
 200                               const u8 *in_data, size_t in_len,
 201                               size_t *out_len);
 202
 203 /**
 204  * tls_connection_servr_handshake - process TLS handshake (server side)
 205  * @tls_ctx: TLS context data from tls_init()
 206  * @conn: Connection context data from tls_connection_init()
 207  * @in_data: Input data from TLS peer
 208  * @in_len: Input data length
 209  * @out_len: Length of the output buffer.
 210  *
 211  * Returns: pointer to output data, %NULL on failure
 212  *
 213  * Caller is responsible for freeing returned output data.
 214  */
 215 u8 * tls_connection_server_handshake(void *tls_ctx,
 216                                      struct tls_connection *conn,
 217                                      const u8 *in_data, size_t in_len,
 218                                      size_t *out_len);
 219
 220 /**
 221  * tls_connection_encrypt - encrypt data into TLS tunnel
 222  * @tls_ctx: TLS context data from tls_init()
 223  * @conn: Connection context data from tls_connection_init()
 224  * @in_data: Pointer to plaintext data to be encrypted
 225  * @in_len: Input buffer length
 226  * @out_data: Pointer to output buffer (encrypted TLS data)
 227  * @out_len: Maximum @out_data length
 228  *
 229  * Returns: Number of bytes written to @out_data, -1 on failure
 230  */
 231 int tls_connection_encrypt(void *tls_ctx, struct tls_connection *conn,
 232                            u8 *in_data, size_t in_len,
 233                            u8 *out_data, size_t out_len);
 234
 235 /**
 236  * tls_connection_decrypt - decrypt data from TLS tunnel
 237  * @tls_ctx: TLS context data from tls_init()
 238  * @conn: Connection context data from tls_connection_init()
 239  * @in_data: Pointer to input buffer (encrypted TLS data)
 240  * @in_len: Input buffer length
 241  * @out_data: Pointer to output buffer (decrypted data from TLS tunnel)
 242  * @out_len: Maximum @out_data length
 243  *
 244  * Returns: Number of bytes written to @out_data, -1 on failure
 245  */
 246 int tls_connection_decrypt(void *tls_ctx, struct tls_connection *conn,
 247                            u8 *in_data, size_t in_len,
 248                            u8 *out_data, size_t out_len);
 249
 250 /**
 251  * tls_connection_resumed - was session resumption used
 252  * @tls_ctx: TLS context data from tls_init()
 253  * @conn: Connection context data from tls_connection_init()
 254  *
 255  * Returns: 1 if current session used session resumption, 0 if not
 256  */
 257 int tls_connection_resumed(void *tls_ctx, struct tls_connection *conn);
 258
 259 /**
 260  * tls_connection_set_master_key - configure master secret for TLS connection
 261  * @tls_ctx: TLS context data from tls_init()
 262  * @conn: Connection context data from tls_connection_init()
 263  * @key: TLS pre-master-secret
 264  * @key_len: length of @key in bytes
 265  *
 266  * Returns: 0 on success, -1 on failure
 267  */
 268 int tls_connection_set_master_key(void *ssl_ctx, struct tls_connection *conn,
 269                                   const u8 *key, size_t key_len);
 270
 271 /**
 272  * tls_connection_set_anon_dh - configure TLS connection to use anonymous DH
 273  * @tls_ctx: TLS context data from tls_init()
 274  * @conn: Connection context data from tls_connection_init()
 275  *
 276  * Returns: 0 on success, -1 on failure
 277  *
 278  * TODO: consider changing this to more generic routine for configuring allowed
 279  * ciphers
 280  */
 281 int tls_connection_set_anon_dh(void *ssl_ctx, struct tls_connection *conn);
 282
 283 /**
 284  * tls_get_cipher - get current cipher name
 285  * @tls_ctx: TLS context data from tls_init()
 286  * @conn: Connection context data from tls_connection_init()
 287  *
 288  * Returns: 0 on success, -1 on failure
 289  *
 290  * Get the name of the currently used cipher.
 291  */
 292 int tls_get_cipher(void *ssl_ctx, struct tls_connection *conn,
 293                    char *buf, size_t buflen);
 294
 295 /**
 296  * tls_connection_enable_workaround - enable TLS workaround options
 297  * @tls_ctx: TLS context data from tls_init()
 298  * @conn: Connection context data from tls_connection_init()
 299  *
 300  * Returns: 0 on success, -1 on failure
 301  *
 302  * This function is used to enable connection-specific workaround options for
 303  * buffer SSL/TLS implementations.
 304  */
 305 int tls_connection_enable_workaround(void *ssl_ctx,
 306                                      struct tls_connection *conn);
 307
 308 int tls_connection_client_hello_ext(void *ssl_ctx, struct tls_connection *conn,
 309                                     int ext_type, const u8 *data,
 310                                     size_t data_len);
 311
 312 #endif /* TLS_H */