ssl.h 62.7 KB
Newer Older
1 2
/**
 * \file ssl.h
Paul Bakker's avatar
Paul Bakker committed
3
 *
4 5
 * \brief SSL/TLS functions.
 *
6
 *  Copyright (C) 2006-2013, Brainspark B.V.
Paul Bakker's avatar
Paul Bakker committed
7 8
 *
 *  This file is part of PolarSSL (http://www.polarssl.org)
9
 *  Lead Maintainer: Paul Bakker <polarssl_maintainer at polarssl.org>
Paul Bakker's avatar
Paul Bakker committed
10
 *
11
 *  All rights reserved.
Paul Bakker's avatar
Paul Bakker committed
12 13 14 15 16 17 18 19 20 21 22 23 24 25
 *
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation; either version 2 of the License, or
 *  (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License along
 *  with this program; if not, write to the Free Software Foundation, Inc.,
 *  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
26
 */
27 28
#ifndef POLARSSL_SSL_H
#define POLARSSL_SSL_H
29

30
#include "config.h"
31
#include "net.h"
32 33
#include "bignum.h"

34 35 36
#include "ssl_ciphersuites.h"

#if defined(POLARSSL_MD5_C)
37
#include "md5.h"
38 39 40
#endif

#if defined(POLARSSL_SHA1_C)
41
#include "sha1.h"
42 43 44
#endif

#if defined(POLARSSL_SHA256_C)
45
#include "sha256.h"
46 47 48
#endif

#if defined(POLARSSL_SHA512_C)
49
#include "sha512.h"
50
#endif
51

52
// for session tickets
53 54 55
#if defined(POLARSSL_AES_C)
#include "aes.h"
#endif
56

57 58 59
#if defined(POLARSSL_X509_CRT_PARSE_C)
#include "x509_crt.h"
#include "x509_crl.h"
60
#endif
61

62 63 64 65
#if defined(POLARSSL_DHM_C)
#include "dhm.h"
#endif

66 67 68 69
#if defined(POLARSSL_ECDH_C)
#include "ecdh.h"
#endif

70 71 72 73
#if defined(POLARSSL_ZLIB_SUPPORT)
#include "zlib.h"
#endif

74 75 76 77
#if defined(POLARSSL_HAVE_TIME)
#include <time.h>
#endif

78 79 80 81 82 83 84 85
/* For convenience below and in programs */
#if defined(POLARSSL_KEY_EXCHANGE_PSK_ENABLED) ||                           \
    defined(POLARSSL_KEY_EXCHANGE_RSA_PSK_ENABLED) ||                       \
    defined(POLARSSL_KEY_EXCHANGE_DHE_PSK_ENABLED) ||                       \
    defined(POLARSSL_KEY_EXCHANGE_ECDHE_PSK_ENABLED)
#define POLARSSL_KEY_EXCHANGE__SOME__PSK_ENABLED
#endif

86 87 88 89 90 91
#if defined(POLARSSL_KEY_EXCHANGE_ECDHE_RSA_ENABLED) ||                     \
    defined(POLARSSL_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED) ||                   \
    defined(POLARSSL_KEY_EXCHANGE_ECDHE_PSK_ENABLED)
#define POLARSSL_KEY_EXCHANGE__SOME__ECDHE_ENABLED
#endif

92
#if defined(_MSC_VER) && !defined(inline)
93
#define inline _inline
94
#else
95
#if defined(__ARMCC_VERSION) && !defined(inline)
96
#define inline __inline
97
#endif /* __ARMCC_VERSION */
98
#endif /*_MSC_VER */
99

100 101 102
/*
 * SSL Error codes
 */
103 104 105 106
#define POLARSSL_ERR_SSL_FEATURE_UNAVAILABLE               -0x7080  /**< The requested feature is not available. */
#define POLARSSL_ERR_SSL_BAD_INPUT_DATA                    -0x7100  /**< Bad input parameters to function. */
#define POLARSSL_ERR_SSL_INVALID_MAC                       -0x7180  /**< Verification of the message MAC failed. */
#define POLARSSL_ERR_SSL_INVALID_RECORD                    -0x7200  /**< An invalid SSL record was received. */
107
#define POLARSSL_ERR_SSL_CONN_EOF                          -0x7280  /**< The connection indicated an EOF. */
108 109
#define POLARSSL_ERR_SSL_UNKNOWN_CIPHER                    -0x7300  /**< An unknown cipher was received. */
#define POLARSSL_ERR_SSL_NO_CIPHER_CHOSEN                  -0x7380  /**< The server has no ciphersuites in common with the client. */
110
#define POLARSSL_ERR_SSL_NO_RNG                            -0x7400  /**< No RNG was provided to the SSL module. */
111 112 113
#define POLARSSL_ERR_SSL_NO_CLIENT_CERTIFICATE             -0x7480  /**< No client certification received from the client, but required by the authentication mode. */
#define POLARSSL_ERR_SSL_CERTIFICATE_TOO_LARGE             -0x7500  /**< Our own certificate(s) is/are too large to send in an SSL message.*/
#define POLARSSL_ERR_SSL_CERTIFICATE_REQUIRED              -0x7580  /**< The own certificate is not set, but needed by the server. */
114
#define POLARSSL_ERR_SSL_PRIVATE_KEY_REQUIRED              -0x7600  /**< The own private key or pre-shared key is not set, but needed. */
115 116 117 118 119 120 121 122 123 124 125 126
#define POLARSSL_ERR_SSL_CA_CHAIN_REQUIRED                 -0x7680  /**< No CA Chain is set, but required to operate. */
#define POLARSSL_ERR_SSL_UNEXPECTED_MESSAGE                -0x7700  /**< An unexpected message was received from our peer. */
#define POLARSSL_ERR_SSL_FATAL_ALERT_MESSAGE               -0x7780  /**< A fatal alert message was received from our peer. */
#define POLARSSL_ERR_SSL_PEER_VERIFY_FAILED                -0x7800  /**< Verification of our peer failed. */
#define POLARSSL_ERR_SSL_PEER_CLOSE_NOTIFY                 -0x7880  /**< The peer notified us that the connection is going to be closed. */
#define POLARSSL_ERR_SSL_BAD_HS_CLIENT_HELLO               -0x7900  /**< Processing of the ClientHello handshake message failed. */
#define POLARSSL_ERR_SSL_BAD_HS_SERVER_HELLO               -0x7980  /**< Processing of the ServerHello handshake message failed. */
#define POLARSSL_ERR_SSL_BAD_HS_CERTIFICATE                -0x7A00  /**< Processing of the Certificate handshake message failed. */
#define POLARSSL_ERR_SSL_BAD_HS_CERTIFICATE_REQUEST        -0x7A80  /**< Processing of the CertificateRequest handshake message failed. */
#define POLARSSL_ERR_SSL_BAD_HS_SERVER_KEY_EXCHANGE        -0x7B00  /**< Processing of the ServerKeyExchange handshake message failed. */
#define POLARSSL_ERR_SSL_BAD_HS_SERVER_HELLO_DONE          -0x7B80  /**< Processing of the ServerHelloDone handshake message failed. */
#define POLARSSL_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE        -0x7C00  /**< Processing of the ClientKeyExchange handshake message failed. */
127 128
#define POLARSSL_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE_RP     -0x7C80  /**< Processing of the ClientKeyExchange handshake message failed in DHM / ECDH Read Public. */
#define POLARSSL_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE_CS     -0x7D00  /**< Processing of the ClientKeyExchange handshake message failed in DHM / ECDH Calculate Secret. */
129 130 131
#define POLARSSL_ERR_SSL_BAD_HS_CERTIFICATE_VERIFY         -0x7D80  /**< Processing of the CertificateVerify handshake message failed. */
#define POLARSSL_ERR_SSL_BAD_HS_CHANGE_CIPHER_SPEC         -0x7E00  /**< Processing of the ChangeCipherSpec handshake message failed. */
#define POLARSSL_ERR_SSL_BAD_HS_FINISHED                   -0x7E80  /**< Processing of the Finished handshake message failed. */
132
#define POLARSSL_ERR_SSL_MALLOC_FAILED                     -0x7F00  /**< Memory allocation failed */
133 134
#define POLARSSL_ERR_SSL_HW_ACCEL_FAILED                   -0x7F80  /**< Hardware acceleration function returned with error */
#define POLARSSL_ERR_SSL_HW_ACCEL_FALLTHROUGH              -0x6F80  /**< Hardware acceleration function skipped / left alone data */
135
#define POLARSSL_ERR_SSL_COMPRESSION_FAILED                -0x6F00  /**< Processing of the compression / decompression failed */
136
#define POLARSSL_ERR_SSL_BAD_HS_PROTOCOL_VERSION           -0x6E80  /**< Handshake protocol not within min/max boundaries */
137
#define POLARSSL_ERR_SSL_BAD_HS_NEW_SESSION_TICKET         -0x6E00  /**< Processing of the NewSessionTicket handshake message failed. */
138
#define POLARSSL_ERR_SSL_SESSION_TICKET_EXPIRED            -0x6D80  /**< Session ticket has expired. */
139
#define POLARSSL_ERR_SSL_PK_TYPE_MISMATCH                  -0x6D00  /**< Public key type mismatch (eg, asked for RSA key exchange and presented EC key) */
Paul Bakker's avatar
Paul Bakker committed
140
#define POLARSSL_ERR_SSL_UNKNOWN_IDENTITY                  -0x6C80  /**< Unkown identity received (eg, PSK identity) */
141
#define POLARSSL_ERR_SSL_INTERNAL_ERROR                    -0x6C00  /**< Internal error (eg, unexpected failure in lower-level module) */
142
#define POLARSSL_ERR_SSL_COUNTER_WRAPPING                  -0x6B80  /**< A counter would wrap (eg, too many messages exchanged). */
143 144 145 146 147 148 149 150

/*
 * Various constants
 */
#define SSL_MAJOR_VERSION_3             3
#define SSL_MINOR_VERSION_0             0   /*!< SSL v3.0 */
#define SSL_MINOR_VERSION_1             1   /*!< TLS v1.0 */
#define SSL_MINOR_VERSION_2             2   /*!< TLS v1.1 */
151
#define SSL_MINOR_VERSION_3             3   /*!< TLS v1.2 */
152

153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190
/* Determine minimum supported version */
#define SSL_MIN_MAJOR_VERSION           SSL_MAJOR_VERSION_3

#if defined(POLARSSL_SSL_PROTO_SSL3)
#define SSL_MIN_MINOR_VERSION           SSL_MINOR_VERSION_0
#else
#if defined(POLARSSL_SSL_PROTO_TLS1)
#define SSL_MIN_MINOR_VERSION           SSL_MINOR_VERSION_1
#else
#if defined(POLARSSL_SSL_PROTO_TLS1_1)
#define SSL_MIN_MINOR_VERSION           SSL_MINOR_VERSION_2
#else
#if defined(POLARSSL_SSL_PROTO_TLS1_2)
#define SSL_MIN_MINOR_VERSION           SSL_MINOR_VERSION_3
#endif
#endif
#endif
#endif

/* Determine maximum supported version */
#define SSL_MAX_MAJOR_VERSION           SSL_MAJOR_VERSION_3

#if defined(POLARSSL_SSL_PROTO_TLS1_2)
#define SSL_MAX_MINOR_VERSION           SSL_MINOR_VERSION_3
#else
#if defined(POLARSSL_SSL_PROTO_TLS1_1)
#define SSL_MAX_MINOR_VERSION           SSL_MINOR_VERSION_2
#else
#if defined(POLARSSL_SSL_PROTO_TLS1)
#define SSL_MAX_MINOR_VERSION           SSL_MINOR_VERSION_1
#else
#if defined(POLARSSL_SSL_PROTO_SSL3)
#define SSL_MAX_MINOR_VERSION           SSL_MINOR_VERSION_0
#endif
#endif
#endif
#endif

191
/* RFC 6066 section 4, see also mfl_code_to_length in ssl_tls.c
Manuel Pégourié-Gonnard's avatar
Manuel Pégourié-Gonnard committed
192
 * NONE must be zero so that memset()ing structure to zero works */
193 194 195 196 197
#define SSL_MAX_FRAG_LEN_NONE           0   /*!< don't use this extension   */
#define SSL_MAX_FRAG_LEN_512            1   /*!< MaxFragmentLength 2^9      */
#define SSL_MAX_FRAG_LEN_1024           2   /*!< MaxFragmentLength 2^10     */
#define SSL_MAX_FRAG_LEN_2048           3   /*!< MaxFragmentLength 2^11     */
#define SSL_MAX_FRAG_LEN_4096           4   /*!< MaxFragmentLength 2^12     */
198
#define SSL_MAX_FRAG_LEN_INVALID        5   /*!< first invalid value        */
199

200 201 202
#define SSL_IS_CLIENT                   0
#define SSL_IS_SERVER                   1
#define SSL_COMPRESS_NULL               0
203
#define SSL_COMPRESS_DEFLATE            1
204 205 206 207 208

#define SSL_VERIFY_NONE                 0
#define SSL_VERIFY_OPTIONAL             1
#define SSL_VERIFY_REQUIRED             2

209
#define SSL_INITIAL_HANDSHAKE           0
210 211
#define SSL_RENEGOTIATION               1   /* In progress */
#define SSL_RENEGOTIATION_DONE          2   /* Done */
212
#define SSL_RENEGOTIATION_PENDING       3   /* Requested (server only) */
213 214 215 216

#define SSL_LEGACY_RENEGOTIATION        0
#define SSL_SECURE_RENEGOTIATION        1

217 218
#define SSL_RENEGOTIATION_DISABLED      0
#define SSL_RENEGOTIATION_ENABLED       1
219

220 221 222
#define SSL_LEGACY_NO_RENEGOTIATION     0
#define SSL_LEGACY_ALLOW_RENEGOTIATION  1
#define SSL_LEGACY_BREAK_HANDSHAKE      2
223

224 225
#define SSL_TRUNC_HMAC_DISABLED         0
#define SSL_TRUNC_HMAC_ENABLED          1
226
#define SSL_TRUNCATED_HMAC_LEN          10  /* 80 bits, rfc 6066 section 7 */
227

228 229 230
#define SSL_SESSION_TICKETS_DISABLED     0
#define SSL_SESSION_TICKETS_ENABLED      1

231 232 233 234
#if !defined(POLARSSL_CONFIG_OPTIONS)
#define SSL_DEFAULT_TICKET_LIFETIME     86400 /**< Lifetime of session tickets (if enabled) */
#endif /* !POLARSSL_CONFIG_OPTIONS */

235 236 237 238 239 240 241 242 243 244
/*
 * Size of the input / output buffer.
 * 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
 * both sides of the connection and have it reduced at both sides!
 */
#if !defined(POLARSSL_CONFIG_OPTIONS)
#define SSL_MAX_CONTENT_LEN         16384   /**< Size of the input / output buffer */
#endif /* !POLARSSL_CONFIG_OPTIONS */
245 246

/*
247 248
 * Allow an extra 301 bytes for the record header
 * and encryption overhead: counter (8) + header (5) + MAC (32) + padding (256)
249 250
 * and allow for a maximum of 1024 of compression expansion if
 * enabled.
251
 */
252 253 254 255 256 257
#if defined(POLARSSL_ZLIB_SUPPORT)
#define SSL_COMPRESSION_ADD          1024
#else
#define SSL_COMPRESSION_ADD             0
#endif

258
#define SSL_BUFFER_LEN (SSL_MAX_CONTENT_LEN + SSL_COMPRESSION_ADD + 301)
259

260
#define SSL_EMPTY_RENEGOTIATION_INFO    0xFF   /**< renegotiation info ext */
261

262 263
/*
 * Supported Signature and Hash algorithms (For TLS 1.2)
264
 * RFC 5246 section 7.4.1.4.1
265 266 267 268 269 270 271 272 273
 */
#define SSL_HASH_NONE                0
#define SSL_HASH_MD5                 1
#define SSL_HASH_SHA1                2
#define SSL_HASH_SHA224              3
#define SSL_HASH_SHA256              4
#define SSL_HASH_SHA384              5
#define SSL_HASH_SHA512              6

274
#define SSL_SIG_ANON                 0
275
#define SSL_SIG_RSA                  1
276
#define SSL_SIG_ECDSA                3
277

278 279
/*
 * Client Certificate Types
280
 * RFC 5246 section 7.4.4 plus RFC 4492 section 5.5
281 282
 */
#define SSL_CERT_TYPE_RSA_SIGN       1
283
#define SSL_CERT_TYPE_ECDSA_SIGN    64
284

285 286 287 288 289 290 291 292
/*
 * Message, alert and handshake types
 */
#define SSL_MSG_CHANGE_CIPHER_SPEC     20
#define SSL_MSG_ALERT                  21
#define SSL_MSG_HANDSHAKE              22
#define SSL_MSG_APPLICATION_DATA       23

Paul Bakker's avatar
Paul Bakker committed
293 294 295
#define SSL_ALERT_LEVEL_WARNING         1
#define SSL_ALERT_LEVEL_FATAL           2

296 297 298 299 300 301
#define SSL_ALERT_MSG_CLOSE_NOTIFY           0  /* 0x00 */
#define SSL_ALERT_MSG_UNEXPECTED_MESSAGE    10  /* 0x0A */
#define SSL_ALERT_MSG_BAD_RECORD_MAC        20  /* 0x14 */
#define SSL_ALERT_MSG_DECRYPTION_FAILED     21  /* 0x15 */
#define SSL_ALERT_MSG_RECORD_OVERFLOW       22  /* 0x16 */
#define SSL_ALERT_MSG_DECOMPRESSION_FAILURE 30  /* 0x1E */
302
#define SSL_ALERT_MSG_HANDSHAKE_FAILURE     40  /* 0x28 */
303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319
#define SSL_ALERT_MSG_NO_CERT               41  /* 0x29 */
#define SSL_ALERT_MSG_BAD_CERT              42  /* 0x2A */
#define SSL_ALERT_MSG_UNSUPPORTED_CERT      43  /* 0x2B */
#define SSL_ALERT_MSG_CERT_REVOKED          44  /* 0x2C */
#define SSL_ALERT_MSG_CERT_EXPIRED          45  /* 0x2D */
#define SSL_ALERT_MSG_CERT_UNKNOWN          46  /* 0x2E */
#define SSL_ALERT_MSG_ILLEGAL_PARAMETER     47  /* 0x2F */
#define SSL_ALERT_MSG_UNKNOWN_CA            48  /* 0x30 */
#define SSL_ALERT_MSG_ACCESS_DENIED         49  /* 0x31 */
#define SSL_ALERT_MSG_DECODE_ERROR          50  /* 0x32 */
#define SSL_ALERT_MSG_DECRYPT_ERROR         51  /* 0x33 */
#define SSL_ALERT_MSG_EXPORT_RESTRICTION    60  /* 0x3C */
#define SSL_ALERT_MSG_PROTOCOL_VERSION      70  /* 0x46 */
#define SSL_ALERT_MSG_INSUFFICIENT_SECURITY 71  /* 0x47 */
#define SSL_ALERT_MSG_INTERNAL_ERROR        80  /* 0x50 */
#define SSL_ALERT_MSG_USER_CANCELED         90  /* 0x5A */
#define SSL_ALERT_MSG_NO_RENEGOTIATION     100  /* 0x64 */
320
#define SSL_ALERT_MSG_UNSUPPORTED_EXT      110  /* 0x6E */
321
#define SSL_ALERT_MSG_UNRECOGNIZED_NAME    112  /* 0x70 */
322
#define SSL_ALERT_MSG_UNKNOWN_PSK_IDENTITY 115  /* 0x73 */
323 324 325 326

#define SSL_HS_HELLO_REQUEST            0
#define SSL_HS_CLIENT_HELLO             1
#define SSL_HS_SERVER_HELLO             2
327
#define SSL_HS_NEW_SESSION_TICKET       4
328 329 330 331 332 333 334 335 336 337 338
#define SSL_HS_CERTIFICATE             11
#define SSL_HS_SERVER_KEY_EXCHANGE     12
#define SSL_HS_CERTIFICATE_REQUEST     13
#define SSL_HS_SERVER_HELLO_DONE       14
#define SSL_HS_CERTIFICATE_VERIFY      15
#define SSL_HS_CLIENT_KEY_EXCHANGE     16
#define SSL_HS_FINISHED                20

/*
 * TLS extensions
 */
339 340 341
#define TLS_EXT_SERVERNAME                   0
#define TLS_EXT_SERVERNAME_HOSTNAME          0

342 343
#define TLS_EXT_MAX_FRAGMENT_LENGTH          1

344 345
#define TLS_EXT_TRUNCATED_HMAC               4

346 347
#define TLS_EXT_SUPPORTED_ELLIPTIC_CURVES   10
#define TLS_EXT_SUPPORTED_POINT_FORMATS     11
348

349
#define TLS_EXT_SIG_ALG                     13
350

351 352
#define TLS_EXT_SESSION_TICKET              35

353
#define TLS_EXT_RENEGOTIATION_INFO      0xFF01
354

355 356 357 358 359 360 361
/*
 * TLS extension flags (for extensions with outgoing ServerHello content
 * that need it (e.g. for RENEGOTIATION_INFO the server already knows because
 * of state of the renegotiation flag, so no indicator is required)
 */
#define TLS_EXT_SUPPORTED_POINT_FORMATS_PRESENT (1 << 0)

362 363 364 365 366 367 368 369 370
/*
 * Size defines
 */
#if !defined(POLARSSL_MPI_MAX_SIZE)
#define POLARSSL_PREMASTER_SIZE             512
#else
#define POLARSSL_PREMASTER_SIZE             POLARSSL_MPI_MAX_SIZE
#endif

371 372 373 374
#ifdef __cplusplus
extern "C" {
#endif

375 376 377 378 379 380 381 382 383
/*
 * Generic function pointers for allowing external RSA private key
 * implementations.
 */
typedef int (*rsa_decrypt_func)( void *ctx, int mode, size_t *olen,
                        const unsigned char *input, unsigned char *output,
                        size_t output_max_len ); 
typedef int (*rsa_sign_func)( void *ctx,
                     int (*f_rng)(void *, unsigned char *, size_t), void *p_rng,
384
                     int mode, md_type_t md_alg, unsigned int hashlen,
385 386 387
                     const unsigned char *hash, unsigned char *sig );
typedef size_t (*rsa_key_len_func)( void *ctx );

388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407
/*
 * SSL state machine
 */
typedef enum
{
    SSL_HELLO_REQUEST,
    SSL_CLIENT_HELLO,
    SSL_SERVER_HELLO,
    SSL_SERVER_CERTIFICATE,
    SSL_SERVER_KEY_EXCHANGE,
    SSL_CERTIFICATE_REQUEST,
    SSL_SERVER_HELLO_DONE,
    SSL_CLIENT_CERTIFICATE,
    SSL_CLIENT_KEY_EXCHANGE,
    SSL_CERTIFICATE_VERIFY,
    SSL_CLIENT_CHANGE_CIPHER_SPEC,
    SSL_CLIENT_FINISHED,
    SSL_SERVER_CHANGE_CIPHER_SPEC,
    SSL_SERVER_FINISHED,
    SSL_FLUSH_BUFFERS,
408
    SSL_HANDSHAKE_WRAPUP,
409 410
    SSL_HANDSHAKE_OVER,
    SSL_SERVER_NEW_SESSION_TICKET,
411 412 413 414 415
}
ssl_states;

typedef struct _ssl_session ssl_session;
typedef struct _ssl_context ssl_context;
416 417
typedef struct _ssl_transform ssl_transform;
typedef struct _ssl_handshake_params ssl_handshake_params;
418
#if defined(POLARSSL_SSL_SESSION_TICKETS)
419
typedef struct _ssl_ticket_keys ssl_ticket_keys;
420
#endif
421 422 423
#if defined(POLARSSL_X509_CRT_PARSE_C)
typedef struct _ssl_key_cert ssl_key_cert;
#endif
424 425

/*
426
 * This structure is used for storing current session data.
427 428 429
 */
struct _ssl_session
{
430
#if defined(POLARSSL_HAVE_TIME)
431
    time_t start;               /*!< starting time      */
432
#endif
433
    int ciphersuite;            /*!< chosen ciphersuite */
434
    int compression;            /*!< chosen compression */
435
    size_t length;              /*!< session id length  */
436 437
    unsigned char id[32];       /*!< session identifier */
    unsigned char master[48];   /*!< the master secret  */
438

439
#if defined(POLARSSL_X509_CRT_PARSE_C)
440
    x509_crt *peer_cert;        /*!< peer X.509 cert chain */
441
#endif /* POLARSSL_X509_CRT_PARSE_C */
442
    int verify_result;          /*!<  verification result     */
443

444
#if defined(POLARSSL_SSL_SESSION_TICKETS)
445 446
    unsigned char *ticket;      /*!< RFC 5077 session ticket */
    size_t ticket_len;          /*!< session ticket length   */
447
    uint32_t ticket_lifetime;   /*!< ticket lifetime hint    */
448
#endif /* POLARSSL_SSL_SESSION_TICKETS */
449

450
#if defined(POLARSSL_SSL_MAX_FRAGMENT_LENGTH)
451
    unsigned char mfl_code;     /*!< MaxFragmentLength negotiated by peer */
452 453
#endif /* POLARSSL_SSL_MAX_FRAGMENT_LENGTH */

454
#if defined(POLARSSL_SSL_TRUNCATED_HMAC)
455
    int trunc_hmac;             /*!< flag for truncated hmac activation   */
456
#endif /* POLARSSL_SSL_TRUNCATED_HMAC */
457 458
};

459 460 461 462 463 464 465 466 467
/*
 * This structure contains a full set of runtime transform parameters
 * either in negotiation or active.
 */
struct _ssl_transform
{
    /*
     * Session specific crypto layer
     */
468 469
    const ssl_ciphersuite_t *ciphersuite_info;
                                        /*!<  Chosen cipersuite_info  */
470 471 472 473 474 475 476 477 478
    unsigned int keylen;                /*!<  symmetric key length    */
    size_t minlen;                      /*!<  min. ciphertext length  */
    size_t ivlen;                       /*!<  IV length               */
    size_t fixed_ivlen;                 /*!<  Fixed part of IV (AEAD) */
    size_t maclen;                      /*!<  MAC length              */

    unsigned char iv_enc[16];           /*!<  IV (encryption)         */
    unsigned char iv_dec[16];           /*!<  IV (decryption)         */

479
#if defined(POLARSSL_SSL_PROTO_SSL3)
480
    /* Needed only for SSL v3.0 secret */
481 482
    unsigned char mac_enc[48];          /*!<  SSL v3.0 secret (enc)   */
    unsigned char mac_dec[48];          /*!<  SSL v3.0 secret (dec)   */
483
#endif /* POLARSSL_SSL_PROTO_SSL3 */
484 485 486

    md_context_t md_ctx_enc;            /*!<  MAC (encryption)        */
    md_context_t md_ctx_dec;            /*!<  MAC (decryption)        */
487

488 489 490
    cipher_context_t cipher_ctx_enc;    /*!<  encryption context      */
    cipher_context_t cipher_ctx_dec;    /*!<  decryption context      */

491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507
    /*
     * Session specific compression layer
     */
#if defined(POLARSSL_ZLIB_SUPPORT)
    z_stream ctx_deflate;               /*!<  compression context     */
    z_stream ctx_inflate;               /*!<  decompression context   */
#endif
};

/*
 * This structure contains the parameters only needed during handshake.
 */
struct _ssl_handshake_params
{
    /*
     * Handshake specific crypto variables
     */
508
    int sig_alg;                        /*!<  Signature algorithm     */
509 510
    int cert_type;                      /*!<  Requested cert type     */
    int verify_sig_alg;                 /*!<  Signature algorithm for verify */
511 512 513
#if defined(POLARSSL_DHM_C)
    dhm_context dhm_ctx;                /*!<  DHM key exchange        */
#endif
514 515 516
#if defined(POLARSSL_ECDH_C)
    ecdh_context ecdh_ctx;              /*!<  ECDH key exchange       */
#endif
517
#if defined(POLARSSL_ECDH_C) || defined(POLARSSL_ECDSA_C)
518
    const ecp_curve_info **curves;      /*!<  Supported elliptic curves */
519
#endif
520
#if defined(POLARSSL_X509_CRT_PARSE_C)
521 522 523 524 525 526 527 528 529 530
    /**
     * Current key/cert or key/cert list.
     * On client: pointer to ssl->key_cert, only the first entry used.
     * On server: starts as a pointer to ssl->key_cert, then becomes
     * a pointer to the chosen key from this list or the SNI list.
     */
    ssl_key_cert *key_cert;
#if defined(POLARSSL_SSL_SERVER_NAME_INDICATION)
    ssl_key_cert *sni_key_cert;         /*!<  key/cert list from SNI  */
#endif
531
#endif
532 533 534 535

    /*
     * Checksum contexts
     */
536 537
#if defined(POLARSSL_SSL_PROTO_SSL3) || defined(POLARSSL_SSL_PROTO_TLS1) || \
    defined(POLARSSL_SSL_PROTO_TLS1_1)
538 539
       md5_context fin_md5;
      sha1_context fin_sha1;
540 541 542
#endif
#if defined(POLARSSL_SSL_PROTO_TLS1_2)
#if defined(POLARSSL_SHA256_C)
543
    sha256_context fin_sha256;
544
#endif
545
#if defined(POLARSSL_SHA512_C)
546
    sha512_context fin_sha512;
547
#endif
548
#endif /* POLARSSL_SSL_PROTO_TLS1_2 */
549

550
    void (*update_checksum)(ssl_context *, const unsigned char *, size_t);
551 552
    void (*calc_verify)(ssl_context *, unsigned char *);
    void (*calc_finished)(ssl_context *, unsigned char *, int);
553 554
    int  (*tls_prf)(const unsigned char *, size_t, const char *,
                    const unsigned char *, size_t,
555 556 557 558 559
                    unsigned char *, size_t);

    size_t pmslen;                      /*!<  premaster length        */

    unsigned char randbytes[64];        /*!<  random bytes            */
560
    unsigned char premaster[POLARSSL_PREMASTER_SIZE];
561
                                        /*!<  premaster secret        */
562 563

    int resume;                         /*!<  session resume indicator*/
564 565
    int max_major_ver;                  /*!< max. major version client*/
    int max_minor_ver;                  /*!< max. minor version client*/
566
    int cli_exts;                       /*!< client extension presence*/
567

568
#if defined(POLARSSL_SSL_SESSION_TICKETS)
569
    int new_session_ticket;             /*!< use NewSessionTicket?    */
570
#endif /* POLARSSL_SSL_SESSION_TICKETS */
571 572
};

573
#if defined(POLARSSL_SSL_SESSION_TICKETS)
574 575 576 577 578 579
/*
 * Parameters needed to secure session tickets
 */
struct _ssl_ticket_keys
{
    unsigned char key_name[16];     /*!< name to quickly discard bad tickets */
580 581
    aes_context enc;                /*!< encryption context                  */
    aes_context dec;                /*!< decryption context                  */
582
    unsigned char mac_key[16];      /*!< authentication key                  */
583
};
584
#endif /* POLARSSL_SSL_SESSION_TICKETS */
585

586 587 588 589 590 591 592 593 594 595 596 597 598
#if defined(POLARSSL_X509_CRT_PARSE_C)
/*
 * List of certificate + private key pairs
 */
struct _ssl_key_cert
{
    x509_crt *cert;                 /*!< cert                       */
    pk_context *key;                /*!< private key                */
    int key_own_alloc;              /*!< did we allocate key?       */
    ssl_key_cert *next;             /*!< next key/cert pair         */
};
#endif /* POLARSSL_X509_CRT_PARSE_C */

599 600 601 602 603 604
struct _ssl_context
{
    /*
     * Miscellaneous
     */
    int state;                  /*!< SSL handshake: current state     */
605
    int renegotiation;          /*!< Initial or renegotiation         */
606 607 608 609

    int major_ver;              /*!< equal to  SSL_MAJOR_VERSION_3    */
    int minor_ver;              /*!< either 0 (SSL3) or 1 (TLS1.0)    */

610 611 612 613
    int max_major_ver;          /*!< max. major version used          */
    int max_minor_ver;          /*!< max. minor version used          */
    int min_major_ver;          /*!< min. major version used          */
    int min_minor_ver;          /*!< min. minor version used          */
614 615

    /*
616
     * Callbacks (RNG, debug, I/O, verification)
617
     */
618
    int  (*f_rng)(void *, unsigned char *, size_t);
619
    void (*f_dbg)(void *, int, const char *);
620
    int (*f_recv)(void *, unsigned char *, size_t);
621
    int (*f_send)(void *, const unsigned char *, size_t);
622 623
    int (*f_get_cache)(void *, ssl_session *);
    int (*f_set_cache)(void *, const ssl_session *);
624 625 626 627 628

    void *p_rng;                /*!< context for the RNG function     */
    void *p_dbg;                /*!< context for the debug function   */
    void *p_recv;               /*!< context for reading operations   */
    void *p_send;               /*!< context for writing operations   */
629 630
    void *p_get_cache;          /*!< context for cache retrieval      */
    void *p_set_cache;          /*!< context for cache store          */
631
    void *p_hw_data;            /*!< context for HW acceleration      */
632

633 634 635 636 637
#if defined(POLARSSL_SSL_SERVER_NAME_INDICATION)
    int (*f_sni)(void *, ssl_context *, const unsigned char *, size_t);
    void *p_sni;                /*!< context for SNI extension        */
#endif

638
#if defined(POLARSSL_X509_CRT_PARSE_C)
639
    int (*f_vrfy)(void *, x509_crt *, int, int *);
640 641 642
    void *p_vrfy;               /*!< context for verification         */
#endif

643
#if defined(POLARSSL_KEY_EXCHANGE__SOME__PSK_ENABLED)
Paul Bakker's avatar
Paul Bakker committed
644 645 646 647
    int (*f_psk)(void *, ssl_context *, const unsigned char *, size_t);
    void *p_psk;               /*!< context for PSK retrieval         */
#endif

648 649 650
    /*
     * Session layer
     */
651 652 653 654
    ssl_session *session_in;            /*!<  current session data (in)   */
    ssl_session *session_out;           /*!<  current session data (out)  */
    ssl_session *session;               /*!<  negotiated session data     */
    ssl_session *session_negotiate;     /*!<  session data in negotiation */
655

656 657 658 659 660 661 662 663 664 665 666
    ssl_handshake_params *handshake;    /*!<  params required only during
                                              the handshake process        */

    /*
     * Record layer transformations
     */
    ssl_transform *transform_in;        /*!<  current transform params (in)   */
    ssl_transform *transform_out;       /*!<  current transform params (in)   */
    ssl_transform *transform;           /*!<  negotiated transform params     */
    ssl_transform *transform_negotiate; /*!<  transform params in negotiation */

667 668 669 670 671
    /*
     * Record layer (incoming data)
     */
    unsigned char *in_ctr;      /*!< 64-bit incoming message counter  */
    unsigned char *in_hdr;      /*!< 5-byte record header (in_ctr+8)  */
672 673
    unsigned char *in_iv;       /*!< ivlen-byte IV (in_hdr+5)         */
    unsigned char *in_msg;      /*!< message contents (in_iv+ivlen)   */
674 675 676
    unsigned char *in_offt;     /*!< read offset in application data  */

    int in_msgtype;             /*!< record header: message type      */
677 678
    size_t in_msglen;           /*!< record header: message length    */
    size_t in_left;             /*!< amount of data read so far       */
679

680
    size_t in_hslen;            /*!< current handshake message length */
681
    int nb_zero;                /*!< # of 0-length encrypted messages */
682
    int record_read;            /*!< record is already present        */
683 684 685 686 687 688

    /*
     * Record layer (outgoing data)
     */
    unsigned char *out_ctr;     /*!< 64-bit outgoing message counter  */
    unsigned char *out_hdr;     /*!< 5-byte record header (out_ctr+8) */
689 690
    unsigned char *out_iv;      /*!< ivlen-byte IV (out_hdr+5)        */
    unsigned char *out_msg;     /*!< message contents (out_iv+ivlen)  */
691 692

    int out_msgtype;            /*!< record header: message type      */
693 694
    size_t out_msglen;          /*!< record header: message length    */
    size_t out_left;            /*!< amount of data not yet written   */
695

696 697 698
#if defined(POLARSSL_ZLIB_SUPPORT)
    unsigned char *compress_buf;        /*!<  zlib data buffer        */
#endif
699
#if defined(POLARSSL_SSL_MAX_FRAGMENT_LENGTH)
700
    unsigned char mfl_code;     /*!< MaxFragmentLength chosen by us   */
701
#endif /* POLARSSL_SSL_MAX_FRAGMENT_LENGTH */
702

703 704 705
    /*
     * PKI layer
     */
706
#if defined(POLARSSL_X509_CRT_PARSE_C)
707 708 709 710 711
    ssl_key_cert *key_cert;             /*!<  own certificate(s)/key(s) */

    x509_crt *ca_chain;                 /*!<  own trusted CA chain      */
    x509_crl *ca_crl;                   /*!<  trusted CA CRLs           */
    const char *peer_cn;                /*!<  expected peer CN          */
712
#endif /* POLARSSL_X509_CRT_PARSE_C */
713

714 715 716
    /*
     * Support for generating and checking session tickets
     */
717
#if defined(POLARSSL_SSL_SESSION_TICKETS)
718
    ssl_ticket_keys *ticket_keys;       /*!<  keys for ticket encryption */
719
#endif /* POLARSSL_SSL_SESSION_TICKETS */
720

721 722 723
    /*
     * User settings
     */
724 725 726 727
    int endpoint;                       /*!<  0: client, 1: server    */
    int authmode;                       /*!<  verification mode       */
    int client_auth;                    /*!<  flag for client auth.   */
    int verify_result;                  /*!<  verification result     */
728 729
    int disable_renegotiation;          /*!<  enable/disable renegotiation   */
    int allow_legacy_renegotiation;     /*!<  allow legacy renegotiation     */
730
    const int *ciphersuite_list[4];     /*!<  allowed ciphersuites / version */
731
#if defined(POLARSSL_SSL_SET_CURVES)
732
    const ecp_group_id *curve_list;     /*!<  allowed curves                 */
733
#endif
734
#if defined(POLARSSL_SSL_TRUNCATED_HMAC)
735
    int trunc_hmac;                     /*!<  negotiate truncated hmac?      */
736
#endif
737
#if defined(POLARSSL_SSL_SESSION_TICKETS)
738
    int session_tickets;                /*!<  use session tickets?    */
739 740
    int ticket_lifetime;                /*!<  session ticket lifetime */
#endif
741

742 743 744
#if defined(POLARSSL_DHM_C)
    mpi dhm_P;                          /*!<  prime modulus for DHM   */
    mpi dhm_G;                          /*!<  generator for DHM       */
745 746
#endif

747
#if defined(POLARSSL_KEY_EXCHANGE__SOME__PSK_ENABLED)
748 749 750
    /*
     * PSK values
     */
Paul Bakker's avatar
Paul Bakker committed
751
    unsigned char *psk;
752
    size_t         psk_len;
Paul Bakker's avatar
Paul Bakker committed
753
    unsigned char *psk_identity;
754 755 756
    size_t         psk_identity_len;
#endif

757
#if defined(POLARSSL_SSL_SERVER_NAME_INDICATION)
758
    /*
759
     * SNI extension
760 761
     */
    unsigned char *hostname;
762
    size_t         hostname_len;
763
#endif
764 765 766 767 768 769 770 771 772

    /*
     * Secure renegotiation
     */
    int secure_renegotiation;           /*!<  does peer support legacy or
                                              secure renegotiation           */
    size_t verify_data_len;             /*!<  length of verify data stored   */
    char own_verify_data[36];           /*!<  previous handshake verify data */
    char peer_verify_data[36];          /*!<  previous handshake verify data */
773 774
};

775
#if defined(POLARSSL_SSL_HW_RECORD_ACCEL)
776 777 778 779

#define SSL_CHANNEL_OUTBOUND    0
#define SSL_CHANNEL_INBOUND     1

780 781
extern int (*ssl_hw_record_init)(ssl_context *ssl,
                const unsigned char *key_enc, const unsigned char *key_dec,
782
                size_t keylen,
783
                const unsigned char *iv_enc,  const unsigned char *iv_dec,
784 785 786 787
                size_t ivlen,
                const unsigned char *mac_enc, const unsigned char *mac_dec,
                size_t maclen);
extern int (*ssl_hw_record_activate)(ssl_context *ssl, int direction);
788 789 790 791 792 793
extern int (*ssl_hw_record_reset)(ssl_context *ssl);
extern int (*ssl_hw_record_write)(ssl_context *ssl);
extern int (*ssl_hw_record_read)(ssl_context *ssl);
extern int (*ssl_hw_record_finish)(ssl_context *ssl);
#endif

794
/**
795
 * \brief Returns the list of ciphersuites supported by the SSL/TLS module.
796
 *
797 798
 * \return              a statically allocated array of ciphersuites, the last
 *                      entry is 0.
799
 */
800
const int *ssl_list_ciphersuites( void );
801 802

/**
803 804
 * \brief               Return the name of the ciphersuite associated with the given
 *                      ID
805
 *
806
 * \param ciphersuite_id SSL ciphersuite ID
807
 *
808
 * \return              a string containing the ciphersuite name
809
 */
810 811 812 813 814 815 816 817 818 819 820
const char *ssl_get_ciphersuite_name( const int ciphersuite_id );

/**
 * \brief               Return the ID of the ciphersuite associated with the given
 *                      name
 *
 * \param ciphersuite_name SSL ciphersuite name
 *
 * \return              the ID with the ciphersuite or 0 if not found
 */
int ssl_get_ciphersuite_id( const char *ciphersuite_name );
821

822 823
/**
 * \brief          Initialize an SSL context
Paul Bakker's avatar
Paul Bakker committed
824
 *                 (An individual SSL context is not thread-safe)
825 826 827
 *
 * \param ssl      SSL context
 *
828 829
 * \return         0 if successful, or POLARSSL_ERR_SSL_MALLOC_FAILED if
 *                 memory allocation failed
830 831 832
 */
int ssl_init( ssl_context *ssl );

833 834 835 836 837 838
/**
 * \brief          Reset an already initialized SSL context for re-use
 *                 while retaining application-set variables, function
 *                 pointers and data.
 *
 * \param ssl      SSL context
839 840
 * \return         0 if successful, or POLASSL_ERR_SSL_MALLOC_FAILED,
                   POLARSSL_ERR_SSL_HW_ACCEL_FAILED or
841
 *                 POLARSSL_ERR_SSL_COMPRESSION_FAILED
842
 */
843
int ssl_session_reset( ssl_context *ssl );
844

845 846 847 848 849
/**
 * \brief          Set the current endpoint type
 *
 * \param ssl      SSL context
 * \param endpoint must be SSL_IS_CLIENT or SSL_IS_SERVER
850 851 852
 *
 * \note           This function should be called right after ssl_init() since
 *                 some other ssl_set_foo() functions depend on it.
853 854 855 856 857 858 859
 */
void ssl_set_endpoint( ssl_context *ssl, int endpoint );

/**
 * \brief          Set the certificate verification mode
 *
 * \param ssl      SSL context
860
 * \param authmode can be:
861 862 863 864 865 866 867 868 869 870 871
 *
 *  SSL_VERIFY_NONE:      peer certificate is not checked (default),
 *                        this is insecure and SHOULD be avoided.
 *
 *  SSL_VERIFY_OPTIONAL:  peer certificate is checked, however the
 *                        handshake continues even if verification failed;
 *                        ssl_get_verify_result() can be called after the
 *                        handshake is complete.
 *
 *  SSL_VERIFY_REQUIRED:  peer *must* present a valid certificate,
 *                        handshake is aborted if verification failed.
872 873 874 875 876 877
 *
 * \note On client, SSL_VERIFY_REQUIRED is the recommended mode.
 * With SSL_VERIFY_OPTIONAL, the user needs to call ssl_get_verify_result() at
 * 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.
878 879 880
 */
void ssl_set_authmode( ssl_context *ssl, int authmode );

881
#if defined(POLARSSL_X509_CRT_PARSE_C)
882 883 884
/**
 * \brief          Set the verification callback (Optional).
 *
885 886 887
 *                 If set, the verify callback is called for each
 *                 certificate in the chain. For implementation
 *                 information, please see \c x509parse_verify()
888 889 890 891 892 893
 *
 * \param ssl      SSL context
 * \param f_vrfy   verification function
 * \param p_vrfy   verification parameter
 */
void ssl_set_verify( ssl_context *ssl,
894
                     int (*f_vrfy)(void *, x509_crt *, int, int *),
895
                     void *p_vrfy );
896
#endif /* POLARSSL_X509_CRT_PARSE_C */
897

898 899 900 901 902 903 904 905
/**
 * \brief          Set the random number generator callback
 *
 * \param ssl      SSL context
 * \param f_rng    RNG function
 * \param p_rng    RNG parameter
 */
void ssl_set_rng( ssl_context *ssl,
906
                  int (*f_rng)(void *, unsigned char *, size_t),
907 908 909 910 911 912 913 914 915 916
                  void *p_rng );

/**
 * \brief          Set the debug callback
 *
 * \param ssl      SSL context
 * \param f_dbg    debug function
 * \param p_dbg    debug parameter
 */
void ssl_set_dbg( ssl_context *ssl,
917
                  void (*f_dbg)(void *, int, const char *),
918 919 920 921 922 923 924 925 926 927 928 929
                  void  *p_dbg );

/**
 * \brief          Set the underlying BIO read and write callbacks
 *
 * \param ssl      SSL context
 * \param f_recv   read callback
 * \param p_recv   read parameter
 * \param f_send   write callback
 * \param p_send   write parameter
 */
void ssl_set_bio( ssl_context *ssl,
930
        int (*f_recv)(void *, unsigned char *, size_t), void *p_recv,
931
        int (*f_send)(void *, const unsigned char *, size_t), void *p_send );
932 933

/**
934 935
 * \brief          Set the session cache callbacks (server-side only)
 *                 If not set, no session resuming is done.
936
 *
937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961
 *                 The session cache has the responsibility to check for stale
 *                 entries based on timeout. See RFC 5246 for recommendations.
 *
 *                 Warning: session.peer_cert is cleared by the SSL/TLS layer on
 *                 connection shutdown, so do not cache the pointer! Either set
 *                 it to NULL or make a full copy of the certificate.
 *
 *                 The get callback is called once during the initial handshake
 *                 to enable session resuming. The get function has the
 *                 following parameters: (void *parameter, ssl_session *session)
 *                 If a valid entry is found, it should fill the master of
 *                 the session object with the cached values and return 0,
 *                 return 1 otherwise. Optionally peer_cert can be set as well
 *                 if it is properly present in cache entry.
 *
 *                 The set callback is called once during the initial handshake
 *                 to enable session resuming after the entire handshake has
 *                 been finished. The set function has the following parameters:
 *                 (void *parameter, const ssl_session *session). The function
 *                 should create a cache entry for future retrieval based on
 *                 the data in the session structure and should keep in mind
 *                 that the ssl_session object presented (and all its referenced
 *                 data) is cleared by the SSL/TLS layer when the connection is
 *                 terminated. It is recommended to add metadata to determine if
 *                 an entry is still valid in the future. Return 0 if
Paul Bakker's avatar
Paul Bakker committed
962
 *                 successfully cached, return 1 otherwise.
963 964 965 966 967 968
 *
 * \param ssl            SSL context
 * \param f_get_cache    session get callback
 * \param p_get_cache    session get parameter
 * \param f_set_cache    session set callback
 * \param p_set_cache    session set parameter
969
 */
970 971 972
void ssl_set_session_cache( ssl_context *ssl,
        int (*f_get_cache)(void *, ssl_session *), void *p_get_cache,
        int (*f_set_cache)(void *, const ssl_session *), void *p_set_cache );
973 974

/**
975 976 977
 * \brief          Request resumption of session (client-side only)
 *                 Session data is copied from presented session structure.
 *
978 979
 * \param ssl      SSL context
 * \param session  session context
980
 *
981 982 983 984 985
 * \return         0 if successful,
 *                 POLARSSL_ERR_SSL_MALLOC_FAILED if memory allocation failed,
 *                 POLARSSL_ERR_SSL_BAD_INPUT_DATA if used server-side or
 *                 arguments are otherwise invalid
 *
986
 * \sa             ssl_get_session()
Paul Bakker's avatar