Mbed TLS v3.6.3
|
SSL/TLS functions. More...
#include "mbedtls/platform_util.h"
#include "mbedtls/private_access.h"
#include "mbedtls/build_info.h"
#include "mbedtls/bignum.h"
#include "mbedtls/ecp.h"
#include "mbedtls/ssl_ciphersuites.h"
#include "mbedtls/x509_crt.h"
#include "mbedtls/x509_crl.h"
#include "mbedtls/dhm.h"
#include "mbedtls/md.h"
#include "mbedtls/ecdh.h"
#include "mbedtls/platform_time.h"
#include "psa/crypto.h"
Go to the source code of this file.
Data Structures | |
union | mbedtls_ssl_premaster_secret |
struct | mbedtls_ssl_tls13_application_secrets |
struct | mbedtls_ssl_session |
union | mbedtls_ssl_user_data_t |
struct | mbedtls_ssl_config |
struct | mbedtls_ssl_context |
Typedefs | |
typedef int | mbedtls_ssl_send_t(void *ctx, const unsigned char *buf, size_t len) |
Callback type: send data on the network. | |
typedef int | mbedtls_ssl_recv_t(void *ctx, unsigned char *buf, size_t len) |
Callback type: receive data from the network. | |
typedef int | mbedtls_ssl_recv_timeout_t(void *ctx, unsigned char *buf, size_t len, uint32_t timeout) |
Callback type: receive data from the network, with timeout. | |
typedef void | mbedtls_ssl_set_timer_t(void *ctx, uint32_t int_ms, uint32_t fin_ms) |
Callback type: set a pair of timers/delays to watch. | |
typedef int | mbedtls_ssl_get_timer_t(void *ctx) |
Callback type: get status of timers/delays. | |
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 struct mbedtls_ssl_sig_hash_set_t | mbedtls_ssl_sig_hash_set_t |
typedef struct mbedtls_ssl_key_cert | mbedtls_ssl_key_cert |
typedef struct mbedtls_ssl_flight_item | mbedtls_ssl_flight_item |
typedef int | mbedtls_ssl_cache_get_t(void *data, unsigned char const *session_id, size_t session_id_len, mbedtls_ssl_session *session) |
Callback type: server-side session cache getter. | |
typedef int | mbedtls_ssl_cache_set_t(void *data, unsigned char const *session_id, size_t session_id_len, const mbedtls_ssl_session *session) |
Callback type: server-side session cache setter. | |
typedef void | mbedtls_ssl_export_keys_t(void *p_expkey, mbedtls_ssl_key_export_type type, const unsigned char *secret, size_t secret_len, const unsigned char client_random[32], const unsigned char server_random[32], mbedtls_tls_prf_types tls_prf_type) |
Callback type: Export key alongside random values for session identification, and PRF for implementation of TLS key exporters. | |
typedef int(* | mbedtls_ssl_hs_cb_t) (mbedtls_ssl_context *ssl) |
Callback type: generic handshake callback. | |
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. | |
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. | |
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. | |
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. | |
Functions | |
const char * | mbedtls_ssl_get_ciphersuite_name (const int ciphersuite_id) |
Return the name of the ciphersuite associated with the given ID. | |
int | mbedtls_ssl_get_ciphersuite_id (const char *ciphersuite_name) |
Return the ID of the ciphersuite associated with the given name. | |
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() | |
int | mbedtls_ssl_setup (mbedtls_ssl_context *ssl, const mbedtls_ssl_config *conf) |
Set up an SSL context for use. | |
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. | |
void | mbedtls_ssl_conf_endpoint (mbedtls_ssl_config *conf, int endpoint) |
Set the current endpoint type. | |
static int | mbedtls_ssl_conf_get_endpoint (const mbedtls_ssl_config *conf) |
Get the current endpoint type. | |
void | mbedtls_ssl_conf_transport (mbedtls_ssl_config *conf, int transport) |
Set the transport type (TLS or DTLS). Default: TLS. | |
void | mbedtls_ssl_conf_authmode (mbedtls_ssl_config *conf, int authmode) |
Set the certificate verification mode Default: NONE on server, REQUIRED on client. | |
void | mbedtls_ssl_conf_verify (mbedtls_ssl_config *conf, int(*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *), void *p_vrfy) |
Set the verification callback (Optional). | |
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. | |
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. | |
static const mbedtls_ssl_config * | mbedtls_ssl_context_get_config (const mbedtls_ssl_context *ssl) |
Return the SSL configuration structure associated with the given SSL context. | |
void | mbedtls_ssl_set_bio (mbedtls_ssl_context *ssl, void *p_bio, mbedtls_ssl_send_t *f_send, mbedtls_ssl_recv_t *f_recv, mbedtls_ssl_recv_timeout_t *f_recv_timeout) |
Set the underlying BIO callbacks for write, read and read-with-timeout. | |
int | mbedtls_ssl_set_cid (mbedtls_ssl_context *ssl, int enable, unsigned char const *own_cid, size_t own_cid_len) |
Configure the use of the Connection ID (CID) extension in the next handshake. | |
int | mbedtls_ssl_get_own_cid (mbedtls_ssl_context *ssl, int *enabled, unsigned char own_cid[MBEDTLS_SSL_CID_IN_LEN_MAX], size_t *own_cid_len) |
Get information about our request for usage of the CID extension in the current connection. | |
int | mbedtls_ssl_get_peer_cid (mbedtls_ssl_context *ssl, int *enabled, unsigned char peer_cid[MBEDTLS_SSL_CID_OUT_LEN_MAX], size_t *peer_cid_len) |
Get information about the use of the CID extension in the current connection. | |
void | mbedtls_ssl_set_mtu (mbedtls_ssl_context *ssl, uint16_t mtu) |
Set the Maximum Transport Unit (MTU). Special value: 0 means unset (no limit). This represents the maximum size of a datagram payload handled by the transport layer (usually UDP) as determined by the network link and stack. In practice, this controls the maximum size datagram the DTLS layer will pass to the f_send() callback set using mbedtls_ssl_set_bio() . | |
void | mbedtls_ssl_set_verify (mbedtls_ssl_context *ssl, int(*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *), void *p_vrfy) |
Set a connection-specific verification callback (optional). | |
void | mbedtls_ssl_conf_read_timeout (mbedtls_ssl_config *conf, uint32_t timeout) |
Set the timeout period for mbedtls_ssl_read() (Default: no timeout.) | |
int | mbedtls_ssl_check_record (mbedtls_ssl_context const *ssl, unsigned char *buf, size_t buflen) |
Check whether a buffer contains a valid and authentic record that has not been seen before. (DTLS only). | |
void | mbedtls_ssl_set_timer_cb (mbedtls_ssl_context *ssl, void *p_timer, mbedtls_ssl_set_timer_t *f_set_timer, mbedtls_ssl_get_timer_t *f_get_timer) |
Set the timer callbacks (Mandatory for DTLS.) | |
static void | mbedtls_ssl_conf_cert_cb (mbedtls_ssl_config *conf, mbedtls_ssl_hs_cb_t f_cert_cb) |
Set the certificate selection callback (server-side only). | |
void | mbedtls_ssl_conf_session_tickets_cb (mbedtls_ssl_config *conf, mbedtls_ssl_ticket_write_t *f_ticket_write, mbedtls_ssl_ticket_parse_t *f_ticket_parse, void *p_ticket) |
Configure SSL session ticket callbacks (server only). (Default: none.) | |
static int | mbedtls_ssl_session_get_ticket_creation_time (mbedtls_ssl_session *session, mbedtls_ms_time_t *ticket_creation_time) |
Get the creation time of a session ticket. | |
static unsigned const char(* | mbedtls_ssl_session_get_id (const mbedtls_ssl_session *session))[32] |
Get the session-id buffer. | |
static size_t | mbedtls_ssl_session_get_id_len (const mbedtls_ssl_session *session) |
Get the size of the session-id. | |
static int | mbedtls_ssl_session_get_ciphersuite_id (const mbedtls_ssl_session *session) |
Get the ciphersuite-id. | |
void | mbedtls_ssl_set_export_keys_cb (mbedtls_ssl_context *ssl, mbedtls_ssl_export_keys_t *f_export_keys, void *p_export_keys) |
Configure a key export callback. (Default: none.) | |
static void | mbedtls_ssl_conf_set_user_data_p (mbedtls_ssl_config *conf, void *p) |
Set the user data in an SSL configuration to a pointer. | |
static void | mbedtls_ssl_conf_set_user_data_n (mbedtls_ssl_config *conf, uintptr_t n) |
Set the user data in an SSL configuration to an integer. | |
static void * | mbedtls_ssl_conf_get_user_data_p (mbedtls_ssl_config *conf) |
Retrieve the user data in an SSL configuration as a pointer. | |
static uintptr_t | mbedtls_ssl_conf_get_user_data_n (mbedtls_ssl_config *conf) |
Retrieve the user data in an SSL configuration as an integer. | |
static void | mbedtls_ssl_set_user_data_p (mbedtls_ssl_context *ssl, void *p) |
Set the user data in an SSL context to a pointer. | |
static void | mbedtls_ssl_set_user_data_n (mbedtls_ssl_context *ssl, uintptr_t n) |
Set the user data in an SSL context to an integer. | |
static void * | mbedtls_ssl_get_user_data_p (mbedtls_ssl_context *ssl) |
Retrieve the user data in an SSL context as a pointer. | |
static uintptr_t | mbedtls_ssl_get_user_data_n (mbedtls_ssl_context *ssl) |
Retrieve the user data in an SSL context as an integer. | |
void | mbedtls_ssl_conf_dtls_cookies (mbedtls_ssl_config *conf, mbedtls_ssl_cookie_write_t *f_cookie_write, mbedtls_ssl_cookie_check_t *f_cookie_check, void *p_cookie) |
Register callbacks for DTLS cookies (Server only. DTLS only.) | |
int | mbedtls_ssl_set_client_transport_id (mbedtls_ssl_context *ssl, const unsigned char *info, size_t ilen) |
Set client's transport-level identification info. (Server only. DTLS only.) | |
void | mbedtls_ssl_conf_dtls_anti_replay (mbedtls_ssl_config *conf, char mode) |
Enable or disable anti-replay protection for DTLS. (DTLS only, no effect on TLS.) Default: enabled. | |
void | mbedtls_ssl_conf_dtls_badmac_limit (mbedtls_ssl_config *conf, unsigned limit) |
Set a limit on the number of records with a bad MAC before terminating the connection. (DTLS only, no effect on TLS.) Default: 0 (disabled). | |
void | mbedtls_ssl_set_datagram_packing (mbedtls_ssl_context *ssl, unsigned allow_packing) |
Allow or disallow packing of multiple handshake records within a single datagram. | |
void | mbedtls_ssl_conf_handshake_timeout (mbedtls_ssl_config *conf, uint32_t min, uint32_t max) |
Set retransmit timeout values for the DTLS handshake. (DTLS only, no effect on TLS.) | |
void | mbedtls_ssl_conf_session_cache (mbedtls_ssl_config *conf, void *p_cache, mbedtls_ssl_cache_get_t *f_get_cache, mbedtls_ssl_cache_set_t *f_set_cache) |
Set the session cache callbacks (server-side only) If not set, no session resuming is done (except if session tickets are enabled too). | |
int | mbedtls_ssl_set_session (mbedtls_ssl_context *ssl, const mbedtls_ssl_session *session) |
Load a session for session resumption. | |
int | mbedtls_ssl_session_load (mbedtls_ssl_session *session, const unsigned char *buf, size_t len) |
Load serialized session data into a session structure. On client, this can be used for loading saved sessions before resuming them with mbedtls_ssl_set_session(). On server, this can be used for alternative implementations of session cache or session tickets. | |
int | mbedtls_ssl_session_save (const mbedtls_ssl_session *session, unsigned char *buf, size_t buf_len, size_t *olen) |
Save session structure as serialized data in a buffer. On client, this can be used for saving session data, potentially in non-volatile storage, for resuming later. On server, this can be used for alternative implementations of session cache or session tickets. | |
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. | |
void | mbedtls_ssl_conf_tls13_key_exchange_modes (mbedtls_ssl_config *conf, const int kex_modes) |
Set the supported key exchange modes for TLS 1.3 connections. | |
int | mbedtls_ssl_conf_cid (mbedtls_ssl_config *conf, size_t len, int ignore_other_cids) |
Specify the length of Connection IDs for incoming encrypted DTLS records, as well as the behaviour on unexpected CIDs. | |
void | mbedtls_ssl_conf_cert_profile (mbedtls_ssl_config *conf, const mbedtls_x509_crt_profile *profile) |
Set the X.509 security profile used for verification. | |
void | mbedtls_ssl_conf_ca_chain (mbedtls_ssl_config *conf, mbedtls_x509_crt *ca_chain, mbedtls_x509_crl *ca_crl) |
Set the data required to verify peer certificate. | |
static void | mbedtls_ssl_conf_dn_hints (mbedtls_ssl_config *conf, const mbedtls_x509_crt *crt) |
Set DN hints sent to client in CertificateRequest message. | |
int | mbedtls_ssl_conf_own_cert (mbedtls_ssl_config *conf, mbedtls_x509_crt *own_cert, mbedtls_pk_context *pk_key) |
Set own certificate chain and private key. | |
int | mbedtls_ssl_conf_psk (mbedtls_ssl_config *conf, const unsigned char *psk, size_t psk_len, const unsigned char *psk_identity, size_t psk_identity_len) |
Configure pre-shared keys (PSKs) and their identities to be used in PSK-based ciphersuites. | |
int | mbedtls_ssl_set_hs_psk (mbedtls_ssl_context *ssl, const unsigned char *psk, size_t psk_len) |
Set the pre-shared Key (PSK) for the current handshake. | |
void | mbedtls_ssl_conf_psk_cb (mbedtls_ssl_config *conf, int(*f_psk)(void *, mbedtls_ssl_context *, const unsigned char *, size_t), void *p_psk) |
Set the PSK callback (server-side only). | |
int | mbedtls_ssl_conf_dh_param_bin (mbedtls_ssl_config *conf, const unsigned char *dhm_P, size_t P_len, const unsigned char *dhm_G, size_t G_len) |
Set the Diffie-Hellman public P and G values from big-endian binary presentations. (Default values: MBEDTLS_DHM_RFC3526_MODP_2048_[PG]_BIN) | |
int | mbedtls_ssl_conf_dh_param_ctx (mbedtls_ssl_config *conf, mbedtls_dhm_context *dhm_ctx) |
Set the Diffie-Hellman public P and G values, read from existing context (server-side only) | |
void | mbedtls_ssl_conf_dhm_min_bitlen (mbedtls_ssl_config *conf, unsigned int bitlen) |
Set the minimum length for Diffie-Hellman parameters. (Client-side only.) (Default: 1024 bits.) | |
void MBEDTLS_DEPRECATED | mbedtls_ssl_conf_curves (mbedtls_ssl_config *conf, const mbedtls_ecp_group_id *curves) |
Set the allowed curves in order of preference. | |
void | mbedtls_ssl_conf_groups (mbedtls_ssl_config *conf, const uint16_t *groups) |
Set the allowed groups in order of preference. | |
void MBEDTLS_DEPRECATED | mbedtls_ssl_conf_sig_hashes (mbedtls_ssl_config *conf, const int *hashes) |
Set the allowed hashes for signatures during the handshake. | |
void | mbedtls_ssl_conf_sig_algs (mbedtls_ssl_config *conf, const uint16_t *sig_algs) |
Configure allowed signature algorithms for use in TLS. | |
int | mbedtls_ssl_set_hostname (mbedtls_ssl_context *ssl, const char *hostname) |
Set or reset the hostname to check against the received peer certificate. On a client, this also sets the ServerName TLS extension, if that extension is enabled. On a TLS 1.3 client, this also sets the server name in the session resumption ticket, if that feature is enabled. | |
static const char * | mbedtls_ssl_get_hostname (mbedtls_ssl_context *ssl) |
Get the hostname that checked against the received server certificate. It is used to set the ServerName TLS extension, too, if that extension is enabled. (client-side only) | |
const unsigned char * | mbedtls_ssl_get_hs_sni (mbedtls_ssl_context *ssl, size_t *name_len) |
Retrieve SNI extension value for the current handshake. Available in f_cert_cb of mbedtls_ssl_conf_cert_cb() , this is the same value passed to f_sni callback of mbedtls_ssl_conf_sni() and may be used instead of mbedtls_ssl_conf_sni() . | |
int | mbedtls_ssl_set_hs_own_cert (mbedtls_ssl_context *ssl, mbedtls_x509_crt *own_cert, mbedtls_pk_context *pk_key) |
Set own certificate and key for the current handshake. | |
void | mbedtls_ssl_set_hs_ca_chain (mbedtls_ssl_context *ssl, mbedtls_x509_crt *ca_chain, mbedtls_x509_crl *ca_crl) |
Set the data required to verify peer certificate for the current handshake. | |
void | mbedtls_ssl_set_hs_dn_hints (mbedtls_ssl_context *ssl, const mbedtls_x509_crt *crt) |
Set DN hints sent to client in CertificateRequest message. | |
void | mbedtls_ssl_set_hs_authmode (mbedtls_ssl_context *ssl, int authmode) |
Set authmode for the current handshake. | |
void | mbedtls_ssl_conf_sni (mbedtls_ssl_config *conf, int(*f_sni)(void *, mbedtls_ssl_context *, const unsigned char *, size_t), void *p_sni) |
Set server side ServerName TLS extension callback (optional, server-side only). | |
int | mbedtls_ssl_conf_alpn_protocols (mbedtls_ssl_config *conf, const char **protos) |
Set the supported Application Layer Protocols. | |
const char * | mbedtls_ssl_get_alpn_protocol (const mbedtls_ssl_context *ssl) |
Get the name of the negotiated Application Layer Protocol. This function should be called after the handshake is completed. | |
void MBEDTLS_DEPRECATED | 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. | |
static void | mbedtls_ssl_conf_max_tls_version (mbedtls_ssl_config *conf, mbedtls_ssl_protocol_version tls_version) |
Set the maximum supported version sent from the client side and/or accepted at the server side. | |
void MBEDTLS_DEPRECATED | mbedtls_ssl_conf_min_version (mbedtls_ssl_config *conf, int major, int minor) |
Set the minimum accepted SSL/TLS protocol version. | |
static void | mbedtls_ssl_conf_min_tls_version (mbedtls_ssl_config *conf, mbedtls_ssl_protocol_version tls_version) |
Set the minimum supported version sent from the client side and/or accepted at the server side. | |
void | mbedtls_ssl_conf_encrypt_then_mac (mbedtls_ssl_config *conf, char etm) |
Enable or disable Encrypt-then-MAC (Default: MBEDTLS_SSL_ETM_ENABLED) | |
void | mbedtls_ssl_conf_extended_master_secret (mbedtls_ssl_config *conf, char ems) |
Enable or disable Extended Master Secret negotiation. (Default: MBEDTLS_SSL_EXTENDED_MS_ENABLED) | |
void | mbedtls_ssl_conf_cert_req_ca_list (mbedtls_ssl_config *conf, char cert_req_ca_list) |
Whether to send a list of acceptable CAs in CertificateRequest messages. (Default: do send) | |
int | mbedtls_ssl_conf_max_frag_len (mbedtls_ssl_config *conf, unsigned char mfl_code) |
Set the maximum fragment length to emit and/or negotiate. (Typical: the smaller of MBEDTLS_SSL_IN_CONTENT_LEN and MBEDTLS_SSL_OUT_CONTENT_LEN, usually 2^14 bytes) (Server: set maximum fragment length to emit, usually negotiated by the client during handshake) (Client: set maximum fragment length to emit and negotiate with the server during handshake) (Default: MBEDTLS_SSL_MAX_FRAG_LEN_NONE) | |
void | mbedtls_ssl_conf_preference_order (mbedtls_ssl_config *conf, int order) |
Pick the ciphersuites order according to the second parameter in the SSL Server module (MBEDTLS_SSL_SRV_C). (Default, if never called: MBEDTLS_SSL_SRV_CIPHERSUITE_ORDER_SERVER) | |
void | mbedtls_ssl_conf_session_tickets (mbedtls_ssl_config *conf, int use_tickets) |
Enable / Disable TLS 1.2 session tickets (client only, TLS 1.2 only). Enabled by default. | |
void | mbedtls_ssl_conf_tls13_enable_signal_new_session_tickets (mbedtls_ssl_config *conf, int signal_new_session_tickets) |
Enable / Disable handling of TLS 1.3 NewSessionTicket messages (client only, TLS 1.3 only). | |
void | mbedtls_ssl_conf_new_session_tickets (mbedtls_ssl_config *conf, uint16_t num_tickets) |
Number of NewSessionTicket messages for the server to send after handshake completion. | |
void | mbedtls_ssl_conf_renegotiation (mbedtls_ssl_config *conf, int renegotiation) |
Enable / Disable renegotiation support for connection when initiated by peer (Default: MBEDTLS_SSL_RENEGOTIATION_DISABLED) | |
void | mbedtls_ssl_conf_legacy_renegotiation (mbedtls_ssl_config *conf, int allow_legacy) |
Prevent or allow legacy renegotiation. (Default: MBEDTLS_SSL_LEGACY_NO_RENEGOTIATION) | |
void | mbedtls_ssl_conf_renegotiation_enforced (mbedtls_ssl_config *conf, int max_records) |
Enforce renegotiation requests. (Default: enforced, max_records = 16) | |
void | mbedtls_ssl_conf_renegotiation_period (mbedtls_ssl_config *conf, const unsigned char period[8]) |
Set record counter threshold for periodic renegotiation. (Default: 2^48 - 1) | |
int | mbedtls_ssl_check_pending (const mbedtls_ssl_context *ssl) |
Check if there is data already read from the underlying transport but not yet processed. | |
size_t | mbedtls_ssl_get_bytes_avail (const mbedtls_ssl_context *ssl) |
Return the number of application data bytes remaining to be read from the current record. | |
uint32_t | mbedtls_ssl_get_verify_result (const mbedtls_ssl_context *ssl) |
Return the result of the certificate verification. | |
int | mbedtls_ssl_get_ciphersuite_id_from_ssl (const mbedtls_ssl_context *ssl) |
Return the id of the current ciphersuite. | |
const char * | mbedtls_ssl_get_ciphersuite (const mbedtls_ssl_context *ssl) |
Return the name of the current ciphersuite. | |
static mbedtls_ssl_protocol_version | mbedtls_ssl_get_version_number (const mbedtls_ssl_context *ssl) |
Return the (D)TLS protocol version negotiated in the given connection. | |
const char * | mbedtls_ssl_get_version (const mbedtls_ssl_context *ssl) |
Return the current TLS version. | |
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) | |
int | mbedtls_ssl_get_max_out_record_payload (const mbedtls_ssl_context *ssl) |
Return the current maximum outgoing record payload in bytes. | |
int | mbedtls_ssl_get_max_in_record_payload (const mbedtls_ssl_context *ssl) |
Return the current maximum incoming record payload in bytes. | |
const mbedtls_x509_crt * | mbedtls_ssl_get_peer_cert (const mbedtls_ssl_context *ssl) |
Return the peer certificate from the current connection. | |
int | mbedtls_ssl_get_session (const mbedtls_ssl_context *ssl, mbedtls_ssl_session *session) |
Export a session in order to resume it later. | |
int | mbedtls_ssl_handshake (mbedtls_ssl_context *ssl) |
Perform the SSL handshake. | |
static int | mbedtls_ssl_is_handshake_over (mbedtls_ssl_context *ssl) |
After calling mbedtls_ssl_handshake() to start the SSL handshake you can call this function to check whether the handshake is over for a given SSL context. This function should be also used to determine when to stop calling mbedtls_handshake_step() for that context. | |
int | mbedtls_ssl_handshake_step (mbedtls_ssl_context *ssl) |
Perform a single step of the SSL handshake. | |
int | mbedtls_ssl_renegotiate (mbedtls_ssl_context *ssl) |
Initiate an SSL renegotiation on the running connection. Client: perform the renegotiation right now. Server: request renegotiation, which will be performed during the next call to mbedtls_ssl_read() if honored by client. | |
int | mbedtls_ssl_read (mbedtls_ssl_context *ssl, unsigned char *buf, size_t len) |
Read at most 'len' application data bytes. | |
int | mbedtls_ssl_write (mbedtls_ssl_context *ssl, const unsigned char *buf, size_t len) |
Try to write exactly 'len' application data bytes. | |
int | mbedtls_ssl_send_alert_message (mbedtls_ssl_context *ssl, unsigned char level, unsigned char message) |
Send an alert message. | |
int | mbedtls_ssl_close_notify (mbedtls_ssl_context *ssl) |
Notify the peer that the connection is being closed. | |
void | mbedtls_ssl_free (mbedtls_ssl_context *ssl) |
Free referenced items in an SSL context and clear memory. | |
int | mbedtls_ssl_context_save (mbedtls_ssl_context *ssl, unsigned char *buf, size_t buf_len, size_t *olen) |
Save an active connection as serialized data in a buffer. This allows the freeing or re-using of the SSL context while still picking up the connection later in a way that it entirely transparent to the peer. | |
int | mbedtls_ssl_context_load (mbedtls_ssl_context *ssl, const unsigned char *buf, size_t len) |
Load serialized connection data to an SSL 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(). | |
int | mbedtls_ssl_config_defaults (mbedtls_ssl_config *conf, int endpoint, int transport, int preset) |
Load reasonable default SSL configuration values. (You need to call mbedtls_ssl_config_init() first.) | |
void | mbedtls_ssl_config_free (mbedtls_ssl_config *conf) |
Free an SSL configuration context. | |
void | mbedtls_ssl_session_init (mbedtls_ssl_session *session) |
Initialize SSL session structure. | |
void | mbedtls_ssl_session_free (mbedtls_ssl_session *session) |
Free referenced items in an SSL session including the peer certificate and clear memory. | |
int | mbedtls_ssl_tls_prf (const mbedtls_tls_prf_types prf, const unsigned char *secret, size_t slen, const char *label, const unsigned char *random, size_t rlen, unsigned char *dstbuf, size_t dlen) |
TLS-PRF function for key derivation. | |
SSL/TLS functions.
Definition in file ssl.h.
#define MBEDTLS_ERR_SSL_ALLOC_FAILED -0x7F00 |
#define MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS -0x6500 |
#define MBEDTLS_ERR_SSL_BAD_CERTIFICATE -0x7A00 |
#define MBEDTLS_ERR_SSL_BAD_CONFIG -0x5E80 |
#define MBEDTLS_ERR_SSL_BAD_INPUT_DATA -0x7100 |
#define MBEDTLS_ERR_SSL_BAD_PROTOCOL_VERSION -0x6E80 |
#define MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL -0x6A00 |
#define MBEDTLS_ERR_SSL_CA_CHAIN_REQUIRED -0x7680 |
#define MBEDTLS_ERR_SSL_CACHE_ENTRY_NOT_FOUND -0x7E80 |
#define MBEDTLS_ERR_SSL_CANNOT_READ_EARLY_DATA -0x7B80 |
#define MBEDTLS_ERR_SSL_CANNOT_WRITE_EARLY_DATA -0x7C80 |
#define MBEDTLS_ERR_SSL_CERTIFICATE_VERIFICATION_WITHOUT_HOSTNAME -0x5D80 |
Attempt to verify a certificate without an expected hostname. This is usually insecure.
In TLS clients, when a client authenticates a server through its certificate, the client normally checks three things:
Omitting any of these checks is generally insecure, and can allow a malicious server to impersonate a legitimate server.
The third check may be safely skipped in some unusual scenarios, such as networks where eavesdropping is a risk but not active attacks, or a private PKI where the client equally trusts all servers that are accredited by the root CA.
You should call mbedtls_ssl_set_hostname() with the expected server name before starting a TLS handshake on a client (unless the client is set up to only use PSK-based authentication, which does not rely on the host name). If you have determined that server name verification is not required for security in your scenario, call mbedtls_ssl_set_hostname() with NULL
as the server name.
This error is raised if all of the following conditions are met:
#define MBEDTLS_ERR_SSL_CLIENT_RECONNECT -0x6780 |
#define MBEDTLS_ERR_SSL_CONN_EOF -0x7280 |
#define MBEDTLS_ERR_SSL_CONTINUE_PROCESSING -0x6580 |
#define MBEDTLS_ERR_SSL_COUNTER_WRAPPING -0x6B80 |
#define MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS -0x7000 |
#define MBEDTLS_ERR_SSL_DECODE_ERROR -0x7300 |
#define MBEDTLS_ERR_SSL_EARLY_MESSAGE -0x6480 |
#define MBEDTLS_ERR_SSL_FATAL_ALERT_MESSAGE -0x7780 |
#define MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE -0x7080 |
#define MBEDTLS_ERR_SSL_HANDSHAKE_FAILURE -0x6E00 |
#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_ILLEGAL_PARAMETER -0x6600 |
#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_APPLICATION_PROTOCOL -0x7580 |
#define MBEDTLS_ERR_SSL_NO_CLIENT_CERTIFICATE -0x7480 |
#define MBEDTLS_ERR_SSL_NO_RNG -0x7400 |
#define MBEDTLS_ERR_SSL_NON_FATAL -0x6680 |
#define MBEDTLS_ERR_SSL_PEER_CLOSE_NOTIFY -0x7880 |
#define MBEDTLS_ERR_SSL_PK_TYPE_MISMATCH -0x6D00 |
#define MBEDTLS_ERR_SSL_PRIVATE_KEY_REQUIRED -0x7600 |
#define MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA -0x7C00 |
Early data has been received as part of an on-going handshake. This error code can be returned only on server side if and only if early data has been enabled by means of the mbedtls_ssl_conf_early_data() API. This error code can then be returned by mbedtls_ssl_handshake(), mbedtls_ssl_handshake_step(), mbedtls_ssl_read() or mbedtls_ssl_write() if early data has been received as part of the handshake sequence they triggered. To read the early data, call mbedtls_ssl_read_early_data().
#define MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET -0x7B00 |
#define MBEDTLS_ERR_SSL_SESSION_TICKET_EXPIRED -0x6D80 |
#define MBEDTLS_ERR_SSL_TIMEOUT -0x6800 |
#define MBEDTLS_ERR_SSL_UNEXPECTED_CID -0x6000 |
#define MBEDTLS_ERR_SSL_UNEXPECTED_MESSAGE -0x7700 |
#define MBEDTLS_ERR_SSL_UNEXPECTED_RECORD -0x6700 |
#define MBEDTLS_ERR_SSL_UNKNOWN_IDENTITY -0x6C80 |
#define MBEDTLS_ERR_SSL_UNRECOGNIZED_NAME -0x7800 |
#define MBEDTLS_ERR_SSL_UNSUPPORTED_EXTENSION -0x7500 |
#define MBEDTLS_ERR_SSL_VERSION_MISMATCH -0x5F00 |
#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_MISSING_EXTENSION 109 /* 0x6d -- new in TLS 1.3 */ |
#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_CID_IN_LEN_MAX 32 |
#define MBEDTLS_SSL_CID_OUT_LEN_MAX 32 |
#define MBEDTLS_SSL_CID_TLS1_3_PADDING_GRANULARITY 16 |
This option controls the use of record plaintext padding in TLS 1.3 and when using the Connection ID extension in DTLS 1.2.
The padding will always be chosen so that the length of the padded plaintext is a multiple of the value of this option.
Note: A value of 1
means that no padding will be used for outgoing records.
Note: On systems lacking division instructions, a power of two should be preferred.
#define MBEDTLS_SSL_DTLS_MAX_BUFFERING 32768 |
Maximum number of heap-allocated bytes for the purpose of DTLS handshake message reassembly and future message buffering.
This should be at least 9/8 * MBEDTLS_SSL_IN_CONTENT_LEN to account for a reassembled handshake message of maximum size, together with its reassembly bitmap.
A value of 2 * MBEDTLS_SSL_IN_CONTENT_LEN (32768 by default) should be sufficient for all practical situations as it allows to reassembly a large handshake message (such as a certificate) while buffering multiple smaller handshake messages.
#define MBEDTLS_SSL_EMPTY_RENEGOTIATION_INFO 0xFF |
#define MBEDTLS_SSL_IN_CONTENT_LEN 16384 |
Maximum length (in bytes) of incoming plaintext fragments.
This determines the size of the incoming TLS I/O buffer in such a way that it is capable of holding the specified amount of plaintext data, regardless of the protection mechanism used.
Uncomment to set the maximum plaintext size of the incoming I/O buffer.
#define MBEDTLS_SSL_MAX_ALPN_LIST_LEN 65535 |
#define MBEDTLS_SSL_MAX_ALPN_NAME_LEN 255 |
#define MBEDTLS_SSL_MAX_EARLY_DATA_SIZE 1024 |
Complete list of ciphersuites to use, in order of preference.
Use this to save a few hundred bytes of ROM (default ordering of all available ciphersuites) and a few to a few hundred bytes of RAM.
The value below is only an example, not the default.
The default maximum amount of 0-RTT data. See the documentation of mbedtls_ssl_conf_max_early_data_size()
for more information.
It must be positive and smaller than UINT32_MAX.
If MBEDTLS_SSL_EARLY_DATA is not defined, this default value does not have any impact on the build.
#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_OUT_CONTENT_LEN 16384 |
Maximum length (in bytes) of outgoing plaintext fragments.
This determines the size of the outgoing TLS I/O buffer in such a way that it is capable of holding the specified amount of plaintext data, regardless of the protection mechanism used.
It is possible to save RAM by setting a smaller outward buffer, while keeping the default inward 16384 byte buffer to conform to the TLS specification.
The minimum required outward buffer size is determined by the handshake protocol's usage. Handshaking will fail if the outward buffer is too small. The specific size requirement depends on the configured ciphers and any certificate data which is sent during the handshake.
Uncomment to set the maximum plaintext size of the outgoing I/O buffer.
#define MBEDTLS_SSL_TLS1_3_DEFAULT_NEW_SESSION_TICKETS 1 |
#define MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_ALL |
#define MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL (1u << 1) |
#define MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL_ALL |
All ephemeral TLS 1.3 key exchanges
#define MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK (1u << 0) |
#define MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_ALL |
All PSK-based TLS 1.3 key exchanges
#define MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL (1u << 2) |
#define MBEDTLS_SSL_TLS1_3_PSK_MODE_ECDHE 1 /* PSK+ECDHE-based exchange */ |
#define MBEDTLS_SSL_TLS1_3_PSK_MODE_PURE 0 /* Pure PSK-based exchange */ |
#define MBEDTLS_SSL_TLS1_3_SIGNAL_NEW_SESSION_TICKETS_DISABLED 0 |
#define MBEDTLS_SSL_TLS1_3_SIGNAL_NEW_SESSION_TICKETS_ENABLED 1 |
#define MBEDTLS_SSL_TLS1_3_TICKET_AGE_TOLERANCE 6000 |
Maximum allowed ticket age difference in milliseconds tolerated between server and client. Default value is 6000. This is not used in TLS 1.2.
The ages might be different due to the client and server clocks not running at the same pace. The typical accuracy of an RTC crystal is ±100 to ±20 parts per million (360 to 72 milliseconds per hour). Default tolerance window is 6s, thus in the worst case clients and servers must sync up their system time every 6000/360/2~=8 hours.
See section 8.3 of the TLS 1.3 specification(RFC 8446) for more information.
#define MBEDTLS_SSL_TLS1_3_TICKET_ALLOW_PSK_EPHEMERAL_RESUMPTION MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL /* 1U << 2 */ |
#define MBEDTLS_SSL_TLS1_3_TICKET_ALLOW_PSK_RESUMPTION MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK /* 1U << 0 */ |
#define MBEDTLS_SSL_TLS1_3_TICKET_FLAGS_MASK |
#define MBEDTLS_SSL_TLS1_3_TICKET_NONCE_LENGTH 32 |
#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_TLS1_3_MD_MAX_SIZE PSA_HASH_MAX_SIZE |
#define MBEDTLS_TLS_EXT_CLI_CERT_TYPE 19 /* RFC 7250 TLS 1.2 and 1.3 */ |
#define MBEDTLS_TLS_EXT_EXTENDED_MASTER_SECRET 0x0017 /* 23 */ |
#define MBEDTLS_TLS_EXT_HEARTBEAT 15 /* RFC 6520 TLS 1.2 and 1.3 */ |
#define MBEDTLS_TLS_EXT_PADDING 21 /* RFC 7685 TLS 1.2 and 1.3 */ |
#define MBEDTLS_TLS_EXT_POST_HANDSHAKE_AUTH 49 /* RFC 8446 TLS 1.3 */ |
#define MBEDTLS_TLS_EXT_PRE_SHARED_KEY 41 /* RFC 8446 TLS 1.3 */ |
#define MBEDTLS_TLS_EXT_PSK_KEY_EXCHANGE_MODES 45 /* RFC 8446 TLS 1.3 */ |
#define MBEDTLS_TLS_EXT_RECORD_SIZE_LIMIT 28 /* RFC 8449 (implemented for TLS 1.3 only) */ |
#define MBEDTLS_TLS_EXT_SERV_CERT_TYPE 20 /* RFC 7250 TLS 1.2 and 1.3 */ |
#define MBEDTLS_TLS_EXT_SIG_ALG_CERT 50 /* RFC 8446 TLS 1.3 */ |
#define MBEDTLS_TLS_EXT_STATUS_REQUEST 5 /* RFC 6066 TLS 1.2 and 1.3 */ |
#define MBEDTLS_TLS_EXT_SUPPORTED_GROUPS 10 /* RFC 8422,7919 TLS 1.2 and 1.3 */ |
#define MBEDTLS_TLS_EXT_SUPPORTED_VERSIONS 43 /* RFC 8446 TLS 1.3 */ |
typedef int mbedtls_ssl_cache_get_t(void *data, unsigned char const *session_id, size_t session_id_len, mbedtls_ssl_session *session) |
Callback type: server-side session cache getter.
The session cache is logically a key value store, with keys being session IDs and values being instances of mbedtls_ssl_session. This callback retrieves an entry in this key-value store.
data | The address of the session cache structure to query. |
session_id | The buffer holding the session ID to query. |
session_id_len | The length of session_id in Bytes. |
session | The address of the session structure to populate. It is initialized with mbdtls_ssl_session_init(), and the callback must always leave it in a state where it can safely be freed via mbedtls_ssl_session_free() independent of the return code of this function. |
0
on success typedef int mbedtls_ssl_cache_set_t(void *data, unsigned char const *session_id, size_t session_id_len, const mbedtls_ssl_session *session) |
Callback type: server-side session cache setter.
The session cache is logically a key value store, with keys being session IDs and values being instances of mbedtls_ssl_session. This callback sets an entry in this key-value store.
data | The address of the session cache structure to modify. |
session_id | The buffer holding the session ID to query. |
session_id_len | The length of session_id in Bytes. |
session | The address of the session to be stored in the session cache. |
0
on success 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.
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 |
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.
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 |
typedef void mbedtls_ssl_export_keys_t(void *p_expkey, mbedtls_ssl_key_export_type type, const unsigned char *secret, size_t secret_len, const unsigned char client_random[32], const unsigned char server_random[32], mbedtls_tls_prf_types tls_prf_type) |
Callback type: Export key alongside random values for session identification, and PRF for implementation of TLS key exporters.
p_expkey | Context for the callback. |
type | The type of the key that is being exported. |
secret | The address of the buffer holding the secret that's being exporterd. |
secret_len | The length of secret in bytes. |
client_random | The client random bytes. |
server_random | The server random bytes. |
tls_prf_type | The identifier for the PRF used in the handshake to which the key belongs. |
typedef struct mbedtls_ssl_flight_item mbedtls_ssl_flight_item |
typedef int mbedtls_ssl_get_timer_t(void *ctx) |
typedef struct mbedtls_ssl_handshake_params mbedtls_ssl_handshake_params |
typedef int(* mbedtls_ssl_hs_cb_t) (mbedtls_ssl_context *ssl) |
Callback type: generic handshake callback.
mbedtls_ssl_get_user_data_p()
mbedtls_ssl_get_user_data_n()
mbedtls_ssl_conf_get_user_data_p()
mbedtls_ssl_conf_get_user_data_n()
ssl | mbedtls_ssl_context on which the callback is run |
typedef struct mbedtls_ssl_key_cert mbedtls_ssl_key_cert |
typedef int mbedtls_ssl_recv_t(void *ctx, unsigned char *buf, size_t len) |
Callback type: receive data from the network.
ctx | Context for the receive callback (typically a file descriptor) |
buf | Buffer to write the received data to |
len | Length of the receive buffer |
0
if the connection has been closed. MBEDTLS_ERR_SSL_WANT_READ
must be returned when the operation would block. typedef int mbedtls_ssl_recv_timeout_t(void *ctx, unsigned char *buf, size_t len, uint32_t timeout) |
Callback type: receive data from the network, with timeout.
ctx | Context for the receive callback (typically a file descriptor) |
buf | Buffer to write the received data to |
len | Length of the receive buffer |
timeout | Maximum number of milliseconds to wait for data 0 means no timeout (potentially waiting forever) |
MBEDTLS_ERR_SSL_TIMEOUT
if the operation timed out, MBEDTLS_ERR_SSL_WANT_READ
if interrupted by a signal.typedef int mbedtls_ssl_send_t(void *ctx, const unsigned char *buf, size_t len) |
Callback type: send data on the network.
ctx | Context for the send callback (typically a file descriptor) |
buf | Buffer holding the data to send |
len | Length of the data to send |
MBEDTLS_ERR_SSL_WANT_WRITE
must be returned when the operation would block.typedef struct mbedtls_ssl_session mbedtls_ssl_session |
typedef void mbedtls_ssl_set_timer_t(void *ctx, uint32_t int_ms, uint32_t fin_ms) |
Callback type: set a pair of timers/delays to watch.
ctx | Context pointer |
int_ms | Intermediate delay in milliseconds |
fin_ms | Final delay in milliseconds 0 cancels the current timer. |
mbedtls_ssl_get_timer_t
callback to return correct information.mbedtls_ssl_handshake()
with the proper SSL context to be scheduled. Care must be taken to ensure that at most one such call happens at a time.typedef struct mbedtls_ssl_sig_hash_set_t mbedtls_ssl_sig_hash_set_t |
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.
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. |
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.
p_ticket | Context for the callback |
session | SSL session to be written in the ticket |
start | Start of the output 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 |
typedef struct mbedtls_ssl_transform mbedtls_ssl_transform |
enum mbedtls_ssl_states |
int mbedtls_ssl_check_pending | ( | const mbedtls_ssl_context * | ssl | ) |
Check if there is data already read from the underlying transport but not yet processed.
ssl | SSL context |
mbedtls_ssl_get_bytes_avail
in that it considers any kind of unprocessed data, not only unread application data. If mbedtls_ssl_get_bytes
returns a non-zero value, this function will also signal pending data, but the converse does not hold. For example, in DTLS there might be further records waiting to be processed from the current underlying transport's datagram.mbedtls_ssl_read
will provide any data; e.g., the unprocessed data might turn out to be an alert or a handshake message.int mbedtls_ssl_check_record | ( | mbedtls_ssl_context const * | ssl, |
unsigned char * | buf, | ||
size_t | buflen | ||
) |
Check whether a buffer contains a valid and authentic record that has not been seen before. (DTLS only).
This function does not change the user-visible state of the SSL context. Its sole purpose is to provide an indication of the legitimacy of an incoming record.
This can be useful e.g. in distributed server environments using the DTLS Connection ID feature, in which connections might need to be passed between service instances on a change of peer address, but where such disruptive operations should only happen after the validity of incoming records has been confirmed.
ssl | The SSL context to use. |
buf | The address of the buffer holding the record to be checked. This must be a read/write buffer of length buflen Bytes. |
buflen | The length of buf in Bytes. |
buf
. If you need to preserve the original record, you have to maintain a copy.0
if the record is valid and authentic and has not been seen before. int mbedtls_ssl_close_notify | ( | mbedtls_ssl_context * | ssl | ) |
Notify the peer that the connection is being closed.
ssl | SSL context |
mbedtls_ssl_session_reset()
on it before re-using it for a new connection; the current connection must be closed. int mbedtls_ssl_conf_alpn_protocols | ( | mbedtls_ssl_config * | conf, |
const char ** | protos | ||
) |
Set the supported Application Layer Protocols.
conf | SSL configuration |
protos | Pointer to a NULL-terminated list of supported protocols, in decreasing preference order. The pointer to the list is recorded by the library for later reference as required, so the lifetime of the table must be at least as long as the lifetime of the SSL configuration structure. |
void mbedtls_ssl_conf_authmode | ( | mbedtls_ssl_config * | conf, |
int | authmode | ||
) |
Set the certificate verification mode Default: NONE on server, REQUIRED on client.
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. (default on client)
void mbedtls_ssl_conf_ca_chain | ( | mbedtls_ssl_config * | conf, |
mbedtls_x509_crt * | ca_chain, | ||
mbedtls_x509_crl * | ca_crl | ||
) |
Set the data required to verify peer certificate.
mbedtls_x509_crt_verify()
for notes regarding the parameters ca_chain (maps to trust_ca for that function) and ca_crl.conf | SSL configuration |
ca_chain | trusted CA chain (meaning all fully trusted top-level CAs) |
ca_crl | trusted CA CRLs |
|
inlinestatic |
Set the certificate selection callback (server-side only).
If set, the callback is always called for each handshake, after `ClientHello` processing has finished.
conf | The SSL configuration to register the callback with. |
f_cert_cb | The callback for selecting server certificate after ClientHello processing has finished. |
void mbedtls_ssl_conf_cert_profile | ( | mbedtls_ssl_config * | conf, |
const mbedtls_x509_crt_profile * | profile | ||
) |
Set the X.509 security profile used for verification.
conf | SSL configuration |
profile | Profile to use |
void mbedtls_ssl_conf_cert_req_ca_list | ( | mbedtls_ssl_config * | conf, |
char | cert_req_ca_list | ||
) |
Whether to send a list of acceptable CAs in CertificateRequest messages. (Default: do send)
conf | SSL configuration |
cert_req_ca_list | MBEDTLS_SSL_CERT_REQ_CA_LIST_ENABLED or MBEDTLS_SSL_CERT_REQ_CA_LIST_DISABLED |
int mbedtls_ssl_conf_cid | ( | mbedtls_ssl_config * | conf, |
size_t | len, | ||
int | ignore_other_cids | ||
) |
Specify the length of Connection IDs for incoming encrypted DTLS records, as well as the behaviour on unexpected CIDs.
By default, the CID length is set to 0
, and unexpected CIDs are silently ignored.
conf | The SSL configuration to modify. |
len | The length in Bytes of the CID fields in encrypted DTLS records using the CID mechanism. This must not be larger than MBEDTLS_SSL_CID_OUT_LEN_MAX. |
ignore_other_cids | This determines the stack's behaviour when receiving a record with an unexpected CID. Possible values are:
|
0
on success. len
is too large. 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.
For TLS 1.2, the notion of ciphersuite determines both the key exchange mechanism and the suite of symmetric algorithms to be used during and after the handshake.
For TLS 1.3 (in development), the notion of ciphersuite only determines the suite of symmetric algorithms to be used during and after the handshake, while key exchange mechanisms are configured separately.
In Mbed TLS, ciphersuites for both TLS 1.2 and TLS 1.3 are configured via this function. For users of TLS 1.3, there will be separate API for the configuration of key exchange mechanisms.
The list of ciphersuites passed to this function may contain a mixture of TLS 1.2 and TLS 1.3 ciphersuite identifiers. This is useful if negotiation of TLS 1.3 should be attempted, but a fallback to TLS 1.2 would be tolerated.
ciphersuites
is not copied. It must remain valid for the lifetime of the SSL configuration conf
.conf | The SSL configuration to modify. |
ciphersuites | A 0-terminated list of IANA identifiers of supported ciphersuites, accessible through MBEDTLS_TLS_XXX and MBEDTLS_TLS1_3_XXX macros defined in ssl_ciphersuites.h. |
void MBEDTLS_DEPRECATED mbedtls_ssl_conf_curves | ( | mbedtls_ssl_config * | conf, |
const mbedtls_ecp_group_id * | curves | ||
) |
Set the allowed curves in order of preference.
On server: this only affects selection of the ECDHE curve; the curves used for ECDH and ECDSA are determined by the list of available certificates instead. On client: this affects the list of curves offered for any use. The server can override our preference order. Both sides: limits the set of curves accepted for use in ECDHE and in the peer's end-entity certificate.
mbedtls_ssl_conf_cert_profile()
for that. For the end-entity certificate however, the key will be accepted only if it is allowed both by this list and by the cert profile.conf | SSL configuration |
curves | Ordered list of allowed curves, terminated by MBEDTLS_ECP_DP_NONE. |
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
conf | SSL configuration |
f_dbg | debug function |
p_dbg | debug parameter |
int mbedtls_ssl_conf_dh_param_bin | ( | mbedtls_ssl_config * | conf, |
const unsigned char * | dhm_P, | ||
size_t | P_len, | ||
const unsigned char * | dhm_G, | ||
size_t | G_len | ||
) |
Set the Diffie-Hellman public P and G values from big-endian binary presentations. (Default values: MBEDTLS_DHM_RFC3526_MODP_2048_[PG]_BIN)
conf | SSL configuration |
dhm_P | Diffie-Hellman-Merkle modulus in big-endian binary form |
P_len | Length of DHM modulus |
dhm_G | Diffie-Hellman-Merkle generator in big-endian binary form |
G_len | Length of DHM generator |
int mbedtls_ssl_conf_dh_param_ctx | ( | mbedtls_ssl_config * | conf, |
mbedtls_dhm_context * | dhm_ctx | ||
) |
Set the Diffie-Hellman public P and G values, read from existing context (server-side only)
conf | SSL configuration |
dhm_ctx | Diffie-Hellman-Merkle context |
void mbedtls_ssl_conf_dhm_min_bitlen | ( | mbedtls_ssl_config * | conf, |
unsigned int | bitlen | ||
) |
Set the minimum length for Diffie-Hellman parameters. (Client-side only.) (Default: 1024 bits.)
conf | SSL configuration |
bitlen | Minimum bit length of the DHM prime |
|
inlinestatic |
Set DN hints sent to client in CertificateRequest message.
mbedtls_ssl_conf_ca_chain()
or mbedtls_ssl_set_hs_ca_chain()
)conf | SSL configuration |
crt | crt chain whose subject DNs are issuer DNs of client certs from which the client should select client peer certificate. |
void mbedtls_ssl_conf_dtls_anti_replay | ( | mbedtls_ssl_config * | conf, |
char | mode | ||
) |
Enable or disable anti-replay protection for DTLS. (DTLS only, no effect on TLS.) Default: enabled.
conf | SSL configuration |
mode | MBEDTLS_SSL_ANTI_REPLAY_ENABLED or MBEDTLS_SSL_ANTI_REPLAY_DISABLED. |
void mbedtls_ssl_conf_dtls_badmac_limit | ( | mbedtls_ssl_config * | conf, |
unsigned | limit | ||
) |
Set a limit on the number of records with a bad MAC before terminating the connection. (DTLS only, no effect on TLS.) Default: 0 (disabled).
conf | SSL configuration |
limit | Limit, or 0 to disable. |
void mbedtls_ssl_conf_dtls_cookies | ( | mbedtls_ssl_config * | conf, |
mbedtls_ssl_cookie_write_t * | f_cookie_write, | ||
mbedtls_ssl_cookie_check_t * | f_cookie_check, | ||
void * | p_cookie | ||
) |
Register callbacks for DTLS cookies (Server only. DTLS only.)
Default: dummy callbacks that fail, in order to force you to register working callbacks (and initialize their context).
To disable HelloVerifyRequest, register NULL callbacks.
mbedtls_ssl_handshake()
about handling the MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED that is expected on the first handshake attempt when this is enabled.mbedtls_ssl_read()
for details.conf | SSL configuration |
f_cookie_write | Cookie write callback |
f_cookie_check | Cookie check callback |
p_cookie | Context for both callbacks |
void mbedtls_ssl_conf_encrypt_then_mac | ( | mbedtls_ssl_config * | conf, |
char | etm | ||
) |
Enable or disable Encrypt-then-MAC (Default: MBEDTLS_SSL_ETM_ENABLED)
conf | SSL configuration |
etm | MBEDTLS_SSL_ETM_ENABLED or MBEDTLS_SSL_ETM_DISABLED |
void mbedtls_ssl_conf_endpoint | ( | mbedtls_ssl_config * | conf, |
int | endpoint | ||
) |
Set the current endpoint type.
conf | SSL configuration |
endpoint | must be MBEDTLS_SSL_IS_CLIENT or MBEDTLS_SSL_IS_SERVER |
void mbedtls_ssl_conf_extended_master_secret | ( | mbedtls_ssl_config * | conf, |
char | ems | ||
) |
Enable or disable Extended Master Secret negotiation. (Default: MBEDTLS_SSL_EXTENDED_MS_ENABLED)
conf | SSL configuration |
ems | MBEDTLS_SSL_EXTENDED_MS_ENABLED or MBEDTLS_SSL_EXTENDED_MS_DISABLED |
|
inlinestatic |
|
inlinestatic |
Retrieve the user data in an SSL configuration as an integer.
This is the value last set with mbedtls_ssl_conf_set_user_data_n(), or 0
if mbedtls_ssl_conf_set_user_data_n() has not previously been called. The value is undefined if mbedtls_ssl_conf_set_user_data_p() has been called without a subsequent call to mbedtls_ssl_conf_set_user_data_n().
conf | The SSL configuration context to modify. |
|
inlinestatic |
Retrieve the user data in an SSL configuration as a pointer.
This is the value last set with mbedtls_ssl_conf_set_user_data_p(), or NULL
if mbedtls_ssl_conf_set_user_data_p() has not previously been called. The value is undefined if mbedtls_ssl_conf_set_user_data_n() has been called without a subsequent call to mbedtls_ssl_conf_set_user_data_p().
conf | The SSL configuration context to modify. |
void mbedtls_ssl_conf_groups | ( | mbedtls_ssl_config * | conf, |
const uint16_t * | groups | ||
) |
Set the allowed groups in order of preference.
On server: This only affects the choice of key agreement mechanism On client: this affects the list of groups offered for any use. The server can override our preference order. Both sides: limits the set of groups accepted for use in key sharing.
conf | SSL configuration |
groups | List of allowed groups ordered by preference, terminated by 0. Must contain valid IANA NamedGroup IDs (provided via either an integer or using MBEDTLS_TLS1_3_NAMED_GROUP_XXX macros). |
void mbedtls_ssl_conf_handshake_timeout | ( | mbedtls_ssl_config * | conf, |
uint32_t | min, | ||
uint32_t | max | ||
) |
Set retransmit timeout values for the DTLS handshake. (DTLS only, no effect on TLS.)
conf | SSL configuration |
min | Initial timeout value in milliseconds. Default: 1000 (1 second). |
max | Maximum timeout value in milliseconds. Default: 60000 (60 seconds). |
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)
conf | SSL configuration |
allow_legacy | Prevent or allow (SSL_NO_LEGACY_RENEGOTIATION, SSL_ALLOW_LEGACY_RENEGOTIATION or MBEDTLS_SSL_LEGACY_BREAK_HANDSHAKE) |
int mbedtls_ssl_conf_max_frag_len | ( | mbedtls_ssl_config * | conf, |
unsigned char | mfl_code | ||
) |
Set the maximum fragment length to emit and/or negotiate. (Typical: the smaller of MBEDTLS_SSL_IN_CONTENT_LEN and MBEDTLS_SSL_OUT_CONTENT_LEN, usually 2^14
bytes) (Server: set maximum fragment length to emit, usually negotiated by the client during handshake) (Client: set maximum fragment length to emit and negotiate with the server during handshake) (Default: MBEDTLS_SSL_MAX_FRAG_LEN_NONE)
mbedtls_ssl_read()
), not handshake messages. With DTLS, this affects both ApplicationData and handshake.mbedtls_ssl_get_record_expansion()
.mbedtls_ssl_set_mtu()
.conf | SSL configuration |
mfl_code | Code for maximum fragment length (allowed values: MBEDTLS_SSL_MAX_FRAG_LEN_512, MBEDTLS_SSL_MAX_FRAG_LEN_1024, MBEDTLS_SSL_MAX_FRAG_LEN_2048, MBEDTLS_SSL_MAX_FRAG_LEN_4096) |
|
inlinestatic |
Set the maximum supported version sent from the client side and/or accepted at the server side.
conf | SSL configuration |
tls_version | TLS protocol version number (mbedtls_ssl_protocol_version ) (MBEDTLS_SSL_VERSION_UNKNOWN is not valid) |
void MBEDTLS_DEPRECATED 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.
See also the documentation of mbedtls_ssl_conf_min_version().
mbedtls_ssl_conf_max_tls_version()
.conf | SSL configuration |
major | Major version number (MBEDTLS_SSL_MAJOR_VERSION_3) |
minor | Minor version number (MBEDTLS_SSL_MINOR_VERSION_3 for (D)TLS 1.2, MBEDTLS_SSL_MINOR_VERSION_4 for TLS 1.3) |
|
inlinestatic |
Set the minimum supported version sent from the client side and/or accepted at the server side.
conf | SSL configuration |
tls_version | TLS protocol version number (mbedtls_ssl_protocol_version ) (MBEDTLS_SSL_VERSION_UNKNOWN is not valid) |
void MBEDTLS_DEPRECATED mbedtls_ssl_conf_min_version | ( | mbedtls_ssl_config * | conf, |
int | major, | ||
int | minor | ||
) |
Set the minimum accepted SSL/TLS protocol version.
major
= MBEDTLS_SSL_MAJOR_VERSION_3, minor
= MBEDTLS_SSL_MINOR_VERSION_3major
= MBEDTLS_SSL_MAJOR_VERSION_3, minor
= MBEDTLS_SSL_MINOR_VERSION_4Note that the numbers in the constant names are the TLS internal protocol numbers, and the minor versions differ by one from the human-readable versions!
mbedtls_ssl_conf_min_tls_version()
.conf | SSL configuration |
major | Major version number (MBEDTLS_SSL_MAJOR_VERSION_3) |
minor | Minor version number (MBEDTLS_SSL_MINOR_VERSION_3 for (D)TLS 1.2, MBEDTLS_SSL_MINOR_VERSION_4 for TLS 1.3) |
void mbedtls_ssl_conf_new_session_tickets | ( | mbedtls_ssl_config * | conf, |
uint16_t | num_tickets | ||
) |
Number of NewSessionTicket messages for the server to send after handshake completion.
MBEDTLS_SSL_TLS1_3_DEFAULT_NEW_SESSION_TICKETS
.conf | SSL configuration |
num_tickets | Number of NewSessionTicket. |
int mbedtls_ssl_conf_own_cert | ( | mbedtls_ssl_config * | conf, |
mbedtls_x509_crt * | own_cert, | ||
mbedtls_pk_context * | pk_key | ||
) |
Set own certificate chain and private key.
pk_key
needs to match the public key in the first certificate in own_cert
, or all handshakes using that certificate will fail. It is your responsibility to ensure that; this function will not perform any check. You may use mbedtls_pk_check_pair() in order to perform this check yourself, but be aware that this function can be computationally expensive on some key types.conf | SSL configuration |
own_cert | own public certificate chain |
pk_key | own private key |
void mbedtls_ssl_conf_preference_order | ( | mbedtls_ssl_config * | conf, |
int | order | ||
) |
Pick the ciphersuites order according to the second parameter in the SSL Server module (MBEDTLS_SSL_SRV_C). (Default, if never called: MBEDTLS_SSL_SRV_CIPHERSUITE_ORDER_SERVER)
conf | SSL configuration |
order | Server or client (MBEDTLS_SSL_SRV_CIPHERSUITE_ORDER_SERVER or MBEDTLS_SSL_SRV_CIPHERSUITE_ORDER_CLIENT) |
int mbedtls_ssl_conf_psk | ( | mbedtls_ssl_config * | conf, |
const unsigned char * | psk, | ||
size_t | psk_len, | ||
const unsigned char * | psk_identity, | ||
size_t | psk_identity_len | ||
) |
Configure pre-shared keys (PSKs) and their identities to be used in PSK-based ciphersuites.
Only one PSK can be registered, through either mbedtls_ssl_conf_psk() or mbedtls_ssl_conf_psk_opaque(). If you attempt to register more than one PSK, this function fails, though this may change in future versions, which may add support for multiple PSKs.
mbedtls_ssl_conf_psk_cb()
instead.mbedtls_ssl_set_hs_psk()
in the PSK callback takes precedence over a PSK configured by this function.conf | The SSL configuration to register the PSK with. |
psk | The pointer to the pre-shared key to use. |
psk_len | The length of the pre-shared key in bytes. |
psk_identity | The pointer to the pre-shared key identity. |
psk_identity_len | The length of the pre-shared key identity in bytes. |
0
if successful. void mbedtls_ssl_conf_psk_cb | ( | mbedtls_ssl_config * | conf, |
int(*)(void *, mbedtls_ssl_context *, const unsigned char *, size_t) | f_psk, | ||
void * | p_psk | ||
) |
Set the PSK callback (server-side only).
If set, the PSK callback is called for each handshake where a PSK-based ciphersuite was negotiated. The caller provides the identity received and wants to receive the actual PSK data and length. The callback has the following parameters: - \c void*: The opaque pointer \p p_psk. - \c mbedtls_ssl_context*: The SSL context to which the operation applies. - \c const unsigned char*: The PSK identity selected by the client. - \c size_t: The length of the PSK identity selected by the client. If a valid PSK identity is found, the callback should use \c mbedtls_ssl_set_hs_psk() or \c mbedtls_ssl_set_hs_psk_opaque() on the SSL context to set the correct PSK and return \c 0. Any other return value will result in a denied PSK identity.
mbedtls_ssl_conf_psk()
or mbedtls_ssl_conf_psk_opaque()
). This means that if you set a PSK callback using this function, you don't need to set a PSK using mbedtls_ssl_conf_psk()
or mbedtls_ssl_conf_psk_opaque()
).conf | The SSL configuration to register the callback with. |
f_psk | The callback for selecting and setting the PSK based in the PSK identity chosen by the client. |
p_psk | A pointer to an opaque structure to be passed to the callback, for example a PSK store. |
void mbedtls_ssl_conf_read_timeout | ( | mbedtls_ssl_config * | conf, |
uint32_t | timeout | ||
) |
Set the timeout period for mbedtls_ssl_read() (Default: no timeout.)
conf | SSL configuration context |
timeout | Timeout value in milliseconds. Use 0 for no timeout (default). |
f_recv_timeout
was set with mbedtls_ssl_set_bio()
. With non-blocking I/O, this will only work if timer callbacks were set with mbedtls_ssl_set_timer_cb()
.void mbedtls_ssl_conf_renegotiation | ( | mbedtls_ssl_config * | conf, |
int | renegotiation | ||
) |
Enable / Disable renegotiation support for connection when initiated by peer (Default: MBEDTLS_SSL_RENEGOTIATION_DISABLED)
conf | SSL configuration |
renegotiation | Enable or disable (MBEDTLS_SSL_RENEGOTIATION_ENABLED or MBEDTLS_SSL_RENEGOTIATION_DISABLED) |
void mbedtls_ssl_conf_renegotiation_enforced | ( | mbedtls_ssl_config * | conf, |
int | max_records | ||
) |
Enforce renegotiation requests. (Default: enforced, max_records = 16)
When we request a renegotiation, the peer can comply or ignore the request. This function allows us to decide whether to enforce our renegotiation requests by closing the connection if the peer doesn't comply.
However, records could already be in transit from the peer when the request is emitted. In order to increase reliability, we can accept a number of records before the expected handshake records.
The optimal value is highly dependent on the specific usage scenario.
conf | SSL configuration |
max_records | Use MBEDTLS_SSL_RENEGOTIATION_NOT_ENFORCED if you don't want to enforce renegotiation, or a non-negative value to enforce it but allow for a grace period of max_records records. |
void mbedtls_ssl_conf_renegotiation_period | ( | mbedtls_ssl_config * | conf, |
const unsigned char | period[8] | ||
) |
Set record counter threshold for periodic renegotiation. (Default: 2^48 - 1)
Renegotiation is automatically triggered when a record counter (outgoing or incoming) crosses the defined threshold. The default value is meant to prevent the connection from being closed when the counter is about to reached its maximal value (it is not allowed to wrap).
Lower values can be used to enforce policies such as "keys must be refreshed every N packets with cipher X".
The renegotiation period can be disabled by setting conf->disable_renegotiation to MBEDTLS_SSL_RENEGOTIATION_DISABLED.
conf | SSL configuration |
period | The threshold value: a big-endian 64-bit number. |
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.
conf | SSL configuration |
f_rng | RNG function (mandatory) |
p_rng | RNG parameter |
void mbedtls_ssl_conf_session_cache | ( | mbedtls_ssl_config * | conf, |
void * | p_cache, | ||
mbedtls_ssl_cache_get_t * | f_get_cache, | ||
mbedtls_ssl_cache_set_t * | f_set_cache | ||
) |
Set the session cache callbacks (server-side only) If not set, no session resuming is done (except if session tickets are enabled too).
The session cache has the responsibility to check for stale entries based on timeout. See RFC 5246 for recommendations.
Warning: session.peer_cert is cleared by the SSL/TLS layer on connection shutdown, so do not cache the pointer! Either set it to NULL or make a full copy of the certificate.
The get callback is called once during the initial handshake to enable session resuming. The get function has the following parameters: (void *parameter, mbedtls_ssl_session *session) If a valid entry is found, it should fill the master of the session object with the cached values and return 0, return 1 otherwise. Optionally peer_cert can be set as well if it is properly present in cache entry.
The set callback is called once during the initial handshake to enable session resuming after the entire handshake has been finished. The set function has the following parameters: (void *parameter, const mbedtls_ssl_session *session). The function should create a cache entry for future retrieval based on the data in the session structure and should keep in mind that the mbedtls_ssl_session object presented (and all its referenced data) is cleared by the SSL/TLS layer when the connection is terminated. It is recommended to add metadata to determine if an entry is still valid in the future. Return 0 if successfully cached, return 1 otherwise.
conf | SSL configuration |
p_cache | parameter (context) for both callbacks |
f_get_cache | session get callback |
f_set_cache | session set callback |
void mbedtls_ssl_conf_session_tickets | ( | mbedtls_ssl_config * | conf, |
int | use_tickets | ||
) |
Enable / Disable TLS 1.2 session tickets (client only, TLS 1.2 only). Enabled by default.
mbedtls_ssl_conf_session_tickets_cb()
.conf | SSL configuration |
use_tickets | Enable or disable (MBEDTLS_SSL_SESSION_TICKETS_ENABLED or MBEDTLS_SSL_SESSION_TICKETS_DISABLED) |
void mbedtls_ssl_conf_session_tickets_cb | ( | mbedtls_ssl_config * | conf, |
mbedtls_ssl_ticket_write_t * | f_ticket_write, | ||
mbedtls_ssl_ticket_parse_t * | f_ticket_parse, | ||
void * | p_ticket | ||
) |
Configure SSL session ticket callbacks (server only). (Default: none.)
mbedtls_ssl_conf_session_tickets()
.conf | SSL configuration context |
f_ticket_write | Callback for writing a ticket |
f_ticket_parse | Callback for parsing a ticket |
p_ticket | Context shared by the two callbacks |
|
inlinestatic |
Set the user data in an SSL configuration to an integer.
You can retrieve this value later with mbedtls_ssl_conf_get_user_data_n().
conf | The SSL configuration context to modify. |
n | The new value of the user data. |
|
inlinestatic |
Set the user data in an SSL configuration to a pointer.
You can retrieve this value later with mbedtls_ssl_conf_get_user_data_p().
p
without accessing it. It is the responsibility of the caller to ensure that the pointer remains valid.conf | The SSL configuration context to modify. |
p | The new value of the user data. |
void mbedtls_ssl_conf_sig_algs | ( | mbedtls_ssl_config * | conf, |
const uint16_t * | sig_algs | ||
) |
Configure allowed signature algorithms for use in TLS.
conf | The SSL configuration to use. |
sig_algs | List of allowed IANA values for TLS 1.3 signature algorithms, terminated by MBEDTLS_TLS1_3_SIG_NONE. The list must remain available throughout the lifetime of the conf object.
|
void MBEDTLS_DEPRECATED mbedtls_ssl_conf_sig_hashes | ( | mbedtls_ssl_config * | conf, |
const int * | hashes | ||
) |
Set the allowed hashes for signatures during the handshake.
mbedtls_ssl_conf_ciphersuites()
. Hashes used for certificate signature are controlled by the verification profile, see mbedtls_ssl_conf_cert_profile()
.conf | SSL configuration |
hashes | Ordered list of allowed signature hashes, terminated by MBEDTLS_MD_NONE . |
void mbedtls_ssl_conf_sni | ( | mbedtls_ssl_config * | conf, |
int(*)(void *, mbedtls_ssl_context *, const unsigned char *, size_t) | f_sni, | ||
void * | p_sni | ||
) |
Set server side ServerName TLS extension callback (optional, server-side only).
If set, the ServerName callback is called whenever the server receives a ServerName TLS extension from the client during a handshake. The ServerName callback has the following parameters: (void *parameter, mbedtls_ssl_context *ssl, const unsigned char *hostname, size_t len). If a suitable certificate is found, the callback must set the certificate(s) and key(s) to use with mbedtls_ssl_set_hs_own_cert()
(can be called repeatedly), and may optionally adjust the CA and associated CRL with mbedtls_ssl_set_hs_ca_chain()
as well as the client authentication mode with mbedtls_ssl_set_hs_authmode()
, then must return 0. If no matching name is found, the callback may return non-zero to abort the handshake.
conf | SSL configuration |
f_sni | verification function |
p_sni | verification parameter |
void mbedtls_ssl_conf_tls13_enable_signal_new_session_tickets | ( | mbedtls_ssl_config * | conf, |
int | signal_new_session_tickets | ||
) |
Enable / Disable handling of TLS 1.3 NewSessionTicket messages (client only, TLS 1.3 only).
The handling of TLS 1.3 NewSessionTicket messages is disabled by default.
In TLS 1.3, servers may send a NewSessionTicket message at any time, and may send multiple NewSessionTicket messages. By default, TLS 1.3 clients ignore NewSessionTicket messages.
To support session tickets in TLS 1.3 clients, call this function with MBEDTLS_SSL_TLS1_3_SIGNAL_NEW_SESSION_TICKETS_ENABLED. When this is enabled, when a client receives a NewSessionTicket message, the next call to a message processing functions (notably mbedtls_ssl_handshake() and mbedtls_ssl_read()) will return MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET. The client should then call mbedtls_ssl_get_session() to retrieve the session ticket before calling the same message processing function again.
conf | SSL configuration |
signal_new_session_tickets | Enable or disable (MBEDTLS_SSL_TLS1_3_SIGNAL_NEW_SESSION_TICKETS_ENABLED or MBEDTLS_SSL_TLS1_3_SIGNAL_NEW_SESSION_TICKETS_DISABLED) |
void mbedtls_ssl_conf_tls13_key_exchange_modes | ( | mbedtls_ssl_config * | conf, |
const int | kex_modes | ||
) |
Set the supported key exchange modes for TLS 1.3 connections.
In contrast to TLS 1.2, the ciphersuite concept in TLS 1.3 does not include the choice of key exchange mechanism. It is therefore not covered by the API mbedtls_ssl_conf_ciphersuites(). See the documentation of mbedtls_ssl_conf_ciphersuites() for more information on the ciphersuite concept in TLS 1.2 and TLS 1.3. The present function is specific to TLS 1.3 and allows users to configure the set of supported key exchange mechanisms in TLS 1.3.
conf | The SSL configuration the change should apply to. |
kex_modes | A bitwise combination of one or more of the following:
|
void mbedtls_ssl_conf_transport | ( | mbedtls_ssl_config * | conf, |
int | transport | ||
) |
Set the transport type (TLS or DTLS). Default: TLS.
mbedtls_ssl_set_bio()
. You also need to provide timer callbacks with mbedtls_ssl_set_timer_cb()
.conf | SSL configuration |
transport | transport type: MBEDTLS_SSL_TRANSPORT_STREAM for TLS, MBEDTLS_SSL_TRANSPORT_DATAGRAM for DTLS. |
void mbedtls_ssl_conf_verify | ( | mbedtls_ssl_config * | conf, |
int(*)(void *, mbedtls_x509_crt *, int, uint32_t *) | f_vrfy, | ||
void * | p_vrfy | ||
) |
Set the verification callback (Optional).
If set, the provided verify callback is called for each certificate in the peer's CRT chain, including the trusted root. For more information, please see the documentation of \c mbedtls_x509_crt_verify().
conf | The SSL configuration to use. |
f_vrfy | The verification callback to use during CRT verification. |
p_vrfy | The opaque context to be passed to the callback. |
int mbedtls_ssl_config_defaults | ( | mbedtls_ssl_config * | conf, |
int | endpoint, | ||
int | transport, | ||
int | preset | ||
) |
Load reasonable default SSL configuration values. (You need to call mbedtls_ssl_config_init() first.)
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 |
mbedtls_ssl_conf_transport()
for notes on DTLS.void mbedtls_ssl_config_free | ( | mbedtls_ssl_config * | conf | ) |
Free an SSL configuration context.
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().
conf | SSL configuration context |
|
inlinestatic |
Return the SSL configuration structure associated with the given SSL context.
ssl | The SSL context to query. |
ssl
. int mbedtls_ssl_context_load | ( | mbedtls_ssl_context * | ssl, |
const unsigned char * | buf, | ||
size_t | len | ||
) |
Load serialized connection data to an SSL context.
ssl
. In this case, you need to prepare the context with the usual sequence starting with a call to mbedtls_ssl_init() if you want to use it again.ssl | The SSL context structure to be populated. It must have been prepared as described in the note above. |
buf | The buffer holding the serialized connection data. It must be a readable buffer of at least len bytes. |
len | The size of the serialized data in bytes. |
0
if successful. int mbedtls_ssl_context_save | ( | mbedtls_ssl_context * | ssl, |
unsigned char * | buf, | ||
size_t | buf_len, | ||
size_t * | olen | ||
) |
Save an active connection as serialized data in a buffer. This allows the freeing or re-using of the SSL context while still picking up the connection later in a way that it entirely transparent to the peer.
ssl
which as a result is no longer associated with the connection that has been serialized. This avoids creating copies of the connection state. You're then free to either re-use the context structure for a different connection, or call mbedtls_ssl_free() on it. See the documentation of mbedtls_ssl_session_reset() for more details.ssl | The SSL context to save. On success, it is no longer associated with the connection that has been serialized. |
buf | The buffer to write the serialized data to. It must be a writeable buffer of at least buf_len bytes, or may be NULL if buf_len is 0 . |
buf_len | The number of bytes available for writing in buf . |
olen | The size in bytes of the data that has been or would have been written. It must point to a valid size_t . |
olen
is updated to the correct value regardless of whether buf_len
was large enough. This makes it possible to determine the necessary size by calling this function with buf
set to NULL
and buf_len
to 0
. However, the value of olen
is only guaranteed to be correct when the function returns MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL or 0
. If the return value is different, then the value of olen
is undefined.0
if successful. buf
is too small. void mbedtls_ssl_free | ( | mbedtls_ssl_context * | ssl | ) |
Free referenced items in an SSL context and clear memory.
ssl | SSL context |
const char * mbedtls_ssl_get_alpn_protocol | ( | const mbedtls_ssl_context * | ssl | ) |
Get the name of the negotiated Application Layer Protocol. This function should be called after the handshake is completed.
ssl | SSL context |
size_t mbedtls_ssl_get_bytes_avail | ( | const mbedtls_ssl_context * | ssl | ) |
Return the number of application data bytes remaining to be read from the current record.
ssl | SSL context |
mbedtls_ssl_read
has written the maximal amount of data fitting into the input buffer. const char * mbedtls_ssl_get_ciphersuite | ( | const mbedtls_ssl_context * | ssl | ) |
Return the name of the current ciphersuite.
ssl | SSL context |
int mbedtls_ssl_get_ciphersuite_id | ( | const char * | ciphersuite_name | ) |
Return the ID of the ciphersuite associated with the given name.
ciphersuite_name | SSL ciphersuite name |
int mbedtls_ssl_get_ciphersuite_id_from_ssl | ( | const mbedtls_ssl_context * | ssl | ) |
Return the id of the current ciphersuite.
ssl | SSL context |
const char * mbedtls_ssl_get_ciphersuite_name | ( | const int | ciphersuite_id | ) |
Return the name of the ciphersuite associated with the given ID.
ciphersuite_id | SSL ciphersuite ID |
|
inlinestatic |
const unsigned char * mbedtls_ssl_get_hs_sni | ( | mbedtls_ssl_context * | ssl, |
size_t * | name_len | ||
) |
Retrieve SNI extension value for the current handshake. Available in f_cert_cb
of mbedtls_ssl_conf_cert_cb()
, this is the same value passed to f_sni
callback of mbedtls_ssl_conf_sni()
and may be used instead of mbedtls_ssl_conf_sni()
.
ssl | SSL context |
name_len | pointer into which to store length of returned value. 0 if SNI extension is not present or not yet processed. |
f_cert_cb
registered with mbedtls_ssl_conf_cert_cb()
.name_len
for len.int mbedtls_ssl_get_max_in_record_payload | ( | const mbedtls_ssl_context * | ssl | ) |
Return the current maximum incoming record payload in bytes.
MBEDTLS_SSL_IN_CONTENT_LEN
, extensions such as the max fragment length extension or record size limit extension if used, and the current record expansion.ssl | SSL context |
int mbedtls_ssl_get_max_out_record_payload | ( | const mbedtls_ssl_context * | ssl | ) |
Return the current maximum outgoing record payload in bytes.
MBEDTLS_SSL_OUT_CONTENT_LEN
, extensions such as the max fragment length or record size limit extension if used, and for DTLS the path MTU as configured and current record expansion.mbedtls_ssl_write()
will return an error if called with a larger length value. With TLS, mbedtls_ssl_write()
will fragment the input if necessary and return the number of bytes written; it is up to the caller to call mbedtls_ssl_write()
again in order to send the remaining bytes if any.ssl | SSL context |
int mbedtls_ssl_get_own_cid | ( | mbedtls_ssl_context * | ssl, |
int * | enabled, | ||
unsigned char | own_cid[MBEDTLS_SSL_CID_IN_LEN_MAX], | ||
size_t * | own_cid_len | ||
) |
Get information about our request for usage of the CID extension in the current connection.
ssl | The SSL context to query. |
enabled | The address at which to store whether the CID extension is requested to be used or not. If the CID is requested, *enabled is set to MBEDTLS_SSL_CID_ENABLED; otherwise, it is set to MBEDTLS_SSL_CID_DISABLED. |
own_cid | The address of the buffer in which to store our own CID (if the CID extension is requested). This may be NULL in case the value of our CID isn't needed. If it is not NULL , own_cid_len must not be NULL . |
own_cid_len | The address at which to store the size of our own CID (if the CID extension is requested). This is also the number of Bytes in own_cid that have been written. This may be NULL in case the length of our own CID isn't needed. If it is NULL , own_cid must be NULL , too. |
*enabled
to MBEDTLS_SSL_CID_DISABLED (the rationale for this is that the resulting outcome is the same as if the CID extensions wasn't requested).0
on success. const mbedtls_x509_crt * mbedtls_ssl_get_peer_cert | ( | const mbedtls_ssl_context * | ssl | ) |
Return the peer certificate from the current connection.
ssl | The SSL context to use. This must be initialized and setup. |
NULL
if no peer certificate is available. This might be because the chosen ciphersuite doesn't use CRTs (PSK-based ciphersuites, for example), or because MBEDTLS_SSL_KEEP_PEER_CERTIFICATE has been disabled, allowing the stack to free the peer's CRT to save memory.int mbedtls_ssl_get_peer_cid | ( | mbedtls_ssl_context * | ssl, |
int * | enabled, | ||
unsigned char | peer_cid[MBEDTLS_SSL_CID_OUT_LEN_MAX], | ||
size_t * | peer_cid_len | ||
) |
Get information about the use of the CID extension in the current connection.
ssl | The SSL context to query. |
enabled | The address at which to store whether the CID extension is currently in use or not. If the CID is in use, *enabled is set to MBEDTLS_SSL_CID_ENABLED; otherwise, it is set to MBEDTLS_SSL_CID_DISABLED. |
peer_cid | The address of the buffer in which to store the CID chosen by the peer (if the CID extension is used). This may be NULL in case the value of peer CID isn't needed. If it is not NULL , peer_cid_len must not be NULL . |
peer_cid_len | The address at which to store the size of the CID chosen by the peer (if the CID extension is used). This is also the number of Bytes in peer_cid that have been written. This may be NULL in case the length of the peer CID isn't needed. If it is NULL , peer_cid must be NULL , too. |
*enabled
to MBEDTLS_SSL_CID_DISABLED (the rationale for this is that the resulting communication is the same as if the CID extensions hadn't been used).0
on success. 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)
ssl | SSL context |
int mbedtls_ssl_get_session | ( | const mbedtls_ssl_context * | ssl, |
mbedtls_ssl_session * | session | ||
) |
Export a session in order to resume it later.
ssl | The SSL context representing the connection for which to to export a session structure for later resumption. |
session | The target structure in which to store the exported session. This must have been initialized with mbedtls_ssl_session_init() but otherwise be unused. |
0
if successful. In this case, session
can be used for session resumption by passing it to mbedtls_ssl_set_session(), and serialized for storage via mbedtls_ssl_session_save().
|
inlinestatic |
Retrieve the user data in an SSL context as an integer.
This is the value last set with mbedtls_ssl_set_user_data_n(), or 0
if mbedtls_ssl_set_user_data_n() has not previously been called. The value is undefined if mbedtls_ssl_set_user_data_p() has been called without a subsequent call to mbedtls_ssl_set_user_data_n().
ssl | The SSL context to modify. |
|
inlinestatic |
Retrieve the user data in an SSL context as a pointer.
This is the value last set with mbedtls_ssl_set_user_data_p(), or NULL
if mbedtls_ssl_set_user_data_p() has not previously been called. The value is undefined if mbedtls_ssl_set_user_data_n() has been called without a subsequent call to mbedtls_ssl_set_user_data_p().
ssl | The SSL context to modify. |
uint32_t mbedtls_ssl_get_verify_result | ( | const mbedtls_ssl_context * | ssl | ) |
Return the result of the certificate verification.
ssl | The SSL context to use. |
0
if the certificate verification was successful. -1u
if the result is not available. This may happen e.g. if the handshake aborts early, or a verification callback returned a fatal error. MBEDTLS_X509_BADCERT_XXX
and MBEDTLS_X509_BADCRL_XXX
failure flags; see x509.h. const char * mbedtls_ssl_get_version | ( | const mbedtls_ssl_context * | ssl | ) |
Return the current TLS version.
ssl | SSL context |
|
inlinestatic |
Return the (D)TLS protocol version negotiated in the given connection.
ssl | The SSL context to query. |
int mbedtls_ssl_handshake | ( | mbedtls_ssl_context * | ssl | ) |
Perform the SSL handshake.
ssl | SSL context |
0
if successful. 0
, MBEDTLS_ERR_SSL_WANT_READ, MBEDTLS_ERR_SSL_WANT_WRITE, MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS or MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS or MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET or MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA, you must stop using the SSL context for reading or writing, and either free it or call mbedtls_ssl_session_reset()
on it before re-using it for a new connection; the current connection must be closed.int mbedtls_ssl_handshake_step | ( | mbedtls_ssl_context * | ssl | ) |
Perform a single step of the SSL handshake.
0
. Do not call this function if mbedtls_ssl_is_handshake_over() returns 1
.ssl | SSL context |
0
, MBEDTLS_ERR_SSL_WANT_READ, MBEDTLS_ERR_SSL_WANT_WRITE, MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS, MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS or MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET or MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA, you must stop using the SSL context for reading or writing, and either free it or call mbedtls_ssl_session_reset()
on it before re-using it for a new connection; the current connection must be closed. 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()
ssl | SSL context |
|
inlinestatic |
After calling mbedtls_ssl_handshake() to start the SSL handshake you can call this function to check whether the handshake is over for a given SSL context. This function should be also used to determine when to stop calling mbedtls_handshake_step() for that context.
ssl | SSL context |
1
if handshake is over, 0
if it is still ongoing. Definition at line 5102 of file ssl.h.
References MBEDTLS_SSL_HANDSHAKE_OVER.
int mbedtls_ssl_read | ( | mbedtls_ssl_context * | ssl, |
unsigned char * | buf, | ||
size_t | len | ||
) |
Read at most 'len' application data bytes.
ssl | SSL context |
buf | buffer that will hold the data |
len | maximum number of bytes to read |
0
if the read end of the underlying transport was closed without sending a CloseNotify beforehand, which might happen because of various reasons (internal error of an underlying stack, non-conformant peer not sending a CloseNotify and such) - in this case you must stop using the context (see below). mbedtls_ssl_session_reset()
on it before re-using it for a new connection; the current connection must be closed.mbedtls_ssl_handshake()
with the same context (as it has been reset internally). Either way, you must 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!mbedtls_ssl_check_pending
to check for remaining records. int mbedtls_ssl_renegotiate | ( | mbedtls_ssl_context * | ssl | ) |
Initiate an SSL renegotiation on the running connection. Client: perform the renegotiation right now. Server: request renegotiation, which will be performed during the next call to mbedtls_ssl_read() if honored by client.
ssl | SSL context |
0
, MBEDTLS_ERR_SSL_WANT_READ, MBEDTLS_ERR_SSL_WANT_WRITE, MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS or MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS, you must stop using the SSL context for reading or writing, and either free it or call mbedtls_ssl_session_reset()
on it before re-using it for a new connection; the current connection must be closed. int mbedtls_ssl_send_alert_message | ( | mbedtls_ssl_context * | ssl, |
unsigned char | level, | ||
unsigned char | message | ||
) |
Send an alert message.
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_*) |
mbedtls_ssl_session_reset()
on it before re-using it for a new connection; the current connection must be closed. void mbedtls_ssl_session_free | ( | mbedtls_ssl_session * | session | ) |
Free referenced items in an SSL session including the peer certificate and clear memory.
session | SSL session |
|
inlinestatic |
|
inlinestatic |
|
inlinestatic |
|
inlinestatic |
Get the creation time of a session ticket.
ticket_creation_time
for information about the intended usage of this function.session | SSL session |
ticket_creation_time | On exit, holds the ticket creation time in milliseconds. |
Definition at line 2763 of file ssl.h.
References MBEDTLS_ERR_SSL_BAD_INPUT_DATA, and MBEDTLS_SSL_IS_SERVER.
void mbedtls_ssl_session_init | ( | mbedtls_ssl_session * | session | ) |
Initialize SSL session structure.
session | SSL session |
int mbedtls_ssl_session_load | ( | mbedtls_ssl_session * | session, |
const unsigned char * | buf, | ||
size_t | len | ||
) |
Load serialized session data into a session structure. On client, this can be used for loading saved sessions before resuming them with mbedtls_ssl_set_session(). On server, this can be used for alternative implementations of session cache or session tickets.
session | The session structure to be populated. It must have been initialised with mbedtls_ssl_session_init() but not populated yet. |
buf | The buffer holding the serialized session data. It must be a readable buffer of at least len bytes. |
len | The size of the serialized data in bytes. |
0
if successful. 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.
ssl | SSL context |
int mbedtls_ssl_session_save | ( | const mbedtls_ssl_session * | session, |
unsigned char * | buf, | ||
size_t | buf_len, | ||
size_t * | olen | ||
) |
Save session structure as serialized data in a buffer. On client, this can be used for saving session data, potentially in non-volatile storage, for resuming later. On server, this can be used for alternative implementations of session cache or session tickets.
session | The session structure to be saved. |
buf | The buffer to write the serialized data to. It must be a writeable buffer of at least buf_len bytes, or may be NULL if buf_len is 0 . |
buf_len | The number of bytes available for writing in buf . |
olen | The size in bytes of the data that has been or would have been written. It must point to a valid size_t . |
olen
is updated to the correct value regardless of whether buf_len
was large enough. This makes it possible to determine the necessary size by calling this function with buf
set to NULL
and buf_len
to 0
.0
if successful. buf
is too small. void mbedtls_ssl_set_bio | ( | mbedtls_ssl_context * | ssl, |
void * | p_bio, | ||
mbedtls_ssl_send_t * | f_send, | ||
mbedtls_ssl_recv_t * | f_recv, | ||
mbedtls_ssl_recv_timeout_t * | f_recv_timeout | ||
) |
Set the underlying BIO callbacks for write, read and read-with-timeout.
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. |
mbedtls_ssl_send_t
, mbedtls_ssl_recv_t
and mbedtls_ssl_recv_timeout_t
for the conventions those callbacks must follow.mbedtls_net_send()
, mbedtls_net_recv()
and mbedtls_net_recv_timeout()
that are suitable to be used here. int mbedtls_ssl_set_cid | ( | mbedtls_ssl_context * | ssl, |
int | enable, | ||
unsigned char const * | own_cid, | ||
size_t | own_cid_len | ||
) |
Configure the use of the Connection ID (CID) extension in the next handshake.
Reference: RFC 9146 (or draft-ietf-tls-dtls-connection-id-05 https://tools.ietf.org/html/draft-ietf-tls-dtls-connection-id-05 for legacy version)
The DTLS CID extension allows the reliable association of DTLS records to DTLS connections across changes in the underlying transport (changed IP and Port metadata) by adding explicit connection identifiers (CIDs) to the headers of encrypted DTLS records. The desired CIDs are configured by the application layer and are exchanged in new ClientHello
/ ServerHello
extensions during the handshake, where each side indicates the CID it wants the peer to use when writing encrypted messages. The CIDs are put to use once records get encrypted: the stack discards any incoming records that don't include the configured CID in their header, and adds the peer's requested CID to the headers of outgoing messages.
This API enables or disables the use of the CID extension in the next handshake and sets the value of the CID to be used for incoming messages.
ssl | The SSL context to configure. This must be initialized. |
enable | This value determines whether the CID extension should be used or not. Possible values are:
|
own_cid | The address of the readable buffer holding the CID we want the peer to use when sending encrypted messages to us. This may be NULL if own_cid_len is 0 . This parameter is unused if enable is set to MBEDTLS_SSL_CID_DISABLED. |
own_cid_len | The length of own_cid . This parameter is unused if enable is set to MBEDTLS_SSL_CID_DISABLED. |
own_cid_len
must match the value of the len
parameter passed to mbedtls_ssl_conf_cid() when configuring the mbedtls_ssl_config that ssl
is bound to.ssl
, but does not trigger one. You still have to call mbedtls_ssl_handshake()
(for the initial handshake) or mbedtls_ssl_renegotiate()
(for a renegotiation handshake) explicitly after a successful call to this function to run the handshake.ClientHello
in the next handshake will include the CID extension, thereby offering the use of the CID to the server. Only if the ServerHello
contains the CID extension, too, the CID extension will actually be put to use.ClientHello
from the client, and, if present, reply with a CID extension in its ServerHello
.own_cid
. It is the responsibility of the user to adapt the underlying transport to take care of CID-based demultiplexing before handing datagrams to Mbed TLS.0
on success. In this case, the CID configuration applies to the next handshake. int mbedtls_ssl_set_client_transport_id | ( | mbedtls_ssl_context * | ssl, |
const unsigned char * | info, | ||
size_t | ilen | ||
) |
Set client's transport-level identification info. (Server only. DTLS only.)
This is usually the IP address (and port), but could be anything identify the client depending on the underlying network stack. Used for HelloVerifyRequest with DTLS. This is not used to route the actual packets.
ssl | SSL context |
info | Transport-level info identifying the client (eg IP + port) |
ilen | Length of info in bytes |
void mbedtls_ssl_set_datagram_packing | ( | mbedtls_ssl_context * | ssl, |
unsigned | allow_packing | ||
) |
Allow or disallow packing of multiple handshake records within a single datagram.
ssl | The SSL context to configure. |
allow_packing | This determines whether datagram packing may be used or not. A value of 0 means that every record will be sent in a separate datagram; a value of 1 means that, if space permits, multiple handshake messages (including CCS) belonging to a single flight may be packed within a single datagram. |
void mbedtls_ssl_set_export_keys_cb | ( | mbedtls_ssl_context * | ssl, |
mbedtls_ssl_export_keys_t * | f_export_keys, | ||
void * | p_export_keys | ||
) |
Configure a key export callback. (Default: none.)
This API can be used for two purposes:
ssl | The SSL context to which the export callback should be attached. |
f_export_keys | The callback for the key export. |
p_export_keys | The opaque context pointer to be passed to the callback f_export_keys . |
int mbedtls_ssl_set_hostname | ( | mbedtls_ssl_context * | ssl, |
const char * | hostname | ||
) |
Set or reset the hostname to check against the received peer certificate. On a client, this also sets the ServerName TLS extension, if that extension is enabled. On a TLS 1.3 client, this also sets the server name in the session resumption ticket, if that feature is enabled.
ssl | SSL context |
hostname | The server hostname. This may be NULL to clear the hostname. |
NULL
on a client, then the server is not authenticated: it only needs to have a valid certificate, not a certificate matching its name. Therefore you should always call this function on a client, unless the connection is set up to only allow pre-shared keys, or in scenarios where server impersonation is not a concern. See the documentation of MBEDTLS_ERR_SSL_CERTIFICATE_VERIFICATION_WITHOUT_HOSTNAME for more details.Hostname set to the one provided on success (cleared when NULL). On allocation failure hostname is cleared. On too long input failure, old hostname is unchanged.
void mbedtls_ssl_set_hs_authmode | ( | mbedtls_ssl_context * | ssl, |
int | authmode | ||
) |
Set authmode for the current handshake.
mbedtls_ssl_conf_authmode()
but for use within the SNI callback or the certificate selection callback.ssl | SSL context |
authmode | MBEDTLS_SSL_VERIFY_NONE, MBEDTLS_SSL_VERIFY_OPTIONAL or MBEDTLS_SSL_VERIFY_REQUIRED |
void mbedtls_ssl_set_hs_ca_chain | ( | mbedtls_ssl_context * | ssl, |
mbedtls_x509_crt * | ca_chain, | ||
mbedtls_x509_crl * | ca_crl | ||
) |
Set the data required to verify peer certificate for the current handshake.
mbedtls_ssl_conf_ca_chain()
but for use within the SNI callback or the certificate selection callback.ssl | SSL context |
ca_chain | trusted CA chain (meaning all fully trusted top-level CAs) |
ca_crl | trusted CA CRLs |
void mbedtls_ssl_set_hs_dn_hints | ( | mbedtls_ssl_context * | ssl, |
const mbedtls_x509_crt * | crt | ||
) |
Set DN hints sent to client in CertificateRequest message.
mbedtls_ssl_conf_dn_hints()
but for use within the SNI callback or the certificate selection callback.ssl | SSL context |
crt | crt chain whose subject DNs are issuer DNs of client certs from which the client should select client peer certificate. |
int mbedtls_ssl_set_hs_own_cert | ( | mbedtls_ssl_context * | ssl, |
mbedtls_x509_crt * | own_cert, | ||
mbedtls_pk_context * | pk_key | ||
) |
Set own certificate and key for the current handshake.
mbedtls_ssl_conf_own_cert()
but for use within the SNI callback or the certificate selection callback.own_cert
clears the certificate list for the current handshake.ssl | SSL context |
own_cert | own public certificate chain |
pk_key | own private key |
int mbedtls_ssl_set_hs_psk | ( | mbedtls_ssl_context * | ssl, |
const unsigned char * | psk, | ||
size_t | psk_len | ||
) |
Set the pre-shared Key (PSK) for the current handshake.
mbedtls_ssl_conf_psk_cb()
.mbedtls_ssl_conf_psk()
.ssl | The SSL context to configure a PSK for. |
psk | The pointer to the pre-shared key. |
psk_len | The length of the pre-shared key in bytes. |
0
if successful. MBEDTLS_ERR_SSL_XXX
error code on failure. void mbedtls_ssl_set_mtu | ( | mbedtls_ssl_context * | ssl, |
uint16_t | mtu | ||
) |
Set the Maximum Transport Unit (MTU). Special value: 0 means unset (no limit). This represents the maximum size of a datagram payload handled by the transport layer (usually UDP) as determined by the network link and stack. In practice, this controls the maximum size datagram the DTLS layer will pass to the f_send()
callback set using mbedtls_ssl_set_bio()
.
mbedtls_ssl_conf_max_frag_len()
.ssl | SSL context |
mtu | Value of the path MTU in bytes |
int mbedtls_ssl_set_session | ( | mbedtls_ssl_context * | ssl, |
const mbedtls_ssl_session * | session | ||
) |
Load a session for session resumption.
Sessions loaded through this call will be considered for session resumption in the next handshake.
ssl
.ssl | The SSL context representing the connection which should be attempted to be setup using session resumption. This must be initialized via mbedtls_ssl_init() and bound to an SSL configuration via mbedtls_ssl_setup(), but the handshake must not yet have been started. |
session | The session to be considered for session resumption. This must be a session previously exported via mbedtls_ssl_get_session(), and potentially serialized and deserialized through mbedtls_ssl_session_save() and mbedtls_ssl_session_load() in the meantime. |
0
if successful. MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE
if the session could not be loaded because one session has already been loaded. This error is non-fatal, and has no observable effect on the SSL context or the session that was attempted to be loaded. void mbedtls_ssl_set_timer_cb | ( | mbedtls_ssl_context * | ssl, |
void * | p_timer, | ||
mbedtls_ssl_set_timer_t * | f_set_timer, | ||
mbedtls_ssl_get_timer_t * | f_get_timer | ||
) |
Set the timer callbacks (Mandatory for DTLS.)
ssl | SSL context |
p_timer | parameter (context) shared by timer callbacks |
f_set_timer | set timer callback |
f_get_timer | get timer callback. Must return: |
mbedtls_ssl_set_timer_t
and mbedtls_ssl_get_timer_t
for the conventions this pair of callbacks must follow.mbedtls_timing_set_delay()
and mbedtls_timing_get_delay()
that are suitable for using here, except if using an event-driven style.
|
inlinestatic |
Set the user data in an SSL context to an integer.
You can retrieve this value later with mbedtls_ssl_get_user_data_n().
ssl | The SSL context to modify. |
n | The new value of the user data. |
|
inlinestatic |
Set the user data in an SSL context to a pointer.
You can retrieve this value later with mbedtls_ssl_get_user_data_p().
p
without accessing it. It is the responsibility of the caller to ensure that the pointer remains valid.ssl | The SSL context to modify. |
p | The new value of the user data. |
void mbedtls_ssl_set_verify | ( | mbedtls_ssl_context * | ssl, |
int(*)(void *, mbedtls_x509_crt *, int, uint32_t *) | f_vrfy, | ||
void * | p_vrfy | ||
) |
Set a connection-specific verification callback (optional).
If set, the provided verify callback is called for each certificate in the peer's CRT chain, including the trusted root. For more information, please see the documentation of \c mbedtls_x509_crt_verify().
ssl | The SSL context to use. |
f_vrfy | The verification callback to use during CRT verification. |
p_vrfy | The opaque context to be passed to the callback. |
int mbedtls_ssl_setup | ( | mbedtls_ssl_context * | ssl, |
const mbedtls_ssl_config * | conf | ||
) |
Set up an SSL context for use.
ssl | SSL context |
conf | SSL configuration to use |
int mbedtls_ssl_tls_prf | ( | const mbedtls_tls_prf_types | prf, |
const unsigned char * | secret, | ||
size_t | slen, | ||
const char * | label, | ||
const unsigned char * | random, | ||
size_t | rlen, | ||
unsigned char * | dstbuf, | ||
size_t | dlen | ||
) |
TLS-PRF function for key derivation.
prf | The tls_prf type function type to be used. |
secret | Secret for the key derivation function. |
slen | Length of the secret. |
label | String label for the key derivation function, terminated with null character. |
random | Random bytes. |
rlen | Length of the random bytes buffer. |
dstbuf | The buffer holding the derived key. |
dlen | Length of the output buffer. |
int mbedtls_ssl_write | ( | mbedtls_ssl_context * | ssl, |
const unsigned char * | buf, | ||
size_t | len | ||
) |
Try to write exactly 'len' application data bytes.
ssl | SSL context |
buf | buffer holding the data |
len | how many bytes must be written |
len
). mbedtls_ssl_session_reset()
on it before re-using it for a new connection; the current connection must be closed.mbedtls_ssl_get_max_out_record_payload()
may be used to query the active maximum fragment length.