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