Rtos API example

Embed: (wiki syntax)

« Back to documentation index

Show/hide line numbers ssl.h Source File

ssl.h

Go to the documentation of this file.
00001 /**
00002  * \file ssl.h
00003  *
00004  * \brief SSL/TLS functions.
00005  *
00006  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
00007  *  SPDX-License-Identifier: Apache-2.0
00008  *
00009  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00010  *  not use this file except in compliance with the License.
00011  *  You may obtain a copy of the License at
00012  *
00013  *  http://www.apache.org/licenses/LICENSE-2.0
00014  *
00015  *  Unless required by applicable law or agreed to in writing, software
00016  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00017  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00018  *  See the License for the specific language governing permissions and
00019  *  limitations under the License.
00020  *
00021  *  This file is part of mbed TLS (https://tls.mbed.org)
00022  */
00023 #ifndef MBEDTLS_SSL_H
00024 #define MBEDTLS_SSL_H
00025 
00026 #if !defined(MBEDTLS_CONFIG_FILE)
00027 #include "config.h"
00028 #else
00029 #include MBEDTLS_CONFIG_FILE
00030 #endif
00031 
00032 #include "bignum.h"
00033 #include "ecp.h"
00034 
00035 #include "ssl_ciphersuites.h"
00036 
00037 #if defined(MBEDTLS_X509_CRT_PARSE_C)
00038 #include "x509_crt.h"
00039 #include "x509_crl.h"
00040 #endif
00041 
00042 #if defined(MBEDTLS_DHM_C)
00043 #include "dhm.h"
00044 #endif
00045 
00046 #if defined(MBEDTLS_ECDH_C)
00047 #include "ecdh.h"
00048 #endif
00049 
00050 #if defined(MBEDTLS_ZLIB_SUPPORT)
00051 #include "zlib.h"
00052 #endif
00053 
00054 #if defined(MBEDTLS_HAVE_TIME)
00055 #include "mbedtls/platform_time.h"
00056 #endif
00057 
00058 /*
00059  * SSL Error codes
00060  */
00061 #define MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE               -0x7080  /**< The requested feature is not available. */
00062 #define MBEDTLS_ERR_SSL_BAD_INPUT_DATA                    -0x7100  /**< Bad input parameters to function. */
00063 #define MBEDTLS_ERR_SSL_INVALID_MAC                       -0x7180  /**< Verification of the message MAC failed. */
00064 #define MBEDTLS_ERR_SSL_INVALID_RECORD                    -0x7200  /**< An invalid SSL record was received. */
00065 #define MBEDTLS_ERR_SSL_CONN_EOF                          -0x7280  /**< The connection indicated an EOF. */
00066 #define MBEDTLS_ERR_SSL_UNKNOWN_CIPHER                    -0x7300  /**< An unknown cipher was received. */
00067 #define MBEDTLS_ERR_SSL_NO_CIPHER_CHOSEN                  -0x7380  /**< The server has no ciphersuites in common with the client. */
00068 #define MBEDTLS_ERR_SSL_NO_RNG                            -0x7400  /**< No RNG was provided to the SSL module. */
00069 #define MBEDTLS_ERR_SSL_NO_CLIENT_CERTIFICATE             -0x7480  /**< No client certification received from the client, but required by the authentication mode. */
00070 #define MBEDTLS_ERR_SSL_CERTIFICATE_TOO_LARGE             -0x7500  /**< Our own certificate(s) is/are too large to send in an SSL message. */
00071 #define MBEDTLS_ERR_SSL_CERTIFICATE_REQUIRED              -0x7580  /**< The own certificate is not set, but needed by the server. */
00072 #define MBEDTLS_ERR_SSL_PRIVATE_KEY_REQUIRED              -0x7600  /**< The own private key or pre-shared key is not set, but needed. */
00073 #define MBEDTLS_ERR_SSL_CA_CHAIN_REQUIRED                 -0x7680  /**< No CA Chain is set, but required to operate. */
00074 #define MBEDTLS_ERR_SSL_UNEXPECTED_MESSAGE                -0x7700  /**< An unexpected message was received from our peer. */
00075 #define MBEDTLS_ERR_SSL_FATAL_ALERT_MESSAGE               -0x7780  /**< A fatal alert message was received from our peer. */
00076 #define MBEDTLS_ERR_SSL_PEER_VERIFY_FAILED                -0x7800  /**< Verification of our peer failed. */
00077 #define MBEDTLS_ERR_SSL_PEER_CLOSE_NOTIFY                 -0x7880  /**< The peer notified us that the connection is going to be closed. */
00078 #define MBEDTLS_ERR_SSL_BAD_HS_CLIENT_HELLO               -0x7900  /**< Processing of the ClientHello handshake message failed. */
00079 #define MBEDTLS_ERR_SSL_BAD_HS_SERVER_HELLO               -0x7980  /**< Processing of the ServerHello handshake message failed. */
00080 #define MBEDTLS_ERR_SSL_BAD_HS_CERTIFICATE                -0x7A00  /**< Processing of the Certificate handshake message failed. */
00081 #define MBEDTLS_ERR_SSL_BAD_HS_CERTIFICATE_REQUEST        -0x7A80  /**< Processing of the CertificateRequest handshake message failed. */
00082 #define MBEDTLS_ERR_SSL_BAD_HS_SERVER_KEY_EXCHANGE        -0x7B00  /**< Processing of the ServerKeyExchange handshake message failed. */
00083 #define MBEDTLS_ERR_SSL_BAD_HS_SERVER_HELLO_DONE          -0x7B80  /**< Processing of the ServerHelloDone handshake message failed. */
00084 #define MBEDTLS_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE        -0x7C00  /**< Processing of the ClientKeyExchange handshake message failed. */
00085 #define MBEDTLS_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE_RP     -0x7C80  /**< Processing of the ClientKeyExchange handshake message failed in DHM / ECDH Read Public. */
00086 #define MBEDTLS_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE_CS     -0x7D00  /**< Processing of the ClientKeyExchange handshake message failed in DHM / ECDH Calculate Secret. */
00087 #define MBEDTLS_ERR_SSL_BAD_HS_CERTIFICATE_VERIFY         -0x7D80  /**< Processing of the CertificateVerify handshake message failed. */
00088 #define MBEDTLS_ERR_SSL_BAD_HS_CHANGE_CIPHER_SPEC         -0x7E00  /**< Processing of the ChangeCipherSpec handshake message failed. */
00089 #define MBEDTLS_ERR_SSL_BAD_HS_FINISHED                   -0x7E80  /**< Processing of the Finished handshake message failed. */
00090 #define MBEDTLS_ERR_SSL_ALLOC_FAILED                      -0x7F00  /**< Memory allocation failed */
00091 #define MBEDTLS_ERR_SSL_HW_ACCEL_FAILED                   -0x7F80  /**< Hardware acceleration function returned with error */
00092 #define MBEDTLS_ERR_SSL_HW_ACCEL_FALLTHROUGH              -0x6F80  /**< Hardware acceleration function skipped / left alone data */
00093 #define MBEDTLS_ERR_SSL_COMPRESSION_FAILED                -0x6F00  /**< Processing of the compression / decompression failed */
00094 #define MBEDTLS_ERR_SSL_BAD_HS_PROTOCOL_VERSION           -0x6E80  /**< Handshake protocol not within min/max boundaries */
00095 #define MBEDTLS_ERR_SSL_BAD_HS_NEW_SESSION_TICKET         -0x6E00  /**< Processing of the NewSessionTicket handshake message failed. */
00096 #define MBEDTLS_ERR_SSL_SESSION_TICKET_EXPIRED            -0x6D80  /**< Session ticket has expired. */
00097 #define MBEDTLS_ERR_SSL_PK_TYPE_MISMATCH                  -0x6D00  /**< Public key type mismatch (eg, asked for RSA key exchange and presented EC key) */
00098 #define MBEDTLS_ERR_SSL_UNKNOWN_IDENTITY                  -0x6C80  /**< Unknown identity received (eg, PSK identity) */
00099 #define MBEDTLS_ERR_SSL_INTERNAL_ERROR                    -0x6C00  /**< Internal error (eg, unexpected failure in lower-level module) */
00100 #define MBEDTLS_ERR_SSL_COUNTER_WRAPPING                  -0x6B80  /**< A counter would wrap (eg, too many messages exchanged). */
00101 #define MBEDTLS_ERR_SSL_WAITING_SERVER_HELLO_RENEGO       -0x6B00  /**< Unexpected message at ServerHello in renegotiation. */
00102 #define MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED             -0x6A80  /**< DTLS client must retry for hello verification */
00103 #define MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL                  -0x6A00  /**< A buffer is too small to receive or write a message */
00104 #define MBEDTLS_ERR_SSL_NO_USABLE_CIPHERSUITE             -0x6980  /**< None of the common ciphersuites is usable (eg, no suitable certificate, see debug messages). */
00105 #define MBEDTLS_ERR_SSL_WANT_READ                         -0x6900  /**< Connection requires a read call. */
00106 #define MBEDTLS_ERR_SSL_WANT_WRITE                        -0x6880  /**< Connection requires a write call. */
00107 #define MBEDTLS_ERR_SSL_TIMEOUT                           -0x6800  /**< The operation timed out. */
00108 #define MBEDTLS_ERR_SSL_CLIENT_RECONNECT                  -0x6780  /**< The client initiated a reconnect from the same port. */
00109 #define MBEDTLS_ERR_SSL_UNEXPECTED_RECORD                 -0x6700  /**< Record header looks valid but is not expected. */
00110 #define MBEDTLS_ERR_SSL_NON_FATAL                         -0x6680  /**< The alert message received indicates a non-fatal error. */
00111 #define MBEDTLS_ERR_SSL_INVALID_VERIFY_HASH               -0x6600  /**< Couldn't set the hash for verifying CertificateVerify */
00112 
00113 /*
00114  * Various constants
00115  */
00116 #define MBEDTLS_SSL_MAJOR_VERSION_3             3
00117 #define MBEDTLS_SSL_MINOR_VERSION_0             0   /*!< SSL v3.0 */
00118 #define MBEDTLS_SSL_MINOR_VERSION_1             1   /*!< TLS v1.0 */
00119 #define MBEDTLS_SSL_MINOR_VERSION_2             2   /*!< TLS v1.1 */
00120 #define MBEDTLS_SSL_MINOR_VERSION_3             3   /*!< TLS v1.2 */
00121 
00122 #define MBEDTLS_SSL_TRANSPORT_STREAM            0   /*!< TLS      */
00123 #define MBEDTLS_SSL_TRANSPORT_DATAGRAM          1   /*!< DTLS     */
00124 
00125 #define MBEDTLS_SSL_MAX_HOST_NAME_LEN           255 /*!< Maximum host name defined in RFC 1035 */
00126 
00127 /* RFC 6066 section 4, see also mfl_code_to_length in ssl_tls.c
00128  * NONE must be zero so that memset()ing structure to zero works */
00129 #define MBEDTLS_SSL_MAX_FRAG_LEN_NONE           0   /*!< don't use this extension   */
00130 #define MBEDTLS_SSL_MAX_FRAG_LEN_512            1   /*!< MaxFragmentLength 2^9      */
00131 #define MBEDTLS_SSL_MAX_FRAG_LEN_1024           2   /*!< MaxFragmentLength 2^10     */
00132 #define MBEDTLS_SSL_MAX_FRAG_LEN_2048           3   /*!< MaxFragmentLength 2^11     */
00133 #define MBEDTLS_SSL_MAX_FRAG_LEN_4096           4   /*!< MaxFragmentLength 2^12     */
00134 #define MBEDTLS_SSL_MAX_FRAG_LEN_INVALID        5   /*!< first invalid value        */
00135 
00136 #define MBEDTLS_SSL_IS_CLIENT                   0
00137 #define MBEDTLS_SSL_IS_SERVER                   1
00138 
00139 #define MBEDTLS_SSL_IS_NOT_FALLBACK             0
00140 #define MBEDTLS_SSL_IS_FALLBACK                 1
00141 
00142 #define MBEDTLS_SSL_EXTENDED_MS_DISABLED        0
00143 #define MBEDTLS_SSL_EXTENDED_MS_ENABLED         1
00144 
00145 #define MBEDTLS_SSL_ETM_DISABLED                0
00146 #define MBEDTLS_SSL_ETM_ENABLED                 1
00147 
00148 #define MBEDTLS_SSL_COMPRESS_NULL               0
00149 #define MBEDTLS_SSL_COMPRESS_DEFLATE            1
00150 
00151 #define MBEDTLS_SSL_VERIFY_NONE                 0
00152 #define MBEDTLS_SSL_VERIFY_OPTIONAL             1
00153 #define MBEDTLS_SSL_VERIFY_REQUIRED             2
00154 #define MBEDTLS_SSL_VERIFY_UNSET                3 /* Used only for sni_authmode */
00155 
00156 #define MBEDTLS_SSL_LEGACY_RENEGOTIATION        0
00157 #define MBEDTLS_SSL_SECURE_RENEGOTIATION        1
00158 
00159 #define MBEDTLS_SSL_RENEGOTIATION_DISABLED      0
00160 #define MBEDTLS_SSL_RENEGOTIATION_ENABLED       1
00161 
00162 #define MBEDTLS_SSL_ANTI_REPLAY_DISABLED        0
00163 #define MBEDTLS_SSL_ANTI_REPLAY_ENABLED         1
00164 
00165 #define MBEDTLS_SSL_RENEGOTIATION_NOT_ENFORCED  -1
00166 #define MBEDTLS_SSL_RENEGO_MAX_RECORDS_DEFAULT  16
00167 
00168 #define MBEDTLS_SSL_LEGACY_NO_RENEGOTIATION     0
00169 #define MBEDTLS_SSL_LEGACY_ALLOW_RENEGOTIATION  1
00170 #define MBEDTLS_SSL_LEGACY_BREAK_HANDSHAKE      2
00171 
00172 #define MBEDTLS_SSL_TRUNC_HMAC_DISABLED         0
00173 #define MBEDTLS_SSL_TRUNC_HMAC_ENABLED          1
00174 #define MBEDTLS_SSL_TRUNCATED_HMAC_LEN          10  /* 80 bits, rfc 6066 section 7 */
00175 
00176 #define MBEDTLS_SSL_SESSION_TICKETS_DISABLED     0
00177 #define MBEDTLS_SSL_SESSION_TICKETS_ENABLED      1
00178 
00179 #define MBEDTLS_SSL_CBC_RECORD_SPLITTING_DISABLED    0
00180 #define MBEDTLS_SSL_CBC_RECORD_SPLITTING_ENABLED     1
00181 
00182 #define MBEDTLS_SSL_ARC4_ENABLED                0
00183 #define MBEDTLS_SSL_ARC4_DISABLED               1
00184 
00185 #define MBEDTLS_SSL_PRESET_DEFAULT              0
00186 #define MBEDTLS_SSL_PRESET_SUITEB               2
00187 
00188 #define MBEDTLS_SSL_CERT_REQ_CA_LIST_ENABLED       1
00189 #define MBEDTLS_SSL_CERT_REQ_CA_LIST_DISABLED      0
00190 
00191 /*
00192  * Default range for DTLS retransmission timer value, in milliseconds.
00193  * RFC 6347 4.2.4.1 says from 1 second to 60 seconds.
00194  */
00195 #define MBEDTLS_SSL_DTLS_TIMEOUT_DFL_MIN    1000
00196 #define MBEDTLS_SSL_DTLS_TIMEOUT_DFL_MAX   60000
00197 
00198 /**
00199  * \name SECTION: Module settings
00200  *
00201  * The configuration options you can set for this module are in this section.
00202  * Either change them in config.h or define them on the compiler command line.
00203  * \{
00204  */
00205 
00206 #if !defined(MBEDTLS_SSL_DEFAULT_TICKET_LIFETIME)
00207 #define MBEDTLS_SSL_DEFAULT_TICKET_LIFETIME     86400 /**< Lifetime of session tickets (if enabled) */
00208 #endif
00209 
00210 /*
00211  * Maxium fragment length in bytes,
00212  * determines the size of each of the two internal I/O buffers.
00213  *
00214  * Note: the RFC defines the default size of SSL / TLS messages. If you
00215  * change the value here, other clients / servers may not be able to
00216  * communicate with you anymore. Only change this value if you control
00217  * both sides of the connection and have it reduced at both sides, or
00218  * if you're using the Max Fragment Length extension and you know all your
00219  * peers are using it too!
00220  */
00221 #if !defined(MBEDTLS_SSL_MAX_CONTENT_LEN)
00222 #define MBEDTLS_SSL_MAX_CONTENT_LEN         16384   /**< Size of the input / output buffer */
00223 #endif
00224 
00225 /* \} name SECTION: Module settings */
00226 
00227 /*
00228  * Length of the verify data for secure renegotiation
00229  */
00230 #if defined(MBEDTLS_SSL_PROTO_SSL3)
00231 #define MBEDTLS_SSL_VERIFY_DATA_MAX_LEN 36
00232 #else
00233 #define MBEDTLS_SSL_VERIFY_DATA_MAX_LEN 12
00234 #endif
00235 
00236 /*
00237  * Signaling ciphersuite values (SCSV)
00238  */
00239 #define MBEDTLS_SSL_EMPTY_RENEGOTIATION_INFO    0xFF   /**< renegotiation info ext */
00240 #define MBEDTLS_SSL_FALLBACK_SCSV_VALUE         0x5600 /**< RFC 7507 section 2 */
00241 
00242 /*
00243  * Supported Signature and Hash algorithms (For TLS 1.2)
00244  * RFC 5246 section 7.4.1.4.1
00245  */
00246 #define MBEDTLS_SSL_HASH_NONE                0
00247 #define MBEDTLS_SSL_HASH_MD5                 1
00248 #define MBEDTLS_SSL_HASH_SHA1                2
00249 #define MBEDTLS_SSL_HASH_SHA224              3
00250 #define MBEDTLS_SSL_HASH_SHA256              4
00251 #define MBEDTLS_SSL_HASH_SHA384              5
00252 #define MBEDTLS_SSL_HASH_SHA512              6
00253 
00254 #define MBEDTLS_SSL_SIG_ANON                 0
00255 #define MBEDTLS_SSL_SIG_RSA                  1
00256 #define MBEDTLS_SSL_SIG_ECDSA                3
00257 
00258 /*
00259  * Client Certificate Types
00260  * RFC 5246 section 7.4.4 plus RFC 4492 section 5.5
00261  */
00262 #define MBEDTLS_SSL_CERT_TYPE_RSA_SIGN       1
00263 #define MBEDTLS_SSL_CERT_TYPE_ECDSA_SIGN    64
00264 
00265 /*
00266  * Message, alert and handshake types
00267  */
00268 #define MBEDTLS_SSL_MSG_CHANGE_CIPHER_SPEC     20
00269 #define MBEDTLS_SSL_MSG_ALERT                  21
00270 #define MBEDTLS_SSL_MSG_HANDSHAKE              22
00271 #define MBEDTLS_SSL_MSG_APPLICATION_DATA       23
00272 
00273 #define MBEDTLS_SSL_ALERT_LEVEL_WARNING         1
00274 #define MBEDTLS_SSL_ALERT_LEVEL_FATAL           2
00275 
00276 #define MBEDTLS_SSL_ALERT_MSG_CLOSE_NOTIFY           0  /* 0x00 */
00277 #define MBEDTLS_SSL_ALERT_MSG_UNEXPECTED_MESSAGE    10  /* 0x0A */
00278 #define MBEDTLS_SSL_ALERT_MSG_BAD_RECORD_MAC        20  /* 0x14 */
00279 #define MBEDTLS_SSL_ALERT_MSG_DECRYPTION_FAILED     21  /* 0x15 */
00280 #define MBEDTLS_SSL_ALERT_MSG_RECORD_OVERFLOW       22  /* 0x16 */
00281 #define MBEDTLS_SSL_ALERT_MSG_DECOMPRESSION_FAILURE 30  /* 0x1E */
00282 #define MBEDTLS_SSL_ALERT_MSG_HANDSHAKE_FAILURE     40  /* 0x28 */
00283 #define MBEDTLS_SSL_ALERT_MSG_NO_CERT               41  /* 0x29 */
00284 #define MBEDTLS_SSL_ALERT_MSG_BAD_CERT              42  /* 0x2A */
00285 #define MBEDTLS_SSL_ALERT_MSG_UNSUPPORTED_CERT      43  /* 0x2B */
00286 #define MBEDTLS_SSL_ALERT_MSG_CERT_REVOKED          44  /* 0x2C */
00287 #define MBEDTLS_SSL_ALERT_MSG_CERT_EXPIRED          45  /* 0x2D */
00288 #define MBEDTLS_SSL_ALERT_MSG_CERT_UNKNOWN          46  /* 0x2E */
00289 #define MBEDTLS_SSL_ALERT_MSG_ILLEGAL_PARAMETER     47  /* 0x2F */
00290 #define MBEDTLS_SSL_ALERT_MSG_UNKNOWN_CA            48  /* 0x30 */
00291 #define MBEDTLS_SSL_ALERT_MSG_ACCESS_DENIED         49  /* 0x31 */
00292 #define MBEDTLS_SSL_ALERT_MSG_DECODE_ERROR          50  /* 0x32 */
00293 #define MBEDTLS_SSL_ALERT_MSG_DECRYPT_ERROR         51  /* 0x33 */
00294 #define MBEDTLS_SSL_ALERT_MSG_EXPORT_RESTRICTION    60  /* 0x3C */
00295 #define MBEDTLS_SSL_ALERT_MSG_PROTOCOL_VERSION      70  /* 0x46 */
00296 #define MBEDTLS_SSL_ALERT_MSG_INSUFFICIENT_SECURITY 71  /* 0x47 */
00297 #define MBEDTLS_SSL_ALERT_MSG_INTERNAL_ERROR        80  /* 0x50 */
00298 #define MBEDTLS_SSL_ALERT_MSG_INAPROPRIATE_FALLBACK 86  /* 0x56 */
00299 #define MBEDTLS_SSL_ALERT_MSG_USER_CANCELED         90  /* 0x5A */
00300 #define MBEDTLS_SSL_ALERT_MSG_NO_RENEGOTIATION     100  /* 0x64 */
00301 #define MBEDTLS_SSL_ALERT_MSG_UNSUPPORTED_EXT      110  /* 0x6E */
00302 #define MBEDTLS_SSL_ALERT_MSG_UNRECOGNIZED_NAME    112  /* 0x70 */
00303 #define MBEDTLS_SSL_ALERT_MSG_UNKNOWN_PSK_IDENTITY 115  /* 0x73 */
00304 #define MBEDTLS_SSL_ALERT_MSG_NO_APPLICATION_PROTOCOL 120 /* 0x78 */
00305 
00306 #define MBEDTLS_SSL_HS_HELLO_REQUEST            0
00307 #define MBEDTLS_SSL_HS_CLIENT_HELLO             1
00308 #define MBEDTLS_SSL_HS_SERVER_HELLO             2
00309 #define MBEDTLS_SSL_HS_HELLO_VERIFY_REQUEST     3
00310 #define MBEDTLS_SSL_HS_NEW_SESSION_TICKET       4
00311 #define MBEDTLS_SSL_HS_CERTIFICATE             11
00312 #define MBEDTLS_SSL_HS_SERVER_KEY_EXCHANGE     12
00313 #define MBEDTLS_SSL_HS_CERTIFICATE_REQUEST     13
00314 #define MBEDTLS_SSL_HS_SERVER_HELLO_DONE       14
00315 #define MBEDTLS_SSL_HS_CERTIFICATE_VERIFY      15
00316 #define MBEDTLS_SSL_HS_CLIENT_KEY_EXCHANGE     16
00317 #define MBEDTLS_SSL_HS_FINISHED                20
00318 
00319 /*
00320  * TLS extensions
00321  */
00322 #define MBEDTLS_TLS_EXT_SERVERNAME                   0
00323 #define MBEDTLS_TLS_EXT_SERVERNAME_HOSTNAME          0
00324 
00325 #define MBEDTLS_TLS_EXT_MAX_FRAGMENT_LENGTH          1
00326 
00327 #define MBEDTLS_TLS_EXT_TRUNCATED_HMAC               4
00328 
00329 #define MBEDTLS_TLS_EXT_SUPPORTED_ELLIPTIC_CURVES   10
00330 #define MBEDTLS_TLS_EXT_SUPPORTED_POINT_FORMATS     11
00331 
00332 #define MBEDTLS_TLS_EXT_SIG_ALG                     13
00333 
00334 #define MBEDTLS_TLS_EXT_ALPN                        16
00335 
00336 #define MBEDTLS_TLS_EXT_ENCRYPT_THEN_MAC            22 /* 0x16 */
00337 #define MBEDTLS_TLS_EXT_EXTENDED_MASTER_SECRET  0x0017 /* 23 */
00338 
00339 #define MBEDTLS_TLS_EXT_SESSION_TICKET              35
00340 
00341 #define MBEDTLS_TLS_EXT_ECJPAKE_KKPP               256 /* experimental */
00342 
00343 #define MBEDTLS_TLS_EXT_RENEGOTIATION_INFO      0xFF01
00344 
00345 /*
00346  * Size defines
00347  */
00348 #if !defined(MBEDTLS_PSK_MAX_LEN)
00349 #define MBEDTLS_PSK_MAX_LEN            32 /* 256 bits */
00350 #endif
00351 
00352 /* Dummy type used only for its size */
00353 union mbedtls_ssl_premaster_secret
00354 {
00355 #if defined(MBEDTLS_KEY_EXCHANGE_RSA_ENABLED)
00356     unsigned char _pms_rsa[48];                         /* RFC 5246 8.1.1 */
00357 #endif
00358 #if defined(MBEDTLS_KEY_EXCHANGE_DHE_RSA_ENABLED)
00359     unsigned char _pms_dhm[MBEDTLS_MPI_MAX_SIZE];      /* RFC 5246 8.1.2 */
00360 #endif
00361 #if defined(MBEDTLS_KEY_EXCHANGE_ECDHE_RSA_ENABLED)    || \
00362     defined(MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED)  || \
00363     defined(MBEDTLS_KEY_EXCHANGE_ECDH_RSA_ENABLED)     || \
00364     defined(MBEDTLS_KEY_EXCHANGE_ECDH_ECDSA_ENABLED)
00365     unsigned char _pms_ecdh[MBEDTLS_ECP_MAX_BYTES];    /* RFC 4492 5.10 */
00366 #endif
00367 #if defined(MBEDTLS_KEY_EXCHANGE_PSK_ENABLED)
00368     unsigned char _pms_psk[4 + 2 * MBEDTLS_PSK_MAX_LEN];       /* RFC 4279 2 */
00369 #endif
00370 #if defined(MBEDTLS_KEY_EXCHANGE_DHE_PSK_ENABLED)
00371     unsigned char _pms_dhe_psk[4 + MBEDTLS_MPI_MAX_SIZE
00372                                  + MBEDTLS_PSK_MAX_LEN];       /* RFC 4279 3 */
00373 #endif
00374 #if defined(MBEDTLS_KEY_EXCHANGE_RSA_PSK_ENABLED)
00375     unsigned char _pms_rsa_psk[52 + MBEDTLS_PSK_MAX_LEN];      /* RFC 4279 4 */
00376 #endif
00377 #if defined(MBEDTLS_KEY_EXCHANGE_ECDHE_PSK_ENABLED)
00378     unsigned char _pms_ecdhe_psk[4 + MBEDTLS_ECP_MAX_BYTES
00379                                    + MBEDTLS_PSK_MAX_LEN];     /* RFC 5489 2 */
00380 #endif
00381 #if defined(MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED)
00382     unsigned char _pms_ecjpake[32];     /* Thread spec: SHA-256 output */
00383 #endif
00384 };
00385 
00386 #define MBEDTLS_PREMASTER_SIZE     sizeof( union mbedtls_ssl_premaster_secret )
00387 
00388 #ifdef __cplusplus
00389 extern "C" {
00390 #endif
00391 
00392 /*
00393  * SSL state machine
00394  */
00395 typedef enum
00396 {
00397     MBEDTLS_SSL_HELLO_REQUEST,
00398     MBEDTLS_SSL_CLIENT_HELLO,
00399     MBEDTLS_SSL_SERVER_HELLO,
00400     MBEDTLS_SSL_SERVER_CERTIFICATE,
00401     MBEDTLS_SSL_SERVER_KEY_EXCHANGE,
00402     MBEDTLS_SSL_CERTIFICATE_REQUEST,
00403     MBEDTLS_SSL_SERVER_HELLO_DONE,
00404     MBEDTLS_SSL_CLIENT_CERTIFICATE,
00405     MBEDTLS_SSL_CLIENT_KEY_EXCHANGE,
00406     MBEDTLS_SSL_CERTIFICATE_VERIFY,
00407     MBEDTLS_SSL_CLIENT_CHANGE_CIPHER_SPEC,
00408     MBEDTLS_SSL_CLIENT_FINISHED,
00409     MBEDTLS_SSL_SERVER_CHANGE_CIPHER_SPEC,
00410     MBEDTLS_SSL_SERVER_FINISHED,
00411     MBEDTLS_SSL_FLUSH_BUFFERS,
00412     MBEDTLS_SSL_HANDSHAKE_WRAPUP,
00413     MBEDTLS_SSL_HANDSHAKE_OVER,
00414     MBEDTLS_SSL_SERVER_NEW_SESSION_TICKET,
00415     MBEDTLS_SSL_SERVER_HELLO_VERIFY_REQUEST_SENT,
00416 }
00417 mbedtls_ssl_states;
00418 
00419 /**
00420  * \brief          Callback type: send data on the network.
00421  *
00422  * \note           That callback may be either blocking or non-blocking.
00423  *
00424  * \param ctx      Context for the send callback (typically a file descriptor)
00425  * \param buf      Buffer holding the data to send
00426  * \param len      Length of the data to send
00427  *
00428  * \return         The callback must return the number of bytes sent if any,
00429  *                 or a non-zero error code.
00430  *                 If performing non-blocking I/O, \c MBEDTLS_ERR_SSL_WANT_WRITE
00431  *                 must be returned when the operation would block.
00432  *
00433  * \note           The callback is allowed to send fewer bytes than requested.
00434  *                 It must always return the number of bytes actually sent.
00435  */
00436 typedef int mbedtls_ssl_send_t( void *ctx,
00437                                 const unsigned char *buf,
00438                                 size_t len );
00439 
00440 /**
00441  * \brief          Callback type: receive data from the network.
00442  *
00443  * \note           That callback may be either blocking or non-blocking.
00444  *
00445  * \param ctx      Context for the receive callback (typically a file
00446  *                 descriptor)
00447  * \param buf      Buffer to write the received data to
00448  * \param len      Length of the receive buffer
00449  *
00450  * \return         The callback must return the number of bytes received,
00451  *                 or a non-zero error code.
00452  *                 If performing non-blocking I/O, \c MBEDTLS_ERR_SSL_WANT_READ
00453  *                 must be returned when the operation would block.
00454  *
00455  * \note           The callback may receive fewer bytes than the length of the
00456  *                 buffer. It must always return the number of bytes actually
00457  *                 received and written to the buffer.
00458  */
00459 typedef int mbedtls_ssl_recv_t( void *ctx,
00460                                 unsigned char *buf,
00461                                 size_t len );
00462 
00463 /**
00464  * \brief          Callback type: receive data from the network, with timeout
00465  *
00466  * \note           That callback must block until data is received, or the
00467  *                 timeout delay expires, or the operation is interrupted by a
00468  *                 signal.
00469  *
00470  * \param ctx      Context for the receive callback (typically a file descriptor)
00471  * \param buf      Buffer to write the received data to
00472  * \param len      Length of the receive buffer
00473  * \param timeout  Maximum nomber of millisecondes to wait for data
00474  *                 0 means no timeout (potentially waiting forever)
00475  *
00476  * \return         The callback must return the number of bytes received,
00477  *                 or a non-zero error code:
00478  *                 \c MBEDTLS_ERR_SSL_TIMEOUT if the operation timed out,
00479  *                 \c MBEDTLS_ERR_SSL_WANT_READ if interrupted by a signal.
00480  *
00481  * \note           The callback may receive fewer bytes than the length of the
00482  *                 buffer. It must always return the number of bytes actually
00483  *                 received and written to the buffer.
00484  */
00485 typedef int mbedtls_ssl_recv_timeout_t( void *ctx,
00486                                         unsigned char *buf,
00487                                         size_t len,
00488                                         uint32_t timeout );
00489 /**
00490  * \brief          Callback type: set a pair of timers/delays to watch
00491  *
00492  * \param ctx      Context pointer
00493  * \param int_ms   Intermediate delay in milliseconds
00494  * \param fin_ms   Final delay in milliseconds
00495  *                 0 cancels the current timer.
00496  *
00497  * \note           This callback must at least store the necessary information
00498  *                 for the associated \c mbedtls_ssl_get_timer_t callback to
00499  *                 return correct information.
00500  *
00501  * \note           If using a event-driven style of programming, an event must
00502  *                 be generated when the final delay is passed. The event must
00503  *                 cause a call to \c mbedtls_ssl_handshake() with the proper
00504  *                 SSL context to be scheduled. Care must be taken to ensure
00505  *                 that at most one such call happens at a time.
00506  *
00507  * \note           Only one timer at a time must be running. Calling this
00508  *                 function while a timer is running must cancel it. Cancelled
00509  *                 timers must not generate any event.
00510  */
00511 typedef void mbedtls_ssl_set_timer_t( void * ctx,
00512                                       uint32_t int_ms,
00513                                       uint32_t fin_ms );
00514 
00515 /**
00516  * \brief          Callback type: get status of timers/delays
00517  *
00518  * \param ctx      Context pointer
00519  *
00520  * \return         This callback must return:
00521  *                 -1 if cancelled (fin_ms == 0),
00522  *                  0 if none of the delays have passed,
00523  *                  1 if only the intermediate delay has passed,
00524  *                  2 if the final delay has passed.
00525  */
00526 typedef int mbedtls_ssl_get_timer_t( void * ctx );
00527 
00528 
00529 /* Defined below */
00530 typedef struct mbedtls_ssl_session mbedtls_ssl_session;
00531 typedef struct mbedtls_ssl_context mbedtls_ssl_context;
00532 typedef struct mbedtls_ssl_config  mbedtls_ssl_config;
00533 
00534 /* Defined in ssl_internal.h */
00535 typedef struct mbedtls_ssl_transform mbedtls_ssl_transform;
00536 typedef struct mbedtls_ssl_handshake_params mbedtls_ssl_handshake_params;
00537 typedef struct mbedtls_ssl_sig_hash_set_t mbedtls_ssl_sig_hash_set_t;
00538 #if defined(MBEDTLS_X509_CRT_PARSE_C)
00539 typedef struct mbedtls_ssl_key_cert mbedtls_ssl_key_cert;
00540 #endif
00541 #if defined(MBEDTLS_SSL_PROTO_DTLS)
00542 typedef struct mbedtls_ssl_flight_item mbedtls_ssl_flight_item;
00543 #endif
00544 
00545 /*
00546  * This structure is used for storing current session data.
00547  */
00548 struct mbedtls_ssl_session
00549 {
00550 #if defined(MBEDTLS_HAVE_TIME)
00551     mbedtls_time_t start;       /*!< starting time      */
00552 #endif
00553     int ciphersuite;            /*!< chosen ciphersuite */
00554     int compression;            /*!< chosen compression */
00555     size_t id_len;              /*!< session id length  */
00556     unsigned char id[32];       /*!< session identifier */
00557     unsigned char master[48];   /*!< the master secret  */
00558 
00559 #if defined(MBEDTLS_X509_CRT_PARSE_C)
00560     mbedtls_x509_crt *peer_cert;        /*!< peer X.509 cert chain */
00561 #endif /* MBEDTLS_X509_CRT_PARSE_C */
00562     uint32_t verify_result;          /*!<  verification result     */
00563 
00564 #if defined(MBEDTLS_SSL_SESSION_TICKETS) && defined(MBEDTLS_SSL_CLI_C)
00565     unsigned char *ticket;      /*!< RFC 5077 session ticket */
00566     size_t ticket_len;          /*!< session ticket length   */
00567     uint32_t ticket_lifetime;   /*!< ticket lifetime hint    */
00568 #endif /* MBEDTLS_SSL_SESSION_TICKETS && MBEDTLS_SSL_CLI_C */
00569 
00570 #if defined(MBEDTLS_SSL_MAX_FRAGMENT_LENGTH)
00571     unsigned char mfl_code;     /*!< MaxFragmentLength negotiated by peer */
00572 #endif /* MBEDTLS_SSL_MAX_FRAGMENT_LENGTH */
00573 
00574 #if defined(MBEDTLS_SSL_TRUNCATED_HMAC)
00575     int trunc_hmac;             /*!< flag for truncated hmac activation   */
00576 #endif /* MBEDTLS_SSL_TRUNCATED_HMAC */
00577 
00578 #if defined(MBEDTLS_SSL_ENCRYPT_THEN_MAC)
00579     int encrypt_then_mac;       /*!< flag for EtM activation                */
00580 #endif
00581 };
00582 
00583 /**
00584  * SSL/TLS configuration to be shared between mbedtls_ssl_context structures.
00585  */
00586 struct mbedtls_ssl_config
00587 {
00588     /* Group items by size (largest first) to minimize padding overhead */
00589 
00590     /*
00591      * Pointers
00592      */
00593 
00594     const int *ciphersuite_list [4]; /*!< allowed ciphersuites per version   */
00595 
00596     /** Callback for printing debug output                                  */
00597     void (*f_dbg)(void *, int, const char *, int, const char *);
00598     void *p_dbg ;                    /*!< context for the debug function     */
00599 
00600     /** Callback for getting (pseudo-)random numbers                        */
00601     int  (*f_rng)(void *, unsigned char *, size_t);
00602     void *p_rng ;                    /*!< context for the RNG function       */
00603 
00604     /** Callback to retrieve a session from the cache                       */
00605     int (*f_get_cache)(void *, mbedtls_ssl_session *);
00606     /** Callback to store a session into the cache                          */
00607     int (*f_set_cache)(void *, const mbedtls_ssl_session *);
00608     void *p_cache ;                  /*!< context for cache callbacks        */
00609 
00610 #if defined(MBEDTLS_SSL_SERVER_NAME_INDICATION)
00611     /** Callback for setting cert according to SNI extension                */
00612     int (*f_sni)(void *, mbedtls_ssl_context *, const unsigned char *, size_t);
00613     void *p_sni ;                    /*!< context for SNI callback           */
00614 #endif
00615 
00616 #if defined(MBEDTLS_X509_CRT_PARSE_C)
00617     /** Callback to customize X.509 certificate chain verification          */
00618     int (*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *);
00619     void *p_vrfy ;                   /*!< context for X.509 verify calllback */
00620 #endif
00621 
00622 #if defined(MBEDTLS_KEY_EXCHANGE__SOME__PSK_ENABLED)
00623     /** Callback to retrieve PSK key from identity                          */
00624     int (*f_psk)(void *, mbedtls_ssl_context *, const unsigned char *, size_t);
00625     void *p_psk ;                    /*!< context for PSK callback           */
00626 #endif
00627 
00628 #if defined(MBEDTLS_SSL_DTLS_HELLO_VERIFY) && defined(MBEDTLS_SSL_SRV_C)
00629     /** Callback to create & write a cookie for ClientHello veirifcation    */
00630     int (*f_cookie_write)( void *, unsigned char **, unsigned char *,
00631                            const unsigned char *, size_t );
00632     /** Callback to verify validity of a ClientHello cookie                 */
00633     int (*f_cookie_check)( void *, const unsigned char *, size_t,
00634                            const unsigned char *, size_t );
00635     void *p_cookie ;                 /*!< context for the cookie callbacks   */
00636 #endif
00637 
00638 #if defined(MBEDTLS_SSL_SESSION_TICKETS) && defined(MBEDTLS_SSL_SRV_C)
00639     /** Callback to create & write a session ticket                         */
00640     int (*f_ticket_write)( void *, const mbedtls_ssl_session *,
00641             unsigned char *, const unsigned char *, size_t *, uint32_t * );
00642     /** Callback to parse a session ticket into a session structure         */
00643     int (*f_ticket_parse)( void *, mbedtls_ssl_session *, unsigned char *, size_t);
00644     void *p_ticket ;                 /*!< context for the ticket callbacks   */
00645 #endif /* MBEDTLS_SSL_SESSION_TICKETS && MBEDTLS_SSL_SRV_C */
00646 
00647 #if defined(MBEDTLS_SSL_EXPORT_KEYS)
00648     /** Callback to export key block and master secret                      */
00649     int (*f_export_keys)( void *, const unsigned char *,
00650             const unsigned char *, size_t, size_t, size_t );
00651     void *p_export_keys ;            /*!< context for key export callback    */
00652 #endif
00653 
00654 #if defined(MBEDTLS_X509_CRT_PARSE_C)
00655     const mbedtls_x509_crt_profile *cert_profile ; /*!< verification profile */
00656     mbedtls_ssl_key_cert *key_cert ; /*!< own certificate/key pair(s)        */
00657     mbedtls_x509_crt *ca_chain ;     /*!< trusted CAs                        */
00658     mbedtls_x509_crl *ca_crl ;       /*!< trusted CAs CRLs                   */
00659 #endif /* MBEDTLS_X509_CRT_PARSE_C */
00660 
00661 #if defined(MBEDTLS_KEY_EXCHANGE__WITH_CERT__ENABLED)
00662     const int *sig_hashes ;          /*!< allowed signature hashes           */
00663 #endif
00664 
00665 #if defined(MBEDTLS_ECP_C)
00666     const mbedtls_ecp_group_id *curve_list ; /*!< allowed curves             */
00667 #endif
00668 
00669 #if defined(MBEDTLS_DHM_C)
00670     mbedtls_mpi dhm_P ;              /*!< prime modulus for DHM              */
00671     mbedtls_mpi dhm_G ;              /*!< generator for DHM                  */
00672 #endif
00673 
00674 #if defined(MBEDTLS_KEY_EXCHANGE__SOME__PSK_ENABLED)
00675     unsigned char *psk ;             /*!< pre-shared key                     */
00676     size_t         psk_len ;         /*!< length of the pre-shared key       */
00677     unsigned char *psk_identity ;    /*!< identity for PSK negotiation       */
00678     size_t         psk_identity_len ;/*!< length of identity                 */
00679 #endif
00680 
00681 #if defined(MBEDTLS_SSL_ALPN)
00682     const char **alpn_list ;         /*!< ordered list of protocols          */
00683 #endif
00684 
00685     /*
00686      * Numerical settings (int then char)
00687      */
00688 
00689     uint32_t read_timeout ;          /*!< timeout for mbedtls_ssl_read (ms)  */
00690 
00691 #if defined(MBEDTLS_SSL_PROTO_DTLS)
00692     uint32_t hs_timeout_min ;        /*!< initial value of the handshake
00693                                          retransmission timeout (ms)        */
00694     uint32_t hs_timeout_max ;        /*!< maximum value of the handshake
00695                                          retransmission timeout (ms)        */
00696 #endif
00697 
00698 #if defined(MBEDTLS_SSL_RENEGOTIATION)
00699     int renego_max_records ;         /*!< grace period for renegotiation     */
00700     unsigned char renego_period [8]; /*!< value of the record counters
00701                                          that triggers renegotiation        */
00702 #endif
00703 
00704 #if defined(MBEDTLS_SSL_DTLS_BADMAC_LIMIT)
00705     unsigned int badmac_limit ;      /*!< limit of records with a bad MAC    */
00706 #endif
00707 
00708 #if defined(MBEDTLS_DHM_C) && defined(MBEDTLS_SSL_CLI_C)
00709     unsigned int dhm_min_bitlen ;    /*!< min. bit length of the DHM prime   */
00710 #endif
00711 
00712     unsigned char max_major_ver ;    /*!< max. major version used            */
00713     unsigned char max_minor_ver ;    /*!< max. minor version used            */
00714     unsigned char min_major_ver ;    /*!< min. major version used            */
00715     unsigned char min_minor_ver ;    /*!< min. minor version used            */
00716 
00717     /*
00718      * Flags (bitfields)
00719      */
00720 
00721     unsigned int endpoint  : 1;      /*!< 0: client, 1: server               */
00722     unsigned int transport  : 1;     /*!< stream (TLS) or datagram (DTLS)    */
00723     unsigned int authmode  : 2;      /*!< MBEDTLS_SSL_VERIFY_XXX             */
00724     /* needed even with renego disabled for LEGACY_BREAK_HANDSHAKE          */
00725     unsigned int allow_legacy_renegotiation  : 2 ; /*!< MBEDTLS_LEGACY_XXX   */
00726 #if defined(MBEDTLS_ARC4_C)
00727     unsigned int arc4_disabled  : 1; /*!< blacklist RC4 ciphersuites?        */
00728 #endif
00729 #if defined(MBEDTLS_SSL_MAX_FRAGMENT_LENGTH)
00730     unsigned int mfl_code  : 3;      /*!< desired fragment length            */
00731 #endif
00732 #if defined(MBEDTLS_SSL_ENCRYPT_THEN_MAC)
00733     unsigned int encrypt_then_mac  : 1 ; /*!< negotiate encrypt-then-mac?    */
00734 #endif
00735 #if defined(MBEDTLS_SSL_EXTENDED_MASTER_SECRET)
00736     unsigned int extended_ms  : 1;   /*!< negotiate extended master secret?  */
00737 #endif
00738 #if defined(MBEDTLS_SSL_DTLS_ANTI_REPLAY)
00739     unsigned int anti_replay  : 1;   /*!< detect and prevent replay?         */
00740 #endif
00741 #if defined(MBEDTLS_SSL_CBC_RECORD_SPLITTING)
00742     unsigned int cbc_record_splitting  : 1;  /*!< do cbc record splitting    */
00743 #endif
00744 #if defined(MBEDTLS_SSL_RENEGOTIATION)
00745     unsigned int disable_renegotiation  : 1; /*!< disable renegotiation?     */
00746 #endif
00747 #if defined(MBEDTLS_SSL_TRUNCATED_HMAC)
00748     unsigned int trunc_hmac  : 1;    /*!< negotiate truncated hmac?          */
00749 #endif
00750 #if defined(MBEDTLS_SSL_SESSION_TICKETS)
00751     unsigned int session_tickets  : 1;   /*!< use session tickets?           */
00752 #endif
00753 #if defined(MBEDTLS_SSL_FALLBACK_SCSV) && defined(MBEDTLS_SSL_CLI_C)
00754     unsigned int fallback  : 1;      /*!< is this a fallback?                */
00755 #endif
00756 #if defined(MBEDTLS_SSL_SRV_C)
00757     unsigned int cert_req_ca_list  : 1;  /*!< enable sending CA list in
00758                                           Certificate Request messages?     */
00759 #endif
00760 };
00761 
00762 
00763 struct mbedtls_ssl_context
00764 {
00765     const mbedtls_ssl_config *conf; /*!< configuration information          */
00766 
00767     /*
00768      * Miscellaneous
00769      */
00770     int state;                  /*!< SSL handshake: current state     */
00771 #if defined(MBEDTLS_SSL_RENEGOTIATION)
00772     int renego_status;          /*!< Initial, in progress, pending?   */
00773     int renego_records_seen;    /*!< Records since renego request, or with DTLS,
00774                                   number of retransmissions of request if
00775                                   renego_max_records is < 0           */
00776 #endif
00777 
00778     int major_ver;              /*!< equal to  MBEDTLS_SSL_MAJOR_VERSION_3    */
00779     int minor_ver;              /*!< either 0 (SSL3) or 1 (TLS1.0)    */
00780 
00781 #if defined(MBEDTLS_SSL_DTLS_BADMAC_LIMIT)
00782     unsigned badmac_seen;       /*!< records with a bad MAC received    */
00783 #endif
00784 
00785     mbedtls_ssl_send_t *f_send; /*!< Callback for network send */
00786     mbedtls_ssl_recv_t *f_recv; /*!< Callback for network receive */
00787     mbedtls_ssl_recv_timeout_t *f_recv_timeout;
00788                                 /*!< Callback for network receive with timeout */
00789 
00790     void *p_bio;                /*!< context for I/O operations   */
00791 
00792     /*
00793      * Session layer
00794      */
00795     mbedtls_ssl_session *session_in;            /*!<  current session data (in)   */
00796     mbedtls_ssl_session *session_out;           /*!<  current session data (out)  */
00797     mbedtls_ssl_session *session;               /*!<  negotiated session data     */
00798     mbedtls_ssl_session *session_negotiate;     /*!<  session data in negotiation */
00799 
00800     mbedtls_ssl_handshake_params *handshake;    /*!<  params required only during
00801                                               the handshake process        */
00802 
00803     /*
00804      * Record layer transformations
00805      */
00806     mbedtls_ssl_transform *transform_in;        /*!<  current transform params (in)   */
00807     mbedtls_ssl_transform *transform_out;       /*!<  current transform params (in)   */
00808     mbedtls_ssl_transform *transform;           /*!<  negotiated transform params     */
00809     mbedtls_ssl_transform *transform_negotiate; /*!<  transform params in negotiation */
00810 
00811     /*
00812      * Timers
00813      */
00814     void *p_timer;              /*!< context for the timer callbacks */
00815 
00816     mbedtls_ssl_set_timer_t *f_set_timer;       /*!< set timer callback */
00817     mbedtls_ssl_get_timer_t *f_get_timer;       /*!< get timer callback */
00818 
00819     /*
00820      * Record layer (incoming data)
00821      */
00822     unsigned char *in_buf;      /*!< input buffer                     */
00823     unsigned char *in_ctr;      /*!< 64-bit incoming message counter
00824                                      TLS: maintained by us
00825                                      DTLS: read from peer             */
00826     unsigned char *in_hdr;      /*!< start of record header           */
00827     unsigned char *in_len;      /*!< two-bytes message length field   */
00828     unsigned char *in_iv;       /*!< ivlen-byte IV                    */
00829     unsigned char *in_msg;      /*!< message contents (in_iv+ivlen)   */
00830     unsigned char *in_offt;     /*!< read offset in application data  */
00831 
00832     int in_msgtype;             /*!< record header: message type      */
00833     size_t in_msglen;           /*!< record header: message length    */
00834     size_t in_left;             /*!< amount of data read so far       */
00835 #if defined(MBEDTLS_SSL_PROTO_DTLS)
00836     uint16_t in_epoch;          /*!< DTLS epoch for incoming records  */
00837     size_t next_record_offset;  /*!< offset of the next record in datagram
00838                                      (equal to in_left if none)       */
00839 #endif
00840 #if defined(MBEDTLS_SSL_DTLS_ANTI_REPLAY)
00841     uint64_t in_window_top;     /*!< last validated record seq_num    */
00842     uint64_t in_window;         /*!< bitmask for replay detection     */
00843 #endif
00844 
00845     size_t in_hslen;            /*!< current handshake message length,
00846                                      including the handshake header   */
00847     int nb_zero;                /*!< # of 0-length encrypted messages */
00848 
00849     int keep_current_message;   /*!< drop or reuse current message
00850                                      on next call to record layer? */
00851 
00852     /*
00853      * Record layer (outgoing data)
00854      */
00855     unsigned char *out_buf;     /*!< output buffer                    */
00856     unsigned char *out_ctr;     /*!< 64-bit outgoing message counter  */
00857     unsigned char *out_hdr;     /*!< start of record header           */
00858     unsigned char *out_len;     /*!< two-bytes message length field   */
00859     unsigned char *out_iv;      /*!< ivlen-byte IV                    */
00860     unsigned char *out_msg;     /*!< message contents (out_iv+ivlen)  */
00861 
00862     int out_msgtype;            /*!< record header: message type      */
00863     size_t out_msglen;          /*!< record header: message length    */
00864     size_t out_left;            /*!< amount of data not yet written   */
00865 
00866 #if defined(MBEDTLS_ZLIB_SUPPORT)
00867     unsigned char *compress_buf;        /*!<  zlib data buffer        */
00868 #endif
00869 #if defined(MBEDTLS_SSL_CBC_RECORD_SPLITTING)
00870     signed char split_done;     /*!< current record already splitted? */
00871 #endif
00872 
00873     /*
00874      * PKI layer
00875      */
00876     int client_auth;                    /*!<  flag for client auth.   */
00877 
00878     /*
00879      * User settings
00880      */
00881 #if defined(MBEDTLS_X509_CRT_PARSE_C)
00882     char *hostname;             /*!< expected peer CN for verification
00883                                      (and SNI if available)                 */
00884 #endif
00885 
00886 #if defined(MBEDTLS_SSL_ALPN)
00887     const char *alpn_chosen;    /*!<  negotiated protocol                   */
00888 #endif
00889 
00890     /*
00891      * Information for DTLS hello verify
00892      */
00893 #if defined(MBEDTLS_SSL_DTLS_HELLO_VERIFY) && defined(MBEDTLS_SSL_SRV_C)
00894     unsigned char  *cli_id;         /*!<  transport-level ID of the client  */
00895     size_t          cli_id_len;     /*!<  length of cli_id                  */
00896 #endif
00897 
00898     /*
00899      * Secure renegotiation
00900      */
00901     /* needed to know when to send extension on server */
00902     int secure_renegotiation;           /*!<  does peer support legacy or
00903                                               secure renegotiation           */
00904 #if defined(MBEDTLS_SSL_RENEGOTIATION)
00905     size_t verify_data_len;             /*!<  length of verify data stored   */
00906     char own_verify_data[MBEDTLS_SSL_VERIFY_DATA_MAX_LEN]; /*!<  previous handshake verify data */
00907     char peer_verify_data[MBEDTLS_SSL_VERIFY_DATA_MAX_LEN]; /*!<  previous handshake verify data */
00908 #endif
00909 };
00910 
00911 #if defined(MBEDTLS_SSL_HW_RECORD_ACCEL)
00912 
00913 #define MBEDTLS_SSL_CHANNEL_OUTBOUND    0
00914 #define MBEDTLS_SSL_CHANNEL_INBOUND     1
00915 
00916 extern int (*mbedtls_ssl_hw_record_init)(mbedtls_ssl_context *ssl,
00917                 const unsigned char *key_enc, const unsigned char *key_dec,
00918                 size_t keylen,
00919                 const unsigned char *iv_enc,  const unsigned char *iv_dec,
00920                 size_t ivlen,
00921                 const unsigned char *mac_enc, const unsigned char *mac_dec,
00922                 size_t maclen);
00923 extern int (*mbedtls_ssl_hw_record_activate)(mbedtls_ssl_context *ssl, int direction);
00924 extern int (*mbedtls_ssl_hw_record_reset)(mbedtls_ssl_context *ssl);
00925 extern int (*mbedtls_ssl_hw_record_write)(mbedtls_ssl_context *ssl);
00926 extern int (*mbedtls_ssl_hw_record_read)(mbedtls_ssl_context *ssl);
00927 extern int (*mbedtls_ssl_hw_record_finish)(mbedtls_ssl_context *ssl);
00928 #endif /* MBEDTLS_SSL_HW_RECORD_ACCEL */
00929 
00930 /**
00931  * \brief Returns the list of ciphersuites supported by the SSL/TLS module.
00932  *
00933  * \return              a statically allocated array of ciphersuites, the last
00934  *                      entry is 0.
00935  */
00936 const int *mbedtls_ssl_list_ciphersuites( void );
00937 
00938 /**
00939  * \brief               Return the name of the ciphersuite associated with the
00940  *                      given ID
00941  *
00942  * \param ciphersuite_id SSL ciphersuite ID
00943  *
00944  * \return              a string containing the ciphersuite name
00945  */
00946 const char *mbedtls_ssl_get_ciphersuite_name( const int ciphersuite_id );
00947 
00948 /**
00949  * \brief               Return the ID of the ciphersuite associated with the
00950  *                      given name
00951  *
00952  * \param ciphersuite_name SSL ciphersuite name
00953  *
00954  * \return              the ID with the ciphersuite or 0 if not found
00955  */
00956 int mbedtls_ssl_get_ciphersuite_id( const char *ciphersuite_name );
00957 
00958 /**
00959  * \brief          Initialize an SSL context
00960  *                 Just makes the context ready for mbedtls_ssl_setup() or
00961  *                 mbedtls_ssl_free()
00962  *
00963  * \param ssl      SSL context
00964  */
00965 void mbedtls_ssl_init( mbedtls_ssl_context *ssl );
00966 
00967 /**
00968  * \brief          Set up an SSL context for use
00969  *
00970  * \note           No copy of the configuration context is made, it can be
00971  *                 shared by many mbedtls_ssl_context structures.
00972  *
00973  * \warning        Modifying the conf structure after it has been used in this
00974  *                 function is unsupported!
00975  *
00976  * \param ssl      SSL context
00977  * \param conf     SSL configuration to use
00978  *
00979  * \return         0 if successful, or MBEDTLS_ERR_SSL_ALLOC_FAILED if
00980  *                 memory allocation failed
00981  */
00982 int mbedtls_ssl_setup( mbedtls_ssl_context *ssl,
00983                        const mbedtls_ssl_config *conf );
00984 
00985 /**
00986  * \brief          Reset an already initialized SSL context for re-use
00987  *                 while retaining application-set variables, function
00988  *                 pointers and data.
00989  *
00990  * \param ssl      SSL context
00991  * \return         0 if successful, or MBEDTLS_ERR_SSL_ALLOC_FAILED,
00992                    MBEDTLS_ERR_SSL_HW_ACCEL_FAILED or
00993  *                 MBEDTLS_ERR_SSL_COMPRESSION_FAILED
00994  */
00995 int mbedtls_ssl_session_reset( mbedtls_ssl_context *ssl );
00996 
00997 /**
00998  * \brief          Set the current endpoint type
00999  *
01000  * \param conf     SSL configuration
01001  * \param endpoint must be MBEDTLS_SSL_IS_CLIENT or MBEDTLS_SSL_IS_SERVER
01002  */
01003 void mbedtls_ssl_conf_endpoint( mbedtls_ssl_config *conf, int endpoint );
01004 
01005 /**
01006  * \brief           Set the transport type (TLS or DTLS).
01007  *                  Default: TLS
01008  *
01009  * \note            For DTLS, you must either provide a recv callback that
01010  *                  doesn't block, or one that handles timeouts, see
01011  *                  \c mbedtls_ssl_set_bio(). You also need to provide timer
01012  *                  callbacks with \c mbedtls_ssl_set_timer_cb().
01013  *
01014  * \param conf      SSL configuration
01015  * \param transport transport type:
01016  *                  MBEDTLS_SSL_TRANSPORT_STREAM for TLS,
01017  *                  MBEDTLS_SSL_TRANSPORT_DATAGRAM for DTLS.
01018  */
01019 void mbedtls_ssl_conf_transport( mbedtls_ssl_config *conf, int transport );
01020 
01021 /**
01022  * \brief          Set the certificate verification mode
01023  *                 Default: NONE on server, REQUIRED on client
01024  *
01025  * \param conf     SSL configuration
01026  * \param authmode can be:
01027  *
01028  *  MBEDTLS_SSL_VERIFY_NONE:      peer certificate is not checked
01029  *                        (default on server)
01030  *                        (insecure on client)
01031  *
01032  *  MBEDTLS_SSL_VERIFY_OPTIONAL:  peer certificate is checked, however the
01033  *                        handshake continues even if verification failed;
01034  *                        mbedtls_ssl_get_verify_result() can be called after the
01035  *                        handshake is complete.
01036  *
01037  *  MBEDTLS_SSL_VERIFY_REQUIRED:  peer *must* present a valid certificate,
01038  *                        handshake is aborted if verification failed.
01039  *                        (default on client)
01040  *
01041  * \note On client, MBEDTLS_SSL_VERIFY_REQUIRED is the recommended mode.
01042  * With MBEDTLS_SSL_VERIFY_OPTIONAL, the user needs to call mbedtls_ssl_get_verify_result() at
01043  * the right time(s), which may not be obvious, while REQUIRED always perform
01044  * the verification as soon as possible. For example, REQUIRED was protecting
01045  * against the "triple handshake" attack even before it was found.
01046  */
01047 void mbedtls_ssl_conf_authmode( mbedtls_ssl_config *conf, int authmode );
01048 
01049 #if defined(MBEDTLS_X509_CRT_PARSE_C)
01050 /**
01051  * \brief          Set the verification callback (Optional).
01052  *
01053  *                 If set, the verify callback is called for each
01054  *                 certificate in the chain. For implementation
01055  *                 information, please see \c mbedtls_x509_crt_verify()
01056  *
01057  * \param conf     SSL configuration
01058  * \param f_vrfy   verification function
01059  * \param p_vrfy   verification parameter
01060  */
01061 void mbedtls_ssl_conf_verify( mbedtls_ssl_config *conf,
01062                      int (*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *),
01063                      void *p_vrfy );
01064 #endif /* MBEDTLS_X509_CRT_PARSE_C */
01065 
01066 /**
01067  * \brief          Set the random number generator callback
01068  *
01069  * \param conf     SSL configuration
01070  * \param f_rng    RNG function
01071  * \param p_rng    RNG parameter
01072  */
01073 void mbedtls_ssl_conf_rng( mbedtls_ssl_config *conf,
01074                   int (*f_rng)(void *, unsigned char *, size_t),
01075                   void *p_rng );
01076 
01077 /**
01078  * \brief          Set the debug callback
01079  *
01080  *                 The callback has the following argument:
01081  *                 void *           opaque context for the callback
01082  *                 int              debug level
01083  *                 const char *     file name
01084  *                 int              line number
01085  *                 const char *     message
01086  *
01087  * \param conf     SSL configuration
01088  * \param f_dbg    debug function
01089  * \param p_dbg    debug parameter
01090  */
01091 void mbedtls_ssl_conf_dbg( mbedtls_ssl_config *conf,
01092                   void (*f_dbg)(void *, int, const char *, int, const char *),
01093                   void  *p_dbg );
01094 
01095 /**
01096  * \brief          Set the underlying BIO callbacks for write, read and
01097  *                 read-with-timeout.
01098  *
01099  * \param ssl      SSL context
01100  * \param p_bio    parameter (context) shared by BIO callbacks
01101  * \param f_send   write callback
01102  * \param f_recv   read callback
01103  * \param f_recv_timeout blocking read callback with timeout.
01104  *
01105  * \note           One of f_recv or f_recv_timeout can be NULL, in which case
01106  *                 the other is used. If both are non-NULL, f_recv_timeout is
01107  *                 used and f_recv is ignored (as if it were NULL).
01108  *
01109  * \note           The two most common use cases are:
01110  *                 - non-blocking I/O, f_recv != NULL, f_recv_timeout == NULL
01111  *                 - blocking I/O, f_recv == NULL, f_recv_timout != NULL
01112  *
01113  * \note           For DTLS, you need to provide either a non-NULL
01114  *                 f_recv_timeout callback, or a f_recv that doesn't block.
01115  *
01116  * \note           See the documentations of \c mbedtls_ssl_sent_t,
01117  *                 \c mbedtls_ssl_recv_t and \c mbedtls_ssl_recv_timeout_t for
01118  *                 the conventions those callbacks must follow.
01119  *
01120  * \note           On some platforms, net_sockets.c provides
01121  *                 \c mbedtls_net_send(), \c mbedtls_net_recv() and
01122  *                 \c mbedtls_net_recv_timeout() that are suitable to be used
01123  *                 here.
01124  */
01125 void mbedtls_ssl_set_bio( mbedtls_ssl_context *ssl,
01126                           void *p_bio,
01127                           mbedtls_ssl_send_t *f_send,
01128                           mbedtls_ssl_recv_t *f_recv,
01129                           mbedtls_ssl_recv_timeout_t *f_recv_timeout );
01130 
01131 /**
01132  * \brief          Set the timeout period for mbedtls_ssl_read()
01133  *                 (Default: no timeout.)
01134  *
01135  * \param conf     SSL configuration context
01136  * \param timeout  Timeout value in milliseconds.
01137  *                 Use 0 for no timeout (default).
01138  *
01139  * \note           With blocking I/O, this will only work if a non-NULL
01140  *                 \c f_recv_timeout was set with \c mbedtls_ssl_set_bio().
01141  *                 With non-blocking I/O, this will only work if timer
01142  *                 callbacks were set with \c mbedtls_ssl_set_timer_cb().
01143  *
01144  * \note           With non-blocking I/O, you may also skip this function
01145  *                 altogether and handle timeouts at the application layer.
01146  */
01147 void mbedtls_ssl_conf_read_timeout( mbedtls_ssl_config *conf, uint32_t timeout );
01148 
01149 /**
01150  * \brief          Set the timer callbacks (Mandatory for DTLS.)
01151  *
01152  * \param ssl      SSL context
01153  * \param p_timer  parameter (context) shared by timer callbacks
01154  * \param f_set_timer   set timer callback
01155  * \param f_get_timer   get timer callback. Must return:
01156  *
01157  * \note           See the documentation of \c mbedtls_ssl_set_timer_t and
01158  *                 \c mbedtls_ssl_get_timer_t for the conventions this pair of
01159  *                 callbacks must follow.
01160  *
01161  * \note           On some platforms, timing.c provides
01162  *                 \c mbedtls_timing_set_delay() and
01163  *                 \c mbedtls_timing_get_delay() that are suitable for using
01164  *                 here, except if using an event-driven style.
01165  *
01166  * \note           See also the "DTLS tutorial" article in our knowledge base.
01167  *                 https://tls.mbed.org/kb/how-to/dtls-tutorial
01168  */
01169 void mbedtls_ssl_set_timer_cb( mbedtls_ssl_context *ssl,
01170                                void *p_timer,
01171                                mbedtls_ssl_set_timer_t *f_set_timer,
01172                                mbedtls_ssl_get_timer_t *f_get_timer );
01173 
01174 /**
01175  * \brief           Callback type: generate and write session ticket
01176  *
01177  * \note            This describes what a callback implementation should do.
01178  *                  This callback should generate an encrypted and
01179  *                  authenticated ticket for the session and write it to the
01180  *                  output buffer. Here, ticket means the opaque ticket part
01181  *                  of the NewSessionTicket structure of RFC 5077.
01182  *
01183  * \param p_ticket  Context for the callback
01184  * \param session   SSL session to be written in the ticket
01185  * \param start     Start of the output buffer
01186  * \param end       End of the output buffer
01187  * \param tlen      On exit, holds the length written
01188  * \param lifetime  On exit, holds the lifetime of the ticket in seconds
01189  *
01190  * \return          0 if successful, or
01191  *                  a specific MBEDTLS_ERR_XXX code.
01192  */
01193 typedef int mbedtls_ssl_ticket_write_t( void *p_ticket,
01194                                         const mbedtls_ssl_session *session,
01195                                         unsigned char *start,
01196                                         const unsigned char *end,
01197                                         size_t *tlen,
01198                                         uint32_t *lifetime );
01199 
01200 #if defined(MBEDTLS_SSL_EXPORT_KEYS)
01201 /**
01202  * \brief           Callback type: Export key block and master secret
01203  *
01204  * \note            This is required for certain uses of TLS, e.g. EAP-TLS
01205  *                  (RFC 5216) and Thread. The key pointers are ephemeral and
01206  *                  therefore must not be stored. The master secret and keys
01207  *                  should not be used directly except as an input to a key
01208  *                  derivation function.
01209  *
01210  * \param p_expkey  Context for the callback
01211  * \param ms        Pointer to master secret (fixed length: 48 bytes)
01212  * \param kb        Pointer to key block, see RFC 5246 section 6.3
01213  *                  (variable length: 2 * maclen + 2 * keylen + 2 * ivlen).
01214  * \param maclen    MAC length
01215  * \param keylen    Key length
01216  * \param ivlen     IV length
01217  *
01218  * \return          0 if successful, or
01219  *                  a specific MBEDTLS_ERR_XXX code.
01220  */
01221 typedef int mbedtls_ssl_export_keys_t( void *p_expkey,
01222                                 const unsigned char *ms,
01223                                 const unsigned char *kb,
01224                                 size_t maclen,
01225                                 size_t keylen,
01226                                 size_t ivlen );
01227 #endif /* MBEDTLS_SSL_EXPORT_KEYS */
01228 
01229 /**
01230  * \brief           Callback type: parse and load session ticket
01231  *
01232  * \note            This describes what a callback implementation should do.
01233  *                  This callback should parse a session ticket as generated
01234  *                  by the corresponding mbedtls_ssl_ticket_write_t function,
01235  *                  and, if the ticket is authentic and valid, load the
01236  *                  session.
01237  *
01238  * \note            The implementation is allowed to modify the first len
01239  *                  bytes of the input buffer, eg to use it as a temporary
01240  *                  area for the decrypted ticket contents.
01241  *
01242  * \param p_ticket  Context for the callback
01243  * \param session   SSL session to be loaded
01244  * \param buf       Start of the buffer containing the ticket
01245  * \param len       Length of the ticket.
01246  *
01247  * \return          0 if successful, or
01248  *                  MBEDTLS_ERR_SSL_INVALID_MAC if not authentic, or
01249  *                  MBEDTLS_ERR_SSL_SESSION_TICKET_EXPIRED if expired, or
01250  *                  any other non-zero code for other failures.
01251  */
01252 typedef int mbedtls_ssl_ticket_parse_t( void *p_ticket,
01253                                         mbedtls_ssl_session *session,
01254                                         unsigned char *buf,
01255                                         size_t len );
01256 
01257 #if defined(MBEDTLS_SSL_SESSION_TICKETS) && defined(MBEDTLS_SSL_SRV_C)
01258 /**
01259  * \brief           Configure SSL session ticket callbacks (server only).
01260  *                  (Default: none.)
01261  *
01262  * \note            On server, session tickets are enabled by providing
01263  *                  non-NULL callbacks.
01264  *
01265  * \note            On client, use \c mbedtls_ssl_conf_session_tickets().
01266  *
01267  * \param conf      SSL configuration context
01268  * \param f_ticket_write    Callback for writing a ticket
01269  * \param f_ticket_parse    Callback for parsing a ticket
01270  * \param p_ticket          Context shared by the two callbacks
01271  */
01272 void mbedtls_ssl_conf_session_tickets_cb( mbedtls_ssl_config *conf,
01273         mbedtls_ssl_ticket_write_t *f_ticket_write,
01274         mbedtls_ssl_ticket_parse_t *f_ticket_parse,
01275         void *p_ticket );
01276 #endif /* MBEDTLS_SSL_SESSION_TICKETS && MBEDTLS_SSL_SRV_C */
01277 
01278 #if defined(MBEDTLS_SSL_EXPORT_KEYS)
01279 /**
01280  * \brief           Configure key export callback.
01281  *                  (Default: none.)
01282  *
01283  * \note            See \c mbedtls_ssl_export_keys_t.
01284  *
01285  * \param conf      SSL configuration context
01286  * \param f_export_keys     Callback for exporting keys
01287  * \param p_export_keys     Context for the callback
01288  */
01289 void mbedtls_ssl_conf_export_keys_cb( mbedtls_ssl_config *conf,
01290         mbedtls_ssl_export_keys_t *f_export_keys,
01291         void *p_export_keys );
01292 #endif /* MBEDTLS_SSL_EXPORT_KEYS */
01293 
01294 /**
01295  * \brief          Callback type: generate a cookie
01296  *
01297  * \param ctx      Context for the callback
01298  * \param p        Buffer to write to,
01299  *                 must be updated to point right after the cookie
01300  * \param end      Pointer to one past the end of the output buffer
01301  * \param info     Client ID info that was passed to
01302  *                 \c mbedtls_ssl_set_client_transport_id()
01303  * \param ilen     Length of info in bytes
01304  *
01305  * \return         The callback must return 0 on success,
01306  *                 or a negative error code.
01307  */
01308 typedef int mbedtls_ssl_cookie_write_t( void *ctx,
01309                                 unsigned char **p, unsigned char *end,
01310                                 const unsigned char *info, size_t ilen );
01311 
01312 /**
01313  * \brief          Callback type: verify a cookie
01314  *
01315  * \param ctx      Context for the callback
01316  * \param cookie   Cookie to verify
01317  * \param clen     Length of cookie
01318  * \param info     Client ID info that was passed to
01319  *                 \c mbedtls_ssl_set_client_transport_id()
01320  * \param ilen     Length of info in bytes
01321  *
01322  * \return         The callback must return 0 if cookie is valid,
01323  *                 or a negative error code.
01324  */
01325 typedef int mbedtls_ssl_cookie_check_t( void *ctx,
01326                                 const unsigned char *cookie, size_t clen,
01327                                 const unsigned char *info, size_t ilen );
01328 
01329 #if defined(MBEDTLS_SSL_DTLS_HELLO_VERIFY) && defined(MBEDTLS_SSL_SRV_C)
01330 /**
01331  * \brief           Register callbacks for DTLS cookies
01332  *                  (Server only. DTLS only.)
01333  *
01334  *                  Default: dummy callbacks that fail, in order to force you to
01335  *                  register working callbacks (and initialize their context).
01336  *
01337  *                  To disable HelloVerifyRequest, register NULL callbacks.
01338  *
01339  * \warning         Disabling hello verification allows your server to be used
01340  *                  for amplification in DoS attacks against other hosts.
01341  *                  Only disable if you known this can't happen in your
01342  *                  particular environment.
01343  *
01344  * \note            See comments on \c mbedtls_ssl_handshake() about handling
01345  *                  the MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED that is expected
01346  *                  on the first handshake attempt when this is enabled.
01347  *
01348  * \note            This is also necessary to handle client reconnection from
01349  *                  the same port as described in RFC 6347 section 4.2.8 (only
01350  *                  the variant with cookies is supported currently). See
01351  *                  comments on \c mbedtls_ssl_read() for details.
01352  *
01353  * \param conf              SSL configuration
01354  * \param f_cookie_write    Cookie write callback
01355  * \param f_cookie_check    Cookie check callback
01356  * \param p_cookie          Context for both callbacks
01357  */
01358 void mbedtls_ssl_conf_dtls_cookies( mbedtls_ssl_config *conf,
01359                            mbedtls_ssl_cookie_write_t *f_cookie_write,
01360                            mbedtls_ssl_cookie_check_t *f_cookie_check,
01361                            void *p_cookie );
01362 
01363 /**
01364  * \brief          Set client's transport-level identification info.
01365  *                 (Server only. DTLS only.)
01366  *
01367  *                 This is usually the IP address (and port), but could be
01368  *                 anything identify the client depending on the underlying
01369  *                 network stack. Used for HelloVerifyRequest with DTLS.
01370  *                 This is *not* used to route the actual packets.
01371  *
01372  * \param ssl      SSL context
01373  * \param info     Transport-level info identifying the client (eg IP + port)
01374  * \param ilen     Length of info in bytes
01375  *
01376  * \note           An internal copy is made, so the info buffer can be reused.
01377  *
01378  * \return         0 on success,
01379  *                 MBEDTLS_ERR_SSL_BAD_INPUT_DATA if used on client,
01380  *                 MBEDTLS_ERR_SSL_ALLOC_FAILED if out of memory.
01381  */
01382 int mbedtls_ssl_set_client_transport_id( mbedtls_ssl_context *ssl,
01383                                  const unsigned char *info,
01384                                  size_t ilen );
01385 
01386 #endif /* MBEDTLS_SSL_DTLS_HELLO_VERIFY && MBEDTLS_SSL_SRV_C */
01387 
01388 #if defined(MBEDTLS_SSL_DTLS_ANTI_REPLAY)
01389 /**
01390  * \brief          Enable or disable anti-replay protection for DTLS.
01391  *                 (DTLS only, no effect on TLS.)
01392  *                 Default: enabled.
01393  *
01394  * \param conf     SSL configuration
01395  * \param mode     MBEDTLS_SSL_ANTI_REPLAY_ENABLED or MBEDTLS_SSL_ANTI_REPLAY_DISABLED.
01396  *
01397  * \warning        Disabling this is a security risk unless the application
01398  *                 protocol handles duplicated packets in a safe way. You
01399  *                 should not disable this without careful consideration.
01400  *                 However, if your application already detects duplicated
01401  *                 packets and needs information about them to adjust its
01402  *                 transmission strategy, then you'll want to disable this.
01403  */
01404 void mbedtls_ssl_conf_dtls_anti_replay( mbedtls_ssl_config *conf, char mode );
01405 #endif /* MBEDTLS_SSL_DTLS_ANTI_REPLAY */
01406 
01407 #if defined(MBEDTLS_SSL_DTLS_BADMAC_LIMIT)
01408 /**
01409  * \brief          Set a limit on the number of records with a bad MAC
01410  *                 before terminating the connection.
01411  *                 (DTLS only, no effect on TLS.)
01412  *                 Default: 0 (disabled).
01413  *
01414  * \param conf     SSL configuration
01415  * \param limit    Limit, or 0 to disable.
01416  *
01417  * \note           If the limit is N, then the connection is terminated when
01418  *                 the Nth non-authentic record is seen.
01419  *
01420  * \note           Records with an invalid header are not counted, only the
01421  *                 ones going through the authentication-decryption phase.
01422  *
01423  * \note           This is a security trade-off related to the fact that it's
01424  *                 often relatively easy for an active attacker ot inject UDP
01425  *                 datagrams. On one hand, setting a low limit here makes it
01426  *                 easier for such an attacker to forcibly terminated a
01427  *                 connection. On the other hand, a high limit or no limit
01428  *                 might make us waste resources checking authentication on
01429  *                 many bogus packets.
01430  */
01431 void mbedtls_ssl_conf_dtls_badmac_limit( mbedtls_ssl_config *conf, unsigned limit );
01432 #endif /* MBEDTLS_SSL_DTLS_BADMAC_LIMIT */
01433 
01434 #if defined(MBEDTLS_SSL_PROTO_DTLS)
01435 /**
01436  * \brief          Set retransmit timeout values for the DTLS handshake.
01437  *                 (DTLS only, no effect on TLS.)
01438  *
01439  * \param conf     SSL configuration
01440  * \param min      Initial timeout value in milliseconds.
01441  *                 Default: 1000 (1 second).
01442  * \param max      Maximum timeout value in milliseconds.
01443  *                 Default: 60000 (60 seconds).
01444  *
01445  * \note           Default values are from RFC 6347 section 4.2.4.1.
01446  *
01447  * \note           The 'min' value should typically be slightly above the
01448  *                 expected round-trip time to your peer, plus whatever time
01449  *                 it takes for the peer to process the message. For example,
01450  *                 if your RTT is about 600ms and you peer needs up to 1s to
01451  *                 do the cryptographic operations in the handshake, then you
01452  *                 should set 'min' slightly above 1600. Lower values of 'min'
01453  *                 might cause spurious resends which waste network resources,
01454  *                 while larger value of 'min' will increase overall latency
01455  *                 on unreliable network links.
01456  *
01457  * \note           The more unreliable your network connection is, the larger
01458  *                 your max / min ratio needs to be in order to achieve
01459  *                 reliable handshakes.
01460  *
01461  * \note           Messages are retransmitted up to log2(ceil(max/min)) times.
01462  *                 For example, if min = 1s and max = 5s, the retransmit plan
01463  *                 goes: send ... 1s -> resend ... 2s -> resend ... 4s ->
01464  *                 resend ... 5s -> give up and return a timeout error.
01465  */
01466 void mbedtls_ssl_conf_handshake_timeout( mbedtls_ssl_config *conf, uint32_t min, uint32_t max );
01467 #endif /* MBEDTLS_SSL_PROTO_DTLS */
01468 
01469 #if defined(MBEDTLS_SSL_SRV_C)
01470 /**
01471  * \brief          Set the session cache callbacks (server-side only)
01472  *                 If not set, no session resuming is done (except if session
01473  *                 tickets are enabled too).
01474  *
01475  *                 The session cache has the responsibility to check for stale
01476  *                 entries based on timeout. See RFC 5246 for recommendations.
01477  *
01478  *                 Warning: session.peer_cert is cleared by the SSL/TLS layer on
01479  *                 connection shutdown, so do not cache the pointer! Either set
01480  *                 it to NULL or make a full copy of the certificate.
01481  *
01482  *                 The get callback is called once during the initial handshake
01483  *                 to enable session resuming. The get function has the
01484  *                 following parameters: (void *parameter, mbedtls_ssl_session *session)
01485  *                 If a valid entry is found, it should fill the master of
01486  *                 the session object with the cached values and return 0,
01487  *                 return 1 otherwise. Optionally peer_cert can be set as well
01488  *                 if it is properly present in cache entry.
01489  *
01490  *                 The set callback is called once during the initial handshake
01491  *                 to enable session resuming after the entire handshake has
01492  *                 been finished. The set function has the following parameters:
01493  *                 (void *parameter, const mbedtls_ssl_session *session). The function
01494  *                 should create a cache entry for future retrieval based on
01495  *                 the data in the session structure and should keep in mind
01496  *                 that the mbedtls_ssl_session object presented (and all its referenced
01497  *                 data) is cleared by the SSL/TLS layer when the connection is
01498  *                 terminated. It is recommended to add metadata to determine if
01499  *                 an entry is still valid in the future. Return 0 if
01500  *                 successfully cached, return 1 otherwise.
01501  *
01502  * \param conf           SSL configuration
01503  * \param p_cache        parmater (context) for both callbacks
01504  * \param f_get_cache    session get callback
01505  * \param f_set_cache    session set callback
01506  */
01507 void mbedtls_ssl_conf_session_cache( mbedtls_ssl_config *conf,
01508         void *p_cache,
01509         int (*f_get_cache)(void *, mbedtls_ssl_session *),
01510         int (*f_set_cache)(void *, const mbedtls_ssl_session *) );
01511 #endif /* MBEDTLS_SSL_SRV_C */
01512 
01513 #if defined(MBEDTLS_SSL_CLI_C)
01514 /**
01515  * \brief          Request resumption of session (client-side only)
01516  *                 Session data is copied from presented session structure.
01517  *
01518  * \param ssl      SSL context
01519  * \param session  session context
01520  *
01521  * \return         0 if successful,
01522  *                 MBEDTLS_ERR_SSL_ALLOC_FAILED if memory allocation failed,
01523  *                 MBEDTLS_ERR_SSL_BAD_INPUT_DATA if used server-side or
01524  *                 arguments are otherwise invalid
01525  *
01526  * \sa             mbedtls_ssl_get_session()
01527  */
01528 int mbedtls_ssl_set_session( mbedtls_ssl_context *ssl, const mbedtls_ssl_session *session );
01529 #endif /* MBEDTLS_SSL_CLI_C */
01530 
01531 /**
01532  * \brief               Set the list of allowed ciphersuites and the preference
01533  *                      order. First in the list has the highest preference.
01534  *                      (Overrides all version-specific lists)
01535  *
01536  *                      The ciphersuites array is not copied, and must remain
01537  *                      valid for the lifetime of the ssl_config.
01538  *
01539  *                      Note: The server uses its own preferences
01540  *                      over the preference of the client unless
01541  *                      MBEDTLS_SSL_SRV_RESPECT_CLIENT_PREFERENCE is defined!
01542  *
01543  * \param conf          SSL configuration
01544  * \param ciphersuites  0-terminated list of allowed ciphersuites
01545  */
01546 void mbedtls_ssl_conf_ciphersuites( mbedtls_ssl_config *conf,
01547                                    const int *ciphersuites );
01548 
01549 /**
01550  * \brief               Set the list of allowed ciphersuites and the
01551  *                      preference order for a specific version of the protocol.
01552  *                      (Only useful on the server side)
01553  *
01554  *                      The ciphersuites array is not copied, and must remain
01555  *                      valid for the lifetime of the ssl_config.
01556  *
01557  * \param conf          SSL configuration
01558  * \param ciphersuites  0-terminated list of allowed ciphersuites
01559  * \param major         Major version number (only MBEDTLS_SSL_MAJOR_VERSION_3
01560  *                      supported)
01561  * \param minor         Minor version number (MBEDTLS_SSL_MINOR_VERSION_0,
01562  *                      MBEDTLS_SSL_MINOR_VERSION_1 and MBEDTLS_SSL_MINOR_VERSION_2,
01563  *                      MBEDTLS_SSL_MINOR_VERSION_3 supported)
01564  *
01565  * \note                With DTLS, use MBEDTLS_SSL_MINOR_VERSION_2 for DTLS 1.0
01566  *                      and MBEDTLS_SSL_MINOR_VERSION_3 for DTLS 1.2
01567  */
01568 void mbedtls_ssl_conf_ciphersuites_for_version( mbedtls_ssl_config *conf,
01569                                        const int *ciphersuites,
01570                                        int major, int minor );
01571 
01572 #if defined(MBEDTLS_X509_CRT_PARSE_C)
01573 /**
01574  * \brief          Set the X.509 security profile used for verification
01575  *
01576  * \note           The restrictions are enforced for all certificates in the
01577  *                 chain. However, signatures in the handshake are not covered
01578  *                 by this setting but by \b mbedtls_ssl_conf_sig_hashes().
01579  *
01580  * \param conf     SSL configuration
01581  * \param profile  Profile to use
01582  */
01583 void mbedtls_ssl_conf_cert_profile( mbedtls_ssl_config *conf,
01584                                     const mbedtls_x509_crt_profile *profile );
01585 
01586 /**
01587  * \brief          Set the data required to verify peer certificate
01588  *
01589  * \param conf     SSL configuration
01590  * \param ca_chain trusted CA chain (meaning all fully trusted top-level CAs)
01591  * \param ca_crl   trusted CA CRLs
01592  */
01593 void mbedtls_ssl_conf_ca_chain( mbedtls_ssl_config *conf,
01594                                mbedtls_x509_crt *ca_chain,
01595                                mbedtls_x509_crl *ca_crl );
01596 
01597 /**
01598  * \brief          Set own certificate chain and private key
01599  *
01600  * \note           own_cert should contain in order from the bottom up your
01601  *                 certificate chain. The top certificate (self-signed)
01602  *                 can be omitted.
01603  *
01604  * \note           On server, this function can be called multiple times to
01605  *                 provision more than one cert/key pair (eg one ECDSA, one
01606  *                 RSA with SHA-256, one RSA with SHA-1). An adequate
01607  *                 certificate will be selected according to the client's
01608  *                 advertised capabilities. In case mutliple certificates are
01609  *                 adequate, preference is given to the one set by the first
01610  *                 call to this function, then second, etc.
01611  *
01612  * \note           On client, only the first call has any effect. That is,
01613  *                 only one client certificate can be provisioned. The
01614  *                 server's preferences in its CertficateRequest message will
01615  *                 be ignored and our only cert will be sent regardless of
01616  *                 whether it matches those preferences - the server can then
01617  *                 decide what it wants to do with it.
01618  *
01619  * \param conf     SSL configuration
01620  * \param own_cert own public certificate chain
01621  * \param pk_key   own private key
01622  *
01623  * \return         0 on success or MBEDTLS_ERR_SSL_ALLOC_FAILED
01624  */
01625 int mbedtls_ssl_conf_own_cert( mbedtls_ssl_config *conf,
01626                               mbedtls_x509_crt *own_cert,
01627                               mbedtls_pk_context *pk_key );
01628 #endif /* MBEDTLS_X509_CRT_PARSE_C */
01629 
01630 #if defined(MBEDTLS_KEY_EXCHANGE__SOME__PSK_ENABLED)
01631 /**
01632  * \brief          Set the Pre Shared Key (PSK) and the expected identity name
01633  *
01634  * \note           This is mainly useful for clients. Servers will usually
01635  *                 want to use \c mbedtls_ssl_conf_psk_cb() instead.
01636  *
01637  * \note           Currently clients can only register one pre-shared key.
01638  *                 In other words, the servers' identity hint is ignored.
01639  *                 Support for setting multiple PSKs on clients and selecting
01640  *                 one based on the identity hint is not a planned feature but
01641  *                 feedback is welcomed.
01642  *
01643  * \param conf     SSL configuration
01644  * \param psk      pointer to the pre-shared key
01645  * \param psk_len  pre-shared key length
01646  * \param psk_identity      pointer to the pre-shared key identity
01647  * \param psk_identity_len  identity key length
01648  *
01649  * \return         0 if successful or MBEDTLS_ERR_SSL_ALLOC_FAILED
01650  */
01651 int mbedtls_ssl_conf_psk( mbedtls_ssl_config *conf,
01652                 const unsigned char *psk, size_t psk_len,
01653                 const unsigned char *psk_identity, size_t psk_identity_len );
01654 
01655 
01656 /**
01657  * \brief          Set the Pre Shared Key (PSK) for the current handshake
01658  *
01659  * \note           This should only be called inside the PSK callback,
01660  *                 ie the function passed to \c mbedtls_ssl_conf_psk_cb().
01661  *
01662  * \param ssl      SSL context
01663  * \param psk      pointer to the pre-shared key
01664  * \param psk_len  pre-shared key length
01665  *
01666  * \return         0 if successful or MBEDTLS_ERR_SSL_ALLOC_FAILED
01667  */
01668 int mbedtls_ssl_set_hs_psk( mbedtls_ssl_context *ssl,
01669                             const unsigned char *psk, size_t psk_len );
01670 
01671 /**
01672  * \brief          Set the PSK callback (server-side only).
01673  *
01674  *                 If set, the PSK callback is called for each
01675  *                 handshake where a PSK ciphersuite was negotiated.
01676  *                 The caller provides the identity received and wants to
01677  *                 receive the actual PSK data and length.
01678  *
01679  *                 The callback has the following parameters: (void *parameter,
01680  *                 mbedtls_ssl_context *ssl, const unsigned char *psk_identity,
01681  *                 size_t identity_len)
01682  *                 If a valid PSK identity is found, the callback should use
01683  *                 \c mbedtls_ssl_set_hs_psk() on the ssl context to set the
01684  *                 correct PSK and return 0.
01685  *                 Any other return value will result in a denied PSK identity.
01686  *
01687  * \note           If you set a PSK callback using this function, then you
01688  *                 don't need to set a PSK key and identity using
01689  *                 \c mbedtls_ssl_conf_psk().
01690  *
01691  * \param conf     SSL configuration
01692  * \param f_psk    PSK identity function
01693  * \param p_psk    PSK identity parameter
01694  */
01695 void mbedtls_ssl_conf_psk_cb( mbedtls_ssl_config *conf,
01696                      int (*f_psk)(void *, mbedtls_ssl_context *, const unsigned char *,
01697                                   size_t),
01698                      void *p_psk );
01699 #endif /* MBEDTLS_KEY_EXCHANGE__SOME__PSK_ENABLED */
01700 
01701 #if defined(MBEDTLS_DHM_C) && defined(MBEDTLS_SSL_SRV_C)
01702 /**
01703  * \brief          Set the Diffie-Hellman public P and G values,
01704  *                 read as hexadecimal strings (server-side only)
01705  *                 (Default: MBEDTLS_DHM_RFC5114_MODP_2048_[PG])
01706  *
01707  * \param conf     SSL configuration
01708  * \param dhm_P    Diffie-Hellman-Merkle modulus
01709  * \param dhm_G    Diffie-Hellman-Merkle generator
01710  *
01711  * \return         0 if successful
01712  */
01713 int mbedtls_ssl_conf_dh_param( mbedtls_ssl_config *conf, const char *dhm_P, const char *dhm_G );
01714 
01715 /**
01716  * \brief          Set the Diffie-Hellman public P and G values,
01717  *                 read from existing context (server-side only)
01718  *
01719  * \param conf     SSL configuration
01720  * \param dhm_ctx  Diffie-Hellman-Merkle context
01721  *
01722  * \return         0 if successful
01723  */
01724 int mbedtls_ssl_conf_dh_param_ctx( mbedtls_ssl_config *conf, mbedtls_dhm_context *dhm_ctx );
01725 #endif /* MBEDTLS_DHM_C && defined(MBEDTLS_SSL_SRV_C) */
01726 
01727 #if defined(MBEDTLS_DHM_C) && defined(MBEDTLS_SSL_CLI_C)
01728 /**
01729  * \brief          Set the minimum length for Diffie-Hellman parameters.
01730  *                 (Client-side only.)
01731  *                 (Default: 1024 bits.)
01732  *
01733  * \param conf     SSL configuration
01734  * \param bitlen   Minimum bit length of the DHM prime
01735  */
01736 void mbedtls_ssl_conf_dhm_min_bitlen( mbedtls_ssl_config *conf,
01737                                       unsigned int bitlen );
01738 #endif /* MBEDTLS_DHM_C && MBEDTLS_SSL_CLI_C */
01739 
01740 #if defined(MBEDTLS_ECP_C)
01741 /**
01742  * \brief          Set the allowed curves in order of preference.
01743  *                 (Default: all defined curves.)
01744  *
01745  *                 On server: this only affects selection of the ECDHE curve;
01746  *                 the curves used for ECDH and ECDSA are determined by the
01747  *                 list of available certificates instead.
01748  *
01749  *                 On client: this affects the list of curves offered for any
01750  *                 use. The server can override our preference order.
01751  *
01752  *                 Both sides: limits the set of curves accepted for use in
01753  *                 ECDHE and in the peer's end-entity certificate.
01754  *
01755  * \note           This has no influence on which curves are allowed inside the
01756  *                 certificate chains, see \c mbedtls_ssl_conf_cert_profile()
01757  *                 for that. For the end-entity certificate however, the key
01758  *                 will be accepted only if it is allowed both by this list
01759  *                 and by the cert profile.
01760  *
01761  * \note           This list should be ordered by decreasing preference
01762  *                 (preferred curve first).
01763  *
01764  * \param conf     SSL configuration
01765  * \param curves   Ordered list of allowed curves,
01766  *                 terminated by MBEDTLS_ECP_DP_NONE.
01767  */
01768 void mbedtls_ssl_conf_curves( mbedtls_ssl_config *conf,
01769                               const mbedtls_ecp_group_id *curves );
01770 #endif /* MBEDTLS_ECP_C */
01771 
01772 #if defined(MBEDTLS_KEY_EXCHANGE__WITH_CERT__ENABLED)
01773 /**
01774  * \brief          Set the allowed hashes for signatures during the handshake.
01775  *                 (Default: all available hashes except MD5.)
01776  *
01777  * \note           This only affects which hashes are offered and can be used
01778  *                 for signatures during the handshake. Hashes for message
01779  *                 authentication and the TLS PRF are controlled by the
01780  *                 ciphersuite, see \c mbedtls_ssl_conf_ciphersuites(). Hashes
01781  *                 used for certificate signature are controlled by the
01782  *                 verification profile, see \c mbedtls_ssl_conf_cert_profile().
01783  *
01784  * \note           This list should be ordered by decreasing preference
01785  *                 (preferred hash first).
01786  *
01787  * \param conf     SSL configuration
01788  * \param hashes   Ordered list of allowed signature hashes,
01789  *                 terminated by \c MBEDTLS_MD_NONE.
01790  */
01791 void mbedtls_ssl_conf_sig_hashes( mbedtls_ssl_config *conf,
01792                                   const int *hashes );
01793 #endif /* MBEDTLS_KEY_EXCHANGE__WITH_CERT__ENABLED */
01794 
01795 #if defined(MBEDTLS_X509_CRT_PARSE_C)
01796 /**
01797  * \brief          Set the hostname to check against the received server
01798  *                 certificate. It sets the ServerName TLS extension too,
01799  *                 if the extension is enabled.
01800  *                 (client-side only)
01801  *
01802  * \param ssl      SSL context
01803  * \param hostname the server hostname
01804  *
01805  * \return         0 if successful or MBEDTLS_ERR_SSL_ALLOC_FAILED
01806  */
01807 int mbedtls_ssl_set_hostname( mbedtls_ssl_context *ssl, const char *hostname );
01808 #endif /* MBEDTLS_X509_CRT_PARSE_C */
01809 
01810 #if defined(MBEDTLS_SSL_SERVER_NAME_INDICATION)
01811 /**
01812  * \brief          Set own certificate and key for the current handshake
01813  *
01814  * \note           Same as \c mbedtls_ssl_conf_own_cert() but for use within
01815  *                 the SNI callback.
01816  *
01817  * \param ssl      SSL context
01818  * \param own_cert own public certificate chain
01819  * \param pk_key   own private key
01820  *
01821  * \return         0 on success or MBEDTLS_ERR_SSL_ALLOC_FAILED
01822  */
01823 int mbedtls_ssl_set_hs_own_cert( mbedtls_ssl_context *ssl,
01824                                  mbedtls_x509_crt *own_cert,
01825                                  mbedtls_pk_context *pk_key );
01826 
01827 /**
01828  * \brief          Set the data required to verify peer certificate for the
01829  *                 current handshake
01830  *
01831  * \note           Same as \c mbedtls_ssl_conf_ca_chain() but for use within
01832  *                 the SNI callback.
01833  *
01834  * \param ssl      SSL context
01835  * \param ca_chain trusted CA chain (meaning all fully trusted top-level CAs)
01836  * \param ca_crl   trusted CA CRLs
01837  */
01838 void mbedtls_ssl_set_hs_ca_chain( mbedtls_ssl_context *ssl,
01839                                   mbedtls_x509_crt *ca_chain,
01840                                   mbedtls_x509_crl *ca_crl );
01841 
01842 /**
01843  * \brief          Set authmode for the current handshake.
01844  *
01845  * \note           Same as \c mbedtls_ssl_conf_authmode() but for use within
01846  *                 the SNI callback.
01847  *
01848  * \param ssl      SSL context
01849  * \param authmode MBEDTLS_SSL_VERIFY_NONE, MBEDTLS_SSL_VERIFY_OPTIONAL or
01850  *                 MBEDTLS_SSL_VERIFY_REQUIRED
01851  */
01852 void mbedtls_ssl_set_hs_authmode( mbedtls_ssl_context *ssl,
01853                                   int authmode );
01854 
01855 /**
01856  * \brief          Set server side ServerName TLS extension callback
01857  *                 (optional, server-side only).
01858  *
01859  *                 If set, the ServerName callback is called whenever the
01860  *                 server receives a ServerName TLS extension from the client
01861  *                 during a handshake. The ServerName callback has the
01862  *                 following parameters: (void *parameter, mbedtls_ssl_context *ssl,
01863  *                 const unsigned char *hostname, size_t len). If a suitable
01864  *                 certificate is found, the callback must set the
01865  *                 certificate(s) and key(s) to use with \c
01866  *                 mbedtls_ssl_set_hs_own_cert() (can be called repeatedly),
01867  *                 and may optionally adjust the CA and associated CRL with \c
01868  *                 mbedtls_ssl_set_hs_ca_chain() as well as the client
01869  *                 authentication mode with \c mbedtls_ssl_set_hs_authmode(),
01870  *                 then must return 0. If no matching name is found, the
01871  *                 callback must either set a default cert, or
01872  *                 return non-zero to abort the handshake at this point.
01873  *
01874  * \param conf     SSL configuration
01875  * \param f_sni    verification function
01876  * \param p_sni    verification parameter
01877  */
01878 void mbedtls_ssl_conf_sni( mbedtls_ssl_config *conf,
01879                   int (*f_sni)(void *, mbedtls_ssl_context *, const unsigned char *,
01880                                size_t),
01881                   void *p_sni );
01882 #endif /* MBEDTLS_SSL_SERVER_NAME_INDICATION */
01883 
01884 #if defined(MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED)
01885 /**
01886  * \brief          Set the EC J-PAKE password for current handshake.
01887  *
01888  * \note           An internal copy is made, and destroyed as soon as the
01889  *                 handshake is completed, or when the SSL context is reset or
01890  *                 freed.
01891  *
01892  * \note           The SSL context needs to be already set up. The right place
01893  *                 to call this function is between \c mbedtls_ssl_setup() or
01894  *                 \c mbedtls_ssl_reset() and \c mbedtls_ssl_handshake().
01895  *
01896  * \param ssl      SSL context
01897  * \param pw       EC J-PAKE password (pre-shared secret)
01898  * \param pw_len   length of pw in bytes
01899  *
01900  * \return         0 on success, or a negative error code.
01901  */
01902 int mbedtls_ssl_set_hs_ecjpake_password( mbedtls_ssl_context *ssl,
01903                                          const unsigned char *pw,
01904                                          size_t pw_len );
01905 #endif /*MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED */
01906 
01907 #if defined(MBEDTLS_SSL_ALPN)
01908 /**
01909  * \brief          Set the supported Application Layer Protocols.
01910  *
01911  * \param conf     SSL configuration
01912  * \param protos   Pointer to a NULL-terminated list of supported protocols,
01913  *                 in decreasing preference order. The pointer to the list is
01914  *                 recorded by the library for later reference as required, so
01915  *                 the lifetime of the table must be atleast as long as the
01916  *                 lifetime of the SSL configuration structure.
01917  *
01918  * \return         0 on success, or MBEDTLS_ERR_SSL_BAD_INPUT_DATA.
01919  */
01920 int mbedtls_ssl_conf_alpn_protocols( mbedtls_ssl_config *conf, const char **protos );
01921 
01922 /**
01923  * \brief          Get the name of the negotiated Application Layer Protocol.
01924  *                 This function should be called after the handshake is
01925  *                 completed.
01926  *
01927  * \param ssl      SSL context
01928  *
01929  * \return         Protcol name, or NULL if no protocol was negotiated.
01930  */
01931 const char *mbedtls_ssl_get_alpn_protocol( const mbedtls_ssl_context *ssl );
01932 #endif /* MBEDTLS_SSL_ALPN */
01933 
01934 /**
01935  * \brief          Set the maximum supported version sent from the client side
01936  *                 and/or accepted at the server side
01937  *                 (Default: MBEDTLS_SSL_MAX_MAJOR_VERSION, MBEDTLS_SSL_MAX_MINOR_VERSION)
01938  *
01939  * \note           This ignores ciphersuites from higher versions.
01940  *
01941  * \note           With DTLS, use MBEDTLS_SSL_MINOR_VERSION_2 for DTLS 1.0 and
01942  *                 MBEDTLS_SSL_MINOR_VERSION_3 for DTLS 1.2
01943  *
01944  * \param conf     SSL configuration
01945  * \param major    Major version number (only MBEDTLS_SSL_MAJOR_VERSION_3 supported)
01946  * \param minor    Minor version number (MBEDTLS_SSL_MINOR_VERSION_0,
01947  *                 MBEDTLS_SSL_MINOR_VERSION_1 and MBEDTLS_SSL_MINOR_VERSION_2,
01948  *                 MBEDTLS_SSL_MINOR_VERSION_3 supported)
01949  */
01950 void mbedtls_ssl_conf_max_version( mbedtls_ssl_config *conf, int major, int minor );
01951 
01952 /**
01953  * \brief          Set the minimum accepted SSL/TLS protocol version
01954  *                 (Default: TLS 1.0)
01955  *
01956  * \note           Input outside of the SSL_MAX_XXXXX_VERSION and
01957  *                 SSL_MIN_XXXXX_VERSION range is ignored.
01958  *
01959  * \note           MBEDTLS_SSL_MINOR_VERSION_0 (SSL v3) should be avoided.
01960  *
01961  * \note           With DTLS, use MBEDTLS_SSL_MINOR_VERSION_2 for DTLS 1.0 and
01962  *                 MBEDTLS_SSL_MINOR_VERSION_3 for DTLS 1.2
01963  *
01964  * \param conf     SSL configuration
01965  * \param major    Major version number (only MBEDTLS_SSL_MAJOR_VERSION_3 supported)
01966  * \param minor    Minor version number (MBEDTLS_SSL_MINOR_VERSION_0,
01967  *                 MBEDTLS_SSL_MINOR_VERSION_1 and MBEDTLS_SSL_MINOR_VERSION_2,
01968  *                 MBEDTLS_SSL_MINOR_VERSION_3 supported)
01969  */
01970 void mbedtls_ssl_conf_min_version( mbedtls_ssl_config *conf, int major, int minor );
01971 
01972 #if defined(MBEDTLS_SSL_FALLBACK_SCSV) && defined(MBEDTLS_SSL_CLI_C)
01973 /**
01974  * \brief          Set the fallback flag (client-side only).
01975  *                 (Default: MBEDTLS_SSL_IS_NOT_FALLBACK).
01976  *
01977  * \note           Set to MBEDTLS_SSL_IS_FALLBACK when preparing a fallback
01978  *                 connection, that is a connection with max_version set to a
01979  *                 lower value than the value you're willing to use. Such
01980  *                 fallback connections are not recommended but are sometimes
01981  *                 necessary to interoperate with buggy (version-intolerant)
01982  *                 servers.
01983  *
01984  * \warning        You should NOT set this to MBEDTLS_SSL_IS_FALLBACK for
01985  *                 non-fallback connections! This would appear to work for a
01986  *                 while, then cause failures when the server is upgraded to
01987  *                 support a newer TLS version.
01988  *
01989  * \param conf     SSL configuration
01990  * \param fallback MBEDTLS_SSL_IS_NOT_FALLBACK or MBEDTLS_SSL_IS_FALLBACK
01991  */
01992 void mbedtls_ssl_conf_fallback( mbedtls_ssl_config *conf, char fallback );
01993 #endif /* MBEDTLS_SSL_FALLBACK_SCSV && MBEDTLS_SSL_CLI_C */
01994 
01995 #if defined(MBEDTLS_SSL_ENCRYPT_THEN_MAC)
01996 /**
01997  * \brief           Enable or disable Encrypt-then-MAC
01998  *                  (Default: MBEDTLS_SSL_ETM_ENABLED)
01999  *
02000  * \note            This should always be enabled, it is a security
02001  *                  improvement, and should not cause any interoperability
02002  *                  issue (used only if the peer supports it too).
02003  *
02004  * \param conf      SSL configuration
02005  * \param etm       MBEDTLS_SSL_ETM_ENABLED or MBEDTLS_SSL_ETM_DISABLED
02006  */
02007 void mbedtls_ssl_conf_encrypt_then_mac( mbedtls_ssl_config *conf, char etm );
02008 #endif /* MBEDTLS_SSL_ENCRYPT_THEN_MAC */
02009 
02010 #if defined(MBEDTLS_SSL_EXTENDED_MASTER_SECRET)
02011 /**
02012  * \brief           Enable or disable Extended Master Secret negotiation.
02013  *                  (Default: MBEDTLS_SSL_EXTENDED_MS_ENABLED)
02014  *
02015  * \note            This should always be enabled, it is a security fix to the
02016  *                  protocol, and should not cause any interoperability issue
02017  *                  (used only if the peer supports it too).
02018  *
02019  * \param conf      SSL configuration
02020  * \param ems       MBEDTLS_SSL_EXTENDED_MS_ENABLED or MBEDTLS_SSL_EXTENDED_MS_DISABLED
02021  */
02022 void mbedtls_ssl_conf_extended_master_secret( mbedtls_ssl_config *conf, char ems );
02023 #endif /* MBEDTLS_SSL_EXTENDED_MASTER_SECRET */
02024 
02025 #if defined(MBEDTLS_ARC4_C)
02026 /**
02027  * \brief          Disable or enable support for RC4
02028  *                 (Default: MBEDTLS_SSL_ARC4_DISABLED)
02029  *
02030  * \warning        Use of RC4 in DTLS/TLS has been prohibited by RFC 7465
02031  *                 for security reasons. Use at your own risk.
02032  *
02033  * \note           This function is deprecated and will likely be removed in
02034  *                 a future version of the library.
02035  *                 RC4 is disabled by default at compile time and needs to be
02036  *                 actively enabled for use with legacy systems.
02037  *
02038  * \param conf     SSL configuration
02039  * \param arc4     MBEDTLS_SSL_ARC4_ENABLED or MBEDTLS_SSL_ARC4_DISABLED
02040  */
02041 void mbedtls_ssl_conf_arc4_support( mbedtls_ssl_config *conf, char arc4 );
02042 #endif /* MBEDTLS_ARC4_C */
02043 
02044 #if defined(MBEDTLS_SSL_SRV_C)
02045 /**
02046  * \brief          Whether to send a list of acceptable CAs in
02047  *                 CertificateRequest messages.
02048  *                 (Default: do send)
02049  *
02050  * \param conf     SSL configuration
02051  * \param cert_req_ca_list   MBEDTLS_SSL_CERT_REQ_CA_LIST_ENABLED or
02052  *                          MBEDTLS_SSL_CERT_REQ_CA_LIST_DISABLED
02053  */
02054 void mbedtls_ssl_conf_cert_req_ca_list( mbedtls_ssl_config *conf,
02055                                           char cert_req_ca_list );
02056 #endif /* MBEDTLS_SSL_SRV_C */
02057 
02058 #if defined(MBEDTLS_SSL_MAX_FRAGMENT_LENGTH)
02059 /**
02060  * \brief          Set the maximum fragment length to emit and/or negotiate
02061  *                 (Default: MBEDTLS_SSL_MAX_CONTENT_LEN, usually 2^14 bytes)
02062  *                 (Server: set maximum fragment length to emit,
02063  *                 usually negotiated by the client during handshake
02064  *                 (Client: set maximum fragment length to emit *and*
02065  *                 negotiate with the server during handshake)
02066  *
02067  * \param conf     SSL configuration
02068  * \param mfl_code Code for maximum fragment length (allowed values:
02069  *                 MBEDTLS_SSL_MAX_FRAG_LEN_512,  MBEDTLS_SSL_MAX_FRAG_LEN_1024,
02070  *                 MBEDTLS_SSL_MAX_FRAG_LEN_2048, MBEDTLS_SSL_MAX_FRAG_LEN_4096)
02071  *
02072  * \return         0 if successful or MBEDTLS_ERR_SSL_BAD_INPUT_DATA
02073  */
02074 int mbedtls_ssl_conf_max_frag_len( mbedtls_ssl_config *conf, unsigned char mfl_code );
02075 #endif /* MBEDTLS_SSL_MAX_FRAGMENT_LENGTH */
02076 
02077 #if defined(MBEDTLS_SSL_TRUNCATED_HMAC)
02078 /**
02079  * \brief          Activate negotiation of truncated HMAC
02080  *                 (Default: MBEDTLS_SSL_TRUNC_HMAC_DISABLED)
02081  *
02082  * \param conf     SSL configuration
02083  * \param truncate Enable or disable (MBEDTLS_SSL_TRUNC_HMAC_ENABLED or
02084  *                                    MBEDTLS_SSL_TRUNC_HMAC_DISABLED)
02085  */
02086 void mbedtls_ssl_conf_truncated_hmac( mbedtls_ssl_config *conf, int truncate );
02087 #endif /* MBEDTLS_SSL_TRUNCATED_HMAC */
02088 
02089 #if defined(MBEDTLS_SSL_CBC_RECORD_SPLITTING)
02090 /**
02091  * \brief          Enable / Disable 1/n-1 record splitting
02092  *                 (Default: MBEDTLS_SSL_CBC_RECORD_SPLITTING_ENABLED)
02093  *
02094  * \note           Only affects SSLv3 and TLS 1.0, not higher versions.
02095  *                 Does not affect non-CBC ciphersuites in any version.
02096  *
02097  * \param conf     SSL configuration
02098  * \param split    MBEDTLS_SSL_CBC_RECORD_SPLITTING_ENABLED or
02099  *                 MBEDTLS_SSL_CBC_RECORD_SPLITTING_DISABLED
02100  */
02101 void mbedtls_ssl_conf_cbc_record_splitting( mbedtls_ssl_config *conf, char split );
02102 #endif /* MBEDTLS_SSL_CBC_RECORD_SPLITTING */
02103 
02104 #if defined(MBEDTLS_SSL_SESSION_TICKETS) && defined(MBEDTLS_SSL_CLI_C)
02105 /**
02106  * \brief          Enable / Disable session tickets (client only).
02107  *                 (Default: MBEDTLS_SSL_SESSION_TICKETS_ENABLED.)
02108  *
02109  * \note           On server, use \c mbedtls_ssl_conf_session_tickets_cb().
02110  *
02111  * \param conf     SSL configuration
02112  * \param use_tickets   Enable or disable (MBEDTLS_SSL_SESSION_TICKETS_ENABLED or
02113  *                                         MBEDTLS_SSL_SESSION_TICKETS_DISABLED)
02114  */
02115 void mbedtls_ssl_conf_session_tickets( mbedtls_ssl_config *conf, int use_tickets );
02116 #endif /* MBEDTLS_SSL_SESSION_TICKETS && MBEDTLS_SSL_CLI_C */
02117 
02118 #if defined(MBEDTLS_SSL_RENEGOTIATION)
02119 /**
02120  * \brief          Enable / Disable renegotiation support for connection when
02121  *                 initiated by peer
02122  *                 (Default: MBEDTLS_SSL_RENEGOTIATION_DISABLED)
02123  *
02124  * \warning        It is recommended to always disable renegotation unless you
02125  *                 know you need it and you know what you're doing. In the
02126  *                 past, there have been several issues associated with
02127  *                 renegotiation or a poor understanding of its properties.
02128  *
02129  * \note           Server-side, enabling renegotiation also makes the server
02130  *                 susceptible to a resource DoS by a malicious client.
02131  *
02132  * \param conf    SSL configuration
02133  * \param renegotiation     Enable or disable (MBEDTLS_SSL_RENEGOTIATION_ENABLED or
02134  *                                             MBEDTLS_SSL_RENEGOTIATION_DISABLED)
02135  */
02136 void mbedtls_ssl_conf_renegotiation( mbedtls_ssl_config *conf, int renegotiation );
02137 #endif /* MBEDTLS_SSL_RENEGOTIATION */
02138 
02139 /**
02140  * \brief          Prevent or allow legacy renegotiation.
02141  *                 (Default: MBEDTLS_SSL_LEGACY_NO_RENEGOTIATION)
02142  *
02143  *                 MBEDTLS_SSL_LEGACY_NO_RENEGOTIATION allows connections to
02144  *                 be established even if the peer does not support
02145  *                 secure renegotiation, but does not allow renegotiation
02146  *                 to take place if not secure.
02147  *                 (Interoperable and secure option)
02148  *
02149  *                 MBEDTLS_SSL_LEGACY_ALLOW_RENEGOTIATION allows renegotiations
02150  *                 with non-upgraded peers. Allowing legacy renegotiation
02151  *                 makes the connection vulnerable to specific man in the
02152  *                 middle attacks. (See RFC 5746)
02153  *                 (Most interoperable and least secure option)
02154  *
02155  *                 MBEDTLS_SSL_LEGACY_BREAK_HANDSHAKE breaks off connections
02156  *                 if peer does not support secure renegotiation. Results
02157  *                 in interoperability issues with non-upgraded peers
02158  *                 that do not support renegotiation altogether.
02159  *                 (Most secure option, interoperability issues)
02160  *
02161  * \param conf     SSL configuration
02162  * \param allow_legacy  Prevent or allow (SSL_NO_LEGACY_RENEGOTIATION,
02163  *                                        SSL_ALLOW_LEGACY_RENEGOTIATION or
02164  *                                        MBEDTLS_SSL_LEGACY_BREAK_HANDSHAKE)
02165  */
02166 void mbedtls_ssl_conf_legacy_renegotiation( mbedtls_ssl_config *conf, int allow_legacy );
02167 
02168 #if defined(MBEDTLS_SSL_RENEGOTIATION)
02169 /**
02170  * \brief          Enforce renegotiation requests.
02171  *                 (Default: enforced, max_records = 16)
02172  *
02173  *                 When we request a renegotiation, the peer can comply or
02174  *                 ignore the request. This function allows us to decide
02175  *                 whether to enforce our renegotiation requests by closing
02176  *                 the connection if the peer doesn't comply.
02177  *
02178  *                 However, records could already be in transit from the peer
02179  *                 when the request is emitted. In order to increase
02180  *                 reliability, we can accept a number of records before the
02181  *                 expected handshake records.
02182  *
02183  *                 The optimal value is highly dependent on the specific usage
02184  *                 scenario.
02185  *
02186  * \note           With DTLS and server-initiated renegotiation, the
02187  *                 HelloRequest is retransmited every time mbedtls_ssl_read() times
02188  *                 out or receives Application Data, until:
02189  *                 - max_records records have beens seen, if it is >= 0, or
02190  *                 - the number of retransmits that would happen during an
02191  *                 actual handshake has been reached.
02192  *                 Please remember the request might be lost a few times
02193  *                 if you consider setting max_records to a really low value.
02194  *
02195  * \warning        On client, the grace period can only happen during
02196  *                 mbedtls_ssl_read(), as opposed to mbedtls_ssl_write() and mbedtls_ssl_renegotiate()
02197  *                 which always behave as if max_record was 0. The reason is,
02198  *                 if we receive application data from the server, we need a
02199  *                 place to write it, which only happens during mbedtls_ssl_read().
02200  *
02201  * \param conf     SSL configuration
02202  * \param max_records Use MBEDTLS_SSL_RENEGOTIATION_NOT_ENFORCED if you don't want to
02203  *                 enforce renegotiation, or a non-negative value to enforce
02204  *                 it but allow for a grace period of max_records records.
02205  */
02206 void mbedtls_ssl_conf_renegotiation_enforced( mbedtls_ssl_config *conf, int max_records );
02207 
02208 /**
02209  * \brief          Set record counter threshold for periodic renegotiation.
02210  *                 (Default: 2^48 - 1)
02211  *
02212  *                 Renegotiation is automatically triggered when a record
02213  *                 counter (outgoing or ingoing) crosses the defined
02214  *                 threshold. The default value is meant to prevent the
02215  *                 connection from being closed when the counter is about to
02216  *                 reached its maximal value (it is not allowed to wrap).
02217  *
02218  *                 Lower values can be used to enforce policies such as "keys
02219  *                 must be refreshed every N packets with cipher X".
02220  *
02221  *                 The renegotiation period can be disabled by setting
02222  *                 conf->disable_renegotiation to
02223  *                 MBEDTLS_SSL_RENEGOTIATION_DISABLED.
02224  *
02225  * \note           When the configured transport is
02226  *                 MBEDTLS_SSL_TRANSPORT_DATAGRAM the maximum renegotiation
02227  *                 period is 2^48 - 1, and for MBEDTLS_SSL_TRANSPORT_STREAM,
02228  *                 the maximum renegotiation period is 2^64 - 1.
02229  *
02230  * \param conf     SSL configuration
02231  * \param period   The threshold value: a big-endian 64-bit number.
02232  */
02233 void mbedtls_ssl_conf_renegotiation_period( mbedtls_ssl_config *conf,
02234                                    const unsigned char period[8] );
02235 #endif /* MBEDTLS_SSL_RENEGOTIATION */
02236 
02237 /**
02238  * \brief          Return the number of data bytes available to read
02239  *
02240  * \param ssl      SSL context
02241  *
02242  * \return         how many bytes are available in the read buffer
02243  */
02244 size_t mbedtls_ssl_get_bytes_avail( const mbedtls_ssl_context *ssl );
02245 
02246 /**
02247  * \brief          Return the result of the certificate verification
02248  *
02249  * \param ssl      SSL context
02250  *
02251  * \return         0 if successful,
02252  *                 -1 if result is not available (eg because the handshake was
02253  *                 aborted too early), or
02254  *                 a combination of BADCERT_xxx and BADCRL_xxx flags, see
02255  *                 x509.h
02256  */
02257 uint32_t mbedtls_ssl_get_verify_result( const mbedtls_ssl_context *ssl );
02258 
02259 /**
02260  * \brief          Return the name of the current ciphersuite
02261  *
02262  * \param ssl      SSL context
02263  *
02264  * \return         a string containing the ciphersuite name
02265  */
02266 const char *mbedtls_ssl_get_ciphersuite( const mbedtls_ssl_context *ssl );
02267 
02268 /**
02269  * \brief          Return the current SSL version (SSLv3/TLSv1/etc)
02270  *
02271  * \param ssl      SSL context
02272  *
02273  * \return         a string containing the SSL version
02274  */
02275 const char *mbedtls_ssl_get_version( const mbedtls_ssl_context *ssl );
02276 
02277 /**
02278  * \brief          Return the (maximum) number of bytes added by the record
02279  *                 layer: header + encryption/MAC overhead (inc. padding)
02280  *
02281  * \param ssl      SSL context
02282  *
02283  * \return         Current maximum record expansion in bytes, or
02284  *                 MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE if compression is
02285  *                 enabled, which makes expansion much less predictable
02286  */
02287 int mbedtls_ssl_get_record_expansion( const mbedtls_ssl_context *ssl );
02288 
02289 #if defined(MBEDTLS_SSL_MAX_FRAGMENT_LENGTH)
02290 /**
02291  * \brief          Return the maximum fragment length (payload, in bytes).
02292  *                 This is the value negotiated with peer if any,
02293  *                 or the locally configured value.
02294  *
02295  * \note           With DTLS, \c mbedtls_ssl_write() will return an error if
02296  *                 called with a larger length value.
02297  *                 With TLS, \c mbedtls_ssl_write() will fragment the input if
02298  *                 necessary and return the number of bytes written; it is up
02299  *                 to the caller to call \c mbedtls_ssl_write() again in
02300  *                 order to send the remaining bytes if any.
02301  *
02302  * \param ssl      SSL context
02303  *
02304  * \return         Current maximum fragment length.
02305  */
02306 size_t mbedtls_ssl_get_max_frag_len( const mbedtls_ssl_context *ssl );
02307 #endif /* MBEDTLS_SSL_MAX_FRAGMENT_LENGTH */
02308 
02309 #if defined(MBEDTLS_X509_CRT_PARSE_C)
02310 /**
02311  * \brief          Return the peer certificate from the current connection
02312  *
02313  *                 Note: Can be NULL in case no certificate was sent during
02314  *                 the handshake. Different calls for the same connection can
02315  *                 return the same or different pointers for the same
02316  *                 certificate and even a different certificate altogether.
02317  *                 The peer cert CAN change in a single connection if
02318  *                 renegotiation is performed.
02319  *
02320  * \param ssl      SSL context
02321  *
02322  * \return         the current peer certificate
02323  */
02324 const mbedtls_x509_crt *mbedtls_ssl_get_peer_cert( const mbedtls_ssl_context *ssl );
02325 #endif /* MBEDTLS_X509_CRT_PARSE_C */
02326 
02327 #if defined(MBEDTLS_SSL_CLI_C)
02328 /**
02329  * \brief          Save session in order to resume it later (client-side only)
02330  *                 Session data is copied to presented session structure.
02331  *
02332  * \warning        Currently, peer certificate is lost in the operation.
02333  *
02334  * \param ssl      SSL context
02335  * \param session  session context
02336  *
02337  * \return         0 if successful,
02338  *                 MBEDTLS_ERR_SSL_ALLOC_FAILED if memory allocation failed,
02339  *                 MBEDTLS_ERR_SSL_BAD_INPUT_DATA if used server-side or
02340  *                 arguments are otherwise invalid
02341  *
02342  * \sa             mbedtls_ssl_set_session()
02343  */
02344 int mbedtls_ssl_get_session( const mbedtls_ssl_context *ssl, mbedtls_ssl_session *session );
02345 #endif /* MBEDTLS_SSL_CLI_C */
02346 
02347 /**
02348  * \brief          Perform the SSL handshake
02349  *
02350  * \param ssl      SSL context
02351  *
02352  * \return         0 if successful, or
02353  *                 MBEDTLS_ERR_SSL_WANT_READ or MBEDTLS_ERR_SSL_WANT_WRITE, or
02354  *                 MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED (see below), or
02355  *                 a specific SSL error code.
02356  *
02357  * \note           If this function returns something other than 0 or
02358  *                 MBEDTLS_ERR_SSL_WANT_READ/WRITE, then the ssl context
02359  *                 becomes unusable, and you should either free it or call
02360  *                 \c mbedtls_ssl_session_reset() on it before re-using it for
02361  *                 a new connection; the current connection must be closed.
02362  *
02363  * \note           If DTLS is in use, then you may choose to handle
02364  *                 MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED specially for logging
02365  *                 purposes, as it is an expected return value rather than an
02366  *                 actual error, but you still need to reset/free the context.
02367  */
02368 int mbedtls_ssl_handshake( mbedtls_ssl_context *ssl );
02369 
02370 /**
02371  * \brief          Perform a single step of the SSL handshake
02372  *
02373  * \note           The state of the context (ssl->state) will be at
02374  *                 the next state after execution of this function. Do not
02375  *                 call this function if state is MBEDTLS_SSL_HANDSHAKE_OVER.
02376  *
02377  * \note           If this function returns something other than 0 or
02378  *                 MBEDTLS_ERR_SSL_WANT_READ/WRITE, then the ssl context
02379  *                 becomes unusable, and you should either free it or call
02380  *                 \c mbedtls_ssl_session_reset() on it before re-using it for
02381  *                 a new connection; the current connection must be closed.
02382  *
02383  * \param ssl      SSL context
02384  *
02385  * \return         0 if successful, or
02386  *                 MBEDTLS_ERR_SSL_WANT_READ or MBEDTLS_ERR_SSL_WANT_WRITE, or
02387  *                 a specific SSL error code.
02388  */
02389 int mbedtls_ssl_handshake_step( mbedtls_ssl_context *ssl );
02390 
02391 #if defined(MBEDTLS_SSL_RENEGOTIATION)
02392 /**
02393  * \brief          Initiate an SSL renegotiation on the running connection.
02394  *                 Client: perform the renegotiation right now.
02395  *                 Server: request renegotiation, which will be performed
02396  *                 during the next call to mbedtls_ssl_read() if honored by
02397  *                 client.
02398  *
02399  * \param ssl      SSL context
02400  *
02401  * \return         0 if successful, or any mbedtls_ssl_handshake() return
02402  *                 value.
02403  *
02404  * \note           If this function returns something other than 0 or
02405  *                 MBEDTLS_ERR_SSL_WANT_READ/WRITE, then the ssl context
02406  *                 becomes unusable, and you should either free it or call
02407  *                 \c mbedtls_ssl_session_reset() on it before re-using it for
02408  *                 a new connection; the current connection must be closed.
02409  */
02410 int mbedtls_ssl_renegotiate( mbedtls_ssl_context *ssl );
02411 #endif /* MBEDTLS_SSL_RENEGOTIATION */
02412 
02413 /**
02414  * \brief          Read at most 'len' application data bytes
02415  *
02416  * \param ssl      SSL context
02417  * \param buf      buffer that will hold the data
02418  * \param len      maximum number of bytes to read
02419  *
02420  * \return         the number of bytes read, or
02421  *                 0 for EOF, or
02422  *                 MBEDTLS_ERR_SSL_WANT_READ or MBEDTLS_ERR_SSL_WANT_WRITE, or
02423  *                 MBEDTLS_ERR_SSL_CLIENT_RECONNECT (see below), or
02424  *                 another negative error code.
02425  *
02426  * \note           If this function returns something other than a positive
02427  *                 value or MBEDTLS_ERR_SSL_WANT_READ/WRITE or
02428  *                 MBEDTLS_ERR_SSL_CLIENT_RECONNECT, then the ssl context
02429  *                 becomes unusable, and you should either free it or call
02430  *                 \c mbedtls_ssl_session_reset() on it before re-using it for
02431  *                 a new connection; the current connection must be closed.
02432  *
02433  * \note           When this function return MBEDTLS_ERR_SSL_CLIENT_RECONNECT
02434  *                 (which can only happen server-side), it means that a client
02435  *                 is initiating a new connection using the same source port.
02436  *                 You can either treat that as a connection close and wait
02437  *                 for the client to resend a ClientHello, or directly
02438  *                 continue with \c mbedtls_ssl_handshake() with the same
02439  *                 context (as it has beeen reset internally). Either way, you
02440  *                 should make sure this is seen by the application as a new
02441  *                 connection: application state, if any, should be reset, and
02442  *                 most importantly the identity of the client must be checked
02443  *                 again. WARNING: not validating the identity of the client
02444  *                 again, or not transmitting the new identity to the
02445  *                 application layer, would allow authentication bypass!
02446  */
02447 int mbedtls_ssl_read( mbedtls_ssl_context *ssl, unsigned char *buf, size_t len );
02448 
02449 /**
02450  * \brief          Try to write exactly 'len' application data bytes
02451  *
02452  * \warning        This function will do partial writes in some cases. If the
02453  *                 return value is non-negative but less than length, the
02454  *                 function must be called again with updated arguments:
02455  *                 buf + ret, len - ret (if ret is the return value) until
02456  *                 it returns a value equal to the last 'len' argument.
02457  *
02458  * \param ssl      SSL context
02459  * \param buf      buffer holding the data
02460  * \param len      how many bytes must be written
02461  *
02462  * \return         the number of bytes actually written (may be less than len),
02463  *                 or MBEDTLS_ERR_SSL_WANT_WRITE or MBEDTLS_ERR_SSL_WANT_READ,
02464  *                 or another negative error code.
02465  *
02466  * \note           If this function returns something other than a positive
02467  *                 value or MBEDTLS_ERR_SSL_WANT_READ/WRITE, the ssl context
02468  *                 becomes unusable, and you should either free it or call
02469  *                 \c mbedtls_ssl_session_reset() on it before re-using it for
02470  *                 a new connection; the current connection must be closed.
02471  *
02472  * \note           When this function returns MBEDTLS_ERR_SSL_WANT_WRITE/READ,
02473  *                 it must be called later with the *same* arguments,
02474  *                 until it returns a positive value.
02475  *
02476  * \note           If the requested length is greater than the maximum
02477  *                 fragment length (either the built-in limit or the one set
02478  *                 or negotiated with the peer), then:
02479  *                 - with TLS, less bytes than requested are written.
02480  *                 - with DTLS, MBEDTLS_ERR_SSL_BAD_INPUT_DATA is returned.
02481  *                 \c mbedtls_ssl_get_max_frag_len() may be used to query the
02482  *                 active maximum fragment length.
02483  */
02484 int mbedtls_ssl_write( mbedtls_ssl_context *ssl, const unsigned char *buf, size_t len );
02485 
02486 /**
02487  * \brief           Send an alert message
02488  *
02489  * \param ssl       SSL context
02490  * \param level     The alert level of the message
02491  *                  (MBEDTLS_SSL_ALERT_LEVEL_WARNING or MBEDTLS_SSL_ALERT_LEVEL_FATAL)
02492  * \param message   The alert message (SSL_ALERT_MSG_*)
02493  *
02494  * \return          0 if successful, or a specific SSL error code.
02495  *
02496  * \note           If this function returns something other than 0 or
02497  *                 MBEDTLS_ERR_SSL_WANT_READ/WRITE, then the ssl context
02498  *                 becomes unusable, and you should either free it or call
02499  *                 \c mbedtls_ssl_session_reset() on it before re-using it for
02500  *                 a new connection; the current connection must be closed.
02501  */
02502 int mbedtls_ssl_send_alert_message( mbedtls_ssl_context *ssl,
02503                             unsigned char level,
02504                             unsigned char message );
02505 /**
02506  * \brief          Notify the peer that the connection is being closed
02507  *
02508  * \param ssl      SSL context
02509  *
02510  * \return          0 if successful, or a specific SSL error code.
02511  *
02512  * \note           If this function returns something other than 0 or
02513  *                 MBEDTLS_ERR_SSL_WANT_READ/WRITE, then the ssl context
02514  *                 becomes unusable, and you should either free it or call
02515  *                 \c mbedtls_ssl_session_reset() on it before re-using it for
02516  *                 a new connection; the current connection must be closed.
02517  */
02518 int mbedtls_ssl_close_notify( mbedtls_ssl_context *ssl );
02519 
02520 /**
02521  * \brief          Free referenced items in an SSL context and clear memory
02522  *
02523  * \param ssl      SSL context
02524  */
02525 void mbedtls_ssl_free( mbedtls_ssl_context *ssl );
02526 
02527 /**
02528  * \brief          Initialize an SSL configuration context
02529  *                 Just makes the context ready for
02530  *                 mbedtls_ssl_config_defaults() or mbedtls_ssl_config_free().
02531  *
02532  * \note           You need to call mbedtls_ssl_config_defaults() unless you
02533  *                 manually set all of the relevent fields yourself.
02534  *
02535  * \param conf     SSL configuration context
02536  */
02537 void mbedtls_ssl_config_init( mbedtls_ssl_config *conf );
02538 
02539 /**
02540  * \brief          Load reasonnable default SSL configuration values.
02541  *                 (You need to call mbedtls_ssl_config_init() first.)
02542  *
02543  * \param conf     SSL configuration context
02544  * \param endpoint MBEDTLS_SSL_IS_CLIENT or MBEDTLS_SSL_IS_SERVER
02545  * \param transport MBEDTLS_SSL_TRANSPORT_STREAM for TLS, or
02546  *                  MBEDTLS_SSL_TRANSPORT_DATAGRAM for DTLS
02547  * \param preset   a MBEDTLS_SSL_PRESET_XXX value
02548  *
02549  * \note           See \c mbedtls_ssl_conf_transport() for notes on DTLS.
02550  *
02551  * \return         0 if successful, or
02552  *                 MBEDTLS_ERR_XXX_ALLOC_FAILED on memory allocation error.
02553  */
02554 int mbedtls_ssl_config_defaults( mbedtls_ssl_config *conf,
02555                                  int endpoint, int transport, int preset );
02556 
02557 /**
02558  * \brief          Free an SSL configuration context
02559  *
02560  * \param conf     SSL configuration context
02561  */
02562 void mbedtls_ssl_config_free( mbedtls_ssl_config *conf );
02563 
02564 /**
02565  * \brief          Initialize SSL session structure
02566  *
02567  * \param session  SSL session
02568  */
02569 void mbedtls_ssl_session_init( mbedtls_ssl_session *session );
02570 
02571 /**
02572  * \brief          Free referenced items in an SSL session including the
02573  *                 peer certificate and clear memory
02574  *
02575  * \param session  SSL session
02576  */
02577 void mbedtls_ssl_session_free( mbedtls_ssl_session *session );
02578 
02579 #ifdef __cplusplus
02580 }
02581 #endif
02582 
02583 #endif /* ssl.h */