ssl.h

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