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