Kenji Arai
/
mbed-os_TYBLE16
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.
Dependents: TYBLE16_simple_data_logger TYBLE16_MP3_Air
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 /* 00007 * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved 00008 * SPDX-License-Identifier: Apache-2.0 00009 * 00010 * Licensed under the Apache License, Version 2.0 (the "License"); you may 00011 * not use this file except in compliance with the License. 00012 * You may obtain a copy of the License at 00013 * 00014 * http://www.apache.org/licenses/LICENSE-2.0 00015 * 00016 * Unless required by applicable law or agreed to in writing, software 00017 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 00018 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00019 * See the License for the specific language governing permissions and 00020 * limitations under the License. 00021 * 00022 * This file is part of mbed TLS (https://tls.mbed.org) 00023 */ 00024 #ifndef MBEDTLS_SSL_H 00025 #define MBEDTLS_SSL_H 00026 00027 #if !defined(MBEDTLS_CONFIG_FILE) 00028 #include "mbedtls/config.h" 00029 #else 00030 #include MBEDTLS_CONFIG_FILE 00031 #endif 00032 00033 #include "mbedtls/bignum.h" 00034 #include "mbedtls/ecp.h" 00035 00036 #include "mbedtls/ssl_ciphersuites.h" 00037 00038 #if defined(MBEDTLS_X509_CRT_PARSE_C) 00039 #include "mbedtls/x509_crt.h" 00040 #include "mbedtls/x509_crl.h" 00041 #endif 00042 00043 #if defined(MBEDTLS_DHM_C) 00044 #include "mbedtls/dhm.h" 00045 #endif 00046 00047 #if defined(MBEDTLS_ECDH_C) 00048 #include "mbedtls/ecdh.h" 00049 #endif 00050 00051 #if defined(MBEDTLS_ZLIB_SUPPORT) 00052 00053 #if defined(MBEDTLS_DEPRECATED_WARNING) 00054 #warning "Record compression support via MBEDTLS_ZLIB_SUPPORT is deprecated and will be removed in the next major revision of the library" 00055 #endif 00056 00057 #if defined(MBEDTLS_DEPRECATED_REMOVED) 00058 #error "Record compression support via MBEDTLS_ZLIB_SUPPORT is deprecated and cannot be used if MBEDTLS_DEPRECATED_REMOVED is set" 00059 #endif 00060 00061 #include "zlib.h" 00062 #endif 00063 00064 #if defined(MBEDTLS_HAVE_TIME) 00065 #include "mbedtls/platform_time.h" 00066 #endif 00067 00068 #if defined(MBEDTLS_USE_PSA_CRYPTO) 00069 #include "psa/crypto.h" 00070 #endif /* MBEDTLS_USE_PSA_CRYPTO */ 00071 00072 /* 00073 * SSL Error codes 00074 */ 00075 #define MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE -0x7080 /**< The requested feature is not available. */ 00076 #define MBEDTLS_ERR_SSL_BAD_INPUT_DATA -0x7100 /**< Bad input parameters to function. */ 00077 #define MBEDTLS_ERR_SSL_INVALID_MAC -0x7180 /**< Verification of the message MAC failed. */ 00078 #define MBEDTLS_ERR_SSL_INVALID_RECORD -0x7200 /**< An invalid SSL record was received. */ 00079 #define MBEDTLS_ERR_SSL_CONN_EOF -0x7280 /**< The connection indicated an EOF. */ 00080 #define MBEDTLS_ERR_SSL_UNKNOWN_CIPHER -0x7300 /**< An unknown cipher was received. */ 00081 #define MBEDTLS_ERR_SSL_NO_CIPHER_CHOSEN -0x7380 /**< The server has no ciphersuites in common with the client. */ 00082 #define MBEDTLS_ERR_SSL_NO_RNG -0x7400 /**< No RNG was provided to the SSL module. */ 00083 #define MBEDTLS_ERR_SSL_NO_CLIENT_CERTIFICATE -0x7480 /**< No client certification received from the client, but required by the authentication mode. */ 00084 #define MBEDTLS_ERR_SSL_CERTIFICATE_TOO_LARGE -0x7500 /**< Our own certificate(s) is/are too large to send in an SSL message. */ 00085 #define MBEDTLS_ERR_SSL_CERTIFICATE_REQUIRED -0x7580 /**< The own certificate is not set, but needed by the server. */ 00086 #define MBEDTLS_ERR_SSL_PRIVATE_KEY_REQUIRED -0x7600 /**< The own private key or pre-shared key is not set, but needed. */ 00087 #define MBEDTLS_ERR_SSL_CA_CHAIN_REQUIRED -0x7680 /**< No CA Chain is set, but required to operate. */ 00088 #define MBEDTLS_ERR_SSL_UNEXPECTED_MESSAGE -0x7700 /**< An unexpected message was received from our peer. */ 00089 #define MBEDTLS_ERR_SSL_FATAL_ALERT_MESSAGE -0x7780 /**< A fatal alert message was received from our peer. */ 00090 #define MBEDTLS_ERR_SSL_PEER_VERIFY_FAILED -0x7800 /**< Verification of our peer failed. */ 00091 #define MBEDTLS_ERR_SSL_PEER_CLOSE_NOTIFY -0x7880 /**< The peer notified us that the connection is going to be closed. */ 00092 #define MBEDTLS_ERR_SSL_BAD_HS_CLIENT_HELLO -0x7900 /**< Processing of the ClientHello handshake message failed. */ 00093 #define MBEDTLS_ERR_SSL_BAD_HS_SERVER_HELLO -0x7980 /**< Processing of the ServerHello handshake message failed. */ 00094 #define MBEDTLS_ERR_SSL_BAD_HS_CERTIFICATE -0x7A00 /**< Processing of the Certificate handshake message failed. */ 00095 #define MBEDTLS_ERR_SSL_BAD_HS_CERTIFICATE_REQUEST -0x7A80 /**< Processing of the CertificateRequest handshake message failed. */ 00096 #define MBEDTLS_ERR_SSL_BAD_HS_SERVER_KEY_EXCHANGE -0x7B00 /**< Processing of the ServerKeyExchange handshake message failed. */ 00097 #define MBEDTLS_ERR_SSL_BAD_HS_SERVER_HELLO_DONE -0x7B80 /**< Processing of the ServerHelloDone handshake message failed. */ 00098 #define MBEDTLS_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE -0x7C00 /**< Processing of the ClientKeyExchange handshake message failed. */ 00099 #define MBEDTLS_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE_RP -0x7C80 /**< Processing of the ClientKeyExchange handshake message failed in DHM / ECDH Read Public. */ 00100 #define MBEDTLS_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE_CS -0x7D00 /**< Processing of the ClientKeyExchange handshake message failed in DHM / ECDH Calculate Secret. */ 00101 #define MBEDTLS_ERR_SSL_BAD_HS_CERTIFICATE_VERIFY -0x7D80 /**< Processing of the CertificateVerify handshake message failed. */ 00102 #define MBEDTLS_ERR_SSL_BAD_HS_CHANGE_CIPHER_SPEC -0x7E00 /**< Processing of the ChangeCipherSpec handshake message failed. */ 00103 #define MBEDTLS_ERR_SSL_BAD_HS_FINISHED -0x7E80 /**< Processing of the Finished handshake message failed. */ 00104 #define MBEDTLS_ERR_SSL_ALLOC_FAILED -0x7F00 /**< Memory allocation failed */ 00105 #define MBEDTLS_ERR_SSL_HW_ACCEL_FAILED -0x7F80 /**< Hardware acceleration function returned with error */ 00106 #define MBEDTLS_ERR_SSL_HW_ACCEL_FALLTHROUGH -0x6F80 /**< Hardware acceleration function skipped / left alone data */ 00107 #define MBEDTLS_ERR_SSL_COMPRESSION_FAILED -0x6F00 /**< Processing of the compression / decompression failed */ 00108 #define MBEDTLS_ERR_SSL_BAD_HS_PROTOCOL_VERSION -0x6E80 /**< Handshake protocol not within min/max boundaries */ 00109 #define MBEDTLS_ERR_SSL_BAD_HS_NEW_SESSION_TICKET -0x6E00 /**< Processing of the NewSessionTicket handshake message failed. */ 00110 #define MBEDTLS_ERR_SSL_SESSION_TICKET_EXPIRED -0x6D80 /**< Session ticket has expired. */ 00111 #define MBEDTLS_ERR_SSL_PK_TYPE_MISMATCH -0x6D00 /**< Public key type mismatch (eg, asked for RSA key exchange and presented EC key) */ 00112 #define MBEDTLS_ERR_SSL_UNKNOWN_IDENTITY -0x6C80 /**< Unknown identity received (eg, PSK identity) */ 00113 #define MBEDTLS_ERR_SSL_INTERNAL_ERROR -0x6C00 /**< Internal error (eg, unexpected failure in lower-level module) */ 00114 #define MBEDTLS_ERR_SSL_COUNTER_WRAPPING -0x6B80 /**< A counter would wrap (eg, too many messages exchanged). */ 00115 #define MBEDTLS_ERR_SSL_WAITING_SERVER_HELLO_RENEGO -0x6B00 /**< Unexpected message at ServerHello in renegotiation. */ 00116 #define MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED -0x6A80 /**< DTLS client must retry for hello verification */ 00117 #define MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL -0x6A00 /**< A buffer is too small to receive or write a message */ 00118 #define MBEDTLS_ERR_SSL_NO_USABLE_CIPHERSUITE -0x6980 /**< None of the common ciphersuites is usable (eg, no suitable certificate, see debug messages). */ 00119 #define MBEDTLS_ERR_SSL_WANT_READ -0x6900 /**< No data of requested type currently available on underlying transport. */ 00120 #define MBEDTLS_ERR_SSL_WANT_WRITE -0x6880 /**< Connection requires a write call. */ 00121 #define MBEDTLS_ERR_SSL_TIMEOUT -0x6800 /**< The operation timed out. */ 00122 #define MBEDTLS_ERR_SSL_CLIENT_RECONNECT -0x6780 /**< The client initiated a reconnect from the same port. */ 00123 #define MBEDTLS_ERR_SSL_UNEXPECTED_RECORD -0x6700 /**< Record header looks valid but is not expected. */ 00124 #define MBEDTLS_ERR_SSL_NON_FATAL -0x6680 /**< The alert message received indicates a non-fatal error. */ 00125 #define MBEDTLS_ERR_SSL_INVALID_VERIFY_HASH -0x6600 /**< Couldn't set the hash for verifying CertificateVerify */ 00126 #define MBEDTLS_ERR_SSL_CONTINUE_PROCESSING -0x6580 /**< Internal-only message signaling that further message-processing should be done */ 00127 #define MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS -0x6500 /**< The asynchronous operation is not completed yet. */ 00128 #define MBEDTLS_ERR_SSL_EARLY_MESSAGE -0x6480 /**< Internal-only message signaling that a message arrived early. */ 00129 #define MBEDTLS_ERR_SSL_UNEXPECTED_CID -0x6000 /**< An encrypted DTLS-frame with an unexpected CID was received. */ 00130 #define MBEDTLS_ERR_SSL_VERSION_MISMATCH -0x5F00 /**< An operation failed due to an unexpected version or configuration. */ 00131 #define MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS -0x7000 /**< A cryptographic operation is in progress. Try again later. */ 00132 00133 /* 00134 * Various constants 00135 */ 00136 #define MBEDTLS_SSL_MAJOR_VERSION_3 3 00137 #define MBEDTLS_SSL_MINOR_VERSION_0 0 /*!< SSL v3.0 */ 00138 #define MBEDTLS_SSL_MINOR_VERSION_1 1 /*!< TLS v1.0 */ 00139 #define MBEDTLS_SSL_MINOR_VERSION_2 2 /*!< TLS v1.1 */ 00140 #define MBEDTLS_SSL_MINOR_VERSION_3 3 /*!< TLS v1.2 */ 00141 00142 #define MBEDTLS_SSL_TRANSPORT_STREAM 0 /*!< TLS */ 00143 #define MBEDTLS_SSL_TRANSPORT_DATAGRAM 1 /*!< DTLS */ 00144 00145 #define MBEDTLS_SSL_MAX_HOST_NAME_LEN 255 /*!< Maximum host name defined in RFC 1035 */ 00146 00147 /* RFC 6066 section 4, see also mfl_code_to_length in ssl_tls.c 00148 * NONE must be zero so that memset()ing structure to zero works */ 00149 #define MBEDTLS_SSL_MAX_FRAG_LEN_NONE 0 /*!< don't use this extension */ 00150 #define MBEDTLS_SSL_MAX_FRAG_LEN_512 1 /*!< MaxFragmentLength 2^9 */ 00151 #define MBEDTLS_SSL_MAX_FRAG_LEN_1024 2 /*!< MaxFragmentLength 2^10 */ 00152 #define MBEDTLS_SSL_MAX_FRAG_LEN_2048 3 /*!< MaxFragmentLength 2^11 */ 00153 #define MBEDTLS_SSL_MAX_FRAG_LEN_4096 4 /*!< MaxFragmentLength 2^12 */ 00154 #define MBEDTLS_SSL_MAX_FRAG_LEN_INVALID 5 /*!< first invalid value */ 00155 00156 #define MBEDTLS_SSL_IS_CLIENT 0 00157 #define MBEDTLS_SSL_IS_SERVER 1 00158 00159 #define MBEDTLS_SSL_IS_NOT_FALLBACK 0 00160 #define MBEDTLS_SSL_IS_FALLBACK 1 00161 00162 #define MBEDTLS_SSL_EXTENDED_MS_DISABLED 0 00163 #define MBEDTLS_SSL_EXTENDED_MS_ENABLED 1 00164 00165 #define MBEDTLS_SSL_CID_DISABLED 0 00166 #define MBEDTLS_SSL_CID_ENABLED 1 00167 00168 #define MBEDTLS_SSL_ETM_DISABLED 0 00169 #define MBEDTLS_SSL_ETM_ENABLED 1 00170 00171 #define MBEDTLS_SSL_COMPRESS_NULL 0 00172 #define MBEDTLS_SSL_COMPRESS_DEFLATE 1 00173 00174 #define MBEDTLS_SSL_VERIFY_NONE 0 00175 #define MBEDTLS_SSL_VERIFY_OPTIONAL 1 00176 #define MBEDTLS_SSL_VERIFY_REQUIRED 2 00177 #define MBEDTLS_SSL_VERIFY_UNSET 3 /* Used only for sni_authmode */ 00178 00179 #define MBEDTLS_SSL_LEGACY_RENEGOTIATION 0 00180 #define MBEDTLS_SSL_SECURE_RENEGOTIATION 1 00181 00182 #define MBEDTLS_SSL_RENEGOTIATION_DISABLED 0 00183 #define MBEDTLS_SSL_RENEGOTIATION_ENABLED 1 00184 00185 #define MBEDTLS_SSL_ANTI_REPLAY_DISABLED 0 00186 #define MBEDTLS_SSL_ANTI_REPLAY_ENABLED 1 00187 00188 #define MBEDTLS_SSL_RENEGOTIATION_NOT_ENFORCED -1 00189 #define MBEDTLS_SSL_RENEGO_MAX_RECORDS_DEFAULT 16 00190 00191 #define MBEDTLS_SSL_LEGACY_NO_RENEGOTIATION 0 00192 #define MBEDTLS_SSL_LEGACY_ALLOW_RENEGOTIATION 1 00193 #define MBEDTLS_SSL_LEGACY_BREAK_HANDSHAKE 2 00194 00195 #define MBEDTLS_SSL_TRUNC_HMAC_DISABLED 0 00196 #define MBEDTLS_SSL_TRUNC_HMAC_ENABLED 1 00197 #define MBEDTLS_SSL_TRUNCATED_HMAC_LEN 10 /* 80 bits, rfc 6066 section 7 */ 00198 00199 #define MBEDTLS_SSL_SESSION_TICKETS_DISABLED 0 00200 #define MBEDTLS_SSL_SESSION_TICKETS_ENABLED 1 00201 00202 #define MBEDTLS_SSL_CBC_RECORD_SPLITTING_DISABLED 0 00203 #define MBEDTLS_SSL_CBC_RECORD_SPLITTING_ENABLED 1 00204 00205 #define MBEDTLS_SSL_ARC4_ENABLED 0 00206 #define MBEDTLS_SSL_ARC4_DISABLED 1 00207 00208 #define MBEDTLS_SSL_PRESET_DEFAULT 0 00209 #define MBEDTLS_SSL_PRESET_SUITEB 2 00210 00211 #define MBEDTLS_SSL_CERT_REQ_CA_LIST_ENABLED 1 00212 #define MBEDTLS_SSL_CERT_REQ_CA_LIST_DISABLED 0 00213 00214 /* 00215 * Default range for DTLS retransmission timer value, in milliseconds. 00216 * RFC 6347 4.2.4.1 says from 1 second to 60 seconds. 00217 */ 00218 #define MBEDTLS_SSL_DTLS_TIMEOUT_DFL_MIN 1000 00219 #define MBEDTLS_SSL_DTLS_TIMEOUT_DFL_MAX 60000 00220 00221 /** 00222 * \name SECTION: Module settings 00223 * 00224 * The configuration options you can set for this module are in this section. 00225 * Either change them in config.h or define them on the compiler command line. 00226 * \{ 00227 */ 00228 00229 #if !defined(MBEDTLS_SSL_DEFAULT_TICKET_LIFETIME) 00230 #define MBEDTLS_SSL_DEFAULT_TICKET_LIFETIME 86400 /**< Lifetime of session tickets (if enabled) */ 00231 #endif 00232 00233 /* 00234 * Maximum fragment length in bytes, 00235 * determines the size of each of the two internal I/O buffers. 00236 * 00237 * Note: the RFC defines the default size of SSL / TLS messages. If you 00238 * change the value here, other clients / servers may not be able to 00239 * communicate with you anymore. Only change this value if you control 00240 * both sides of the connection and have it reduced at both sides, or 00241 * if you're using the Max Fragment Length extension and you know all your 00242 * peers are using it too! 00243 */ 00244 #if !defined(MBEDTLS_SSL_MAX_CONTENT_LEN) 00245 #define MBEDTLS_SSL_MAX_CONTENT_LEN 16384 /**< Size of the input / output buffer */ 00246 #endif 00247 00248 #if !defined(MBEDTLS_SSL_IN_CONTENT_LEN) 00249 #define MBEDTLS_SSL_IN_CONTENT_LEN MBEDTLS_SSL_MAX_CONTENT_LEN 00250 #endif 00251 00252 #if !defined(MBEDTLS_SSL_OUT_CONTENT_LEN) 00253 #define MBEDTLS_SSL_OUT_CONTENT_LEN MBEDTLS_SSL_MAX_CONTENT_LEN 00254 #endif 00255 00256 /* 00257 * Maximum number of heap-allocated bytes for the purpose of 00258 * DTLS handshake message reassembly and future message buffering. 00259 */ 00260 #if !defined(MBEDTLS_SSL_DTLS_MAX_BUFFERING) 00261 #define MBEDTLS_SSL_DTLS_MAX_BUFFERING 32768 00262 #endif 00263 00264 /* 00265 * Maximum length of CIDs for incoming and outgoing messages. 00266 */ 00267 #if !defined(MBEDTLS_SSL_CID_IN_LEN_MAX) 00268 #define MBEDTLS_SSL_CID_IN_LEN_MAX 32 00269 #endif 00270 00271 #if !defined(MBEDTLS_SSL_CID_OUT_LEN_MAX) 00272 #define MBEDTLS_SSL_CID_OUT_LEN_MAX 32 00273 #endif 00274 00275 #if !defined(MBEDTLS_SSL_CID_PADDING_GRANULARITY) 00276 #define MBEDTLS_SSL_CID_PADDING_GRANULARITY 16 00277 #endif 00278 00279 /* \} name SECTION: Module settings */ 00280 00281 /* 00282 * Length of the verify data for secure renegotiation 00283 */ 00284 #if defined(MBEDTLS_SSL_PROTO_SSL3) 00285 #define MBEDTLS_SSL_VERIFY_DATA_MAX_LEN 36 00286 #else 00287 #define MBEDTLS_SSL_VERIFY_DATA_MAX_LEN 12 00288 #endif 00289 00290 /* 00291 * Signaling ciphersuite values (SCSV) 00292 */ 00293 #define MBEDTLS_SSL_EMPTY_RENEGOTIATION_INFO 0xFF /**< renegotiation info ext */ 00294 #define MBEDTLS_SSL_FALLBACK_SCSV_VALUE 0x5600 /**< RFC 7507 section 2 */ 00295 00296 /* 00297 * Supported Signature and Hash algorithms (For TLS 1.2) 00298 * RFC 5246 section 7.4.1.4.1 00299 */ 00300 #define MBEDTLS_SSL_HASH_NONE 0 00301 #define MBEDTLS_SSL_HASH_MD5 1 00302 #define MBEDTLS_SSL_HASH_SHA1 2 00303 #define MBEDTLS_SSL_HASH_SHA224 3 00304 #define MBEDTLS_SSL_HASH_SHA256 4 00305 #define MBEDTLS_SSL_HASH_SHA384 5 00306 #define MBEDTLS_SSL_HASH_SHA512 6 00307 00308 #define MBEDTLS_SSL_SIG_ANON 0 00309 #define MBEDTLS_SSL_SIG_RSA 1 00310 #define MBEDTLS_SSL_SIG_ECDSA 3 00311 00312 /* 00313 * Client Certificate Types 00314 * RFC 5246 section 7.4.4 plus RFC 4492 section 5.5 00315 */ 00316 #define MBEDTLS_SSL_CERT_TYPE_RSA_SIGN 1 00317 #define MBEDTLS_SSL_CERT_TYPE_ECDSA_SIGN 64 00318 00319 /* 00320 * Message, alert and handshake types 00321 */ 00322 #define MBEDTLS_SSL_MSG_CHANGE_CIPHER_SPEC 20 00323 #define MBEDTLS_SSL_MSG_ALERT 21 00324 #define MBEDTLS_SSL_MSG_HANDSHAKE 22 00325 #define MBEDTLS_SSL_MSG_APPLICATION_DATA 23 00326 #define MBEDTLS_SSL_MSG_CID 25 00327 00328 #define MBEDTLS_SSL_ALERT_LEVEL_WARNING 1 00329 #define MBEDTLS_SSL_ALERT_LEVEL_FATAL 2 00330 00331 #define MBEDTLS_SSL_ALERT_MSG_CLOSE_NOTIFY 0 /* 0x00 */ 00332 #define MBEDTLS_SSL_ALERT_MSG_UNEXPECTED_MESSAGE 10 /* 0x0A */ 00333 #define MBEDTLS_SSL_ALERT_MSG_BAD_RECORD_MAC 20 /* 0x14 */ 00334 #define MBEDTLS_SSL_ALERT_MSG_DECRYPTION_FAILED 21 /* 0x15 */ 00335 #define MBEDTLS_SSL_ALERT_MSG_RECORD_OVERFLOW 22 /* 0x16 */ 00336 #define MBEDTLS_SSL_ALERT_MSG_DECOMPRESSION_FAILURE 30 /* 0x1E */ 00337 #define MBEDTLS_SSL_ALERT_MSG_HANDSHAKE_FAILURE 40 /* 0x28 */ 00338 #define MBEDTLS_SSL_ALERT_MSG_NO_CERT 41 /* 0x29 */ 00339 #define MBEDTLS_SSL_ALERT_MSG_BAD_CERT 42 /* 0x2A */ 00340 #define MBEDTLS_SSL_ALERT_MSG_UNSUPPORTED_CERT 43 /* 0x2B */ 00341 #define MBEDTLS_SSL_ALERT_MSG_CERT_REVOKED 44 /* 0x2C */ 00342 #define MBEDTLS_SSL_ALERT_MSG_CERT_EXPIRED 45 /* 0x2D */ 00343 #define MBEDTLS_SSL_ALERT_MSG_CERT_UNKNOWN 46 /* 0x2E */ 00344 #define MBEDTLS_SSL_ALERT_MSG_ILLEGAL_PARAMETER 47 /* 0x2F */ 00345 #define MBEDTLS_SSL_ALERT_MSG_UNKNOWN_CA 48 /* 0x30 */ 00346 #define MBEDTLS_SSL_ALERT_MSG_ACCESS_DENIED 49 /* 0x31 */ 00347 #define MBEDTLS_SSL_ALERT_MSG_DECODE_ERROR 50 /* 0x32 */ 00348 #define MBEDTLS_SSL_ALERT_MSG_DECRYPT_ERROR 51 /* 0x33 */ 00349 #define MBEDTLS_SSL_ALERT_MSG_EXPORT_RESTRICTION 60 /* 0x3C */ 00350 #define MBEDTLS_SSL_ALERT_MSG_PROTOCOL_VERSION 70 /* 0x46 */ 00351 #define MBEDTLS_SSL_ALERT_MSG_INSUFFICIENT_SECURITY 71 /* 0x47 */ 00352 #define MBEDTLS_SSL_ALERT_MSG_INTERNAL_ERROR 80 /* 0x50 */ 00353 #define MBEDTLS_SSL_ALERT_MSG_INAPROPRIATE_FALLBACK 86 /* 0x56 */ 00354 #define MBEDTLS_SSL_ALERT_MSG_USER_CANCELED 90 /* 0x5A */ 00355 #define MBEDTLS_SSL_ALERT_MSG_NO_RENEGOTIATION 100 /* 0x64 */ 00356 #define MBEDTLS_SSL_ALERT_MSG_UNSUPPORTED_EXT 110 /* 0x6E */ 00357 #define MBEDTLS_SSL_ALERT_MSG_UNRECOGNIZED_NAME 112 /* 0x70 */ 00358 #define MBEDTLS_SSL_ALERT_MSG_UNKNOWN_PSK_IDENTITY 115 /* 0x73 */ 00359 #define MBEDTLS_SSL_ALERT_MSG_NO_APPLICATION_PROTOCOL 120 /* 0x78 */ 00360 00361 #define MBEDTLS_SSL_HS_HELLO_REQUEST 0 00362 #define MBEDTLS_SSL_HS_CLIENT_HELLO 1 00363 #define MBEDTLS_SSL_HS_SERVER_HELLO 2 00364 #define MBEDTLS_SSL_HS_HELLO_VERIFY_REQUEST 3 00365 #define MBEDTLS_SSL_HS_NEW_SESSION_TICKET 4 00366 #define MBEDTLS_SSL_HS_CERTIFICATE 11 00367 #define MBEDTLS_SSL_HS_SERVER_KEY_EXCHANGE 12 00368 #define MBEDTLS_SSL_HS_CERTIFICATE_REQUEST 13 00369 #define MBEDTLS_SSL_HS_SERVER_HELLO_DONE 14 00370 #define MBEDTLS_SSL_HS_CERTIFICATE_VERIFY 15 00371 #define MBEDTLS_SSL_HS_CLIENT_KEY_EXCHANGE 16 00372 #define MBEDTLS_SSL_HS_FINISHED 20 00373 00374 /* 00375 * TLS extensions 00376 */ 00377 #define MBEDTLS_TLS_EXT_SERVERNAME 0 00378 #define MBEDTLS_TLS_EXT_SERVERNAME_HOSTNAME 0 00379 00380 #define MBEDTLS_TLS_EXT_MAX_FRAGMENT_LENGTH 1 00381 00382 #define MBEDTLS_TLS_EXT_TRUNCATED_HMAC 4 00383 00384 #define MBEDTLS_TLS_EXT_SUPPORTED_ELLIPTIC_CURVES 10 00385 #define MBEDTLS_TLS_EXT_SUPPORTED_POINT_FORMATS 11 00386 00387 #define MBEDTLS_TLS_EXT_SIG_ALG 13 00388 00389 #define MBEDTLS_TLS_EXT_ALPN 16 00390 00391 #define MBEDTLS_TLS_EXT_ENCRYPT_THEN_MAC 22 /* 0x16 */ 00392 #define MBEDTLS_TLS_EXT_EXTENDED_MASTER_SECRET 0x0017 /* 23 */ 00393 00394 #define MBEDTLS_TLS_EXT_SESSION_TICKET 35 00395 00396 /* The value of the CID extension is still TBD as of 00397 * draft-ietf-tls-dtls-connection-id-05 00398 * (https://tools.ietf.org/html/draft-ietf-tls-dtls-connection-id-05) */ 00399 #define MBEDTLS_TLS_EXT_CID 254 /* TBD */ 00400 00401 #define MBEDTLS_TLS_EXT_ECJPAKE_KKPP 256 /* experimental */ 00402 00403 #define MBEDTLS_TLS_EXT_RENEGOTIATION_INFO 0xFF01 00404 00405 /* 00406 * Size defines 00407 */ 00408 #if !defined(MBEDTLS_PSK_MAX_LEN) 00409 #define MBEDTLS_PSK_MAX_LEN 32 /* 256 bits */ 00410 #endif 00411 00412 /* Dummy type used only for its size */ 00413 union mbedtls_ssl_premaster_secret 00414 { 00415 #if defined(MBEDTLS_KEY_EXCHANGE_RSA_ENABLED) 00416 unsigned char _pms_rsa[48]; /* RFC 5246 8.1.1 */ 00417 #endif 00418 #if defined(MBEDTLS_KEY_EXCHANGE_DHE_RSA_ENABLED) 00419 unsigned char _pms_dhm[MBEDTLS_MPI_MAX_SIZE]; /* RFC 5246 8.1.2 */ 00420 #endif 00421 #if defined(MBEDTLS_KEY_EXCHANGE_ECDHE_RSA_ENABLED) || \ 00422 defined(MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED) || \ 00423 defined(MBEDTLS_KEY_EXCHANGE_ECDH_RSA_ENABLED) || \ 00424 defined(MBEDTLS_KEY_EXCHANGE_ECDH_ECDSA_ENABLED) 00425 unsigned char _pms_ecdh[MBEDTLS_ECP_MAX_BYTES]; /* RFC 4492 5.10 */ 00426 #endif 00427 #if defined(MBEDTLS_KEY_EXCHANGE_PSK_ENABLED) 00428 unsigned char _pms_psk[4 + 2 * MBEDTLS_PSK_MAX_LEN]; /* RFC 4279 2 */ 00429 #endif 00430 #if defined(MBEDTLS_KEY_EXCHANGE_DHE_PSK_ENABLED) 00431 unsigned char _pms_dhe_psk[4 + MBEDTLS_MPI_MAX_SIZE 00432 + MBEDTLS_PSK_MAX_LEN]; /* RFC 4279 3 */ 00433 #endif 00434 #if defined(MBEDTLS_KEY_EXCHANGE_RSA_PSK_ENABLED) 00435 unsigned char _pms_rsa_psk[52 + MBEDTLS_PSK_MAX_LEN]; /* RFC 4279 4 */ 00436 #endif 00437 #if defined(MBEDTLS_KEY_EXCHANGE_ECDHE_PSK_ENABLED) 00438 unsigned char _pms_ecdhe_psk[4 + MBEDTLS_ECP_MAX_BYTES 00439 + MBEDTLS_PSK_MAX_LEN]; /* RFC 5489 2 */ 00440 #endif 00441 #if defined(MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED) 00442 unsigned char _pms_ecjpake[32]; /* Thread spec: SHA-256 output */ 00443 #endif 00444 }; 00445 00446 #define MBEDTLS_PREMASTER_SIZE sizeof( union mbedtls_ssl_premaster_secret ) 00447 00448 #ifdef __cplusplus 00449 extern "C" { 00450 #endif 00451 00452 /* 00453 * SSL state machine 00454 */ 00455 typedef enum 00456 { 00457 MBEDTLS_SSL_HELLO_REQUEST, 00458 MBEDTLS_SSL_CLIENT_HELLO, 00459 MBEDTLS_SSL_SERVER_HELLO, 00460 MBEDTLS_SSL_SERVER_CERTIFICATE, 00461 MBEDTLS_SSL_SERVER_KEY_EXCHANGE, 00462 MBEDTLS_SSL_CERTIFICATE_REQUEST, 00463 MBEDTLS_SSL_SERVER_HELLO_DONE, 00464 MBEDTLS_SSL_CLIENT_CERTIFICATE, 00465 MBEDTLS_SSL_CLIENT_KEY_EXCHANGE, 00466 MBEDTLS_SSL_CERTIFICATE_VERIFY, 00467 MBEDTLS_SSL_CLIENT_CHANGE_CIPHER_SPEC, 00468 MBEDTLS_SSL_CLIENT_FINISHED, 00469 MBEDTLS_SSL_SERVER_CHANGE_CIPHER_SPEC, 00470 MBEDTLS_SSL_SERVER_FINISHED, 00471 MBEDTLS_SSL_FLUSH_BUFFERS, 00472 MBEDTLS_SSL_HANDSHAKE_WRAPUP, 00473 MBEDTLS_SSL_HANDSHAKE_OVER, 00474 MBEDTLS_SSL_SERVER_NEW_SESSION_TICKET, 00475 MBEDTLS_SSL_SERVER_HELLO_VERIFY_REQUEST_SENT, 00476 } 00477 mbedtls_ssl_states; 00478 00479 /* 00480 * The tls_prf function types. 00481 */ 00482 typedef enum 00483 { 00484 MBEDTLS_SSL_TLS_PRF_NONE, 00485 MBEDTLS_SSL_TLS_PRF_SSL3, 00486 MBEDTLS_SSL_TLS_PRF_TLS1, 00487 MBEDTLS_SSL_TLS_PRF_SHA384, 00488 MBEDTLS_SSL_TLS_PRF_SHA256 00489 } 00490 mbedtls_tls_prf_types; 00491 /** 00492 * \brief Callback type: send data on the network. 00493 * 00494 * \note That callback may be either blocking or non-blocking. 00495 * 00496 * \param ctx Context for the send callback (typically a file descriptor) 00497 * \param buf Buffer holding the data to send 00498 * \param len Length of the data to send 00499 * 00500 * \return The callback must return the number of bytes sent if any, 00501 * or a non-zero error code. 00502 * If performing non-blocking I/O, \c MBEDTLS_ERR_SSL_WANT_WRITE 00503 * must be returned when the operation would block. 00504 * 00505 * \note The callback is allowed to send fewer bytes than requested. 00506 * It must always return the number of bytes actually sent. 00507 */ 00508 typedef int mbedtls_ssl_send_t( void *ctx, 00509 const unsigned char *buf, 00510 size_t len ); 00511 00512 /** 00513 * \brief Callback type: receive data from the network. 00514 * 00515 * \note That callback may be either blocking or non-blocking. 00516 * 00517 * \param ctx Context for the receive callback (typically a file 00518 * descriptor) 00519 * \param buf Buffer to write the received data to 00520 * \param len Length of the receive buffer 00521 * 00522 * \return The callback must return the number of bytes received, 00523 * or a non-zero error code. 00524 * If performing non-blocking I/O, \c MBEDTLS_ERR_SSL_WANT_READ 00525 * must be returned when the operation would block. 00526 * 00527 * \note The callback may receive fewer bytes than the length of the 00528 * buffer. It must always return the number of bytes actually 00529 * received and written to the buffer. 00530 */ 00531 typedef int mbedtls_ssl_recv_t( void *ctx, 00532 unsigned char *buf, 00533 size_t len ); 00534 00535 /** 00536 * \brief Callback type: receive data from the network, with timeout 00537 * 00538 * \note That callback must block until data is received, or the 00539 * timeout delay expires, or the operation is interrupted by a 00540 * signal. 00541 * 00542 * \param ctx Context for the receive callback (typically a file descriptor) 00543 * \param buf Buffer to write the received data to 00544 * \param len Length of the receive buffer 00545 * \param timeout Maximum nomber of millisecondes to wait for data 00546 * 0 means no timeout (potentially waiting forever) 00547 * 00548 * \return The callback must return the number of bytes received, 00549 * or a non-zero error code: 00550 * \c MBEDTLS_ERR_SSL_TIMEOUT if the operation timed out, 00551 * \c MBEDTLS_ERR_SSL_WANT_READ if interrupted by a signal. 00552 * 00553 * \note The callback may receive fewer bytes than the length of the 00554 * buffer. It must always return the number of bytes actually 00555 * received and written to the buffer. 00556 */ 00557 typedef int mbedtls_ssl_recv_timeout_t( void *ctx, 00558 unsigned char *buf, 00559 size_t len, 00560 uint32_t timeout ); 00561 /** 00562 * \brief Callback type: set a pair of timers/delays to watch 00563 * 00564 * \param ctx Context pointer 00565 * \param int_ms Intermediate delay in milliseconds 00566 * \param fin_ms Final delay in milliseconds 00567 * 0 cancels the current timer. 00568 * 00569 * \note This callback must at least store the necessary information 00570 * for the associated \c mbedtls_ssl_get_timer_t callback to 00571 * return correct information. 00572 * 00573 * \note If using a event-driven style of programming, an event must 00574 * be generated when the final delay is passed. The event must 00575 * cause a call to \c mbedtls_ssl_handshake() with the proper 00576 * SSL context to be scheduled. Care must be taken to ensure 00577 * that at most one such call happens at a time. 00578 * 00579 * \note Only one timer at a time must be running. Calling this 00580 * function while a timer is running must cancel it. Cancelled 00581 * timers must not generate any event. 00582 */ 00583 typedef void mbedtls_ssl_set_timer_t( void * ctx, 00584 uint32_t int_ms, 00585 uint32_t fin_ms ); 00586 00587 /** 00588 * \brief Callback type: get status of timers/delays 00589 * 00590 * \param ctx Context pointer 00591 * 00592 * \return This callback must return: 00593 * -1 if cancelled (fin_ms == 0), 00594 * 0 if none of the delays have passed, 00595 * 1 if only the intermediate delay has passed, 00596 * 2 if the final delay has passed. 00597 */ 00598 typedef int mbedtls_ssl_get_timer_t( void * ctx ); 00599 00600 /* Defined below */ 00601 typedef struct mbedtls_ssl_session mbedtls_ssl_session; 00602 typedef struct mbedtls_ssl_context mbedtls_ssl_context; 00603 typedef struct mbedtls_ssl_config mbedtls_ssl_config; 00604 00605 /* Defined in ssl_internal.h */ 00606 typedef struct mbedtls_ssl_transform mbedtls_ssl_transform; 00607 typedef struct mbedtls_ssl_handshake_params mbedtls_ssl_handshake_params; 00608 typedef struct mbedtls_ssl_sig_hash_set_t mbedtls_ssl_sig_hash_set_t; 00609 #if defined(MBEDTLS_X509_CRT_PARSE_C) 00610 typedef struct mbedtls_ssl_key_cert mbedtls_ssl_key_cert; 00611 #endif 00612 #if defined(MBEDTLS_SSL_PROTO_DTLS) 00613 typedef struct mbedtls_ssl_flight_item mbedtls_ssl_flight_item; 00614 #endif 00615 00616 #if defined(MBEDTLS_SSL_ASYNC_PRIVATE) 00617 #if defined(MBEDTLS_X509_CRT_PARSE_C) 00618 /** 00619 * \brief Callback type: start external signature operation. 00620 * 00621 * This callback is called during an SSL handshake to start 00622 * a signature decryption operation using an 00623 * external processor. The parameter \p cert contains 00624 * the public key; it is up to the callback function to 00625 * determine how to access the associated private key. 00626 * 00627 * This function typically sends or enqueues a request, and 00628 * does not wait for the operation to complete. This allows 00629 * the handshake step to be non-blocking. 00630 * 00631 * The parameters \p ssl and \p cert are guaranteed to remain 00632 * valid throughout the handshake. On the other hand, this 00633 * function must save the contents of \p hash if the value 00634 * is needed for later processing, because the \p hash buffer 00635 * is no longer valid after this function returns. 00636 * 00637 * This function may call mbedtls_ssl_set_async_operation_data() 00638 * to store an operation context for later retrieval 00639 * by the resume or cancel callback. 00640 * 00641 * \note For RSA signatures, this function must produce output 00642 * that is consistent with PKCS#1 v1.5 in the same way as 00643 * mbedtls_rsa_pkcs1_sign(). Before the private key operation, 00644 * apply the padding steps described in RFC 8017, section 9.2 00645 * "EMSA-PKCS1-v1_5" as follows. 00646 * - If \p md_alg is #MBEDTLS_MD_NONE, apply the PKCS#1 v1.5 00647 * encoding, treating \p hash as the DigestInfo to be 00648 * padded. In other words, apply EMSA-PKCS1-v1_5 starting 00649 * from step 3, with `T = hash` and `tLen = hash_len`. 00650 * - If `md_alg != MBEDTLS_MD_NONE`, apply the PKCS#1 v1.5 00651 * encoding, treating \p hash as the hash to be encoded and 00652 * padded. In other words, apply EMSA-PKCS1-v1_5 starting 00653 * from step 2, with `digestAlgorithm` obtained by calling 00654 * mbedtls_oid_get_oid_by_md() on \p md_alg. 00655 * 00656 * \note For ECDSA signatures, the output format is the DER encoding 00657 * `Ecdsa-Sig-Value` defined in 00658 * [RFC 4492 section 5.4](https://tools.ietf.org/html/rfc4492#section-5.4). 00659 * 00660 * \param ssl The SSL connection instance. It should not be 00661 * modified other than via 00662 * mbedtls_ssl_set_async_operation_data(). 00663 * \param cert Certificate containing the public key. 00664 * In simple cases, this is one of the pointers passed to 00665 * mbedtls_ssl_conf_own_cert() when configuring the SSL 00666 * connection. However, if other callbacks are used, this 00667 * property may not hold. For example, if an SNI callback 00668 * is registered with mbedtls_ssl_conf_sni(), then 00669 * this callback determines what certificate is used. 00670 * \param md_alg Hash algorithm. 00671 * \param hash Buffer containing the hash. This buffer is 00672 * no longer valid when the function returns. 00673 * \param hash_len Size of the \c hash buffer in bytes. 00674 * 00675 * \return 0 if the operation was started successfully and the SSL 00676 * stack should call the resume callback immediately. 00677 * \return #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS if the operation 00678 * was started successfully and the SSL stack should return 00679 * immediately without calling the resume callback yet. 00680 * \return #MBEDTLS_ERR_SSL_HW_ACCEL_FALLTHROUGH if the external 00681 * processor does not support this key. The SSL stack will 00682 * use the private key object instead. 00683 * \return Any other error indicates a fatal failure and is 00684 * propagated up the call chain. The callback should 00685 * use \c MBEDTLS_ERR_PK_xxx error codes, and <b>must not</b> 00686 * use \c MBEDTLS_ERR_SSL_xxx error codes except as 00687 * directed in the documentation of this callback. 00688 */ 00689 typedef int mbedtls_ssl_async_sign_t( mbedtls_ssl_context *ssl, 00690 mbedtls_x509_crt *cert, 00691 mbedtls_md_type_t md_alg, 00692 const unsigned char *hash, 00693 size_t hash_len ); 00694 00695 /** 00696 * \brief Callback type: start external decryption operation. 00697 * 00698 * This callback is called during an SSL handshake to start 00699 * an RSA decryption operation using an 00700 * external processor. The parameter \p cert contains 00701 * the public key; it is up to the callback function to 00702 * determine how to access the associated private key. 00703 * 00704 * This function typically sends or enqueues a request, and 00705 * does not wait for the operation to complete. This allows 00706 * the handshake step to be non-blocking. 00707 * 00708 * The parameters \p ssl and \p cert are guaranteed to remain 00709 * valid throughout the handshake. On the other hand, this 00710 * function must save the contents of \p input if the value 00711 * is needed for later processing, because the \p input buffer 00712 * is no longer valid after this function returns. 00713 * 00714 * This function may call mbedtls_ssl_set_async_operation_data() 00715 * to store an operation context for later retrieval 00716 * by the resume or cancel callback. 00717 * 00718 * \warning RSA decryption as used in TLS is subject to a potential 00719 * timing side channel attack first discovered by Bleichenbacher 00720 * in 1998. This attack can be remotely exploitable 00721 * in practice. To avoid this attack, you must ensure that 00722 * if the callback performs an RSA decryption, the time it 00723 * takes to execute and return the result does not depend 00724 * on whether the RSA decryption succeeded or reported 00725 * invalid padding. 00726 * 00727 * \param ssl The SSL connection instance. It should not be 00728 * modified other than via 00729 * mbedtls_ssl_set_async_operation_data(). 00730 * \param cert Certificate containing the public key. 00731 * In simple cases, this is one of the pointers passed to 00732 * mbedtls_ssl_conf_own_cert() when configuring the SSL 00733 * connection. However, if other callbacks are used, this 00734 * property may not hold. For example, if an SNI callback 00735 * is registered with mbedtls_ssl_conf_sni(), then 00736 * this callback determines what certificate is used. 00737 * \param input Buffer containing the input ciphertext. This buffer 00738 * is no longer valid when the function returns. 00739 * \param input_len Size of the \p input buffer in bytes. 00740 * 00741 * \return 0 if the operation was started successfully and the SSL 00742 * stack should call the resume callback immediately. 00743 * \return #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS if the operation 00744 * was started successfully and the SSL stack should return 00745 * immediately without calling the resume callback yet. 00746 * \return #MBEDTLS_ERR_SSL_HW_ACCEL_FALLTHROUGH if the external 00747 * processor does not support this key. The SSL stack will 00748 * use the private key object instead. 00749 * \return Any other error indicates a fatal failure and is 00750 * propagated up the call chain. The callback should 00751 * use \c MBEDTLS_ERR_PK_xxx error codes, and <b>must not</b> 00752 * use \c MBEDTLS_ERR_SSL_xxx error codes except as 00753 * directed in the documentation of this callback. 00754 */ 00755 typedef int mbedtls_ssl_async_decrypt_t( mbedtls_ssl_context *ssl, 00756 mbedtls_x509_crt *cert, 00757 const unsigned char *input, 00758 size_t input_len ); 00759 #endif /* MBEDTLS_X509_CRT_PARSE_C */ 00760 00761 /** 00762 * \brief Callback type: resume external operation. 00763 * 00764 * This callback is called during an SSL handshake to resume 00765 * an external operation started by the 00766 * ::mbedtls_ssl_async_sign_t or 00767 * ::mbedtls_ssl_async_decrypt_t callback. 00768 * 00769 * This function typically checks the status of a pending 00770 * request or causes the request queue to make progress, and 00771 * does not wait for the operation to complete. This allows 00772 * the handshake step to be non-blocking. 00773 * 00774 * This function may call mbedtls_ssl_get_async_operation_data() 00775 * to retrieve an operation context set by the start callback. 00776 * It may call mbedtls_ssl_set_async_operation_data() to modify 00777 * this context. 00778 * 00779 * Note that when this function returns a status other than 00780 * #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS, it must free any 00781 * resources associated with the operation. 00782 * 00783 * \param ssl The SSL connection instance. It should not be 00784 * modified other than via 00785 * mbedtls_ssl_set_async_operation_data(). 00786 * \param output Buffer containing the output (signature or decrypted 00787 * data) on success. 00788 * \param output_len On success, number of bytes written to \p output. 00789 * \param output_size Size of the \p output buffer in bytes. 00790 * 00791 * \return 0 if output of the operation is available in the 00792 * \p output buffer. 00793 * \return #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS if the operation 00794 * is still in progress. Subsequent requests for progress 00795 * on the SSL connection will call the resume callback 00796 * again. 00797 * \return Any other error means that the operation is aborted. 00798 * The SSL handshake is aborted. The callback should 00799 * use \c MBEDTLS_ERR_PK_xxx error codes, and <b>must not</b> 00800 * use \c MBEDTLS_ERR_SSL_xxx error codes except as 00801 * directed in the documentation of this callback. 00802 */ 00803 typedef int mbedtls_ssl_async_resume_t( mbedtls_ssl_context *ssl, 00804 unsigned char *output, 00805 size_t *output_len, 00806 size_t output_size ); 00807 00808 /** 00809 * \brief Callback type: cancel external operation. 00810 * 00811 * This callback is called if an SSL connection is closed 00812 * while an asynchronous operation is in progress. Note that 00813 * this callback is not called if the 00814 * ::mbedtls_ssl_async_resume_t callback has run and has 00815 * returned a value other than 00816 * #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS, since in that case 00817 * the asynchronous operation has already completed. 00818 * 00819 * This function may call mbedtls_ssl_get_async_operation_data() 00820 * to retrieve an operation context set by the start callback. 00821 * 00822 * \param ssl The SSL connection instance. It should not be 00823 * modified. 00824 */ 00825 typedef void mbedtls_ssl_async_cancel_t( mbedtls_ssl_context *ssl ); 00826 #endif /* MBEDTLS_SSL_ASYNC_PRIVATE */ 00827 00828 #if defined(MBEDTLS_KEY_EXCHANGE__WITH_CERT__ENABLED) && \ 00829 !defined(MBEDTLS_SSL_KEEP_PEER_CERTIFICATE) 00830 #define MBEDTLS_SSL_PEER_CERT_DIGEST_MAX_LEN 48 00831 #if defined(MBEDTLS_SHA256_C) 00832 #define MBEDTLS_SSL_PEER_CERT_DIGEST_DFL_TYPE MBEDTLS_MD_SHA256 00833 #define MBEDTLS_SSL_PEER_CERT_DIGEST_DFL_LEN 32 00834 #elif defined(MBEDTLS_SHA512_C) 00835 #define MBEDTLS_SSL_PEER_CERT_DIGEST_DFL_TYPE MBEDTLS_MD_SHA384 00836 #define MBEDTLS_SSL_PEER_CERT_DIGEST_DFL_LEN 48 00837 #elif defined(MBEDTLS_SHA1_C) 00838 #define MBEDTLS_SSL_PEER_CERT_DIGEST_DFL_TYPE MBEDTLS_MD_SHA1 00839 #define MBEDTLS_SSL_PEER_CERT_DIGEST_DFL_LEN 20 00840 #else 00841 /* This is already checked in check_config.h, but be sure. */ 00842 #error "Bad configuration - need SHA-1, SHA-256 or SHA-512 enabled to compute digest of peer CRT." 00843 #endif 00844 #endif /* MBEDTLS_KEY_EXCHANGE__WITH_CERT__ENABLED && 00845 !MBEDTLS_SSL_KEEP_PEER_CERTIFICATE */ 00846 00847 /* 00848 * This structure is used for storing current session data. 00849 * 00850 * Note: when changing this definition, we need to check and update: 00851 * - in tests/suites/test_suite_ssl.function: 00852 * ssl_populate_session() and ssl_serialize_session_save_load() 00853 * - in library/ssl_tls.c: 00854 * mbedtls_ssl_session_init() and mbedtls_ssl_session_free() 00855 * mbedtls_ssl_session_save() and ssl_session_load() 00856 * ssl_session_copy() 00857 */ 00858 struct mbedtls_ssl_session 00859 { 00860 #if defined(MBEDTLS_HAVE_TIME) 00861 mbedtls_time_t start; /*!< starting time */ 00862 #endif 00863 int ciphersuite; /*!< chosen ciphersuite */ 00864 int compression; /*!< chosen compression */ 00865 size_t id_len; /*!< session id length */ 00866 unsigned char id[32]; /*!< session identifier */ 00867 unsigned char master[48]; /*!< the master secret */ 00868 00869 #if defined(MBEDTLS_X509_CRT_PARSE_C) 00870 #if defined(MBEDTLS_SSL_KEEP_PEER_CERTIFICATE) 00871 mbedtls_x509_crt *peer_cert; /*!< peer X.509 cert chain */ 00872 #else /* MBEDTLS_SSL_KEEP_PEER_CERTIFICATE */ 00873 /*! The digest of the peer's end-CRT. This must be kept to detect CRT 00874 * changes during renegotiation, mitigating the triple handshake attack. */ 00875 unsigned char *peer_cert_digest; 00876 size_t peer_cert_digest_len; 00877 mbedtls_md_type_t peer_cert_digest_type; 00878 #endif /* !MBEDTLS_SSL_KEEP_PEER_CERTIFICATE */ 00879 #endif /* MBEDTLS_X509_CRT_PARSE_C */ 00880 uint32_t verify_result; /*!< verification result */ 00881 00882 #if defined(MBEDTLS_SSL_SESSION_TICKETS) && defined(MBEDTLS_SSL_CLI_C) 00883 unsigned char *ticket; /*!< RFC 5077 session ticket */ 00884 size_t ticket_len; /*!< session ticket length */ 00885 uint32_t ticket_lifetime; /*!< ticket lifetime hint */ 00886 #endif /* MBEDTLS_SSL_SESSION_TICKETS && MBEDTLS_SSL_CLI_C */ 00887 00888 #if defined(MBEDTLS_SSL_MAX_FRAGMENT_LENGTH) 00889 unsigned char mfl_code; /*!< MaxFragmentLength negotiated by peer */ 00890 #endif /* MBEDTLS_SSL_MAX_FRAGMENT_LENGTH */ 00891 00892 #if defined(MBEDTLS_SSL_TRUNCATED_HMAC) 00893 int trunc_hmac; /*!< flag for truncated hmac activation */ 00894 #endif /* MBEDTLS_SSL_TRUNCATED_HMAC */ 00895 00896 #if defined(MBEDTLS_SSL_ENCRYPT_THEN_MAC) 00897 int encrypt_then_mac; /*!< flag for EtM activation */ 00898 #endif 00899 }; 00900 00901 /** 00902 * SSL/TLS configuration to be shared between mbedtls_ssl_context structures. 00903 */ 00904 struct mbedtls_ssl_config 00905 { 00906 /* Group items by size (largest first) to minimize padding overhead */ 00907 00908 /* 00909 * Pointers 00910 */ 00911 00912 const int *ciphersuite_list [4]; /*!< allowed ciphersuites per version */ 00913 00914 /** Callback for printing debug output */ 00915 void (*f_dbg)(void *, int, const char *, int, const char *); 00916 void *p_dbg ; /*!< context for the debug function */ 00917 00918 /** Callback for getting (pseudo-)random numbers */ 00919 int (*f_rng)(void *, unsigned char *, size_t); 00920 void *p_rng ; /*!< context for the RNG function */ 00921 00922 /** Callback to retrieve a session from the cache */ 00923 int (*f_get_cache)(void *, mbedtls_ssl_session *); 00924 /** Callback to store a session into the cache */ 00925 int (*f_set_cache)(void *, const mbedtls_ssl_session *); 00926 void *p_cache ; /*!< context for cache callbacks */ 00927 00928 #if defined(MBEDTLS_SSL_SERVER_NAME_INDICATION) 00929 /** Callback for setting cert according to SNI extension */ 00930 int (*f_sni)(void *, mbedtls_ssl_context *, const unsigned char *, size_t); 00931 void *p_sni ; /*!< context for SNI callback */ 00932 #endif 00933 00934 #if defined(MBEDTLS_X509_CRT_PARSE_C) 00935 /** Callback to customize X.509 certificate chain verification */ 00936 int (*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *); 00937 void *p_vrfy ; /*!< context for X.509 verify calllback */ 00938 #endif 00939 00940 #if defined(MBEDTLS_KEY_EXCHANGE__SOME__PSK_ENABLED) 00941 /** Callback to retrieve PSK key from identity */ 00942 int (*f_psk)(void *, mbedtls_ssl_context *, const unsigned char *, size_t); 00943 void *p_psk ; /*!< context for PSK callback */ 00944 #endif 00945 00946 #if defined(MBEDTLS_SSL_DTLS_HELLO_VERIFY) && defined(MBEDTLS_SSL_SRV_C) 00947 /** Callback to create & write a cookie for ClientHello veirifcation */ 00948 int (*f_cookie_write)( void *, unsigned char **, unsigned char *, 00949 const unsigned char *, size_t ); 00950 /** Callback to verify validity of a ClientHello cookie */ 00951 int (*f_cookie_check)( void *, const unsigned char *, size_t, 00952 const unsigned char *, size_t ); 00953 void *p_cookie ; /*!< context for the cookie callbacks */ 00954 #endif 00955 00956 #if defined(MBEDTLS_SSL_SESSION_TICKETS) && defined(MBEDTLS_SSL_SRV_C) 00957 /** Callback to create & write a session ticket */ 00958 int (*f_ticket_write)( void *, const mbedtls_ssl_session *, 00959 unsigned char *, const unsigned char *, size_t *, uint32_t * ); 00960 /** Callback to parse a session ticket into a session structure */ 00961 int (*f_ticket_parse)( void *, mbedtls_ssl_session *, unsigned char *, size_t); 00962 void *p_ticket ; /*!< context for the ticket callbacks */ 00963 #endif /* MBEDTLS_SSL_SESSION_TICKETS && MBEDTLS_SSL_SRV_C */ 00964 00965 #if defined(MBEDTLS_SSL_EXPORT_KEYS) 00966 /** Callback to export key block and master secret */ 00967 int (*f_export_keys)( void *, const unsigned char *, 00968 const unsigned char *, size_t, size_t, size_t ); 00969 /** Callback to export key block, master secret, 00970 * tls_prf and random bytes. Should replace f_export_keys */ 00971 int (*f_export_keys_ext)( void *, const unsigned char *, 00972 const unsigned char *, size_t, size_t, size_t, 00973 const unsigned char[32], const unsigned char[32], 00974 mbedtls_tls_prf_types ); 00975 void *p_export_keys ; /*!< context for key export callback */ 00976 #endif 00977 00978 #if defined(MBEDTLS_SSL_DTLS_CONNECTION_ID) 00979 size_t cid_len ; /*!< The length of CIDs for incoming DTLS records. */ 00980 #endif /* MBEDTLS_SSL_DTLS_CONNECTION_ID */ 00981 00982 #if defined(MBEDTLS_X509_CRT_PARSE_C) 00983 const mbedtls_x509_crt_profile *cert_profile ; /*!< verification profile */ 00984 mbedtls_ssl_key_cert *key_cert ; /*!< own certificate/key pair(s) */ 00985 mbedtls_x509_crt *ca_chain ; /*!< trusted CAs */ 00986 mbedtls_x509_crl *ca_crl ; /*!< trusted CAs CRLs */ 00987 #if defined(MBEDTLS_X509_TRUSTED_CERTIFICATE_CALLBACK) 00988 mbedtls_x509_crt_ca_cb_t f_ca_cb; 00989 void *p_ca_cb; 00990 #endif /* MBEDTLS_X509_TRUSTED_CERTIFICATE_CALLBACK */ 00991 #endif /* MBEDTLS_X509_CRT_PARSE_C */ 00992 00993 #if defined(MBEDTLS_SSL_ASYNC_PRIVATE) 00994 #if defined(MBEDTLS_X509_CRT_PARSE_C) 00995 mbedtls_ssl_async_sign_t *f_async_sign_start ; /*!< start asynchronous signature operation */ 00996 mbedtls_ssl_async_decrypt_t *f_async_decrypt_start ; /*!< start asynchronous decryption operation */ 00997 #endif /* MBEDTLS_X509_CRT_PARSE_C */ 00998 mbedtls_ssl_async_resume_t *f_async_resume ; /*!< resume asynchronous operation */ 00999 mbedtls_ssl_async_cancel_t *f_async_cancel ; /*!< cancel asynchronous operation */ 01000 void *p_async_config_data ; /*!< Configuration data set by mbedtls_ssl_conf_async_private_cb(). */ 01001 #endif /* MBEDTLS_SSL_ASYNC_PRIVATE */ 01002 01003 #if defined(MBEDTLS_KEY_EXCHANGE__WITH_CERT__ENABLED) 01004 const int *sig_hashes ; /*!< allowed signature hashes */ 01005 #endif 01006 01007 #if defined(MBEDTLS_ECP_C) 01008 const mbedtls_ecp_group_id *curve_list ; /*!< allowed curves */ 01009 #endif 01010 01011 #if defined(MBEDTLS_DHM_C) 01012 mbedtls_mpi dhm_P ; /*!< prime modulus for DHM */ 01013 mbedtls_mpi dhm_G ; /*!< generator for DHM */ 01014 #endif 01015 01016 #if defined(MBEDTLS_KEY_EXCHANGE__SOME__PSK_ENABLED) 01017 01018 #if defined(MBEDTLS_USE_PSA_CRYPTO) 01019 psa_key_handle_t psk_opaque ; /*!< PSA key slot holding opaque PSK. 01020 * This field should only be set via 01021 * mbedtls_ssl_conf_psk_opaque(). 01022 * If either no PSK or a raw PSK have 01023 * been configured, this has value \c 0. */ 01024 #endif /* MBEDTLS_USE_PSA_CRYPTO */ 01025 01026 unsigned char *psk ; /*!< The raw pre-shared key. This field should 01027 * only be set via mbedtls_ssl_conf_psk(). 01028 * If either no PSK or an opaque PSK 01029 * have been configured, this has value NULL. */ 01030 size_t psk_len ; /*!< The length of the raw pre-shared key. 01031 * This field should only be set via 01032 * mbedtls_ssl_conf_psk(). 01033 * Its value is non-zero if and only if 01034 * \c psk is not \c NULL. */ 01035 01036 unsigned char *psk_identity ; /*!< The PSK identity for PSK negotiation. 01037 * This field should only be set via 01038 * mbedtls_ssl_conf_psk(). 01039 * This is set if and only if either 01040 * \c psk or \c psk_opaque are set. */ 01041 size_t psk_identity_len ;/*!< The length of PSK identity. 01042 * This field should only be set via 01043 * mbedtls_ssl_conf_psk(). 01044 * Its value is non-zero if and only if 01045 * \c psk is not \c NULL or \c psk_opaque 01046 * is not \c 0. */ 01047 #endif /* MBEDTLS_KEY_EXCHANGE__SOME__PSK_ENABLED */ 01048 01049 #if defined(MBEDTLS_SSL_ALPN) 01050 const char **alpn_list ; /*!< ordered list of protocols */ 01051 #endif 01052 01053 /* 01054 * Numerical settings (int then char) 01055 */ 01056 01057 uint32_t read_timeout ; /*!< timeout for mbedtls_ssl_read (ms) */ 01058 01059 #if defined(MBEDTLS_SSL_PROTO_DTLS) 01060 uint32_t hs_timeout_min ; /*!< initial value of the handshake 01061 retransmission timeout (ms) */ 01062 uint32_t hs_timeout_max ; /*!< maximum value of the handshake 01063 retransmission timeout (ms) */ 01064 #endif 01065 01066 #if defined(MBEDTLS_SSL_RENEGOTIATION) 01067 int renego_max_records ; /*!< grace period for renegotiation */ 01068 unsigned char renego_period [8]; /*!< value of the record counters 01069 that triggers renegotiation */ 01070 #endif 01071 01072 #if defined(MBEDTLS_SSL_DTLS_BADMAC_LIMIT) 01073 unsigned int badmac_limit ; /*!< limit of records with a bad MAC */ 01074 #endif 01075 01076 #if defined(MBEDTLS_DHM_C) && defined(MBEDTLS_SSL_CLI_C) 01077 unsigned int dhm_min_bitlen ; /*!< min. bit length of the DHM prime */ 01078 #endif 01079 01080 unsigned char max_major_ver ; /*!< max. major version used */ 01081 unsigned char max_minor_ver ; /*!< max. minor version used */ 01082 unsigned char min_major_ver ; /*!< min. major version used */ 01083 unsigned char min_minor_ver ; /*!< min. minor version used */ 01084 01085 /* 01086 * Flags (bitfields) 01087 */ 01088 01089 unsigned int endpoint : 1; /*!< 0: client, 1: server */ 01090 unsigned int transport : 1; /*!< stream (TLS) or datagram (DTLS) */ 01091 unsigned int authmode : 2; /*!< MBEDTLS_SSL_VERIFY_XXX */ 01092 /* needed even with renego disabled for LEGACY_BREAK_HANDSHAKE */ 01093 unsigned int allow_legacy_renegotiation : 2 ; /*!< MBEDTLS_LEGACY_XXX */ 01094 #if defined(MBEDTLS_ARC4_C) 01095 unsigned int arc4_disabled : 1; /*!< blacklist RC4 ciphersuites? */ 01096 #endif 01097 #if defined(MBEDTLS_SSL_MAX_FRAGMENT_LENGTH) 01098 unsigned int mfl_code : 3; /*!< desired fragment length */ 01099 #endif 01100 #if defined(MBEDTLS_SSL_ENCRYPT_THEN_MAC) 01101 unsigned int encrypt_then_mac : 1 ; /*!< negotiate encrypt-then-mac? */ 01102 #endif 01103 #if defined(MBEDTLS_SSL_EXTENDED_MASTER_SECRET) 01104 unsigned int extended_ms : 1; /*!< negotiate extended master secret? */ 01105 #endif 01106 #if defined(MBEDTLS_SSL_DTLS_ANTI_REPLAY) 01107 unsigned int anti_replay : 1; /*!< detect and prevent replay? */ 01108 #endif 01109 #if defined(MBEDTLS_SSL_CBC_RECORD_SPLITTING) 01110 unsigned int cbc_record_splitting : 1; /*!< do cbc record splitting */ 01111 #endif 01112 #if defined(MBEDTLS_SSL_RENEGOTIATION) 01113 unsigned int disable_renegotiation : 1; /*!< disable renegotiation? */ 01114 #endif 01115 #if defined(MBEDTLS_SSL_TRUNCATED_HMAC) 01116 unsigned int trunc_hmac : 1; /*!< negotiate truncated hmac? */ 01117 #endif 01118 #if defined(MBEDTLS_SSL_SESSION_TICKETS) 01119 unsigned int session_tickets : 1; /*!< use session tickets? */ 01120 #endif 01121 #if defined(MBEDTLS_SSL_FALLBACK_SCSV) && defined(MBEDTLS_SSL_CLI_C) 01122 unsigned int fallback : 1; /*!< is this a fallback? */ 01123 #endif 01124 #if defined(MBEDTLS_SSL_SRV_C) 01125 unsigned int cert_req_ca_list : 1; /*!< enable sending CA list in 01126 Certificate Request messages? */ 01127 #endif 01128 #if defined(MBEDTLS_SSL_DTLS_CONNECTION_ID) 01129 unsigned int ignore_unexpected_cid : 1; /*!< Determines whether DTLS 01130 * record with unexpected CID 01131 * should lead to failure. */ 01132 #endif /* MBEDTLS_SSL_DTLS_CONNECTION_ID */ 01133 }; 01134 01135 01136 struct mbedtls_ssl_context 01137 { 01138 const mbedtls_ssl_config *conf; /*!< configuration information */ 01139 01140 /* 01141 * Miscellaneous 01142 */ 01143 int state; /*!< SSL handshake: current state */ 01144 #if defined(MBEDTLS_SSL_RENEGOTIATION) 01145 int renego_status; /*!< Initial, in progress, pending? */ 01146 int renego_records_seen; /*!< Records since renego request, or with DTLS, 01147 number of retransmissions of request if 01148 renego_max_records is < 0 */ 01149 #endif /* MBEDTLS_SSL_RENEGOTIATION */ 01150 01151 int major_ver; /*!< equal to MBEDTLS_SSL_MAJOR_VERSION_3 */ 01152 int minor_ver; /*!< either 0 (SSL3) or 1 (TLS1.0) */ 01153 01154 #if defined(MBEDTLS_SSL_DTLS_BADMAC_LIMIT) 01155 unsigned badmac_seen; /*!< records with a bad MAC received */ 01156 #endif /* MBEDTLS_SSL_DTLS_BADMAC_LIMIT */ 01157 01158 #if defined(MBEDTLS_X509_CRT_PARSE_C) 01159 /** Callback to customize X.509 certificate chain verification */ 01160 int (*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *); 01161 void *p_vrfy; /*!< context for X.509 verify callback */ 01162 #endif 01163 01164 mbedtls_ssl_send_t *f_send; /*!< Callback for network send */ 01165 mbedtls_ssl_recv_t *f_recv; /*!< Callback for network receive */ 01166 mbedtls_ssl_recv_timeout_t *f_recv_timeout; 01167 /*!< Callback for network receive with timeout */ 01168 01169 void *p_bio; /*!< context for I/O operations */ 01170 01171 /* 01172 * Session layer 01173 */ 01174 mbedtls_ssl_session *session_in; /*!< current session data (in) */ 01175 mbedtls_ssl_session *session_out; /*!< current session data (out) */ 01176 mbedtls_ssl_session *session; /*!< negotiated session data */ 01177 mbedtls_ssl_session *session_negotiate; /*!< session data in negotiation */ 01178 01179 mbedtls_ssl_handshake_params *handshake; /*!< params required only during 01180 the handshake process */ 01181 01182 /* 01183 * Record layer transformations 01184 */ 01185 mbedtls_ssl_transform *transform_in; /*!< current transform params (in) */ 01186 mbedtls_ssl_transform *transform_out; /*!< current transform params (in) */ 01187 mbedtls_ssl_transform *transform; /*!< negotiated transform params */ 01188 mbedtls_ssl_transform *transform_negotiate; /*!< transform params in negotiation */ 01189 01190 /* 01191 * Timers 01192 */ 01193 void *p_timer; /*!< context for the timer callbacks */ 01194 01195 mbedtls_ssl_set_timer_t *f_set_timer; /*!< set timer callback */ 01196 mbedtls_ssl_get_timer_t *f_get_timer; /*!< get timer callback */ 01197 01198 /* 01199 * Record layer (incoming data) 01200 */ 01201 unsigned char *in_buf; /*!< input buffer */ 01202 unsigned char *in_ctr; /*!< 64-bit incoming message counter 01203 TLS: maintained by us 01204 DTLS: read from peer */ 01205 unsigned char *in_hdr; /*!< start of record header */ 01206 #if defined(MBEDTLS_SSL_DTLS_CONNECTION_ID) 01207 unsigned char *in_cid; /*!< The start of the CID; 01208 * (the end is marked by in_len). */ 01209 #endif /* MBEDTLS_SSL_DTLS_CONNECTION_ID */ 01210 unsigned char *in_len; /*!< two-bytes message length field */ 01211 unsigned char *in_iv; /*!< ivlen-byte IV */ 01212 unsigned char *in_msg; /*!< message contents (in_iv+ivlen) */ 01213 unsigned char *in_offt; /*!< read offset in application data */ 01214 01215 int in_msgtype; /*!< record header: message type */ 01216 size_t in_msglen; /*!< record header: message length */ 01217 size_t in_left; /*!< amount of data read so far */ 01218 #if defined(MBEDTLS_SSL_PROTO_DTLS) 01219 uint16_t in_epoch; /*!< DTLS epoch for incoming records */ 01220 size_t next_record_offset; /*!< offset of the next record in datagram 01221 (equal to in_left if none) */ 01222 #endif /* MBEDTLS_SSL_PROTO_DTLS */ 01223 #if defined(MBEDTLS_SSL_DTLS_ANTI_REPLAY) 01224 uint64_t in_window_top; /*!< last validated record seq_num */ 01225 uint64_t in_window; /*!< bitmask for replay detection */ 01226 #endif /* MBEDTLS_SSL_DTLS_ANTI_REPLAY */ 01227 01228 size_t in_hslen; /*!< current handshake message length, 01229 including the handshake header */ 01230 int nb_zero; /*!< # of 0-length encrypted messages */ 01231 01232 int keep_current_message; /*!< drop or reuse current message 01233 on next call to record layer? */ 01234 01235 #if defined(MBEDTLS_SSL_PROTO_DTLS) 01236 uint8_t disable_datagram_packing; /*!< Disable packing multiple records 01237 * within a single datagram. */ 01238 #endif /* MBEDTLS_SSL_PROTO_DTLS */ 01239 01240 /* 01241 * Record layer (outgoing data) 01242 */ 01243 unsigned char *out_buf; /*!< output buffer */ 01244 unsigned char *out_ctr; /*!< 64-bit outgoing message counter */ 01245 unsigned char *out_hdr; /*!< start of record header */ 01246 #if defined(MBEDTLS_SSL_DTLS_CONNECTION_ID) 01247 unsigned char *out_cid; /*!< The start of the CID; 01248 * (the end is marked by in_len). */ 01249 #endif /* MBEDTLS_SSL_DTLS_CONNECTION_ID */ 01250 unsigned char *out_len; /*!< two-bytes message length field */ 01251 unsigned char *out_iv; /*!< ivlen-byte IV */ 01252 unsigned char *out_msg; /*!< message contents (out_iv+ivlen) */ 01253 01254 int out_msgtype; /*!< record header: message type */ 01255 size_t out_msglen; /*!< record header: message length */ 01256 size_t out_left; /*!< amount of data not yet written */ 01257 01258 unsigned char cur_out_ctr[8]; /*!< Outgoing record sequence number. */ 01259 01260 #if defined(MBEDTLS_SSL_PROTO_DTLS) 01261 uint16_t mtu; /*!< path mtu, used to fragment outgoing messages */ 01262 #endif /* MBEDTLS_SSL_PROTO_DTLS */ 01263 01264 #if defined(MBEDTLS_ZLIB_SUPPORT) 01265 unsigned char *compress_buf; /*!< zlib data buffer */ 01266 #endif /* MBEDTLS_ZLIB_SUPPORT */ 01267 #if defined(MBEDTLS_SSL_CBC_RECORD_SPLITTING) 01268 signed char split_done; /*!< current record already splitted? */ 01269 #endif /* MBEDTLS_SSL_CBC_RECORD_SPLITTING */ 01270 01271 /* 01272 * PKI layer 01273 */ 01274 int client_auth; /*!< flag for client auth. */ 01275 01276 /* 01277 * User settings 01278 */ 01279 #if defined(MBEDTLS_X509_CRT_PARSE_C) 01280 char *hostname; /*!< expected peer CN for verification 01281 (and SNI if available) */ 01282 #endif /* MBEDTLS_X509_CRT_PARSE_C */ 01283 01284 #if defined(MBEDTLS_SSL_ALPN) 01285 const char *alpn_chosen; /*!< negotiated protocol */ 01286 #endif /* MBEDTLS_SSL_ALPN */ 01287 01288 /* 01289 * Information for DTLS hello verify 01290 */ 01291 #if defined(MBEDTLS_SSL_DTLS_HELLO_VERIFY) && defined(MBEDTLS_SSL_SRV_C) 01292 unsigned char *cli_id; /*!< transport-level ID of the client */ 01293 size_t cli_id_len; /*!< length of cli_id */ 01294 #endif /* MBEDTLS_SSL_DTLS_HELLO_VERIFY && MBEDTLS_SSL_SRV_C */ 01295 01296 /* 01297 * Secure renegotiation 01298 */ 01299 /* needed to know when to send extension on server */ 01300 int secure_renegotiation; /*!< does peer support legacy or 01301 secure renegotiation */ 01302 #if defined(MBEDTLS_SSL_RENEGOTIATION) 01303 size_t verify_data_len; /*!< length of verify data stored */ 01304 char own_verify_data[MBEDTLS_SSL_VERIFY_DATA_MAX_LEN]; /*!< previous handshake verify data */ 01305 char peer_verify_data[MBEDTLS_SSL_VERIFY_DATA_MAX_LEN]; /*!< previous handshake verify data */ 01306 #endif /* MBEDTLS_SSL_RENEGOTIATION */ 01307 01308 #if defined(MBEDTLS_SSL_DTLS_CONNECTION_ID) 01309 /* CID configuration to use in subsequent handshakes. */ 01310 01311 /*! The next incoming CID, chosen by the user and applying to 01312 * all subsequent handshakes. This may be different from the 01313 * CID currently used in case the user has re-configured the CID 01314 * after an initial handshake. */ 01315 unsigned char own_cid[ MBEDTLS_SSL_CID_IN_LEN_MAX ]; 01316 uint8_t own_cid_len; /*!< The length of \c own_cid. */ 01317 uint8_t negotiate_cid; /*!< This indicates whether the CID extension should 01318 * be negotiated in the next handshake or not. 01319 * Possible values are #MBEDTLS_SSL_CID_ENABLED 01320 * and #MBEDTLS_SSL_CID_DISABLED. */ 01321 #endif /* MBEDTLS_SSL_DTLS_CONNECTION_ID */ 01322 }; 01323 01324 #if defined(MBEDTLS_SSL_HW_RECORD_ACCEL) 01325 01326 #define MBEDTLS_SSL_CHANNEL_OUTBOUND 0 01327 #define MBEDTLS_SSL_CHANNEL_INBOUND 1 01328 01329 extern int (*mbedtls_ssl_hw_record_init)(mbedtls_ssl_context *ssl, 01330 const unsigned char *key_enc, const unsigned char *key_dec, 01331 size_t keylen, 01332 const unsigned char *iv_enc, const unsigned char *iv_dec, 01333 size_t ivlen, 01334 const unsigned char *mac_enc, const unsigned char *mac_dec, 01335 size_t maclen); 01336 extern int (*mbedtls_ssl_hw_record_activate)(mbedtls_ssl_context *ssl, int direction); 01337 extern int (*mbedtls_ssl_hw_record_reset)(mbedtls_ssl_context *ssl); 01338 extern int (*mbedtls_ssl_hw_record_write)(mbedtls_ssl_context *ssl); 01339 extern int (*mbedtls_ssl_hw_record_read)(mbedtls_ssl_context *ssl); 01340 extern int (*mbedtls_ssl_hw_record_finish)(mbedtls_ssl_context *ssl); 01341 #endif /* MBEDTLS_SSL_HW_RECORD_ACCEL */ 01342 01343 /** 01344 * \brief Return the name of the ciphersuite associated with the 01345 * given ID 01346 * 01347 * \param ciphersuite_id SSL ciphersuite ID 01348 * 01349 * \return a string containing the ciphersuite name 01350 */ 01351 const char *mbedtls_ssl_get_ciphersuite_name( const int ciphersuite_id ); 01352 01353 /** 01354 * \brief Return the ID of the ciphersuite associated with the 01355 * given name 01356 * 01357 * \param ciphersuite_name SSL ciphersuite name 01358 * 01359 * \return the ID with the ciphersuite or 0 if not found 01360 */ 01361 int mbedtls_ssl_get_ciphersuite_id( const char *ciphersuite_name ); 01362 01363 /** 01364 * \brief Initialize an SSL context 01365 * Just makes the context ready for mbedtls_ssl_setup() or 01366 * mbedtls_ssl_free() 01367 * 01368 * \param ssl SSL context 01369 */ 01370 void mbedtls_ssl_init( mbedtls_ssl_context *ssl ); 01371 01372 /** 01373 * \brief Set up an SSL context for use 01374 * 01375 * \note No copy of the configuration context is made, it can be 01376 * shared by many mbedtls_ssl_context structures. 01377 * 01378 * \warning The conf structure will be accessed during the session. 01379 * It must not be modified or freed as long as the session 01380 * is active. 01381 * 01382 * \warning This function must be called exactly once per context. 01383 * Calling mbedtls_ssl_setup again is not supported, even 01384 * if no session is active. 01385 * 01386 * \param ssl SSL context 01387 * \param conf SSL configuration to use 01388 * 01389 * \return 0 if successful, or MBEDTLS_ERR_SSL_ALLOC_FAILED if 01390 * memory allocation failed 01391 */ 01392 int mbedtls_ssl_setup( mbedtls_ssl_context *ssl, 01393 const mbedtls_ssl_config *conf ); 01394 01395 /** 01396 * \brief Reset an already initialized SSL context for re-use 01397 * while retaining application-set variables, function 01398 * pointers and data. 01399 * 01400 * \param ssl SSL context 01401 * \return 0 if successful, or MBEDTLS_ERR_SSL_ALLOC_FAILED, 01402 MBEDTLS_ERR_SSL_HW_ACCEL_FAILED or 01403 * MBEDTLS_ERR_SSL_COMPRESSION_FAILED 01404 */ 01405 int mbedtls_ssl_session_reset( mbedtls_ssl_context *ssl ); 01406 01407 /** 01408 * \brief Set the current endpoint type 01409 * 01410 * \param conf SSL configuration 01411 * \param endpoint must be MBEDTLS_SSL_IS_CLIENT or MBEDTLS_SSL_IS_SERVER 01412 */ 01413 void mbedtls_ssl_conf_endpoint( mbedtls_ssl_config *conf, int endpoint ); 01414 01415 /** 01416 * \brief Set the transport type (TLS or DTLS). 01417 * Default: TLS 01418 * 01419 * \note For DTLS, you must either provide a recv callback that 01420 * doesn't block, or one that handles timeouts, see 01421 * \c mbedtls_ssl_set_bio(). You also need to provide timer 01422 * callbacks with \c mbedtls_ssl_set_timer_cb(). 01423 * 01424 * \param conf SSL configuration 01425 * \param transport transport type: 01426 * MBEDTLS_SSL_TRANSPORT_STREAM for TLS, 01427 * MBEDTLS_SSL_TRANSPORT_DATAGRAM for DTLS. 01428 */ 01429 void mbedtls_ssl_conf_transport( mbedtls_ssl_config *conf, int transport ); 01430 01431 /** 01432 * \brief Set the certificate verification mode 01433 * Default: NONE on server, REQUIRED on client 01434 * 01435 * \param conf SSL configuration 01436 * \param authmode can be: 01437 * 01438 * MBEDTLS_SSL_VERIFY_NONE: peer certificate is not checked 01439 * (default on server) 01440 * (insecure on client) 01441 * 01442 * MBEDTLS_SSL_VERIFY_OPTIONAL: peer certificate is checked, however the 01443 * handshake continues even if verification failed; 01444 * mbedtls_ssl_get_verify_result() can be called after the 01445 * handshake is complete. 01446 * 01447 * MBEDTLS_SSL_VERIFY_REQUIRED: peer *must* present a valid certificate, 01448 * handshake is aborted if verification failed. 01449 * (default on client) 01450 * 01451 * \note On client, MBEDTLS_SSL_VERIFY_REQUIRED is the recommended mode. 01452 * With MBEDTLS_SSL_VERIFY_OPTIONAL, the user needs to call mbedtls_ssl_get_verify_result() at 01453 * the right time(s), which may not be obvious, while REQUIRED always perform 01454 * the verification as soon as possible. For example, REQUIRED was protecting 01455 * against the "triple handshake" attack even before it was found. 01456 */ 01457 void mbedtls_ssl_conf_authmode( mbedtls_ssl_config *conf, int authmode ); 01458 01459 #if defined(MBEDTLS_X509_CRT_PARSE_C) 01460 /** 01461 * \brief Set the verification callback (Optional). 01462 * 01463 * If set, the provided verify callback is called for each 01464 * certificate in the peer's CRT chain, including the trusted 01465 * root. For more information, please see the documentation of 01466 * \c mbedtls_x509_crt_verify(). 01467 * 01468 * \note For per context callbacks and contexts, please use 01469 * mbedtls_ssl_set_verify() instead. 01470 * 01471 * \param conf The SSL configuration to use. 01472 * \param f_vrfy The verification callback to use during CRT verification. 01473 * \param p_vrfy The opaque context to be passed to the callback. 01474 */ 01475 void mbedtls_ssl_conf_verify( mbedtls_ssl_config *conf, 01476 int (*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *), 01477 void *p_vrfy ); 01478 #endif /* MBEDTLS_X509_CRT_PARSE_C */ 01479 01480 /** 01481 * \brief Set the random number generator callback 01482 * 01483 * \param conf SSL configuration 01484 * \param f_rng RNG function 01485 * \param p_rng RNG parameter 01486 */ 01487 void mbedtls_ssl_conf_rng( mbedtls_ssl_config *conf, 01488 int (*f_rng)(void *, unsigned char *, size_t), 01489 void *p_rng ); 01490 01491 /** 01492 * \brief Set the debug callback 01493 * 01494 * The callback has the following argument: 01495 * void * opaque context for the callback 01496 * int debug level 01497 * const char * file name 01498 * int line number 01499 * const char * message 01500 * 01501 * \param conf SSL configuration 01502 * \param f_dbg debug function 01503 * \param p_dbg debug parameter 01504 */ 01505 void mbedtls_ssl_conf_dbg( mbedtls_ssl_config *conf, 01506 void (*f_dbg)(void *, int, const char *, int, const char *), 01507 void *p_dbg ); 01508 01509 /** 01510 * \brief Set the underlying BIO callbacks for write, read and 01511 * read-with-timeout. 01512 * 01513 * \param ssl SSL context 01514 * \param p_bio parameter (context) shared by BIO callbacks 01515 * \param f_send write callback 01516 * \param f_recv read callback 01517 * \param f_recv_timeout blocking read callback with timeout. 01518 * 01519 * \note One of f_recv or f_recv_timeout can be NULL, in which case 01520 * the other is used. If both are non-NULL, f_recv_timeout is 01521 * used and f_recv is ignored (as if it were NULL). 01522 * 01523 * \note The two most common use cases are: 01524 * - non-blocking I/O, f_recv != NULL, f_recv_timeout == NULL 01525 * - blocking I/O, f_recv == NULL, f_recv_timout != NULL 01526 * 01527 * \note For DTLS, you need to provide either a non-NULL 01528 * f_recv_timeout callback, or a f_recv that doesn't block. 01529 * 01530 * \note See the documentations of \c mbedtls_ssl_sent_t, 01531 * \c mbedtls_ssl_recv_t and \c mbedtls_ssl_recv_timeout_t for 01532 * the conventions those callbacks must follow. 01533 * 01534 * \note On some platforms, net_sockets.c provides 01535 * \c mbedtls_net_send(), \c mbedtls_net_recv() and 01536 * \c mbedtls_net_recv_timeout() that are suitable to be used 01537 * here. 01538 */ 01539 void mbedtls_ssl_set_bio( mbedtls_ssl_context *ssl, 01540 void *p_bio, 01541 mbedtls_ssl_send_t *f_send, 01542 mbedtls_ssl_recv_t *f_recv, 01543 mbedtls_ssl_recv_timeout_t *f_recv_timeout ); 01544 01545 #if defined(MBEDTLS_SSL_PROTO_DTLS) 01546 01547 #if defined(MBEDTLS_SSL_DTLS_CONNECTION_ID) 01548 01549 01550 /** 01551 * \brief Configure the use of the Connection ID (CID) 01552 * extension in the next handshake. 01553 * 01554 * Reference: draft-ietf-tls-dtls-connection-id-05 01555 * https://tools.ietf.org/html/draft-ietf-tls-dtls-connection-id-05 01556 * 01557 * The DTLS CID extension allows the reliable association of 01558 * DTLS records to DTLS connections across changes in the 01559 * underlying transport (changed IP and Port metadata) by 01560 * adding explicit connection identifiers (CIDs) to the 01561 * headers of encrypted DTLS records. The desired CIDs are 01562 * configured by the application layer and are exchanged in 01563 * new `ClientHello` / `ServerHello` extensions during the 01564 * handshake, where each side indicates the CID it wants the 01565 * peer to use when writing encrypted messages. The CIDs are 01566 * put to use once records get encrypted: the stack discards 01567 * any incoming records that don't include the configured CID 01568 * in their header, and adds the peer's requested CID to the 01569 * headers of outgoing messages. 01570 * 01571 * This API enables or disables the use of the CID extension 01572 * in the next handshake and sets the value of the CID to 01573 * be used for incoming messages. 01574 * 01575 * \param ssl The SSL context to configure. This must be initialized. 01576 * \param enable This value determines whether the CID extension should 01577 * be used or not. Possible values are: 01578 * - MBEDTLS_SSL_CID_ENABLED to enable the use of the CID. 01579 * - MBEDTLS_SSL_CID_DISABLED (default) to disable the use 01580 * of the CID. 01581 * \param own_cid The address of the readable buffer holding the CID we want 01582 * the peer to use when sending encrypted messages to us. 01583 * This may be \c NULL if \p own_cid_len is \c 0. 01584 * This parameter is unused if \p enabled is set to 01585 * MBEDTLS_SSL_CID_DISABLED. 01586 * \param own_cid_len The length of \p own_cid. 01587 * This parameter is unused if \p enabled is set to 01588 * MBEDTLS_SSL_CID_DISABLED. 01589 * 01590 * \note The value of \p own_cid_len must match the value of the 01591 * \c len parameter passed to mbedtls_ssl_conf_cid() 01592 * when configuring the ::mbedtls_ssl_config that \p ssl 01593 * is bound to. 01594 * 01595 * \note This CID configuration applies to subsequent handshakes 01596 * performed on the SSL context \p ssl, but does not trigger 01597 * one. You still have to call `mbedtls_ssl_handshake()` 01598 * (for the initial handshake) or `mbedtls_ssl_renegotiate()` 01599 * (for a renegotiation handshake) explicitly after a 01600 * successful call to this function to run the handshake. 01601 * 01602 * \note This call cannot guarantee that the use of the CID 01603 * will be successfully negotiated in the next handshake, 01604 * because the peer might not support it. Specifically: 01605 * - On the Client, enabling the use of the CID through 01606 * this call implies that the `ClientHello` in the next 01607 * handshake will include the CID extension, thereby 01608 * offering the use of the CID to the server. Only if 01609 * the `ServerHello` contains the CID extension, too, 01610 * the CID extension will actually be put to use. 01611 * - On the Server, enabling the use of the CID through 01612 * this call implies that that the server will look for 01613 * the CID extension in a `ClientHello` from the client, 01614 * and, if present, reply with a CID extension in its 01615 * `ServerHello`. 01616 * 01617 * \note To check whether the use of the CID was negotiated 01618 * after the subsequent handshake has completed, please 01619 * use the API mbedtls_ssl_get_peer_cid(). 01620 * 01621 * \warning If the use of the CID extension is enabled in this call 01622 * and the subsequent handshake negotiates its use, Mbed TLS 01623 * will silently drop every packet whose CID does not match 01624 * the CID configured in \p own_cid. It is the responsibility 01625 * of the user to adapt the underlying transport to take care 01626 * of CID-based demultiplexing before handing datagrams to 01627 * Mbed TLS. 01628 * 01629 * \return \c 0 on success. In this case, the CID configuration 01630 * applies to the next handshake. 01631 * \return A negative error code on failure. 01632 */ 01633 int mbedtls_ssl_set_cid( mbedtls_ssl_context *ssl, 01634 int enable, 01635 unsigned char const *own_cid, 01636 size_t own_cid_len ); 01637 01638 /** 01639 * \brief Get information about the use of the CID extension 01640 * in the current connection. 01641 * 01642 * \param ssl The SSL context to query. 01643 * \param enabled The address at which to store whether the CID extension 01644 * is currently in use or not. If the CID is in use, 01645 * `*enabled` is set to MBEDTLS_SSL_CID_ENABLED; 01646 * otherwise, it is set to MBEDTLS_SSL_CID_DISABLED. 01647 * \param peer_cid The address of the buffer in which to store the CID 01648 * chosen by the peer (if the CID extension is used). 01649 * This may be \c NULL in case the value of peer CID 01650 * isn't needed. If it is not \c NULL, \p peer_cid_len 01651 * must not be \c NULL. 01652 * \param peer_cid_len The address at which to store the size of the CID 01653 * chosen by the peer (if the CID extension is used). 01654 * This is also the number of Bytes in \p peer_cid that 01655 * have been written. 01656 * This may be \c NULL in case the length of the peer CID 01657 * isn't needed. If it is \c NULL, \p peer_cid must be 01658 * \c NULL, too. 01659 * 01660 * \note This applies to the state of the CID negotiated in 01661 * the last complete handshake. If a handshake is in 01662 * progress, this function will attempt to complete 01663 * the handshake first. 01664 * 01665 * \note If CID extensions have been exchanged but both client 01666 * and server chose to use an empty CID, this function 01667 * sets `*enabled` to #MBEDTLS_SSL_CID_DISABLED 01668 * (the rationale for this is that the resulting 01669 * communication is the same as if the CID extensions 01670 * hadn't been used). 01671 * 01672 * \return \c 0 on success. 01673 * \return A negative error code on failure. 01674 */ 01675 int mbedtls_ssl_get_peer_cid( mbedtls_ssl_context *ssl, 01676 int *enabled, 01677 unsigned char peer_cid[ MBEDTLS_SSL_CID_OUT_LEN_MAX ], 01678 size_t *peer_cid_len ); 01679 01680 #endif /* MBEDTLS_SSL_DTLS_CONNECTION_ID */ 01681 01682 /** 01683 * \brief Set the Maximum Tranport Unit (MTU). 01684 * Special value: 0 means unset (no limit). 01685 * This represents the maximum size of a datagram payload 01686 * handled by the transport layer (usually UDP) as determined 01687 * by the network link and stack. In practice, this controls 01688 * the maximum size datagram the DTLS layer will pass to the 01689 * \c f_send() callback set using \c mbedtls_ssl_set_bio(). 01690 * 01691 * \note The limit on datagram size is converted to a limit on 01692 * record payload by subtracting the current overhead of 01693 * encapsulation and encryption/authentication if any. 01694 * 01695 * \note This can be called at any point during the connection, for 01696 * example when a Path Maximum Transfer Unit (PMTU) 01697 * estimate becomes available from other sources, 01698 * such as lower (or higher) protocol layers. 01699 * 01700 * \note This setting only controls the size of the packets we send, 01701 * and does not restrict the size of the datagrams we're 01702 * willing to receive. Client-side, you can request the 01703 * server to use smaller records with \c 01704 * mbedtls_ssl_conf_max_frag_len(). 01705 * 01706 * \note If both a MTU and a maximum fragment length have been 01707 * configured (or negotiated with the peer), the resulting 01708 * lower limit on record payload (see first note) is used. 01709 * 01710 * \note This can only be used to decrease the maximum size 01711 * of datagrams (hence records, see first note) sent. It 01712 * cannot be used to increase the maximum size of records over 01713 * the limit set by #MBEDTLS_SSL_OUT_CONTENT_LEN. 01714 * 01715 * \note Values lower than the current record layer expansion will 01716 * result in an error when trying to send data. 01717 * 01718 * \note Using record compression together with a non-zero MTU value 01719 * will result in an error when trying to send data. 01720 * 01721 * \param ssl SSL context 01722 * \param mtu Value of the path MTU in bytes 01723 */ 01724 void mbedtls_ssl_set_mtu( mbedtls_ssl_context *ssl, uint16_t mtu ); 01725 #endif /* MBEDTLS_SSL_PROTO_DTLS */ 01726 01727 #if defined(MBEDTLS_X509_CRT_PARSE_C) 01728 /** 01729 * \brief Set a connection-specific verification callback (optional). 01730 * 01731 * If set, the provided verify callback is called for each 01732 * certificate in the peer's CRT chain, including the trusted 01733 * root. For more information, please see the documentation of 01734 * \c mbedtls_x509_crt_verify(). 01735 * 01736 * \note This call is analogous to mbedtls_ssl_conf_verify() but 01737 * binds the verification callback and context to an SSL context 01738 * as opposed to an SSL configuration. 01739 * If mbedtls_ssl_conf_verify() and mbedtls_ssl_set_verify() 01740 * are both used, mbedtls_ssl_set_verify() takes precedence. 01741 * 01742 * \param ssl The SSL context to use. 01743 * \param f_vrfy The verification callback to use during CRT verification. 01744 * \param p_vrfy The opaque context to be passed to the callback. 01745 */ 01746 void mbedtls_ssl_set_verify( mbedtls_ssl_context *ssl, 01747 int (*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *), 01748 void *p_vrfy ); 01749 #endif /* MBEDTLS_X509_CRT_PARSE_C */ 01750 01751 /** 01752 * \brief Set the timeout period for mbedtls_ssl_read() 01753 * (Default: no timeout.) 01754 * 01755 * \param conf SSL configuration context 01756 * \param timeout Timeout value in milliseconds. 01757 * Use 0 for no timeout (default). 01758 * 01759 * \note With blocking I/O, this will only work if a non-NULL 01760 * \c f_recv_timeout was set with \c mbedtls_ssl_set_bio(). 01761 * With non-blocking I/O, this will only work if timer 01762 * callbacks were set with \c mbedtls_ssl_set_timer_cb(). 01763 * 01764 * \note With non-blocking I/O, you may also skip this function 01765 * altogether and handle timeouts at the application layer. 01766 */ 01767 void mbedtls_ssl_conf_read_timeout( mbedtls_ssl_config *conf, uint32_t timeout ); 01768 01769 #if defined(MBEDTLS_SSL_RECORD_CHECKING) 01770 /** 01771 * \brief Check whether a buffer contains a valid and authentic record 01772 * that has not been seen before. (DTLS only). 01773 * 01774 * This function does not change the user-visible state 01775 * of the SSL context. Its sole purpose is to provide 01776 * an indication of the legitimacy of an incoming record. 01777 * 01778 * This can be useful e.g. in distributed server environments 01779 * using the DTLS Connection ID feature, in which connections 01780 * might need to be passed between service instances on a change 01781 * of peer address, but where such disruptive operations should 01782 * only happen after the validity of incoming records has been 01783 * confirmed. 01784 * 01785 * \param ssl The SSL context to use. 01786 * \param buf The address of the buffer holding the record to be checked. 01787 * This must be a read/write buffer of length \p buflen Bytes. 01788 * \param buflen The length of \p buf in Bytes. 01789 * 01790 * \note This routine only checks whether the provided buffer begins 01791 * with a valid and authentic record that has not been seen 01792 * before, but does not check potential data following the 01793 * initial record. In particular, it is possible to pass DTLS 01794 * datagrams containing multiple records, in which case only 01795 * the first record is checked. 01796 * 01797 * \note This function modifies the input buffer \p buf. If you need 01798 * to preserve the original record, you have to maintain a copy. 01799 * 01800 * \return \c 0 if the record is valid and authentic and has not been 01801 * seen before. 01802 * \return MBEDTLS_ERR_SSL_INVALID_MAC if the check completed 01803 * successfully but the record was found to be not authentic. 01804 * \return MBEDTLS_ERR_SSL_INVALID_RECORD if the check completed 01805 * successfully but the record was found to be invalid for 01806 * a reason different from authenticity checking. 01807 * \return MBEDTLS_ERR_SSL_UNEXPECTED_RECORD if the check completed 01808 * successfully but the record was found to be unexpected 01809 * in the state of the SSL context, including replayed records. 01810 * \return Another negative error code on different kinds of failure. 01811 * In this case, the SSL context becomes unusable and needs 01812 * to be freed or reset before reuse. 01813 */ 01814 int mbedtls_ssl_check_record( mbedtls_ssl_context const *ssl, 01815 unsigned char *buf, 01816 size_t buflen ); 01817 #endif /* MBEDTLS_SSL_RECORD_CHECKING */ 01818 01819 /** 01820 * \brief Set the timer callbacks (Mandatory for DTLS.) 01821 * 01822 * \param ssl SSL context 01823 * \param p_timer parameter (context) shared by timer callbacks 01824 * \param f_set_timer set timer callback 01825 * \param f_get_timer get timer callback. Must return: 01826 * 01827 * \note See the documentation of \c mbedtls_ssl_set_timer_t and 01828 * \c mbedtls_ssl_get_timer_t for the conventions this pair of 01829 * callbacks must follow. 01830 * 01831 * \note On some platforms, timing.c provides 01832 * \c mbedtls_timing_set_delay() and 01833 * \c mbedtls_timing_get_delay() that are suitable for using 01834 * here, except if using an event-driven style. 01835 * 01836 * \note See also the "DTLS tutorial" article in our knowledge base. 01837 * https://tls.mbed.org/kb/how-to/dtls-tutorial 01838 */ 01839 void mbedtls_ssl_set_timer_cb( mbedtls_ssl_context *ssl, 01840 void *p_timer, 01841 mbedtls_ssl_set_timer_t *f_set_timer, 01842 mbedtls_ssl_get_timer_t *f_get_timer ); 01843 01844 /** 01845 * \brief Callback type: generate and write session ticket 01846 * 01847 * \note This describes what a callback implementation should do. 01848 * This callback should generate an encrypted and 01849 * authenticated ticket for the session and write it to the 01850 * output buffer. Here, ticket means the opaque ticket part 01851 * of the NewSessionTicket structure of RFC 5077. 01852 * 01853 * \param p_ticket Context for the callback 01854 * \param session SSL session to be written in the ticket 01855 * \param start Start of the output buffer 01856 * \param end End of the output buffer 01857 * \param tlen On exit, holds the length written 01858 * \param lifetime On exit, holds the lifetime of the ticket in seconds 01859 * 01860 * \return 0 if successful, or 01861 * a specific MBEDTLS_ERR_XXX code. 01862 */ 01863 typedef int mbedtls_ssl_ticket_write_t( void *p_ticket, 01864 const mbedtls_ssl_session *session, 01865 unsigned char *start, 01866 const unsigned char *end, 01867 size_t *tlen, 01868 uint32_t *lifetime ); 01869 01870 #if defined(MBEDTLS_SSL_EXPORT_KEYS) 01871 /** 01872 * \brief Callback type: Export key block and master secret 01873 * 01874 * \note This is required for certain uses of TLS, e.g. EAP-TLS 01875 * (RFC 5216) and Thread. The key pointers are ephemeral and 01876 * therefore must not be stored. The master secret and keys 01877 * should not be used directly except as an input to a key 01878 * derivation function. 01879 * 01880 * \param p_expkey Context for the callback 01881 * \param ms Pointer to master secret (fixed length: 48 bytes) 01882 * \param kb Pointer to key block, see RFC 5246 section 6.3 01883 * (variable length: 2 * maclen + 2 * keylen + 2 * ivlen). 01884 * \param maclen MAC length 01885 * \param keylen Key length 01886 * \param ivlen IV length 01887 * 01888 * \return 0 if successful, or 01889 * a specific MBEDTLS_ERR_XXX code. 01890 */ 01891 typedef int mbedtls_ssl_export_keys_t( void *p_expkey, 01892 const unsigned char *ms, 01893 const unsigned char *kb, 01894 size_t maclen, 01895 size_t keylen, 01896 size_t ivlen ); 01897 01898 /** 01899 * \brief Callback type: Export key block, master secret, 01900 * handshake randbytes and the tls_prf function 01901 * used to derive keys. 01902 * 01903 * \note This is required for certain uses of TLS, e.g. EAP-TLS 01904 * (RFC 5216) and Thread. The key pointers are ephemeral and 01905 * therefore must not be stored. The master secret and keys 01906 * should not be used directly except as an input to a key 01907 * derivation function. 01908 * 01909 * \param p_expkey Context for the callback. 01910 * \param ms Pointer to master secret (fixed length: 48 bytes). 01911 * \param kb Pointer to key block, see RFC 5246 section 6.3. 01912 * (variable length: 2 * maclen + 2 * keylen + 2 * ivlen). 01913 * \param maclen MAC length. 01914 * \param keylen Key length. 01915 * \param ivlen IV length. 01916 * \param client_random The client random bytes. 01917 * \param server_random The server random bytes. 01918 * \param tls_prf_type The tls_prf enum type. 01919 * 01920 * \return 0 if successful, or 01921 * a specific MBEDTLS_ERR_XXX code. 01922 */ 01923 typedef int mbedtls_ssl_export_keys_ext_t( void *p_expkey, 01924 const unsigned char *ms, 01925 const unsigned char *kb, 01926 size_t maclen, 01927 size_t keylen, 01928 size_t ivlen, 01929 const unsigned char client_random[32], 01930 const unsigned char server_random[32], 01931 mbedtls_tls_prf_types tls_prf_type ); 01932 #endif /* MBEDTLS_SSL_EXPORT_KEYS */ 01933 01934 /** 01935 * \brief Callback type: parse and load session ticket 01936 * 01937 * \note This describes what a callback implementation should do. 01938 * This callback should parse a session ticket as generated 01939 * by the corresponding mbedtls_ssl_ticket_write_t function, 01940 * and, if the ticket is authentic and valid, load the 01941 * session. 01942 * 01943 * \note The implementation is allowed to modify the first len 01944 * bytes of the input buffer, eg to use it as a temporary 01945 * area for the decrypted ticket contents. 01946 * 01947 * \param p_ticket Context for the callback 01948 * \param session SSL session to be loaded 01949 * \param buf Start of the buffer containing the ticket 01950 * \param len Length of the ticket. 01951 * 01952 * \return 0 if successful, or 01953 * MBEDTLS_ERR_SSL_INVALID_MAC if not authentic, or 01954 * MBEDTLS_ERR_SSL_SESSION_TICKET_EXPIRED if expired, or 01955 * any other non-zero code for other failures. 01956 */ 01957 typedef int mbedtls_ssl_ticket_parse_t( void *p_ticket, 01958 mbedtls_ssl_session *session, 01959 unsigned char *buf, 01960 size_t len ); 01961 01962 #if defined(MBEDTLS_SSL_SESSION_TICKETS) && defined(MBEDTLS_SSL_SRV_C) 01963 /** 01964 * \brief Configure SSL session ticket callbacks (server only). 01965 * (Default: none.) 01966 * 01967 * \note On server, session tickets are enabled by providing 01968 * non-NULL callbacks. 01969 * 01970 * \note On client, use \c mbedtls_ssl_conf_session_tickets(). 01971 * 01972 * \param conf SSL configuration context 01973 * \param f_ticket_write Callback for writing a ticket 01974 * \param f_ticket_parse Callback for parsing a ticket 01975 * \param p_ticket Context shared by the two callbacks 01976 */ 01977 void mbedtls_ssl_conf_session_tickets_cb( mbedtls_ssl_config *conf, 01978 mbedtls_ssl_ticket_write_t *f_ticket_write, 01979 mbedtls_ssl_ticket_parse_t *f_ticket_parse, 01980 void *p_ticket ); 01981 #endif /* MBEDTLS_SSL_SESSION_TICKETS && MBEDTLS_SSL_SRV_C */ 01982 01983 #if defined(MBEDTLS_SSL_EXPORT_KEYS) 01984 /** 01985 * \brief Configure key export callback. 01986 * (Default: none.) 01987 * 01988 * \note See \c mbedtls_ssl_export_keys_t. 01989 * 01990 * \param conf SSL configuration context 01991 * \param f_export_keys Callback for exporting keys 01992 * \param p_export_keys Context for the callback 01993 */ 01994 void mbedtls_ssl_conf_export_keys_cb( mbedtls_ssl_config *conf, 01995 mbedtls_ssl_export_keys_t *f_export_keys, 01996 void *p_export_keys ); 01997 01998 /** 01999 * \brief Configure extended key export callback. 02000 * (Default: none.) 02001 * 02002 * \note See \c mbedtls_ssl_export_keys_ext_t. 02003 * 02004 * \param conf SSL configuration context 02005 * \param f_export_keys_ext Callback for exporting keys 02006 * \param p_export_keys Context for the callback 02007 */ 02008 void mbedtls_ssl_conf_export_keys_ext_cb( mbedtls_ssl_config *conf, 02009 mbedtls_ssl_export_keys_ext_t *f_export_keys_ext, 02010 void *p_export_keys ); 02011 #endif /* MBEDTLS_SSL_EXPORT_KEYS */ 02012 02013 #if defined(MBEDTLS_SSL_ASYNC_PRIVATE) 02014 /** 02015 * \brief Configure asynchronous private key operation callbacks. 02016 * 02017 * \param conf SSL configuration context 02018 * \param f_async_sign Callback to start a signature operation. See 02019 * the description of ::mbedtls_ssl_async_sign_t 02020 * for more information. This may be \c NULL if the 02021 * external processor does not support any signature 02022 * operation; in this case the private key object 02023 * associated with the certificate will be used. 02024 * \param f_async_decrypt Callback to start a decryption operation. See 02025 * the description of ::mbedtls_ssl_async_decrypt_t 02026 * for more information. This may be \c NULL if the 02027 * external processor does not support any decryption 02028 * operation; in this case the private key object 02029 * associated with the certificate will be used. 02030 * \param f_async_resume Callback to resume an asynchronous operation. See 02031 * the description of ::mbedtls_ssl_async_resume_t 02032 * for more information. This may not be \c NULL unless 02033 * \p f_async_sign and \p f_async_decrypt are both 02034 * \c NULL. 02035 * \param f_async_cancel Callback to cancel an asynchronous operation. See 02036 * the description of ::mbedtls_ssl_async_cancel_t 02037 * for more information. This may be \c NULL if 02038 * no cleanup is needed. 02039 * \param config_data A pointer to configuration data which can be 02040 * retrieved with 02041 * mbedtls_ssl_conf_get_async_config_data(). The 02042 * library stores this value without dereferencing it. 02043 */ 02044 void mbedtls_ssl_conf_async_private_cb( mbedtls_ssl_config *conf, 02045 mbedtls_ssl_async_sign_t *f_async_sign, 02046 mbedtls_ssl_async_decrypt_t *f_async_decrypt, 02047 mbedtls_ssl_async_resume_t *f_async_resume, 02048 mbedtls_ssl_async_cancel_t *f_async_cancel, 02049 void *config_data ); 02050 02051 /** 02052 * \brief Retrieve the configuration data set by 02053 * mbedtls_ssl_conf_async_private_cb(). 02054 * 02055 * \param conf SSL configuration context 02056 * \return The configuration data set by 02057 * mbedtls_ssl_conf_async_private_cb(). 02058 */ 02059 void *mbedtls_ssl_conf_get_async_config_data( const mbedtls_ssl_config *conf ); 02060 02061 /** 02062 * \brief Retrieve the asynchronous operation user context. 02063 * 02064 * \note This function may only be called while a handshake 02065 * is in progress. 02066 * 02067 * \param ssl The SSL context to access. 02068 * 02069 * \return The asynchronous operation user context that was last 02070 * set during the current handshake. If 02071 * mbedtls_ssl_set_async_operation_data() has not yet been 02072 * called during the current handshake, this function returns 02073 * \c NULL. 02074 */ 02075 void *mbedtls_ssl_get_async_operation_data( const mbedtls_ssl_context *ssl ); 02076 02077 /** 02078 * \brief Retrieve the asynchronous operation user context. 02079 * 02080 * \note This function may only be called while a handshake 02081 * is in progress. 02082 * 02083 * \param ssl The SSL context to access. 02084 * \param ctx The new value of the asynchronous operation user context. 02085 * Call mbedtls_ssl_get_async_operation_data() later during the 02086 * same handshake to retrieve this value. 02087 */ 02088 void mbedtls_ssl_set_async_operation_data( mbedtls_ssl_context *ssl, 02089 void *ctx ); 02090 #endif /* MBEDTLS_SSL_ASYNC_PRIVATE */ 02091 02092 /** 02093 * \brief Callback type: generate a cookie 02094 * 02095 * \param ctx Context for the callback 02096 * \param p Buffer to write to, 02097 * must be updated to point right after the cookie 02098 * \param end Pointer to one past the end of the output buffer 02099 * \param info Client ID info that was passed to 02100 * \c mbedtls_ssl_set_client_transport_id() 02101 * \param ilen Length of info in bytes 02102 * 02103 * \return The callback must return 0 on success, 02104 * or a negative error code. 02105 */ 02106 typedef int mbedtls_ssl_cookie_write_t( void *ctx, 02107 unsigned char **p, unsigned char *end, 02108 const unsigned char *info, size_t ilen ); 02109 02110 /** 02111 * \brief Callback type: verify a cookie 02112 * 02113 * \param ctx Context for the callback 02114 * \param cookie Cookie to verify 02115 * \param clen Length of cookie 02116 * \param info Client ID info that was passed to 02117 * \c mbedtls_ssl_set_client_transport_id() 02118 * \param ilen Length of info in bytes 02119 * 02120 * \return The callback must return 0 if cookie is valid, 02121 * or a negative error code. 02122 */ 02123 typedef int mbedtls_ssl_cookie_check_t( void *ctx, 02124 const unsigned char *cookie, size_t clen, 02125 const unsigned char *info, size_t ilen ); 02126 02127 #if defined(MBEDTLS_SSL_DTLS_HELLO_VERIFY) && defined(MBEDTLS_SSL_SRV_C) 02128 /** 02129 * \brief Register callbacks for DTLS cookies 02130 * (Server only. DTLS only.) 02131 * 02132 * Default: dummy callbacks that fail, in order to force you to 02133 * register working callbacks (and initialize their context). 02134 * 02135 * To disable HelloVerifyRequest, register NULL callbacks. 02136 * 02137 * \warning Disabling hello verification allows your server to be used 02138 * for amplification in DoS attacks against other hosts. 02139 * Only disable if you known this can't happen in your 02140 * particular environment. 02141 * 02142 * \note See comments on \c mbedtls_ssl_handshake() about handling 02143 * the MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED that is expected 02144 * on the first handshake attempt when this is enabled. 02145 * 02146 * \note This is also necessary to handle client reconnection from 02147 * the same port as described in RFC 6347 section 4.2.8 (only 02148 * the variant with cookies is supported currently). See 02149 * comments on \c mbedtls_ssl_read() for details. 02150 * 02151 * \param conf SSL configuration 02152 * \param f_cookie_write Cookie write callback 02153 * \param f_cookie_check Cookie check callback 02154 * \param p_cookie Context for both callbacks 02155 */ 02156 void mbedtls_ssl_conf_dtls_cookies( mbedtls_ssl_config *conf, 02157 mbedtls_ssl_cookie_write_t *f_cookie_write, 02158 mbedtls_ssl_cookie_check_t *f_cookie_check, 02159 void *p_cookie ); 02160 02161 /** 02162 * \brief Set client's transport-level identification info. 02163 * (Server only. DTLS only.) 02164 * 02165 * This is usually the IP address (and port), but could be 02166 * anything identify the client depending on the underlying 02167 * network stack. Used for HelloVerifyRequest with DTLS. 02168 * This is *not* used to route the actual packets. 02169 * 02170 * \param ssl SSL context 02171 * \param info Transport-level info identifying the client (eg IP + port) 02172 * \param ilen Length of info in bytes 02173 * 02174 * \note An internal copy is made, so the info buffer can be reused. 02175 * 02176 * \return 0 on success, 02177 * MBEDTLS_ERR_SSL_BAD_INPUT_DATA if used on client, 02178 * MBEDTLS_ERR_SSL_ALLOC_FAILED if out of memory. 02179 */ 02180 int mbedtls_ssl_set_client_transport_id( mbedtls_ssl_context *ssl, 02181 const unsigned char *info, 02182 size_t ilen ); 02183 02184 #endif /* MBEDTLS_SSL_DTLS_HELLO_VERIFY && MBEDTLS_SSL_SRV_C */ 02185 02186 #if defined(MBEDTLS_SSL_DTLS_ANTI_REPLAY) 02187 /** 02188 * \brief Enable or disable anti-replay protection for DTLS. 02189 * (DTLS only, no effect on TLS.) 02190 * Default: enabled. 02191 * 02192 * \param conf SSL configuration 02193 * \param mode MBEDTLS_SSL_ANTI_REPLAY_ENABLED or MBEDTLS_SSL_ANTI_REPLAY_DISABLED. 02194 * 02195 * \warning Disabling this is a security risk unless the application 02196 * protocol handles duplicated packets in a safe way. You 02197 * should not disable this without careful consideration. 02198 * However, if your application already detects duplicated 02199 * packets and needs information about them to adjust its 02200 * transmission strategy, then you'll want to disable this. 02201 */ 02202 void mbedtls_ssl_conf_dtls_anti_replay( mbedtls_ssl_config *conf, char mode ); 02203 #endif /* MBEDTLS_SSL_DTLS_ANTI_REPLAY */ 02204 02205 #if defined(MBEDTLS_SSL_DTLS_BADMAC_LIMIT) 02206 /** 02207 * \brief Set a limit on the number of records with a bad MAC 02208 * before terminating the connection. 02209 * (DTLS only, no effect on TLS.) 02210 * Default: 0 (disabled). 02211 * 02212 * \param conf SSL configuration 02213 * \param limit Limit, or 0 to disable. 02214 * 02215 * \note If the limit is N, then the connection is terminated when 02216 * the Nth non-authentic record is seen. 02217 * 02218 * \note Records with an invalid header are not counted, only the 02219 * ones going through the authentication-decryption phase. 02220 * 02221 * \note This is a security trade-off related to the fact that it's 02222 * often relatively easy for an active attacker ot inject UDP 02223 * datagrams. On one hand, setting a low limit here makes it 02224 * easier for such an attacker to forcibly terminated a 02225 * connection. On the other hand, a high limit or no limit 02226 * might make us waste resources checking authentication on 02227 * many bogus packets. 02228 */ 02229 void mbedtls_ssl_conf_dtls_badmac_limit( mbedtls_ssl_config *conf, unsigned limit ); 02230 #endif /* MBEDTLS_SSL_DTLS_BADMAC_LIMIT */ 02231 02232 #if defined(MBEDTLS_SSL_PROTO_DTLS) 02233 02234 /** 02235 * \brief Allow or disallow packing of multiple handshake records 02236 * within a single datagram. 02237 * 02238 * \param ssl The SSL context to configure. 02239 * \param allow_packing This determines whether datagram packing may 02240 * be used or not. A value of \c 0 means that every 02241 * record will be sent in a separate datagram; a 02242 * value of \c 1 means that, if space permits, 02243 * multiple handshake messages (including CCS) belonging to 02244 * a single flight may be packed within a single datagram. 02245 * 02246 * \note This is enabled by default and should only be disabled 02247 * for test purposes, or if datagram packing causes 02248 * interoperability issues with peers that don't support it. 02249 * 02250 * \note Allowing datagram packing reduces the network load since 02251 * there's less overhead if multiple messages share the same 02252 * datagram. Also, it increases the handshake efficiency 02253 * since messages belonging to a single datagram will not 02254 * be reordered in transit, and so future message buffering 02255 * or flight retransmission (if no buffering is used) as 02256 * means to deal with reordering are needed less frequently. 02257 * 02258 * \note Application records are not affected by this option and 02259 * are currently always sent in separate datagrams. 02260 * 02261 */ 02262 void mbedtls_ssl_set_datagram_packing( mbedtls_ssl_context *ssl, 02263 unsigned allow_packing ); 02264 02265 /** 02266 * \brief Set retransmit timeout values for the DTLS handshake. 02267 * (DTLS only, no effect on TLS.) 02268 * 02269 * \param conf SSL configuration 02270 * \param min Initial timeout value in milliseconds. 02271 * Default: 1000 (1 second). 02272 * \param max Maximum timeout value in milliseconds. 02273 * Default: 60000 (60 seconds). 02274 * 02275 * \note Default values are from RFC 6347 section 4.2.4.1. 02276 * 02277 * \note The 'min' value should typically be slightly above the 02278 * expected round-trip time to your peer, plus whatever time 02279 * it takes for the peer to process the message. For example, 02280 * if your RTT is about 600ms and you peer needs up to 1s to 02281 * do the cryptographic operations in the handshake, then you 02282 * should set 'min' slightly above 1600. Lower values of 'min' 02283 * might cause spurious resends which waste network resources, 02284 * while larger value of 'min' will increase overall latency 02285 * on unreliable network links. 02286 * 02287 * \note The more unreliable your network connection is, the larger 02288 * your max / min ratio needs to be in order to achieve 02289 * reliable handshakes. 02290 * 02291 * \note Messages are retransmitted up to log2(ceil(max/min)) times. 02292 * For example, if min = 1s and max = 5s, the retransmit plan 02293 * goes: send ... 1s -> resend ... 2s -> resend ... 4s -> 02294 * resend ... 5s -> give up and return a timeout error. 02295 */ 02296 void mbedtls_ssl_conf_handshake_timeout( mbedtls_ssl_config *conf, uint32_t min, uint32_t max ); 02297 #endif /* MBEDTLS_SSL_PROTO_DTLS */ 02298 02299 #if defined(MBEDTLS_SSL_SRV_C) 02300 /** 02301 * \brief Set the session cache callbacks (server-side only) 02302 * If not set, no session resuming is done (except if session 02303 * tickets are enabled too). 02304 * 02305 * The session cache has the responsibility to check for stale 02306 * entries based on timeout. See RFC 5246 for recommendations. 02307 * 02308 * Warning: session.peer_cert is cleared by the SSL/TLS layer on 02309 * connection shutdown, so do not cache the pointer! Either set 02310 * it to NULL or make a full copy of the certificate. 02311 * 02312 * The get callback is called once during the initial handshake 02313 * to enable session resuming. The get function has the 02314 * following parameters: (void *parameter, mbedtls_ssl_session *session) 02315 * If a valid entry is found, it should fill the master of 02316 * the session object with the cached values and return 0, 02317 * return 1 otherwise. Optionally peer_cert can be set as well 02318 * if it is properly present in cache entry. 02319 * 02320 * The set callback is called once during the initial handshake 02321 * to enable session resuming after the entire handshake has 02322 * been finished. The set function has the following parameters: 02323 * (void *parameter, const mbedtls_ssl_session *session). The function 02324 * should create a cache entry for future retrieval based on 02325 * the data in the session structure and should keep in mind 02326 * that the mbedtls_ssl_session object presented (and all its referenced 02327 * data) is cleared by the SSL/TLS layer when the connection is 02328 * terminated. It is recommended to add metadata to determine if 02329 * an entry is still valid in the future. Return 0 if 02330 * successfully cached, return 1 otherwise. 02331 * 02332 * \param conf SSL configuration 02333 * \param p_cache parmater (context) for both callbacks 02334 * \param f_get_cache session get callback 02335 * \param f_set_cache session set callback 02336 */ 02337 void mbedtls_ssl_conf_session_cache( mbedtls_ssl_config *conf, 02338 void *p_cache, 02339 int (*f_get_cache)(void *, mbedtls_ssl_session *), 02340 int (*f_set_cache)(void *, const mbedtls_ssl_session *) ); 02341 #endif /* MBEDTLS_SSL_SRV_C */ 02342 02343 #if defined(MBEDTLS_SSL_CLI_C) 02344 /** 02345 * \brief Request resumption of session (client-side only) 02346 * Session data is copied from presented session structure. 02347 * 02348 * \param ssl SSL context 02349 * \param session session context 02350 * 02351 * \return 0 if successful, 02352 * MBEDTLS_ERR_SSL_ALLOC_FAILED if memory allocation failed, 02353 * MBEDTLS_ERR_SSL_BAD_INPUT_DATA if used server-side or 02354 * arguments are otherwise invalid 02355 * 02356 * \sa mbedtls_ssl_get_session() 02357 */ 02358 int mbedtls_ssl_set_session( mbedtls_ssl_context *ssl, const mbedtls_ssl_session *session ); 02359 #endif /* MBEDTLS_SSL_CLI_C */ 02360 02361 /** 02362 * \brief Load serialized session data into a session structure. 02363 * On client, this can be used for loading saved sessions 02364 * before resuming them with mbedstls_ssl_set_session(). 02365 * On server, this can be used for alternative implementations 02366 * of session cache or session tickets. 02367 * 02368 * \warning If a peer certificate chain is associated with the session, 02369 * the serialized state will only contain the peer's 02370 * end-entity certificate and the result of the chain 02371 * verification (unless verification was disabled), but not 02372 * the rest of the chain. 02373 * 02374 * \see mbedtls_ssl_session_save() 02375 * \see mbedtls_ssl_set_session() 02376 * 02377 * \param session The session structure to be populated. It must have been 02378 * initialised with mbedtls_ssl_session_init() but not 02379 * populated yet. 02380 * \param buf The buffer holding the serialized session data. It must be a 02381 * readable buffer of at least \p len bytes. 02382 * \param len The size of the serialized data in bytes. 02383 * 02384 * \return \c 0 if successful. 02385 * \return #MBEDTLS_ERR_SSL_ALLOC_FAILED if memory allocation failed. 02386 * \return #MBEDTLS_ERR_SSL_BAD_INPUT_DATA if input data is invalid. 02387 * \return #MBEDTLS_ERR_SSL_VERSION_MISMATCH if the serialized data 02388 * was generated in a different version or configuration of 02389 * Mbed TLS. 02390 * \return Another negative value for other kinds of errors (for 02391 * example, unsupported features in the embedded certificate). 02392 */ 02393 int mbedtls_ssl_session_load( mbedtls_ssl_session *session, 02394 const unsigned char *buf, 02395 size_t len ); 02396 02397 /** 02398 * \brief Save session structure as serialized data in a buffer. 02399 * On client, this can be used for saving session data, 02400 * potentially in non-volatile storage, for resuming later. 02401 * On server, this can be used for alternative implementations 02402 * of session cache or session tickets. 02403 * 02404 * \see mbedtls_ssl_session_load() 02405 * \see mbedtls_ssl_get_session_pointer() 02406 * 02407 * \param session The session structure to be saved. 02408 * \param buf The buffer to write the serialized data to. It must be a 02409 * writeable buffer of at least \p len bytes, or may be \c 02410 * NULL if \p len is \c 0. 02411 * \param buf_len The number of bytes available for writing in \p buf. 02412 * \param olen The size in bytes of the data that has been or would have 02413 * been written. It must point to a valid \c size_t. 02414 * 02415 * \note \p olen is updated to the correct value regardless of 02416 * whether \p buf_len was large enough. This makes it possible 02417 * to determine the necessary size by calling this function 02418 * with \p buf set to \c NULL and \p buf_len to \c 0. 02419 * 02420 * \return \c 0 if successful. 02421 * \return #MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL if \p buf is too small. 02422 */ 02423 int mbedtls_ssl_session_save( const mbedtls_ssl_session *session, 02424 unsigned char *buf, 02425 size_t buf_len, 02426 size_t *olen ); 02427 02428 /** 02429 * \brief Get a pointer to the current session structure, for example 02430 * to serialize it. 02431 * 02432 * \warning Ownership of the session remains with the SSL context, and 02433 * the returned pointer is only guaranteed to be valid until 02434 * the next API call operating on the same \p ssl context. 02435 * 02436 * \see mbedtls_ssl_session_save() 02437 * 02438 * \param ssl The SSL context. 02439 * 02440 * \return A pointer to the current session if successful. 02441 * \return \c NULL if no session is active. 02442 */ 02443 const mbedtls_ssl_session *mbedtls_ssl_get_session_pointer( const mbedtls_ssl_context *ssl ); 02444 02445 /** 02446 * \brief Set the list of allowed ciphersuites and the preference 02447 * order. First in the list has the highest preference. 02448 * (Overrides all version-specific lists) 02449 * 02450 * The ciphersuites array is not copied, and must remain 02451 * valid for the lifetime of the ssl_config. 02452 * 02453 * Note: The server uses its own preferences 02454 * over the preference of the client unless 02455 * MBEDTLS_SSL_SRV_RESPECT_CLIENT_PREFERENCE is defined! 02456 * 02457 * \param conf SSL configuration 02458 * \param ciphersuites 0-terminated list of allowed ciphersuites 02459 */ 02460 void mbedtls_ssl_conf_ciphersuites( mbedtls_ssl_config *conf, 02461 const int *ciphersuites ); 02462 02463 #if defined(MBEDTLS_SSL_DTLS_CONNECTION_ID) 02464 #define MBEDTLS_SSL_UNEXPECTED_CID_IGNORE 0 02465 #define MBEDTLS_SSL_UNEXPECTED_CID_FAIL 1 02466 /** 02467 * \brief Specify the length of Connection IDs for incoming 02468 * encrypted DTLS records, as well as the behaviour 02469 * on unexpected CIDs. 02470 * 02471 * By default, the CID length is set to \c 0, 02472 * and unexpected CIDs are silently ignored. 02473 * 02474 * \param conf The SSL configuration to modify. 02475 * \param len The length in Bytes of the CID fields in encrypted 02476 * DTLS records using the CID mechanism. This must 02477 * not be larger than #MBEDTLS_SSL_CID_OUT_LEN_MAX. 02478 * \param ignore_other_cids This determines the stack's behaviour when 02479 * receiving a record with an unexpected CID. 02480 * Possible values are: 02481 * - #MBEDTLS_SSL_UNEXPECTED_CID_IGNORE 02482 * In this case, the record is silently ignored. 02483 * - #MBEDTLS_SSL_UNEXPECTED_CID_FAIL 02484 * In this case, the stack fails with the specific 02485 * error code #MBEDTLS_ERR_SSL_UNEXPECTED_CID. 02486 * 02487 * \note The CID specification allows implementations to either 02488 * use a common length for all incoming connection IDs or 02489 * allow variable-length incoming IDs. Mbed TLS currently 02490 * requires a common length for all connections sharing the 02491 * same SSL configuration; this allows simpler parsing of 02492 * record headers. 02493 * 02494 * \return \c 0 on success. 02495 * \return #MBEDTLS_ERR_SSL_BAD_INPUT_DATA if \p own_cid_len 02496 * is too large. 02497 */ 02498 int mbedtls_ssl_conf_cid( mbedtls_ssl_config *conf, size_t len, 02499 int ignore_other_cids ); 02500 #endif /* MBEDTLS_SSL_DTLS_CONNECTION_ID */ 02501 02502 /** 02503 * \brief Set the list of allowed ciphersuites and the 02504 * preference order for a specific version of the protocol. 02505 * (Only useful on the server side) 02506 * 02507 * The ciphersuites array is not copied, and must remain 02508 * valid for the lifetime of the ssl_config. 02509 * 02510 * \param conf SSL configuration 02511 * \param ciphersuites 0-terminated list of allowed ciphersuites 02512 * \param major Major version number (only MBEDTLS_SSL_MAJOR_VERSION_3 02513 * supported) 02514 * \param minor Minor version number (MBEDTLS_SSL_MINOR_VERSION_0, 02515 * MBEDTLS_SSL_MINOR_VERSION_1 and MBEDTLS_SSL_MINOR_VERSION_2, 02516 * MBEDTLS_SSL_MINOR_VERSION_3 supported) 02517 * 02518 * \note With DTLS, use MBEDTLS_SSL_MINOR_VERSION_2 for DTLS 1.0 02519 * and MBEDTLS_SSL_MINOR_VERSION_3 for DTLS 1.2 02520 */ 02521 void mbedtls_ssl_conf_ciphersuites_for_version( mbedtls_ssl_config *conf, 02522 const int *ciphersuites, 02523 int major, int minor ); 02524 02525 #if defined(MBEDTLS_X509_CRT_PARSE_C) 02526 /** 02527 * \brief Set the X.509 security profile used for verification 02528 * 02529 * \note The restrictions are enforced for all certificates in the 02530 * chain. However, signatures in the handshake are not covered 02531 * by this setting but by \b mbedtls_ssl_conf_sig_hashes(). 02532 * 02533 * \param conf SSL configuration 02534 * \param profile Profile to use 02535 */ 02536 void mbedtls_ssl_conf_cert_profile( mbedtls_ssl_config *conf, 02537 const mbedtls_x509_crt_profile *profile ); 02538 02539 /** 02540 * \brief Set the data required to verify peer certificate 02541 * 02542 * \note See \c mbedtls_x509_crt_verify() for notes regarding the 02543 * parameters ca_chain (maps to trust_ca for that function) 02544 * and ca_crl. 02545 * 02546 * \param conf SSL configuration 02547 * \param ca_chain trusted CA chain (meaning all fully trusted top-level CAs) 02548 * \param ca_crl trusted CA CRLs 02549 */ 02550 void mbedtls_ssl_conf_ca_chain( mbedtls_ssl_config *conf, 02551 mbedtls_x509_crt *ca_chain, 02552 mbedtls_x509_crl *ca_crl ); 02553 02554 #if defined(MBEDTLS_X509_TRUSTED_CERTIFICATE_CALLBACK) 02555 /** 02556 * \brief Set the trusted certificate callback. 02557 * 02558 * This API allows to register the set of trusted certificates 02559 * through a callback, instead of a linked list as configured 02560 * by mbedtls_ssl_conf_ca_chain(). 02561 * 02562 * This is useful for example in contexts where a large number 02563 * of CAs are used, and the inefficiency of maintaining them 02564 * in a linked list cannot be tolerated. It is also useful when 02565 * the set of trusted CAs needs to be modified frequently. 02566 * 02567 * See the documentation of `mbedtls_x509_crt_ca_cb_t` for 02568 * more information. 02569 * 02570 * \param conf The SSL configuration to register the callback with. 02571 * \param f_ca_cb The trusted certificate callback to use when verifying 02572 * certificate chains. 02573 * \param p_ca_cb The context to be passed to \p f_ca_cb (for example, 02574 * a reference to a trusted CA database). 02575 * 02576 * \note This API is incompatible with mbedtls_ssl_conf_ca_chain(): 02577 * Any call to this function overwrites the values set through 02578 * earlier calls to mbedtls_ssl_conf_ca_chain() or 02579 * mbedtls_ssl_conf_ca_cb(). 02580 * 02581 * \note This API is incompatible with CA indication in 02582 * CertificateRequest messages: A server-side SSL context which 02583 * is bound to an SSL configuration that uses a CA callback 02584 * configured via mbedtls_ssl_conf_ca_cb(), and which requires 02585 * client authentication, will send an empty CA list in the 02586 * corresponding CertificateRequest message. 02587 * 02588 * \note This API is incompatible with mbedtls_ssl_set_hs_ca_chain(): 02589 * If an SSL context is bound to an SSL configuration which uses 02590 * CA callbacks configured via mbedtls_ssl_conf_ca_cb(), then 02591 * calls to mbedtls_ssl_set_hs_ca_chain() have no effect. 02592 * 02593 * \note The use of this API disables the use of restartable ECC 02594 * during X.509 CRT signature verification (but doesn't affect 02595 * other uses). 02596 * 02597 * \warning This API is incompatible with the use of CRLs. Any call to 02598 * mbedtls_ssl_conf_ca_cb() unsets CRLs configured through 02599 * earlier calls to mbedtls_ssl_conf_ca_chain(). 02600 * 02601 * \warning In multi-threaded environments, the callback \p f_ca_cb 02602 * must be thread-safe, and it is the user's responsibility 02603 * to guarantee this (for example through a mutex 02604 * contained in the callback context pointed to by \p p_ca_cb). 02605 */ 02606 void mbedtls_ssl_conf_ca_cb( mbedtls_ssl_config *conf, 02607 mbedtls_x509_crt_ca_cb_t f_ca_cb, 02608 void *p_ca_cb ); 02609 #endif /* MBEDTLS_X509_TRUSTED_CERTIFICATE_CALLBACK */ 02610 02611 /** 02612 * \brief Set own certificate chain and private key 02613 * 02614 * \note own_cert should contain in order from the bottom up your 02615 * certificate chain. The top certificate (self-signed) 02616 * can be omitted. 02617 * 02618 * \note On server, this function can be called multiple times to 02619 * provision more than one cert/key pair (eg one ECDSA, one 02620 * RSA with SHA-256, one RSA with SHA-1). An adequate 02621 * certificate will be selected according to the client's 02622 * advertised capabilities. In case multiple certificates are 02623 * adequate, preference is given to the one set by the first 02624 * call to this function, then second, etc. 02625 * 02626 * \note On client, only the first call has any effect. That is, 02627 * only one client certificate can be provisioned. The 02628 * server's preferences in its CertficateRequest message will 02629 * be ignored and our only cert will be sent regardless of 02630 * whether it matches those preferences - the server can then 02631 * decide what it wants to do with it. 02632 * 02633 * \note The provided \p pk_key needs to match the public key in the 02634 * first certificate in \p own_cert, or all handshakes using 02635 * that certificate will fail. It is your responsibility 02636 * to ensure that; this function will not perform any check. 02637 * You may use mbedtls_pk_check_pair() in order to perform 02638 * this check yourself, but be aware that this function can 02639 * be computationally expensive on some key types. 02640 * 02641 * \param conf SSL configuration 02642 * \param own_cert own public certificate chain 02643 * \param pk_key own private key 02644 * 02645 * \return 0 on success or MBEDTLS_ERR_SSL_ALLOC_FAILED 02646 */ 02647 int mbedtls_ssl_conf_own_cert( mbedtls_ssl_config *conf, 02648 mbedtls_x509_crt *own_cert, 02649 mbedtls_pk_context *pk_key ); 02650 #endif /* MBEDTLS_X509_CRT_PARSE_C */ 02651 02652 #if defined(MBEDTLS_KEY_EXCHANGE__SOME__PSK_ENABLED) 02653 /** 02654 * \brief Configure a pre-shared key (PSK) and identity 02655 * to be used in PSK-based ciphersuites. 02656 * 02657 * \note This is mainly useful for clients. Servers will usually 02658 * want to use \c mbedtls_ssl_conf_psk_cb() instead. 02659 * 02660 * \warning Currently, clients can only register a single pre-shared key. 02661 * Calling this function or mbedtls_ssl_conf_psk_opaque() more 02662 * than once will overwrite values configured in previous calls. 02663 * Support for setting multiple PSKs on clients and selecting 02664 * one based on the identity hint is not a planned feature, 02665 * but feedback is welcomed. 02666 * 02667 * \param conf The SSL configuration to register the PSK with. 02668 * \param psk The pointer to the pre-shared key to use. 02669 * \param psk_len The length of the pre-shared key in bytes. 02670 * \param psk_identity The pointer to the pre-shared key identity. 02671 * \param psk_identity_len The length of the pre-shared key identity 02672 * in bytes. 02673 * 02674 * \note The PSK and its identity are copied internally and 02675 * hence need not be preserved by the caller for the lifetime 02676 * of the SSL configuration. 02677 * 02678 * \return \c 0 if successful. 02679 * \return An \c MBEDTLS_ERR_SSL_XXX error code on failure. 02680 */ 02681 int mbedtls_ssl_conf_psk( mbedtls_ssl_config *conf, 02682 const unsigned char *psk, size_t psk_len, 02683 const unsigned char *psk_identity, size_t psk_identity_len ); 02684 02685 #if defined(MBEDTLS_USE_PSA_CRYPTO) 02686 /** 02687 * \brief Configure an opaque pre-shared key (PSK) and identity 02688 * to be used in PSK-based ciphersuites. 02689 * 02690 * \note This is mainly useful for clients. Servers will usually 02691 * want to use \c mbedtls_ssl_conf_psk_cb() instead. 02692 * 02693 * \warning Currently, clients can only register a single pre-shared key. 02694 * Calling this function or mbedtls_ssl_conf_psk() more than 02695 * once will overwrite values configured in previous calls. 02696 * Support for setting multiple PSKs on clients and selecting 02697 * one based on the identity hint is not a planned feature, 02698 * but feedback is welcomed. 02699 * 02700 * \param conf The SSL configuration to register the PSK with. 02701 * \param psk The identifier of the key slot holding the PSK. 02702 * Until \p conf is destroyed or this function is successfully 02703 * called again, the key slot \p psk must be populated with a 02704 * key of type PSA_ALG_CATEGORY_KEY_DERIVATION whose policy 02705 * allows its use for the key derivation algorithm applied 02706 * in the handshake. 02707 * \param psk_identity The pointer to the pre-shared key identity. 02708 * \param psk_identity_len The length of the pre-shared key identity 02709 * in bytes. 02710 * 02711 * \note The PSK identity hint is copied internally and hence need 02712 * not be preserved by the caller for the lifetime of the 02713 * SSL configuration. 02714 * 02715 * \return \c 0 if successful. 02716 * \return An \c MBEDTLS_ERR_SSL_XXX error code on failure. 02717 */ 02718 int mbedtls_ssl_conf_psk_opaque( mbedtls_ssl_config *conf, 02719 psa_key_handle_t psk, 02720 const unsigned char *psk_identity, 02721 size_t psk_identity_len ); 02722 #endif /* MBEDTLS_USE_PSA_CRYPTO */ 02723 02724 /** 02725 * \brief Set the pre-shared Key (PSK) for the current handshake. 02726 * 02727 * \note This should only be called inside the PSK callback, 02728 * i.e. the function passed to \c mbedtls_ssl_conf_psk_cb(). 02729 * 02730 * \param ssl The SSL context to configure a PSK for. 02731 * \param psk The pointer to the pre-shared key. 02732 * \param psk_len The length of the pre-shared key in bytes. 02733 * 02734 * \return \c 0 if successful. 02735 * \return An \c MBEDTLS_ERR_SSL_XXX error code on failure. 02736 */ 02737 int mbedtls_ssl_set_hs_psk( mbedtls_ssl_context *ssl, 02738 const unsigned char *psk, size_t psk_len ); 02739 02740 #if defined(MBEDTLS_USE_PSA_CRYPTO) 02741 /** 02742 * \brief Set an opaque pre-shared Key (PSK) for the current handshake. 02743 * 02744 * \note This should only be called inside the PSK callback, 02745 * i.e. the function passed to \c mbedtls_ssl_conf_psk_cb(). 02746 * 02747 * \param ssl The SSL context to configure a PSK for. 02748 * \param psk The identifier of the key slot holding the PSK. 02749 * For the duration of the current handshake, the key slot 02750 * must be populated with a key of type 02751 * PSA_ALG_CATEGORY_KEY_DERIVATION whose policy allows its 02752 * use for the key derivation algorithm 02753 * applied in the handshake. 02754 * 02755 * \return \c 0 if successful. 02756 * \return An \c MBEDTLS_ERR_SSL_XXX error code on failure. 02757 */ 02758 int mbedtls_ssl_set_hs_psk_opaque( mbedtls_ssl_context *ssl, 02759 psa_key_handle_t psk ); 02760 #endif /* MBEDTLS_USE_PSA_CRYPTO */ 02761 02762 /** 02763 * \brief Set the PSK callback (server-side only). 02764 * 02765 * If set, the PSK callback is called for each 02766 * handshake where a PSK-based ciphersuite was negotiated. 02767 * The caller provides the identity received and wants to 02768 * receive the actual PSK data and length. 02769 * 02770 * The callback has the following parameters: 02771 * - \c void*: The opaque pointer \p p_psk. 02772 * - \c mbedtls_ssl_context*: The SSL context to which 02773 * the operation applies. 02774 * - \c const unsigned char*: The PSK identity 02775 * selected by the client. 02776 * - \c size_t: The length of the PSK identity 02777 * selected by the client. 02778 * 02779 * If a valid PSK identity is found, the callback should use 02780 * \c mbedtls_ssl_set_hs_psk() or 02781 * \c mbedtls_ssl_set_hs_psk_opaque() 02782 * on the SSL context to set the correct PSK and return \c 0. 02783 * Any other return value will result in a denied PSK identity. 02784 * 02785 * \note If you set a PSK callback using this function, then you 02786 * don't need to set a PSK key and identity using 02787 * \c mbedtls_ssl_conf_psk(). 02788 * 02789 * \param conf The SSL configuration to register the callback with. 02790 * \param f_psk The callback for selecting and setting the PSK based 02791 * in the PSK identity chosen by the client. 02792 * \param p_psk A pointer to an opaque structure to be passed to 02793 * the callback, for example a PSK store. 02794 */ 02795 void mbedtls_ssl_conf_psk_cb( mbedtls_ssl_config *conf, 02796 int (*f_psk)(void *, mbedtls_ssl_context *, const unsigned char *, 02797 size_t), 02798 void *p_psk ); 02799 #endif /* MBEDTLS_KEY_EXCHANGE__SOME__PSK_ENABLED */ 02800 02801 #if defined(MBEDTLS_DHM_C) && defined(MBEDTLS_SSL_SRV_C) 02802 02803 #if !defined(MBEDTLS_DEPRECATED_REMOVED) 02804 02805 #if defined(MBEDTLS_DEPRECATED_WARNING) 02806 #define MBEDTLS_DEPRECATED __attribute__((deprecated)) 02807 #else 02808 #define MBEDTLS_DEPRECATED 02809 #endif 02810 02811 /** 02812 * \brief Set the Diffie-Hellman public P and G values, 02813 * read as hexadecimal strings (server-side only) 02814 * (Default values: MBEDTLS_DHM_RFC3526_MODP_2048_[PG]) 02815 * 02816 * \param conf SSL configuration 02817 * \param dhm_P Diffie-Hellman-Merkle modulus 02818 * \param dhm_G Diffie-Hellman-Merkle generator 02819 * 02820 * \deprecated Superseded by \c mbedtls_ssl_conf_dh_param_bin. 02821 * 02822 * \return 0 if successful 02823 */ 02824 MBEDTLS_DEPRECATED int mbedtls_ssl_conf_dh_param( mbedtls_ssl_config *conf, 02825 const char *dhm_P, 02826 const char *dhm_G ); 02827 02828 #endif /* MBEDTLS_DEPRECATED_REMOVED */ 02829 02830 /** 02831 * \brief Set the Diffie-Hellman public P and G values 02832 * from big-endian binary presentations. 02833 * (Default values: MBEDTLS_DHM_RFC3526_MODP_2048_[PG]_BIN) 02834 * 02835 * \param conf SSL configuration 02836 * \param dhm_P Diffie-Hellman-Merkle modulus in big-endian binary form 02837 * \param P_len Length of DHM modulus 02838 * \param dhm_G Diffie-Hellman-Merkle generator in big-endian binary form 02839 * \param G_len Length of DHM generator 02840 * 02841 * \return 0 if successful 02842 */ 02843 int mbedtls_ssl_conf_dh_param_bin( mbedtls_ssl_config *conf, 02844 const unsigned char *dhm_P, size_t P_len, 02845 const unsigned char *dhm_G, size_t G_len ); 02846 02847 /** 02848 * \brief Set the Diffie-Hellman public P and G values, 02849 * read from existing context (server-side only) 02850 * 02851 * \param conf SSL configuration 02852 * \param dhm_ctx Diffie-Hellman-Merkle context 02853 * 02854 * \return 0 if successful 02855 */ 02856 int mbedtls_ssl_conf_dh_param_ctx( mbedtls_ssl_config *conf, mbedtls_dhm_context *dhm_ctx ); 02857 #endif /* MBEDTLS_DHM_C && defined(MBEDTLS_SSL_SRV_C) */ 02858 02859 #if defined(MBEDTLS_DHM_C) && defined(MBEDTLS_SSL_CLI_C) 02860 /** 02861 * \brief Set the minimum length for Diffie-Hellman parameters. 02862 * (Client-side only.) 02863 * (Default: 1024 bits.) 02864 * 02865 * \param conf SSL configuration 02866 * \param bitlen Minimum bit length of the DHM prime 02867 */ 02868 void mbedtls_ssl_conf_dhm_min_bitlen( mbedtls_ssl_config *conf, 02869 unsigned int bitlen ); 02870 #endif /* MBEDTLS_DHM_C && MBEDTLS_SSL_CLI_C */ 02871 02872 #if defined(MBEDTLS_ECP_C) 02873 /** 02874 * \brief Set the allowed curves in order of preference. 02875 * (Default: all defined curves.) 02876 * 02877 * On server: this only affects selection of the ECDHE curve; 02878 * the curves used for ECDH and ECDSA are determined by the 02879 * list of available certificates instead. 02880 * 02881 * On client: this affects the list of curves offered for any 02882 * use. The server can override our preference order. 02883 * 02884 * Both sides: limits the set of curves accepted for use in 02885 * ECDHE and in the peer's end-entity certificate. 02886 * 02887 * \note This has no influence on which curves are allowed inside the 02888 * certificate chains, see \c mbedtls_ssl_conf_cert_profile() 02889 * for that. For the end-entity certificate however, the key 02890 * will be accepted only if it is allowed both by this list 02891 * and by the cert profile. 02892 * 02893 * \note This list should be ordered by decreasing preference 02894 * (preferred curve first). 02895 * 02896 * \param conf SSL configuration 02897 * \param curves Ordered list of allowed curves, 02898 * terminated by MBEDTLS_ECP_DP_NONE. 02899 */ 02900 void mbedtls_ssl_conf_curves( mbedtls_ssl_config *conf, 02901 const mbedtls_ecp_group_id *curves ); 02902 #endif /* MBEDTLS_ECP_C */ 02903 02904 #if defined(MBEDTLS_KEY_EXCHANGE__WITH_CERT__ENABLED) 02905 /** 02906 * \brief Set the allowed hashes for signatures during the handshake. 02907 * (Default: all available hashes except MD5.) 02908 * 02909 * \note This only affects which hashes are offered and can be used 02910 * for signatures during the handshake. Hashes for message 02911 * authentication and the TLS PRF are controlled by the 02912 * ciphersuite, see \c mbedtls_ssl_conf_ciphersuites(). Hashes 02913 * used for certificate signature are controlled by the 02914 * verification profile, see \c mbedtls_ssl_conf_cert_profile(). 02915 * 02916 * \note This list should be ordered by decreasing preference 02917 * (preferred hash first). 02918 * 02919 * \param conf SSL configuration 02920 * \param hashes Ordered list of allowed signature hashes, 02921 * terminated by \c MBEDTLS_MD_NONE. 02922 */ 02923 void mbedtls_ssl_conf_sig_hashes( mbedtls_ssl_config *conf, 02924 const int *hashes ); 02925 #endif /* MBEDTLS_KEY_EXCHANGE__WITH_CERT__ENABLED */ 02926 02927 #if defined(MBEDTLS_X509_CRT_PARSE_C) 02928 /** 02929 * \brief Set or reset the hostname to check against the received 02930 * server certificate. It sets the ServerName TLS extension, 02931 * too, if that extension is enabled. (client-side only) 02932 * 02933 * \param ssl SSL context 02934 * \param hostname the server hostname, may be NULL to clear hostname 02935 02936 * \note Maximum hostname length MBEDTLS_SSL_MAX_HOST_NAME_LEN. 02937 * 02938 * \return 0 if successful, MBEDTLS_ERR_SSL_ALLOC_FAILED on 02939 * allocation failure, MBEDTLS_ERR_SSL_BAD_INPUT_DATA on 02940 * too long input hostname. 02941 * 02942 * Hostname set to the one provided on success (cleared 02943 * when NULL). On allocation failure hostname is cleared. 02944 * On too long input failure, old hostname is unchanged. 02945 */ 02946 int mbedtls_ssl_set_hostname( mbedtls_ssl_context *ssl, const char *hostname ); 02947 #endif /* MBEDTLS_X509_CRT_PARSE_C */ 02948 02949 #if defined(MBEDTLS_SSL_SERVER_NAME_INDICATION) 02950 /** 02951 * \brief Set own certificate and key for the current handshake 02952 * 02953 * \note Same as \c mbedtls_ssl_conf_own_cert() but for use within 02954 * the SNI callback. 02955 * 02956 * \param ssl SSL context 02957 * \param own_cert own public certificate chain 02958 * \param pk_key own private key 02959 * 02960 * \return 0 on success or MBEDTLS_ERR_SSL_ALLOC_FAILED 02961 */ 02962 int mbedtls_ssl_set_hs_own_cert( mbedtls_ssl_context *ssl, 02963 mbedtls_x509_crt *own_cert, 02964 mbedtls_pk_context *pk_key ); 02965 02966 /** 02967 * \brief Set the data required to verify peer certificate for the 02968 * current handshake 02969 * 02970 * \note Same as \c mbedtls_ssl_conf_ca_chain() but for use within 02971 * the SNI callback. 02972 * 02973 * \param ssl SSL context 02974 * \param ca_chain trusted CA chain (meaning all fully trusted top-level CAs) 02975 * \param ca_crl trusted CA CRLs 02976 */ 02977 void mbedtls_ssl_set_hs_ca_chain( mbedtls_ssl_context *ssl, 02978 mbedtls_x509_crt *ca_chain, 02979 mbedtls_x509_crl *ca_crl ); 02980 02981 /** 02982 * \brief Set authmode for the current handshake. 02983 * 02984 * \note Same as \c mbedtls_ssl_conf_authmode() but for use within 02985 * the SNI callback. 02986 * 02987 * \param ssl SSL context 02988 * \param authmode MBEDTLS_SSL_VERIFY_NONE, MBEDTLS_SSL_VERIFY_OPTIONAL or 02989 * MBEDTLS_SSL_VERIFY_REQUIRED 02990 */ 02991 void mbedtls_ssl_set_hs_authmode( mbedtls_ssl_context *ssl, 02992 int authmode ); 02993 02994 /** 02995 * \brief Set server side ServerName TLS extension callback 02996 * (optional, server-side only). 02997 * 02998 * If set, the ServerName callback is called whenever the 02999 * server receives a ServerName TLS extension from the client 03000 * during a handshake. The ServerName callback has the 03001 * following parameters: (void *parameter, mbedtls_ssl_context *ssl, 03002 * const unsigned char *hostname, size_t len). If a suitable 03003 * certificate is found, the callback must set the 03004 * certificate(s) and key(s) to use with \c 03005 * mbedtls_ssl_set_hs_own_cert() (can be called repeatedly), 03006 * and may optionally adjust the CA and associated CRL with \c 03007 * mbedtls_ssl_set_hs_ca_chain() as well as the client 03008 * authentication mode with \c mbedtls_ssl_set_hs_authmode(), 03009 * then must return 0. If no matching name is found, the 03010 * callback must either set a default cert, or 03011 * return non-zero to abort the handshake at this point. 03012 * 03013 * \param conf SSL configuration 03014 * \param f_sni verification function 03015 * \param p_sni verification parameter 03016 */ 03017 void mbedtls_ssl_conf_sni( mbedtls_ssl_config *conf, 03018 int (*f_sni)(void *, mbedtls_ssl_context *, const unsigned char *, 03019 size_t), 03020 void *p_sni ); 03021 #endif /* MBEDTLS_SSL_SERVER_NAME_INDICATION */ 03022 03023 #if defined(MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED) 03024 /** 03025 * \brief Set the EC J-PAKE password for current handshake. 03026 * 03027 * \note An internal copy is made, and destroyed as soon as the 03028 * handshake is completed, or when the SSL context is reset or 03029 * freed. 03030 * 03031 * \note The SSL context needs to be already set up. The right place 03032 * to call this function is between \c mbedtls_ssl_setup() or 03033 * \c mbedtls_ssl_reset() and \c mbedtls_ssl_handshake(). 03034 * 03035 * \param ssl SSL context 03036 * \param pw EC J-PAKE password (pre-shared secret) 03037 * \param pw_len length of pw in bytes 03038 * 03039 * \return 0 on success, or a negative error code. 03040 */ 03041 int mbedtls_ssl_set_hs_ecjpake_password( mbedtls_ssl_context *ssl, 03042 const unsigned char *pw, 03043 size_t pw_len ); 03044 #endif /*MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED */ 03045 03046 #if defined(MBEDTLS_SSL_ALPN) 03047 /** 03048 * \brief Set the supported Application Layer Protocols. 03049 * 03050 * \param conf SSL configuration 03051 * \param protos Pointer to a NULL-terminated list of supported protocols, 03052 * in decreasing preference order. The pointer to the list is 03053 * recorded by the library for later reference as required, so 03054 * the lifetime of the table must be atleast as long as the 03055 * lifetime of the SSL configuration structure. 03056 * 03057 * \return 0 on success, or MBEDTLS_ERR_SSL_BAD_INPUT_DATA. 03058 */ 03059 int mbedtls_ssl_conf_alpn_protocols( mbedtls_ssl_config *conf, const char **protos ); 03060 03061 /** 03062 * \brief Get the name of the negotiated Application Layer Protocol. 03063 * This function should be called after the handshake is 03064 * completed. 03065 * 03066 * \param ssl SSL context 03067 * 03068 * \return Protcol name, or NULL if no protocol was negotiated. 03069 */ 03070 const char *mbedtls_ssl_get_alpn_protocol( const mbedtls_ssl_context *ssl ); 03071 #endif /* MBEDTLS_SSL_ALPN */ 03072 03073 /** 03074 * \brief Set the maximum supported version sent from the client side 03075 * and/or accepted at the server side 03076 * (Default: MBEDTLS_SSL_MAX_MAJOR_VERSION, MBEDTLS_SSL_MAX_MINOR_VERSION) 03077 * 03078 * \note This ignores ciphersuites from higher versions. 03079 * 03080 * \note With DTLS, use MBEDTLS_SSL_MINOR_VERSION_2 for DTLS 1.0 and 03081 * MBEDTLS_SSL_MINOR_VERSION_3 for DTLS 1.2 03082 * 03083 * \param conf SSL configuration 03084 * \param major Major version number (only MBEDTLS_SSL_MAJOR_VERSION_3 supported) 03085 * \param minor Minor version number (MBEDTLS_SSL_MINOR_VERSION_0, 03086 * MBEDTLS_SSL_MINOR_VERSION_1 and MBEDTLS_SSL_MINOR_VERSION_2, 03087 * MBEDTLS_SSL_MINOR_VERSION_3 supported) 03088 */ 03089 void mbedtls_ssl_conf_max_version( mbedtls_ssl_config *conf, int major, int minor ); 03090 03091 /** 03092 * \brief Set the minimum accepted SSL/TLS protocol version 03093 * (Default: TLS 1.0) 03094 * 03095 * \note Input outside of the SSL_MAX_XXXXX_VERSION and 03096 * SSL_MIN_XXXXX_VERSION range is ignored. 03097 * 03098 * \note MBEDTLS_SSL_MINOR_VERSION_0 (SSL v3) should be avoided. 03099 * 03100 * \note With DTLS, use MBEDTLS_SSL_MINOR_VERSION_2 for DTLS 1.0 and 03101 * MBEDTLS_SSL_MINOR_VERSION_3 for DTLS 1.2 03102 * 03103 * \param conf SSL configuration 03104 * \param major Major version number (only MBEDTLS_SSL_MAJOR_VERSION_3 supported) 03105 * \param minor Minor version number (MBEDTLS_SSL_MINOR_VERSION_0, 03106 * MBEDTLS_SSL_MINOR_VERSION_1 and MBEDTLS_SSL_MINOR_VERSION_2, 03107 * MBEDTLS_SSL_MINOR_VERSION_3 supported) 03108 */ 03109 void mbedtls_ssl_conf_min_version( mbedtls_ssl_config *conf, int major, int minor ); 03110 03111 #if defined(MBEDTLS_SSL_FALLBACK_SCSV) && defined(MBEDTLS_SSL_CLI_C) 03112 /** 03113 * \brief Set the fallback flag (client-side only). 03114 * (Default: MBEDTLS_SSL_IS_NOT_FALLBACK). 03115 * 03116 * \note Set to MBEDTLS_SSL_IS_FALLBACK when preparing a fallback 03117 * connection, that is a connection with max_version set to a 03118 * lower value than the value you're willing to use. Such 03119 * fallback connections are not recommended but are sometimes 03120 * necessary to interoperate with buggy (version-intolerant) 03121 * servers. 03122 * 03123 * \warning You should NOT set this to MBEDTLS_SSL_IS_FALLBACK for 03124 * non-fallback connections! This would appear to work for a 03125 * while, then cause failures when the server is upgraded to 03126 * support a newer TLS version. 03127 * 03128 * \param conf SSL configuration 03129 * \param fallback MBEDTLS_SSL_IS_NOT_FALLBACK or MBEDTLS_SSL_IS_FALLBACK 03130 */ 03131 void mbedtls_ssl_conf_fallback( mbedtls_ssl_config *conf, char fallback ); 03132 #endif /* MBEDTLS_SSL_FALLBACK_SCSV && MBEDTLS_SSL_CLI_C */ 03133 03134 #if defined(MBEDTLS_SSL_ENCRYPT_THEN_MAC) 03135 /** 03136 * \brief Enable or disable Encrypt-then-MAC 03137 * (Default: MBEDTLS_SSL_ETM_ENABLED) 03138 * 03139 * \note This should always be enabled, it is a security 03140 * improvement, and should not cause any interoperability 03141 * issue (used only if the peer supports it too). 03142 * 03143 * \param conf SSL configuration 03144 * \param etm MBEDTLS_SSL_ETM_ENABLED or MBEDTLS_SSL_ETM_DISABLED 03145 */ 03146 void mbedtls_ssl_conf_encrypt_then_mac( mbedtls_ssl_config *conf, char etm ); 03147 #endif /* MBEDTLS_SSL_ENCRYPT_THEN_MAC */ 03148 03149 #if defined(MBEDTLS_SSL_EXTENDED_MASTER_SECRET) 03150 /** 03151 * \brief Enable or disable Extended Master Secret negotiation. 03152 * (Default: MBEDTLS_SSL_EXTENDED_MS_ENABLED) 03153 * 03154 * \note This should always be enabled, it is a security fix to the 03155 * protocol, and should not cause any interoperability issue 03156 * (used only if the peer supports it too). 03157 * 03158 * \param conf SSL configuration 03159 * \param ems MBEDTLS_SSL_EXTENDED_MS_ENABLED or MBEDTLS_SSL_EXTENDED_MS_DISABLED 03160 */ 03161 void mbedtls_ssl_conf_extended_master_secret( mbedtls_ssl_config *conf, char ems ); 03162 #endif /* MBEDTLS_SSL_EXTENDED_MASTER_SECRET */ 03163 03164 #if defined(MBEDTLS_ARC4_C) 03165 /** 03166 * \brief Disable or enable support for RC4 03167 * (Default: MBEDTLS_SSL_ARC4_DISABLED) 03168 * 03169 * \warning Use of RC4 in DTLS/TLS has been prohibited by RFC 7465 03170 * for security reasons. Use at your own risk. 03171 * 03172 * \note This function is deprecated and will likely be removed in 03173 * a future version of the library. 03174 * RC4 is disabled by default at compile time and needs to be 03175 * actively enabled for use with legacy systems. 03176 * 03177 * \param conf SSL configuration 03178 * \param arc4 MBEDTLS_SSL_ARC4_ENABLED or MBEDTLS_SSL_ARC4_DISABLED 03179 */ 03180 void mbedtls_ssl_conf_arc4_support( mbedtls_ssl_config *conf, char arc4 ); 03181 #endif /* MBEDTLS_ARC4_C */ 03182 03183 #if defined(MBEDTLS_SSL_SRV_C) 03184 /** 03185 * \brief Whether to send a list of acceptable CAs in 03186 * CertificateRequest messages. 03187 * (Default: do send) 03188 * 03189 * \param conf SSL configuration 03190 * \param cert_req_ca_list MBEDTLS_SSL_CERT_REQ_CA_LIST_ENABLED or 03191 * MBEDTLS_SSL_CERT_REQ_CA_LIST_DISABLED 03192 */ 03193 void mbedtls_ssl_conf_cert_req_ca_list( mbedtls_ssl_config *conf, 03194 char cert_req_ca_list ); 03195 #endif /* MBEDTLS_SSL_SRV_C */ 03196 03197 #if defined(MBEDTLS_SSL_MAX_FRAGMENT_LENGTH) 03198 /** 03199 * \brief Set the maximum fragment length to emit and/or negotiate. 03200 * (Typical: the smaller of #MBEDTLS_SSL_IN_CONTENT_LEN and 03201 * #MBEDTLS_SSL_OUT_CONTENT_LEN, usually `2^14` bytes) 03202 * (Server: set maximum fragment length to emit, 03203 * usually negotiated by the client during handshake) 03204 * (Client: set maximum fragment length to emit *and* 03205 * negotiate with the server during handshake) 03206 * (Default: #MBEDTLS_SSL_MAX_FRAG_LEN_NONE) 03207 * 03208 * \note On the client side, the maximum fragment length extension 03209 * *will not* be used, unless the maximum fragment length has 03210 * been set via this function to a value different than 03211 * #MBEDTLS_SSL_MAX_FRAG_LEN_NONE. 03212 * 03213 * \note With TLS, this currently only affects ApplicationData (sent 03214 * with \c mbedtls_ssl_read()), not handshake messages. 03215 * With DTLS, this affects both ApplicationData and handshake. 03216 * 03217 * \note This sets the maximum length for a record's payload, 03218 * excluding record overhead that will be added to it, see 03219 * \c mbedtls_ssl_get_record_expansion(). 03220 * 03221 * \note For DTLS, it is also possible to set a limit for the total 03222 * size of daragrams passed to the transport layer, including 03223 * record overhead, see \c mbedtls_ssl_set_mtu(). 03224 * 03225 * \param conf SSL configuration 03226 * \param mfl_code Code for maximum fragment length (allowed values: 03227 * MBEDTLS_SSL_MAX_FRAG_LEN_512, MBEDTLS_SSL_MAX_FRAG_LEN_1024, 03228 * MBEDTLS_SSL_MAX_FRAG_LEN_2048, MBEDTLS_SSL_MAX_FRAG_LEN_4096) 03229 * 03230 * \return 0 if successful or MBEDTLS_ERR_SSL_BAD_INPUT_DATA 03231 */ 03232 int mbedtls_ssl_conf_max_frag_len( mbedtls_ssl_config *conf, unsigned char mfl_code ); 03233 #endif /* MBEDTLS_SSL_MAX_FRAGMENT_LENGTH */ 03234 03235 #if defined(MBEDTLS_SSL_TRUNCATED_HMAC) 03236 /** 03237 * \brief Activate negotiation of truncated HMAC 03238 * (Default: MBEDTLS_SSL_TRUNC_HMAC_DISABLED) 03239 * 03240 * \param conf SSL configuration 03241 * \param truncate Enable or disable (MBEDTLS_SSL_TRUNC_HMAC_ENABLED or 03242 * MBEDTLS_SSL_TRUNC_HMAC_DISABLED) 03243 */ 03244 void mbedtls_ssl_conf_truncated_hmac( mbedtls_ssl_config *conf, int truncate ); 03245 #endif /* MBEDTLS_SSL_TRUNCATED_HMAC */ 03246 03247 #if defined(MBEDTLS_SSL_CBC_RECORD_SPLITTING) 03248 /** 03249 * \brief Enable / Disable 1/n-1 record splitting 03250 * (Default: MBEDTLS_SSL_CBC_RECORD_SPLITTING_ENABLED) 03251 * 03252 * \note Only affects SSLv3 and TLS 1.0, not higher versions. 03253 * Does not affect non-CBC ciphersuites in any version. 03254 * 03255 * \param conf SSL configuration 03256 * \param split MBEDTLS_SSL_CBC_RECORD_SPLITTING_ENABLED or 03257 * MBEDTLS_SSL_CBC_RECORD_SPLITTING_DISABLED 03258 */ 03259 void mbedtls_ssl_conf_cbc_record_splitting( mbedtls_ssl_config *conf, char split ); 03260 #endif /* MBEDTLS_SSL_CBC_RECORD_SPLITTING */ 03261 03262 #if defined(MBEDTLS_SSL_SESSION_TICKETS) && defined(MBEDTLS_SSL_CLI_C) 03263 /** 03264 * \brief Enable / Disable session tickets (client only). 03265 * (Default: MBEDTLS_SSL_SESSION_TICKETS_ENABLED.) 03266 * 03267 * \note On server, use \c mbedtls_ssl_conf_session_tickets_cb(). 03268 * 03269 * \param conf SSL configuration 03270 * \param use_tickets Enable or disable (MBEDTLS_SSL_SESSION_TICKETS_ENABLED or 03271 * MBEDTLS_SSL_SESSION_TICKETS_DISABLED) 03272 */ 03273 void mbedtls_ssl_conf_session_tickets( mbedtls_ssl_config *conf, int use_tickets ); 03274 #endif /* MBEDTLS_SSL_SESSION_TICKETS && MBEDTLS_SSL_CLI_C */ 03275 03276 #if defined(MBEDTLS_SSL_RENEGOTIATION) 03277 /** 03278 * \brief Enable / Disable renegotiation support for connection when 03279 * initiated by peer 03280 * (Default: MBEDTLS_SSL_RENEGOTIATION_DISABLED) 03281 * 03282 * \warning It is recommended to always disable renegotation unless you 03283 * know you need it and you know what you're doing. In the 03284 * past, there have been several issues associated with 03285 * renegotiation or a poor understanding of its properties. 03286 * 03287 * \note Server-side, enabling renegotiation also makes the server 03288 * susceptible to a resource DoS by a malicious client. 03289 * 03290 * \param conf SSL configuration 03291 * \param renegotiation Enable or disable (MBEDTLS_SSL_RENEGOTIATION_ENABLED or 03292 * MBEDTLS_SSL_RENEGOTIATION_DISABLED) 03293 */ 03294 void mbedtls_ssl_conf_renegotiation( mbedtls_ssl_config *conf, int renegotiation ); 03295 #endif /* MBEDTLS_SSL_RENEGOTIATION */ 03296 03297 /** 03298 * \brief Prevent or allow legacy renegotiation. 03299 * (Default: MBEDTLS_SSL_LEGACY_NO_RENEGOTIATION) 03300 * 03301 * MBEDTLS_SSL_LEGACY_NO_RENEGOTIATION allows connections to 03302 * be established even if the peer does not support 03303 * secure renegotiation, but does not allow renegotiation 03304 * to take place if not secure. 03305 * (Interoperable and secure option) 03306 * 03307 * MBEDTLS_SSL_LEGACY_ALLOW_RENEGOTIATION allows renegotiations 03308 * with non-upgraded peers. Allowing legacy renegotiation 03309 * makes the connection vulnerable to specific man in the 03310 * middle attacks. (See RFC 5746) 03311 * (Most interoperable and least secure option) 03312 * 03313 * MBEDTLS_SSL_LEGACY_BREAK_HANDSHAKE breaks off connections 03314 * if peer does not support secure renegotiation. Results 03315 * in interoperability issues with non-upgraded peers 03316 * that do not support renegotiation altogether. 03317 * (Most secure option, interoperability issues) 03318 * 03319 * \param conf SSL configuration 03320 * \param allow_legacy Prevent or allow (SSL_NO_LEGACY_RENEGOTIATION, 03321 * SSL_ALLOW_LEGACY_RENEGOTIATION or 03322 * MBEDTLS_SSL_LEGACY_BREAK_HANDSHAKE) 03323 */ 03324 void mbedtls_ssl_conf_legacy_renegotiation( mbedtls_ssl_config *conf, int allow_legacy ); 03325 03326 #if defined(MBEDTLS_SSL_RENEGOTIATION) 03327 /** 03328 * \brief Enforce renegotiation requests. 03329 * (Default: enforced, max_records = 16) 03330 * 03331 * When we request a renegotiation, the peer can comply or 03332 * ignore the request. This function allows us to decide 03333 * whether to enforce our renegotiation requests by closing 03334 * the connection if the peer doesn't comply. 03335 * 03336 * However, records could already be in transit from the peer 03337 * when the request is emitted. In order to increase 03338 * reliability, we can accept a number of records before the 03339 * expected handshake records. 03340 * 03341 * The optimal value is highly dependent on the specific usage 03342 * scenario. 03343 * 03344 * \note With DTLS and server-initiated renegotiation, the 03345 * HelloRequest is retransmited every time mbedtls_ssl_read() times 03346 * out or receives Application Data, until: 03347 * - max_records records have beens seen, if it is >= 0, or 03348 * - the number of retransmits that would happen during an 03349 * actual handshake has been reached. 03350 * Please remember the request might be lost a few times 03351 * if you consider setting max_records to a really low value. 03352 * 03353 * \warning On client, the grace period can only happen during 03354 * mbedtls_ssl_read(), as opposed to mbedtls_ssl_write() and mbedtls_ssl_renegotiate() 03355 * which always behave as if max_record was 0. The reason is, 03356 * if we receive application data from the server, we need a 03357 * place to write it, which only happens during mbedtls_ssl_read(). 03358 * 03359 * \param conf SSL configuration 03360 * \param max_records Use MBEDTLS_SSL_RENEGOTIATION_NOT_ENFORCED if you don't want to 03361 * enforce renegotiation, or a non-negative value to enforce 03362 * it but allow for a grace period of max_records records. 03363 */ 03364 void mbedtls_ssl_conf_renegotiation_enforced( mbedtls_ssl_config *conf, int max_records ); 03365 03366 /** 03367 * \brief Set record counter threshold for periodic renegotiation. 03368 * (Default: 2^48 - 1) 03369 * 03370 * Renegotiation is automatically triggered when a record 03371 * counter (outgoing or incoming) crosses the defined 03372 * threshold. The default value is meant to prevent the 03373 * connection from being closed when the counter is about to 03374 * reached its maximal value (it is not allowed to wrap). 03375 * 03376 * Lower values can be used to enforce policies such as "keys 03377 * must be refreshed every N packets with cipher X". 03378 * 03379 * The renegotiation period can be disabled by setting 03380 * conf->disable_renegotiation to 03381 * MBEDTLS_SSL_RENEGOTIATION_DISABLED. 03382 * 03383 * \note When the configured transport is 03384 * MBEDTLS_SSL_TRANSPORT_DATAGRAM the maximum renegotiation 03385 * period is 2^48 - 1, and for MBEDTLS_SSL_TRANSPORT_STREAM, 03386 * the maximum renegotiation period is 2^64 - 1. 03387 * 03388 * \param conf SSL configuration 03389 * \param period The threshold value: a big-endian 64-bit number. 03390 */ 03391 void mbedtls_ssl_conf_renegotiation_period( mbedtls_ssl_config *conf, 03392 const unsigned char period[8] ); 03393 #endif /* MBEDTLS_SSL_RENEGOTIATION */ 03394 03395 /** 03396 * \brief Check if there is data already read from the 03397 * underlying transport but not yet processed. 03398 * 03399 * \param ssl SSL context 03400 * 03401 * \return 0 if nothing's pending, 1 otherwise. 03402 * 03403 * \note This is different in purpose and behaviour from 03404 * \c mbedtls_ssl_get_bytes_avail in that it considers 03405 * any kind of unprocessed data, not only unread 03406 * application data. If \c mbedtls_ssl_get_bytes 03407 * returns a non-zero value, this function will 03408 * also signal pending data, but the converse does 03409 * not hold. For example, in DTLS there might be 03410 * further records waiting to be processed from 03411 * the current underlying transport's datagram. 03412 * 03413 * \note If this function returns 1 (data pending), this 03414 * does not imply that a subsequent call to 03415 * \c mbedtls_ssl_read will provide any data; 03416 * e.g., the unprocessed data might turn out 03417 * to be an alert or a handshake message. 03418 * 03419 * \note This function is useful in the following situation: 03420 * If the SSL/TLS module successfully returns from an 03421 * operation - e.g. a handshake or an application record 03422 * read - and you're awaiting incoming data next, you 03423 * must not immediately idle on the underlying transport 03424 * to have data ready, but you need to check the value 03425 * of this function first. The reason is that the desired 03426 * data might already be read but not yet processed. 03427 * If, in contrast, a previous call to the SSL/TLS module 03428 * returned MBEDTLS_ERR_SSL_WANT_READ, it is not necessary 03429 * to call this function, as the latter error code entails 03430 * that all internal data has been processed. 03431 * 03432 */ 03433 int mbedtls_ssl_check_pending( const mbedtls_ssl_context *ssl ); 03434 03435 /** 03436 * \brief Return the number of application data bytes 03437 * remaining to be read from the current record. 03438 * 03439 * \param ssl SSL context 03440 * 03441 * \return How many bytes are available in the application 03442 * data record read buffer. 03443 * 03444 * \note When working over a datagram transport, this is 03445 * useful to detect the current datagram's boundary 03446 * in case \c mbedtls_ssl_read has written the maximal 03447 * amount of data fitting into the input buffer. 03448 * 03449 */ 03450 size_t mbedtls_ssl_get_bytes_avail( const mbedtls_ssl_context *ssl ); 03451 03452 /** 03453 * \brief Return the result of the certificate verification 03454 * 03455 * \param ssl The SSL context to use. 03456 * 03457 * \return \c 0 if the certificate verification was successful. 03458 * \return \c -1u if the result is not available. This may happen 03459 * e.g. if the handshake aborts early, or a verification 03460 * callback returned a fatal error. 03461 * \return A bitwise combination of \c MBEDTLS_X509_BADCERT_XXX 03462 * and \c MBEDTLS_X509_BADCRL_XXX failure flags; see x509.h. 03463 */ 03464 uint32_t mbedtls_ssl_get_verify_result( const mbedtls_ssl_context *ssl ); 03465 03466 /** 03467 * \brief Return the name of the current ciphersuite 03468 * 03469 * \param ssl SSL context 03470 * 03471 * \return a string containing the ciphersuite name 03472 */ 03473 const char *mbedtls_ssl_get_ciphersuite( const mbedtls_ssl_context *ssl ); 03474 03475 /** 03476 * \brief Return the current SSL version (SSLv3/TLSv1/etc) 03477 * 03478 * \param ssl SSL context 03479 * 03480 * \return a string containing the SSL version 03481 */ 03482 const char *mbedtls_ssl_get_version( const mbedtls_ssl_context *ssl ); 03483 03484 /** 03485 * \brief Return the (maximum) number of bytes added by the record 03486 * layer: header + encryption/MAC overhead (inc. padding) 03487 * 03488 * \note This function is not available (always returns an error) 03489 * when record compression is enabled. 03490 * 03491 * \param ssl SSL context 03492 * 03493 * \return Current maximum record expansion in bytes, or 03494 * MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE if compression is 03495 * enabled, which makes expansion much less predictable 03496 */ 03497 int mbedtls_ssl_get_record_expansion( const mbedtls_ssl_context *ssl ); 03498 03499 #if defined(MBEDTLS_SSL_MAX_FRAGMENT_LENGTH) 03500 /** 03501 * \brief Return the maximum fragment length (payload, in bytes). 03502 * This is the value negotiated with peer if any, 03503 * or the locally configured value. 03504 * 03505 * \sa mbedtls_ssl_conf_max_frag_len() 03506 * \sa mbedtls_ssl_get_max_record_payload() 03507 * 03508 * \param ssl SSL context 03509 * 03510 * \return Current maximum fragment length. 03511 */ 03512 size_t mbedtls_ssl_get_max_frag_len( const mbedtls_ssl_context *ssl ); 03513 #endif /* MBEDTLS_SSL_MAX_FRAGMENT_LENGTH */ 03514 03515 /** 03516 * \brief Return the current maximum outgoing record payload in bytes. 03517 * This takes into account the config.h setting \c 03518 * MBEDTLS_SSL_OUT_CONTENT_LEN, the configured and negotiated 03519 * max fragment length extension if used, and for DTLS the 03520 * path MTU as configured and current record expansion. 03521 * 03522 * \note With DTLS, \c mbedtls_ssl_write() will return an error if 03523 * called with a larger length value. 03524 * With TLS, \c mbedtls_ssl_write() will fragment the input if 03525 * necessary and return the number of bytes written; it is up 03526 * to the caller to call \c mbedtls_ssl_write() again in 03527 * order to send the remaining bytes if any. 03528 * 03529 * \note This function is not available (always returns an error) 03530 * when record compression is enabled. 03531 * 03532 * \sa mbedtls_ssl_set_mtu() 03533 * \sa mbedtls_ssl_get_max_frag_len() 03534 * \sa mbedtls_ssl_get_record_expansion() 03535 * 03536 * \param ssl SSL context 03537 * 03538 * \return Current maximum payload for an outgoing record, 03539 * or a negative error code. 03540 */ 03541 int mbedtls_ssl_get_max_out_record_payload( const mbedtls_ssl_context *ssl ); 03542 03543 #if defined(MBEDTLS_X509_CRT_PARSE_C) 03544 /** 03545 * \brief Return the peer certificate from the current connection. 03546 * 03547 * \param ssl The SSL context to use. This must be initialized and setup. 03548 * 03549 * \return The current peer certificate, if available. 03550 * The returned certificate is owned by the SSL context and 03551 * is valid only until the next call to the SSL API. 03552 * \return \c NULL if no peer certificate is available. This might 03553 * be because the chosen ciphersuite doesn't use CRTs 03554 * (PSK-based ciphersuites, for example), or because 03555 * #MBEDTLS_SSL_KEEP_PEER_CERTIFICATE has been disabled, 03556 * allowing the stack to free the peer's CRT to save memory. 03557 * 03558 * \note For one-time inspection of the peer's certificate during 03559 * the handshake, consider registering an X.509 CRT verification 03560 * callback through mbedtls_ssl_conf_verify() instead of calling 03561 * this function. Using mbedtls_ssl_conf_verify() also comes at 03562 * the benefit of allowing you to influence the verification 03563 * process, for example by masking expected and tolerated 03564 * verification failures. 03565 * 03566 * \warning You must not use the pointer returned by this function 03567 * after any further call to the SSL API, including 03568 * mbedtls_ssl_read() and mbedtls_ssl_write(); this is 03569 * because the pointer might change during renegotiation, 03570 * which happens transparently to the user. 03571 * If you want to use the certificate across API calls, 03572 * you must make a copy. 03573 */ 03574 const mbedtls_x509_crt *mbedtls_ssl_get_peer_cert( const mbedtls_ssl_context *ssl ); 03575 #endif /* MBEDTLS_X509_CRT_PARSE_C */ 03576 03577 #if defined(MBEDTLS_SSL_CLI_C) 03578 /** 03579 * \brief Save session in order to resume it later (client-side only) 03580 * Session data is copied to presented session structure. 03581 * 03582 * 03583 * \param ssl SSL context 03584 * \param session session context 03585 * 03586 * \return 0 if successful, 03587 * MBEDTLS_ERR_SSL_ALLOC_FAILED if memory allocation failed, 03588 * MBEDTLS_ERR_SSL_BAD_INPUT_DATA if used server-side or 03589 * arguments are otherwise invalid. 03590 * 03591 * \note Only the server certificate is copied, and not the full chain, 03592 * so you should not attempt to validate the certificate again 03593 * by calling \c mbedtls_x509_crt_verify() on it. 03594 * Instead, you should use the results from the verification 03595 * in the original handshake by calling \c mbedtls_ssl_get_verify_result() 03596 * after loading the session again into a new SSL context 03597 * using \c mbedtls_ssl_set_session(). 03598 * 03599 * \note Once the session object is not needed anymore, you should 03600 * free it by calling \c mbedtls_ssl_session_free(). 03601 * 03602 * \sa mbedtls_ssl_set_session() 03603 */ 03604 int mbedtls_ssl_get_session( const mbedtls_ssl_context *ssl, mbedtls_ssl_session *session ); 03605 #endif /* MBEDTLS_SSL_CLI_C */ 03606 03607 /** 03608 * \brief Perform the SSL handshake 03609 * 03610 * \param ssl SSL context 03611 * 03612 * \return \c 0 if successful. 03613 * \return #MBEDTLS_ERR_SSL_WANT_READ or #MBEDTLS_ERR_SSL_WANT_WRITE 03614 * if the handshake is incomplete and waiting for data to 03615 * be available for reading from or writing to the underlying 03616 * transport - in this case you must call this function again 03617 * when the underlying transport is ready for the operation. 03618 * \return #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS if an asynchronous 03619 * operation is in progress (see 03620 * mbedtls_ssl_conf_async_private_cb()) - in this case you 03621 * must call this function again when the operation is ready. 03622 * \return #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS if a cryptographic 03623 * operation is in progress (see mbedtls_ecp_set_max_ops()) - 03624 * in this case you must call this function again to complete 03625 * the handshake when you're done attending other tasks. 03626 * \return #MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED if DTLS is in use 03627 * and the client did not demonstrate reachability yet - in 03628 * this case you must stop using the context (see below). 03629 * \return Another SSL error code - in this case you must stop using 03630 * the context (see below). 03631 * 03632 * \warning If this function returns something other than 03633 * \c 0, 03634 * #MBEDTLS_ERR_SSL_WANT_READ, 03635 * #MBEDTLS_ERR_SSL_WANT_WRITE, 03636 * #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS or 03637 * #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS, 03638 * you must stop using the SSL context for reading or writing, 03639 * and either free it or call \c mbedtls_ssl_session_reset() 03640 * on it before re-using it for a new connection; the current 03641 * connection must be closed. 03642 * 03643 * \note If DTLS is in use, then you may choose to handle 03644 * #MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED specially for logging 03645 * purposes, as it is an expected return value rather than an 03646 * actual error, but you still need to reset/free the context. 03647 * 03648 * \note Remarks regarding event-driven DTLS: 03649 * If the function returns #MBEDTLS_ERR_SSL_WANT_READ, no datagram 03650 * from the underlying transport layer is currently being processed, 03651 * and it is safe to idle until the timer or the underlying transport 03652 * signal a new event. This is not true for a successful handshake, 03653 * in which case the datagram of the underlying transport that is 03654 * currently being processed might or might not contain further 03655 * DTLS records. 03656 */ 03657 int mbedtls_ssl_handshake( mbedtls_ssl_context *ssl ); 03658 03659 /** 03660 * \brief Perform a single step of the SSL handshake 03661 * 03662 * \note The state of the context (ssl->state) will be at 03663 * the next state after this function returns \c 0. Do not 03664 * call this function if state is MBEDTLS_SSL_HANDSHAKE_OVER. 03665 * 03666 * \param ssl SSL context 03667 * 03668 * \return See mbedtls_ssl_handshake(). 03669 * 03670 * \warning If this function returns something other than \c 0, 03671 * #MBEDTLS_ERR_SSL_WANT_READ, #MBEDTLS_ERR_SSL_WANT_WRITE, 03672 * #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS or 03673 * #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS, you must stop using 03674 * the SSL context for reading or writing, and either free it 03675 * or call \c mbedtls_ssl_session_reset() on it before 03676 * re-using it for a new connection; the current connection 03677 * must be closed. 03678 */ 03679 int mbedtls_ssl_handshake_step( mbedtls_ssl_context *ssl ); 03680 03681 #if defined(MBEDTLS_SSL_RENEGOTIATION) 03682 /** 03683 * \brief Initiate an SSL renegotiation on the running connection. 03684 * Client: perform the renegotiation right now. 03685 * Server: request renegotiation, which will be performed 03686 * during the next call to mbedtls_ssl_read() if honored by 03687 * client. 03688 * 03689 * \param ssl SSL context 03690 * 03691 * \return 0 if successful, or any mbedtls_ssl_handshake() return 03692 * value except #MBEDTLS_ERR_SSL_CLIENT_RECONNECT that can't 03693 * happen during a renegotiation. 03694 * 03695 * \warning If this function returns something other than \c 0, 03696 * #MBEDTLS_ERR_SSL_WANT_READ, #MBEDTLS_ERR_SSL_WANT_WRITE, 03697 * #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS or 03698 * #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS, you must stop using 03699 * the SSL context for reading or writing, and either free it 03700 * or call \c mbedtls_ssl_session_reset() on it before 03701 * re-using it for a new connection; the current connection 03702 * must be closed. 03703 * 03704 */ 03705 int mbedtls_ssl_renegotiate( mbedtls_ssl_context *ssl ); 03706 #endif /* MBEDTLS_SSL_RENEGOTIATION */ 03707 03708 /** 03709 * \brief Read at most 'len' application data bytes 03710 * 03711 * \param ssl SSL context 03712 * \param buf buffer that will hold the data 03713 * \param len maximum number of bytes to read 03714 * 03715 * \return The (positive) number of bytes read if successful. 03716 * \return \c 0 if the read end of the underlying transport was closed 03717 * - in this case you must stop using the context (see below). 03718 * \return #MBEDTLS_ERR_SSL_WANT_READ or #MBEDTLS_ERR_SSL_WANT_WRITE 03719 * if the handshake is incomplete and waiting for data to 03720 * be available for reading from or writing to the underlying 03721 * transport - in this case you must call this function again 03722 * when the underlying transport is ready for the operation. 03723 * \return #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS if an asynchronous 03724 * operation is in progress (see 03725 * mbedtls_ssl_conf_async_private_cb()) - in this case you 03726 * must call this function again when the operation is ready. 03727 * \return #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS if a cryptographic 03728 * operation is in progress (see mbedtls_ecp_set_max_ops()) - 03729 * in this case you must call this function again to complete 03730 * the handshake when you're done attending other tasks. 03731 * \return #MBEDTLS_ERR_SSL_CLIENT_RECONNECT if we're at the server 03732 * side of a DTLS connection and the client is initiating a 03733 * new connection using the same source port. See below. 03734 * \return Another SSL error code - in this case you must stop using 03735 * the context (see below). 03736 * 03737 * \warning If this function returns something other than 03738 * a positive value, 03739 * #MBEDTLS_ERR_SSL_WANT_READ, 03740 * #MBEDTLS_ERR_SSL_WANT_WRITE, 03741 * #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS, 03742 * #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS or 03743 * #MBEDTLS_ERR_SSL_CLIENT_RECONNECT, 03744 * you must stop using the SSL context for reading or writing, 03745 * and either free it or call \c mbedtls_ssl_session_reset() 03746 * on it before re-using it for a new connection; the current 03747 * connection must be closed. 03748 * 03749 * \note When this function returns #MBEDTLS_ERR_SSL_CLIENT_RECONNECT 03750 * (which can only happen server-side), it means that a client 03751 * is initiating a new connection using the same source port. 03752 * You can either treat that as a connection close and wait 03753 * for the client to resend a ClientHello, or directly 03754 * continue with \c mbedtls_ssl_handshake() with the same 03755 * context (as it has been reset internally). Either way, you 03756 * must make sure this is seen by the application as a new 03757 * connection: application state, if any, should be reset, and 03758 * most importantly the identity of the client must be checked 03759 * again. WARNING: not validating the identity of the client 03760 * again, or not transmitting the new identity to the 03761 * application layer, would allow authentication bypass! 03762 * 03763 * \note Remarks regarding event-driven DTLS: 03764 * - If the function returns #MBEDTLS_ERR_SSL_WANT_READ, no datagram 03765 * from the underlying transport layer is currently being processed, 03766 * and it is safe to idle until the timer or the underlying transport 03767 * signal a new event. 03768 * - This function may return MBEDTLS_ERR_SSL_WANT_READ even if data was 03769 * initially available on the underlying transport, as this data may have 03770 * been only e.g. duplicated messages or a renegotiation request. 03771 * Therefore, you must be prepared to receive MBEDTLS_ERR_SSL_WANT_READ even 03772 * when reacting to an incoming-data event from the underlying transport. 03773 * - On success, the datagram of the underlying transport that is currently 03774 * being processed may contain further DTLS records. You should call 03775 * \c mbedtls_ssl_check_pending to check for remaining records. 03776 * 03777 */ 03778 int mbedtls_ssl_read( mbedtls_ssl_context *ssl, unsigned char *buf, size_t len ); 03779 03780 /** 03781 * \brief Try to write exactly 'len' application data bytes 03782 * 03783 * \warning This function will do partial writes in some cases. If the 03784 * return value is non-negative but less than length, the 03785 * function must be called again with updated arguments: 03786 * buf + ret, len - ret (if ret is the return value) until 03787 * it returns a value equal to the last 'len' argument. 03788 * 03789 * \param ssl SSL context 03790 * \param buf buffer holding the data 03791 * \param len how many bytes must be written 03792 * 03793 * \return The (non-negative) number of bytes actually written if 03794 * successful (may be less than \p len). 03795 * \return #MBEDTLS_ERR_SSL_WANT_READ or #MBEDTLS_ERR_SSL_WANT_WRITE 03796 * if the handshake is incomplete and waiting for data to 03797 * be available for reading from or writing to the underlying 03798 * transport - in this case you must call this function again 03799 * when the underlying transport is ready for the operation. 03800 * \return #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS if an asynchronous 03801 * operation is in progress (see 03802 * mbedtls_ssl_conf_async_private_cb()) - in this case you 03803 * must call this function again when the operation is ready. 03804 * \return #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS if a cryptographic 03805 * operation is in progress (see mbedtls_ecp_set_max_ops()) - 03806 * in this case you must call this function again to complete 03807 * the handshake when you're done attending other tasks. 03808 * \return Another SSL error code - in this case you must stop using 03809 * the context (see below). 03810 * 03811 * \warning If this function returns something other than 03812 * a non-negative value, 03813 * #MBEDTLS_ERR_SSL_WANT_READ, 03814 * #MBEDTLS_ERR_SSL_WANT_WRITE, 03815 * #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS or 03816 * #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS, 03817 * you must stop using the SSL context for reading or writing, 03818 * and either free it or call \c mbedtls_ssl_session_reset() 03819 * on it before re-using it for a new connection; the current 03820 * connection must be closed. 03821 * 03822 * \note When this function returns #MBEDTLS_ERR_SSL_WANT_WRITE/READ, 03823 * it must be called later with the *same* arguments, 03824 * until it returns a value greater that or equal to 0. When 03825 * the function returns #MBEDTLS_ERR_SSL_WANT_WRITE there may be 03826 * some partial data in the output buffer, however this is not 03827 * yet sent. 03828 * 03829 * \note If the requested length is greater than the maximum 03830 * fragment length (either the built-in limit or the one set 03831 * or negotiated with the peer), then: 03832 * - with TLS, less bytes than requested are written. 03833 * - with DTLS, MBEDTLS_ERR_SSL_BAD_INPUT_DATA is returned. 03834 * \c mbedtls_ssl_get_max_frag_len() may be used to query the 03835 * active maximum fragment length. 03836 * 03837 * \note Attempting to write 0 bytes will result in an empty TLS 03838 * application record being sent. 03839 */ 03840 int mbedtls_ssl_write( mbedtls_ssl_context *ssl, const unsigned char *buf, size_t len ); 03841 03842 /** 03843 * \brief Send an alert message 03844 * 03845 * \param ssl SSL context 03846 * \param level The alert level of the message 03847 * (MBEDTLS_SSL_ALERT_LEVEL_WARNING or MBEDTLS_SSL_ALERT_LEVEL_FATAL) 03848 * \param message The alert message (SSL_ALERT_MSG_*) 03849 * 03850 * \return 0 if successful, or a specific SSL error code. 03851 * 03852 * \note If this function returns something other than 0 or 03853 * MBEDTLS_ERR_SSL_WANT_READ/WRITE, you must stop using 03854 * the SSL context for reading or writing, and either free it or 03855 * call \c mbedtls_ssl_session_reset() on it before re-using it 03856 * for a new connection; the current connection must be closed. 03857 */ 03858 int mbedtls_ssl_send_alert_message( mbedtls_ssl_context *ssl, 03859 unsigned char level, 03860 unsigned char message ); 03861 /** 03862 * \brief Notify the peer that the connection is being closed 03863 * 03864 * \param ssl SSL context 03865 * 03866 * \return 0 if successful, or a specific SSL error code. 03867 * 03868 * \note If this function returns something other than 0 or 03869 * MBEDTLS_ERR_SSL_WANT_READ/WRITE, you must stop using 03870 * the SSL context for reading or writing, and either free it or 03871 * call \c mbedtls_ssl_session_reset() on it before re-using it 03872 * for a new connection; the current connection must be closed. 03873 */ 03874 int mbedtls_ssl_close_notify( mbedtls_ssl_context *ssl ); 03875 03876 /** 03877 * \brief Free referenced items in an SSL context and clear memory 03878 * 03879 * \param ssl SSL context 03880 */ 03881 void mbedtls_ssl_free( mbedtls_ssl_context *ssl ); 03882 03883 #if defined(MBEDTLS_SSL_CONTEXT_SERIALIZATION) 03884 /** 03885 * \brief Save an active connection as serialized data in a buffer. 03886 * This allows the freeing or re-using of the SSL context 03887 * while still picking up the connection later in a way that 03888 * it entirely transparent to the peer. 03889 * 03890 * \see mbedtls_ssl_context_load() 03891 * 03892 * \note This feature is currently only available under certain 03893 * conditions, see the documentation of the return value 03894 * #MBEDTLS_ERR_SSL_BAD_INPUT_DATA for details. 03895 * 03896 * \note When this function succeeds, it calls 03897 * mbedtls_ssl_session_reset() on \p ssl which as a result is 03898 * no longer associated with the connection that has been 03899 * serialized. This avoids creating copies of the connection 03900 * state. You're then free to either re-use the context 03901 * structure for a different connection, or call 03902 * mbedtls_ssl_free() on it. See the documentation of 03903 * mbedtls_ssl_session_reset() for more details. 03904 * 03905 * \param ssl The SSL context to save. On success, it is no longer 03906 * associated with the connection that has been serialized. 03907 * \param buf The buffer to write the serialized data to. It must be a 03908 * writeable buffer of at least \p buf_len bytes, or may be \c 03909 * NULL if \p buf_len is \c 0. 03910 * \param buf_len The number of bytes available for writing in \p buf. 03911 * \param olen The size in bytes of the data that has been or would have 03912 * been written. It must point to a valid \c size_t. 03913 * 03914 * \note \p olen is updated to the correct value regardless of 03915 * whether \p buf_len was large enough. This makes it possible 03916 * to determine the necessary size by calling this function 03917 * with \p buf set to \c NULL and \p buf_len to \c 0. However, 03918 * the value of \p olen is only guaranteed to be correct when 03919 * the function returns #MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL or 03920 * \c 0. If the return value is different, then the value of 03921 * \p olen is undefined. 03922 * 03923 * \return \c 0 if successful. 03924 * \return #MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL if \p buf is too small. 03925 * \return #MBEDTLS_ERR_SSL_ALLOC_FAILED if memory allocation failed 03926 * while reseting the context. 03927 * \return #MBEDTLS_ERR_SSL_BAD_INPUT_DATA if a handshake is in 03928 * progress, or there is pending data for reading or sending, 03929 * or the connection does not use DTLS 1.2 with an AEAD 03930 * ciphersuite, or renegotiation is enabled. 03931 */ 03932 int mbedtls_ssl_context_save( mbedtls_ssl_context *ssl, 03933 unsigned char *buf, 03934 size_t buf_len, 03935 size_t *olen ); 03936 03937 /** 03938 * \brief Load serialized connection data to an SSL context. 03939 * 03940 * \see mbedtls_ssl_context_save() 03941 * 03942 * \warning The same serialized data must never be loaded into more 03943 * that one context. In order to ensure that, after 03944 * successfully loading serialized data to an SSL context, you 03945 * should immediately destroy or invalidate all copies of the 03946 * serialized data that was loaded. Loading the same data in 03947 * more than one context would cause severe security failures 03948 * including but not limited to loss of confidentiality. 03949 * 03950 * \note Before calling this function, the SSL context must be 03951 * prepared in one of the two following ways. The first way is 03952 * to take a context freshly initialised with 03953 * mbedtls_ssl_init() and call mbedtls_ssl_setup() on it with 03954 * the same ::mbedtls_ssl_config structure that was used in 03955 * the original connection. The second way is to 03956 * call mbedtls_ssl_session_reset() on a context that was 03957 * previously prepared as above but used in the meantime. 03958 * Either way, you must not use the context to perform a 03959 * handshake between calling mbedtls_ssl_setup() or 03960 * mbedtls_ssl_session_reset() and calling this function. You 03961 * may however call other setter functions in that time frame 03962 * as indicated in the note below. 03963 * 03964 * \note Before or after calling this function successfully, you 03965 * also need to configure some connection-specific callbacks 03966 * and settings before you can use the connection again 03967 * (unless they were already set before calling 03968 * mbedtls_ssl_session_reset() and the values are suitable for 03969 * the present connection). Specifically, you want to call 03970 * at least mbedtls_ssl_set_bio() and 03971 * mbedtls_ssl_set_timer_cb(). All other SSL setter functions 03972 * are not necessary to call, either because they're only used 03973 * in handshakes, or because the setting is already saved. You 03974 * might choose to call them anyway, for example in order to 03975 * share code between the cases of establishing a new 03976 * connection and the case of loading an already-established 03977 * connection. 03978 * 03979 * \note If you have new information about the path MTU, you want to 03980 * call mbedtls_ssl_set_mtu() after calling this function, as 03981 * otherwise this function would overwrite your 03982 * newly-configured value with the value that was active when 03983 * the context was saved. 03984 * 03985 * \note When this function returns an error code, it calls 03986 * mbedtls_ssl_free() on \p ssl. In this case, you need to 03987 * prepare the context with the usual sequence starting with a 03988 * call to mbedtls_ssl_init() if you want to use it again. 03989 * 03990 * \param ssl The SSL context structure to be populated. It must have 03991 * been prepared as described in the note above. 03992 * \param buf The buffer holding the serialized connection data. It must 03993 * be a readable buffer of at least \p len bytes. 03994 * \param len The size of the serialized data in bytes. 03995 * 03996 * \return \c 0 if successful. 03997 * \return #MBEDTLS_ERR_SSL_ALLOC_FAILED if memory allocation failed. 03998 * \return #MBEDTLS_ERR_SSL_VERSION_MISMATCH if the serialized data 03999 * comes from a different Mbed TLS version or build. 04000 * \return #MBEDTLS_ERR_SSL_BAD_INPUT_DATA if input data is invalid. 04001 */ 04002 int mbedtls_ssl_context_load( mbedtls_ssl_context *ssl, 04003 const unsigned char *buf, 04004 size_t len ); 04005 #endif /* MBEDTLS_SSL_CONTEXT_SERIALIZATION */ 04006 04007 /** 04008 * \brief Initialize an SSL configuration context 04009 * Just makes the context ready for 04010 * mbedtls_ssl_config_defaults() or mbedtls_ssl_config_free(). 04011 * 04012 * \note You need to call mbedtls_ssl_config_defaults() unless you 04013 * manually set all of the relevant fields yourself. 04014 * 04015 * \param conf SSL configuration context 04016 */ 04017 void mbedtls_ssl_config_init( mbedtls_ssl_config *conf ); 04018 04019 /** 04020 * \brief Load reasonnable default SSL configuration values. 04021 * (You need to call mbedtls_ssl_config_init() first.) 04022 * 04023 * \param conf SSL configuration context 04024 * \param endpoint MBEDTLS_SSL_IS_CLIENT or MBEDTLS_SSL_IS_SERVER 04025 * \param transport MBEDTLS_SSL_TRANSPORT_STREAM for TLS, or 04026 * MBEDTLS_SSL_TRANSPORT_DATAGRAM for DTLS 04027 * \param preset a MBEDTLS_SSL_PRESET_XXX value 04028 * 04029 * \note See \c mbedtls_ssl_conf_transport() for notes on DTLS. 04030 * 04031 * \return 0 if successful, or 04032 * MBEDTLS_ERR_XXX_ALLOC_FAILED on memory allocation error. 04033 */ 04034 int mbedtls_ssl_config_defaults( mbedtls_ssl_config *conf, 04035 int endpoint, int transport, int preset ); 04036 04037 /** 04038 * \brief Free an SSL configuration context 04039 * 04040 * \param conf SSL configuration context 04041 */ 04042 void mbedtls_ssl_config_free( mbedtls_ssl_config *conf ); 04043 04044 /** 04045 * \brief Initialize SSL session structure 04046 * 04047 * \param session SSL session 04048 */ 04049 void mbedtls_ssl_session_init( mbedtls_ssl_session *session ); 04050 04051 /** 04052 * \brief Free referenced items in an SSL session including the 04053 * peer certificate and clear memory 04054 * 04055 * \note A session object can be freed even if the SSL context 04056 * that was used to retrieve the session is still in use. 04057 * 04058 * \param session SSL session 04059 */ 04060 void mbedtls_ssl_session_free( mbedtls_ssl_session *session ); 04061 04062 /** 04063 * \brief TLS-PRF function for key derivation. 04064 * 04065 * \param prf The tls_prf type funtion type to be used. 04066 * \param secret Secret for the key derivation function. 04067 * \param slen Length of the secret. 04068 * \param label String label for the key derivation function, 04069 * terminated with null character. 04070 * \param random Random bytes. 04071 * \param rlen Length of the random bytes buffer. 04072 * \param dstbuf The buffer holding the derived key. 04073 * \param dlen Length of the output buffer. 04074 * 04075 * \return 0 on sucess. An SSL specific error on failure. 04076 */ 04077 int mbedtls_ssl_tls_prf( const mbedtls_tls_prf_types prf, 04078 const unsigned char *secret, size_t slen, 04079 const char *label, 04080 const unsigned char *random, size_t rlen, 04081 unsigned char *dstbuf, size_t dlen ); 04082 04083 #ifdef __cplusplus 04084 } 04085 #endif 04086 04087 #endif /* ssl.h */
Generated on Tue Jul 12 2022 13:54:52 by
1.7.2