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