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