ssl.h 110 KB
Newer Older
1 2
/**
 * \file ssl.h
3
 *
4 5
 * \brief SSL/TLS functions.
 *
6
 *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
7
 *  SPDX-License-Identifier: Apache-2.0
8
 *
9 10 11
 *  Licensed under the Apache License, Version 2.0 (the "License"); you may
 *  not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
12
 *
13
 *  http://www.apache.org/licenses/LICENSE-2.0
14
 *
15 16 17 18 19
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
20
 *
21
 *  This file is part of mbed TLS (https://tls.mbed.org)
22
 */
23 24
#ifndef MBEDTLS_SSL_H
#define MBEDTLS_SSL_H
25

26
#if !defined(MBEDTLS_CONFIG_FILE)
27
#include "config.h"
28
#else
29
#include MBEDTLS_CONFIG_FILE
30
#endif
31

32
#include "bignum.h"
33
#include "ecp.h"
34

35 36
#include "ssl_ciphersuites.h"

37
#if defined(MBEDTLS_X509_CRT_PARSE_C)
38 39
#include "x509_crt.h"
#include "x509_crl.h"
40
#endif
41

42
#if defined(MBEDTLS_DHM_C)
43 44 45
#include "dhm.h"
#endif

46
#if defined(MBEDTLS_ECDH_C)
47 48 49
#include "ecdh.h"
#endif

50
#if defined(MBEDTLS_ZLIB_SUPPORT)
51 52 53
#include "zlib.h"
#endif

54
#if defined(MBEDTLS_HAVE_TIME)
55
#include "mbedtls/platform_time.h"
56 57
#endif

58 59 60
/*
 * SSL Error codes
 */
61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89
#define MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE               -0x7080  /**< The requested feature is not available. */
#define MBEDTLS_ERR_SSL_BAD_INPUT_DATA                    -0x7100  /**< Bad input parameters to function. */
#define MBEDTLS_ERR_SSL_INVALID_MAC                       -0x7180  /**< Verification of the message MAC failed. */
#define MBEDTLS_ERR_SSL_INVALID_RECORD                    -0x7200  /**< An invalid SSL record was received. */
#define MBEDTLS_ERR_SSL_CONN_EOF                          -0x7280  /**< The connection indicated an EOF. */
#define MBEDTLS_ERR_SSL_UNKNOWN_CIPHER                    -0x7300  /**< An unknown cipher was received. */
#define MBEDTLS_ERR_SSL_NO_CIPHER_CHOSEN                  -0x7380  /**< The server has no ciphersuites in common with the client. */
#define MBEDTLS_ERR_SSL_NO_RNG                            -0x7400  /**< No RNG was provided to the SSL module. */
#define MBEDTLS_ERR_SSL_NO_CLIENT_CERTIFICATE             -0x7480  /**< No client certification received from the client, but required by the authentication mode. */
#define MBEDTLS_ERR_SSL_CERTIFICATE_TOO_LARGE             -0x7500  /**< Our own certificate(s) is/are too large to send in an SSL message. */
#define MBEDTLS_ERR_SSL_CERTIFICATE_REQUIRED              -0x7580  /**< The own certificate is not set, but needed by the server. */
#define MBEDTLS_ERR_SSL_PRIVATE_KEY_REQUIRED              -0x7600  /**< The own private key or pre-shared key is not set, but needed. */
#define MBEDTLS_ERR_SSL_CA_CHAIN_REQUIRED                 -0x7680  /**< No CA Chain is set, but required to operate. */
#define MBEDTLS_ERR_SSL_UNEXPECTED_MESSAGE                -0x7700  /**< An unexpected message was received from our peer. */
#define MBEDTLS_ERR_SSL_FATAL_ALERT_MESSAGE               -0x7780  /**< A fatal alert message was received from our peer. */
#define MBEDTLS_ERR_SSL_PEER_VERIFY_FAILED                -0x7800  /**< Verification of our peer failed. */
#define MBEDTLS_ERR_SSL_PEER_CLOSE_NOTIFY                 -0x7880  /**< The peer notified us that the connection is going to be closed. */
#define MBEDTLS_ERR_SSL_BAD_HS_CLIENT_HELLO               -0x7900  /**< Processing of the ClientHello handshake message failed. */
#define MBEDTLS_ERR_SSL_BAD_HS_SERVER_HELLO               -0x7980  /**< Processing of the ServerHello handshake message failed. */
#define MBEDTLS_ERR_SSL_BAD_HS_CERTIFICATE                -0x7A00  /**< Processing of the Certificate handshake message failed. */
#define MBEDTLS_ERR_SSL_BAD_HS_CERTIFICATE_REQUEST        -0x7A80  /**< Processing of the CertificateRequest handshake message failed. */
#define MBEDTLS_ERR_SSL_BAD_HS_SERVER_KEY_EXCHANGE        -0x7B00  /**< Processing of the ServerKeyExchange handshake message failed. */
#define MBEDTLS_ERR_SSL_BAD_HS_SERVER_HELLO_DONE          -0x7B80  /**< Processing of the ServerHelloDone handshake message failed. */
#define MBEDTLS_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE        -0x7C00  /**< Processing of the ClientKeyExchange handshake message failed. */
#define MBEDTLS_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE_RP     -0x7C80  /**< Processing of the ClientKeyExchange handshake message failed in DHM / ECDH Read Public. */
#define MBEDTLS_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE_CS     -0x7D00  /**< Processing of the ClientKeyExchange handshake message failed in DHM / ECDH Calculate Secret. */
#define MBEDTLS_ERR_SSL_BAD_HS_CERTIFICATE_VERIFY         -0x7D80  /**< Processing of the CertificateVerify handshake message failed. */
#define MBEDTLS_ERR_SSL_BAD_HS_CHANGE_CIPHER_SPEC         -0x7E00  /**< Processing of the ChangeCipherSpec handshake message failed. */
#define MBEDTLS_ERR_SSL_BAD_HS_FINISHED                   -0x7E80  /**< Processing of the Finished handshake message failed. */
90
#define MBEDTLS_ERR_SSL_ALLOC_FAILED                      -0x7F00  /**< Memory allocation failed */
91 92 93 94 95 96 97 98 99 100 101 102 103 104
#define MBEDTLS_ERR_SSL_HW_ACCEL_FAILED                   -0x7F80  /**< Hardware acceleration function returned with error */
#define MBEDTLS_ERR_SSL_HW_ACCEL_FALLTHROUGH              -0x6F80  /**< Hardware acceleration function skipped / left alone data */
#define MBEDTLS_ERR_SSL_COMPRESSION_FAILED                -0x6F00  /**< Processing of the compression / decompression failed */
#define MBEDTLS_ERR_SSL_BAD_HS_PROTOCOL_VERSION           -0x6E80  /**< Handshake protocol not within min/max boundaries */
#define MBEDTLS_ERR_SSL_BAD_HS_NEW_SESSION_TICKET         -0x6E00  /**< Processing of the NewSessionTicket handshake message failed. */
#define MBEDTLS_ERR_SSL_SESSION_TICKET_EXPIRED            -0x6D80  /**< Session ticket has expired. */
#define MBEDTLS_ERR_SSL_PK_TYPE_MISMATCH                  -0x6D00  /**< Public key type mismatch (eg, asked for RSA key exchange and presented EC key) */
#define MBEDTLS_ERR_SSL_UNKNOWN_IDENTITY                  -0x6C80  /**< Unknown identity received (eg, PSK identity) */
#define MBEDTLS_ERR_SSL_INTERNAL_ERROR                    -0x6C00  /**< Internal error (eg, unexpected failure in lower-level module) */
#define MBEDTLS_ERR_SSL_COUNTER_WRAPPING                  -0x6B80  /**< A counter would wrap (eg, too many messages exchanged). */
#define MBEDTLS_ERR_SSL_WAITING_SERVER_HELLO_RENEGO       -0x6B00  /**< Unexpected message at ServerHello in renegotiation. */
#define MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED             -0x6A80  /**< DTLS client must retry for hello verification */
#define MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL                  -0x6A00  /**< A buffer is too small to receive or write a message */
#define MBEDTLS_ERR_SSL_NO_USABLE_CIPHERSUITE             -0x6980  /**< None of the common ciphersuites is usable (eg, no suitable certificate, see debug messages). */
105 106 107
#define MBEDTLS_ERR_SSL_WANT_READ                         -0x6900  /**< Connection requires a read call. */
#define MBEDTLS_ERR_SSL_WANT_WRITE                        -0x6880  /**< Connection requires a write call. */
#define MBEDTLS_ERR_SSL_TIMEOUT                           -0x6800  /**< The operation timed out. */
108
#define MBEDTLS_ERR_SSL_CLIENT_RECONNECT                  -0x6780  /**< The client initiated a reconnect from the same port. */
109
#define MBEDTLS_ERR_SSL_UNEXPECTED_RECORD                 -0x6700  /**< Record header looks valid but is not expected. */
110 111 112 113

/*
 * Various constants
 */
114 115 116 117 118
#define MBEDTLS_SSL_MAJOR_VERSION_3             3
#define MBEDTLS_SSL_MINOR_VERSION_0             0   /*!< SSL v3.0 */
#define MBEDTLS_SSL_MINOR_VERSION_1             1   /*!< TLS v1.0 */
#define MBEDTLS_SSL_MINOR_VERSION_2             2   /*!< TLS v1.1 */
#define MBEDTLS_SSL_MINOR_VERSION_3             3   /*!< TLS v1.2 */
119

120 121
#define MBEDTLS_SSL_TRANSPORT_STREAM            0   /*!< TLS      */
#define MBEDTLS_SSL_TRANSPORT_DATAGRAM          1   /*!< DTLS     */
122

123
#define MBEDTLS_SSL_MAX_HOST_NAME_LEN           255 /*!< Maximum host name defined in RFC 1035 */
124

125
/* RFC 6066 section 4, see also mfl_code_to_length in ssl_tls.c
126
 * NONE must be zero so that memset()ing structure to zero works */
127 128 129 130 131 132
#define MBEDTLS_SSL_MAX_FRAG_LEN_NONE           0   /*!< don't use this extension   */
#define MBEDTLS_SSL_MAX_FRAG_LEN_512            1   /*!< MaxFragmentLength 2^9      */
#define MBEDTLS_SSL_MAX_FRAG_LEN_1024           2   /*!< MaxFragmentLength 2^10     */
#define MBEDTLS_SSL_MAX_FRAG_LEN_2048           3   /*!< MaxFragmentLength 2^11     */
#define MBEDTLS_SSL_MAX_FRAG_LEN_4096           4   /*!< MaxFragmentLength 2^12     */
#define MBEDTLS_SSL_MAX_FRAG_LEN_INVALID        5   /*!< first invalid value        */
133

134 135
#define MBEDTLS_SSL_IS_CLIENT                   0
#define MBEDTLS_SSL_IS_SERVER                   1
136

137 138
#define MBEDTLS_SSL_IS_NOT_FALLBACK             0
#define MBEDTLS_SSL_IS_FALLBACK                 1
139

140 141
#define MBEDTLS_SSL_EXTENDED_MS_DISABLED        0
#define MBEDTLS_SSL_EXTENDED_MS_ENABLED         1
142

143 144
#define MBEDTLS_SSL_ETM_DISABLED                0
#define MBEDTLS_SSL_ETM_ENABLED                 1
145

146 147
#define MBEDTLS_SSL_COMPRESS_NULL               0
#define MBEDTLS_SSL_COMPRESS_DEFLATE            1
148

149 150 151
#define MBEDTLS_SSL_VERIFY_NONE                 0
#define MBEDTLS_SSL_VERIFY_OPTIONAL             1
#define MBEDTLS_SSL_VERIFY_REQUIRED             2
152
#define MBEDTLS_SSL_VERIFY_UNSET                3 /* Used only for sni_authmode */
153

154 155
#define MBEDTLS_SSL_LEGACY_RENEGOTIATION        0
#define MBEDTLS_SSL_SECURE_RENEGOTIATION        1
156

157 158
#define MBEDTLS_SSL_RENEGOTIATION_DISABLED      0
#define MBEDTLS_SSL_RENEGOTIATION_ENABLED       1
159

160 161
#define MBEDTLS_SSL_ANTI_REPLAY_DISABLED        0
#define MBEDTLS_SSL_ANTI_REPLAY_ENABLED         1
162

163 164
#define MBEDTLS_SSL_RENEGOTIATION_NOT_ENFORCED  -1
#define MBEDTLS_SSL_RENEGO_MAX_RECORDS_DEFAULT  16
165

166 167 168
#define MBEDTLS_SSL_LEGACY_NO_RENEGOTIATION     0
#define MBEDTLS_SSL_LEGACY_ALLOW_RENEGOTIATION  1
#define MBEDTLS_SSL_LEGACY_BREAK_HANDSHAKE      2
169

170 171 172
#define MBEDTLS_SSL_TRUNC_HMAC_DISABLED         0
#define MBEDTLS_SSL_TRUNC_HMAC_ENABLED          1
#define MBEDTLS_SSL_TRUNCATED_HMAC_LEN          10  /* 80 bits, rfc 6066 section 7 */
173

174 175
#define MBEDTLS_SSL_SESSION_TICKETS_DISABLED     0
#define MBEDTLS_SSL_SESSION_TICKETS_ENABLED      1
176

177 178
#define MBEDTLS_SSL_CBC_RECORD_SPLITTING_DISABLED    0
#define MBEDTLS_SSL_CBC_RECORD_SPLITTING_ENABLED     1
179

180 181
#define MBEDTLS_SSL_ARC4_ENABLED                0
#define MBEDTLS_SSL_ARC4_DISABLED               1
182

183 184 185
#define MBEDTLS_SSL_PRESET_DEFAULT              0
#define MBEDTLS_SSL_PRESET_SUITEB               2

186 187 188 189
/*
 * Default range for DTLS retransmission timer value, in milliseconds.
 * RFC 6347 4.2.4.1 says from 1 second to 60 seconds.
 */
190 191
#define MBEDTLS_SSL_DTLS_TIMEOUT_DFL_MIN    1000
#define MBEDTLS_SSL_DTLS_TIMEOUT_DFL_MAX   60000
192

193 194 195 196 197 198 199 200
/**
 * \name SECTION: Module settings
 *
 * The configuration options you can set for this module are in this section.
 * Either change them in config.h or define them on the compiler command line.
 * \{
 */

201 202
#if !defined(MBEDTLS_SSL_DEFAULT_TICKET_LIFETIME)
#define MBEDTLS_SSL_DEFAULT_TICKET_LIFETIME     86400 /**< Lifetime of session tickets (if enabled) */
203
#endif
204

205
/*
206 207 208
 * Maxium fragment length in bytes,
 * determines the size of each of the two internal I/O buffers.
 *
209 210 211
 * Note: the RFC defines the default size of SSL / TLS messages. If you
 * change the value here, other clients / servers may not be able to
 * communicate with you anymore. Only change this value if you control
212 213 214
 * both sides of the connection and have it reduced at both sides, or
 * if you're using the Max Fragment Length extension and you know all your
 * peers are using it too!
215
 */
216 217
#if !defined(MBEDTLS_SSL_MAX_CONTENT_LEN)
#define MBEDTLS_SSL_MAX_CONTENT_LEN         16384   /**< Size of the input / output buffer */
218 219 220
#endif

/* \} name SECTION: Module settings */
221

222 223 224
/*
 * Length of the verify data for secure renegotiation
 */
225 226
#if defined(MBEDTLS_SSL_PROTO_SSL3)
#define MBEDTLS_SSL_VERIFY_DATA_MAX_LEN 36
227
#else
228
#define MBEDTLS_SSL_VERIFY_DATA_MAX_LEN 12
229 230
#endif

231 232 233
/*
 * Signaling ciphersuite values (SCSV)
 */
234
#define MBEDTLS_SSL_EMPTY_RENEGOTIATION_INFO    0xFF   /**< renegotiation info ext */
235
#define MBEDTLS_SSL_FALLBACK_SCSV_VALUE         0x5600 /**< RFC 7507 section 2 */
236

237 238
/*
 * Supported Signature and Hash algorithms (For TLS 1.2)
239
 * RFC 5246 section 7.4.1.4.1
240
 */
241 242 243 244 245 246 247
#define MBEDTLS_SSL_HASH_NONE                0
#define MBEDTLS_SSL_HASH_MD5                 1
#define MBEDTLS_SSL_HASH_SHA1                2
#define MBEDTLS_SSL_HASH_SHA224              3
#define MBEDTLS_SSL_HASH_SHA256              4
#define MBEDTLS_SSL_HASH_SHA384              5
#define MBEDTLS_SSL_HASH_SHA512              6
248

249 250 251
#define MBEDTLS_SSL_SIG_ANON                 0
#define MBEDTLS_SSL_SIG_RSA                  1
#define MBEDTLS_SSL_SIG_ECDSA                3
252

253 254
/*
 * Client Certificate Types
255
 * RFC 5246 section 7.4.4 plus RFC 4492 section 5.5
256
 */
257 258
#define MBEDTLS_SSL_CERT_TYPE_RSA_SIGN       1
#define MBEDTLS_SSL_CERT_TYPE_ECDSA_SIGN    64
259

260 261 262
/*
 * Message, alert and handshake types
 */
263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312
#define MBEDTLS_SSL_MSG_CHANGE_CIPHER_SPEC     20
#define MBEDTLS_SSL_MSG_ALERT                  21
#define MBEDTLS_SSL_MSG_HANDSHAKE              22
#define MBEDTLS_SSL_MSG_APPLICATION_DATA       23

#define MBEDTLS_SSL_ALERT_LEVEL_WARNING         1
#define MBEDTLS_SSL_ALERT_LEVEL_FATAL           2

#define MBEDTLS_SSL_ALERT_MSG_CLOSE_NOTIFY           0  /* 0x00 */
#define MBEDTLS_SSL_ALERT_MSG_UNEXPECTED_MESSAGE    10  /* 0x0A */
#define MBEDTLS_SSL_ALERT_MSG_BAD_RECORD_MAC        20  /* 0x14 */
#define MBEDTLS_SSL_ALERT_MSG_DECRYPTION_FAILED     21  /* 0x15 */
#define MBEDTLS_SSL_ALERT_MSG_RECORD_OVERFLOW       22  /* 0x16 */
#define MBEDTLS_SSL_ALERT_MSG_DECOMPRESSION_FAILURE 30  /* 0x1E */
#define MBEDTLS_SSL_ALERT_MSG_HANDSHAKE_FAILURE     40  /* 0x28 */
#define MBEDTLS_SSL_ALERT_MSG_NO_CERT               41  /* 0x29 */
#define MBEDTLS_SSL_ALERT_MSG_BAD_CERT              42  /* 0x2A */
#define MBEDTLS_SSL_ALERT_MSG_UNSUPPORTED_CERT      43  /* 0x2B */
#define MBEDTLS_SSL_ALERT_MSG_CERT_REVOKED          44  /* 0x2C */
#define MBEDTLS_SSL_ALERT_MSG_CERT_EXPIRED          45  /* 0x2D */
#define MBEDTLS_SSL_ALERT_MSG_CERT_UNKNOWN          46  /* 0x2E */
#define MBEDTLS_SSL_ALERT_MSG_ILLEGAL_PARAMETER     47  /* 0x2F */
#define MBEDTLS_SSL_ALERT_MSG_UNKNOWN_CA            48  /* 0x30 */
#define MBEDTLS_SSL_ALERT_MSG_ACCESS_DENIED         49  /* 0x31 */
#define MBEDTLS_SSL_ALERT_MSG_DECODE_ERROR          50  /* 0x32 */
#define MBEDTLS_SSL_ALERT_MSG_DECRYPT_ERROR         51  /* 0x33 */
#define MBEDTLS_SSL_ALERT_MSG_EXPORT_RESTRICTION    60  /* 0x3C */
#define MBEDTLS_SSL_ALERT_MSG_PROTOCOL_VERSION      70  /* 0x46 */
#define MBEDTLS_SSL_ALERT_MSG_INSUFFICIENT_SECURITY 71  /* 0x47 */
#define MBEDTLS_SSL_ALERT_MSG_INTERNAL_ERROR        80  /* 0x50 */
#define MBEDTLS_SSL_ALERT_MSG_INAPROPRIATE_FALLBACK 86  /* 0x56 */
#define MBEDTLS_SSL_ALERT_MSG_USER_CANCELED         90  /* 0x5A */
#define MBEDTLS_SSL_ALERT_MSG_NO_RENEGOTIATION     100  /* 0x64 */
#define MBEDTLS_SSL_ALERT_MSG_UNSUPPORTED_EXT      110  /* 0x6E */
#define MBEDTLS_SSL_ALERT_MSG_UNRECOGNIZED_NAME    112  /* 0x70 */
#define MBEDTLS_SSL_ALERT_MSG_UNKNOWN_PSK_IDENTITY 115  /* 0x73 */
#define MBEDTLS_SSL_ALERT_MSG_NO_APPLICATION_PROTOCOL 120 /* 0x78 */

#define MBEDTLS_SSL_HS_HELLO_REQUEST            0
#define MBEDTLS_SSL_HS_CLIENT_HELLO             1
#define MBEDTLS_SSL_HS_SERVER_HELLO             2
#define MBEDTLS_SSL_HS_HELLO_VERIFY_REQUEST     3
#define MBEDTLS_SSL_HS_NEW_SESSION_TICKET       4
#define MBEDTLS_SSL_HS_CERTIFICATE             11
#define MBEDTLS_SSL_HS_SERVER_KEY_EXCHANGE     12
#define MBEDTLS_SSL_HS_CERTIFICATE_REQUEST     13
#define MBEDTLS_SSL_HS_SERVER_HELLO_DONE       14
#define MBEDTLS_SSL_HS_CERTIFICATE_VERIFY      15
#define MBEDTLS_SSL_HS_CLIENT_KEY_EXCHANGE     16
#define MBEDTLS_SSL_HS_FINISHED                20
313 314 315 316

/*
 * TLS extensions
 */
317 318
#define MBEDTLS_TLS_EXT_SERVERNAME                   0
#define MBEDTLS_TLS_EXT_SERVERNAME_HOSTNAME          0
319

320
#define MBEDTLS_TLS_EXT_MAX_FRAGMENT_LENGTH          1
321

322
#define MBEDTLS_TLS_EXT_TRUNCATED_HMAC               4
323

324 325
#define MBEDTLS_TLS_EXT_SUPPORTED_ELLIPTIC_CURVES   10
#define MBEDTLS_TLS_EXT_SUPPORTED_POINT_FORMATS     11
326

327
#define MBEDTLS_TLS_EXT_SIG_ALG                     13
328

329
#define MBEDTLS_TLS_EXT_ALPN                        16
330

331 332
#define MBEDTLS_TLS_EXT_ENCRYPT_THEN_MAC            22 /* 0x16 */
#define MBEDTLS_TLS_EXT_EXTENDED_MASTER_SECRET  0x0017 /* 23 */
333

334
#define MBEDTLS_TLS_EXT_SESSION_TICKET              35
335

336 337
#define MBEDTLS_TLS_EXT_ECJPAKE_KKPP               256 /* experimental */

338
#define MBEDTLS_TLS_EXT_RENEGOTIATION_INFO      0xFF01
339

340 341 342
/*
 * Size defines
 */
343 344
#if !defined(MBEDTLS_PSK_MAX_LEN)
#define MBEDTLS_PSK_MAX_LEN            32 /* 256 bits */
345 346 347
#endif

/* Dummy type used only for its size */
348
union mbedtls_ssl_premaster_secret
349
{
350
#if defined(MBEDTLS_KEY_EXCHANGE_RSA_ENABLED)
351 352
    unsigned char _pms_rsa[48];                         /* RFC 5246 8.1.1 */
#endif
353 354
#if defined(MBEDTLS_KEY_EXCHANGE_DHE_RSA_ENABLED)
    unsigned char _pms_dhm[MBEDTLS_MPI_MAX_SIZE];      /* RFC 5246 8.1.2 */
355
#endif
356 357 358 359 360
#if defined(MBEDTLS_KEY_EXCHANGE_ECDHE_RSA_ENABLED)    || \
    defined(MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED)  || \
    defined(MBEDTLS_KEY_EXCHANGE_ECDH_RSA_ENABLED)     || \
    defined(MBEDTLS_KEY_EXCHANGE_ECDH_ECDSA_ENABLED)
    unsigned char _pms_ecdh[MBEDTLS_ECP_MAX_BYTES];    /* RFC 4492 5.10 */
361
#endif
362 363
#if defined(MBEDTLS_KEY_EXCHANGE_PSK_ENABLED)
    unsigned char _pms_psk[4 + 2 * MBEDTLS_PSK_MAX_LEN];       /* RFC 4279 2 */
364
#endif
365 366 367
#if defined(MBEDTLS_KEY_EXCHANGE_DHE_PSK_ENABLED)
    unsigned char _pms_dhe_psk[4 + MBEDTLS_MPI_MAX_SIZE
                                 + MBEDTLS_PSK_MAX_LEN];       /* RFC 4279 3 */
368
#endif
369 370
#if defined(MBEDTLS_KEY_EXCHANGE_RSA_PSK_ENABLED)
    unsigned char _pms_rsa_psk[52 + MBEDTLS_PSK_MAX_LEN];      /* RFC 4279 4 */
371
#endif
372 373 374
#if defined(MBEDTLS_KEY_EXCHANGE_ECDHE_PSK_ENABLED)
    unsigned char _pms_ecdhe_psk[4 + MBEDTLS_ECP_MAX_BYTES
                                   + MBEDTLS_PSK_MAX_LEN];     /* RFC 5489 2 */
375
#endif
376 377 378
#if defined(MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED)
    unsigned char _pms_ecjpake[32];     /* Thread spec: SHA-256 output */
#endif
379 380
};

381
#define MBEDTLS_PREMASTER_SIZE     sizeof( union mbedtls_ssl_premaster_secret )
382

383 384 385 386
#ifdef __cplusplus
extern "C" {
#endif

387 388 389 390 391
/*
 * SSL state machine
 */
typedef enum
{
392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410
    MBEDTLS_SSL_HELLO_REQUEST,
    MBEDTLS_SSL_CLIENT_HELLO,
    MBEDTLS_SSL_SERVER_HELLO,
    MBEDTLS_SSL_SERVER_CERTIFICATE,
    MBEDTLS_SSL_SERVER_KEY_EXCHANGE,
    MBEDTLS_SSL_CERTIFICATE_REQUEST,
    MBEDTLS_SSL_SERVER_HELLO_DONE,
    MBEDTLS_SSL_CLIENT_CERTIFICATE,
    MBEDTLS_SSL_CLIENT_KEY_EXCHANGE,
    MBEDTLS_SSL_CERTIFICATE_VERIFY,
    MBEDTLS_SSL_CLIENT_CHANGE_CIPHER_SPEC,
    MBEDTLS_SSL_CLIENT_FINISHED,
    MBEDTLS_SSL_SERVER_CHANGE_CIPHER_SPEC,
    MBEDTLS_SSL_SERVER_FINISHED,
    MBEDTLS_SSL_FLUSH_BUFFERS,
    MBEDTLS_SSL_HANDSHAKE_WRAPUP,
    MBEDTLS_SSL_HANDSHAKE_OVER,
    MBEDTLS_SSL_SERVER_NEW_SESSION_TICKET,
    MBEDTLS_SSL_SERVER_HELLO_VERIFY_REQUEST_SENT,
411
}
412
mbedtls_ssl_states;
413

414 415 416 417 418 419
/**
 * \brief          Callback type: send data on the network.
 *
 * \note           That callback may be either blocking or non-blocking.
 *
 * \param ctx      Context for the send callback (typically a file descriptor)
420
 * \param buf      Buffer holding the data to send
421 422 423 424 425 426 427
 * \param len      Length of the data to send
 *
 * \return         The callback must return the number of bytes sent if any,
 *                 or a non-zero error code.
 *                 If performing non-blocking I/O, \c MBEDTLS_ERR_SSL_WANT_WRITE
 *                 must be returned when the operation would block.
 *
428
 * \note           The callback is allowed to send fewer bytes than requested.
429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449
 *                 It must always return the number of bytes actually sent.
 */
typedef int mbedtls_ssl_send_t( void *ctx,
                                const unsigned char *buf,
                                size_t len );

/**
 * \brief          Callback type: receive data from the network.
 *
 * \note           That callback may be either blocking or non-blocking.
 *
 * \param ctx      Context for the receive callback (typically a file
 *                 descriptor)
 * \param buf      Buffer to write the received data to
 * \param len      Length of the receive buffer
 *
 * \return         The callback must return the number of bytes received,
 *                 or a non-zero error code.
 *                 If performing non-blocking I/O, \c MBEDTLS_ERR_SSL_WANT_READ
 *                 must be returned when the operation would block.
 *
450
 * \note           The callback may receive fewer bytes than the length of the
451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468
 *                 buffer. It must always return the number of bytes actually
 *                 received and written to the buffer.
 */
typedef int mbedtls_ssl_recv_t( void *ctx,
                                unsigned char *buf,
                                size_t len );

/**
 * \brief          Callback type: receive data from the network, with timeout
 *
 * \note           That callback must block until data is received, or the
 *                 timeout delay expires, or the operation is interrupted by a
 *                 signal.
 *
 * \param ctx      Context for the receive callback (typically a file descriptor)
 * \param buf      Buffer to write the received data to
 * \param len      Length of the receive buffer
 * \param timeout  Maximum nomber of millisecondes to wait for data
469
 *                 0 means no timeout (potentially waiting forever)
470 471 472 473 474 475
 *
 * \return         The callback must return the number of bytes received,
 *                 or a non-zero error code:
 *                 \c MBEDTLS_ERR_SSL_TIMEOUT if the operation timed out,
 *                 \c MBEDTLS_ERR_SSL_WANT_READ if interrupted by a signal.
 *
476
 * \note           The callback may receive fewer bytes than the length of the
477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516
 *                 buffer. It must always return the number of bytes actually
 *                 received and written to the buffer.
 */
typedef int mbedtls_ssl_recv_timeout_t( void *ctx,
                                        unsigned char *buf,
                                        size_t len,
                                        uint32_t timeout );
/**
 * \brief          Callback type: set a pair of timers/delays to watch
 *
 * \param ctx      Context pointer
 * \param int_ms   Intermediate delay in milliseconds
 * \param fin_ms   Final delay in milliseconds
 *                 0 cancels the current timer.
 *
 * \note           This callback must at least store the necessary information
 *                 for the associated \c mbedtls_ssl_get_timer_t callback to
 *                 return correct information.
 *
 * \note           If using a event-driven style of programming, an event must
 *                 be generated when the final delay is passed. The event must
 *                 cause a call to \c mbedtls_ssl_handshake() with the proper
 *                 SSL context to be scheduled. Care must be taken to ensure
 *                 that at most one such call happens at a time.
 *
 * \note           Only one timer at a time must be running. Calling this
 *                 function while a timer is running must cancel it. Cancelled
 *                 timers must not generate any event.
 */
typedef void mbedtls_ssl_set_timer_t( void * ctx,
                                      uint32_t int_ms,
                                      uint32_t fin_ms );

/**
 * \brief          Callback type: get status of timers/delays
 *
 * \param ctx      Context pointer
 *
 * \return         This callback must return:
 *                 -1 if cancelled (fin_ms == 0),
517 518 519
 *                  0 if none of the delays have passed,
 *                  1 if only the intermediate delay has passed,
 *                  2 if the final delay has passed.
520 521 522 523
 */
typedef int mbedtls_ssl_get_timer_t( void * ctx );


524
/* Defined below */
525 526
typedef struct mbedtls_ssl_session mbedtls_ssl_session;
typedef struct mbedtls_ssl_context mbedtls_ssl_context;
527 528 529
typedef struct mbedtls_ssl_config  mbedtls_ssl_config;

/* Defined in ssl_internal.h */
530 531 532 533
typedef struct mbedtls_ssl_transform mbedtls_ssl_transform;
typedef struct mbedtls_ssl_handshake_params mbedtls_ssl_handshake_params;
#if defined(MBEDTLS_X509_CRT_PARSE_C)
typedef struct mbedtls_ssl_key_cert mbedtls_ssl_key_cert;
534
#endif
535 536
#if defined(MBEDTLS_SSL_PROTO_DTLS)
typedef struct mbedtls_ssl_flight_item mbedtls_ssl_flight_item;
537
#endif
538 539

/*
540
 * This structure is used for storing current session data.
541
 */
542
struct mbedtls_ssl_session
543
{
544
#if defined(MBEDTLS_HAVE_TIME)
545
    mbedtls_time_t start;       /*!< starting time      */
546
#endif
547
    int ciphersuite;            /*!< chosen ciphersuite */
548
    int compression;            /*!< chosen compression */
549
    size_t id_len;              /*!< session id length  */
550 551
    unsigned char id[32];       /*!< session identifier */
    unsigned char master[48];   /*!< the master secret  */
552

553 554 555
#if defined(MBEDTLS_X509_CRT_PARSE_C)
    mbedtls_x509_crt *peer_cert;        /*!< peer X.509 cert chain */
#endif /* MBEDTLS_X509_CRT_PARSE_C */
556
    uint32_t verify_result;          /*!<  verification result     */
557

558
#if defined(MBEDTLS_SSL_SESSION_TICKETS) && defined(MBEDTLS_SSL_CLI_C)
559 560
    unsigned char *ticket;      /*!< RFC 5077 session ticket */
    size_t ticket_len;          /*!< session ticket length   */
561
    uint32_t ticket_lifetime;   /*!< ticket lifetime hint    */
562
#endif /* MBEDTLS_SSL_SESSION_TICKETS && MBEDTLS_SSL_CLI_C */
563

564
#if defined(MBEDTLS_SSL_MAX_FRAGMENT_LENGTH)
565
    unsigned char mfl_code;     /*!< MaxFragmentLength negotiated by peer */
566
#endif /* MBEDTLS_SSL_MAX_FRAGMENT_LENGTH */
567

568
#if defined(MBEDTLS_SSL_TRUNCATED_HMAC)
569
    int trunc_hmac;             /*!< flag for truncated hmac activation   */
570
#endif /* MBEDTLS_SSL_TRUNCATED_HMAC */
571

572
#if defined(MBEDTLS_SSL_ENCRYPT_THEN_MAC)
573 574
    int encrypt_then_mac;       /*!< flag for EtM activation                */
#endif
575 576
};

577
/**
578
 * SSL/TLS configuration to be shared between mbedtls_ssl_context structures.
579
 */
580
struct mbedtls_ssl_config
581 582 583 584 585 586 587
{
    /* Group items by size (largest first) to minimize padding overhead */

    /*
     * Pointers
     */

588
    const int *ciphersuite_list[4]; /*!< allowed ciphersuites per version   */
589 590

    /** Callback for printing debug output                                  */
591
    void (*f_dbg)(void *, int, const char *, int, const char *);
592 593
    void *p_dbg;                    /*!< context for the debug function     */

594 595 596 597
    /** Callback for getting (pseudo-)random numbers                        */
    int  (*f_rng)(void *, unsigned char *, size_t);
    void *p_rng;                    /*!< context for the RNG function       */

598 599 600 601
    /** Callback to retrieve a session from the cache                       */
    int (*f_get_cache)(void *, mbedtls_ssl_session *);
    /** Callback to store a session into the cache                          */
    int (*f_set_cache)(void *, const mbedtls_ssl_session *);
602
    void *p_cache;                  /*!< context for cache callbacks        */
603 604 605 606 607 608 609 610 611

#if defined(MBEDTLS_SSL_SERVER_NAME_INDICATION)
    /** Callback for setting cert according to SNI extension                */
    int (*f_sni)(void *, mbedtls_ssl_context *, const unsigned char *, size_t);
    void *p_sni;                    /*!< context for SNI callback           */
#endif

#if defined(MBEDTLS_X509_CRT_PARSE_C)
    /** Callback to customize X.509 certificate chain verification          */
612
    int (*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *);
613 614 615 616 617 618 619 620 621
    void *p_vrfy;                   /*!< context for X.509 verify calllback */
#endif

#if defined(MBEDTLS_KEY_EXCHANGE__SOME__PSK_ENABLED)
    /** Callback to retrieve PSK key from identity                          */
    int (*f_psk)(void *, mbedtls_ssl_context *, const unsigned char *, size_t);
    void *p_psk;                    /*!< context for PSK callback           */
#endif

622
#if defined(MBEDTLS_SSL_DTLS_HELLO_VERIFY) && defined(MBEDTLS_SSL_SRV_C)
623 624 625 626 627 628
    /** Callback to create & write a cookie for ClientHello veirifcation    */
    int (*f_cookie_write)( void *, unsigned char **, unsigned char *,
                           const unsigned char *, size_t );
    /** Callback to verify validity of a ClientHello cookie                 */
    int (*f_cookie_check)( void *, const unsigned char *, size_t,
                           const unsigned char *, size_t );
629
    void *p_cookie;                 /*!< context for the cookie callbacks   */
630 631
#endif

632
#if defined(MBEDTLS_SSL_SESSION_TICKETS) && defined(MBEDTLS_SSL_SRV_C)
633 634 635 636 637 638
    /** Callback to create & write a session ticket                         */
    int (*f_ticket_write)( void *, const mbedtls_ssl_session *,
            unsigned char *, const unsigned char *, size_t *, uint32_t * );
    /** Callback to parse a session ticket into a session structure         */
    int (*f_ticket_parse)( void *, mbedtls_ssl_session *, unsigned char *, size_t);
    void *p_ticket;                 /*!< context for the ticket callbacks   */
639
#endif /* MBEDTLS_SSL_SESSION_TICKETS && MBEDTLS_SSL_SRV_C */
640

Robert Cragie's avatar
Robert Cragie committed
641
#if defined(MBEDTLS_SSL_EXPORT_KEYS)
642
    /** Callback to export key block and master secret                      */
Robert Cragie's avatar
Robert Cragie committed
643 644 645 646 647
    int (*f_export_keys)( void *, const unsigned char *,
            const unsigned char *, size_t, size_t, size_t );
    void *p_export_keys;            /*!< context for key export callback    */
#endif

648
#if defined(MBEDTLS_X509_CRT_PARSE_C)
649
    const mbedtls_x509_crt_profile *cert_profile; /*!< verification profile */
650 651 652 653 654
    mbedtls_ssl_key_cert *key_cert; /*!< own certificate/key pair(s)        */
    mbedtls_x509_crt *ca_chain;     /*!< trusted CAs                        */
    mbedtls_x509_crl *ca_crl;       /*!< trusted CAs CRLs                   */
#endif /* MBEDTLS_X509_CRT_PARSE_C */

655
#if defined(MBEDTLS_KEY_EXCHANGE__WITH_CERT__ENABLED)
656 657 658
    const int *sig_hashes;          /*!< allowed signature hashes           */
#endif

659
#if defined(MBEDTLS_ECP_C)
660
    const mbedtls_ecp_group_id *curve_list; /*!< allowed curves             */
661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682
#endif

#if defined(MBEDTLS_DHM_C)
    mbedtls_mpi dhm_P;              /*!< prime modulus for DHM              */
    mbedtls_mpi dhm_G;              /*!< generator for DHM                  */
#endif

#if defined(MBEDTLS_KEY_EXCHANGE__SOME__PSK_ENABLED)
    unsigned char *psk;             /*!< pre-shared key                     */
    size_t         psk_len;         /*!< length of the pre-shared key       */
    unsigned char *psk_identity;    /*!< identity for PSK negotiation       */
    size_t         psk_identity_len;/*!< length of identity                 */
#endif

#if defined(MBEDTLS_SSL_ALPN)
    const char **alpn_list;         /*!< ordered list of protocols          */
#endif

    /*
     * Numerical settings (int then char)
     */

683 684
    uint32_t read_timeout;          /*!< timeout for mbedtls_ssl_read (ms)  */

685 686
#if defined(MBEDTLS_SSL_PROTO_DTLS)
    uint32_t hs_timeout_min;        /*!< initial value of the handshake
687
                                         retransmission timeout (ms)        */
688
    uint32_t hs_timeout_max;        /*!< maximum value of the handshake
689
                                         retransmission timeout (ms)        */
690 691 692 693 694 695 696 697 698 699 700 701
#endif

#if defined(MBEDTLS_SSL_RENEGOTIATION)
    int renego_max_records;         /*!< grace period for renegotiation     */
    unsigned char renego_period[8]; /*!< value of the record counters
                                         that triggers renegotiation        */
#endif

#if defined(MBEDTLS_SSL_DTLS_BADMAC_LIMIT)
    unsigned int badmac_limit;      /*!< limit of records with a bad MAC    */
#endif

702 703 704 705
#if defined(MBEDTLS_DHM_C) && defined(MBEDTLS_SSL_CLI_C)
    unsigned int dhm_min_bitlen;    /*!< min. bit length of the DHM prime   */
#endif

706 707 708 709 710 711 712 713 714 715 716 717 718 719
    unsigned char max_major_ver;    /*!< max. major version used            */
    unsigned char max_minor_ver;    /*!< max. minor version used            */
    unsigned char min_major_ver;    /*!< min. major version used            */
    unsigned char min_minor_ver;    /*!< min. minor version used            */

    /*
     * Flags (bitfields)
     */

    unsigned int endpoint : 1;      /*!< 0: client, 1: server               */
    unsigned int transport : 1;     /*!< stream (TLS) or datagram (DTLS)    */
    unsigned int authmode : 2;      /*!< MBEDTLS_SSL_VERIFY_XXX             */
    /* needed even with renego disabled for LEGACY_BREAK_HANDSHAKE          */
    unsigned int allow_legacy_renegotiation : 2 ; /*!< MBEDTLS_LEGACY_XXX   */
720 721 722
#if defined(MBEDTLS_ARC4_C)
    unsigned int arc4_disabled : 1; /*!< blacklist RC4 ciphersuites?        */
#endif
723 724 725
#if defined(MBEDTLS_SSL_MAX_FRAGMENT_LENGTH)
    unsigned int mfl_code : 3;      /*!< desired fragment length            */
#endif
726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746
#if defined(MBEDTLS_SSL_ENCRYPT_THEN_MAC)
    unsigned int encrypt_then_mac : 1 ; /*!< negotiate encrypt-then-mac?    */
#endif
#if defined(MBEDTLS_SSL_EXTENDED_MASTER_SECRET)
    unsigned int extended_ms : 1;   /*!< negotiate extended master secret?  */
#endif
#if defined(MBEDTLS_SSL_DTLS_ANTI_REPLAY)
    unsigned int anti_replay : 1;   /*!< detect and prevent replay?         */
#endif
#if defined(MBEDTLS_SSL_CBC_RECORD_SPLITTING)
    unsigned int cbc_record_splitting : 1;  /*!< do cbc record splitting    */
#endif
#if defined(MBEDTLS_SSL_RENEGOTIATION)
    unsigned int disable_renegotiation : 1; /*!< disable renegotiation?     */
#endif
#if defined(MBEDTLS_SSL_TRUNCATED_HMAC)
    unsigned int trunc_hmac : 1;    /*!< negotiate truncated hmac?          */
#endif
#if defined(MBEDTLS_SSL_SESSION_TICKETS)
    unsigned int session_tickets : 1;   /*!< use session tickets?           */
#endif
747 748 749
#if defined(MBEDTLS_SSL_FALLBACK_SCSV) && defined(MBEDTLS_SSL_CLI_C)
    unsigned int fallback : 1;      /*!< is this a fallback?                */
#endif
750 751
};

752

753
struct mbedtls_ssl_context
754
{
755
    const mbedtls_ssl_config *conf; /*!< configuration information          */
756

757 758 759 760
    /*
     * Miscellaneous
     */
    int state;                  /*!< SSL handshake: current state     */
761
#if defined(MBEDTLS_SSL_RENEGOTIATION)
762
    int renego_status;          /*!< Initial, in progress, pending?   */
763 764 765
    int renego_records_seen;    /*!< Records since renego request, or with DTLS,
                                  number of retransmissions of request if
                                  renego_max_records is < 0           */
766
#endif
767

768
    int major_ver;              /*!< equal to  MBEDTLS_SSL_MAJOR_VERSION_3    */
769 770
    int minor_ver;              /*!< either 0 (SSL3) or 1 (TLS1.0)    */

771
#if defined(MBEDTLS_SSL_DTLS_BADMAC_LIMIT)
772 773 774
    unsigned badmac_seen;       /*!< records with a bad MAC received    */
#endif

775 776 777 778 779
    mbedtls_ssl_send_t *f_send; /*!< Callback for network send */
    mbedtls_ssl_recv_t *f_recv; /*!< Callback for network receive */
    mbedtls_ssl_recv_timeout_t *f_recv_timeout;
                                /*!< Callback for network receive with timeout */

780
    void *p_bio;                /*!< context for I/O operations   */
781

782 783 784
    /*
     * Session layer
     */
785 786 787 788
    mbedtls_ssl_session *session_in;            /*!<  current session data (in)   */
    mbedtls_ssl_session *session_out;           /*!<  current session data (out)  */
    mbedtls_ssl_session *session;               /*!<  negotiated session data     */
    mbedtls_ssl_session *session_negotiate;     /*!<  session data in negotiation */
789

790
    mbedtls_ssl_handshake_params *handshake;    /*!<  params required only during
791 792 793 794 795
                                              the handshake process        */

    /*
     * Record layer transformations
     */
796 797 798 799
    mbedtls_ssl_transform *transform_in;        /*!<  current transform params (in)   */
    mbedtls_ssl_transform *transform_out;       /*!<  current transform params (in)   */
    mbedtls_ssl_transform *transform;           /*!<  negotiated transform params     */
    mbedtls_ssl_transform *transform_negotiate; /*!<  transform params in negotiation */
800

801
    /*
802
     * Timers
803
     */
804
    void *p_timer;              /*!< context for the timer callbacks */
805 806 807

    mbedtls_ssl_set_timer_t *f_set_timer;       /*!< set timer callback */
    mbedtls_ssl_get_timer_t *f_get_timer;       /*!< get timer callback */
808

809 810 811
    /*
     * Record layer (incoming data)
     */
812
    unsigned char *in_buf;      /*!< input buffer                     */
813 814 815
    unsigned char *in_ctr;      /*!< 64-bit incoming message counter
                                     TLS: maintained by us
                                     DTLS: read from peer             */
816 817 818
    unsigned char *in_hdr;      /*!< start of record header           */
    unsigned char *in_len;      /*!< two-bytes message length field   */
    unsigned char *in_iv;       /*!< ivlen-byte IV                    */
819
    unsigned char *in_msg;      /*!< message contents (in_iv+ivlen)   */
820 821 822
    unsigned char *in_offt;     /*!< read offset in application data  */

    int in_msgtype;             /*!< record header: message type      */
823 824
    size_t in_msglen;           /*!< record header: message length    */
    size_t in_left;             /*!< amount of data read so far       */
825
#if defined(MBEDTLS_SSL_PROTO_DTLS)
826
    uint16_t in_epoch;          /*!< DTLS epoch for incoming records  */
827 828
    size_t next_record_offset;  /*!< offset of the next record in datagram
                                     (equal to in_left if none)       */
829
#endif
830
#if defined(MBEDTLS_SSL_DTLS_ANTI_REPLAY)
831 832 833
    uint64_t in_window_top;     /*!< last validated record seq_num    */
    uint64_t in_window;         /*!< bitmask for replay detection     */
#endif
834

835 836
    size_t in_hslen;            /*!< current handshake message length,
                                     including the handshake header   */
837
    int nb_zero;                /*!< # of 0-length encrypted messages */
838
    int record_read;            /*!< record is already present        */
839 840 841 842

    /*
     * Record layer (outgoing data)
     */
843
    unsigned char *out_buf;     /*!< output buffer                    */
844
    unsigned char *out_ctr;     /*!< 64-bit outgoing message counter  */
845 846 847
    unsigned char *out_hdr;     /*!< start of record header           */
    unsigned char *out_len;     /*!< two-bytes message length field   */
    unsigned char *out_iv;      /*!< ivlen-byte IV                    */
848
    unsigned char *out_msg;     /*!< message contents (out_iv+ivlen)  */
849 850

    int out_msgtype;            /*!< record header: message type      */
851 852
    size_t out_msglen;          /*!< record header: message length    */
    size_t out_left;            /*!< amount of data not yet written   */
853

854
#if defined(MBEDTLS_ZLIB_SUPPORT)
855 856
    unsigned char *compress_buf;        /*!<  zlib data buffer        */
#endif
857
#if defined(MBEDTLS_SSL_CBC_RECORD_SPLITTING)
858
    signed char split_done;     /*!< current record already splitted? */
859
#endif
860

861 862 863 864 865
    /*
     * PKI layer
     */
    int client_auth;                    /*!<  flag for client auth.   */

866
    /*
867
     * User settings
868
     */
869 870 871
#if defined(MBEDTLS_X509_CRT_PARSE_C)
    char *hostname;             /*!< expected peer CN for verification
                                     (and SNI if available)                 */
872
#endif
873

874
#if defined(MBEDTLS_SSL_ALPN)
875 876 877
    const char *alpn_chosen;    /*!<  negotiated protocol                   */
#endif

878
    /*
879
     * Information for DTLS hello verify
880
     */
881
#if defined(MBEDTLS_SSL_DTLS_HELLO_VERIFY) && defined(MBEDTLS_SSL_SRV_C)
882 883 884 885
    unsigned char  *cli_id;         /*!<  transport-level ID of the client  */
    size_t          cli_id_len;     /*!<  length of cli_id                  */
#endif

886 887 888
    /*
     * Secure renegotiation
     */
889
    /* needed to know when to send extension on server */
890 891
    int secure_renegotiation;           /*!<  does peer support legacy or
                                              secure renegotiation           */
892
#if defined(MBEDTLS_SSL_RENEGOTIATION)
893
    size_t verify_data_len;             /*!<  length of verify data stored   */
894 895
    char own_verify_data[MBEDTLS_SSL_VERIFY_DATA_MAX_LEN]; /*!<  previous handshake verify data */
    char peer_verify_data[MBEDTLS_SSL_VERIFY_DATA_MAX_LEN]; /*!<  previous handshake verify data */
896
#endif
897 898
};

899
#if defined(MBEDTLS_SSL_HW_RECORD_ACCEL)
900

901 902
#define MBEDTLS_SSL_CHANNEL_OUTBOUND    0
#define MBEDTLS_SSL_CHANNEL_INBOUND     1
903

904
extern int (*mbedtls_ssl_hw_record_init)(mbedtls_ssl_context *ssl,
905
                const unsigned char *key_enc, const unsigned char *key_dec,
906
                size_t keylen,
907
                const unsigned char *iv_enc,  const unsigned char *iv_dec,
908 909 910
                size_t ivlen,
                const unsigned char *mac_enc, const unsigned char *mac_dec,
                size_t maclen);
911 912 913 914 915 916
extern int (*mbedtls_ssl_hw_record_activate)(mbedtls_ssl_context *ssl, int direction);
extern int (*mbedtls_ssl_hw_record_reset)(mbedtls_ssl_context *ssl);
extern int (*mbedtls_ssl_hw_record_write)(mbedtls_ssl_context *ssl);
extern int (*mbedtls_ssl_hw_record_read)(mbedtls_ssl_context *ssl);
extern int (*mbedtls_ssl_hw_record_finish)(mbedtls_ssl_context *ssl);
#endif /* MBEDTLS_SSL_HW_RECORD_ACCEL */
917

918
/**
919
 * \brief Returns the list of ciphersuites supported by the SSL/TLS module.
920
 *
921 922
 * \return              a statically allocated array of ciphersuites, the last
 *                      entry is 0.
923
 */
924
const int *mbedtls_ssl_list_ciphersuites( void );
925 926

/**
927 928
 * \brief               Return the name of the ciphersuite associated with the
 *                      given ID
929
 *
930
 * \param ciphersuite_id SSL ciphersuite ID
931
 *
932
 * \return              a string containing the ciphersuite name
933
 */
934
const char *mbedtls_ssl_get_ciphersuite_name( const int ciphersuite_id );
935 936

/**
937 938
 * \brief               Return the ID of the ciphersuite associated with the
 *                      given name
939 940 941 942 943
 *
 * \param ciphersuite_name SSL ciphersuite name
 *
 * \return              the ID with the ciphersuite or 0 if not found
 */
944
int mbedtls_ssl_get_ciphersuite_id( const char *ciphersuite_name );
945

946 947
/**
 * \brief          Initialize an SSL context
948
 *                 Just makes the context ready for mbedtls_ssl_setup() or
949 950 951 952 953 954 955 956
 *                 mbedtls_ssl_free()
 *
 * \param ssl      SSL context
 */
void mbedtls_ssl_init( mbedtls_ssl_context *ssl );

/**
 * \brief          Set up an SSL context for use
957
 *
958
 * \note           No copy of the configuration context is made, it can be
959
 *                 shared by many mbedtls_ssl_context structures.
960
 *
961
 * \warning        Modifying the conf structure after it has been used in this
962 963
 *                 function is unsupported!
 *
964
 * \param ssl      SSL context
965
 * \param conf     SSL configuration to use
966
 *
967
 * \return         0 if successful, or MBEDTLS_ERR_SSL_ALLOC_FAILED if
968
 *                 memory allocation failed
969
 */
970
int mbedtls_ssl_setup( mbedtls_ssl_context *ssl,
971
                       const mbedtls_ssl_config *conf );
972

973 974 975 976 977 978
/**
 * \brief          Reset an already initialized SSL context for re-use
 *                 while retaining application-set variables, function
 *                 pointers and data.
 *
 * \param ssl      SSL context
Attila Molnar's avatar
Attila Molnar committed
979
 * \return         0 if successful, or MBEDTLS_ERR_SSL_ALLOC_FAILED,
980 981
                   MBEDTLS_ERR_SSL_HW_ACCEL_FAILED or
 *                 MBEDTLS_ERR_SSL_COMPRESSION_FAILED
982
 */
983
int mbedtls_ssl_session_reset( mbedtls_ssl_context *ssl );
984

985 986 987
/**
 * \brief          Set the current endpoint type
 *
988
 * \param conf     SSL configuration
989
 * \param endpoint must be MBEDTLS_SSL_IS_CLIENT or MBEDTLS_SSL_IS_SERVER
990
 */
991
void mbedtls_ssl_conf_endpoint( mbedtls_ssl_config *conf, int endpoint );
992

993
/**
994 995
 * \brief           Set the transport type (TLS or DTLS).
 *                  Default: TLS
996
 *
997 998
 * \note            For DTLS, you must either provide a recv callback that
 *                  doesn't block, or one that handles timeouts, see
999 1000
 *                  \c mbedtls_ssl_set_bio(). You also need to provide timer
 *                  callbacks with \c mbedtls_ssl_set_timer_cb().
1001
 *
1002
 * \param conf      SSL configuration
1003
 * \param transport transport type:
1004 1005
 *                  MBEDTLS_SSL_TRANSPORT_STREAM for TLS,
 *                  MBEDTLS_SSL_TRANSPORT_DATAGRAM for DTLS.
1006
 */
1007
void mbedtls_ssl_conf_transport( mbedtls_ssl_config *conf, int transport );
1008

1009 1010
/**
 * \brief          Set the certificate verification mode
1011
 *                 Default: NONE on server, REQUIRED on client
1012
 *
1013
 * \param conf     SSL configuration
1014
 * \param authmode can be:
1015
 *
1016
 *  MBEDTLS_SSL_VERIFY_NONE:      peer certificate is not checked
1017 1018
 *                        (default on server)
 *                        (insecure on client)
1019
 *
1020
 *  MBEDTLS_SSL_VERIFY_OPTIONAL:  peer certificate is checked, however the
1021
 *                        handshake continues even if verification failed;
1022
 *                        mbedtls_ssl_get_verify_result() can be called after the
1023 1024
 *                        handshake is complete.
 *
1025
 *  MBEDTLS_SSL_VERIFY_REQUIRED:  peer *must* present a valid certificate,
1026
 *                        handshake is aborted if verification failed.
1027
 *                        (default on client)
1028
 *
1029 1030
 * \note On client, MBEDTLS_SSL_VERIFY_REQUIRED is the recommended mode.
 * With MBEDTLS_SSL_VERIFY_OPTIONAL, the user needs to call mbedtls_ssl_get_verify_result() at
1031 1032 1033
 * the right time(s), which may not be obvious, while REQUIRED always perform
 * the verification as soon as possible. For example, REQUIRED was protecting
 * against the "triple handshake" attack even before it was found.
1034
 */
1035
void mbedtls_ssl_conf_authmode( mbedtls_ssl_config *conf, int authmode );
1036

1037
#if defined(MBEDTLS_X509_CRT_PARSE_C)
1038 1039 1040
/**
 * \brief          Set the verification callback (Optional).
 *
1041 1042 1043
 *                 If set, the verify callback is called for each
 *                 certificate in the chain. For implementation
 *                 information, please see \c x509parse_verify()
1044
 *
1045
 * \param conf     SSL configuration
1046 1047 1048
 * \param f_vrfy   verification function
 * \param p_vrfy   verification parameter
 */
1049
void mbedtls_ssl_conf_verify( mbedtls_ssl_config *conf,
1050
                     int (*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *),
1051
                     void *p_vrfy );
1052
#endif /* MBEDTLS_X509_CRT_PARSE_C */
1053

1054 1055 1056
/**
 * \brief          Set the random number generator callback
 *
1057
 * \param conf     SSL configuration
1058 1059 1060
 * \param f_rng    RNG function
 * \param p_rng    RNG parameter
 */
1061
void mbedtls_ssl_conf_rng( mbedtls_ssl_config *conf,
1062
                  int (*f_rng)(void *, unsigned char *, size_t),
1063 1064 1065 1066 1067
                  void *p_rng );

/**
 * \brief          Set the debug callback
 *
1068 1069 1070 1071 1072 1073 1074
 *                 The callback has the following argument:
 *                 void *           opaque context for the callback
 *                 int              debug level
 *                 const char *     file name
 *                 int              line number
 *                 const char *     message
 *
1075
 * \param conf     SSL configuration
1076 1077 1078
 * \param f_dbg    debug function
 * \param p_dbg    debug parameter
 */
1079
void mbedtls_ssl_conf_dbg( mbedtls_ssl_config *conf,
1080
                  void (*f_dbg)(void *, int, const char *, int, const char *),
1081 1082
                  void  *p_dbg );

1083 1084 1085 1086 1087 1088 1089 1090
/**
 * \brief          Set the underlying BIO callbacks for write, read and
 *                 read-with-timeout.
 *
 * \param ssl      SSL context
 * \param p_bio    parameter (context) shared by BIO callbacks
 * \param f_send   write callback
 * \param f_recv   read callback
1091
 * \param f_recv_timeout blocking read callback with timeout.
1092
 *
1093 1094 1095
 * \note           One of f_recv or f_recv_timeout can be NULL, in which case
 *                 the other is used. If both are non-NULL, f_recv_timeout is
 *                 used and f_recv is ignored (as if it were NULL).
1096
 *
1097 1098 1099 1100 1101 1102
 * \note           The two most common use cases are:
 *                 - non-blocking I/O, f_recv != NULL, f_recv_timeout == NULL
 *                 - blocking I/O, f_recv == NULL, f_recv_timout != NULL
 *
 * \note           For DTLS, you need to provide either a non-NULL
 *                 f_recv_timeout callback, or a f_recv that doesn't block.
1103 1104 1105
 *
 * \note           See the documentations of \c mbedtls_ssl_sent_t,
 *                 \c mbedtls_ssl_recv_t and \c mbedtls_ssl_recv_timeout_t for
1106
 *                 the conventions those callbacks must follow.
1107
 *
1108 1109 1110 1111
 * \note           On some platforms, net_sockets.c provides
 *                 \c mbedtls_net_send(), \c mbedtls_net_recv() and
 *                 \c mbedtls_net_recv_timeout() that are suitable to be used
 *                 here.
1112
 */
1113
void mbedtls_ssl_set_bio( mbedtls_ssl_context *ssl,
1114 1115 1116 1117
                          void *p_bio,
                          mbedtls_ssl_send_t *f_send,
                          mbedtls_ssl_recv_t *f_recv,
                          mbedtls_ssl_recv_timeout_t *f_recv_timeout );
1118 1119 1120 1121 1122 1123 1124 1125 1126 1127

/**
 * \brief          Set the timeout period for mbedtls_ssl_read()
 *                 (Default: no timeout.)
 *
 * \param conf     SSL configuration context
 * \param timeout  Timeout value in milliseconds.
 *                 Use 0 for no timeout (default).
 *
 * \note           With blocking I/O, this will only work if a non-NULL
1128
 *                 \c f_recv_timeout was set with \c mbedtls_ssl_set_bio().
1129 1130 1131 1132 1133
 *                 With non-blocking I/O, this will only work if timer
 *                 callbacks were set with \c mbedtls_ssl_set_timer_cb().
 *
 * \note           With non-blocking I/O, you may also skip this function
 *                 altogether and handle timeouts at the application layer.
1134
 */
1135
void mbedtls_ssl_conf_read_timeout( mbedtls_ssl_config *conf, uint32_t timeout );
1136

1137 1138
/**
 * \brief          Set the timer callbacks (Mandatory for DTLS.)
1139 1140
 *
 * \param ssl      SSL context
1141
 * \param p_timer  parameter (context) shared by timer callbacks
1142 1143
 * \param f_set_timer   set timer callback
 * \param f_get_timer   get timer callback. Must return:
1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154
 *
 * \note           See the documentation of \c mbedtls_ssl_set_timer_t and
 *                 \c mbedtls_ssl_get_timer_t for the conventions this pair of
 *                 callbacks must fallow.
 *
 * \note           On some platforms, timing.c provides
 *                 \c mbedtls_timing_set_delay() and
 *                 \c mbedtls_timing_get_delay() that are suitable for using
 *                 here, except if using an event-driven style.
 *
 * \note           See also the "DTLS tutorial" article in our knowledge base.
1155
 *                 https://tls.mbed.org/kb/how-to/dtls-tutorial
1156 1157 1158
 */
void mbedtls_ssl_set_timer_cb( mbedtls_ssl_context *ssl,
                               void *p_timer,
1159 1160
                               mbedtls_ssl_set_timer_t *f_set_timer,
                               mbedtls_ssl_get_timer_t *f_get_timer );
1161

1162 1163 1164 1165
/**
 * \brief           Callback type: generate and write session ticket
 *
 * \note            This describes what a callback implementation should do.
1166
 *                  This callback should generate an encrypted and
1167 1168 1169 1170 1171
 *                  authenticated ticket for the session and write it to the
 *                  output buffer. Here, ticket means the opaque ticket part
 *                  of the NewSessionTicket structure of RFC 5077.
 *
 * \param p_ticket  Context for the callback
1172 1173
 * \param session   SSL session to be written in the ticket
 * \param start     Start of the output buffer
1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187
 * \param end       End of the output buffer
 * \param tlen      On exit, holds the length written
 * \param lifetime  On exit, holds the lifetime of the ticket in seconds
 *
 * \return          0 if successful, or
 *                  a specific MBEDTLS_ERR_XXX code.
 */
typedef int mbedtls_ssl_ticket_write_t( void *p_ticket,
                                        const mbedtls_ssl_session *session,
                                        unsigned char *start,
                                        const unsigned char *end,
                                        size_t *tlen,
                                        uint32_t *lifetime );

Robert Cragie's avatar
Robert Cragie committed
1188 1189
#if defined(MBEDTLS_SSL_EXPORT_KEYS)
/**
1190
 * \brief           Callback type: Export key block and master secret
Robert Cragie's avatar
Robert Cragie committed
1191 1192
 *
 * \note            This is required for certain uses of TLS, e.g. EAP-TLS
1193 1194 1195 1196
 *                  (RFC 5216) and Thread. The key pointers are ephemeral and
 *                  therefore must not be stored. The master secret and keys
 *                  should not be used directly except as an input to a key
 *                  derivation function.
Robert Cragie's avatar
Robert Cragie committed
1197 1198
 *
 * \param p_expkey  Context for the callback
1199 1200 1201
 * \param ms        Pointer to master secret (fixed length: 48 bytes)
 * \param kb        Pointer to key block, see RFC 5246 section 6.3
 *                  (variable length: 2 * maclen + 2 * keylen + 2 * ivlen).
Robert Cragie's avatar
Robert Cragie committed
1202 1203 1204 1205 1206 1207 1208 1209
 * \param maclen    MAC length
 * \param keylen    Key length
 * \param ivlen     IV length
 *
 * \return          0 if successful, or
 *                  a specific MBEDTLS_ERR_XXX code.
 */
typedef int mbedtls_ssl_export_keys_t( void *p_expkey,
1210
                                const unsigned char *ms,
Robert Cragie's avatar
Robert Cragie committed
1211 1212 1213 1214 1215
                                const unsigned char *kb,
                                size_t maclen,
                                size_t keylen,
                                size_t ivlen );
#endif /* MBEDTLS_SSL_EXPORT_KEYS */
1216

1217 1218 1219 1220 1221 1222 1223 1224 1225 1226
/**
 * \brief           Callback type: parse and load session ticket
 *
 * \note            This describes what a callback implementation should do.
 *                  This callback should parse a session ticket as generated
 *                  by the corresponding mbedtls_ssl_ticket_write_t function,
 *                  and, if the ticket is authentic and valid, load the
 *                  session.
 *
 * \note            The implementation is allowed to modify the first len
1227 1228
 *                  bytes of the input buffer, eg to use it as a temporary
 *                  area for the decrypted ticket contents.
1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244
 *
 * \param p_ticket  Context for the callback
 * \param session   SSL session to be loaded
 * \param buf       Start of the buffer containing the ticket
 * \param len       Length of the ticket.
 *
 * \return          0 if successful, or
 *                  MBEDTLS_ERR_SSL_INVALID_MAC if not authentic, or
 *                  MBEDTLS_ERR_SSL_SESSION_TICKET_EXPIRED if expired, or
 *                  any other non-zero code for other failures.
 */
typedef int mbedtls_ssl_ticket_parse_t( void *p_ticket,
                                        mbedtls_ssl_session *session,
                                        unsigned char *buf,
                                        size_t len );

1245
#if defined(MBEDTLS_SSL_SESSION_TICKETS) && defined(MBEDTLS_SSL_SRV_C)
1246
/**
1247 1248 1249 1250 1251 1252
 * \brief           Configure SSL session ticket callbacks (server only).
 *                  (Default: none.)
 *
 * \note            On server, session tickets are enabled by providing
 *                  non-NULL callbacks.
 *
1253
 * \note            On client, use \c mbedtls_ssl_conf_session_tickets().
1254 1255 1256 1257 1258 1259 1260 1261 1262 1263
 *
 * \param conf      SSL configuration context
 * \param f_ticket_write    Callback for writing a ticket
 * \param f_ticket_parse    Callback for parsing a ticket
 * \param p_ticket          Context shared by the two callbacks
 */
void mbedtls_ssl_conf_session_tickets_cb( mbedtls_ssl_config *conf,
        mbedtls_ssl_ticket_write_t *f_ticket_write,
        mbedtls_ssl_ticket_parse_t *f_ticket_parse,
        void *p_ticket );
1264
#endif /* MBEDTLS_SSL_SESSION_TICKETS && MBEDTLS_SSL_SRV_C */
1265

Robert Cragie's avatar
Robert Cragie committed
1266 1267 1268 1269 1270
#if defined(MBEDTLS_SSL_EXPORT_KEYS)
/**
 * \brief           Configure key export callback.
 *                  (Default: none.)
 *
1271
 * \note            See \c mbedtls_ssl_export_keys_t.
Robert Cragie's avatar
Robert Cragie committed
1272 1273 1274
 *
 * \param conf      SSL configuration context
 * \param f_export_keys     Callback for exporting keys
1275
 * \param p_export_keys     Context for the callback
Robert Cragie's avatar
Robert Cragie committed
1276 1277 1278 1279 1280 1281
 */
void mbedtls_ssl_conf_export_keys_cb( mbedtls_ssl_config *conf,
        mbedtls_ssl_export_keys_t *f_export_keys,
        void *p_export_keys );
#endif /* MBEDTLS_SSL_EXPORT_KEYS */

1282 1283 1284 1285 1286 1287 1288 1289
/**
 * \brief          Callback type: generate a cookie
 *
 * \param ctx      Context for the callback
 * \param p        Buffer to write to,
 *                 must be updated to point right after the cookie
 * \param end      Pointer to one past the end of the output buffer
 * \param info     Client ID info that was passed to
1290
 *                 \c mbedtls_ssl_set_client_transport_id()
1291 1292 1293 1294 1295
 * \param ilen     Length of info in bytes
 *
 * \return         The callback must return 0 on success,
 *                 or a negative error code.
 */
1296
typedef int mbedtls_ssl_cookie_write_t( void *ctx,
1297 1298 1299 1300 1301 1302 1303 1304 1305 1306
                                unsigned char **p, unsigned char *end,
                                const unsigned char *info, size_t ilen );

/**
 * \brief          Callback type: verify a cookie
 *
 * \param ctx      Context for the callback
 * \param cookie   Cookie to verify
 * \param clen     Length of cookie
 * \param info     Client ID info that was passed to
1307
 *                 \c mbedtls_ssl_set_client_transport_id()
1308 1309 1310 1311 1312
 * \param ilen     Length of info in bytes
 *
 * \return         The callback must return 0 if cookie is valid,
 *                 or a negative error code.
 */
1313
typedef int mbedtls_ssl_cookie_check_t( void *ctx,
1314 1315 1316
                                const unsigned char *cookie, size_t clen,
                                const unsigned char *info, size_t ilen );

1317
#if defined(MBEDTLS_SSL_DTLS_HELLO_VERIFY) && defined(MBEDTLS_SSL_SRV_C)
1318 1319 1320 1321
/**
 * \brief           Register callbacks for DTLS cookies
 *                  (Server only. DTLS only.)
 *