4 * \brief SSL/TLS functions.
\r
7 * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
\r
8 * SPDX-License-Identifier: Apache-2.0
\r
10 * Licensed under the Apache License, Version 2.0 (the "License"); you may
\r
11 * not use this file except in compliance with the License.
\r
12 * You may obtain a copy of the License at
\r
14 * http://www.apache.org/licenses/LICENSE-2.0
\r
16 * Unless required by applicable law or agreed to in writing, software
\r
17 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
\r
18 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
\r
19 * See the License for the specific language governing permissions and
\r
20 * limitations under the License.
\r
22 * This file is part of mbed TLS (https://tls.mbed.org)
\r
24 #ifndef MBEDTLS_SSL_H
\r
25 #define MBEDTLS_SSL_H
\r
27 #if !defined(MBEDTLS_CONFIG_FILE)
\r
30 #include MBEDTLS_CONFIG_FILE
\r
36 #include "ssl_ciphersuites.h"
\r
38 #if defined(MBEDTLS_X509_CRT_PARSE_C)
\r
39 #include "x509_crt.h"
\r
40 #include "x509_crl.h"
\r
43 #if defined(MBEDTLS_DHM_C)
\r
47 #if defined(MBEDTLS_ECDH_C)
\r
51 #if defined(MBEDTLS_ZLIB_SUPPORT)
\r
53 #if defined(MBEDTLS_DEPRECATED_WARNING)
\r
54 #warning "Record compression support via MBEDTLS_ZLIB_SUPPORT is deprecated and will be removed in the next major revision of the library"
\r
57 #if defined(MBEDTLS_DEPRECATED_REMOVED)
\r
58 #error "Record compression support via MBEDTLS_ZLIB_SUPPORT is deprecated and cannot be used if MBEDTLS_DEPRECATED_REMOVED is set"
\r
64 #if defined(MBEDTLS_HAVE_TIME)
\r
65 #include "platform_time.h"
\r
68 #if defined(MBEDTLS_USE_PSA_CRYPTO)
\r
69 #include "psa/crypto.h"
\r
70 #endif /* MBEDTLS_USE_PSA_CRYPTO */
\r
75 #define MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE -0x7080 /**< The requested feature is not available. */
\r
76 #define MBEDTLS_ERR_SSL_BAD_INPUT_DATA -0x7100 /**< Bad input parameters to function. */
\r
77 #define MBEDTLS_ERR_SSL_INVALID_MAC -0x7180 /**< Verification of the message MAC failed. */
\r
78 #define MBEDTLS_ERR_SSL_INVALID_RECORD -0x7200 /**< An invalid SSL record was received. */
\r
79 #define MBEDTLS_ERR_SSL_CONN_EOF -0x7280 /**< The connection indicated an EOF. */
\r
80 #define MBEDTLS_ERR_SSL_UNKNOWN_CIPHER -0x7300 /**< An unknown cipher was received. */
\r
81 #define MBEDTLS_ERR_SSL_NO_CIPHER_CHOSEN -0x7380 /**< The server has no ciphersuites in common with the client. */
\r
82 #define MBEDTLS_ERR_SSL_NO_RNG -0x7400 /**< No RNG was provided to the SSL module. */
\r
83 #define MBEDTLS_ERR_SSL_NO_CLIENT_CERTIFICATE -0x7480 /**< No client certification received from the client, but required by the authentication mode. */
\r
84 #define MBEDTLS_ERR_SSL_CERTIFICATE_TOO_LARGE -0x7500 /**< Our own certificate(s) is/are too large to send in an SSL message. */
\r
85 #define MBEDTLS_ERR_SSL_CERTIFICATE_REQUIRED -0x7580 /**< The own certificate is not set, but needed by the server. */
\r
86 #define MBEDTLS_ERR_SSL_PRIVATE_KEY_REQUIRED -0x7600 /**< The own private key or pre-shared key is not set, but needed. */
\r
87 #define MBEDTLS_ERR_SSL_CA_CHAIN_REQUIRED -0x7680 /**< No CA Chain is set, but required to operate. */
\r
88 #define MBEDTLS_ERR_SSL_UNEXPECTED_MESSAGE -0x7700 /**< An unexpected message was received from our peer. */
\r
89 #define MBEDTLS_ERR_SSL_FATAL_ALERT_MESSAGE -0x7780 /**< A fatal alert message was received from our peer. */
\r
90 #define MBEDTLS_ERR_SSL_PEER_VERIFY_FAILED -0x7800 /**< Verification of our peer failed. */
\r
91 #define MBEDTLS_ERR_SSL_PEER_CLOSE_NOTIFY -0x7880 /**< The peer notified us that the connection is going to be closed. */
\r
92 #define MBEDTLS_ERR_SSL_BAD_HS_CLIENT_HELLO -0x7900 /**< Processing of the ClientHello handshake message failed. */
\r
93 #define MBEDTLS_ERR_SSL_BAD_HS_SERVER_HELLO -0x7980 /**< Processing of the ServerHello handshake message failed. */
\r
94 #define MBEDTLS_ERR_SSL_BAD_HS_CERTIFICATE -0x7A00 /**< Processing of the Certificate handshake message failed. */
\r
95 #define MBEDTLS_ERR_SSL_BAD_HS_CERTIFICATE_REQUEST -0x7A80 /**< Processing of the CertificateRequest handshake message failed. */
\r
96 #define MBEDTLS_ERR_SSL_BAD_HS_SERVER_KEY_EXCHANGE -0x7B00 /**< Processing of the ServerKeyExchange handshake message failed. */
\r
97 #define MBEDTLS_ERR_SSL_BAD_HS_SERVER_HELLO_DONE -0x7B80 /**< Processing of the ServerHelloDone handshake message failed. */
\r
98 #define MBEDTLS_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE -0x7C00 /**< Processing of the ClientKeyExchange handshake message failed. */
\r
99 #define MBEDTLS_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE_RP -0x7C80 /**< Processing of the ClientKeyExchange handshake message failed in DHM / ECDH Read Public. */
\r
100 #define MBEDTLS_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE_CS -0x7D00 /**< Processing of the ClientKeyExchange handshake message failed in DHM / ECDH Calculate Secret. */
\r
101 #define MBEDTLS_ERR_SSL_BAD_HS_CERTIFICATE_VERIFY -0x7D80 /**< Processing of the CertificateVerify handshake message failed. */
\r
102 #define MBEDTLS_ERR_SSL_BAD_HS_CHANGE_CIPHER_SPEC -0x7E00 /**< Processing of the ChangeCipherSpec handshake message failed. */
\r
103 #define MBEDTLS_ERR_SSL_BAD_HS_FINISHED -0x7E80 /**< Processing of the Finished handshake message failed. */
\r
104 #define MBEDTLS_ERR_SSL_ALLOC_FAILED -0x7F00 /**< Memory allocation failed */
\r
105 #define MBEDTLS_ERR_SSL_HW_ACCEL_FAILED -0x7F80 /**< Hardware acceleration function returned with error */
\r
106 #define MBEDTLS_ERR_SSL_HW_ACCEL_FALLTHROUGH -0x6F80 /**< Hardware acceleration function skipped / left alone data */
\r
107 #define MBEDTLS_ERR_SSL_COMPRESSION_FAILED -0x6F00 /**< Processing of the compression / decompression failed */
\r
108 #define MBEDTLS_ERR_SSL_BAD_HS_PROTOCOL_VERSION -0x6E80 /**< Handshake protocol not within min/max boundaries */
\r
109 #define MBEDTLS_ERR_SSL_BAD_HS_NEW_SESSION_TICKET -0x6E00 /**< Processing of the NewSessionTicket handshake message failed. */
\r
110 #define MBEDTLS_ERR_SSL_SESSION_TICKET_EXPIRED -0x6D80 /**< Session ticket has expired. */
\r
111 #define MBEDTLS_ERR_SSL_PK_TYPE_MISMATCH -0x6D00 /**< Public key type mismatch (eg, asked for RSA key exchange and presented EC key) */
\r
112 #define MBEDTLS_ERR_SSL_UNKNOWN_IDENTITY -0x6C80 /**< Unknown identity received (eg, PSK identity) */
\r
113 #define MBEDTLS_ERR_SSL_INTERNAL_ERROR -0x6C00 /**< Internal error (eg, unexpected failure in lower-level module) */
\r
114 #define MBEDTLS_ERR_SSL_COUNTER_WRAPPING -0x6B80 /**< A counter would wrap (eg, too many messages exchanged). */
\r
115 #define MBEDTLS_ERR_SSL_WAITING_SERVER_HELLO_RENEGO -0x6B00 /**< Unexpected message at ServerHello in renegotiation. */
\r
116 #define MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED -0x6A80 /**< DTLS client must retry for hello verification */
\r
117 #define MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL -0x6A00 /**< A buffer is too small to receive or write a message */
\r
118 #define MBEDTLS_ERR_SSL_NO_USABLE_CIPHERSUITE -0x6980 /**< None of the common ciphersuites is usable (eg, no suitable certificate, see debug messages). */
\r
119 #define MBEDTLS_ERR_SSL_WANT_READ -0x6900 /**< No data of requested type currently available on underlying transport. */
\r
120 #define MBEDTLS_ERR_SSL_WANT_WRITE -0x6880 /**< Connection requires a write call. */
\r
121 #define MBEDTLS_ERR_SSL_TIMEOUT -0x6800 /**< The operation timed out. */
\r
122 #define MBEDTLS_ERR_SSL_CLIENT_RECONNECT -0x6780 /**< The client initiated a reconnect from the same port. */
\r
123 #define MBEDTLS_ERR_SSL_UNEXPECTED_RECORD -0x6700 /**< Record header looks valid but is not expected. */
\r
124 #define MBEDTLS_ERR_SSL_NON_FATAL -0x6680 /**< The alert message received indicates a non-fatal error. */
\r
125 #define MBEDTLS_ERR_SSL_INVALID_VERIFY_HASH -0x6600 /**< Couldn't set the hash for verifying CertificateVerify */
\r
126 #define MBEDTLS_ERR_SSL_CONTINUE_PROCESSING -0x6580 /**< Internal-only message signaling that further message-processing should be done */
\r
127 #define MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS -0x6500 /**< The asynchronous operation is not completed yet. */
\r
128 #define MBEDTLS_ERR_SSL_EARLY_MESSAGE -0x6480 /**< Internal-only message signaling that a message arrived early. */
\r
129 #define MBEDTLS_ERR_SSL_UNEXPECTED_CID -0x6000 /**< An encrypted DTLS-frame with an unexpected CID was received. */
\r
130 #define MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS -0x7000 /**< A cryptographic operation is in progress. Try again later. */
\r
133 * Various constants
\r
135 #define MBEDTLS_SSL_MAJOR_VERSION_3 3
\r
136 #define MBEDTLS_SSL_MINOR_VERSION_0 0 /*!< SSL v3.0 */
\r
137 #define MBEDTLS_SSL_MINOR_VERSION_1 1 /*!< TLS v1.0 */
\r
138 #define MBEDTLS_SSL_MINOR_VERSION_2 2 /*!< TLS v1.1 */
\r
139 #define MBEDTLS_SSL_MINOR_VERSION_3 3 /*!< TLS v1.2 */
\r
141 #define MBEDTLS_SSL_TRANSPORT_STREAM 0 /*!< TLS */
\r
142 #define MBEDTLS_SSL_TRANSPORT_DATAGRAM 1 /*!< DTLS */
\r
144 #define MBEDTLS_SSL_MAX_HOST_NAME_LEN 255 /*!< Maximum host name defined in RFC 1035 */
\r
146 /* RFC 6066 section 4, see also mfl_code_to_length in ssl_tls.c
\r
147 * NONE must be zero so that memset()ing structure to zero works */
\r
148 #define MBEDTLS_SSL_MAX_FRAG_LEN_NONE 0 /*!< don't use this extension */
\r
149 #define MBEDTLS_SSL_MAX_FRAG_LEN_512 1 /*!< MaxFragmentLength 2^9 */
\r
150 #define MBEDTLS_SSL_MAX_FRAG_LEN_1024 2 /*!< MaxFragmentLength 2^10 */
\r
151 #define MBEDTLS_SSL_MAX_FRAG_LEN_2048 3 /*!< MaxFragmentLength 2^11 */
\r
152 #define MBEDTLS_SSL_MAX_FRAG_LEN_4096 4 /*!< MaxFragmentLength 2^12 */
\r
153 #define MBEDTLS_SSL_MAX_FRAG_LEN_INVALID 5 /*!< first invalid value */
\r
155 #define MBEDTLS_SSL_IS_CLIENT 0
\r
156 #define MBEDTLS_SSL_IS_SERVER 1
\r
158 #define MBEDTLS_SSL_IS_NOT_FALLBACK 0
\r
159 #define MBEDTLS_SSL_IS_FALLBACK 1
\r
161 #define MBEDTLS_SSL_EXTENDED_MS_DISABLED 0
\r
162 #define MBEDTLS_SSL_EXTENDED_MS_ENABLED 1
\r
164 #define MBEDTLS_SSL_CID_DISABLED 0
\r
165 #define MBEDTLS_SSL_CID_ENABLED 1
\r
167 #define MBEDTLS_SSL_ETM_DISABLED 0
\r
168 #define MBEDTLS_SSL_ETM_ENABLED 1
\r
170 #define MBEDTLS_SSL_COMPRESS_NULL 0
\r
171 #define MBEDTLS_SSL_COMPRESS_DEFLATE 1
\r
173 #define MBEDTLS_SSL_VERIFY_NONE 0
\r
174 #define MBEDTLS_SSL_VERIFY_OPTIONAL 1
\r
175 #define MBEDTLS_SSL_VERIFY_REQUIRED 2
\r
176 #define MBEDTLS_SSL_VERIFY_UNSET 3 /* Used only for sni_authmode */
\r
178 #define MBEDTLS_SSL_LEGACY_RENEGOTIATION 0
\r
179 #define MBEDTLS_SSL_SECURE_RENEGOTIATION 1
\r
181 #define MBEDTLS_SSL_RENEGOTIATION_DISABLED 0
\r
182 #define MBEDTLS_SSL_RENEGOTIATION_ENABLED 1
\r
184 #define MBEDTLS_SSL_ANTI_REPLAY_DISABLED 0
\r
185 #define MBEDTLS_SSL_ANTI_REPLAY_ENABLED 1
\r
187 #define MBEDTLS_SSL_RENEGOTIATION_NOT_ENFORCED -1
\r
188 #define MBEDTLS_SSL_RENEGO_MAX_RECORDS_DEFAULT 16
\r
190 #define MBEDTLS_SSL_LEGACY_NO_RENEGOTIATION 0
\r
191 #define MBEDTLS_SSL_LEGACY_ALLOW_RENEGOTIATION 1
\r
192 #define MBEDTLS_SSL_LEGACY_BREAK_HANDSHAKE 2
\r
194 #define MBEDTLS_SSL_TRUNC_HMAC_DISABLED 0
\r
195 #define MBEDTLS_SSL_TRUNC_HMAC_ENABLED 1
\r
196 #define MBEDTLS_SSL_TRUNCATED_HMAC_LEN 10 /* 80 bits, rfc 6066 section 7 */
\r
198 #define MBEDTLS_SSL_SESSION_TICKETS_DISABLED 0
\r
199 #define MBEDTLS_SSL_SESSION_TICKETS_ENABLED 1
\r
201 #define MBEDTLS_SSL_CBC_RECORD_SPLITTING_DISABLED 0
\r
202 #define MBEDTLS_SSL_CBC_RECORD_SPLITTING_ENABLED 1
\r
204 #define MBEDTLS_SSL_ARC4_ENABLED 0
\r
205 #define MBEDTLS_SSL_ARC4_DISABLED 1
\r
207 #define MBEDTLS_SSL_PRESET_DEFAULT 0
\r
208 #define MBEDTLS_SSL_PRESET_SUITEB 2
\r
210 #define MBEDTLS_SSL_CERT_REQ_CA_LIST_ENABLED 1
\r
211 #define MBEDTLS_SSL_CERT_REQ_CA_LIST_DISABLED 0
\r
214 * Default range for DTLS retransmission timer value, in milliseconds.
\r
215 * RFC 6347 4.2.4.1 says from 1 second to 60 seconds.
\r
217 #define MBEDTLS_SSL_DTLS_TIMEOUT_DFL_MIN 1000
\r
218 #define MBEDTLS_SSL_DTLS_TIMEOUT_DFL_MAX 60000
\r
221 * \name SECTION: Module settings
\r
223 * The configuration options you can set for this module are in this section.
\r
224 * Either change them in config.h or define them on the compiler command line.
\r
228 #if !defined(MBEDTLS_SSL_DEFAULT_TICKET_LIFETIME)
\r
229 #define MBEDTLS_SSL_DEFAULT_TICKET_LIFETIME 86400 /**< Lifetime of session tickets (if enabled) */
\r
233 * Maximum fragment length in bytes,
\r
234 * determines the size of each of the two internal I/O buffers.
\r
236 * Note: the RFC defines the default size of SSL / TLS messages. If you
\r
237 * change the value here, other clients / servers may not be able to
\r
238 * communicate with you anymore. Only change this value if you control
\r
239 * both sides of the connection and have it reduced at both sides, or
\r
240 * if you're using the Max Fragment Length extension and you know all your
\r
241 * peers are using it too!
\r
243 #if !defined(MBEDTLS_SSL_MAX_CONTENT_LEN)
\r
244 #define MBEDTLS_SSL_MAX_CONTENT_LEN 16384 /**< Size of the input / output buffer */
\r
247 #if !defined(MBEDTLS_SSL_IN_CONTENT_LEN)
\r
248 #define MBEDTLS_SSL_IN_CONTENT_LEN MBEDTLS_SSL_MAX_CONTENT_LEN
\r
251 #if !defined(MBEDTLS_SSL_OUT_CONTENT_LEN)
\r
252 #define MBEDTLS_SSL_OUT_CONTENT_LEN MBEDTLS_SSL_MAX_CONTENT_LEN
\r
256 * Maximum number of heap-allocated bytes for the purpose of
\r
257 * DTLS handshake message reassembly and future message buffering.
\r
259 #if !defined(MBEDTLS_SSL_DTLS_MAX_BUFFERING)
\r
260 #define MBEDTLS_SSL_DTLS_MAX_BUFFERING 32768
\r
264 * Maximum length of CIDs for incoming and outgoing messages.
\r
266 #if !defined(MBEDTLS_SSL_CID_IN_LEN_MAX)
\r
267 #define MBEDTLS_SSL_CID_IN_LEN_MAX 32
\r
270 #if !defined(MBEDTLS_SSL_CID_OUT_LEN_MAX)
\r
271 #define MBEDTLS_SSL_CID_OUT_LEN_MAX 32
\r
274 #if !defined(MBEDTLS_SSL_CID_PADDING_GRANULARITY)
\r
275 #define MBEDTLS_SSL_CID_PADDING_GRANULARITY 16
\r
278 /* \} name SECTION: Module settings */
\r
281 * Length of the verify data for secure renegotiation
\r
283 #if defined(MBEDTLS_SSL_PROTO_SSL3)
\r
284 #define MBEDTLS_SSL_VERIFY_DATA_MAX_LEN 36
\r
286 #define MBEDTLS_SSL_VERIFY_DATA_MAX_LEN 12
\r
290 * Signaling ciphersuite values (SCSV)
\r
292 #define MBEDTLS_SSL_EMPTY_RENEGOTIATION_INFO 0xFF /**< renegotiation info ext */
\r
293 #define MBEDTLS_SSL_FALLBACK_SCSV_VALUE 0x5600 /**< RFC 7507 section 2 */
\r
296 * Supported Signature and Hash algorithms (For TLS 1.2)
\r
297 * RFC 5246 section 7.4.1.4.1
\r
299 #define MBEDTLS_SSL_HASH_NONE 0
\r
300 #define MBEDTLS_SSL_HASH_MD5 1
\r
301 #define MBEDTLS_SSL_HASH_SHA1 2
\r
302 #define MBEDTLS_SSL_HASH_SHA224 3
\r
303 #define MBEDTLS_SSL_HASH_SHA256 4
\r
304 #define MBEDTLS_SSL_HASH_SHA384 5
\r
305 #define MBEDTLS_SSL_HASH_SHA512 6
\r
307 #define MBEDTLS_SSL_SIG_ANON 0
\r
308 #define MBEDTLS_SSL_SIG_RSA 1
\r
309 #define MBEDTLS_SSL_SIG_ECDSA 3
\r
312 * Client Certificate Types
\r
313 * RFC 5246 section 7.4.4 plus RFC 4492 section 5.5
\r
315 #define MBEDTLS_SSL_CERT_TYPE_RSA_SIGN 1
\r
316 #define MBEDTLS_SSL_CERT_TYPE_ECDSA_SIGN 64
\r
319 * Message, alert and handshake types
\r
321 #define MBEDTLS_SSL_MSG_CHANGE_CIPHER_SPEC 20
\r
322 #define MBEDTLS_SSL_MSG_ALERT 21
\r
323 #define MBEDTLS_SSL_MSG_HANDSHAKE 22
\r
324 #define MBEDTLS_SSL_MSG_APPLICATION_DATA 23
\r
325 #define MBEDTLS_SSL_MSG_CID 25
\r
327 #define MBEDTLS_SSL_ALERT_LEVEL_WARNING 1
\r
328 #define MBEDTLS_SSL_ALERT_LEVEL_FATAL 2
\r
330 #define MBEDTLS_SSL_ALERT_MSG_CLOSE_NOTIFY 0 /* 0x00 */
\r
331 #define MBEDTLS_SSL_ALERT_MSG_UNEXPECTED_MESSAGE 10 /* 0x0A */
\r
332 #define MBEDTLS_SSL_ALERT_MSG_BAD_RECORD_MAC 20 /* 0x14 */
\r
333 #define MBEDTLS_SSL_ALERT_MSG_DECRYPTION_FAILED 21 /* 0x15 */
\r
334 #define MBEDTLS_SSL_ALERT_MSG_RECORD_OVERFLOW 22 /* 0x16 */
\r
335 #define MBEDTLS_SSL_ALERT_MSG_DECOMPRESSION_FAILURE 30 /* 0x1E */
\r
336 #define MBEDTLS_SSL_ALERT_MSG_HANDSHAKE_FAILURE 40 /* 0x28 */
\r
337 #define MBEDTLS_SSL_ALERT_MSG_NO_CERT 41 /* 0x29 */
\r
338 #define MBEDTLS_SSL_ALERT_MSG_BAD_CERT 42 /* 0x2A */
\r
339 #define MBEDTLS_SSL_ALERT_MSG_UNSUPPORTED_CERT 43 /* 0x2B */
\r
340 #define MBEDTLS_SSL_ALERT_MSG_CERT_REVOKED 44 /* 0x2C */
\r
341 #define MBEDTLS_SSL_ALERT_MSG_CERT_EXPIRED 45 /* 0x2D */
\r
342 #define MBEDTLS_SSL_ALERT_MSG_CERT_UNKNOWN 46 /* 0x2E */
\r
343 #define MBEDTLS_SSL_ALERT_MSG_ILLEGAL_PARAMETER 47 /* 0x2F */
\r
344 #define MBEDTLS_SSL_ALERT_MSG_UNKNOWN_CA 48 /* 0x30 */
\r
345 #define MBEDTLS_SSL_ALERT_MSG_ACCESS_DENIED 49 /* 0x31 */
\r
346 #define MBEDTLS_SSL_ALERT_MSG_DECODE_ERROR 50 /* 0x32 */
\r
347 #define MBEDTLS_SSL_ALERT_MSG_DECRYPT_ERROR 51 /* 0x33 */
\r
348 #define MBEDTLS_SSL_ALERT_MSG_EXPORT_RESTRICTION 60 /* 0x3C */
\r
349 #define MBEDTLS_SSL_ALERT_MSG_PROTOCOL_VERSION 70 /* 0x46 */
\r
350 #define MBEDTLS_SSL_ALERT_MSG_INSUFFICIENT_SECURITY 71 /* 0x47 */
\r
351 #define MBEDTLS_SSL_ALERT_MSG_INTERNAL_ERROR 80 /* 0x50 */
\r
352 #define MBEDTLS_SSL_ALERT_MSG_INAPROPRIATE_FALLBACK 86 /* 0x56 */
\r
353 #define MBEDTLS_SSL_ALERT_MSG_USER_CANCELED 90 /* 0x5A */
\r
354 #define MBEDTLS_SSL_ALERT_MSG_NO_RENEGOTIATION 100 /* 0x64 */
\r
355 #define MBEDTLS_SSL_ALERT_MSG_UNSUPPORTED_EXT 110 /* 0x6E */
\r
356 #define MBEDTLS_SSL_ALERT_MSG_UNRECOGNIZED_NAME 112 /* 0x70 */
\r
357 #define MBEDTLS_SSL_ALERT_MSG_UNKNOWN_PSK_IDENTITY 115 /* 0x73 */
\r
358 #define MBEDTLS_SSL_ALERT_MSG_NO_APPLICATION_PROTOCOL 120 /* 0x78 */
\r
360 #define MBEDTLS_SSL_HS_HELLO_REQUEST 0
\r
361 #define MBEDTLS_SSL_HS_CLIENT_HELLO 1
\r
362 #define MBEDTLS_SSL_HS_SERVER_HELLO 2
\r
363 #define MBEDTLS_SSL_HS_HELLO_VERIFY_REQUEST 3
\r
364 #define MBEDTLS_SSL_HS_NEW_SESSION_TICKET 4
\r
365 #define MBEDTLS_SSL_HS_CERTIFICATE 11
\r
366 #define MBEDTLS_SSL_HS_SERVER_KEY_EXCHANGE 12
\r
367 #define MBEDTLS_SSL_HS_CERTIFICATE_REQUEST 13
\r
368 #define MBEDTLS_SSL_HS_SERVER_HELLO_DONE 14
\r
369 #define MBEDTLS_SSL_HS_CERTIFICATE_VERIFY 15
\r
370 #define MBEDTLS_SSL_HS_CLIENT_KEY_EXCHANGE 16
\r
371 #define MBEDTLS_SSL_HS_FINISHED 20
\r
376 #define MBEDTLS_TLS_EXT_SERVERNAME 0
\r
377 #define MBEDTLS_TLS_EXT_SERVERNAME_HOSTNAME 0
\r
379 #define MBEDTLS_TLS_EXT_MAX_FRAGMENT_LENGTH 1
\r
381 #define MBEDTLS_TLS_EXT_TRUNCATED_HMAC 4
\r
383 #define MBEDTLS_TLS_EXT_SUPPORTED_ELLIPTIC_CURVES 10
\r
384 #define MBEDTLS_TLS_EXT_SUPPORTED_POINT_FORMATS 11
\r
386 #define MBEDTLS_TLS_EXT_SIG_ALG 13
\r
388 #define MBEDTLS_TLS_EXT_ALPN 16
\r
390 #define MBEDTLS_TLS_EXT_ENCRYPT_THEN_MAC 22 /* 0x16 */
\r
391 #define MBEDTLS_TLS_EXT_EXTENDED_MASTER_SECRET 0x0017 /* 23 */
\r
393 #define MBEDTLS_TLS_EXT_SESSION_TICKET 35
\r
395 /* The value of the CID extension is still TBD as of
\r
396 * draft-ietf-tls-dtls-connection-id-05
\r
397 * (https://tools.ietf.org/html/draft-ietf-tls-dtls-connection-id-05) */
\r
398 #define MBEDTLS_TLS_EXT_CID 254 /* TBD */
\r
400 #define MBEDTLS_TLS_EXT_ECJPAKE_KKPP 256 /* experimental */
\r
402 #define MBEDTLS_TLS_EXT_RENEGOTIATION_INFO 0xFF01
\r
407 #if !defined(MBEDTLS_PSK_MAX_LEN)
\r
408 #define MBEDTLS_PSK_MAX_LEN 32 /* 256 bits */
\r
411 /* Dummy type used only for its size */
\r
412 union mbedtls_ssl_premaster_secret
\r
414 #if defined(MBEDTLS_KEY_EXCHANGE_RSA_ENABLED)
\r
415 unsigned char _pms_rsa[48]; /* RFC 5246 8.1.1 */
\r
417 #if defined(MBEDTLS_KEY_EXCHANGE_DHE_RSA_ENABLED)
\r
418 unsigned char _pms_dhm[MBEDTLS_MPI_MAX_SIZE]; /* RFC 5246 8.1.2 */
\r
420 #if defined(MBEDTLS_KEY_EXCHANGE_ECDHE_RSA_ENABLED) || \
\r
421 defined(MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED) || \
\r
422 defined(MBEDTLS_KEY_EXCHANGE_ECDH_RSA_ENABLED) || \
\r
423 defined(MBEDTLS_KEY_EXCHANGE_ECDH_ECDSA_ENABLED)
\r
424 unsigned char _pms_ecdh[MBEDTLS_ECP_MAX_BYTES]; /* RFC 4492 5.10 */
\r
426 #if defined(MBEDTLS_KEY_EXCHANGE_PSK_ENABLED)
\r
427 unsigned char _pms_psk[4 + 2 * MBEDTLS_PSK_MAX_LEN]; /* RFC 4279 2 */
\r
429 #if defined(MBEDTLS_KEY_EXCHANGE_DHE_PSK_ENABLED)
\r
430 unsigned char _pms_dhe_psk[4 + MBEDTLS_MPI_MAX_SIZE
\r
431 + MBEDTLS_PSK_MAX_LEN]; /* RFC 4279 3 */
\r
433 #if defined(MBEDTLS_KEY_EXCHANGE_RSA_PSK_ENABLED)
\r
434 unsigned char _pms_rsa_psk[52 + MBEDTLS_PSK_MAX_LEN]; /* RFC 4279 4 */
\r
436 #if defined(MBEDTLS_KEY_EXCHANGE_ECDHE_PSK_ENABLED)
\r
437 unsigned char _pms_ecdhe_psk[4 + MBEDTLS_ECP_MAX_BYTES
\r
438 + MBEDTLS_PSK_MAX_LEN]; /* RFC 5489 2 */
\r
440 #if defined(MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED)
\r
441 unsigned char _pms_ecjpake[32]; /* Thread spec: SHA-256 output */
\r
445 #define MBEDTLS_PREMASTER_SIZE sizeof( union mbedtls_ssl_premaster_secret )
\r
452 * SSL state machine
\r
456 MBEDTLS_SSL_HELLO_REQUEST,
\r
457 MBEDTLS_SSL_CLIENT_HELLO,
\r
458 MBEDTLS_SSL_SERVER_HELLO,
\r
459 MBEDTLS_SSL_SERVER_CERTIFICATE,
\r
460 MBEDTLS_SSL_SERVER_KEY_EXCHANGE,
\r
461 MBEDTLS_SSL_CERTIFICATE_REQUEST,
\r
462 MBEDTLS_SSL_SERVER_HELLO_DONE,
\r
463 MBEDTLS_SSL_CLIENT_CERTIFICATE,
\r
464 MBEDTLS_SSL_CLIENT_KEY_EXCHANGE,
\r
465 MBEDTLS_SSL_CERTIFICATE_VERIFY,
\r
466 MBEDTLS_SSL_CLIENT_CHANGE_CIPHER_SPEC,
\r
467 MBEDTLS_SSL_CLIENT_FINISHED,
\r
468 MBEDTLS_SSL_SERVER_CHANGE_CIPHER_SPEC,
\r
469 MBEDTLS_SSL_SERVER_FINISHED,
\r
470 MBEDTLS_SSL_FLUSH_BUFFERS,
\r
471 MBEDTLS_SSL_HANDSHAKE_WRAPUP,
\r
472 MBEDTLS_SSL_HANDSHAKE_OVER,
\r
473 MBEDTLS_SSL_SERVER_NEW_SESSION_TICKET,
\r
474 MBEDTLS_SSL_SERVER_HELLO_VERIFY_REQUEST_SENT,
\r
476 mbedtls_ssl_states;
\r
479 * The tls_prf function types.
\r
483 MBEDTLS_SSL_TLS_PRF_NONE,
\r
484 MBEDTLS_SSL_TLS_PRF_SSL3,
\r
485 MBEDTLS_SSL_TLS_PRF_TLS1,
\r
486 MBEDTLS_SSL_TLS_PRF_SHA384,
\r
487 MBEDTLS_SSL_TLS_PRF_SHA256
\r
489 mbedtls_tls_prf_types;
\r
491 * \brief Callback type: send data on the network.
\r
493 * \note That callback may be either blocking or non-blocking.
\r
495 * \param ctx Context for the send callback (typically a file descriptor)
\r
496 * \param buf Buffer holding the data to send
\r
497 * \param len Length of the data to send
\r
499 * \return The callback must return the number of bytes sent if any,
\r
500 * or a non-zero error code.
\r
501 * If performing non-blocking I/O, \c MBEDTLS_ERR_SSL_WANT_WRITE
\r
502 * must be returned when the operation would block.
\r
504 * \note The callback is allowed to send fewer bytes than requested.
\r
505 * It must always return the number of bytes actually sent.
\r
507 typedef int mbedtls_ssl_send_t( void *ctx,
\r
508 const unsigned char *buf,
\r
512 * \brief Callback type: receive data from the network.
\r
514 * \note That callback may be either blocking or non-blocking.
\r
516 * \param ctx Context for the receive callback (typically a file
\r
518 * \param buf Buffer to write the received data to
\r
519 * \param len Length of the receive buffer
\r
521 * \return The callback must return the number of bytes received,
\r
522 * or a non-zero error code.
\r
523 * If performing non-blocking I/O, \c MBEDTLS_ERR_SSL_WANT_READ
\r
524 * must be returned when the operation would block.
\r
526 * \note The callback may receive fewer bytes than the length of the
\r
527 * buffer. It must always return the number of bytes actually
\r
528 * received and written to the buffer.
\r
530 typedef int mbedtls_ssl_recv_t( void *ctx,
\r
531 unsigned char *buf,
\r
535 * \brief Callback type: receive data from the network, with timeout
\r
537 * \note That callback must block until data is received, or the
\r
538 * timeout delay expires, or the operation is interrupted by a
\r
541 * \param ctx Context for the receive callback (typically a file descriptor)
\r
542 * \param buf Buffer to write the received data to
\r
543 * \param len Length of the receive buffer
\r
544 * \param timeout Maximum nomber of millisecondes to wait for data
\r
545 * 0 means no timeout (potentially waiting forever)
\r
547 * \return The callback must return the number of bytes received,
\r
548 * or a non-zero error code:
\r
549 * \c MBEDTLS_ERR_SSL_TIMEOUT if the operation timed out,
\r
550 * \c MBEDTLS_ERR_SSL_WANT_READ if interrupted by a signal.
\r
552 * \note The callback may receive fewer bytes than the length of the
\r
553 * buffer. It must always return the number of bytes actually
\r
554 * received and written to the buffer.
\r
556 typedef int mbedtls_ssl_recv_timeout_t( void *ctx,
\r
557 unsigned char *buf,
\r
559 uint32_t timeout );
\r
561 * \brief Callback type: set a pair of timers/delays to watch
\r
563 * \param ctx Context pointer
\r
564 * \param int_ms Intermediate delay in milliseconds
\r
565 * \param fin_ms Final delay in milliseconds
\r
566 * 0 cancels the current timer.
\r
568 * \note This callback must at least store the necessary information
\r
569 * for the associated \c mbedtls_ssl_get_timer_t callback to
\r
570 * return correct information.
\r
572 * \note If using a event-driven style of programming, an event must
\r
573 * be generated when the final delay is passed. The event must
\r
574 * cause a call to \c mbedtls_ssl_handshake() with the proper
\r
575 * SSL context to be scheduled. Care must be taken to ensure
\r
576 * that at most one such call happens at a time.
\r
578 * \note Only one timer at a time must be running. Calling this
\r
579 * function while a timer is running must cancel it. Cancelled
\r
580 * timers must not generate any event.
\r
582 typedef void mbedtls_ssl_set_timer_t( void * ctx,
\r
587 * \brief Callback type: get status of timers/delays
\r
589 * \param ctx Context pointer
\r
591 * \return This callback must return:
\r
592 * -1 if cancelled (fin_ms == 0),
\r
593 * 0 if none of the delays have passed,
\r
594 * 1 if only the intermediate delay has passed,
\r
595 * 2 if the final delay has passed.
\r
597 typedef int mbedtls_ssl_get_timer_t( void * ctx );
\r
599 /* Defined below */
\r
600 typedef struct mbedtls_ssl_session mbedtls_ssl_session;
\r
601 typedef struct mbedtls_ssl_context mbedtls_ssl_context;
\r
602 typedef struct mbedtls_ssl_config mbedtls_ssl_config;
\r
604 /* Defined in ssl_internal.h */
\r
605 typedef struct mbedtls_ssl_transform mbedtls_ssl_transform;
\r
606 typedef struct mbedtls_ssl_handshake_params mbedtls_ssl_handshake_params;
\r
607 typedef struct mbedtls_ssl_sig_hash_set_t mbedtls_ssl_sig_hash_set_t;
\r
608 #if defined(MBEDTLS_X509_CRT_PARSE_C)
\r
609 typedef struct mbedtls_ssl_key_cert mbedtls_ssl_key_cert;
\r
611 #if defined(MBEDTLS_SSL_PROTO_DTLS)
\r
612 typedef struct mbedtls_ssl_flight_item mbedtls_ssl_flight_item;
\r
615 #if defined(MBEDTLS_SSL_ASYNC_PRIVATE)
\r
616 #if defined(MBEDTLS_X509_CRT_PARSE_C)
\r
618 * \brief Callback type: start external signature operation.
\r
620 * This callback is called during an SSL handshake to start
\r
621 * a signature decryption operation using an
\r
622 * external processor. The parameter \p cert contains
\r
623 * the public key; it is up to the callback function to
\r
624 * determine how to access the associated private key.
\r
626 * This function typically sends or enqueues a request, and
\r
627 * does not wait for the operation to complete. This allows
\r
628 * the handshake step to be non-blocking.
\r
630 * The parameters \p ssl and \p cert are guaranteed to remain
\r
631 * valid throughout the handshake. On the other hand, this
\r
632 * function must save the contents of \p hash if the value
\r
633 * is needed for later processing, because the \p hash buffer
\r
634 * is no longer valid after this function returns.
\r
636 * This function may call mbedtls_ssl_set_async_operation_data()
\r
637 * to store an operation context for later retrieval
\r
638 * by the resume or cancel callback.
\r
640 * \note For RSA signatures, this function must produce output
\r
641 * that is consistent with PKCS#1 v1.5 in the same way as
\r
642 * mbedtls_rsa_pkcs1_sign(). Before the private key operation,
\r
643 * apply the padding steps described in RFC 8017, section 9.2
\r
644 * "EMSA-PKCS1-v1_5" as follows.
\r
645 * - If \p md_alg is #MBEDTLS_MD_NONE, apply the PKCS#1 v1.5
\r
646 * encoding, treating \p hash as the DigestInfo to be
\r
647 * padded. In other words, apply EMSA-PKCS1-v1_5 starting
\r
648 * from step 3, with `T = hash` and `tLen = hash_len`.
\r
649 * - If `md_alg != MBEDTLS_MD_NONE`, apply the PKCS#1 v1.5
\r
650 * encoding, treating \p hash as the hash to be encoded and
\r
651 * padded. In other words, apply EMSA-PKCS1-v1_5 starting
\r
652 * from step 2, with `digestAlgorithm` obtained by calling
\r
653 * mbedtls_oid_get_oid_by_md() on \p md_alg.
\r
655 * \note For ECDSA signatures, the output format is the DER encoding
\r
656 * `Ecdsa-Sig-Value` defined in
\r
657 * [RFC 4492 section 5.4](https://tools.ietf.org/html/rfc4492#section-5.4).
\r
659 * \param ssl The SSL connection instance. It should not be
\r
660 * modified other than via
\r
661 * mbedtls_ssl_set_async_operation_data().
\r
662 * \param cert Certificate containing the public key.
\r
663 * In simple cases, this is one of the pointers passed to
\r
664 * mbedtls_ssl_conf_own_cert() when configuring the SSL
\r
665 * connection. However, if other callbacks are used, this
\r
666 * property may not hold. For example, if an SNI callback
\r
667 * is registered with mbedtls_ssl_conf_sni(), then
\r
668 * this callback determines what certificate is used.
\r
669 * \param md_alg Hash algorithm.
\r
670 * \param hash Buffer containing the hash. This buffer is
\r
671 * no longer valid when the function returns.
\r
672 * \param hash_len Size of the \c hash buffer in bytes.
\r
674 * \return 0 if the operation was started successfully and the SSL
\r
675 * stack should call the resume callback immediately.
\r
676 * \return #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS if the operation
\r
677 * was started successfully and the SSL stack should return
\r
678 * immediately without calling the resume callback yet.
\r
679 * \return #MBEDTLS_ERR_SSL_HW_ACCEL_FALLTHROUGH if the external
\r
680 * processor does not support this key. The SSL stack will
\r
681 * use the private key object instead.
\r
682 * \return Any other error indicates a fatal failure and is
\r
683 * propagated up the call chain. The callback should
\r
684 * use \c MBEDTLS_ERR_PK_xxx error codes, and <b>must not</b>
\r
685 * use \c MBEDTLS_ERR_SSL_xxx error codes except as
\r
686 * directed in the documentation of this callback.
\r
688 typedef int mbedtls_ssl_async_sign_t( mbedtls_ssl_context *ssl,
\r
689 mbedtls_x509_crt *cert,
\r
690 mbedtls_md_type_t md_alg,
\r
691 const unsigned char *hash,
\r
695 * \brief Callback type: start external decryption operation.
\r
697 * This callback is called during an SSL handshake to start
\r
698 * an RSA decryption operation using an
\r
699 * external processor. The parameter \p cert contains
\r
700 * the public key; it is up to the callback function to
\r
701 * determine how to access the associated private key.
\r
703 * This function typically sends or enqueues a request, and
\r
704 * does not wait for the operation to complete. This allows
\r
705 * the handshake step to be non-blocking.
\r
707 * The parameters \p ssl and \p cert are guaranteed to remain
\r
708 * valid throughout the handshake. On the other hand, this
\r
709 * function must save the contents of \p input if the value
\r
710 * is needed for later processing, because the \p input buffer
\r
711 * is no longer valid after this function returns.
\r
713 * This function may call mbedtls_ssl_set_async_operation_data()
\r
714 * to store an operation context for later retrieval
\r
715 * by the resume or cancel callback.
\r
717 * \warning RSA decryption as used in TLS is subject to a potential
\r
718 * timing side channel attack first discovered by Bleichenbacher
\r
719 * in 1998. This attack can be remotely exploitable
\r
720 * in practice. To avoid this attack, you must ensure that
\r
721 * if the callback performs an RSA decryption, the time it
\r
722 * takes to execute and return the result does not depend
\r
723 * on whether the RSA decryption succeeded or reported
\r
726 * \param ssl The SSL connection instance. It should not be
\r
727 * modified other than via
\r
728 * mbedtls_ssl_set_async_operation_data().
\r
729 * \param cert Certificate containing the public key.
\r
730 * In simple cases, this is one of the pointers passed to
\r
731 * mbedtls_ssl_conf_own_cert() when configuring the SSL
\r
732 * connection. However, if other callbacks are used, this
\r
733 * property may not hold. For example, if an SNI callback
\r
734 * is registered with mbedtls_ssl_conf_sni(), then
\r
735 * this callback determines what certificate is used.
\r
736 * \param input Buffer containing the input ciphertext. This buffer
\r
737 * is no longer valid when the function returns.
\r
738 * \param input_len Size of the \p input buffer in bytes.
\r
740 * \return 0 if the operation was started successfully and the SSL
\r
741 * stack should call the resume callback immediately.
\r
742 * \return #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS if the operation
\r
743 * was started successfully and the SSL stack should return
\r
744 * immediately without calling the resume callback yet.
\r
745 * \return #MBEDTLS_ERR_SSL_HW_ACCEL_FALLTHROUGH if the external
\r
746 * processor does not support this key. The SSL stack will
\r
747 * use the private key object instead.
\r
748 * \return Any other error indicates a fatal failure and is
\r
749 * propagated up the call chain. The callback should
\r
750 * use \c MBEDTLS_ERR_PK_xxx error codes, and <b>must not</b>
\r
751 * use \c MBEDTLS_ERR_SSL_xxx error codes except as
\r
752 * directed in the documentation of this callback.
\r
754 typedef int mbedtls_ssl_async_decrypt_t( mbedtls_ssl_context *ssl,
\r
755 mbedtls_x509_crt *cert,
\r
756 const unsigned char *input,
\r
757 size_t input_len );
\r
758 #endif /* MBEDTLS_X509_CRT_PARSE_C */
\r
761 * \brief Callback type: resume external operation.
\r
763 * This callback is called during an SSL handshake to resume
\r
764 * an external operation started by the
\r
765 * ::mbedtls_ssl_async_sign_t or
\r
766 * ::mbedtls_ssl_async_decrypt_t callback.
\r
768 * This function typically checks the status of a pending
\r
769 * request or causes the request queue to make progress, and
\r
770 * does not wait for the operation to complete. This allows
\r
771 * the handshake step to be non-blocking.
\r
773 * This function may call mbedtls_ssl_get_async_operation_data()
\r
774 * to retrieve an operation context set by the start callback.
\r
775 * It may call mbedtls_ssl_set_async_operation_data() to modify
\r
778 * Note that when this function returns a status other than
\r
779 * #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS, it must free any
\r
780 * resources associated with the operation.
\r
782 * \param ssl The SSL connection instance. It should not be
\r
783 * modified other than via
\r
784 * mbedtls_ssl_set_async_operation_data().
\r
785 * \param output Buffer containing the output (signature or decrypted
\r
786 * data) on success.
\r
787 * \param output_len On success, number of bytes written to \p output.
\r
788 * \param output_size Size of the \p output buffer in bytes.
\r
790 * \return 0 if output of the operation is available in the
\r
791 * \p output buffer.
\r
792 * \return #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS if the operation
\r
793 * is still in progress. Subsequent requests for progress
\r
794 * on the SSL connection will call the resume callback
\r
796 * \return Any other error means that the operation is aborted.
\r
797 * The SSL handshake is aborted. The callback should
\r
798 * use \c MBEDTLS_ERR_PK_xxx error codes, and <b>must not</b>
\r
799 * use \c MBEDTLS_ERR_SSL_xxx error codes except as
\r
800 * directed in the documentation of this callback.
\r
802 typedef int mbedtls_ssl_async_resume_t( mbedtls_ssl_context *ssl,
\r
803 unsigned char *output,
\r
804 size_t *output_len,
\r
805 size_t output_size );
\r
808 * \brief Callback type: cancel external operation.
\r
810 * This callback is called if an SSL connection is closed
\r
811 * while an asynchronous operation is in progress. Note that
\r
812 * this callback is not called if the
\r
813 * ::mbedtls_ssl_async_resume_t callback has run and has
\r
814 * returned a value other than
\r
815 * #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS, since in that case
\r
816 * the asynchronous operation has already completed.
\r
818 * This function may call mbedtls_ssl_get_async_operation_data()
\r
819 * to retrieve an operation context set by the start callback.
\r
821 * \param ssl The SSL connection instance. It should not be
\r
824 typedef void mbedtls_ssl_async_cancel_t( mbedtls_ssl_context *ssl );
\r
825 #endif /* MBEDTLS_SSL_ASYNC_PRIVATE */
\r
827 #if defined(MBEDTLS_KEY_EXCHANGE__WITH_CERT__ENABLED) && \
\r
828 !defined(MBEDTLS_SSL_KEEP_PEER_CERTIFICATE)
\r
829 #define MBEDTLS_SSL_PEER_CERT_DIGEST_MAX_LEN 48
\r
830 #if defined(MBEDTLS_SHA256_C)
\r
831 #define MBEDTLS_SSL_PEER_CERT_DIGEST_DFL_TYPE MBEDTLS_MD_SHA256
\r
832 #define MBEDTLS_SSL_PEER_CERT_DIGEST_DFL_LEN 32
\r
833 #elif defined(MBEDTLS_SHA512_C)
\r
834 #define MBEDTLS_SSL_PEER_CERT_DIGEST_DFL_TYPE MBEDTLS_MD_SHA384
\r
835 #define MBEDTLS_SSL_PEER_CERT_DIGEST_DFL_LEN 48
\r
836 #elif defined(MBEDTLS_SHA1_C)
\r
837 #define MBEDTLS_SSL_PEER_CERT_DIGEST_DFL_TYPE MBEDTLS_MD_SHA1
\r
838 #define MBEDTLS_SSL_PEER_CERT_DIGEST_DFL_LEN 20
\r
840 /* This is already checked in check_config.h, but be sure. */
\r
841 #error "Bad configuration - need SHA-1, SHA-256 or SHA-512 enabled to compute digest of peer CRT."
\r
843 #endif /* MBEDTLS_KEY_EXCHANGE__WITH_CERT__ENABLED &&
\r
844 !MBEDTLS_SSL_KEEP_PEER_CERTIFICATE */
\r
847 * This structure is used for storing current session data.
\r
849 struct mbedtls_ssl_session
\r
851 #if defined(MBEDTLS_HAVE_TIME)
\r
852 mbedtls_time_t start; /*!< starting time */
\r
854 int ciphersuite; /*!< chosen ciphersuite */
\r
855 int compression; /*!< chosen compression */
\r
856 size_t id_len; /*!< session id length */
\r
857 unsigned char id[32]; /*!< session identifier */
\r
858 unsigned char master[48]; /*!< the master secret */
\r
860 #if defined(MBEDTLS_X509_CRT_PARSE_C)
\r
861 #if defined(MBEDTLS_SSL_KEEP_PEER_CERTIFICATE)
\r
862 mbedtls_x509_crt *peer_cert; /*!< peer X.509 cert chain */
\r
863 #else /* MBEDTLS_SSL_KEEP_PEER_CERTIFICATE */
\r
864 /*! The digest of the peer's end-CRT. This must be kept to detect CRT
\r
865 * changes during renegotiation, mitigating the triple handshake attack. */
\r
866 unsigned char *peer_cert_digest;
\r
867 size_t peer_cert_digest_len;
\r
868 mbedtls_md_type_t peer_cert_digest_type;
\r
869 #endif /* !MBEDTLS_SSL_KEEP_PEER_CERTIFICATE */
\r
870 #endif /* MBEDTLS_X509_CRT_PARSE_C */
\r
871 uint32_t verify_result; /*!< verification result */
\r
873 #if defined(MBEDTLS_SSL_SESSION_TICKETS) && defined(MBEDTLS_SSL_CLI_C)
\r
874 unsigned char *ticket; /*!< RFC 5077 session ticket */
\r
875 size_t ticket_len; /*!< session ticket length */
\r
876 uint32_t ticket_lifetime; /*!< ticket lifetime hint */
\r
877 #endif /* MBEDTLS_SSL_SESSION_TICKETS && MBEDTLS_SSL_CLI_C */
\r
879 #if defined(MBEDTLS_SSL_MAX_FRAGMENT_LENGTH)
\r
880 unsigned char mfl_code; /*!< MaxFragmentLength negotiated by peer */
\r
881 #endif /* MBEDTLS_SSL_MAX_FRAGMENT_LENGTH */
\r
883 #if defined(MBEDTLS_SSL_TRUNCATED_HMAC)
\r
884 int trunc_hmac; /*!< flag for truncated hmac activation */
\r
885 #endif /* MBEDTLS_SSL_TRUNCATED_HMAC */
\r
887 #if defined(MBEDTLS_SSL_ENCRYPT_THEN_MAC)
\r
888 int encrypt_then_mac; /*!< flag for EtM activation */
\r
893 * SSL/TLS configuration to be shared between mbedtls_ssl_context structures.
\r
895 struct mbedtls_ssl_config
\r
897 /* Group items by size (largest first) to minimize padding overhead */
\r
903 const int *ciphersuite_list[4]; /*!< allowed ciphersuites per version */
\r
905 /** Callback for printing debug output */
\r
906 void (*f_dbg)(void *, int, const char *, int, const char *);
\r
907 void *p_dbg; /*!< context for the debug function */
\r
909 /** Callback for getting (pseudo-)random numbers */
\r
910 int (*f_rng)(void *, unsigned char *, size_t);
\r
911 void *p_rng; /*!< context for the RNG function */
\r
913 /** Callback to retrieve a session from the cache */
\r
914 int (*f_get_cache)(void *, mbedtls_ssl_session *);
\r
915 /** Callback to store a session into the cache */
\r
916 int (*f_set_cache)(void *, const mbedtls_ssl_session *);
\r
917 void *p_cache; /*!< context for cache callbacks */
\r
919 #if defined(MBEDTLS_SSL_SERVER_NAME_INDICATION)
\r
920 /** Callback for setting cert according to SNI extension */
\r
921 int (*f_sni)(void *, mbedtls_ssl_context *, const unsigned char *, size_t);
\r
922 void *p_sni; /*!< context for SNI callback */
\r
925 #if defined(MBEDTLS_X509_CRT_PARSE_C)
\r
926 /** Callback to customize X.509 certificate chain verification */
\r
927 int (*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *);
\r
928 void *p_vrfy; /*!< context for X.509 verify calllback */
\r
931 #if defined(MBEDTLS_KEY_EXCHANGE__SOME__PSK_ENABLED)
\r
932 /** Callback to retrieve PSK key from identity */
\r
933 int (*f_psk)(void *, mbedtls_ssl_context *, const unsigned char *, size_t);
\r
934 void *p_psk; /*!< context for PSK callback */
\r
937 #if defined(MBEDTLS_SSL_DTLS_HELLO_VERIFY) && defined(MBEDTLS_SSL_SRV_C)
\r
938 /** Callback to create & write a cookie for ClientHello veirifcation */
\r
939 int (*f_cookie_write)( void *, unsigned char **, unsigned char *,
\r
940 const unsigned char *, size_t );
\r
941 /** Callback to verify validity of a ClientHello cookie */
\r
942 int (*f_cookie_check)( void *, const unsigned char *, size_t,
\r
943 const unsigned char *, size_t );
\r
944 void *p_cookie; /*!< context for the cookie callbacks */
\r
947 #if defined(MBEDTLS_SSL_SESSION_TICKETS) && defined(MBEDTLS_SSL_SRV_C)
\r
948 /** Callback to create & write a session ticket */
\r
949 int (*f_ticket_write)( void *, const mbedtls_ssl_session *,
\r
950 unsigned char *, const unsigned char *, size_t *, uint32_t * );
\r
951 /** Callback to parse a session ticket into a session structure */
\r
952 int (*f_ticket_parse)( void *, mbedtls_ssl_session *, unsigned char *, size_t);
\r
953 void *p_ticket; /*!< context for the ticket callbacks */
\r
954 #endif /* MBEDTLS_SSL_SESSION_TICKETS && MBEDTLS_SSL_SRV_C */
\r
956 #if defined(MBEDTLS_SSL_EXPORT_KEYS)
\r
957 /** Callback to export key block and master secret */
\r
958 int (*f_export_keys)( void *, const unsigned char *,
\r
959 const unsigned char *, size_t, size_t, size_t );
\r
960 /** Callback to export key block, master secret,
\r
961 * tls_prf and random bytes. Should replace f_export_keys */
\r
962 int (*f_export_keys_ext)( void *, const unsigned char *,
\r
963 const unsigned char *, size_t, size_t, size_t,
\r
964 unsigned char[32], unsigned char[32], mbedtls_tls_prf_types );
\r
965 void *p_export_keys; /*!< context for key export callback */
\r
968 #if defined(MBEDTLS_SSL_DTLS_CONNECTION_ID)
\r
969 size_t cid_len; /*!< The length of CIDs for incoming DTLS records. */
\r
970 #endif /* MBEDTLS_SSL_DTLS_CONNECTION_ID */
\r
972 #if defined(MBEDTLS_X509_CRT_PARSE_C)
\r
973 const mbedtls_x509_crt_profile *cert_profile; /*!< verification profile */
\r
974 mbedtls_ssl_key_cert *key_cert; /*!< own certificate/key pair(s) */
\r
975 mbedtls_x509_crt *ca_chain; /*!< trusted CAs */
\r
976 mbedtls_x509_crl *ca_crl; /*!< trusted CAs CRLs */
\r
977 #if defined(MBEDTLS_X509_TRUSTED_CERTIFICATE_CALLBACK)
\r
978 mbedtls_x509_crt_ca_cb_t f_ca_cb;
\r
980 #endif /* MBEDTLS_X509_TRUSTED_CERTIFICATE_CALLBACK */
\r
981 #endif /* MBEDTLS_X509_CRT_PARSE_C */
\r
983 #if defined(MBEDTLS_SSL_ASYNC_PRIVATE)
\r
984 #if defined(MBEDTLS_X509_CRT_PARSE_C)
\r
985 mbedtls_ssl_async_sign_t *f_async_sign_start; /*!< start asynchronous signature operation */
\r
986 mbedtls_ssl_async_decrypt_t *f_async_decrypt_start; /*!< start asynchronous decryption operation */
\r
987 #endif /* MBEDTLS_X509_CRT_PARSE_C */
\r
988 mbedtls_ssl_async_resume_t *f_async_resume; /*!< resume asynchronous operation */
\r
989 mbedtls_ssl_async_cancel_t *f_async_cancel; /*!< cancel asynchronous operation */
\r
990 void *p_async_config_data; /*!< Configuration data set by mbedtls_ssl_conf_async_private_cb(). */
\r
991 #endif /* MBEDTLS_SSL_ASYNC_PRIVATE */
\r
993 #if defined(MBEDTLS_KEY_EXCHANGE__WITH_CERT__ENABLED)
\r
994 const int *sig_hashes; /*!< allowed signature hashes */
\r
997 #if defined(MBEDTLS_ECP_C)
\r
998 const mbedtls_ecp_group_id *curve_list; /*!< allowed curves */
\r
1001 #if defined(MBEDTLS_DHM_C)
\r
1002 mbedtls_mpi dhm_P; /*!< prime modulus for DHM */
\r
1003 mbedtls_mpi dhm_G; /*!< generator for DHM */
\r
1006 #if defined(MBEDTLS_KEY_EXCHANGE__SOME__PSK_ENABLED)
\r
1008 #if defined(MBEDTLS_USE_PSA_CRYPTO)
\r
1009 psa_key_handle_t psk_opaque; /*!< PSA key slot holding opaque PSK.
\r
1010 * This field should only be set via
\r
1011 * mbedtls_ssl_conf_psk_opaque().
\r
1012 * If either no PSK or a raw PSK have
\r
1013 * been configured, this has value \c 0. */
\r
1014 #endif /* MBEDTLS_USE_PSA_CRYPTO */
\r
1016 unsigned char *psk; /*!< The raw pre-shared key. This field should
\r
1017 * only be set via mbedtls_ssl_conf_psk().
\r
1018 * If either no PSK or an opaque PSK
\r
1019 * have been configured, this has value NULL. */
\r
1020 size_t psk_len; /*!< The length of the raw pre-shared key.
\r
1021 * This field should only be set via
\r
1022 * mbedtls_ssl_conf_psk().
\r
1023 * Its value is non-zero if and only if
\r
1024 * \c psk is not \c NULL. */
\r
1026 unsigned char *psk_identity; /*!< The PSK identity for PSK negotiation.
\r
1027 * This field should only be set via
\r
1028 * mbedtls_ssl_conf_psk().
\r
1029 * This is set if and only if either
\r
1030 * \c psk or \c psk_opaque are set. */
\r
1031 size_t psk_identity_len;/*!< The length of PSK identity.
\r
1032 * This field should only be set via
\r
1033 * mbedtls_ssl_conf_psk().
\r
1034 * Its value is non-zero if and only if
\r
1035 * \c psk is not \c NULL or \c psk_opaque
\r
1037 #endif /* MBEDTLS_KEY_EXCHANGE__SOME__PSK_ENABLED */
\r
1039 #if defined(MBEDTLS_SSL_ALPN)
\r
1040 const char **alpn_list; /*!< ordered list of protocols */
\r
1044 * Numerical settings (int then char)
\r
1047 uint32_t read_timeout; /*!< timeout for mbedtls_ssl_read (ms) */
\r
1049 #if defined(MBEDTLS_SSL_PROTO_DTLS)
\r
1050 uint32_t hs_timeout_min; /*!< initial value of the handshake
\r
1051 retransmission timeout (ms) */
\r
1052 uint32_t hs_timeout_max; /*!< maximum value of the handshake
\r
1053 retransmission timeout (ms) */
\r
1056 #if defined(MBEDTLS_SSL_RENEGOTIATION)
\r
1057 int renego_max_records; /*!< grace period for renegotiation */
\r
1058 unsigned char renego_period[8]; /*!< value of the record counters
\r
1059 that triggers renegotiation */
\r
1062 #if defined(MBEDTLS_SSL_DTLS_BADMAC_LIMIT)
\r
1063 unsigned int badmac_limit; /*!< limit of records with a bad MAC */
\r
1066 #if defined(MBEDTLS_DHM_C) && defined(MBEDTLS_SSL_CLI_C)
\r
1067 unsigned int dhm_min_bitlen; /*!< min. bit length of the DHM prime */
\r
1070 unsigned char max_major_ver; /*!< max. major version used */
\r
1071 unsigned char max_minor_ver; /*!< max. minor version used */
\r
1072 unsigned char min_major_ver; /*!< min. major version used */
\r
1073 unsigned char min_minor_ver; /*!< min. minor version used */
\r
1076 * Flags (bitfields)
\r
1079 unsigned int endpoint : 1; /*!< 0: client, 1: server */
\r
1080 unsigned int transport : 1; /*!< stream (TLS) or datagram (DTLS) */
\r
1081 unsigned int authmode : 2; /*!< MBEDTLS_SSL_VERIFY_XXX */
\r
1082 /* needed even with renego disabled for LEGACY_BREAK_HANDSHAKE */
\r
1083 unsigned int allow_legacy_renegotiation : 2 ; /*!< MBEDTLS_LEGACY_XXX */
\r
1084 #if defined(MBEDTLS_ARC4_C)
\r
1085 unsigned int arc4_disabled : 1; /*!< blacklist RC4 ciphersuites? */
\r
1087 #if defined(MBEDTLS_SSL_MAX_FRAGMENT_LENGTH)
\r
1088 unsigned int mfl_code : 3; /*!< desired fragment length */
\r
1090 #if defined(MBEDTLS_SSL_ENCRYPT_THEN_MAC)
\r
1091 unsigned int encrypt_then_mac : 1 ; /*!< negotiate encrypt-then-mac? */
\r
1093 #if defined(MBEDTLS_SSL_EXTENDED_MASTER_SECRET)
\r
1094 unsigned int extended_ms : 1; /*!< negotiate extended master secret? */
\r
1096 #if defined(MBEDTLS_SSL_DTLS_ANTI_REPLAY)
\r
1097 unsigned int anti_replay : 1; /*!< detect and prevent replay? */
\r
1099 #if defined(MBEDTLS_SSL_CBC_RECORD_SPLITTING)
\r
1100 unsigned int cbc_record_splitting : 1; /*!< do cbc record splitting */
\r
1102 #if defined(MBEDTLS_SSL_RENEGOTIATION)
\r
1103 unsigned int disable_renegotiation : 1; /*!< disable renegotiation? */
\r
1105 #if defined(MBEDTLS_SSL_TRUNCATED_HMAC)
\r
1106 unsigned int trunc_hmac : 1; /*!< negotiate truncated hmac? */
\r
1108 #if defined(MBEDTLS_SSL_SESSION_TICKETS)
\r
1109 unsigned int session_tickets : 1; /*!< use session tickets? */
\r
1111 #if defined(MBEDTLS_SSL_FALLBACK_SCSV) && defined(MBEDTLS_SSL_CLI_C)
\r
1112 unsigned int fallback : 1; /*!< is this a fallback? */
\r
1114 #if defined(MBEDTLS_SSL_SRV_C)
\r
1115 unsigned int cert_req_ca_list : 1; /*!< enable sending CA list in
\r
1116 Certificate Request messages? */
\r
1118 #if defined(MBEDTLS_SSL_DTLS_CONNECTION_ID)
\r
1119 unsigned int ignore_unexpected_cid : 1; /*!< Determines whether DTLS
\r
1120 * record with unexpected CID
\r
1121 * should lead to failure. */
\r
1122 #endif /* MBEDTLS_SSL_DTLS_CONNECTION_ID */
\r
1126 struct mbedtls_ssl_context
\r
1128 const mbedtls_ssl_config *conf; /*!< configuration information */
\r
1133 int state; /*!< SSL handshake: current state */
\r
1134 #if defined(MBEDTLS_SSL_RENEGOTIATION)
\r
1135 int renego_status; /*!< Initial, in progress, pending? */
\r
1136 int renego_records_seen; /*!< Records since renego request, or with DTLS,
\r
1137 number of retransmissions of request if
\r
1138 renego_max_records is < 0 */
\r
1139 #endif /* MBEDTLS_SSL_RENEGOTIATION */
\r
1141 int major_ver; /*!< equal to MBEDTLS_SSL_MAJOR_VERSION_3 */
\r
1142 int minor_ver; /*!< either 0 (SSL3) or 1 (TLS1.0) */
\r
1144 #if defined(MBEDTLS_SSL_DTLS_BADMAC_LIMIT)
\r
1145 unsigned badmac_seen; /*!< records with a bad MAC received */
\r
1146 #endif /* MBEDTLS_SSL_DTLS_BADMAC_LIMIT */
\r
1148 #if defined(MBEDTLS_X509_CRT_PARSE_C)
\r
1149 /** Callback to customize X.509 certificate chain verification */
\r
1150 int (*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *);
\r
1151 void *p_vrfy; /*!< context for X.509 verify callback */
\r
1154 mbedtls_ssl_send_t *f_send; /*!< Callback for network send */
\r
1155 mbedtls_ssl_recv_t *f_recv; /*!< Callback for network receive */
\r
1156 mbedtls_ssl_recv_timeout_t *f_recv_timeout;
\r
1157 /*!< Callback for network receive with timeout */
\r
1159 void *p_bio; /*!< context for I/O operations */
\r
1164 mbedtls_ssl_session *session_in; /*!< current session data (in) */
\r
1165 mbedtls_ssl_session *session_out; /*!< current session data (out) */
\r
1166 mbedtls_ssl_session *session; /*!< negotiated session data */
\r
1167 mbedtls_ssl_session *session_negotiate; /*!< session data in negotiation */
\r
1169 mbedtls_ssl_handshake_params *handshake; /*!< params required only during
\r
1170 the handshake process */
\r
1173 * Record layer transformations
\r
1175 mbedtls_ssl_transform *transform_in; /*!< current transform params (in) */
\r
1176 mbedtls_ssl_transform *transform_out; /*!< current transform params (in) */
\r
1177 mbedtls_ssl_transform *transform; /*!< negotiated transform params */
\r
1178 mbedtls_ssl_transform *transform_negotiate; /*!< transform params in negotiation */
\r
1183 void *p_timer; /*!< context for the timer callbacks */
\r
1185 mbedtls_ssl_set_timer_t *f_set_timer; /*!< set timer callback */
\r
1186 mbedtls_ssl_get_timer_t *f_get_timer; /*!< get timer callback */
\r
1189 * Record layer (incoming data)
\r
1191 unsigned char *in_buf; /*!< input buffer */
\r
1192 unsigned char *in_ctr; /*!< 64-bit incoming message counter
\r
1193 TLS: maintained by us
\r
1194 DTLS: read from peer */
\r
1195 unsigned char *in_hdr; /*!< start of record header */
\r
1196 #if defined(MBEDTLS_SSL_DTLS_CONNECTION_ID)
\r
1197 unsigned char *in_cid; /*!< The start of the CID;
\r
1198 * (the end is marked by in_len). */
\r
1199 #endif /* MBEDTLS_SSL_DTLS_CONNECTION_ID */
\r
1200 unsigned char *in_len; /*!< two-bytes message length field */
\r
1201 unsigned char *in_iv; /*!< ivlen-byte IV */
\r
1202 unsigned char *in_msg; /*!< message contents (in_iv+ivlen) */
\r
1203 unsigned char *in_offt; /*!< read offset in application data */
\r
1205 int in_msgtype; /*!< record header: message type */
\r
1206 size_t in_msglen; /*!< record header: message length */
\r
1207 size_t in_left; /*!< amount of data read so far */
\r
1208 #if defined(MBEDTLS_SSL_PROTO_DTLS)
\r
1209 uint16_t in_epoch; /*!< DTLS epoch for incoming records */
\r
1210 size_t next_record_offset; /*!< offset of the next record in datagram
\r
1211 (equal to in_left if none) */
\r
1212 #endif /* MBEDTLS_SSL_PROTO_DTLS */
\r
1213 #if defined(MBEDTLS_SSL_DTLS_ANTI_REPLAY)
\r
1214 uint64_t in_window_top; /*!< last validated record seq_num */
\r
1215 uint64_t in_window; /*!< bitmask for replay detection */
\r
1216 #endif /* MBEDTLS_SSL_DTLS_ANTI_REPLAY */
\r
1218 size_t in_hslen; /*!< current handshake message length,
\r
1219 including the handshake header */
\r
1220 int nb_zero; /*!< # of 0-length encrypted messages */
\r
1222 int keep_current_message; /*!< drop or reuse current message
\r
1223 on next call to record layer? */
\r
1225 #if defined(MBEDTLS_SSL_PROTO_DTLS)
\r
1226 uint8_t disable_datagram_packing; /*!< Disable packing multiple records
\r
1227 * within a single datagram. */
\r
1228 #endif /* MBEDTLS_SSL_PROTO_DTLS */
\r
1231 * Record layer (outgoing data)
\r
1233 unsigned char *out_buf; /*!< output buffer */
\r
1234 unsigned char *out_ctr; /*!< 64-bit outgoing message counter */
\r
1235 unsigned char *out_hdr; /*!< start of record header */
\r
1236 #if defined(MBEDTLS_SSL_DTLS_CONNECTION_ID)
\r
1237 unsigned char *out_cid; /*!< The start of the CID;
\r
1238 * (the end is marked by in_len). */
\r
1239 #endif /* MBEDTLS_SSL_DTLS_CONNECTION_ID */
\r
1240 unsigned char *out_len; /*!< two-bytes message length field */
\r
1241 unsigned char *out_iv; /*!< ivlen-byte IV */
\r
1242 unsigned char *out_msg; /*!< message contents (out_iv+ivlen) */
\r
1244 int out_msgtype; /*!< record header: message type */
\r
1245 size_t out_msglen; /*!< record header: message length */
\r
1246 size_t out_left; /*!< amount of data not yet written */
\r
1248 unsigned char cur_out_ctr[8]; /*!< Outgoing record sequence number. */
\r
1250 #if defined(MBEDTLS_SSL_PROTO_DTLS)
\r
1251 uint16_t mtu; /*!< path mtu, used to fragment outgoing messages */
\r
1252 #endif /* MBEDTLS_SSL_PROTO_DTLS */
\r
1254 #if defined(MBEDTLS_ZLIB_SUPPORT)
\r
1255 unsigned char *compress_buf; /*!< zlib data buffer */
\r
1256 #endif /* MBEDTLS_ZLIB_SUPPORT */
\r
1257 #if defined(MBEDTLS_SSL_CBC_RECORD_SPLITTING)
\r
1258 signed char split_done; /*!< current record already splitted? */
\r
1259 #endif /* MBEDTLS_SSL_CBC_RECORD_SPLITTING */
\r
1264 int client_auth; /*!< flag for client auth. */
\r
1269 #if defined(MBEDTLS_X509_CRT_PARSE_C)
\r
1270 char *hostname; /*!< expected peer CN for verification
\r
1271 (and SNI if available) */
\r
1272 #endif /* MBEDTLS_X509_CRT_PARSE_C */
\r
1274 #if defined(MBEDTLS_SSL_ALPN)
\r
1275 const char *alpn_chosen; /*!< negotiated protocol */
\r
1276 #endif /* MBEDTLS_SSL_ALPN */
\r
1279 * Information for DTLS hello verify
\r
1281 #if defined(MBEDTLS_SSL_DTLS_HELLO_VERIFY) && defined(MBEDTLS_SSL_SRV_C)
\r
1282 unsigned char *cli_id; /*!< transport-level ID of the client */
\r
1283 size_t cli_id_len; /*!< length of cli_id */
\r
1284 #endif /* MBEDTLS_SSL_DTLS_HELLO_VERIFY && MBEDTLS_SSL_SRV_C */
\r
1287 * Secure renegotiation
\r
1289 /* needed to know when to send extension on server */
\r
1290 int secure_renegotiation; /*!< does peer support legacy or
\r
1291 secure renegotiation */
\r
1292 #if defined(MBEDTLS_SSL_RENEGOTIATION)
\r
1293 size_t verify_data_len; /*!< length of verify data stored */
\r
1294 char own_verify_data[MBEDTLS_SSL_VERIFY_DATA_MAX_LEN]; /*!< previous handshake verify data */
\r
1295 char peer_verify_data[MBEDTLS_SSL_VERIFY_DATA_MAX_LEN]; /*!< previous handshake verify data */
\r
1296 #endif /* MBEDTLS_SSL_RENEGOTIATION */
\r
1298 #if defined(MBEDTLS_SSL_DTLS_CONNECTION_ID)
\r
1299 /* CID configuration to use in subsequent handshakes. */
\r
1301 /*! The next incoming CID, chosen by the user and applying to
\r
1302 * all subsequent handshakes. This may be different from the
\r
1303 * CID currently used in case the user has re-configured the CID
\r
1304 * after an initial handshake. */
\r
1305 unsigned char own_cid[ MBEDTLS_SSL_CID_IN_LEN_MAX ];
\r
1306 uint8_t own_cid_len; /*!< The length of \c own_cid. */
\r
1307 uint8_t negotiate_cid; /*!< This indicates whether the CID extension should
\r
1308 * be negotiated in the next handshake or not.
\r
1309 * Possible values are #MBEDTLS_SSL_CID_ENABLED
\r
1310 * and #MBEDTLS_SSL_CID_DISABLED. */
\r
1311 #endif /* MBEDTLS_SSL_DTLS_CONNECTION_ID */
\r
1314 #if defined(MBEDTLS_SSL_HW_RECORD_ACCEL)
\r
1316 #define MBEDTLS_SSL_CHANNEL_OUTBOUND 0
\r
1317 #define MBEDTLS_SSL_CHANNEL_INBOUND 1
\r
1319 extern int (*mbedtls_ssl_hw_record_init)(mbedtls_ssl_context *ssl,
\r
1320 const unsigned char *key_enc, const unsigned char *key_dec,
\r
1322 const unsigned char *iv_enc, const unsigned char *iv_dec,
\r
1324 const unsigned char *mac_enc, const unsigned char *mac_dec,
\r
1326 extern int (*mbedtls_ssl_hw_record_activate)(mbedtls_ssl_context *ssl, int direction);
\r
1327 extern int (*mbedtls_ssl_hw_record_reset)(mbedtls_ssl_context *ssl);
\r
1328 extern int (*mbedtls_ssl_hw_record_write)(mbedtls_ssl_context *ssl);
\r
1329 extern int (*mbedtls_ssl_hw_record_read)(mbedtls_ssl_context *ssl);
\r
1330 extern int (*mbedtls_ssl_hw_record_finish)(mbedtls_ssl_context *ssl);
\r
1331 #endif /* MBEDTLS_SSL_HW_RECORD_ACCEL */
\r
1334 * \brief Return the name of the ciphersuite associated with the
\r
1337 * \param ciphersuite_id SSL ciphersuite ID
\r
1339 * \return a string containing the ciphersuite name
\r
1341 const char *mbedtls_ssl_get_ciphersuite_name( const int ciphersuite_id );
\r
1344 * \brief Return the ID of the ciphersuite associated with the
\r
1347 * \param ciphersuite_name SSL ciphersuite name
\r
1349 * \return the ID with the ciphersuite or 0 if not found
\r
1351 int mbedtls_ssl_get_ciphersuite_id( const char *ciphersuite_name );
\r
1354 * \brief Initialize an SSL context
\r
1355 * Just makes the context ready for mbedtls_ssl_setup() or
\r
1356 * mbedtls_ssl_free()
\r
1358 * \param ssl SSL context
\r
1360 void mbedtls_ssl_init( mbedtls_ssl_context *ssl );
\r
1363 * \brief Set up an SSL context for use
\r
1365 * \note No copy of the configuration context is made, it can be
\r
1366 * shared by many mbedtls_ssl_context structures.
\r
1368 * \warning The conf structure will be accessed during the session.
\r
1369 * It must not be modified or freed as long as the session
\r
1372 * \warning This function must be called exactly once per context.
\r
1373 * Calling mbedtls_ssl_setup again is not supported, even
\r
1374 * if no session is active.
\r
1376 * \param ssl SSL context
\r
1377 * \param conf SSL configuration to use
\r
1379 * \return 0 if successful, or MBEDTLS_ERR_SSL_ALLOC_FAILED if
\r
1380 * memory allocation failed
\r
1382 int mbedtls_ssl_setup( mbedtls_ssl_context *ssl,
\r
1383 const mbedtls_ssl_config *conf );
\r
1386 * \brief Reset an already initialized SSL context for re-use
\r
1387 * while retaining application-set variables, function
\r
1388 * pointers and data.
\r
1390 * \param ssl SSL context
\r
1391 * \return 0 if successful, or MBEDTLS_ERR_SSL_ALLOC_FAILED,
\r
1392 MBEDTLS_ERR_SSL_HW_ACCEL_FAILED or
\r
1393 * MBEDTLS_ERR_SSL_COMPRESSION_FAILED
\r
1395 int mbedtls_ssl_session_reset( mbedtls_ssl_context *ssl );
\r
1398 * \brief Set the current endpoint type
\r
1400 * \param conf SSL configuration
\r
1401 * \param endpoint must be MBEDTLS_SSL_IS_CLIENT or MBEDTLS_SSL_IS_SERVER
\r
1403 void mbedtls_ssl_conf_endpoint( mbedtls_ssl_config *conf, int endpoint );
\r
1406 * \brief Set the transport type (TLS or DTLS).
\r
1409 * \note For DTLS, you must either provide a recv callback that
\r
1410 * doesn't block, or one that handles timeouts, see
\r
1411 * \c mbedtls_ssl_set_bio(). You also need to provide timer
\r
1412 * callbacks with \c mbedtls_ssl_set_timer_cb().
\r
1414 * \param conf SSL configuration
\r
1415 * \param transport transport type:
\r
1416 * MBEDTLS_SSL_TRANSPORT_STREAM for TLS,
\r
1417 * MBEDTLS_SSL_TRANSPORT_DATAGRAM for DTLS.
\r
1419 void mbedtls_ssl_conf_transport( mbedtls_ssl_config *conf, int transport );
\r
1422 * \brief Set the certificate verification mode
\r
1423 * Default: NONE on server, REQUIRED on client
\r
1425 * \param conf SSL configuration
\r
1426 * \param authmode can be:
\r
1428 * MBEDTLS_SSL_VERIFY_NONE: peer certificate is not checked
\r
1429 * (default on server)
\r
1430 * (insecure on client)
\r
1432 * MBEDTLS_SSL_VERIFY_OPTIONAL: peer certificate is checked, however the
\r
1433 * handshake continues even if verification failed;
\r
1434 * mbedtls_ssl_get_verify_result() can be called after the
\r
1435 * handshake is complete.
\r
1437 * MBEDTLS_SSL_VERIFY_REQUIRED: peer *must* present a valid certificate,
\r
1438 * handshake is aborted if verification failed.
\r
1439 * (default on client)
\r
1441 * \note On client, MBEDTLS_SSL_VERIFY_REQUIRED is the recommended mode.
\r
1442 * With MBEDTLS_SSL_VERIFY_OPTIONAL, the user needs to call mbedtls_ssl_get_verify_result() at
\r
1443 * the right time(s), which may not be obvious, while REQUIRED always perform
\r
1444 * the verification as soon as possible. For example, REQUIRED was protecting
\r
1445 * against the "triple handshake" attack even before it was found.
\r
1447 void mbedtls_ssl_conf_authmode( mbedtls_ssl_config *conf, int authmode );
\r
1449 #if defined(MBEDTLS_X509_CRT_PARSE_C)
\r
1451 * \brief Set the verification callback (Optional).
\r
1453 * If set, the provided verify callback is called for each
\r
1454 * certificate in the peer's CRT chain, including the trusted
\r
1455 * root. For more information, please see the documentation of
\r
1456 * \c mbedtls_x509_crt_verify().
\r
1458 * \note For per context callbacks and contexts, please use
\r
1459 * mbedtls_ssl_set_verify() instead.
\r
1461 * \param conf The SSL configuration to use.
\r
1462 * \param f_vrfy The verification callback to use during CRT verification.
\r
1463 * \param p_vrfy The opaque context to be passed to the callback.
\r
1465 void mbedtls_ssl_conf_verify( mbedtls_ssl_config *conf,
\r
1466 int (*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *),
\r
1468 #endif /* MBEDTLS_X509_CRT_PARSE_C */
\r
1471 * \brief Set the random number generator callback
\r
1473 * \param conf SSL configuration
\r
1474 * \param f_rng RNG function
\r
1475 * \param p_rng RNG parameter
\r
1477 void mbedtls_ssl_conf_rng( mbedtls_ssl_config *conf,
\r
1478 int (*f_rng)(void *, unsigned char *, size_t),
\r
1482 * \brief Set the debug callback
\r
1484 * The callback has the following argument:
\r
1485 * void * opaque context for the callback
\r
1487 * const char * file name
\r
1489 * const char * message
\r
1491 * \param conf SSL configuration
\r
1492 * \param f_dbg debug function
\r
1493 * \param p_dbg debug parameter
\r
1495 void mbedtls_ssl_conf_dbg( mbedtls_ssl_config *conf,
\r
1496 void (*f_dbg)(void *, int, const char *, int, const char *),
\r
1500 * \brief Set the underlying BIO callbacks for write, read and
\r
1501 * read-with-timeout.
\r
1503 * \param ssl SSL context
\r
1504 * \param p_bio parameter (context) shared by BIO callbacks
\r
1505 * \param f_send write callback
\r
1506 * \param f_recv read callback
\r
1507 * \param f_recv_timeout blocking read callback with timeout.
\r
1509 * \note One of f_recv or f_recv_timeout can be NULL, in which case
\r
1510 * the other is used. If both are non-NULL, f_recv_timeout is
\r
1511 * used and f_recv is ignored (as if it were NULL).
\r
1513 * \note The two most common use cases are:
\r
1514 * - non-blocking I/O, f_recv != NULL, f_recv_timeout == NULL
\r
1515 * - blocking I/O, f_recv == NULL, f_recv_timout != NULL
\r
1517 * \note For DTLS, you need to provide either a non-NULL
\r
1518 * f_recv_timeout callback, or a f_recv that doesn't block.
\r
1520 * \note See the documentations of \c mbedtls_ssl_sent_t,
\r
1521 * \c mbedtls_ssl_recv_t and \c mbedtls_ssl_recv_timeout_t for
\r
1522 * the conventions those callbacks must follow.
\r
1524 * \note On some platforms, net_sockets.c provides
\r
1525 * \c mbedtls_net_send(), \c mbedtls_net_recv() and
\r
1526 * \c mbedtls_net_recv_timeout() that are suitable to be used
\r
1529 void mbedtls_ssl_set_bio( mbedtls_ssl_context *ssl,
\r
1531 mbedtls_ssl_send_t *f_send,
\r
1532 mbedtls_ssl_recv_t *f_recv,
\r
1533 mbedtls_ssl_recv_timeout_t *f_recv_timeout );
\r
1535 #if defined(MBEDTLS_SSL_PROTO_DTLS)
\r
1537 #if defined(MBEDTLS_SSL_DTLS_CONNECTION_ID)
\r
1541 * \brief Configure the use of the Connection ID (CID)
\r
1542 * extension in the next handshake.
\r
1544 * Reference: draft-ietf-tls-dtls-connection-id-05
\r
1545 * https://tools.ietf.org/html/draft-ietf-tls-dtls-connection-id-05
\r
1547 * The DTLS CID extension allows the reliable association of
\r
1548 * DTLS records to DTLS connections across changes in the
\r
1549 * underlying transport (changed IP and Port metadata) by
\r
1550 * adding explicit connection identifiers (CIDs) to the
\r
1551 * headers of encrypted DTLS records. The desired CIDs are
\r
1552 * configured by the application layer and are exchanged in
\r
1553 * new `ClientHello` / `ServerHello` extensions during the
\r
1554 * handshake, where each side indicates the CID it wants the
\r
1555 * peer to use when writing encrypted messages. The CIDs are
\r
1556 * put to use once records get encrypted: the stack discards
\r
1557 * any incoming records that don't include the configured CID
\r
1558 * in their header, and adds the peer's requested CID to the
\r
1559 * headers of outgoing messages.
\r
1561 * This API enables or disables the use of the CID extension
\r
1562 * in the next handshake and sets the value of the CID to
\r
1563 * be used for incoming messages.
\r
1565 * \param ssl The SSL context to configure. This must be initialized.
\r
1566 * \param enable This value determines whether the CID extension should
\r
1567 * be used or not. Possible values are:
\r
1568 * - MBEDTLS_SSL_CID_ENABLED to enable the use of the CID.
\r
1569 * - MBEDTLS_SSL_CID_DISABLED (default) to disable the use
\r
1571 * \param own_cid The address of the readable buffer holding the CID we want
\r
1572 * the peer to use when sending encrypted messages to us.
\r
1573 * This may be \c NULL if \p own_cid_len is \c 0.
\r
1574 * This parameter is unused if \p enabled is set to
\r
1575 * MBEDTLS_SSL_CID_DISABLED.
\r
1576 * \param own_cid_len The length of \p own_cid.
\r
1577 * This parameter is unused if \p enabled is set to
\r
1578 * MBEDTLS_SSL_CID_DISABLED.
\r
1580 * \note The value of \p own_cid_len must match the value of the
\r
1581 * \c len parameter passed to mbedtls_ssl_conf_cid()
\r
1582 * when configuring the ::mbedtls_ssl_config that \p ssl
\r
1585 * \note This CID configuration applies to subsequent handshakes
\r
1586 * performed on the SSL context \p ssl, but does not trigger
\r
1587 * one. You still have to call `mbedtls_ssl_handshake()`
\r
1588 * (for the initial handshake) or `mbedtls_ssl_renegotiate()`
\r
1589 * (for a renegotiation handshake) explicitly after a
\r
1590 * successful call to this function to run the handshake.
\r
1592 * \note This call cannot guarantee that the use of the CID
\r
1593 * will be successfully negotiated in the next handshake,
\r
1594 * because the peer might not support it. Specifically:
\r
1595 * - On the Client, enabling the use of the CID through
\r
1596 * this call implies that the `ClientHello` in the next
\r
1597 * handshake will include the CID extension, thereby
\r
1598 * offering the use of the CID to the server. Only if
\r
1599 * the `ServerHello` contains the CID extension, too,
\r
1600 * the CID extension will actually be put to use.
\r
1601 * - On the Server, enabling the use of the CID through
\r
1602 * this call implies that that the server will look for
\r
1603 * the CID extension in a `ClientHello` from the client,
\r
1604 * and, if present, reply with a CID extension in its
\r
1607 * \note To check whether the use of the CID was negotiated
\r
1608 * after the subsequent handshake has completed, please
\r
1609 * use the API mbedtls_ssl_get_peer_cid().
\r
1611 * \warning If the use of the CID extension is enabled in this call
\r
1612 * and the subsequent handshake negotiates its use, Mbed TLS
\r
1613 * will silently drop every packet whose CID does not match
\r
1614 * the CID configured in \p own_cid. It is the responsibility
\r
1615 * of the user to adapt the underlying transport to take care
\r
1616 * of CID-based demultiplexing before handing datagrams to
\r
1619 * \return \c 0 on success. In this case, the CID configuration
\r
1620 * applies to the next handshake.
\r
1621 * \return A negative error code on failure.
\r
1623 int mbedtls_ssl_set_cid( mbedtls_ssl_context *ssl,
\r
1625 unsigned char const *own_cid,
\r
1626 size_t own_cid_len );
\r
1629 * \brief Get information about the use of the CID extension
\r
1630 * in the current connection.
\r
1632 * \param ssl The SSL context to query.
\r
1633 * \param enabled The address at which to store whether the CID extension
\r
1634 * is currently in use or not. If the CID is in use,
\r
1635 * `*enabled` is set to MBEDTLS_SSL_CID_ENABLED;
\r
1636 * otherwise, it is set to MBEDTLS_SSL_CID_DISABLED.
\r
1637 * \param peer_cid The address of the buffer in which to store the CID
\r
1638 * chosen by the peer (if the CID extension is used).
\r
1639 * This may be \c NULL in case the value of peer CID
\r
1640 * isn't needed. If it is not \c NULL, \p peer_cid_len
\r
1641 * must not be \c NULL.
\r
1642 * \param peer_cid_len The address at which to store the size of the CID
\r
1643 * chosen by the peer (if the CID extension is used).
\r
1644 * This is also the number of Bytes in \p peer_cid that
\r
1645 * have been written.
\r
1646 * This may be \c NULL in case the length of the peer CID
\r
1647 * isn't needed. If it is \c NULL, \p peer_cid must be
\r
1650 * \note This applies to the state of the CID negotiated in
\r
1651 * the last complete handshake. If a handshake is in
\r
1652 * progress, this function will attempt to complete
\r
1653 * the handshake first.
\r
1655 * \note If CID extensions have been exchanged but both client
\r
1656 * and server chose to use an empty CID, this function
\r
1657 * sets `*enabled` to #MBEDTLS_SSL_CID_DISABLED
\r
1658 * (the rationale for this is that the resulting
\r
1659 * communication is the same as if the CID extensions
\r
1660 * hadn't been used).
\r
1662 * \return \c 0 on success.
\r
1663 * \return A negative error code on failure.
\r
1665 int mbedtls_ssl_get_peer_cid( mbedtls_ssl_context *ssl,
\r
1667 unsigned char peer_cid[ MBEDTLS_SSL_CID_OUT_LEN_MAX ],
\r
1668 size_t *peer_cid_len );
\r
1670 #endif /* MBEDTLS_SSL_DTLS_CONNECTION_ID */
\r
1673 * \brief Set the Maximum Tranport Unit (MTU).
\r
1674 * Special value: 0 means unset (no limit).
\r
1675 * This represents the maximum size of a datagram payload
\r
1676 * handled by the transport layer (usually UDP) as determined
\r
1677 * by the network link and stack. In practice, this controls
\r
1678 * the maximum size datagram the DTLS layer will pass to the
\r
1679 * \c f_send() callback set using \c mbedtls_ssl_set_bio().
\r
1681 * \note The limit on datagram size is converted to a limit on
\r
1682 * record payload by subtracting the current overhead of
\r
1683 * encapsulation and encryption/authentication if any.
\r
1685 * \note This can be called at any point during the connection, for
\r
1686 * example when a Path Maximum Transfer Unit (PMTU)
\r
1687 * estimate becomes available from other sources,
\r
1688 * such as lower (or higher) protocol layers.
\r
1690 * \note This setting only controls the size of the packets we send,
\r
1691 * and does not restrict the size of the datagrams we're
\r
1692 * willing to receive. Client-side, you can request the
\r
1693 * server to use smaller records with \c
\r
1694 * mbedtls_ssl_conf_max_frag_len().
\r
1696 * \note If both a MTU and a maximum fragment length have been
\r
1697 * configured (or negotiated with the peer), the resulting
\r
1698 * lower limit on record payload (see first note) is used.
\r
1700 * \note This can only be used to decrease the maximum size
\r
1701 * of datagrams (hence records, see first note) sent. It
\r
1702 * cannot be used to increase the maximum size of records over
\r
1703 * the limit set by #MBEDTLS_SSL_OUT_CONTENT_LEN.
\r
1705 * \note Values lower than the current record layer expansion will
\r
1706 * result in an error when trying to send data.
\r
1708 * \note Using record compression together with a non-zero MTU value
\r
1709 * will result in an error when trying to send data.
\r
1711 * \param ssl SSL context
\r
1712 * \param mtu Value of the path MTU in bytes
\r
1714 void mbedtls_ssl_set_mtu( mbedtls_ssl_context *ssl, uint16_t mtu );
\r
1715 #endif /* MBEDTLS_SSL_PROTO_DTLS */
\r
1717 #if defined(MBEDTLS_X509_CRT_PARSE_C)
\r
1719 * \brief Set a connection-specific verification callback (optional).
\r
1721 * If set, the provided verify callback is called for each
\r
1722 * certificate in the peer's CRT chain, including the trusted
\r
1723 * root. For more information, please see the documentation of
\r
1724 * \c mbedtls_x509_crt_verify().
\r
1726 * \note This call is analogous to mbedtls_ssl_conf_verify() but
\r
1727 * binds the verification callback and context to an SSL context
\r
1728 * as opposed to an SSL configuration.
\r
1729 * If mbedtls_ssl_conf_verify() and mbedtls_ssl_set_verify()
\r
1730 * are both used, mbedtls_ssl_set_verify() takes precedence.
\r
1732 * \param ssl The SSL context to use.
\r
1733 * \param f_vrfy The verification callback to use during CRT verification.
\r
1734 * \param p_vrfy The opaque context to be passed to the callback.
\r
1736 void mbedtls_ssl_set_verify( mbedtls_ssl_context *ssl,
\r
1737 int (*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *),
\r
1739 #endif /* MBEDTLS_X509_CRT_PARSE_C */
\r
1742 * \brief Set the timeout period for mbedtls_ssl_read()
\r
1743 * (Default: no timeout.)
\r
1745 * \param conf SSL configuration context
\r
1746 * \param timeout Timeout value in milliseconds.
\r
1747 * Use 0 for no timeout (default).
\r
1749 * \note With blocking I/O, this will only work if a non-NULL
\r
1750 * \c f_recv_timeout was set with \c mbedtls_ssl_set_bio().
\r
1751 * With non-blocking I/O, this will only work if timer
\r
1752 * callbacks were set with \c mbedtls_ssl_set_timer_cb().
\r
1754 * \note With non-blocking I/O, you may also skip this function
\r
1755 * altogether and handle timeouts at the application layer.
\r
1757 void mbedtls_ssl_conf_read_timeout( mbedtls_ssl_config *conf, uint32_t timeout );
\r
1760 * \brief Set the timer callbacks (Mandatory for DTLS.)
\r
1762 * \param ssl SSL context
\r
1763 * \param p_timer parameter (context) shared by timer callbacks
\r
1764 * \param f_set_timer set timer callback
\r
1765 * \param f_get_timer get timer callback. Must return:
\r
1767 * \note See the documentation of \c mbedtls_ssl_set_timer_t and
\r
1768 * \c mbedtls_ssl_get_timer_t for the conventions this pair of
\r
1769 * callbacks must follow.
\r
1771 * \note On some platforms, timing.c provides
\r
1772 * \c mbedtls_timing_set_delay() and
\r
1773 * \c mbedtls_timing_get_delay() that are suitable for using
\r
1774 * here, except if using an event-driven style.
\r
1776 * \note See also the "DTLS tutorial" article in our knowledge base.
\r
1777 * https://tls.mbed.org/kb/how-to/dtls-tutorial
\r
1779 void mbedtls_ssl_set_timer_cb( mbedtls_ssl_context *ssl,
\r
1781 mbedtls_ssl_set_timer_t *f_set_timer,
\r
1782 mbedtls_ssl_get_timer_t *f_get_timer );
\r
1785 * \brief Callback type: generate and write session ticket
\r
1787 * \note This describes what a callback implementation should do.
\r
1788 * This callback should generate an encrypted and
\r
1789 * authenticated ticket for the session and write it to the
\r
1790 * output buffer. Here, ticket means the opaque ticket part
\r
1791 * of the NewSessionTicket structure of RFC 5077.
\r
1793 * \param p_ticket Context for the callback
\r
1794 * \param session SSL session to be written in the ticket
\r
1795 * \param start Start of the output buffer
\r
1796 * \param end End of the output buffer
\r
1797 * \param tlen On exit, holds the length written
\r
1798 * \param lifetime On exit, holds the lifetime of the ticket in seconds
\r
1800 * \return 0 if successful, or
\r
1801 * a specific MBEDTLS_ERR_XXX code.
\r
1803 typedef int mbedtls_ssl_ticket_write_t( void *p_ticket,
\r
1804 const mbedtls_ssl_session *session,
\r
1805 unsigned char *start,
\r
1806 const unsigned char *end,
\r
1808 uint32_t *lifetime );
\r
1810 #if defined(MBEDTLS_SSL_EXPORT_KEYS)
\r
1812 * \brief Callback type: Export key block and master secret
\r
1814 * \note This is required for certain uses of TLS, e.g. EAP-TLS
\r
1815 * (RFC 5216) and Thread. The key pointers are ephemeral and
\r
1816 * therefore must not be stored. The master secret and keys
\r
1817 * should not be used directly except as an input to a key
\r
1818 * derivation function.
\r
1820 * \param p_expkey Context for the callback
\r
1821 * \param ms Pointer to master secret (fixed length: 48 bytes)
\r
1822 * \param kb Pointer to key block, see RFC 5246 section 6.3
\r
1823 * (variable length: 2 * maclen + 2 * keylen + 2 * ivlen).
\r
1824 * \param maclen MAC length
\r
1825 * \param keylen Key length
\r
1826 * \param ivlen IV length
\r
1828 * \return 0 if successful, or
\r
1829 * a specific MBEDTLS_ERR_XXX code.
\r
1831 typedef int mbedtls_ssl_export_keys_t( void *p_expkey,
\r
1832 const unsigned char *ms,
\r
1833 const unsigned char *kb,
\r
1839 * \brief Callback type: Export key block, master secret,
\r
1840 * handshake randbytes and the tls_prf function
\r
1841 * used to derive keys.
\r
1843 * \note This is required for certain uses of TLS, e.g. EAP-TLS
\r
1844 * (RFC 5216) and Thread. The key pointers are ephemeral and
\r
1845 * therefore must not be stored. The master secret and keys
\r
1846 * should not be used directly except as an input to a key
\r
1847 * derivation function.
\r
1849 * \param p_expkey Context for the callback.
\r
1850 * \param ms Pointer to master secret (fixed length: 48 bytes).
\r
1851 * \param kb Pointer to key block, see RFC 5246 section 6.3.
\r
1852 * (variable length: 2 * maclen + 2 * keylen + 2 * ivlen).
\r
1853 * \param maclen MAC length.
\r
1854 * \param keylen Key length.
\r
1855 * \param ivlen IV length.
\r
1856 * \param client_random The client random bytes.
\r
1857 * \param server_random The server random bytes.
\r
1858 * \param tls_prf_type The tls_prf enum type.
\r
1860 * \return 0 if successful, or
\r
1861 * a specific MBEDTLS_ERR_XXX code.
\r
1863 typedef int mbedtls_ssl_export_keys_ext_t( void *p_expkey,
\r
1864 const unsigned char *ms,
\r
1865 const unsigned char *kb,
\r
1869 unsigned char client_random[32],
\r
1870 unsigned char server_random[32],
\r
1871 mbedtls_tls_prf_types tls_prf_type );
\r
1872 #endif /* MBEDTLS_SSL_EXPORT_KEYS */
\r
1875 * \brief Callback type: parse and load session ticket
\r
1877 * \note This describes what a callback implementation should do.
\r
1878 * This callback should parse a session ticket as generated
\r
1879 * by the corresponding mbedtls_ssl_ticket_write_t function,
\r
1880 * and, if the ticket is authentic and valid, load the
\r
1883 * \note The implementation is allowed to modify the first len
\r
1884 * bytes of the input buffer, eg to use it as a temporary
\r
1885 * area for the decrypted ticket contents.
\r
1887 * \param p_ticket Context for the callback
\r
1888 * \param session SSL session to be loaded
\r
1889 * \param buf Start of the buffer containing the ticket
\r
1890 * \param len Length of the ticket.
\r
1892 * \return 0 if successful, or
\r
1893 * MBEDTLS_ERR_SSL_INVALID_MAC if not authentic, or
\r
1894 * MBEDTLS_ERR_SSL_SESSION_TICKET_EXPIRED if expired, or
\r
1895 * any other non-zero code for other failures.
\r
1897 typedef int mbedtls_ssl_ticket_parse_t( void *p_ticket,
\r
1898 mbedtls_ssl_session *session,
\r
1899 unsigned char *buf,
\r
1902 #if defined(MBEDTLS_SSL_SESSION_TICKETS) && defined(MBEDTLS_SSL_SRV_C)
\r
1904 * \brief Configure SSL session ticket callbacks (server only).
\r
1905 * (Default: none.)
\r
1907 * \note On server, session tickets are enabled by providing
\r
1908 * non-NULL callbacks.
\r
1910 * \note On client, use \c mbedtls_ssl_conf_session_tickets().
\r
1912 * \param conf SSL configuration context
\r
1913 * \param f_ticket_write Callback for writing a ticket
\r
1914 * \param f_ticket_parse Callback for parsing a ticket
\r
1915 * \param p_ticket Context shared by the two callbacks
\r
1917 void mbedtls_ssl_conf_session_tickets_cb( mbedtls_ssl_config *conf,
\r
1918 mbedtls_ssl_ticket_write_t *f_ticket_write,
\r
1919 mbedtls_ssl_ticket_parse_t *f_ticket_parse,
\r
1921 #endif /* MBEDTLS_SSL_SESSION_TICKETS && MBEDTLS_SSL_SRV_C */
\r
1923 #if defined(MBEDTLS_SSL_EXPORT_KEYS)
\r
1925 * \brief Configure key export callback.
\r
1926 * (Default: none.)
\r
1928 * \note See \c mbedtls_ssl_export_keys_t.
\r
1930 * \param conf SSL configuration context
\r
1931 * \param f_export_keys Callback for exporting keys
\r
1932 * \param p_export_keys Context for the callback
\r
1934 void mbedtls_ssl_conf_export_keys_cb( mbedtls_ssl_config *conf,
\r
1935 mbedtls_ssl_export_keys_t *f_export_keys,
\r
1936 void *p_export_keys );
\r
1939 * \brief Configure extended key export callback.
\r
1940 * (Default: none.)
\r
1942 * \note See \c mbedtls_ssl_export_keys_ext_t.
\r
1944 * \param conf SSL configuration context
\r
1945 * \param f_export_keys_ext Callback for exporting keys
\r
1946 * \param p_export_keys Context for the callback
\r
1948 void mbedtls_ssl_conf_export_keys_ext_cb( mbedtls_ssl_config *conf,
\r
1949 mbedtls_ssl_export_keys_ext_t *f_export_keys_ext,
\r
1950 void *p_export_keys );
\r
1951 #endif /* MBEDTLS_SSL_EXPORT_KEYS */
\r
1953 #if defined(MBEDTLS_SSL_ASYNC_PRIVATE)
\r
1955 * \brief Configure asynchronous private key operation callbacks.
\r
1957 * \param conf SSL configuration context
\r
1958 * \param f_async_sign Callback to start a signature operation. See
\r
1959 * the description of ::mbedtls_ssl_async_sign_t
\r
1960 * for more information. This may be \c NULL if the
\r
1961 * external processor does not support any signature
\r
1962 * operation; in this case the private key object
\r
1963 * associated with the certificate will be used.
\r
1964 * \param f_async_decrypt Callback to start a decryption operation. See
\r
1965 * the description of ::mbedtls_ssl_async_decrypt_t
\r
1966 * for more information. This may be \c NULL if the
\r
1967 * external processor does not support any decryption
\r
1968 * operation; in this case the private key object
\r
1969 * associated with the certificate will be used.
\r
1970 * \param f_async_resume Callback to resume an asynchronous operation. See
\r
1971 * the description of ::mbedtls_ssl_async_resume_t
\r
1972 * for more information. This may not be \c NULL unless
\r
1973 * \p f_async_sign and \p f_async_decrypt are both
\r
1975 * \param f_async_cancel Callback to cancel an asynchronous operation. See
\r
1976 * the description of ::mbedtls_ssl_async_cancel_t
\r
1977 * for more information. This may be \c NULL if
\r
1978 * no cleanup is needed.
\r
1979 * \param config_data A pointer to configuration data which can be
\r
1981 * mbedtls_ssl_conf_get_async_config_data(). The
\r
1982 * library stores this value without dereferencing it.
\r
1984 void mbedtls_ssl_conf_async_private_cb( mbedtls_ssl_config *conf,
\r
1985 mbedtls_ssl_async_sign_t *f_async_sign,
\r
1986 mbedtls_ssl_async_decrypt_t *f_async_decrypt,
\r
1987 mbedtls_ssl_async_resume_t *f_async_resume,
\r
1988 mbedtls_ssl_async_cancel_t *f_async_cancel,
\r
1989 void *config_data );
\r
1992 * \brief Retrieve the configuration data set by
\r
1993 * mbedtls_ssl_conf_async_private_cb().
\r
1995 * \param conf SSL configuration context
\r
1996 * \return The configuration data set by
\r
1997 * mbedtls_ssl_conf_async_private_cb().
\r
1999 void *mbedtls_ssl_conf_get_async_config_data( const mbedtls_ssl_config *conf );
\r
2002 * \brief Retrieve the asynchronous operation user context.
\r
2004 * \note This function may only be called while a handshake
\r
2007 * \param ssl The SSL context to access.
\r
2009 * \return The asynchronous operation user context that was last
\r
2010 * set during the current handshake. If
\r
2011 * mbedtls_ssl_set_async_operation_data() has not yet been
\r
2012 * called during the current handshake, this function returns
\r
2015 void *mbedtls_ssl_get_async_operation_data( const mbedtls_ssl_context *ssl );
\r
2018 * \brief Retrieve the asynchronous operation user context.
\r
2020 * \note This function may only be called while a handshake
\r
2023 * \param ssl The SSL context to access.
\r
2024 * \param ctx The new value of the asynchronous operation user context.
\r
2025 * Call mbedtls_ssl_get_async_operation_data() later during the
\r
2026 * same handshake to retrieve this value.
\r
2028 void mbedtls_ssl_set_async_operation_data( mbedtls_ssl_context *ssl,
\r
2030 #endif /* MBEDTLS_SSL_ASYNC_PRIVATE */
\r
2033 * \brief Callback type: generate a cookie
\r
2035 * \param ctx Context for the callback
\r
2036 * \param p Buffer to write to,
\r
2037 * must be updated to point right after the cookie
\r
2038 * \param end Pointer to one past the end of the output buffer
\r
2039 * \param info Client ID info that was passed to
\r
2040 * \c mbedtls_ssl_set_client_transport_id()
\r
2041 * \param ilen Length of info in bytes
\r
2043 * \return The callback must return 0 on success,
\r
2044 * or a negative error code.
\r
2046 typedef int mbedtls_ssl_cookie_write_t( void *ctx,
\r
2047 unsigned char **p, unsigned char *end,
\r
2048 const unsigned char *info, size_t ilen );
\r
2051 * \brief Callback type: verify a cookie
\r
2053 * \param ctx Context for the callback
\r
2054 * \param cookie Cookie to verify
\r
2055 * \param clen Length of cookie
\r
2056 * \param info Client ID info that was passed to
\r
2057 * \c mbedtls_ssl_set_client_transport_id()
\r
2058 * \param ilen Length of info in bytes
\r
2060 * \return The callback must return 0 if cookie is valid,
\r
2061 * or a negative error code.
\r
2063 typedef int mbedtls_ssl_cookie_check_t( void *ctx,
\r
2064 const unsigned char *cookie, size_t clen,
\r
2065 const unsigned char *info, size_t ilen );
\r
2067 #if defined(MBEDTLS_SSL_DTLS_HELLO_VERIFY) && defined(MBEDTLS_SSL_SRV_C)
\r
2069 * \brief Register callbacks for DTLS cookies
\r
2070 * (Server only. DTLS only.)
\r
2072 * Default: dummy callbacks that fail, in order to force you to
\r
2073 * register working callbacks (and initialize their context).
\r
2075 * To disable HelloVerifyRequest, register NULL callbacks.
\r
2077 * \warning Disabling hello verification allows your server to be used
\r
2078 * for amplification in DoS attacks against other hosts.
\r
2079 * Only disable if you known this can't happen in your
\r
2080 * particular environment.
\r
2082 * \note See comments on \c mbedtls_ssl_handshake() about handling
\r
2083 * the MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED that is expected
\r
2084 * on the first handshake attempt when this is enabled.
\r
2086 * \note This is also necessary to handle client reconnection from
\r
2087 * the same port as described in RFC 6347 section 4.2.8 (only
\r
2088 * the variant with cookies is supported currently). See
\r
2089 * comments on \c mbedtls_ssl_read() for details.
\r
2091 * \param conf SSL configuration
\r
2092 * \param f_cookie_write Cookie write callback
\r
2093 * \param f_cookie_check Cookie check callback
\r
2094 * \param p_cookie Context for both callbacks
\r
2096 void mbedtls_ssl_conf_dtls_cookies( mbedtls_ssl_config *conf,
\r
2097 mbedtls_ssl_cookie_write_t *f_cookie_write,
\r
2098 mbedtls_ssl_cookie_check_t *f_cookie_check,
\r
2102 * \brief Set client's transport-level identification info.
\r
2103 * (Server only. DTLS only.)
\r
2105 * This is usually the IP address (and port), but could be
\r
2106 * anything identify the client depending on the underlying
\r
2107 * network stack. Used for HelloVerifyRequest with DTLS.
\r
2108 * This is *not* used to route the actual packets.
\r
2110 * \param ssl SSL context
\r
2111 * \param info Transport-level info identifying the client (eg IP + port)
\r
2112 * \param ilen Length of info in bytes
\r
2114 * \note An internal copy is made, so the info buffer can be reused.
\r
2116 * \return 0 on success,
\r
2117 * MBEDTLS_ERR_SSL_BAD_INPUT_DATA if used on client,
\r
2118 * MBEDTLS_ERR_SSL_ALLOC_FAILED if out of memory.
\r
2120 int mbedtls_ssl_set_client_transport_id( mbedtls_ssl_context *ssl,
\r
2121 const unsigned char *info,
\r
2124 #endif /* MBEDTLS_SSL_DTLS_HELLO_VERIFY && MBEDTLS_SSL_SRV_C */
\r
2126 #if defined(MBEDTLS_SSL_DTLS_ANTI_REPLAY)
\r
2128 * \brief Enable or disable anti-replay protection for DTLS.
\r
2129 * (DTLS only, no effect on TLS.)
\r
2130 * Default: enabled.
\r
2132 * \param conf SSL configuration
\r
2133 * \param mode MBEDTLS_SSL_ANTI_REPLAY_ENABLED or MBEDTLS_SSL_ANTI_REPLAY_DISABLED.
\r
2135 * \warning Disabling this is a security risk unless the application
\r
2136 * protocol handles duplicated packets in a safe way. You
\r
2137 * should not disable this without careful consideration.
\r
2138 * However, if your application already detects duplicated
\r
2139 * packets and needs information about them to adjust its
\r
2140 * transmission strategy, then you'll want to disable this.
\r
2142 void mbedtls_ssl_conf_dtls_anti_replay( mbedtls_ssl_config *conf, char mode );
\r
2143 #endif /* MBEDTLS_SSL_DTLS_ANTI_REPLAY */
\r
2145 #if defined(MBEDTLS_SSL_DTLS_BADMAC_LIMIT)
\r
2147 * \brief Set a limit on the number of records with a bad MAC
\r
2148 * before terminating the connection.
\r
2149 * (DTLS only, no effect on TLS.)
\r
2150 * Default: 0 (disabled).
\r
2152 * \param conf SSL configuration
\r
2153 * \param limit Limit, or 0 to disable.
\r
2155 * \note If the limit is N, then the connection is terminated when
\r
2156 * the Nth non-authentic record is seen.
\r
2158 * \note Records with an invalid header are not counted, only the
\r
2159 * ones going through the authentication-decryption phase.
\r
2161 * \note This is a security trade-off related to the fact that it's
\r
2162 * often relatively easy for an active attacker ot inject UDP
\r
2163 * datagrams. On one hand, setting a low limit here makes it
\r
2164 * easier for such an attacker to forcibly terminated a
\r
2165 * connection. On the other hand, a high limit or no limit
\r
2166 * might make us waste resources checking authentication on
\r
2167 * many bogus packets.
\r
2169 void mbedtls_ssl_conf_dtls_badmac_limit( mbedtls_ssl_config *conf, unsigned limit );
\r
2170 #endif /* MBEDTLS_SSL_DTLS_BADMAC_LIMIT */
\r
2172 #if defined(MBEDTLS_SSL_PROTO_DTLS)
\r
2175 * \brief Allow or disallow packing of multiple handshake records
\r
2176 * within a single datagram.
\r
2178 * \param ssl The SSL context to configure.
\r
2179 * \param allow_packing This determines whether datagram packing may
\r
2180 * be used or not. A value of \c 0 means that every
\r
2181 * record will be sent in a separate datagram; a
\r
2182 * value of \c 1 means that, if space permits,
\r
2183 * multiple handshake messages (including CCS) belonging to
\r
2184 * a single flight may be packed within a single datagram.
\r
2186 * \note This is enabled by default and should only be disabled
\r
2187 * for test purposes, or if datagram packing causes
\r
2188 * interoperability issues with peers that don't support it.
\r
2190 * \note Allowing datagram packing reduces the network load since
\r
2191 * there's less overhead if multiple messages share the same
\r
2192 * datagram. Also, it increases the handshake efficiency
\r
2193 * since messages belonging to a single datagram will not
\r
2194 * be reordered in transit, and so future message buffering
\r
2195 * or flight retransmission (if no buffering is used) as
\r
2196 * means to deal with reordering are needed less frequently.
\r
2198 * \note Application records are not affected by this option and
\r
2199 * are currently always sent in separate datagrams.
\r
2202 void mbedtls_ssl_set_datagram_packing( mbedtls_ssl_context *ssl,
\r
2203 unsigned allow_packing );
\r
2206 * \brief Set retransmit timeout values for the DTLS handshake.
\r
2207 * (DTLS only, no effect on TLS.)
\r
2209 * \param conf SSL configuration
\r
2210 * \param min Initial timeout value in milliseconds.
\r
2211 * Default: 1000 (1 second).
\r
2212 * \param max Maximum timeout value in milliseconds.
\r
2213 * Default: 60000 (60 seconds).
\r
2215 * \note Default values are from RFC 6347 section 4.2.4.1.
\r
2217 * \note The 'min' value should typically be slightly above the
\r
2218 * expected round-trip time to your peer, plus whatever time
\r
2219 * it takes for the peer to process the message. For example,
\r
2220 * if your RTT is about 600ms and you peer needs up to 1s to
\r
2221 * do the cryptographic operations in the handshake, then you
\r
2222 * should set 'min' slightly above 1600. Lower values of 'min'
\r
2223 * might cause spurious resends which waste network resources,
\r
2224 * while larger value of 'min' will increase overall latency
\r
2225 * on unreliable network links.
\r
2227 * \note The more unreliable your network connection is, the larger
\r
2228 * your max / min ratio needs to be in order to achieve
\r
2229 * reliable handshakes.
\r
2231 * \note Messages are retransmitted up to log2(ceil(max/min)) times.
\r
2232 * For example, if min = 1s and max = 5s, the retransmit plan
\r
2233 * goes: send ... 1s -> resend ... 2s -> resend ... 4s ->
\r
2234 * resend ... 5s -> give up and return a timeout error.
\r
2236 void mbedtls_ssl_conf_handshake_timeout( mbedtls_ssl_config *conf, uint32_t min, uint32_t max );
\r
2237 #endif /* MBEDTLS_SSL_PROTO_DTLS */
\r
2239 #if defined(MBEDTLS_SSL_SRV_C)
\r
2241 * \brief Set the session cache callbacks (server-side only)
\r
2242 * If not set, no session resuming is done (except if session
\r
2243 * tickets are enabled too).
\r
2245 * The session cache has the responsibility to check for stale
\r
2246 * entries based on timeout. See RFC 5246 for recommendations.
\r
2248 * Warning: session.peer_cert is cleared by the SSL/TLS layer on
\r
2249 * connection shutdown, so do not cache the pointer! Either set
\r
2250 * it to NULL or make a full copy of the certificate.
\r
2252 * The get callback is called once during the initial handshake
\r
2253 * to enable session resuming. The get function has the
\r
2254 * following parameters: (void *parameter, mbedtls_ssl_session *session)
\r
2255 * If a valid entry is found, it should fill the master of
\r
2256 * the session object with the cached values and return 0,
\r
2257 * return 1 otherwise. Optionally peer_cert can be set as well
\r
2258 * if it is properly present in cache entry.
\r
2260 * The set callback is called once during the initial handshake
\r
2261 * to enable session resuming after the entire handshake has
\r
2262 * been finished. The set function has the following parameters:
\r
2263 * (void *parameter, const mbedtls_ssl_session *session). The function
\r
2264 * should create a cache entry for future retrieval based on
\r
2265 * the data in the session structure and should keep in mind
\r
2266 * that the mbedtls_ssl_session object presented (and all its referenced
\r
2267 * data) is cleared by the SSL/TLS layer when the connection is
\r
2268 * terminated. It is recommended to add metadata to determine if
\r
2269 * an entry is still valid in the future. Return 0 if
\r
2270 * successfully cached, return 1 otherwise.
\r
2272 * \param conf SSL configuration
\r
2273 * \param p_cache parmater (context) for both callbacks
\r
2274 * \param f_get_cache session get callback
\r
2275 * \param f_set_cache session set callback
\r
2277 void mbedtls_ssl_conf_session_cache( mbedtls_ssl_config *conf,
\r
2279 int (*f_get_cache)(void *, mbedtls_ssl_session *),
\r
2280 int (*f_set_cache)(void *, const mbedtls_ssl_session *) );
\r
2281 #endif /* MBEDTLS_SSL_SRV_C */
\r
2283 #if defined(MBEDTLS_SSL_CLI_C)
\r
2285 * \brief Request resumption of session (client-side only)
\r
2286 * Session data is copied from presented session structure.
\r
2288 * \param ssl SSL context
\r
2289 * \param session session context
\r
2291 * \return 0 if successful,
\r
2292 * MBEDTLS_ERR_SSL_ALLOC_FAILED if memory allocation failed,
\r
2293 * MBEDTLS_ERR_SSL_BAD_INPUT_DATA if used server-side or
\r
2294 * arguments are otherwise invalid
\r
2296 * \sa mbedtls_ssl_get_session()
\r
2298 int mbedtls_ssl_set_session( mbedtls_ssl_context *ssl, const mbedtls_ssl_session *session );
\r
2299 #endif /* MBEDTLS_SSL_CLI_C */
\r
2302 * \brief Set the list of allowed ciphersuites and the preference
\r
2303 * order. First in the list has the highest preference.
\r
2304 * (Overrides all version-specific lists)
\r
2306 * The ciphersuites array is not copied, and must remain
\r
2307 * valid for the lifetime of the ssl_config.
\r
2309 * Note: The server uses its own preferences
\r
2310 * over the preference of the client unless
\r
2311 * MBEDTLS_SSL_SRV_RESPECT_CLIENT_PREFERENCE is defined!
\r
2313 * \param conf SSL configuration
\r
2314 * \param ciphersuites 0-terminated list of allowed ciphersuites
\r
2316 void mbedtls_ssl_conf_ciphersuites( mbedtls_ssl_config *conf,
\r
2317 const int *ciphersuites );
\r
2319 #if defined(MBEDTLS_SSL_DTLS_CONNECTION_ID)
\r
2320 #define MBEDTLS_SSL_UNEXPECTED_CID_IGNORE 0
\r
2321 #define MBEDTLS_SSL_UNEXPECTED_CID_FAIL 1
\r
2323 * \brief Specify the length of Connection IDs for incoming
\r
2324 * encrypted DTLS records, as well as the behaviour
\r
2325 * on unexpected CIDs.
\r
2327 * By default, the CID length is set to \c 0,
\r
2328 * and unexpected CIDs are silently ignored.
\r
2330 * \param conf The SSL configuration to modify.
\r
2331 * \param len The length in Bytes of the CID fields in encrypted
\r
2332 * DTLS records using the CID mechanism. This must
\r
2333 * not be larger than #MBEDTLS_SSL_CID_OUT_LEN_MAX.
\r
2334 * \param ignore_other_cids This determines the stack's behaviour when
\r
2335 * receiving a record with an unexpected CID.
\r
2336 * Possible values are:
\r
2337 * - #MBEDTLS_SSL_UNEXPECTED_CID_IGNORE
\r
2338 * In this case, the record is silently ignored.
\r
2339 * - #MBEDTLS_SSL_UNEXPECTED_CID_FAIL
\r
2340 * In this case, the stack fails with the specific
\r
2341 * error code #MBEDTLS_ERR_SSL_UNEXPECTED_CID.
\r
2343 * \note The CID specification allows implementations to either
\r
2344 * use a common length for all incoming connection IDs or
\r
2345 * allow variable-length incoming IDs. Mbed TLS currently
\r
2346 * requires a common length for all connections sharing the
\r
2347 * same SSL configuration; this allows simpler parsing of
\r
2350 * \return \c 0 on success.
\r
2351 * \return #MBEDTLS_ERR_SSL_BAD_INPUT_DATA if \p own_cid_len
\r
2354 int mbedtls_ssl_conf_cid( mbedtls_ssl_config *conf, size_t len,
\r
2355 int ignore_other_cids );
\r
2356 #endif /* MBEDTLS_SSL_DTLS_CONNECTION_ID */
\r
2359 * \brief Set the list of allowed ciphersuites and the
\r
2360 * preference order for a specific version of the protocol.
\r
2361 * (Only useful on the server side)
\r
2363 * The ciphersuites array is not copied, and must remain
\r
2364 * valid for the lifetime of the ssl_config.
\r
2366 * \param conf SSL configuration
\r
2367 * \param ciphersuites 0-terminated list of allowed ciphersuites
\r
2368 * \param major Major version number (only MBEDTLS_SSL_MAJOR_VERSION_3
\r
2370 * \param minor Minor version number (MBEDTLS_SSL_MINOR_VERSION_0,
\r
2371 * MBEDTLS_SSL_MINOR_VERSION_1 and MBEDTLS_SSL_MINOR_VERSION_2,
\r
2372 * MBEDTLS_SSL_MINOR_VERSION_3 supported)
\r
2374 * \note With DTLS, use MBEDTLS_SSL_MINOR_VERSION_2 for DTLS 1.0
\r
2375 * and MBEDTLS_SSL_MINOR_VERSION_3 for DTLS 1.2
\r
2377 void mbedtls_ssl_conf_ciphersuites_for_version( mbedtls_ssl_config *conf,
\r
2378 const int *ciphersuites,
\r
2379 int major, int minor );
\r
2381 #if defined(MBEDTLS_X509_CRT_PARSE_C)
\r
2383 * \brief Set the X.509 security profile used for verification
\r
2385 * \note The restrictions are enforced for all certificates in the
\r
2386 * chain. However, signatures in the handshake are not covered
\r
2387 * by this setting but by \b mbedtls_ssl_conf_sig_hashes().
\r
2389 * \param conf SSL configuration
\r
2390 * \param profile Profile to use
\r
2392 void mbedtls_ssl_conf_cert_profile( mbedtls_ssl_config *conf,
\r
2393 const mbedtls_x509_crt_profile *profile );
\r
2396 * \brief Set the data required to verify peer certificate
\r
2398 * \note See \c mbedtls_x509_crt_verify() for notes regarding the
\r
2399 * parameters ca_chain (maps to trust_ca for that function)
\r
2402 * \param conf SSL configuration
\r
2403 * \param ca_chain trusted CA chain (meaning all fully trusted top-level CAs)
\r
2404 * \param ca_crl trusted CA CRLs
\r
2406 void mbedtls_ssl_conf_ca_chain( mbedtls_ssl_config *conf,
\r
2407 mbedtls_x509_crt *ca_chain,
\r
2408 mbedtls_x509_crl *ca_crl );
\r
2410 #if defined(MBEDTLS_X509_TRUSTED_CERTIFICATE_CALLBACK)
\r
2412 * \brief Set the trusted certificate callback.
\r
2414 * This API allows to register the set of trusted certificates
\r
2415 * through a callback, instead of a linked list as configured
\r
2416 * by mbedtls_ssl_conf_ca_chain().
\r
2418 * This is useful for example in contexts where a large number
\r
2419 * of CAs are used, and the inefficiency of maintaining them
\r
2420 * in a linked list cannot be tolerated. It is also useful when
\r
2421 * the set of trusted CAs needs to be modified frequently.
\r
2423 * See the documentation of `mbedtls_x509_crt_ca_cb_t` for
\r
2424 * more information.
\r
2426 * \param conf The SSL configuration to register the callback with.
\r
2427 * \param f_ca_cb The trusted certificate callback to use when verifying
\r
2428 * certificate chains.
\r
2429 * \param p_ca_cb The context to be passed to \p f_ca_cb (for example,
\r
2430 * a reference to a trusted CA database).
\r
2432 * \note This API is incompatible with mbedtls_ssl_conf_ca_chain():
\r
2433 * Any call to this function overwrites the values set through
\r
2434 * earlier calls to mbedtls_ssl_conf_ca_chain() or
\r
2435 * mbedtls_ssl_conf_ca_cb().
\r
2437 * \note This API is incompatible with CA indication in
\r
2438 * CertificateRequest messages: A server-side SSL context which
\r
2439 * is bound to an SSL configuration that uses a CA callback
\r
2440 * configured via mbedtls_ssl_conf_ca_cb(), and which requires
\r
2441 * client authentication, will send an empty CA list in the
\r
2442 * corresponding CertificateRequest message.
\r
2444 * \note This API is incompatible with mbedtls_ssl_set_hs_ca_chain():
\r
2445 * If an SSL context is bound to an SSL configuration which uses
\r
2446 * CA callbacks configured via mbedtls_ssl_conf_ca_cb(), then
\r
2447 * calls to mbedtls_ssl_set_hs_ca_chain() have no effect.
\r
2449 * \note The use of this API disables the use of restartable ECC
\r
2450 * during X.509 CRT signature verification (but doesn't affect
\r
2453 * \warning This API is incompatible with the use of CRLs. Any call to
\r
2454 * mbedtls_ssl_conf_ca_cb() unsets CRLs configured through
\r
2455 * earlier calls to mbedtls_ssl_conf_ca_chain().
\r
2457 * \warning In multi-threaded environments, the callback \p f_ca_cb
\r
2458 * must be thread-safe, and it is the user's responsibility
\r
2459 * to guarantee this (for example through a mutex
\r
2460 * contained in the callback context pointed to by \p p_ca_cb).
\r
2462 void mbedtls_ssl_conf_ca_cb( mbedtls_ssl_config *conf,
\r
2463 mbedtls_x509_crt_ca_cb_t f_ca_cb,
\r
2465 #endif /* MBEDTLS_X509_TRUSTED_CERTIFICATE_CALLBACK */
\r
2468 * \brief Set own certificate chain and private key
\r
2470 * \note own_cert should contain in order from the bottom up your
\r
2471 * certificate chain. The top certificate (self-signed)
\r
2474 * \note On server, this function can be called multiple times to
\r
2475 * provision more than one cert/key pair (eg one ECDSA, one
\r
2476 * RSA with SHA-256, one RSA with SHA-1). An adequate
\r
2477 * certificate will be selected according to the client's
\r
2478 * advertised capabilities. In case multiple certificates are
\r
2479 * adequate, preference is given to the one set by the first
\r
2480 * call to this function, then second, etc.
\r
2482 * \note On client, only the first call has any effect. That is,
\r
2483 * only one client certificate can be provisioned. The
\r
2484 * server's preferences in its CertficateRequest message will
\r
2485 * be ignored and our only cert will be sent regardless of
\r
2486 * whether it matches those preferences - the server can then
\r
2487 * decide what it wants to do with it.
\r
2489 * \note The provided \p pk_key needs to match the public key in the
\r
2490 * first certificate in \p own_cert, or all handshakes using
\r
2491 * that certificate will fail. It is your responsibility
\r
2492 * to ensure that; this function will not perform any check.
\r
2493 * You may use mbedtls_pk_check_pair() in order to perform
\r
2494 * this check yourself, but be aware that this function can
\r
2495 * be computationally expensive on some key types.
\r
2497 * \param conf SSL configuration
\r
2498 * \param own_cert own public certificate chain
\r
2499 * \param pk_key own private key
\r
2501 * \return 0 on success or MBEDTLS_ERR_SSL_ALLOC_FAILED
\r
2503 int mbedtls_ssl_conf_own_cert( mbedtls_ssl_config *conf,
\r
2504 mbedtls_x509_crt *own_cert,
\r
2505 mbedtls_pk_context *pk_key );
\r
2506 #endif /* MBEDTLS_X509_CRT_PARSE_C */
\r
2508 #if defined(MBEDTLS_KEY_EXCHANGE__SOME__PSK_ENABLED)
\r
2510 * \brief Configure a pre-shared key (PSK) and identity
\r
2511 * to be used in PSK-based ciphersuites.
\r
2513 * \note This is mainly useful for clients. Servers will usually
\r
2514 * want to use \c mbedtls_ssl_conf_psk_cb() instead.
\r
2516 * \warning Currently, clients can only register a single pre-shared key.
\r
2517 * Calling this function or mbedtls_ssl_conf_psk_opaque() more
\r
2518 * than once will overwrite values configured in previous calls.
\r
2519 * Support for setting multiple PSKs on clients and selecting
\r
2520 * one based on the identity hint is not a planned feature,
\r
2521 * but feedback is welcomed.
\r
2523 * \param conf The SSL configuration to register the PSK with.
\r
2524 * \param psk The pointer to the pre-shared key to use.
\r
2525 * \param psk_len The length of the pre-shared key in bytes.
\r
2526 * \param psk_identity The pointer to the pre-shared key identity.
\r
2527 * \param psk_identity_len The length of the pre-shared key identity
\r
2530 * \note The PSK and its identity are copied internally and
\r
2531 * hence need not be preserved by the caller for the lifetime
\r
2532 * of the SSL configuration.
\r
2534 * \return \c 0 if successful.
\r
2535 * \return An \c MBEDTLS_ERR_SSL_XXX error code on failure.
\r
2537 int mbedtls_ssl_conf_psk( mbedtls_ssl_config *conf,
\r
2538 const unsigned char *psk, size_t psk_len,
\r
2539 const unsigned char *psk_identity, size_t psk_identity_len );
\r
2541 #if defined(MBEDTLS_USE_PSA_CRYPTO)
\r
2543 * \brief Configure an opaque pre-shared key (PSK) and identity
\r
2544 * to be used in PSK-based ciphersuites.
\r
2546 * \note This is mainly useful for clients. Servers will usually
\r
2547 * want to use \c mbedtls_ssl_conf_psk_cb() instead.
\r
2549 * \warning Currently, clients can only register a single pre-shared key.
\r
2550 * Calling this function or mbedtls_ssl_conf_psk() more than
\r
2551 * once will overwrite values configured in previous calls.
\r
2552 * Support for setting multiple PSKs on clients and selecting
\r
2553 * one based on the identity hint is not a planned feature,
\r
2554 * but feedback is welcomed.
\r
2556 * \param conf The SSL configuration to register the PSK with.
\r
2557 * \param psk The identifier of the key slot holding the PSK.
\r
2558 * Until \p conf is destroyed or this function is successfully
\r
2559 * called again, the key slot \p psk must be populated with a
\r
2560 * key of type PSA_ALG_CATEGORY_KEY_DERIVATION whose policy
\r
2561 * allows its use for the key derivation algorithm applied
\r
2562 * in the handshake.
\r
2563 * \param psk_identity The pointer to the pre-shared key identity.
\r
2564 * \param psk_identity_len The length of the pre-shared key identity
\r
2567 * \note The PSK identity hint is copied internally and hence need
\r
2568 * not be preserved by the caller for the lifetime of the
\r
2569 * SSL configuration.
\r
2571 * \return \c 0 if successful.
\r
2572 * \return An \c MBEDTLS_ERR_SSL_XXX error code on failure.
\r
2574 int mbedtls_ssl_conf_psk_opaque( mbedtls_ssl_config *conf,
\r
2575 psa_key_handle_t psk,
\r
2576 const unsigned char *psk_identity,
\r
2577 size_t psk_identity_len );
\r
2578 #endif /* MBEDTLS_USE_PSA_CRYPTO */
\r
2581 * \brief Set the pre-shared Key (PSK) for the current handshake.
\r
2583 * \note This should only be called inside the PSK callback,
\r
2584 * i.e. the function passed to \c mbedtls_ssl_conf_psk_cb().
\r
2586 * \param ssl The SSL context to configure a PSK for.
\r
2587 * \param psk The pointer to the pre-shared key.
\r
2588 * \param psk_len The length of the pre-shared key in bytes.
\r
2590 * \return \c 0 if successful.
\r
2591 * \return An \c MBEDTLS_ERR_SSL_XXX error code on failure.
\r
2593 int mbedtls_ssl_set_hs_psk( mbedtls_ssl_context *ssl,
\r
2594 const unsigned char *psk, size_t psk_len );
\r
2596 #if defined(MBEDTLS_USE_PSA_CRYPTO)
\r
2598 * \brief Set an opaque pre-shared Key (PSK) for the current handshake.
\r
2600 * \note This should only be called inside the PSK callback,
\r
2601 * i.e. the function passed to \c mbedtls_ssl_conf_psk_cb().
\r
2603 * \param ssl The SSL context to configure a PSK for.
\r
2604 * \param psk The identifier of the key slot holding the PSK.
\r
2605 * For the duration of the current handshake, the key slot
\r
2606 * must be populated with a key of type
\r
2607 * PSA_ALG_CATEGORY_KEY_DERIVATION whose policy allows its
\r
2608 * use for the key derivation algorithm
\r
2609 * applied in the handshake.
\r
2611 * \return \c 0 if successful.
\r
2612 * \return An \c MBEDTLS_ERR_SSL_XXX error code on failure.
\r
2614 int mbedtls_ssl_set_hs_psk_opaque( mbedtls_ssl_context *ssl,
\r
2615 psa_key_handle_t psk );
\r
2616 #endif /* MBEDTLS_USE_PSA_CRYPTO */
\r
2619 * \brief Set the PSK callback (server-side only).
\r
2621 * If set, the PSK callback is called for each
\r
2622 * handshake where a PSK-based ciphersuite was negotiated.
\r
2623 * The caller provides the identity received and wants to
\r
2624 * receive the actual PSK data and length.
\r
2626 * The callback has the following parameters:
\r
2627 * - \c void*: The opaque pointer \p p_psk.
\r
2628 * - \c mbedtls_ssl_context*: The SSL context to which
\r
2629 * the operation applies.
\r
2630 * - \c const unsigned char*: The PSK identity
\r
2631 * selected by the client.
\r
2632 * - \c size_t: The length of the PSK identity
\r
2633 * selected by the client.
\r
2635 * If a valid PSK identity is found, the callback should use
\r
2636 * \c mbedtls_ssl_set_hs_psk() or
\r
2637 * \c mbedtls_ssl_set_hs_psk_opaque()
\r
2638 * on the SSL context to set the correct PSK and return \c 0.
\r
2639 * Any other return value will result in a denied PSK identity.
\r
2641 * \note If you set a PSK callback using this function, then you
\r
2642 * don't need to set a PSK key and identity using
\r
2643 * \c mbedtls_ssl_conf_psk().
\r
2645 * \param conf The SSL configuration to register the callback with.
\r
2646 * \param f_psk The callback for selecting and setting the PSK based
\r
2647 * in the PSK identity chosen by the client.
\r
2648 * \param p_psk A pointer to an opaque structure to be passed to
\r
2649 * the callback, for example a PSK store.
\r
2651 void mbedtls_ssl_conf_psk_cb( mbedtls_ssl_config *conf,
\r
2652 int (*f_psk)(void *, mbedtls_ssl_context *, const unsigned char *,
\r
2655 #endif /* MBEDTLS_KEY_EXCHANGE__SOME__PSK_ENABLED */
\r
2657 #if defined(MBEDTLS_DHM_C) && defined(MBEDTLS_SSL_SRV_C)
\r
2659 #if !defined(MBEDTLS_DEPRECATED_REMOVED)
\r
2661 #if defined(MBEDTLS_DEPRECATED_WARNING)
\r
2662 #define MBEDTLS_DEPRECATED __attribute__((deprecated))
\r
2664 #define MBEDTLS_DEPRECATED
\r
2668 * \brief Set the Diffie-Hellman public P and G values,
\r
2669 * read as hexadecimal strings (server-side only)
\r
2670 * (Default values: MBEDTLS_DHM_RFC3526_MODP_2048_[PG])
\r
2672 * \param conf SSL configuration
\r
2673 * \param dhm_P Diffie-Hellman-Merkle modulus
\r
2674 * \param dhm_G Diffie-Hellman-Merkle generator
\r
2676 * \deprecated Superseded by \c mbedtls_ssl_conf_dh_param_bin.
\r
2678 * \return 0 if successful
\r
2680 MBEDTLS_DEPRECATED int mbedtls_ssl_conf_dh_param( mbedtls_ssl_config *conf,
\r
2681 const char *dhm_P,
\r
2682 const char *dhm_G );
\r
2684 #endif /* MBEDTLS_DEPRECATED_REMOVED */
\r
2687 * \brief Set the Diffie-Hellman public P and G values
\r
2688 * from big-endian binary presentations.
\r
2689 * (Default values: MBEDTLS_DHM_RFC3526_MODP_2048_[PG]_BIN)
\r
2691 * \param conf SSL configuration
\r
2692 * \param dhm_P Diffie-Hellman-Merkle modulus in big-endian binary form
\r
2693 * \param P_len Length of DHM modulus
\r
2694 * \param dhm_G Diffie-Hellman-Merkle generator in big-endian binary form
\r
2695 * \param G_len Length of DHM generator
\r
2697 * \return 0 if successful
\r
2699 int mbedtls_ssl_conf_dh_param_bin( mbedtls_ssl_config *conf,
\r
2700 const unsigned char *dhm_P, size_t P_len,
\r
2701 const unsigned char *dhm_G, size_t G_len );
\r
2704 * \brief Set the Diffie-Hellman public P and G values,
\r
2705 * read from existing context (server-side only)
\r
2707 * \param conf SSL configuration
\r
2708 * \param dhm_ctx Diffie-Hellman-Merkle context
\r
2710 * \return 0 if successful
\r
2712 int mbedtls_ssl_conf_dh_param_ctx( mbedtls_ssl_config *conf, mbedtls_dhm_context *dhm_ctx );
\r
2713 #endif /* MBEDTLS_DHM_C && defined(MBEDTLS_SSL_SRV_C) */
\r
2715 #if defined(MBEDTLS_DHM_C) && defined(MBEDTLS_SSL_CLI_C)
\r
2717 * \brief Set the minimum length for Diffie-Hellman parameters.
\r
2718 * (Client-side only.)
\r
2719 * (Default: 1024 bits.)
\r
2721 * \param conf SSL configuration
\r
2722 * \param bitlen Minimum bit length of the DHM prime
\r
2724 void mbedtls_ssl_conf_dhm_min_bitlen( mbedtls_ssl_config *conf,
\r
2725 unsigned int bitlen );
\r
2726 #endif /* MBEDTLS_DHM_C && MBEDTLS_SSL_CLI_C */
\r
2728 #if defined(MBEDTLS_ECP_C)
\r
2730 * \brief Set the allowed curves in order of preference.
\r
2731 * (Default: all defined curves.)
\r
2733 * On server: this only affects selection of the ECDHE curve;
\r
2734 * the curves used for ECDH and ECDSA are determined by the
\r
2735 * list of available certificates instead.
\r
2737 * On client: this affects the list of curves offered for any
\r
2738 * use. The server can override our preference order.
\r
2740 * Both sides: limits the set of curves accepted for use in
\r
2741 * ECDHE and in the peer's end-entity certificate.
\r
2743 * \note This has no influence on which curves are allowed inside the
\r
2744 * certificate chains, see \c mbedtls_ssl_conf_cert_profile()
\r
2745 * for that. For the end-entity certificate however, the key
\r
2746 * will be accepted only if it is allowed both by this list
\r
2747 * and by the cert profile.
\r
2749 * \note This list should be ordered by decreasing preference
\r
2750 * (preferred curve first).
\r
2752 * \param conf SSL configuration
\r
2753 * \param curves Ordered list of allowed curves,
\r
2754 * terminated by MBEDTLS_ECP_DP_NONE.
\r
2756 void mbedtls_ssl_conf_curves( mbedtls_ssl_config *conf,
\r
2757 const mbedtls_ecp_group_id *curves );
\r
2758 #endif /* MBEDTLS_ECP_C */
\r
2760 #if defined(MBEDTLS_KEY_EXCHANGE__WITH_CERT__ENABLED)
\r
2762 * \brief Set the allowed hashes for signatures during the handshake.
\r
2763 * (Default: all available hashes except MD5.)
\r
2765 * \note This only affects which hashes are offered and can be used
\r
2766 * for signatures during the handshake. Hashes for message
\r
2767 * authentication and the TLS PRF are controlled by the
\r
2768 * ciphersuite, see \c mbedtls_ssl_conf_ciphersuites(). Hashes
\r
2769 * used for certificate signature are controlled by the
\r
2770 * verification profile, see \c mbedtls_ssl_conf_cert_profile().
\r
2772 * \note This list should be ordered by decreasing preference
\r
2773 * (preferred hash first).
\r
2775 * \param conf SSL configuration
\r
2776 * \param hashes Ordered list of allowed signature hashes,
\r
2777 * terminated by \c MBEDTLS_MD_NONE.
\r
2779 void mbedtls_ssl_conf_sig_hashes( mbedtls_ssl_config *conf,
\r
2780 const int *hashes );
\r
2781 #endif /* MBEDTLS_KEY_EXCHANGE__WITH_CERT__ENABLED */
\r
2783 #if defined(MBEDTLS_X509_CRT_PARSE_C)
\r
2785 * \brief Set or reset the hostname to check against the received
\r
2786 * server certificate. It sets the ServerName TLS extension,
\r
2787 * too, if that extension is enabled. (client-side only)
\r
2789 * \param ssl SSL context
\r
2790 * \param hostname the server hostname, may be NULL to clear hostname
\r
2792 * \note Maximum hostname length MBEDTLS_SSL_MAX_HOST_NAME_LEN.
\r
2794 * \return 0 if successful, MBEDTLS_ERR_SSL_ALLOC_FAILED on
\r
2795 * allocation failure, MBEDTLS_ERR_SSL_BAD_INPUT_DATA on
\r
2796 * too long input hostname.
\r
2798 * Hostname set to the one provided on success (cleared
\r
2799 * when NULL). On allocation failure hostname is cleared.
\r
2800 * On too long input failure, old hostname is unchanged.
\r
2802 int mbedtls_ssl_set_hostname( mbedtls_ssl_context *ssl, const char *hostname );
\r
2803 #endif /* MBEDTLS_X509_CRT_PARSE_C */
\r
2805 #if defined(MBEDTLS_SSL_SERVER_NAME_INDICATION)
\r
2807 * \brief Set own certificate and key for the current handshake
\r
2809 * \note Same as \c mbedtls_ssl_conf_own_cert() but for use within
\r
2810 * the SNI callback.
\r
2812 * \param ssl SSL context
\r
2813 * \param own_cert own public certificate chain
\r
2814 * \param pk_key own private key
\r
2816 * \return 0 on success or MBEDTLS_ERR_SSL_ALLOC_FAILED
\r
2818 int mbedtls_ssl_set_hs_own_cert( mbedtls_ssl_context *ssl,
\r
2819 mbedtls_x509_crt *own_cert,
\r
2820 mbedtls_pk_context *pk_key );
\r
2823 * \brief Set the data required to verify peer certificate for the
\r
2824 * current handshake
\r
2826 * \note Same as \c mbedtls_ssl_conf_ca_chain() but for use within
\r
2827 * the SNI callback.
\r
2829 * \param ssl SSL context
\r
2830 * \param ca_chain trusted CA chain (meaning all fully trusted top-level CAs)
\r
2831 * \param ca_crl trusted CA CRLs
\r
2833 void mbedtls_ssl_set_hs_ca_chain( mbedtls_ssl_context *ssl,
\r
2834 mbedtls_x509_crt *ca_chain,
\r
2835 mbedtls_x509_crl *ca_crl );
\r
2838 * \brief Set authmode for the current handshake.
\r
2840 * \note Same as \c mbedtls_ssl_conf_authmode() but for use within
\r
2841 * the SNI callback.
\r
2843 * \param ssl SSL context
\r
2844 * \param authmode MBEDTLS_SSL_VERIFY_NONE, MBEDTLS_SSL_VERIFY_OPTIONAL or
\r
2845 * MBEDTLS_SSL_VERIFY_REQUIRED
\r
2847 void mbedtls_ssl_set_hs_authmode( mbedtls_ssl_context *ssl,
\r
2851 * \brief Set server side ServerName TLS extension callback
\r
2852 * (optional, server-side only).
\r
2854 * If set, the ServerName callback is called whenever the
\r
2855 * server receives a ServerName TLS extension from the client
\r
2856 * during a handshake. The ServerName callback has the
\r
2857 * following parameters: (void *parameter, mbedtls_ssl_context *ssl,
\r
2858 * const unsigned char *hostname, size_t len). If a suitable
\r
2859 * certificate is found, the callback must set the
\r
2860 * certificate(s) and key(s) to use with \c
\r
2861 * mbedtls_ssl_set_hs_own_cert() (can be called repeatedly),
\r
2862 * and may optionally adjust the CA and associated CRL with \c
\r
2863 * mbedtls_ssl_set_hs_ca_chain() as well as the client
\r
2864 * authentication mode with \c mbedtls_ssl_set_hs_authmode(),
\r
2865 * then must return 0. If no matching name is found, the
\r
2866 * callback must either set a default cert, or
\r
2867 * return non-zero to abort the handshake at this point.
\r
2869 * \param conf SSL configuration
\r
2870 * \param f_sni verification function
\r
2871 * \param p_sni verification parameter
\r
2873 void mbedtls_ssl_conf_sni( mbedtls_ssl_config *conf,
\r
2874 int (*f_sni)(void *, mbedtls_ssl_context *, const unsigned char *,
\r
2877 #endif /* MBEDTLS_SSL_SERVER_NAME_INDICATION */
\r
2879 #if defined(MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED)
\r
2881 * \brief Set the EC J-PAKE password for current handshake.
\r
2883 * \note An internal copy is made, and destroyed as soon as the
\r
2884 * handshake is completed, or when the SSL context is reset or
\r
2887 * \note The SSL context needs to be already set up. The right place
\r
2888 * to call this function is between \c mbedtls_ssl_setup() or
\r
2889 * \c mbedtls_ssl_reset() and \c mbedtls_ssl_handshake().
\r
2891 * \param ssl SSL context
\r
2892 * \param pw EC J-PAKE password (pre-shared secret)
\r
2893 * \param pw_len length of pw in bytes
\r
2895 * \return 0 on success, or a negative error code.
\r
2897 int mbedtls_ssl_set_hs_ecjpake_password( mbedtls_ssl_context *ssl,
\r
2898 const unsigned char *pw,
\r
2900 #endif /*MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED */
\r
2902 #if defined(MBEDTLS_SSL_ALPN)
\r
2904 * \brief Set the supported Application Layer Protocols.
\r
2906 * \param conf SSL configuration
\r
2907 * \param protos Pointer to a NULL-terminated list of supported protocols,
\r
2908 * in decreasing preference order. The pointer to the list is
\r
2909 * recorded by the library for later reference as required, so
\r
2910 * the lifetime of the table must be atleast as long as the
\r
2911 * lifetime of the SSL configuration structure.
\r
2913 * \return 0 on success, or MBEDTLS_ERR_SSL_BAD_INPUT_DATA.
\r
2915 int mbedtls_ssl_conf_alpn_protocols( mbedtls_ssl_config *conf, const char **protos );
\r
2918 * \brief Get the name of the negotiated Application Layer Protocol.
\r
2919 * This function should be called after the handshake is
\r
2922 * \param ssl SSL context
\r
2924 * \return Protcol name, or NULL if no protocol was negotiated.
\r
2926 const char *mbedtls_ssl_get_alpn_protocol( const mbedtls_ssl_context *ssl );
\r
2927 #endif /* MBEDTLS_SSL_ALPN */
\r
2930 * \brief Set the maximum supported version sent from the client side
\r
2931 * and/or accepted at the server side
\r
2932 * (Default: MBEDTLS_SSL_MAX_MAJOR_VERSION, MBEDTLS_SSL_MAX_MINOR_VERSION)
\r
2934 * \note This ignores ciphersuites from higher versions.
\r
2936 * \note With DTLS, use MBEDTLS_SSL_MINOR_VERSION_2 for DTLS 1.0 and
\r
2937 * MBEDTLS_SSL_MINOR_VERSION_3 for DTLS 1.2
\r
2939 * \param conf SSL configuration
\r
2940 * \param major Major version number (only MBEDTLS_SSL_MAJOR_VERSION_3 supported)
\r
2941 * \param minor Minor version number (MBEDTLS_SSL_MINOR_VERSION_0,
\r
2942 * MBEDTLS_SSL_MINOR_VERSION_1 and MBEDTLS_SSL_MINOR_VERSION_2,
\r
2943 * MBEDTLS_SSL_MINOR_VERSION_3 supported)
\r
2945 void mbedtls_ssl_conf_max_version( mbedtls_ssl_config *conf, int major, int minor );
\r
2948 * \brief Set the minimum accepted SSL/TLS protocol version
\r
2949 * (Default: TLS 1.0)
\r
2951 * \note Input outside of the SSL_MAX_XXXXX_VERSION and
\r
2952 * SSL_MIN_XXXXX_VERSION range is ignored.
\r
2954 * \note MBEDTLS_SSL_MINOR_VERSION_0 (SSL v3) should be avoided.
\r
2956 * \note With DTLS, use MBEDTLS_SSL_MINOR_VERSION_2 for DTLS 1.0 and
\r
2957 * MBEDTLS_SSL_MINOR_VERSION_3 for DTLS 1.2
\r
2959 * \param conf SSL configuration
\r
2960 * \param major Major version number (only MBEDTLS_SSL_MAJOR_VERSION_3 supported)
\r
2961 * \param minor Minor version number (MBEDTLS_SSL_MINOR_VERSION_0,
\r
2962 * MBEDTLS_SSL_MINOR_VERSION_1 and MBEDTLS_SSL_MINOR_VERSION_2,
\r
2963 * MBEDTLS_SSL_MINOR_VERSION_3 supported)
\r
2965 void mbedtls_ssl_conf_min_version( mbedtls_ssl_config *conf, int major, int minor );
\r
2967 #if defined(MBEDTLS_SSL_FALLBACK_SCSV) && defined(MBEDTLS_SSL_CLI_C)
\r
2969 * \brief Set the fallback flag (client-side only).
\r
2970 * (Default: MBEDTLS_SSL_IS_NOT_FALLBACK).
\r
2972 * \note Set to MBEDTLS_SSL_IS_FALLBACK when preparing a fallback
\r
2973 * connection, that is a connection with max_version set to a
\r
2974 * lower value than the value you're willing to use. Such
\r
2975 * fallback connections are not recommended but are sometimes
\r
2976 * necessary to interoperate with buggy (version-intolerant)
\r
2979 * \warning You should NOT set this to MBEDTLS_SSL_IS_FALLBACK for
\r
2980 * non-fallback connections! This would appear to work for a
\r
2981 * while, then cause failures when the server is upgraded to
\r
2982 * support a newer TLS version.
\r
2984 * \param conf SSL configuration
\r
2985 * \param fallback MBEDTLS_SSL_IS_NOT_FALLBACK or MBEDTLS_SSL_IS_FALLBACK
\r
2987 void mbedtls_ssl_conf_fallback( mbedtls_ssl_config *conf, char fallback );
\r
2988 #endif /* MBEDTLS_SSL_FALLBACK_SCSV && MBEDTLS_SSL_CLI_C */
\r
2990 #if defined(MBEDTLS_SSL_ENCRYPT_THEN_MAC)
\r
2992 * \brief Enable or disable Encrypt-then-MAC
\r
2993 * (Default: MBEDTLS_SSL_ETM_ENABLED)
\r
2995 * \note This should always be enabled, it is a security
\r
2996 * improvement, and should not cause any interoperability
\r
2997 * issue (used only if the peer supports it too).
\r
2999 * \param conf SSL configuration
\r
3000 * \param etm MBEDTLS_SSL_ETM_ENABLED or MBEDTLS_SSL_ETM_DISABLED
\r
3002 void mbedtls_ssl_conf_encrypt_then_mac( mbedtls_ssl_config *conf, char etm );
\r
3003 #endif /* MBEDTLS_SSL_ENCRYPT_THEN_MAC */
\r
3005 #if defined(MBEDTLS_SSL_EXTENDED_MASTER_SECRET)
\r
3007 * \brief Enable or disable Extended Master Secret negotiation.
\r
3008 * (Default: MBEDTLS_SSL_EXTENDED_MS_ENABLED)
\r
3010 * \note This should always be enabled, it is a security fix to the
\r
3011 * protocol, and should not cause any interoperability issue
\r
3012 * (used only if the peer supports it too).
\r
3014 * \param conf SSL configuration
\r
3015 * \param ems MBEDTLS_SSL_EXTENDED_MS_ENABLED or MBEDTLS_SSL_EXTENDED_MS_DISABLED
\r
3017 void mbedtls_ssl_conf_extended_master_secret( mbedtls_ssl_config *conf, char ems );
\r
3018 #endif /* MBEDTLS_SSL_EXTENDED_MASTER_SECRET */
\r
3020 #if defined(MBEDTLS_ARC4_C)
\r
3022 * \brief Disable or enable support for RC4
\r
3023 * (Default: MBEDTLS_SSL_ARC4_DISABLED)
\r
3025 * \warning Use of RC4 in DTLS/TLS has been prohibited by RFC 7465
\r
3026 * for security reasons. Use at your own risk.
\r
3028 * \note This function is deprecated and will likely be removed in
\r
3029 * a future version of the library.
\r
3030 * RC4 is disabled by default at compile time and needs to be
\r
3031 * actively enabled for use with legacy systems.
\r
3033 * \param conf SSL configuration
\r
3034 * \param arc4 MBEDTLS_SSL_ARC4_ENABLED or MBEDTLS_SSL_ARC4_DISABLED
\r
3036 void mbedtls_ssl_conf_arc4_support( mbedtls_ssl_config *conf, char arc4 );
\r
3037 #endif /* MBEDTLS_ARC4_C */
\r
3039 #if defined(MBEDTLS_SSL_SRV_C)
\r
3041 * \brief Whether to send a list of acceptable CAs in
\r
3042 * CertificateRequest messages.
\r
3043 * (Default: do send)
\r
3045 * \param conf SSL configuration
\r
3046 * \param cert_req_ca_list MBEDTLS_SSL_CERT_REQ_CA_LIST_ENABLED or
\r
3047 * MBEDTLS_SSL_CERT_REQ_CA_LIST_DISABLED
\r
3049 void mbedtls_ssl_conf_cert_req_ca_list( mbedtls_ssl_config *conf,
\r
3050 char cert_req_ca_list );
\r
3051 #endif /* MBEDTLS_SSL_SRV_C */
\r
3053 #if defined(MBEDTLS_SSL_MAX_FRAGMENT_LENGTH)
\r
3055 * \brief Set the maximum fragment length to emit and/or negotiate.
\r
3056 * (Typical: the smaller of #MBEDTLS_SSL_IN_CONTENT_LEN and
\r
3057 * #MBEDTLS_SSL_OUT_CONTENT_LEN, usually `2^14` bytes)
\r
3058 * (Server: set maximum fragment length to emit,
\r
3059 * usually negotiated by the client during handshake)
\r
3060 * (Client: set maximum fragment length to emit *and*
\r
3061 * negotiate with the server during handshake)
\r
3062 * (Default: #MBEDTLS_SSL_MAX_FRAG_LEN_NONE)
\r
3064 * \note On the client side, the maximum fragment length extension
\r
3065 * *will not* be used, unless the maximum fragment length has
\r
3066 * been set via this function to a value different than
\r
3067 * #MBEDTLS_SSL_MAX_FRAG_LEN_NONE.
\r
3069 * \note With TLS, this currently only affects ApplicationData (sent
\r
3070 * with \c mbedtls_ssl_read()), not handshake messages.
\r
3071 * With DTLS, this affects both ApplicationData and handshake.
\r
3073 * \note This sets the maximum length for a record's payload,
\r
3074 * excluding record overhead that will be added to it, see
\r
3075 * \c mbedtls_ssl_get_record_expansion().
\r
3077 * \note For DTLS, it is also possible to set a limit for the total
\r
3078 * size of daragrams passed to the transport layer, including
\r
3079 * record overhead, see \c mbedtls_ssl_set_mtu().
\r
3081 * \param conf SSL configuration
\r
3082 * \param mfl_code Code for maximum fragment length (allowed values:
\r
3083 * MBEDTLS_SSL_MAX_FRAG_LEN_512, MBEDTLS_SSL_MAX_FRAG_LEN_1024,
\r
3084 * MBEDTLS_SSL_MAX_FRAG_LEN_2048, MBEDTLS_SSL_MAX_FRAG_LEN_4096)
\r
3086 * \return 0 if successful or MBEDTLS_ERR_SSL_BAD_INPUT_DATA
\r
3088 int mbedtls_ssl_conf_max_frag_len( mbedtls_ssl_config *conf, unsigned char mfl_code );
\r
3089 #endif /* MBEDTLS_SSL_MAX_FRAGMENT_LENGTH */
\r
3091 #if defined(MBEDTLS_SSL_TRUNCATED_HMAC)
\r
3093 * \brief Activate negotiation of truncated HMAC
\r
3094 * (Default: MBEDTLS_SSL_TRUNC_HMAC_DISABLED)
\r
3096 * \param conf SSL configuration
\r
3097 * \param truncate Enable or disable (MBEDTLS_SSL_TRUNC_HMAC_ENABLED or
\r
3098 * MBEDTLS_SSL_TRUNC_HMAC_DISABLED)
\r
3100 void mbedtls_ssl_conf_truncated_hmac( mbedtls_ssl_config *conf, int truncate );
\r
3101 #endif /* MBEDTLS_SSL_TRUNCATED_HMAC */
\r
3103 #if defined(MBEDTLS_SSL_CBC_RECORD_SPLITTING)
\r
3105 * \brief Enable / Disable 1/n-1 record splitting
\r
3106 * (Default: MBEDTLS_SSL_CBC_RECORD_SPLITTING_ENABLED)
\r
3108 * \note Only affects SSLv3 and TLS 1.0, not higher versions.
\r
3109 * Does not affect non-CBC ciphersuites in any version.
\r
3111 * \param conf SSL configuration
\r
3112 * \param split MBEDTLS_SSL_CBC_RECORD_SPLITTING_ENABLED or
\r
3113 * MBEDTLS_SSL_CBC_RECORD_SPLITTING_DISABLED
\r
3115 void mbedtls_ssl_conf_cbc_record_splitting( mbedtls_ssl_config *conf, char split );
\r
3116 #endif /* MBEDTLS_SSL_CBC_RECORD_SPLITTING */
\r
3118 #if defined(MBEDTLS_SSL_SESSION_TICKETS) && defined(MBEDTLS_SSL_CLI_C)
\r
3120 * \brief Enable / Disable session tickets (client only).
\r
3121 * (Default: MBEDTLS_SSL_SESSION_TICKETS_ENABLED.)
\r
3123 * \note On server, use \c mbedtls_ssl_conf_session_tickets_cb().
\r
3125 * \param conf SSL configuration
\r
3126 * \param use_tickets Enable or disable (MBEDTLS_SSL_SESSION_TICKETS_ENABLED or
\r
3127 * MBEDTLS_SSL_SESSION_TICKETS_DISABLED)
\r
3129 void mbedtls_ssl_conf_session_tickets( mbedtls_ssl_config *conf, int use_tickets );
\r
3130 #endif /* MBEDTLS_SSL_SESSION_TICKETS && MBEDTLS_SSL_CLI_C */
\r
3132 #if defined(MBEDTLS_SSL_RENEGOTIATION)
\r
3134 * \brief Enable / Disable renegotiation support for connection when
\r
3135 * initiated by peer
\r
3136 * (Default: MBEDTLS_SSL_RENEGOTIATION_DISABLED)
\r
3138 * \warning It is recommended to always disable renegotation unless you
\r
3139 * know you need it and you know what you're doing. In the
\r
3140 * past, there have been several issues associated with
\r
3141 * renegotiation or a poor understanding of its properties.
\r
3143 * \note Server-side, enabling renegotiation also makes the server
\r
3144 * susceptible to a resource DoS by a malicious client.
\r
3146 * \param conf SSL configuration
\r
3147 * \param renegotiation Enable or disable (MBEDTLS_SSL_RENEGOTIATION_ENABLED or
\r
3148 * MBEDTLS_SSL_RENEGOTIATION_DISABLED)
\r
3150 void mbedtls_ssl_conf_renegotiation( mbedtls_ssl_config *conf, int renegotiation );
\r
3151 #endif /* MBEDTLS_SSL_RENEGOTIATION */
\r
3154 * \brief Prevent or allow legacy renegotiation.
\r
3155 * (Default: MBEDTLS_SSL_LEGACY_NO_RENEGOTIATION)
\r
3157 * MBEDTLS_SSL_LEGACY_NO_RENEGOTIATION allows connections to
\r
3158 * be established even if the peer does not support
\r
3159 * secure renegotiation, but does not allow renegotiation
\r
3160 * to take place if not secure.
\r
3161 * (Interoperable and secure option)
\r
3163 * MBEDTLS_SSL_LEGACY_ALLOW_RENEGOTIATION allows renegotiations
\r
3164 * with non-upgraded peers. Allowing legacy renegotiation
\r
3165 * makes the connection vulnerable to specific man in the
\r
3166 * middle attacks. (See RFC 5746)
\r
3167 * (Most interoperable and least secure option)
\r
3169 * MBEDTLS_SSL_LEGACY_BREAK_HANDSHAKE breaks off connections
\r
3170 * if peer does not support secure renegotiation. Results
\r
3171 * in interoperability issues with non-upgraded peers
\r
3172 * that do not support renegotiation altogether.
\r
3173 * (Most secure option, interoperability issues)
\r
3175 * \param conf SSL configuration
\r
3176 * \param allow_legacy Prevent or allow (SSL_NO_LEGACY_RENEGOTIATION,
\r
3177 * SSL_ALLOW_LEGACY_RENEGOTIATION or
\r
3178 * MBEDTLS_SSL_LEGACY_BREAK_HANDSHAKE)
\r
3180 void mbedtls_ssl_conf_legacy_renegotiation( mbedtls_ssl_config *conf, int allow_legacy );
\r
3182 #if defined(MBEDTLS_SSL_RENEGOTIATION)
\r
3184 * \brief Enforce renegotiation requests.
\r
3185 * (Default: enforced, max_records = 16)
\r
3187 * When we request a renegotiation, the peer can comply or
\r
3188 * ignore the request. This function allows us to decide
\r
3189 * whether to enforce our renegotiation requests by closing
\r
3190 * the connection if the peer doesn't comply.
\r
3192 * However, records could already be in transit from the peer
\r
3193 * when the request is emitted. In order to increase
\r
3194 * reliability, we can accept a number of records before the
\r
3195 * expected handshake records.
\r
3197 * The optimal value is highly dependent on the specific usage
\r
3200 * \note With DTLS and server-initiated renegotiation, the
\r
3201 * HelloRequest is retransmited every time mbedtls_ssl_read() times
\r
3202 * out or receives Application Data, until:
\r
3203 * - max_records records have beens seen, if it is >= 0, or
\r
3204 * - the number of retransmits that would happen during an
\r
3205 * actual handshake has been reached.
\r
3206 * Please remember the request might be lost a few times
\r
3207 * if you consider setting max_records to a really low value.
\r
3209 * \warning On client, the grace period can only happen during
\r
3210 * mbedtls_ssl_read(), as opposed to mbedtls_ssl_write() and mbedtls_ssl_renegotiate()
\r
3211 * which always behave as if max_record was 0. The reason is,
\r
3212 * if we receive application data from the server, we need a
\r
3213 * place to write it, which only happens during mbedtls_ssl_read().
\r
3215 * \param conf SSL configuration
\r
3216 * \param max_records Use MBEDTLS_SSL_RENEGOTIATION_NOT_ENFORCED if you don't want to
\r
3217 * enforce renegotiation, or a non-negative value to enforce
\r
3218 * it but allow for a grace period of max_records records.
\r
3220 void mbedtls_ssl_conf_renegotiation_enforced( mbedtls_ssl_config *conf, int max_records );
\r
3223 * \brief Set record counter threshold for periodic renegotiation.
\r
3224 * (Default: 2^48 - 1)
\r
3226 * Renegotiation is automatically triggered when a record
\r
3227 * counter (outgoing or incoming) crosses the defined
\r
3228 * threshold. The default value is meant to prevent the
\r
3229 * connection from being closed when the counter is about to
\r
3230 * reached its maximal value (it is not allowed to wrap).
\r
3232 * Lower values can be used to enforce policies such as "keys
\r
3233 * must be refreshed every N packets with cipher X".
\r
3235 * The renegotiation period can be disabled by setting
\r
3236 * conf->disable_renegotiation to
\r
3237 * MBEDTLS_SSL_RENEGOTIATION_DISABLED.
\r
3239 * \note When the configured transport is
\r
3240 * MBEDTLS_SSL_TRANSPORT_DATAGRAM the maximum renegotiation
\r
3241 * period is 2^48 - 1, and for MBEDTLS_SSL_TRANSPORT_STREAM,
\r
3242 * the maximum renegotiation period is 2^64 - 1.
\r
3244 * \param conf SSL configuration
\r
3245 * \param period The threshold value: a big-endian 64-bit number.
\r
3247 void mbedtls_ssl_conf_renegotiation_period( mbedtls_ssl_config *conf,
\r
3248 const unsigned char period[8] );
\r
3249 #endif /* MBEDTLS_SSL_RENEGOTIATION */
\r
3252 * \brief Check if there is data already read from the
\r
3253 * underlying transport but not yet processed.
\r
3255 * \param ssl SSL context
\r
3257 * \return 0 if nothing's pending, 1 otherwise.
\r
3259 * \note This is different in purpose and behaviour from
\r
3260 * \c mbedtls_ssl_get_bytes_avail in that it considers
\r
3261 * any kind of unprocessed data, not only unread
\r
3262 * application data. If \c mbedtls_ssl_get_bytes
\r
3263 * returns a non-zero value, this function will
\r
3264 * also signal pending data, but the converse does
\r
3265 * not hold. For example, in DTLS there might be
\r
3266 * further records waiting to be processed from
\r
3267 * the current underlying transport's datagram.
\r
3269 * \note If this function returns 1 (data pending), this
\r
3270 * does not imply that a subsequent call to
\r
3271 * \c mbedtls_ssl_read will provide any data;
\r
3272 * e.g., the unprocessed data might turn out
\r
3273 * to be an alert or a handshake message.
\r
3275 * \note This function is useful in the following situation:
\r
3276 * If the SSL/TLS module successfully returns from an
\r
3277 * operation - e.g. a handshake or an application record
\r
3278 * read - and you're awaiting incoming data next, you
\r
3279 * must not immediately idle on the underlying transport
\r
3280 * to have data ready, but you need to check the value
\r
3281 * of this function first. The reason is that the desired
\r
3282 * data might already be read but not yet processed.
\r
3283 * If, in contrast, a previous call to the SSL/TLS module
\r
3284 * returned MBEDTLS_ERR_SSL_WANT_READ, it is not necessary
\r
3285 * to call this function, as the latter error code entails
\r
3286 * that all internal data has been processed.
\r
3289 int mbedtls_ssl_check_pending( const mbedtls_ssl_context *ssl );
\r
3292 * \brief Return the number of application data bytes
\r
3293 * remaining to be read from the current record.
\r
3295 * \param ssl SSL context
\r
3297 * \return How many bytes are available in the application
\r
3298 * data record read buffer.
\r
3300 * \note When working over a datagram transport, this is
\r
3301 * useful to detect the current datagram's boundary
\r
3302 * in case \c mbedtls_ssl_read has written the maximal
\r
3303 * amount of data fitting into the input buffer.
\r
3306 size_t mbedtls_ssl_get_bytes_avail( const mbedtls_ssl_context *ssl );
\r
3309 * \brief Return the result of the certificate verification
\r
3311 * \param ssl The SSL context to use.
\r
3313 * \return \c 0 if the certificate verification was successful.
\r
3314 * \return \c -1u if the result is not available. This may happen
\r
3315 * e.g. if the handshake aborts early, or a verification
\r
3316 * callback returned a fatal error.
\r
3317 * \return A bitwise combination of \c MBEDTLS_X509_BADCERT_XXX
\r
3318 * and \c MBEDTLS_X509_BADCRL_XXX failure flags; see x509.h.
\r
3320 uint32_t mbedtls_ssl_get_verify_result( const mbedtls_ssl_context *ssl );
\r
3323 * \brief Return the name of the current ciphersuite
\r
3325 * \param ssl SSL context
\r
3327 * \return a string containing the ciphersuite name
\r
3329 const char *mbedtls_ssl_get_ciphersuite( const mbedtls_ssl_context *ssl );
\r
3332 * \brief Return the current SSL version (SSLv3/TLSv1/etc)
\r
3334 * \param ssl SSL context
\r
3336 * \return a string containing the SSL version
\r
3338 const char *mbedtls_ssl_get_version( const mbedtls_ssl_context *ssl );
\r
3341 * \brief Return the (maximum) number of bytes added by the record
\r
3342 * layer: header + encryption/MAC overhead (inc. padding)
\r
3344 * \note This function is not available (always returns an error)
\r
3345 * when record compression is enabled.
\r
3347 * \param ssl SSL context
\r
3349 * \return Current maximum record expansion in bytes, or
\r
3350 * MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE if compression is
\r
3351 * enabled, which makes expansion much less predictable
\r
3353 int mbedtls_ssl_get_record_expansion( const mbedtls_ssl_context *ssl );
\r
3355 #if defined(MBEDTLS_SSL_MAX_FRAGMENT_LENGTH)
\r
3357 * \brief Return the maximum fragment length (payload, in bytes).
\r
3358 * This is the value negotiated with peer if any,
\r
3359 * or the locally configured value.
\r
3361 * \sa mbedtls_ssl_conf_max_frag_len()
\r
3362 * \sa mbedtls_ssl_get_max_record_payload()
\r
3364 * \param ssl SSL context
\r
3366 * \return Current maximum fragment length.
\r
3368 size_t mbedtls_ssl_get_max_frag_len( const mbedtls_ssl_context *ssl );
\r
3369 #endif /* MBEDTLS_SSL_MAX_FRAGMENT_LENGTH */
\r
3372 * \brief Return the current maximum outgoing record payload in bytes.
\r
3373 * This takes into account the config.h setting \c
\r
3374 * MBEDTLS_SSL_OUT_CONTENT_LEN, the configured and negotiated
\r
3375 * max fragment length extension if used, and for DTLS the
\r
3376 * path MTU as configured and current record expansion.
\r
3378 * \note With DTLS, \c mbedtls_ssl_write() will return an error if
\r
3379 * called with a larger length value.
\r
3380 * With TLS, \c mbedtls_ssl_write() will fragment the input if
\r
3381 * necessary and return the number of bytes written; it is up
\r
3382 * to the caller to call \c mbedtls_ssl_write() again in
\r
3383 * order to send the remaining bytes if any.
\r
3385 * \note This function is not available (always returns an error)
\r
3386 * when record compression is enabled.
\r
3388 * \sa mbedtls_ssl_set_mtu()
\r
3389 * \sa mbedtls_ssl_get_max_frag_len()
\r
3390 * \sa mbedtls_ssl_get_record_expansion()
\r
3392 * \param ssl SSL context
\r
3394 * \return Current maximum payload for an outgoing record,
\r
3395 * or a negative error code.
\r
3397 int mbedtls_ssl_get_max_out_record_payload( const mbedtls_ssl_context *ssl );
\r
3399 #if defined(MBEDTLS_X509_CRT_PARSE_C)
\r
3401 * \brief Return the peer certificate from the current connection.
\r
3403 * \param ssl The SSL context to use. This must be initialized and setup.
\r
3405 * \return The current peer certificate, if available.
\r
3406 * The returned certificate is owned by the SSL context and
\r
3407 * is valid only until the next call to the SSL API.
\r
3408 * \return \c NULL if no peer certificate is available. This might
\r
3409 * be because the chosen ciphersuite doesn't use CRTs
\r
3410 * (PSK-based ciphersuites, for example), or because
\r
3411 * #MBEDTLS_SSL_KEEP_PEER_CERTIFICATE has been disabled,
\r
3412 * allowing the stack to free the peer's CRT to save memory.
\r
3414 * \note For one-time inspection of the peer's certificate during
\r
3415 * the handshake, consider registering an X.509 CRT verification
\r
3416 * callback through mbedtls_ssl_conf_verify() instead of calling
\r
3417 * this function. Using mbedtls_ssl_conf_verify() also comes at
\r
3418 * the benefit of allowing you to influence the verification
\r
3419 * process, for example by masking expected and tolerated
\r
3420 * verification failures.
\r
3422 * \warning You must not use the pointer returned by this function
\r
3423 * after any further call to the SSL API, including
\r
3424 * mbedtls_ssl_read() and mbedtls_ssl_write(); this is
\r
3425 * because the pointer might change during renegotiation,
\r
3426 * which happens transparently to the user.
\r
3427 * If you want to use the certificate across API calls,
\r
3428 * you must make a copy.
\r
3430 const mbedtls_x509_crt *mbedtls_ssl_get_peer_cert( const mbedtls_ssl_context *ssl );
\r
3431 #endif /* MBEDTLS_X509_CRT_PARSE_C */
\r
3433 #if defined(MBEDTLS_SSL_CLI_C)
\r
3435 * \brief Save session in order to resume it later (client-side only)
\r
3436 * Session data is copied to presented session structure.
\r
3439 * \param ssl SSL context
\r
3440 * \param session session context
\r
3442 * \return 0 if successful,
\r
3443 * MBEDTLS_ERR_SSL_ALLOC_FAILED if memory allocation failed,
\r
3444 * MBEDTLS_ERR_SSL_BAD_INPUT_DATA if used server-side or
\r
3445 * arguments are otherwise invalid.
\r
3447 * \note Only the server certificate is copied, and not the full chain,
\r
3448 * so you should not attempt to validate the certificate again
\r
3449 * by calling \c mbedtls_x509_crt_verify() on it.
\r
3450 * Instead, you should use the results from the verification
\r
3451 * in the original handshake by calling \c mbedtls_ssl_get_verify_result()
\r
3452 * after loading the session again into a new SSL context
\r
3453 * using \c mbedtls_ssl_set_session().
\r
3455 * \note Once the session object is not needed anymore, you should
\r
3456 * free it by calling \c mbedtls_ssl_session_free().
\r
3458 * \sa mbedtls_ssl_set_session()
\r
3460 int mbedtls_ssl_get_session( const mbedtls_ssl_context *ssl, mbedtls_ssl_session *session );
\r
3461 #endif /* MBEDTLS_SSL_CLI_C */
\r
3464 * \brief Perform the SSL handshake
\r
3466 * \param ssl SSL context
\r
3468 * \return \c 0 if successful.
\r
3469 * \return #MBEDTLS_ERR_SSL_WANT_READ or #MBEDTLS_ERR_SSL_WANT_WRITE
\r
3470 * if the handshake is incomplete and waiting for data to
\r
3471 * be available for reading from or writing to the underlying
\r
3472 * transport - in this case you must call this function again
\r
3473 * when the underlying transport is ready for the operation.
\r
3474 * \return #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS if an asynchronous
\r
3475 * operation is in progress (see
\r
3476 * mbedtls_ssl_conf_async_private_cb()) - in this case you
\r
3477 * must call this function again when the operation is ready.
\r
3478 * \return #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS if a cryptographic
\r
3479 * operation is in progress (see mbedtls_ecp_set_max_ops()) -
\r
3480 * in this case you must call this function again to complete
\r
3481 * the handshake when you're done attending other tasks.
\r
3482 * \return #MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED if DTLS is in use
\r
3483 * and the client did not demonstrate reachability yet - in
\r
3484 * this case you must stop using the context (see below).
\r
3485 * \return Another SSL error code - in this case you must stop using
\r
3486 * the context (see below).
\r
3488 * \warning If this function returns something other than
\r
3490 * #MBEDTLS_ERR_SSL_WANT_READ,
\r
3491 * #MBEDTLS_ERR_SSL_WANT_WRITE,
\r
3492 * #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS or
\r
3493 * #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS,
\r
3494 * you must stop using the SSL context for reading or writing,
\r
3495 * and either free it or call \c mbedtls_ssl_session_reset()
\r
3496 * on it before re-using it for a new connection; the current
\r
3497 * connection must be closed.
\r
3499 * \note If DTLS is in use, then you may choose to handle
\r
3500 * #MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED specially for logging
\r
3501 * purposes, as it is an expected return value rather than an
\r
3502 * actual error, but you still need to reset/free the context.
\r
3504 * \note Remarks regarding event-driven DTLS:
\r
3505 * If the function returns #MBEDTLS_ERR_SSL_WANT_READ, no datagram
\r
3506 * from the underlying transport layer is currently being processed,
\r
3507 * and it is safe to idle until the timer or the underlying transport
\r
3508 * signal a new event. This is not true for a successful handshake,
\r
3509 * in which case the datagram of the underlying transport that is
\r
3510 * currently being processed might or might not contain further
\r
3513 int mbedtls_ssl_handshake( mbedtls_ssl_context *ssl );
\r
3516 * \brief Perform a single step of the SSL handshake
\r
3518 * \note The state of the context (ssl->state) will be at
\r
3519 * the next state after this function returns \c 0. Do not
\r
3520 * call this function if state is MBEDTLS_SSL_HANDSHAKE_OVER.
\r
3522 * \param ssl SSL context
\r
3524 * \return See mbedtls_ssl_handshake().
\r
3526 * \warning If this function returns something other than \c 0,
\r
3527 * #MBEDTLS_ERR_SSL_WANT_READ, #MBEDTLS_ERR_SSL_WANT_WRITE,
\r
3528 * #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS or
\r
3529 * #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS, you must stop using
\r
3530 * the SSL context for reading or writing, and either free it
\r
3531 * or call \c mbedtls_ssl_session_reset() on it before
\r
3532 * re-using it for a new connection; the current connection
\r
3535 int mbedtls_ssl_handshake_step( mbedtls_ssl_context *ssl );
\r
3537 #if defined(MBEDTLS_SSL_RENEGOTIATION)
\r
3539 * \brief Initiate an SSL renegotiation on the running connection.
\r
3540 * Client: perform the renegotiation right now.
\r
3541 * Server: request renegotiation, which will be performed
\r
3542 * during the next call to mbedtls_ssl_read() if honored by
\r
3545 * \param ssl SSL context
\r
3547 * \return 0 if successful, or any mbedtls_ssl_handshake() return
\r
3548 * value except #MBEDTLS_ERR_SSL_CLIENT_RECONNECT that can't
\r
3549 * happen during a renegotiation.
\r
3551 * \warning If this function returns something other than \c 0,
\r
3552 * #MBEDTLS_ERR_SSL_WANT_READ, #MBEDTLS_ERR_SSL_WANT_WRITE,
\r
3553 * #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS or
\r
3554 * #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS, you must stop using
\r
3555 * the SSL context for reading or writing, and either free it
\r
3556 * or call \c mbedtls_ssl_session_reset() on it before
\r
3557 * re-using it for a new connection; the current connection
\r
3561 int mbedtls_ssl_renegotiate( mbedtls_ssl_context *ssl );
\r
3562 #endif /* MBEDTLS_SSL_RENEGOTIATION */
\r
3565 * \brief Read at most 'len' application data bytes
\r
3567 * \param ssl SSL context
\r
3568 * \param buf buffer that will hold the data
\r
3569 * \param len maximum number of bytes to read
\r
3571 * \return The (positive) number of bytes read if successful.
\r
3572 * \return \c 0 if the read end of the underlying transport was closed
\r
3573 * - in this case you must stop using the context (see below).
\r
3574 * \return #MBEDTLS_ERR_SSL_WANT_READ or #MBEDTLS_ERR_SSL_WANT_WRITE
\r
3575 * if the handshake is incomplete and waiting for data to
\r
3576 * be available for reading from or writing to the underlying
\r
3577 * transport - in this case you must call this function again
\r
3578 * when the underlying transport is ready for the operation.
\r
3579 * \return #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS if an asynchronous
\r
3580 * operation is in progress (see
\r
3581 * mbedtls_ssl_conf_async_private_cb()) - in this case you
\r
3582 * must call this function again when the operation is ready.
\r
3583 * \return #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS if a cryptographic
\r
3584 * operation is in progress (see mbedtls_ecp_set_max_ops()) -
\r
3585 * in this case you must call this function again to complete
\r
3586 * the handshake when you're done attending other tasks.
\r
3587 * \return #MBEDTLS_ERR_SSL_CLIENT_RECONNECT if we're at the server
\r
3588 * side of a DTLS connection and the client is initiating a
\r
3589 * new connection using the same source port. See below.
\r
3590 * \return Another SSL error code - in this case you must stop using
\r
3591 * the context (see below).
\r
3593 * \warning If this function returns something other than
\r
3594 * a positive value,
\r
3595 * #MBEDTLS_ERR_SSL_WANT_READ,
\r
3596 * #MBEDTLS_ERR_SSL_WANT_WRITE,
\r
3597 * #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS,
\r
3598 * #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS or
\r
3599 * #MBEDTLS_ERR_SSL_CLIENT_RECONNECT,
\r
3600 * you must stop using the SSL context for reading or writing,
\r
3601 * and either free it or call \c mbedtls_ssl_session_reset()
\r
3602 * on it before re-using it for a new connection; the current
\r
3603 * connection must be closed.
\r
3605 * \note When this function returns #MBEDTLS_ERR_SSL_CLIENT_RECONNECT
\r
3606 * (which can only happen server-side), it means that a client
\r
3607 * is initiating a new connection using the same source port.
\r
3608 * You can either treat that as a connection close and wait
\r
3609 * for the client to resend a ClientHello, or directly
\r
3610 * continue with \c mbedtls_ssl_handshake() with the same
\r
3611 * context (as it has been reset internally). Either way, you
\r
3612 * must make sure this is seen by the application as a new
\r
3613 * connection: application state, if any, should be reset, and
\r
3614 * most importantly the identity of the client must be checked
\r
3615 * again. WARNING: not validating the identity of the client
\r
3616 * again, or not transmitting the new identity to the
\r
3617 * application layer, would allow authentication bypass!
\r
3619 * \note Remarks regarding event-driven DTLS:
\r
3620 * - If the function returns #MBEDTLS_ERR_SSL_WANT_READ, no datagram
\r
3621 * from the underlying transport layer is currently being processed,
\r
3622 * and it is safe to idle until the timer or the underlying transport
\r
3623 * signal a new event.
\r
3624 * - This function may return MBEDTLS_ERR_SSL_WANT_READ even if data was
\r
3625 * initially available on the underlying transport, as this data may have
\r
3626 * been only e.g. duplicated messages or a renegotiation request.
\r
3627 * Therefore, you must be prepared to receive MBEDTLS_ERR_SSL_WANT_READ even
\r
3628 * when reacting to an incoming-data event from the underlying transport.
\r
3629 * - On success, the datagram of the underlying transport that is currently
\r
3630 * being processed may contain further DTLS records. You should call
\r
3631 * \c mbedtls_ssl_check_pending to check for remaining records.
\r
3634 int mbedtls_ssl_read( mbedtls_ssl_context *ssl, unsigned char *buf, size_t len );
\r
3637 * \brief Try to write exactly 'len' application data bytes
\r
3639 * \warning This function will do partial writes in some cases. If the
\r
3640 * return value is non-negative but less than length, the
\r
3641 * function must be called again with updated arguments:
\r
3642 * buf + ret, len - ret (if ret is the return value) until
\r
3643 * it returns a value equal to the last 'len' argument.
\r
3645 * \param ssl SSL context
\r
3646 * \param buf buffer holding the data
\r
3647 * \param len how many bytes must be written
\r
3649 * \return The (non-negative) number of bytes actually written if
\r
3650 * successful (may be less than \p len).
\r
3651 * \return #MBEDTLS_ERR_SSL_WANT_READ or #MBEDTLS_ERR_SSL_WANT_WRITE
\r
3652 * if the handshake is incomplete and waiting for data to
\r
3653 * be available for reading from or writing to the underlying
\r
3654 * transport - in this case you must call this function again
\r
3655 * when the underlying transport is ready for the operation.
\r
3656 * \return #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS if an asynchronous
\r
3657 * operation is in progress (see
\r
3658 * mbedtls_ssl_conf_async_private_cb()) - in this case you
\r
3659 * must call this function again when the operation is ready.
\r
3660 * \return #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS if a cryptographic
\r
3661 * operation is in progress (see mbedtls_ecp_set_max_ops()) -
\r
3662 * in this case you must call this function again to complete
\r
3663 * the handshake when you're done attending other tasks.
\r
3664 * \return Another SSL error code - in this case you must stop using
\r
3665 * the context (see below).
\r
3667 * \warning If this function returns something other than
\r
3668 * a non-negative value,
\r
3669 * #MBEDTLS_ERR_SSL_WANT_READ,
\r
3670 * #MBEDTLS_ERR_SSL_WANT_WRITE,
\r
3671 * #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS or
\r
3672 * #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS,
\r
3673 * you must stop using the SSL context for reading or writing,
\r
3674 * and either free it or call \c mbedtls_ssl_session_reset()
\r
3675 * on it before re-using it for a new connection; the current
\r
3676 * connection must be closed.
\r
3678 * \note When this function returns #MBEDTLS_ERR_SSL_WANT_WRITE/READ,
\r
3679 * it must be called later with the *same* arguments,
\r
3680 * until it returns a value greater that or equal to 0. When
\r
3681 * the function returns #MBEDTLS_ERR_SSL_WANT_WRITE there may be
\r
3682 * some partial data in the output buffer, however this is not
\r
3685 * \note If the requested length is greater than the maximum
\r
3686 * fragment length (either the built-in limit or the one set
\r
3687 * or negotiated with the peer), then:
\r
3688 * - with TLS, less bytes than requested are written.
\r
3689 * - with DTLS, MBEDTLS_ERR_SSL_BAD_INPUT_DATA is returned.
\r
3690 * \c mbedtls_ssl_get_max_frag_len() may be used to query the
\r
3691 * active maximum fragment length.
\r
3693 * \note Attempting to write 0 bytes will result in an empty TLS
\r
3694 * application record being sent.
\r
3696 int mbedtls_ssl_write( mbedtls_ssl_context *ssl, const unsigned char *buf, size_t len );
\r
3699 * \brief Send an alert message
\r
3701 * \param ssl SSL context
\r
3702 * \param level The alert level of the message
\r
3703 * (MBEDTLS_SSL_ALERT_LEVEL_WARNING or MBEDTLS_SSL_ALERT_LEVEL_FATAL)
\r
3704 * \param message The alert message (SSL_ALERT_MSG_*)
\r
3706 * \return 0 if successful, or a specific SSL error code.
\r
3708 * \note If this function returns something other than 0 or
\r
3709 * MBEDTLS_ERR_SSL_WANT_READ/WRITE, you must stop using
\r
3710 * the SSL context for reading or writing, and either free it or
\r
3711 * call \c mbedtls_ssl_session_reset() on it before re-using it
\r
3712 * for a new connection; the current connection must be closed.
\r
3714 int mbedtls_ssl_send_alert_message( mbedtls_ssl_context *ssl,
\r
3715 unsigned char level,
\r
3716 unsigned char message );
\r
3718 * \brief Notify the peer that the connection is being closed
\r
3720 * \param ssl SSL context
\r
3722 * \return 0 if successful, or a specific SSL error code.
\r
3724 * \note If this function returns something other than 0 or
\r
3725 * MBEDTLS_ERR_SSL_WANT_READ/WRITE, you must stop using
\r
3726 * the SSL context for reading or writing, and either free it or
\r
3727 * call \c mbedtls_ssl_session_reset() on it before re-using it
\r
3728 * for a new connection; the current connection must be closed.
\r
3730 int mbedtls_ssl_close_notify( mbedtls_ssl_context *ssl );
\r
3733 * \brief Free referenced items in an SSL context and clear memory
\r
3735 * \param ssl SSL context
\r
3737 void mbedtls_ssl_free( mbedtls_ssl_context *ssl );
\r
3740 * \brief Initialize an SSL configuration context
\r
3741 * Just makes the context ready for
\r
3742 * mbedtls_ssl_config_defaults() or mbedtls_ssl_config_free().
\r
3744 * \note You need to call mbedtls_ssl_config_defaults() unless you
\r
3745 * manually set all of the relevant fields yourself.
\r
3747 * \param conf SSL configuration context
\r
3749 void mbedtls_ssl_config_init( mbedtls_ssl_config *conf );
\r
3752 * \brief Load reasonnable default SSL configuration values.
\r
3753 * (You need to call mbedtls_ssl_config_init() first.)
\r
3755 * \param conf SSL configuration context
\r
3756 * \param endpoint MBEDTLS_SSL_IS_CLIENT or MBEDTLS_SSL_IS_SERVER
\r
3757 * \param transport MBEDTLS_SSL_TRANSPORT_STREAM for TLS, or
\r
3758 * MBEDTLS_SSL_TRANSPORT_DATAGRAM for DTLS
\r
3759 * \param preset a MBEDTLS_SSL_PRESET_XXX value
\r
3761 * \note See \c mbedtls_ssl_conf_transport() for notes on DTLS.
\r
3763 * \return 0 if successful, or
\r
3764 * MBEDTLS_ERR_XXX_ALLOC_FAILED on memory allocation error.
\r
3766 int mbedtls_ssl_config_defaults( mbedtls_ssl_config *conf,
\r
3767 int endpoint, int transport, int preset );
\r
3770 * \brief Free an SSL configuration context
\r
3772 * \param conf SSL configuration context
\r
3774 void mbedtls_ssl_config_free( mbedtls_ssl_config *conf );
\r
3777 * \brief Initialize SSL session structure
\r
3779 * \param session SSL session
\r
3781 void mbedtls_ssl_session_init( mbedtls_ssl_session *session );
\r
3784 * \brief Free referenced items in an SSL session including the
\r
3785 * peer certificate and clear memory
\r
3787 * \note A session object can be freed even if the SSL context
\r
3788 * that was used to retrieve the session is still in use.
\r
3790 * \param session SSL session
\r
3792 void mbedtls_ssl_session_free( mbedtls_ssl_session *session );
\r
3795 * \brief TLS-PRF function for key derivation.
\r
3797 * \param prf The tls_prf type funtion type to be used.
\r
3798 * \param secret Secret for the key derivation function.
\r
3799 * \param slen Length of the secret.
\r
3800 * \param label String label for the key derivation function,
\r
3801 * terminated with null character.
\r
3802 * \param random Random bytes.
\r
3803 * \param rlen Length of the random bytes buffer.
\r
3804 * \param dstbuf The buffer holding the derived key.
\r
3805 * \param dlen Length of the output buffer.
\r
3807 * \return 0 on sucess. An SSL specific error on failure.
\r
3809 int mbedtls_ssl_tls_prf( const mbedtls_tls_prf_types prf,
\r
3810 const unsigned char *secret, size_t slen,
\r
3811 const char *label,
\r
3812 const unsigned char *random, size_t rlen,
\r
3813 unsigned char *dstbuf, size_t dlen );
\r
3815 #ifdef __cplusplus
\r
3819 #endif /* ssl.h */
\r
projects / freertos / blob