Detailed Description
SSL/TLS functions.
Copyright (C) 2006-2015, ARM Limited, All Rights Reserved SPDX-License-Identifier: Apache-2.0
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
This file is part of mbed TLS (https://tls.mbed.org)
Definition in file ssl.h.
#include <config-sl-crypto-all-acceleration.h>#include "bignum.h"#include "ecp.h"#include "ssl_ciphersuites.h"
Include dependency graph for ssl.h:
This graph shows which files directly or indirectly include this file:
Go to the source code of this file.
Data Structures | |
| union | mbedtls_ssl_premaster_secret |
| struct | mbedtls_ssl_session |
| struct | mbedtls_ssl_config |
| SSL/TLS configuration to be shared between mbedtls_ssl_context structures. More... | |
| struct | mbedtls_ssl_context |
Typedefs | |
| typedef struct mbedtls_ssl_session | mbedtls_ssl_session |
| typedef struct mbedtls_ssl_context | mbedtls_ssl_context |
| typedef struct mbedtls_ssl_config | mbedtls_ssl_config |
| typedef struct mbedtls_ssl_transform | mbedtls_ssl_transform |
| typedef struct mbedtls_ssl_handshake_params | mbedtls_ssl_handshake_params |
| typedef int | mbedtls_ssl_ticket_write_t(void *p_ticket, const mbedtls_ssl_session *session, unsigned char *start, const unsigned char *end, size_t *tlen, uint32_t *lifetime) |
| Callback type: generate and write session ticket. More... | |
| typedef int | mbedtls_ssl_ticket_parse_t(void *p_ticket, mbedtls_ssl_session *session, unsigned char *buf, size_t len) |
| Callback type: parse and load session ticket. More... | |
| typedef int | mbedtls_ssl_cookie_write_t(void *ctx, unsigned char **p, unsigned char *end, const unsigned char *info, size_t ilen) |
| Callback type: generate a cookie. More... | |
| typedef int | mbedtls_ssl_cookie_check_t(void *ctx, const unsigned char *cookie, size_t clen, const unsigned char *info, size_t ilen) |
| Callback type: verify a cookie. More... | |
Functions | |
| const int * | mbedtls_ssl_list_ciphersuites (void) |
| Returns the list of ciphersuites supported by the SSL/TLS module. More... | |
| const char * | mbedtls_ssl_get_ciphersuite_name (const int ciphersuite_id) |
| Return the name of the ciphersuite associated with the given ID. More... | |
| int | mbedtls_ssl_get_ciphersuite_id (const char *ciphersuite_name) |
| Return the ID of the ciphersuite associated with the given name. More... | |
| void | mbedtls_ssl_init (mbedtls_ssl_context *ssl) |
| Initialize an SSL context Just makes the context ready for mbedtls_ssl_setup() or mbedtls_ssl_free() More... | |
| int | mbedtls_ssl_setup (mbedtls_ssl_context *ssl, const mbedtls_ssl_config *conf) |
| Set up an SSL context for use. More... | |
| int | mbedtls_ssl_session_reset (mbedtls_ssl_context *ssl) |
| Reset an already initialized SSL context for re-use while retaining application-set variables, function pointers and data. More... | |
| void | mbedtls_ssl_conf_endpoint (mbedtls_ssl_config *conf, int endpoint) |
| Set the current endpoint type. More... | |
| void | mbedtls_ssl_conf_transport (mbedtls_ssl_config *conf, int transport) |
| Set the transport type (TLS or DTLS). More... | |
| void | mbedtls_ssl_conf_authmode (mbedtls_ssl_config *conf, int authmode) |
| Set the certificate verification mode Default: NONE on server, REQUIRED on client. More... | |
| void | mbedtls_ssl_conf_rng (mbedtls_ssl_config *conf, int(*f_rng)(void *, unsigned char *, size_t), void *p_rng) |
| Set the random number generator callback. More... | |
| void | mbedtls_ssl_conf_dbg (mbedtls_ssl_config *conf, void(*f_dbg)(void *, int, const char *, int, const char *), void *p_dbg) |
| Set the debug callback. More... | |
| void | mbedtls_ssl_set_bio (mbedtls_ssl_context *ssl, void *p_bio, int(*f_send)(void *, const unsigned char *, size_t), int(*f_recv)(void *, unsigned char *, size_t), int(*f_recv_timeout)(void *, unsigned char *, size_t, uint32_t)) |
| Set the underlying BIO callbacks for write, read and read-with-timeout. More... | |
| void | mbedtls_ssl_conf_read_timeout (mbedtls_ssl_config *conf, uint32_t timeout) |
| Set the timeout period for mbedtls_ssl_read() (Default: no timeout.) More... | |
| void | mbedtls_ssl_set_timer_cb (mbedtls_ssl_context *ssl, void *p_timer, void(*f_set_timer)(void *, uint32_t int_ms, uint32_t fin_ms), int(*f_get_timer)(void *)) |
| Set the timer callbacks (Mandatory for DTLS.) More... | |
| void | mbedtls_ssl_conf_ciphersuites (mbedtls_ssl_config *conf, const int *ciphersuites) |
| Set the list of allowed ciphersuites and the preference order. More... | |
| void | mbedtls_ssl_conf_ciphersuites_for_version (mbedtls_ssl_config *conf, const int *ciphersuites, int major, int minor) |
| Set the list of allowed ciphersuites and the preference order for a specific version of the protocol. More... | |
| void | mbedtls_ssl_conf_max_version (mbedtls_ssl_config *conf, int major, int minor) |
| Set the maximum supported version sent from the client side and/or accepted at the server side (Default: MBEDTLS_SSL_MAX_MAJOR_VERSION, MBEDTLS_SSL_MAX_MINOR_VERSION) More... | |
| void | mbedtls_ssl_conf_min_version (mbedtls_ssl_config *conf, int major, int minor) |
| Set the minimum accepted SSL/TLS protocol version (Default: TLS 1.0) More... | |
| void | mbedtls_ssl_conf_legacy_renegotiation (mbedtls_ssl_config *conf, int allow_legacy) |
| Prevent or allow legacy renegotiation. More... | |
| size_t | mbedtls_ssl_get_bytes_avail (const mbedtls_ssl_context *ssl) |
| Return the number of data bytes available to read. More... | |
| uint32_t | mbedtls_ssl_get_verify_result (const mbedtls_ssl_context *ssl) |
| Return the result of the certificate verification. More... | |
| const char * | mbedtls_ssl_get_ciphersuite (const mbedtls_ssl_context *ssl) |
| Return the name of the current ciphersuite. More... | |
| const char * | mbedtls_ssl_get_version (const mbedtls_ssl_context *ssl) |
| Return the current SSL version (SSLv3/TLSv1/etc) More... | |
| int | mbedtls_ssl_get_record_expansion (const mbedtls_ssl_context *ssl) |
| Return the (maximum) number of bytes added by the record layer: header + encryption/MAC overhead (inc. More... | |
| int | mbedtls_ssl_handshake (mbedtls_ssl_context *ssl) |
| Perform the SSL handshake. More... | |
| int | mbedtls_ssl_handshake_step (mbedtls_ssl_context *ssl) |
| Perform a single step of the SSL handshake. More... | |
| int | mbedtls_ssl_read (mbedtls_ssl_context *ssl, unsigned char *buf, size_t len) |
| Read at most 'len' application data bytes. More... | |
| int | mbedtls_ssl_write (mbedtls_ssl_context *ssl, const unsigned char *buf, size_t len) |
| Try to write exactly 'len' application data bytes. More... | |
| int | mbedtls_ssl_send_alert_message (mbedtls_ssl_context *ssl, unsigned char level, unsigned char message) |
| Send an alert message. More... | |
| int | mbedtls_ssl_close_notify (mbedtls_ssl_context *ssl) |
| Notify the peer that the connection is being closed. More... | |
| void | mbedtls_ssl_free (mbedtls_ssl_context *ssl) |
| Free referenced items in an SSL context and clear memory. More... | |
| void | mbedtls_ssl_config_init (mbedtls_ssl_config *conf) |
| Initialize an SSL configuration context Just makes the context ready for mbedtls_ssl_config_defaults() or mbedtls_ssl_config_free(). More... | |
| int | mbedtls_ssl_config_defaults (mbedtls_ssl_config *conf, int endpoint, int transport, int preset) |
| Load reasonnable default SSL configuration values. More... | |
| void | mbedtls_ssl_config_free (mbedtls_ssl_config *conf) |
| Free an SSL configuration context. More... | |
| void | mbedtls_ssl_session_init (mbedtls_ssl_session *session) |
| Initialize SSL session structure. More... | |
| void | mbedtls_ssl_session_free (mbedtls_ssl_session *session) |
| Free referenced items in an SSL session including the peer certificate and clear memory. More... | |
Macro Definition Documentation
| #define MBEDTLS_ERR_SSL_ALLOC_FAILED -0x7F00 |
| #define MBEDTLS_ERR_SSL_BAD_HS_CERTIFICATE -0x7A00 |
| #define MBEDTLS_ERR_SSL_BAD_HS_CERTIFICATE_REQUEST -0x7A80 |
| #define MBEDTLS_ERR_SSL_BAD_HS_CERTIFICATE_VERIFY -0x7D80 |
| #define MBEDTLS_ERR_SSL_BAD_HS_CHANGE_CIPHER_SPEC -0x7E00 |
| #define MBEDTLS_ERR_SSL_BAD_HS_CLIENT_HELLO -0x7900 |
| #define MBEDTLS_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE -0x7C00 |
| #define MBEDTLS_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE_CS -0x7D00 |
| #define MBEDTLS_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE_RP -0x7C80 |
| #define MBEDTLS_ERR_SSL_BAD_HS_FINISHED -0x7E80 |
| #define MBEDTLS_ERR_SSL_BAD_HS_NEW_SESSION_TICKET -0x6E00 |
| #define MBEDTLS_ERR_SSL_BAD_HS_PROTOCOL_VERSION -0x6E80 |
| #define MBEDTLS_ERR_SSL_BAD_HS_SERVER_HELLO -0x7980 |
| #define MBEDTLS_ERR_SSL_BAD_HS_SERVER_HELLO_DONE -0x7B80 |
| #define MBEDTLS_ERR_SSL_BAD_HS_SERVER_KEY_EXCHANGE -0x7B00 |
| #define MBEDTLS_ERR_SSL_BAD_INPUT_DATA -0x7100 |
| #define MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL -0x6A00 |
| #define MBEDTLS_ERR_SSL_CA_CHAIN_REQUIRED -0x7680 |
| #define MBEDTLS_ERR_SSL_CERTIFICATE_REQUIRED -0x7580 |
| #define MBEDTLS_ERR_SSL_CERTIFICATE_TOO_LARGE -0x7500 |
| #define MBEDTLS_ERR_SSL_CLIENT_RECONNECT -0x6780 |
| #define MBEDTLS_ERR_SSL_COMPRESSION_FAILED -0x6F00 |
| #define MBEDTLS_ERR_SSL_CONN_EOF -0x7280 |
| #define MBEDTLS_ERR_SSL_COUNTER_WRAPPING -0x6B80 |
| #define MBEDTLS_ERR_SSL_FATAL_ALERT_MESSAGE -0x7780 |
| #define MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE -0x7080 |
| #define MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED -0x6A80 |
| #define MBEDTLS_ERR_SSL_HW_ACCEL_FAILED -0x7F80 |
| #define MBEDTLS_ERR_SSL_HW_ACCEL_FALLTHROUGH -0x6F80 |
| #define MBEDTLS_ERR_SSL_INTERNAL_ERROR -0x6C00 |
| #define MBEDTLS_ERR_SSL_INVALID_MAC -0x7180 |
| #define MBEDTLS_ERR_SSL_INVALID_RECORD -0x7200 |
| #define MBEDTLS_ERR_SSL_NO_CIPHER_CHOSEN -0x7380 |
| #define MBEDTLS_ERR_SSL_NO_CLIENT_CERTIFICATE -0x7480 |
| #define MBEDTLS_ERR_SSL_NO_RNG -0x7400 |
| #define MBEDTLS_ERR_SSL_NO_USABLE_CIPHERSUITE -0x6980 |
| #define MBEDTLS_ERR_SSL_PEER_CLOSE_NOTIFY -0x7880 |
| #define MBEDTLS_ERR_SSL_PEER_VERIFY_FAILED -0x7800 |
| #define MBEDTLS_ERR_SSL_PK_TYPE_MISMATCH -0x6D00 |
| #define MBEDTLS_ERR_SSL_PRIVATE_KEY_REQUIRED -0x7600 |
| #define MBEDTLS_ERR_SSL_SESSION_TICKET_EXPIRED -0x6D80 |
| #define MBEDTLS_ERR_SSL_TIMEOUT -0x6800 |
| #define MBEDTLS_ERR_SSL_UNEXPECTED_MESSAGE -0x7700 |
| #define MBEDTLS_ERR_SSL_UNKNOWN_CIPHER -0x7300 |
| #define MBEDTLS_ERR_SSL_UNKNOWN_IDENTITY -0x6C80 |
| #define MBEDTLS_ERR_SSL_WAITING_SERVER_HELLO_RENEGO -0x6B00 |
| #define MBEDTLS_ERR_SSL_WANT_READ -0x6900 |
| #define MBEDTLS_ERR_SSL_WANT_WRITE -0x6880 |
| #define MBEDTLS_PREMASTER_SIZE sizeof( union mbedtls_ssl_premaster_secret ) |
| #define MBEDTLS_SSL_ALERT_MSG_DECOMPRESSION_FAILURE 30 /* 0x1E */ |
| #define MBEDTLS_SSL_ALERT_MSG_EXPORT_RESTRICTION 60 /* 0x3C */ |
| #define MBEDTLS_SSL_ALERT_MSG_INAPROPRIATE_FALLBACK 86 /* 0x56 */ |
| #define MBEDTLS_SSL_ALERT_MSG_INSUFFICIENT_SECURITY 71 /* 0x47 */ |
| #define MBEDTLS_SSL_ALERT_MSG_NO_APPLICATION_PROTOCOL 120 /* 0x78 */ |
| #define MBEDTLS_SSL_ALERT_MSG_UNEXPECTED_MESSAGE 10 /* 0x0A */ |
| #define MBEDTLS_SSL_ALERT_MSG_UNKNOWN_PSK_IDENTITY 115 /* 0x73 */ |
| #define MBEDTLS_SSL_ALERT_MSG_UNRECOGNIZED_NAME 112 /* 0x70 */ |
| #define MBEDTLS_SSL_DEFAULT_TICKET_LIFETIME 86400 |
| #define MBEDTLS_SSL_EMPTY_RENEGOTIATION_INFO 0xFF |
| #define MBEDTLS_SSL_FALLBACK_SCSV_VALUE 0x5600 |
| #define MBEDTLS_SSL_MAX_CONTENT_LEN 16384 |
| #define MBEDTLS_SSL_MAX_FRAG_LEN_1024 2 |
| #define MBEDTLS_SSL_MAX_FRAG_LEN_2048 3 |
| #define MBEDTLS_SSL_MAX_FRAG_LEN_4096 4 |
| #define MBEDTLS_SSL_MAX_FRAG_LEN_INVALID 5 |
| #define MBEDTLS_SSL_MAX_FRAG_LEN_NONE 0 |
| #define MBEDTLS_SSL_MAX_HOST_NAME_LEN 255 |
| #define MBEDTLS_SSL_TRANSPORT_DATAGRAM 1 |
DTLS
Definition at line 120 of file ssl.h.
Referenced by mbedtls_ssl_hdr_len(), and mbedtls_ssl_hs_hdr_len().
| #define MBEDTLS_SSL_TRUNCATED_HMAC_LEN 10 /* 80 bits, rfc 6066 section 7 */ |
| #define MBEDTLS_SSL_VERIFY_UNSET 3 /* Used only for sni_authmode */ |
| #define MBEDTLS_TLS_EXT_EXTENDED_MASTER_SECRET 0x0017 /* 23 */ |
Typedef Documentation
| typedef struct mbedtls_ssl_config mbedtls_ssl_config |
| typedef struct mbedtls_ssl_context mbedtls_ssl_context |
| typedef int mbedtls_ssl_cookie_check_t(void *ctx, const unsigned char *cookie, size_t clen, const unsigned char *info, size_t ilen) |
Callback type: verify a cookie.
- Parameters
-
ctx Context for the callback cookie Cookie to verify clen Length of cookie info Client ID info that was passed to mbedtls_ssl_set_client_transport_id()ilen Length of info in bytes
- Returns
- The callback must return 0 if cookie is valid, or a negative error code.
| typedef int mbedtls_ssl_cookie_write_t(void *ctx, unsigned char **p, unsigned char *end, const unsigned char *info, size_t ilen) |
Callback type: generate a cookie.
- Parameters
-
ctx Context for the callback p Buffer to write to, must be updated to point right after the cookie end Pointer to one past the end of the output buffer info Client ID info that was passed to mbedtls_ssl_set_client_transport_id()ilen Length of info in bytes
- Returns
- The callback must return 0 on success, or a negative error code.
| typedef struct mbedtls_ssl_handshake_params mbedtls_ssl_handshake_params |
| typedef struct mbedtls_ssl_session mbedtls_ssl_session |
| typedef int mbedtls_ssl_ticket_parse_t(void *p_ticket, mbedtls_ssl_session *session, unsigned char *buf, size_t len) |
Callback type: parse and load session ticket.
- Note
- This describes what a callback implementation should do. This callback should parse a session ticket as generated by the corresponding mbedtls_ssl_ticket_write_t function, and, if the ticket is authentic and valid, load the session.
- The implementation is allowed to modify the first len bytes of the input buffer, eg to use it as a temporary area for the decrypted ticket contents.
- Parameters
-
p_ticket Context for the callback session SSL session to be loaded buf Start of the buffer containing the ticket len Length of the ticket.
- Returns
- 0 if successful, or MBEDTLS_ERR_SSL_INVALID_MAC if not authentic, or MBEDTLS_ERR_SSL_SESSION_TICKET_EXPIRED if expired, or any other non-zero code for other failures.
| typedef int mbedtls_ssl_ticket_write_t(void *p_ticket, const mbedtls_ssl_session *session, unsigned char *start, const unsigned char *end, size_t *tlen, uint32_t *lifetime) |
Callback type: generate and write session ticket.
- Note
- This describes what a callback implementation should do. This callback should generate and encrypted and authenticated ticket for the session and write it to the output buffer. Here, ticket means the opaque ticket part of the NewSessionTicket structure of RFC 5077.
- Parameters
-
p_ticket Context for the callback session SSL session to bo written in the ticket start Start of the outpur buffer end End of the output buffer tlen On exit, holds the length written lifetime On exit, holds the lifetime of the ticket in seconds
- Returns
- 0 if successful, or a specific MBEDTLS_ERR_XXX code.
| typedef struct mbedtls_ssl_transform mbedtls_ssl_transform |
Enumeration Type Documentation
| enum mbedtls_ssl_states |
Function Documentation
| int mbedtls_ssl_close_notify | ( | mbedtls_ssl_context * | ssl | ) |
Notify the peer that the connection is being closed.
- Parameters
-
ssl SSL context
| void mbedtls_ssl_conf_authmode | ( | mbedtls_ssl_config * | conf, |
| int | authmode | ||
| ) |
Set the certificate verification mode Default: NONE on server, REQUIRED on client.
- Parameters
-
conf SSL configuration authmode can be:
MBEDTLS_SSL_VERIFY_NONE: peer certificate is not checked (default on server) (insecure on client)
MBEDTLS_SSL_VERIFY_OPTIONAL: peer certificate is checked, however the handshake continues even if verification failed; mbedtls_ssl_get_verify_result() can be called after the handshake is complete.
MBEDTLS_SSL_VERIFY_REQUIRED: peer must present a valid certificate, handshake is aborted if verification failed.
- Note
- On client, MBEDTLS_SSL_VERIFY_REQUIRED is the recommended mode. With MBEDTLS_SSL_VERIFY_OPTIONAL, the user needs to call mbedtls_ssl_get_verify_result() at the right time(s), which may not be obvious, while REQUIRED always perform the verification as soon as possible. For example, REQUIRED was protecting against the "triple handshake" attack even before it was found.
| void mbedtls_ssl_conf_ciphersuites | ( | mbedtls_ssl_config * | conf, |
| const int * | ciphersuites | ||
| ) |
Set the list of allowed ciphersuites and the preference order.
First in the list has the highest preference. (Overrides all version specific lists)
The ciphersuites array is not copied, and must remain valid for the lifetime of the ssl_config.
Note: The server uses its own preferences over the preference of the client unless MBEDTLS_SSL_SRV_RESPECT_CLIENT_PREFERENCE is defined!
- Parameters
-
conf SSL configuration ciphersuites 0-terminated list of allowed ciphersuites
| void mbedtls_ssl_conf_ciphersuites_for_version | ( | mbedtls_ssl_config * | conf, |
| const int * | ciphersuites, | ||
| int | major, | ||
| int | minor | ||
| ) |
Set the list of allowed ciphersuites and the preference order for a specific version of the protocol.
(Only useful on the server side)
The ciphersuites array is not copied, and must remain valid for the lifetime of the ssl_config.
- Parameters
-
conf SSL configuration ciphersuites 0-terminated list of allowed ciphersuites major Major version number (only MBEDTLS_SSL_MAJOR_VERSION_3 supported) minor Minor version number (MBEDTLS_SSL_MINOR_VERSION_0, MBEDTLS_SSL_MINOR_VERSION_1 and MBEDTLS_SSL_MINOR_VERSION_2, MBEDTLS_SSL_MINOR_VERSION_3 supported)
- Note
- With DTLS, use MBEDTLS_SSL_MINOR_VERSION_2 for DTLS 1.0 and MBEDTLS_SSL_MINOR_VERSION_3 for DTLS 1.2
| void mbedtls_ssl_conf_dbg | ( | mbedtls_ssl_config * | conf, |
| void(*)(void *, int, const char *, int, const char *) | f_dbg, | ||
| void * | p_dbg | ||
| ) |
Set the debug callback.
The callback has the following argument: void * opaque context for the callback int debug level const char * file name int line number const char * message
- Parameters
-
conf SSL configuration f_dbg debug function p_dbg debug parameter
| void mbedtls_ssl_conf_endpoint | ( | mbedtls_ssl_config * | conf, |
| int | endpoint | ||
| ) |
Set the current endpoint type.
- Parameters
-
conf SSL configuration endpoint must be MBEDTLS_SSL_IS_CLIENT or MBEDTLS_SSL_IS_SERVER
| void mbedtls_ssl_conf_legacy_renegotiation | ( | mbedtls_ssl_config * | conf, |
| int | allow_legacy | ||
| ) |
Prevent or allow legacy renegotiation.
(Default: MBEDTLS_SSL_LEGACY_NO_RENEGOTIATION)
MBEDTLS_SSL_LEGACY_NO_RENEGOTIATION allows connections to be established even if the peer does not support secure renegotiation, but does not allow renegotiation to take place if not secure. (Interoperable and secure option)
MBEDTLS_SSL_LEGACY_ALLOW_RENEGOTIATION allows renegotiations with non-upgraded peers. Allowing legacy renegotiation makes the connection vulnerable to specific man in the middle attacks. (See RFC 5746) (Most interoperable and least secure option)
MBEDTLS_SSL_LEGACY_BREAK_HANDSHAKE breaks off connections if peer does not support secure renegotiation. Results in interoperability issues with non-upgraded peers that do not support renegotiation altogether. (Most secure option, interoperability issues)
- Parameters
-
conf SSL configuration allow_legacy Prevent or allow (SSL_NO_LEGACY_RENEGOTIATION, SSL_ALLOW_LEGACY_RENEGOTIATION or MBEDTLS_SSL_LEGACY_BREAK_HANDSHAKE)
| void mbedtls_ssl_conf_max_version | ( | mbedtls_ssl_config * | conf, |
| int | major, | ||
| int | minor | ||
| ) |
Set the maximum supported version sent from the client side and/or accepted at the server side (Default: MBEDTLS_SSL_MAX_MAJOR_VERSION, MBEDTLS_SSL_MAX_MINOR_VERSION)
- Note
- This ignores ciphersuites from higher versions.
- With DTLS, use MBEDTLS_SSL_MINOR_VERSION_2 for DTLS 1.0 and MBEDTLS_SSL_MINOR_VERSION_3 for DTLS 1.2
- Parameters
-
conf SSL configuration major Major version number (only MBEDTLS_SSL_MAJOR_VERSION_3 supported) minor Minor version number (MBEDTLS_SSL_MINOR_VERSION_0, MBEDTLS_SSL_MINOR_VERSION_1 and MBEDTLS_SSL_MINOR_VERSION_2, MBEDTLS_SSL_MINOR_VERSION_3 supported)
| void mbedtls_ssl_conf_min_version | ( | mbedtls_ssl_config * | conf, |
| int | major, | ||
| int | minor | ||
| ) |
Set the minimum accepted SSL/TLS protocol version (Default: TLS 1.0)
- Note
- Input outside of the SSL_MAX_XXXXX_VERSION and SSL_MIN_XXXXX_VERSION range is ignored.
- MBEDTLS_SSL_MINOR_VERSION_0 (SSL v3) should be avoided.
- With DTLS, use MBEDTLS_SSL_MINOR_VERSION_2 for DTLS 1.0 and MBEDTLS_SSL_MINOR_VERSION_3 for DTLS 1.2
- Parameters
-
conf SSL configuration major Major version number (only MBEDTLS_SSL_MAJOR_VERSION_3 supported) minor Minor version number (MBEDTLS_SSL_MINOR_VERSION_0, MBEDTLS_SSL_MINOR_VERSION_1 and MBEDTLS_SSL_MINOR_VERSION_2, MBEDTLS_SSL_MINOR_VERSION_3 supported)
| void mbedtls_ssl_conf_read_timeout | ( | mbedtls_ssl_config * | conf, |
| uint32_t | timeout | ||
| ) |
Set the timeout period for mbedtls_ssl_read() (Default: no timeout.)
- Parameters
-
conf SSL configuration context timeout Timeout value in milliseconds. Use 0 for no timeout (default).
- Note
- With blocking I/O, this will only work if a non-NULL
f_recv_timeoutwas set withmbedtls_ssl_set_bio(). With non-blocking I/O, this will only work if timer callbacks were set withmbedtls_ssl_set_timer_cb(). - With non-blocking I/O, you may also skip this function altogether and handle timeouts at the application layer.
| void mbedtls_ssl_conf_rng | ( | mbedtls_ssl_config * | conf, |
| int(*)(void *, unsigned char *, size_t) | f_rng, | ||
| void * | p_rng | ||
| ) |
Set the random number generator callback.
- Parameters
-
conf SSL configuration f_rng RNG function p_rng RNG parameter
| void mbedtls_ssl_conf_transport | ( | mbedtls_ssl_config * | conf, |
| int | transport | ||
| ) |
Set the transport type (TLS or DTLS).
Default: TLS
- Note
- For DTLS, you must either provide a recv callback that doesn't block, or one that handles timeouts, see
mbedtls_ssl_set_bio(). You also need to provide timer callbacks withmbedtls_ssl_set_timer_cb().
- Parameters
-
conf SSL configuration transport transport type: MBEDTLS_SSL_TRANSPORT_STREAM for TLS, MBEDTLS_SSL_TRANSPORT_DATAGRAM for DTLS.
| int mbedtls_ssl_config_defaults | ( | mbedtls_ssl_config * | conf, |
| int | endpoint, | ||
| int | transport, | ||
| int | preset | ||
| ) |
Load reasonnable default SSL configuration values.
(You need to call mbedtls_ssl_config_init() first.)
- Parameters
-
conf SSL configuration context endpoint MBEDTLS_SSL_IS_CLIENT or MBEDTLS_SSL_IS_SERVER transport MBEDTLS_SSL_TRANSPORT_STREAM for TLS, or MBEDTLS_SSL_TRANSPORT_DATAGRAM for DTLS preset a MBEDTLS_SSL_PRESET_XXX value (currently unused).
- Note
- See
mbedtls_ssl_conf_transport()for notes on DTLS.
- Returns
- 0 if successful, or MBEDTLS_ERR_XXX_ALLOC_FAILED on memory allocation error.
| void mbedtls_ssl_config_free | ( | mbedtls_ssl_config * | conf | ) |
Free an SSL configuration context.
- Parameters
-
conf SSL configuration context
| void mbedtls_ssl_config_init | ( | mbedtls_ssl_config * | conf | ) |
Initialize an SSL configuration context Just makes the context ready for mbedtls_ssl_config_defaults() or mbedtls_ssl_config_free().
- Note
- You need to call mbedtls_ssl_config_defaults() unless you manually set all of the relevent fields yourself.
- Parameters
-
conf SSL configuration context
| void mbedtls_ssl_free | ( | mbedtls_ssl_context * | ssl | ) |
Free referenced items in an SSL context and clear memory.
- Parameters
-
ssl SSL context
| size_t mbedtls_ssl_get_bytes_avail | ( | const mbedtls_ssl_context * | ssl | ) |
Return the number of data bytes available to read.
- Parameters
-
ssl SSL context
- Returns
- how many bytes are available in the read buffer
| const char* mbedtls_ssl_get_ciphersuite | ( | const mbedtls_ssl_context * | ssl | ) |
Return the name of the current ciphersuite.
- Parameters
-
ssl SSL context
- Returns
- a string containing the ciphersuite name
| int mbedtls_ssl_get_ciphersuite_id | ( | const char * | ciphersuite_name | ) |
Return the ID of the ciphersuite associated with the given name.
- Parameters
-
ciphersuite_name SSL ciphersuite name
- Returns
- the ID with the ciphersuite or 0 if not found
| const char* mbedtls_ssl_get_ciphersuite_name | ( | const int | ciphersuite_id | ) |
Return the name of the ciphersuite associated with the given ID.
- Parameters
-
ciphersuite_id SSL ciphersuite ID
- Returns
- a string containing the ciphersuite name
| int mbedtls_ssl_get_record_expansion | ( | const mbedtls_ssl_context * | ssl | ) |
Return the (maximum) number of bytes added by the record layer: header + encryption/MAC overhead (inc.
padding)
- Parameters
-
ssl SSL context
- Returns
- Current maximum record expansion in bytes, or MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE if compression is enabled, which makes expansion much less predictable
| uint32_t mbedtls_ssl_get_verify_result | ( | const mbedtls_ssl_context * | ssl | ) |
Return the result of the certificate verification.
- Parameters
-
ssl SSL context
- Returns
- 0 if successful, -1 if result is not available (eg because the handshake was aborted too early), or a combination of BADCERT_xxx and BADCRL_xxx flags, see x509.h
| const char* mbedtls_ssl_get_version | ( | const mbedtls_ssl_context * | ssl | ) |
Return the current SSL version (SSLv3/TLSv1/etc)
- Parameters
-
ssl SSL context
- Returns
- a string containing the SSL version
| int mbedtls_ssl_handshake | ( | mbedtls_ssl_context * | ssl | ) |
Perform the SSL handshake.
- Parameters
-
ssl SSL context
- Returns
- 0 if successful, or MBEDTLS_ERR_SSL_WANT_READ or MBEDTLS_ERR_SSL_WANT_WRITE, or MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED (see below), or a specific SSL error code.
- Note
- If this function returns something other than 0 or MBEDTLS_ERR_SSL_WANT_READ/WRITE, then the ssl context becomes unusable, and you should either free it or call
mbedtls_ssl_session_reset()on it before re-using it. - If DTLS is in use, then you may choose to handle MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED specially for logging purposes, as it is an expected return value rather than an actual error, but you still need to reset/free the context.
| int mbedtls_ssl_handshake_step | ( | mbedtls_ssl_context * | ssl | ) |
Perform a single step of the SSL handshake.
- Note
- The state of the context (ssl->state) will be at the following state after execution of this function. Do not call this function if state is MBEDTLS_SSL_HANDSHAKE_OVER.
- Parameters
-
ssl SSL context
- Returns
- 0 if successful, or MBEDTLS_ERR_SSL_WANT_READ or MBEDTLS_ERR_SSL_WANT_WRITE, or a specific SSL error code.
| void mbedtls_ssl_init | ( | mbedtls_ssl_context * | ssl | ) |
Initialize an SSL context Just makes the context ready for mbedtls_ssl_setup() or mbedtls_ssl_free()
- Parameters
-
ssl SSL context
| const int* mbedtls_ssl_list_ciphersuites | ( | void | ) |
Returns the list of ciphersuites supported by the SSL/TLS module.
- Returns
- a statically allocated array of ciphersuites, the last entry is 0.
| int mbedtls_ssl_read | ( | mbedtls_ssl_context * | ssl, |
| unsigned char * | buf, | ||
| size_t | len | ||
| ) |
Read at most 'len' application data bytes.
- Parameters
-
ssl SSL context buf buffer that will hold the data len maximum number of bytes to read
- Returns
- the number of bytes read, or 0 for EOF, or MBEDTLS_ERR_SSL_WANT_READ or MBEDTLS_ERR_SSL_WANT_WRITE, or MBEDTLS_ERR_SSL_CLIENT_RECONNECT (see below), or another negative error code.
- Note
- When this function return MBEDTLS_ERR_SSL_CLIENT_RECONNECT (which can only happen server-side), it means that a client is initiating a new connection using the same source port. You can either treat that as a connection close and wait for the client to resend a ClientHello, or directly continue with
mbedtls_ssl_handshake()with the same context (as it has beeen reset internally). Either way, you should make sure this is seen by the application as a new connection: application state, if any, should be reset, and most importantly the identity of the client must be checked again. WARNING: not validating the identity of the client again, or not transmitting the new identity to the application layer, would allow authentication bypass!
| int mbedtls_ssl_send_alert_message | ( | mbedtls_ssl_context * | ssl, |
| unsigned char | level, | ||
| unsigned char | message | ||
| ) |
Send an alert message.
- Parameters
-
ssl SSL context level The alert level of the message (MBEDTLS_SSL_ALERT_LEVEL_WARNING or MBEDTLS_SSL_ALERT_LEVEL_FATAL) message The alert message (SSL_ALERT_MSG_*)
- Returns
- 0 if successful, or a specific SSL error code.
| void mbedtls_ssl_session_free | ( | mbedtls_ssl_session * | session | ) |
Free referenced items in an SSL session including the peer certificate and clear memory.
- Parameters
-
session SSL session
| void mbedtls_ssl_session_init | ( | mbedtls_ssl_session * | session | ) |
Initialize SSL session structure.
- Parameters
-
session SSL session
| int mbedtls_ssl_session_reset | ( | mbedtls_ssl_context * | ssl | ) |
Reset an already initialized SSL context for re-use while retaining application-set variables, function pointers and data.
- Parameters
-
ssl SSL context
- Returns
- 0 if successful, or POLASSL_ERR_SSL_MALLOC_FAILED, MBEDTLS_ERR_SSL_HW_ACCEL_FAILED or MBEDTLS_ERR_SSL_COMPRESSION_FAILED
| void mbedtls_ssl_set_bio | ( | mbedtls_ssl_context * | ssl, |
| void * | p_bio, | ||
| int(*)(void *, const unsigned char *, size_t) | f_send, | ||
| int(*)(void *, unsigned char *, size_t) | f_recv, | ||
| int(*)(void *, unsigned char *, size_t, uint32_t) | f_recv_timeout | ||
| ) |
Set the underlying BIO callbacks for write, read and read-with-timeout.
- Parameters
-
ssl SSL context p_bio parameter (context) shared by BIO callbacks f_send write callback f_recv read callback f_recv_timeout blocking read callback with timeout. The last argument is the timeout in milliseconds, 0 means no timeout (block forever until a message comes)
- Note
- One of f_recv or f_recv_timeout can be NULL, in which case the other is used. If both are non-NULL, f_recv_timeout is used and f_recv is ignored (as if it were NULL).
-
The two most common use cases are:
- non-blocking I/O, f_recv != NULL, f_recv_timeout == NULL
- blocking I/O, f_recv == NULL, f_recv_timout != NULL
- For DTLS, you need to provide either a non-NULL f_recv_timeout callback, or a f_recv that doesn't block.
| void mbedtls_ssl_set_timer_cb | ( | mbedtls_ssl_context * | ssl, |
| void * | p_timer, | ||
| void(*)(void *, uint32_t int_ms, uint32_t fin_ms) | f_set_timer, | ||
| int(*)(void *) | f_get_timer | ||
| ) |
Set the timer callbacks (Mandatory for DTLS.)
- Parameters
-
ssl SSL context p_timer parameter (context) shared by timer callback f_set_timer set timer callback Accepts an intermediate and a final delay in milliseconcs If the final delay is 0, cancels the running timer. f_get_timer get timer callback. Must return: -1 if cancelled 0 if none of the delays is expired 1 if the intermediate delay only is expired 2 if the final delay is expired
| int mbedtls_ssl_setup | ( | mbedtls_ssl_context * | ssl, |
| const mbedtls_ssl_config * | conf | ||
| ) |
Set up an SSL context for use.
- Note
- No copy of the configuration context is made, it can be shared by many mbedtls_ssl_context structures.
- Warning
- Modifying the conf structure after is has been used in this function is unsupported!
- Parameters
-
ssl SSL context conf SSL configuration to use
- Returns
- 0 if successful, or MBEDTLS_ERR_SSL_ALLOC_FAILED if memory allocation failed
| int mbedtls_ssl_write | ( | mbedtls_ssl_context * | ssl, |
| const unsigned char * | buf, | ||
| size_t | len | ||
| ) |
Try to write exactly 'len' application data bytes.
- Warning
- This function will do partial writes in some cases. If the return value is non-negative but less than length, the function must be called again with updated arguments: buf + ret, len - ret (if ret is the return value) until it returns a value equal to the last 'len' argument.
- Parameters
-
ssl SSL context buf buffer holding the data len how many bytes must be written
- Returns
- the number of bytes actually written (may be less than len), or MBEDTLS_ERR_SSL_WANT_WRITE of MBEDTLS_ERR_SSL_WANT_READ, or another negative error code.
- Note
- When this function returns MBEDTLS_ERR_SSL_WANT_WRITE/READ, it must be called later with the same arguments, until it returns a positive value.
-
If the requested length is greater than the maximum fragment length (either the built-in limit or the one set or negotiated with the peer), then:
- with TLS, less bytes than requested are written.
- with DTLS, MBEDTLS_ERR_SSL_BAD_INPUT_DATA is returned.
mbedtls_ssl_get_max_frag_len()may be used to query the active maximum fragment length.
