Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
Dependents: TYBLE16_simple_data_logger TYBLE16_MP3_Air
ssl.h File Reference
SSL/TLS functions. More...
Go to the source code of this file.
Data Structures | |
struct | mbedtls_ssl_config |
SSL/TLS configuration to be shared between mbedtls_ssl_context structures. More... | |
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 int | mbedtls_ssl_async_sign_t (mbedtls_ssl_context *ssl, mbedtls_x509_crt *cert, mbedtls_md_type_t md_alg, const unsigned char *hash, size_t hash_len) |
Callback type: start external signature operation. | |
typedef int | mbedtls_ssl_async_decrypt_t (mbedtls_ssl_context *ssl, mbedtls_x509_crt *cert, const unsigned char *input, size_t input_len) |
Callback type: start external decryption operation. | |
typedef int | mbedtls_ssl_async_resume_t (mbedtls_ssl_context *ssl, unsigned char *output, size_t *output_len, size_t output_size) |
Callback type: resume external operation. | |
typedef void | mbedtls_ssl_async_cancel_t (mbedtls_ssl_context *ssl) |
Callback type: cancel external operation. | |
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_export_keys_t (void *p_expkey, const unsigned char *ms, const unsigned char *kb, size_t maclen, size_t keylen, size_t ivlen) |
Callback type: Export key block and master secret. | |
typedef int | mbedtls_ssl_export_keys_ext_t (void *p_expkey, const unsigned char *ms, const unsigned char *kb, size_t maclen, size_t keylen, size_t ivlen, const unsigned char client_random[32], const unsigned char server_random[32], mbedtls_tls_prf_types tls_prf_type) |
Callback type: Export key block, master secret, handshake randbytes and the tls_prf function used to derive keys. | |
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. | |
void | mbedtls_ssl_conf_transport (mbedtls_ssl_config *conf, int transport) |
Set the transport type (TLS or DTLS). | |
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. | |
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_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 Tranport Unit (MTU). | |
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. | |
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.) | |
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). | |
void | mbedtls_ssl_conf_export_keys_cb (mbedtls_ssl_config *conf, mbedtls_ssl_export_keys_t *f_export_keys, void *p_export_keys) |
Configure key export callback. | |
void | mbedtls_ssl_conf_export_keys_ext_cb (mbedtls_ssl_config *conf, mbedtls_ssl_export_keys_ext_t *f_export_keys_ext, void *p_export_keys) |
Configure extended key export callback. | |
void | mbedtls_ssl_conf_async_private_cb (mbedtls_ssl_config *conf, mbedtls_ssl_async_sign_t *f_async_sign, mbedtls_ssl_async_decrypt_t *f_async_decrypt, mbedtls_ssl_async_resume_t *f_async_resume, mbedtls_ssl_async_cancel_t *f_async_cancel, void *config_data) |
Configure asynchronous private key operation callbacks. | |
void * | mbedtls_ssl_conf_get_async_config_data (const mbedtls_ssl_config *conf) |
Retrieve the configuration data set by mbedtls_ssl_conf_async_private_cb(). | |
void * | mbedtls_ssl_get_async_operation_data (const mbedtls_ssl_context *ssl) |
Retrieve the asynchronous operation user context. | |
void | mbedtls_ssl_set_async_operation_data (mbedtls_ssl_context *ssl, void *ctx) |
Retrieve the asynchronous operation user context. | |
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. | |
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. | |
void | mbedtls_ssl_conf_dtls_anti_replay (mbedtls_ssl_config *conf, char mode) |
Enable or disable anti-replay protection for DTLS. | |
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. | |
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. | |
void | mbedtls_ssl_conf_session_cache (mbedtls_ssl_config *conf, void *p_cache, int(*f_get_cache)(void *, mbedtls_ssl_session *), int(*f_set_cache)(void *, const mbedtls_ssl_session *)) |
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) |
Request resumption of session (client-side only) Session data is copied from presented session structure. | |
int | mbedtls_ssl_session_load (mbedtls_ssl_session *session, const unsigned char *buf, size_t len) |
Load serialized session data into a session structure. | |
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. | |
const mbedtls_ssl_session * | mbedtls_ssl_get_session_pointer (const mbedtls_ssl_context *ssl) |
Get a pointer to the current session structure, for example to serialize it. | |
void | mbedtls_ssl_conf_ciphersuites (mbedtls_ssl_config *conf, const int *ciphersuites) |
Set the list of allowed ciphersuites and the preference order. | |
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_ciphersuites_for_version (mbedtls_ssl_config *conf, const int *ciphersuites, int major, int minor) |
Set the list of allowed ciphersuites and the preference order for a specific version of the protocol. | |
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. | |
void | mbedtls_ssl_conf_ca_cb (mbedtls_ssl_config *conf, mbedtls_x509_crt_ca_cb_t f_ca_cb, void *p_ca_cb) |
Set the trusted certificate callback. | |
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 a pre-shared key (PSK) and identity to be used in PSK-based ciphersuites. | |
int | mbedtls_ssl_conf_psk_opaque (mbedtls_ssl_config *conf, psa_key_handle_t psk, const unsigned char *psk_identity, size_t psk_identity_len) |
Configure an opaque pre-shared key (PSK) and identity 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. | |
int | mbedtls_ssl_set_hs_psk_opaque (mbedtls_ssl_context *ssl, psa_key_handle_t psk) |
Set an opaque 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). | |
MBEDTLS_DEPRECATED int | mbedtls_ssl_conf_dh_param (mbedtls_ssl_config *conf, const char *dhm_P, const char *dhm_G) |
Set the Diffie-Hellman public P and G values, read as hexadecimal strings (server-side only) (Default values: MBEDTLS_DHM_RFC3526_MODP_2048_[PG]) | |
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. | |
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. | |
void | 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_sig_hashes (mbedtls_ssl_config *conf, const int *hashes) |
Set the allowed hashes for signatures during the handshake. | |
int | mbedtls_ssl_set_hostname (mbedtls_ssl_context *ssl, const char *hostname) |
Set or reset the hostname to check against the received server 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. | |
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_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_set_hs_ecjpake_password (mbedtls_ssl_context *ssl, const unsigned char *pw, size_t pw_len) |
Set the EC J-PAKE password for current handshake. | |
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. | |
void | mbedtls_ssl_conf_max_version (mbedtls_ssl_config *conf, int major, int minor) |
Set the maximum supported version sent from the client side and/or accepted at the server side (Default: MBEDTLS_SSL_MAX_MAJOR_VERSION, MBEDTLS_SSL_MAX_MINOR_VERSION) | |
void | mbedtls_ssl_conf_min_version (mbedtls_ssl_config *conf, int major, int minor) |
Set the minimum accepted SSL/TLS protocol version (Default: TLS 1.0) | |
void | mbedtls_ssl_conf_fallback (mbedtls_ssl_config *conf, char fallback) |
Set the fallback flag (client-side only). | |
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. | |
void | mbedtls_ssl_conf_arc4_support (mbedtls_ssl_config *conf, char arc4) |
Disable or enable support for RC4 (Default: MBEDTLS_SSL_ARC4_DISABLED) | |
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. | |
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. | |
void | mbedtls_ssl_conf_truncated_hmac (mbedtls_ssl_config *conf, int truncate) |
Activate negotiation of truncated HMAC (Default: MBEDTLS_SSL_TRUNC_HMAC_DISABLED) | |
void | mbedtls_ssl_conf_cbc_record_splitting (mbedtls_ssl_config *conf, char split) |
Enable / Disable 1/n-1 record splitting (Default: MBEDTLS_SSL_CBC_RECORD_SPLITTING_ENABLED) | |
void | mbedtls_ssl_conf_session_tickets (mbedtls_ssl_config *conf, int use_tickets) |
Enable / Disable session tickets (client only). | |
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. | |
void | mbedtls_ssl_conf_renegotiation_enforced (mbedtls_ssl_config *conf, int max_records) |
Enforce renegotiation requests. | |
void | mbedtls_ssl_conf_renegotiation_period (mbedtls_ssl_config *conf, const unsigned char period[8]) |
Set record counter threshold for periodic renegotiation. | |
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. | |
const char * | mbedtls_ssl_get_ciphersuite (const mbedtls_ssl_context *ssl) |
Return the name of the current ciphersuite. | |
const char * | mbedtls_ssl_get_version (const mbedtls_ssl_context *ssl) |
Return the current SSL version (SSLv3/TLSv1/etc) | |
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. | |
size_t | mbedtls_ssl_get_max_frag_len (const mbedtls_ssl_context *ssl) |
Return the maximum fragment length (payload, in bytes). | |
int | mbedtls_ssl_get_max_out_record_payload (const mbedtls_ssl_context *ssl) |
Return the current maximum outgoing 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) |
Save session in order to resume it later (client-side only) Session data is copied to presented session structure. | |
int | mbedtls_ssl_handshake (mbedtls_ssl_context *ssl) |
Perform the SSL handshake. | |
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. | |
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. | |
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 reasonnable default SSL configuration values. | |
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. |
Detailed Description
SSL/TLS functions.
Definition in file ssl.h.
Typedef Documentation
typedef void mbedtls_ssl_async_cancel_t(mbedtls_ssl_context *ssl) |
Callback type: cancel external operation.
This callback is called if an SSL connection is closed while an asynchronous operation is in progress. Note that this callback is not called if the mbedtls_ssl_async_resume_t callback has run and has returned a value other than MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS, since in that case the asynchronous operation has already completed.
This function may call mbedtls_ssl_get_async_operation_data() to retrieve an operation context set by the start callback.
- Parameters:
-
ssl The SSL connection instance. It should not be modified.
typedef int mbedtls_ssl_async_decrypt_t(mbedtls_ssl_context *ssl, mbedtls_x509_crt *cert, const unsigned char *input, size_t input_len) |
Callback type: start external decryption operation.
This callback is called during an SSL handshake to start an RSA decryption operation using an external processor. The parameter cert
contains the public key; it is up to the callback function to determine how to access the associated private key.
This function typically sends or enqueues a request, and does not wait for the operation to complete. This allows the handshake step to be non-blocking.
The parameters ssl
and cert
are guaranteed to remain valid throughout the handshake. On the other hand, this function must save the contents of input
if the value is needed for later processing, because the input
buffer is no longer valid after this function returns.
This function may call mbedtls_ssl_set_async_operation_data() to store an operation context for later retrieval by the resume or cancel callback.
- Warning:
- RSA decryption as used in TLS is subject to a potential timing side channel attack first discovered by Bleichenbacher in 1998. This attack can be remotely exploitable in practice. To avoid this attack, you must ensure that if the callback performs an RSA decryption, the time it takes to execute and return the result does not depend on whether the RSA decryption succeeded or reported invalid padding.
- Parameters:
-
ssl The SSL connection instance. It should not be modified other than via mbedtls_ssl_set_async_operation_data(). cert Certificate containing the public key. In simple cases, this is one of the pointers passed to mbedtls_ssl_conf_own_cert() when configuring the SSL connection. However, if other callbacks are used, this property may not hold. For example, if an SNI callback is registered with mbedtls_ssl_conf_sni(), then this callback determines what certificate is used. input Buffer containing the input ciphertext. This buffer is no longer valid when the function returns. input_len Size of the input
buffer in bytes.
- Returns:
- 0 if the operation was started successfully and the SSL stack should call the resume callback immediately.
- MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS if the operation was started successfully and the SSL stack should return immediately without calling the resume callback yet.
- MBEDTLS_ERR_SSL_HW_ACCEL_FALLTHROUGH if the external processor does not support this key. The SSL stack will use the private key object instead.
-
Any other error indicates a fatal failure and is propagated up the call chain. The callback should use
MBEDTLS_ERR_PK_xxx
error codes, and must not useMBEDTLS_ERR_SSL_xxx
error codes except as directed in the documentation of this callback.
typedef int mbedtls_ssl_async_resume_t(mbedtls_ssl_context *ssl, unsigned char *output, size_t *output_len, size_t output_size) |
Callback type: resume external operation.
This callback is called during an SSL handshake to resume an external operation started by the mbedtls_ssl_async_sign_t or mbedtls_ssl_async_decrypt_t callback.
This function typically checks the status of a pending request or causes the request queue to make progress, and does not wait for the operation to complete. This allows the handshake step to be non-blocking.
This function may call mbedtls_ssl_get_async_operation_data() to retrieve an operation context set by the start callback. It may call mbedtls_ssl_set_async_operation_data() to modify this context.
Note that when this function returns a status other than MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS, it must free any resources associated with the operation.
- Parameters:
-
ssl The SSL connection instance. It should not be modified other than via mbedtls_ssl_set_async_operation_data(). output Buffer containing the output (signature or decrypted data) on success. output_len On success, number of bytes written to output
.output_size Size of the output
buffer in bytes.
- Returns:
- 0 if output of the operation is available in the
output
buffer. - MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS if the operation is still in progress. Subsequent requests for progress on the SSL connection will call the resume callback again.
-
Any other error means that the operation is aborted. The SSL handshake is aborted. The callback should use
MBEDTLS_ERR_PK_xxx
error codes, and must not useMBEDTLS_ERR_SSL_xxx
error codes except as directed in the documentation of this callback.
typedef int mbedtls_ssl_async_sign_t(mbedtls_ssl_context *ssl, mbedtls_x509_crt *cert, mbedtls_md_type_t md_alg, const unsigned char *hash, size_t hash_len) |
Callback type: start external signature operation.
This callback is called during an SSL handshake to start a signature decryption operation using an external processor. The parameter cert
contains the public key; it is up to the callback function to determine how to access the associated private key.
This function typically sends or enqueues a request, and does not wait for the operation to complete. This allows the handshake step to be non-blocking.
The parameters ssl
and cert
are guaranteed to remain valid throughout the handshake. On the other hand, this function must save the contents of hash
if the value is needed for later processing, because the hash
buffer is no longer valid after this function returns.
This function may call mbedtls_ssl_set_async_operation_data() to store an operation context for later retrieval by the resume or cancel callback.
- Note:
- For RSA signatures, this function must produce output that is consistent with PKCS#1 v1.5 in the same way as mbedtls_rsa_pkcs1_sign(). Before the private key operation, apply the padding steps described in RFC 8017, section 9.2 "EMSA-PKCS1-v1_5" as follows.
- If
md_alg
is MBEDTLS_MD_NONE, apply the PKCS#1 v1.5 encoding, treatinghash
as the DigestInfo to be padded. In other words, apply EMSA-PKCS1-v1_5 starting from step 3, with `T = hash` and `tLen = hash_len`. - If `md_alg != MBEDTLS_MD_NONE`, apply the PKCS#1 v1.5 encoding, treating
hash
as the hash to be encoded and padded. In other words, apply EMSA-PKCS1-v1_5 starting from step 2, with `digestAlgorithm` obtained by calling mbedtls_oid_get_oid_by_md() onmd_alg
.
- If
- For ECDSA signatures, the output format is the DER encoding `Ecdsa-Sig-Value` defined in [RFC 4492 section 5.4](https://tools.ietf.org/html/rfc4492#section-5.4).
- Parameters:
-
ssl The SSL connection instance. It should not be modified other than via mbedtls_ssl_set_async_operation_data(). cert Certificate containing the public key. In simple cases, this is one of the pointers passed to mbedtls_ssl_conf_own_cert() when configuring the SSL connection. However, if other callbacks are used, this property may not hold. For example, if an SNI callback is registered with mbedtls_ssl_conf_sni(), then this callback determines what certificate is used. md_alg Hash algorithm. hash Buffer containing the hash. This buffer is no longer valid when the function returns. hash_len Size of the hash
buffer in bytes.
- Returns:
- 0 if the operation was started successfully and the SSL stack should call the resume callback immediately.
- MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS if the operation was started successfully and the SSL stack should return immediately without calling the resume callback yet.
- MBEDTLS_ERR_SSL_HW_ACCEL_FALLTHROUGH if the external processor does not support this key. The SSL stack will use the private key object instead.
-
Any other error indicates a fatal failure and is propagated up the call chain. The callback should use
MBEDTLS_ERR_PK_xxx
error codes, and must not useMBEDTLS_ERR_SSL_xxx
error codes except as directed in the documentation of this callback.
typedef int mbedtls_ssl_cookie_check_t(void *ctx, const unsigned char *cookie, size_t clen, const unsigned char *info, size_t ilen) |
Callback type: verify a cookie.
- Parameters:
-
ctx Context for the callback cookie Cookie to verify clen Length of cookie info Client ID info that was passed to mbedtls_ssl_set_client_transport_id()
ilen Length of info in bytes
- Returns:
- The callback must return 0 if cookie is valid, or a negative error code.
typedef int mbedtls_ssl_cookie_write_t(void *ctx, unsigned char **p, unsigned char *end, const unsigned char *info, size_t ilen) |
Callback type: generate a cookie.
- Parameters:
-
ctx Context for the callback p Buffer to write to, must be updated to point right after the cookie end Pointer to one past the end of the output buffer info Client ID info that was passed to mbedtls_ssl_set_client_transport_id()
ilen Length of info in bytes
- Returns:
- The callback must return 0 on success, or a negative error code.
typedef int mbedtls_ssl_export_keys_ext_t(void *p_expkey, const unsigned char *ms, const unsigned char *kb, size_t maclen, size_t keylen, size_t ivlen, const unsigned char client_random[32], const unsigned char server_random[32], mbedtls_tls_prf_types tls_prf_type) |
Callback type: Export key block, master secret, handshake randbytes and the tls_prf function used to derive keys.
- Note:
- This is required for certain uses of TLS, e.g. EAP-TLS (RFC 5216) and Thread. The key pointers are ephemeral and therefore must not be stored. The master secret and keys should not be used directly except as an input to a key derivation function.
- Parameters:
-
p_expkey Context for the callback. ms Pointer to master secret (fixed length: 48 bytes). kb Pointer to key block, see RFC 5246 section 6.3. (variable length: 2 * maclen + 2 * keylen + 2 * ivlen). maclen MAC length. keylen Key length. ivlen IV length. client_random The client random bytes. server_random The server random bytes. tls_prf_type The tls_prf enum type.
- Returns:
- 0 if successful, or a specific MBEDTLS_ERR_XXX code.
typedef int mbedtls_ssl_export_keys_t(void *p_expkey, const unsigned char *ms, const unsigned char *kb, size_t maclen, size_t keylen, size_t ivlen) |
Callback type: Export key block and master secret.
- Note:
- This is required for certain uses of TLS, e.g. EAP-TLS (RFC 5216) and Thread. The key pointers are ephemeral and therefore must not be stored. The master secret and keys should not be used directly except as an input to a key derivation function.
- Parameters:
-
p_expkey Context for the callback ms Pointer to master secret (fixed length: 48 bytes) kb Pointer to key block, see RFC 5246 section 6.3 (variable length: 2 * maclen + 2 * keylen + 2 * ivlen). maclen MAC length keylen Key length ivlen IV length
- Returns:
- 0 if successful, or a specific MBEDTLS_ERR_XXX code.
typedef int mbedtls_ssl_get_timer_t(void *ctx) |
typedef int mbedtls_ssl_recv_t(void *ctx, unsigned char *buf, size_t len) |
Callback type: receive data from the network.
- Note:
- That callback may be either blocking or non-blocking.
- Parameters:
-
ctx Context for the receive callback (typically a file descriptor) buf Buffer to write the received data to len Length of the receive buffer
- Returns:
- The callback must return the number of bytes received, or a non-zero error code. If performing non-blocking I/O,
MBEDTLS_ERR_SSL_WANT_READ
must be returned when the operation would block.
- Note:
- The callback may receive fewer bytes than the length of the buffer. It must always return the number of bytes actually received and written to the buffer.
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.
- Note:
- That callback must block until data is received, or the timeout delay expires, or the operation is interrupted by a signal.
- Parameters:
-
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 nomber of millisecondes to wait for data 0 means no timeout (potentially waiting forever)
- Returns:
- The callback must return the number of bytes received, or a non-zero error code:
MBEDTLS_ERR_SSL_TIMEOUT
if the operation timed out,MBEDTLS_ERR_SSL_WANT_READ
if interrupted by a signal.
- Note:
- The callback may receive fewer bytes than the length of the buffer. It must always return the number of bytes actually received and written to the buffer.
typedef int mbedtls_ssl_send_t(void *ctx, const unsigned char *buf, size_t len) |
Callback type: send data on the network.
- Note:
- That callback may be either blocking or non-blocking.
- Parameters:
-
ctx Context for the send callback (typically a file descriptor) buf Buffer holding the data to send len Length of the data to send
- Returns:
- The callback must return the number of bytes sent if any, or a non-zero error code. If performing non-blocking I/O,
MBEDTLS_ERR_SSL_WANT_WRITE
must be returned when the operation would block.
- Note:
- The callback is allowed to send fewer bytes than requested. It must always return the number of bytes actually sent.
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.
- Parameters:
-
ctx Context pointer int_ms Intermediate delay in milliseconds fin_ms Final delay in milliseconds 0 cancels the current timer.
- Note:
- This callback must at least store the necessary information for the associated
mbedtls_ssl_get_timer_t
callback to return correct information. -
If using a event-driven style of programming, an event must be generated when the final delay is passed. The event must cause a call to
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. - Only one timer at a time must be running. Calling this function while a timer is running must cancel it. Cancelled timers must not generate any event.
typedef int mbedtls_ssl_ticket_parse_t(void *p_ticket, mbedtls_ssl_session *session, unsigned char *buf, size_t len) |
Callback type: parse and load session ticket.
- Note:
- This describes what a callback implementation should do. This callback should parse a session ticket as generated by the corresponding mbedtls_ssl_ticket_write_t function, and, if the ticket is authentic and valid, load the session.
- The implementation is allowed to modify the first len bytes of the input buffer, eg to use it as a temporary area for the decrypted ticket contents.
- Parameters:
-
p_ticket Context for the callback session SSL session to be loaded buf Start of the buffer containing the ticket len Length of the ticket.
- Returns:
- 0 if successful, or MBEDTLS_ERR_SSL_INVALID_MAC if not authentic, or MBEDTLS_ERR_SSL_SESSION_TICKET_EXPIRED if expired, or any other non-zero code for other failures.
typedef int mbedtls_ssl_ticket_write_t(void *p_ticket, const mbedtls_ssl_session *session, unsigned char *start, const unsigned char *end, size_t *tlen, uint32_t *lifetime) |
Callback type: generate and write session ticket.
- Note:
- This describes what a callback implementation should do. This callback should generate an encrypted and authenticated ticket for the session and write it to the output buffer. Here, ticket means the opaque ticket part of the NewSessionTicket structure of RFC 5077.
- Parameters:
-
p_ticket Context for the callback session SSL session to 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
- Returns:
- 0 if successful, or a specific MBEDTLS_ERR_XXX code.
Function Documentation
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.
- Parameters:
-
ssl SSL context
- Returns:
- 0 if nothing's pending, 1 otherwise.
- Note:
- This is different in purpose and behaviour from
mbedtls_ssl_get_bytes_avail
in that it considers any kind of unprocessed data, not only unread application data. Ifmbedtls_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. -
If this function returns 1 (data pending), this does not imply that a subsequent call to
mbedtls_ssl_read
will provide any data; e.g., the unprocessed data might turn out to be an alert or a handshake message. - This function is useful in the following situation: If the SSL/TLS module successfully returns from an operation - e.g. a handshake or an application record read - and you're awaiting incoming data next, you must not immediately idle on the underlying transport to have data ready, but you need to check the value of this function first. The reason is that the desired data might already be read but not yet processed. If, in contrast, a previous call to the SSL/TLS module returned MBEDTLS_ERR_SSL_WANT_READ, it is not necessary to call this function, as the latter error code entails that all internal data has been processed.
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.
- Parameters:
-
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.
- Note:
- This routine only checks whether the provided buffer begins with a valid and authentic record that has not been seen before, but does not check potential data following the initial record. In particular, it is possible to pass DTLS datagrams containing multiple records, in which case only the first record is checked.
-
This function modifies the input buffer
buf
. If you need to preserve the original record, you have to maintain a copy.
- Returns:
0
if the record is valid and authentic and has not been seen before.- MBEDTLS_ERR_SSL_INVALID_MAC if the check completed successfully but the record was found to be not authentic.
- MBEDTLS_ERR_SSL_INVALID_RECORD if the check completed successfully but the record was found to be invalid for a reason different from authenticity checking.
- MBEDTLS_ERR_SSL_UNEXPECTED_RECORD if the check completed successfully but the record was found to be unexpected in the state of the SSL context, including replayed records.
- Another negative error code on different kinds of failure. In this case, the SSL context becomes unusable and needs to be freed or reset before reuse.
int mbedtls_ssl_close_notify | ( | mbedtls_ssl_context * | ssl ) |
Notify the peer that the connection is being closed.
- Parameters:
-
ssl SSL context
- Returns:
- 0 if successful, or a specific SSL error code.
- Note:
- If this function returns something other than 0 or MBEDTLS_ERR_SSL_WANT_READ/WRITE, 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_conf_alpn_protocols | ( | mbedtls_ssl_config * | conf, |
const char ** | protos | ||
) |
Set the supported Application Layer Protocols.
- Parameters:
-
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 atleast as long as the lifetime of the SSL configuration structure.
- Returns:
- 0 on success, or MBEDTLS_ERR_SSL_BAD_INPUT_DATA.
void mbedtls_ssl_conf_arc4_support | ( | mbedtls_ssl_config * | conf, |
char | arc4 | ||
) |
Disable or enable support for RC4 (Default: MBEDTLS_SSL_ARC4_DISABLED)
- Warning:
- Use of RC4 in DTLS/TLS has been prohibited by RFC 7465 for security reasons. Use at your own risk.
- Note:
- This function is deprecated and will likely be removed in a future version of the library. RC4 is disabled by default at compile time and needs to be actively enabled for use with legacy systems.
- Parameters:
-
conf SSL configuration arc4 MBEDTLS_SSL_ARC4_ENABLED or MBEDTLS_SSL_ARC4_DISABLED
void mbedtls_ssl_conf_async_private_cb | ( | mbedtls_ssl_config * | conf, |
mbedtls_ssl_async_sign_t * | f_async_sign, | ||
mbedtls_ssl_async_decrypt_t * | f_async_decrypt, | ||
mbedtls_ssl_async_resume_t * | f_async_resume, | ||
mbedtls_ssl_async_cancel_t * | f_async_cancel, | ||
void * | config_data | ||
) |
Configure asynchronous private key operation callbacks.
- Parameters:
-
conf SSL configuration context f_async_sign Callback to start a signature operation. See the description of mbedtls_ssl_async_sign_t for more information. This may be NULL
if the external processor does not support any signature operation; in this case the private key object associated with the certificate will be used.f_async_decrypt Callback to start a decryption operation. See the description of mbedtls_ssl_async_decrypt_t for more information. This may be NULL
if the external processor does not support any decryption operation; in this case the private key object associated with the certificate will be used.f_async_resume Callback to resume an asynchronous operation. See the description of mbedtls_ssl_async_resume_t for more information. This may not be NULL
unlessf_async_sign
andf_async_decrypt
are bothNULL
.f_async_cancel Callback to cancel an asynchronous operation. See the description of mbedtls_ssl_async_cancel_t for more information. This may be NULL
if no cleanup is needed.config_data A pointer to configuration data which can be retrieved with mbedtls_ssl_conf_get_async_config_data(). The library stores this value without dereferencing it.
void mbedtls_ssl_conf_authmode | ( | mbedtls_ssl_config * | conf, |
int | authmode | ||
) |
Set the certificate verification mode Default: NONE on server, REQUIRED on client.
- Parameters:
-
conf SSL configuration authmode can be:
MBEDTLS_SSL_VERIFY_NONE: peer certificate is not checked (default on server) (insecure on client)
MBEDTLS_SSL_VERIFY_OPTIONAL: peer certificate is checked, however the handshake continues even if verification failed; mbedtls_ssl_get_verify_result() can be called after the handshake is complete.
MBEDTLS_SSL_VERIFY_REQUIRED: peer *must* present a valid certificate, handshake is aborted if verification failed. (default on client)
- Note:
- On client, MBEDTLS_SSL_VERIFY_REQUIRED is the recommended mode. With MBEDTLS_SSL_VERIFY_OPTIONAL, the user needs to call mbedtls_ssl_get_verify_result() at the right time(s), which may not be obvious, while REQUIRED always perform the verification as soon as possible. For example, REQUIRED was protecting against the "triple handshake" attack even before it was found.
void mbedtls_ssl_conf_ca_cb | ( | mbedtls_ssl_config * | conf, |
mbedtls_x509_crt_ca_cb_t | f_ca_cb, | ||
void * | p_ca_cb | ||
) |
Set the trusted certificate callback.
This API allows to register the set of trusted certificates through a callback, instead of a linked list as configured by mbedtls_ssl_conf_ca_chain().
This is useful for example in contexts where a large number of CAs are used, and the inefficiency of maintaining them in a linked list cannot be tolerated. It is also useful when the set of trusted CAs needs to be modified frequently.
See the documentation of `mbedtls_x509_crt_ca_cb_t` for more information.
- Parameters:
-
conf The SSL configuration to register the callback with. f_ca_cb The trusted certificate callback to use when verifying certificate chains. p_ca_cb The context to be passed to f_ca_cb
(for example, a reference to a trusted CA database).
- Note:
- This API is incompatible with mbedtls_ssl_conf_ca_chain(): Any call to this function overwrites the values set through earlier calls to mbedtls_ssl_conf_ca_chain() or mbedtls_ssl_conf_ca_cb().
- This API is incompatible with CA indication in CertificateRequest messages: A server-side SSL context which is bound to an SSL configuration that uses a CA callback configured via mbedtls_ssl_conf_ca_cb(), and which requires client authentication, will send an empty CA list in the corresponding CertificateRequest message.
- This API is incompatible with mbedtls_ssl_set_hs_ca_chain(): If an SSL context is bound to an SSL configuration which uses CA callbacks configured via mbedtls_ssl_conf_ca_cb(), then calls to mbedtls_ssl_set_hs_ca_chain() have no effect.
- The use of this API disables the use of restartable ECC during X.509 CRT signature verification (but doesn't affect other uses).
- Warning:
- This API is incompatible with the use of CRLs. Any call to mbedtls_ssl_conf_ca_cb() unsets CRLs configured through earlier calls to mbedtls_ssl_conf_ca_chain().
-
In multi-threaded environments, the callback
f_ca_cb
must be thread-safe, and it is the user's responsibility to guarantee this (for example through a mutex contained in the callback context pointed to byp_ca_cb
).
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.
- Note:
- See
mbedtls_x509_crt_verify()
for notes regarding the parameters ca_chain (maps to trust_ca for that function) and ca_crl.
- Parameters:
-
conf SSL configuration ca_chain trusted CA chain (meaning all fully trusted top-level CAs) ca_crl trusted CA CRLs
void mbedtls_ssl_conf_cbc_record_splitting | ( | mbedtls_ssl_config * | conf, |
char | split | ||
) |
Enable / Disable 1/n-1 record splitting (Default: MBEDTLS_SSL_CBC_RECORD_SPLITTING_ENABLED)
- Note:
- Only affects SSLv3 and TLS 1.0, not higher versions. Does not affect non-CBC ciphersuites in any version.
- Parameters:
-
conf SSL configuration split MBEDTLS_SSL_CBC_RECORD_SPLITTING_ENABLED or MBEDTLS_SSL_CBC_RECORD_SPLITTING_DISABLED
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.
- Note:
- The restrictions are enforced for all certificates in the chain. However, signatures in the handshake are not covered by this setting but by mbedtls_ssl_conf_sig_hashes().
- Parameters:
-
conf SSL configuration profile Profile to use
void mbedtls_ssl_conf_cert_req_ca_list | ( | mbedtls_ssl_config * | conf, |
char | cert_req_ca_list | ||
) |
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.
- Parameters:
-
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: - MBEDTLS_SSL_UNEXPECTED_CID_IGNORE In this case, the record is silently ignored.
- MBEDTLS_SSL_UNEXPECTED_CID_FAIL In this case, the stack fails with the specific error code MBEDTLS_ERR_SSL_UNEXPECTED_CID.
- Note:
- The CID specification allows implementations to either use a common length for all incoming connection IDs or allow variable-length incoming IDs. Mbed TLS currently requires a common length for all connections sharing the same SSL configuration; this allows simpler parsing of record headers.
- Returns:
0
on success.-
MBEDTLS_ERR_SSL_BAD_INPUT_DATA if
own_cid_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. (Overrides all version-specific lists)
The ciphersuites array is not copied, and must remain valid for the lifetime of the ssl_config.
Note: The server uses its own preferences over the preference of the client unless MBEDTLS_SSL_SRV_RESPECT_CLIENT_PREFERENCE is defined!
- Parameters:
-
conf SSL configuration ciphersuites 0-terminated list of allowed ciphersuites
void mbedtls_ssl_conf_ciphersuites_for_version | ( | mbedtls_ssl_config * | conf, |
const int * | ciphersuites, | ||
int | major, | ||
int | minor | ||
) |
Set the list of allowed ciphersuites and the preference order for a specific version of the protocol.
(Only useful on the server side)
The ciphersuites array is not copied, and must remain valid for the lifetime of the ssl_config.
- Parameters:
-
conf SSL configuration ciphersuites 0-terminated list of allowed ciphersuites major Major version number (only MBEDTLS_SSL_MAJOR_VERSION_3 supported) minor Minor version number (MBEDTLS_SSL_MINOR_VERSION_0, MBEDTLS_SSL_MINOR_VERSION_1 and MBEDTLS_SSL_MINOR_VERSION_2, MBEDTLS_SSL_MINOR_VERSION_3 supported)
- Note:
- With DTLS, use MBEDTLS_SSL_MINOR_VERSION_2 for DTLS 1.0 and MBEDTLS_SSL_MINOR_VERSION_3 for DTLS 1.2
void mbedtls_ssl_conf_curves | ( | mbedtls_ssl_config * | conf, |
const mbedtls_ecp_group_id * | curves | ||
) |
Set the allowed curves in order of preference.
(Default: all defined curves.)
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.
- Note:
- This has no influence on which curves are allowed inside the certificate chains, see
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. - This list should be ordered by decreasing preference (preferred curve first).
- Parameters:
-
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 | ||
) |
MBEDTLS_DEPRECATED int mbedtls_ssl_conf_dh_param | ( | mbedtls_ssl_config * | conf, |
const char * | dhm_P, | ||
const char * | dhm_G | ||
) |
Set the Diffie-Hellman public P and G values, read as hexadecimal strings (server-side only) (Default values: MBEDTLS_DHM_RFC3526_MODP_2048_[PG])
- Parameters:
-
conf SSL configuration dhm_P Diffie-Hellman-Merkle modulus dhm_G Diffie-Hellman-Merkle generator
- Returns:
- 0 if successful
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)
- Parameters:
-
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
- Returns:
- 0 if successful
int mbedtls_ssl_conf_dh_param_ctx | ( | mbedtls_ssl_config * | conf, |
mbedtls_dhm_context * | dhm_ctx | ||
) |
void mbedtls_ssl_conf_dhm_min_bitlen | ( | mbedtls_ssl_config * | conf, |
unsigned int | bitlen | ||
) |
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.
- Parameters:
-
conf SSL configuration mode MBEDTLS_SSL_ANTI_REPLAY_ENABLED or MBEDTLS_SSL_ANTI_REPLAY_DISABLED.
- Warning:
- Disabling this is a security risk unless the application protocol handles duplicated packets in a safe way. You should not disable this without careful consideration. However, if your application already detects duplicated packets and needs information about them to adjust its transmission strategy, then you'll want to disable this.
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).
- Parameters:
-
conf SSL configuration limit Limit, or 0 to disable.
- Note:
- If the limit is N, then the connection is terminated when the Nth non-authentic record is seen.
- Records with an invalid header are not counted, only the ones going through the authentication-decryption phase.
- This is a security trade-off related to the fact that it's often relatively easy for an active attacker ot inject UDP datagrams. On one hand, setting a low limit here makes it easier for such an attacker to forcibly terminated a connection. On the other hand, a high limit or no limit might make us waste resources checking authentication on many bogus packets.
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.
- Warning:
- Disabling hello verification allows your server to be used for amplification in DoS attacks against other hosts. Only disable if you known this can't happen in your particular environment.
- Note:
- See comments on
mbedtls_ssl_handshake()
about handling the MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED that is expected on the first handshake attempt when this is enabled. -
This is also necessary to handle client reconnection from the same port as described in RFC 6347 section 4.2.8 (only the variant with cookies is supported currently). See comments on
mbedtls_ssl_read()
for details.
- Parameters:
-
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)
- Note:
- This should always be enabled, it is a security improvement, and should not cause any interoperability issue (used only if the peer supports it too).
- Parameters:
-
conf SSL configuration etm MBEDTLS_SSL_ETM_ENABLED or MBEDTLS_SSL_ETM_DISABLED
void mbedtls_ssl_conf_endpoint | ( | mbedtls_ssl_config * | conf, |
int | endpoint | ||
) |
void mbedtls_ssl_conf_export_keys_cb | ( | mbedtls_ssl_config * | conf, |
mbedtls_ssl_export_keys_t * | f_export_keys, | ||
void * | p_export_keys | ||
) |
void mbedtls_ssl_conf_export_keys_ext_cb | ( | mbedtls_ssl_config * | conf, |
mbedtls_ssl_export_keys_ext_t * | f_export_keys_ext, | ||
void * | p_export_keys | ||
) |
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)
- Note:
- This should always be enabled, it is a security fix to the protocol, and should not cause any interoperability issue (used only if the peer supports it too).
- Parameters:
-
conf SSL configuration ems MBEDTLS_SSL_EXTENDED_MS_ENABLED or MBEDTLS_SSL_EXTENDED_MS_DISABLED
void mbedtls_ssl_conf_fallback | ( | mbedtls_ssl_config * | conf, |
char | fallback | ||
) |
Set the fallback flag (client-side only).
(Default: MBEDTLS_SSL_IS_NOT_FALLBACK).
- Note:
- Set to MBEDTLS_SSL_IS_FALLBACK when preparing a fallback connection, that is a connection with max_version set to a lower value than the value you're willing to use. Such fallback connections are not recommended but are sometimes necessary to interoperate with buggy (version-intolerant) servers.
- Warning:
- You should NOT set this to MBEDTLS_SSL_IS_FALLBACK for non-fallback connections! This would appear to work for a while, then cause failures when the server is upgraded to support a newer TLS version.
- Parameters:
-
conf SSL configuration fallback MBEDTLS_SSL_IS_NOT_FALLBACK or MBEDTLS_SSL_IS_FALLBACK
void* mbedtls_ssl_conf_get_async_config_data | ( | const mbedtls_ssl_config * | conf ) |
Retrieve the configuration data set by mbedtls_ssl_conf_async_private_cb().
- Parameters:
-
conf SSL configuration context
- Returns:
- The configuration data set by mbedtls_ssl_conf_async_private_cb().
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.)
- Parameters:
-
conf SSL configuration min Initial timeout value in milliseconds. Default: 1000 (1 second). max Maximum timeout value in milliseconds. Default: 60000 (60 seconds).
- Note:
- Default values are from RFC 6347 section 4.2.4.1.
- The 'min' value should typically be slightly above the expected round-trip time to your peer, plus whatever time it takes for the peer to process the message. For example, if your RTT is about 600ms and you peer needs up to 1s to do the cryptographic operations in the handshake, then you should set 'min' slightly above 1600. Lower values of 'min' might cause spurious resends which waste network resources, while larger value of 'min' will increase overall latency on unreliable network links.
- The more unreliable your network connection is, the larger your max / min ratio needs to be in order to achieve reliable handshakes.
- Messages are retransmitted up to log2(ceil(max/min)) times. For example, if min = 1s and max = 5s, the retransmit plan goes: send ... 1s -> resend ... 2s -> resend ... 4s -> resend ... 5s -> give up and return a timeout error.
void mbedtls_ssl_conf_legacy_renegotiation | ( | mbedtls_ssl_config * | conf, |
int | allow_legacy | ||
) |
Prevent or allow legacy renegotiation.
(Default: MBEDTLS_SSL_LEGACY_NO_RENEGOTIATION)
MBEDTLS_SSL_LEGACY_NO_RENEGOTIATION allows connections to be established even if the peer does not support secure renegotiation, but does not allow renegotiation to take place if not secure. (Interoperable and secure option)
MBEDTLS_SSL_LEGACY_ALLOW_RENEGOTIATION allows renegotiations with non-upgraded peers. Allowing legacy renegotiation makes the connection vulnerable to specific man in the middle attacks. (See RFC 5746) (Most interoperable and least secure option)
MBEDTLS_SSL_LEGACY_BREAK_HANDSHAKE breaks off connections if peer does not support secure renegotiation. Results in interoperability issues with non-upgraded peers that do not support renegotiation altogether. (Most secure option, interoperability issues)
- Parameters:
-
conf SSL configuration allow_legacy Prevent or allow (SSL_NO_LEGACY_RENEGOTIATION, SSL_ALLOW_LEGACY_RENEGOTIATION or MBEDTLS_SSL_LEGACY_BREAK_HANDSHAKE)
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)
- Note:
- On the client side, the maximum fragment length extension *will not* be used, unless the maximum fragment length has been set via this function to a value different than MBEDTLS_SSL_MAX_FRAG_LEN_NONE.
-
With TLS, this currently only affects ApplicationData (sent with
mbedtls_ssl_read()
), not handshake messages. With DTLS, this affects both ApplicationData and handshake. -
This sets the maximum length for a record's payload, excluding record overhead that will be added to it, see
mbedtls_ssl_get_record_expansion()
. -
For DTLS, it is also possible to set a limit for the total size of daragrams passed to the transport layer, including record overhead, see
mbedtls_ssl_set_mtu()
.
- Parameters:
-
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)
- Returns:
- 0 if successful or MBEDTLS_ERR_SSL_BAD_INPUT_DATA
void mbedtls_ssl_conf_max_version | ( | mbedtls_ssl_config * | conf, |
int | major, | ||
int | minor | ||
) |
Set the maximum supported version sent from the client side and/or accepted at the server side (Default: MBEDTLS_SSL_MAX_MAJOR_VERSION, MBEDTLS_SSL_MAX_MINOR_VERSION)
- Note:
- This ignores ciphersuites from higher versions.
- With DTLS, use MBEDTLS_SSL_MINOR_VERSION_2 for DTLS 1.0 and MBEDTLS_SSL_MINOR_VERSION_3 for DTLS 1.2
- Parameters:
-
conf SSL configuration major Major version number (only MBEDTLS_SSL_MAJOR_VERSION_3 supported) minor Minor version number (MBEDTLS_SSL_MINOR_VERSION_0, MBEDTLS_SSL_MINOR_VERSION_1 and MBEDTLS_SSL_MINOR_VERSION_2, MBEDTLS_SSL_MINOR_VERSION_3 supported)
void mbedtls_ssl_conf_min_version | ( | mbedtls_ssl_config * | conf, |
int | major, | ||
int | minor | ||
) |
Set the minimum accepted SSL/TLS protocol version (Default: TLS 1.0)
- Note:
- Input outside of the SSL_MAX_XXXXX_VERSION and SSL_MIN_XXXXX_VERSION range is ignored.
- MBEDTLS_SSL_MINOR_VERSION_0 (SSL v3) should be avoided.
- With DTLS, use MBEDTLS_SSL_MINOR_VERSION_2 for DTLS 1.0 and MBEDTLS_SSL_MINOR_VERSION_3 for DTLS 1.2
- Parameters:
-
conf SSL configuration major Major version number (only MBEDTLS_SSL_MAJOR_VERSION_3 supported) minor Minor version number (MBEDTLS_SSL_MINOR_VERSION_0, MBEDTLS_SSL_MINOR_VERSION_1 and MBEDTLS_SSL_MINOR_VERSION_2, MBEDTLS_SSL_MINOR_VERSION_3 supported)
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.
- Note:
- own_cert should contain in order from the bottom up your certificate chain. The top certificate (self-signed) can be omitted.
- On server, this function can be called multiple times to provision more than one cert/key pair (eg one ECDSA, one RSA with SHA-256, one RSA with SHA-1). An adequate certificate will be selected according to the client's advertised capabilities. In case multiple certificates are adequate, preference is given to the one set by the first call to this function, then second, etc.
- On client, only the first call has any effect. That is, only one client certificate can be provisioned. The server's preferences in its CertficateRequest message will be ignored and our only cert will be sent regardless of whether it matches those preferences - the server can then decide what it wants to do with it.
-
The provided
pk_key
needs to match the public key in the first certificate inown_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.
- Parameters:
-
conf SSL configuration own_cert own public certificate chain pk_key own private key
- Returns:
- 0 on success or MBEDTLS_ERR_SSL_ALLOC_FAILED
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 a pre-shared key (PSK) and identity to be used in PSK-based ciphersuites.
- Note:
- This is mainly useful for clients. Servers will usually want to use
mbedtls_ssl_conf_psk_cb()
instead.
- Warning:
- Currently, clients can only register a single pre-shared key. Calling this function or mbedtls_ssl_conf_psk_opaque() more than once will overwrite values configured in previous calls. Support for setting multiple PSKs on clients and selecting one based on the identity hint is not a planned feature, but feedback is welcomed.
- Parameters:
-
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.
- Note:
- The PSK and its identity are copied internally and hence need not be preserved by the caller for the lifetime of the SSL configuration.
- Returns:
0
if successful.-
An
MBEDTLS_ERR_SSL_XXX
error code on failure.
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:
void*
: The opaque pointerp_psk
.mbedtls_ssl_context*
: The SSL context to which the operation applies.const
unsigned char*: The PSK identity selected by the client.size_t:
The length of the PSK identity selected by the client.
If a valid PSK identity is found, the callback should use mbedtls_ssl_set_hs_psk()
or mbedtls_ssl_set_hs_psk_opaque()
on the SSL context to set the correct PSK and return 0
. Any other return value will result in a denied PSK identity.
- Note:
- If you set a PSK callback using this function, then you don't need to set a PSK key and identity using
mbedtls_ssl_conf_psk()
.
- Parameters:
-
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.
int mbedtls_ssl_conf_psk_opaque | ( | mbedtls_ssl_config * | conf, |
psa_key_handle_t | psk, | ||
const unsigned char * | psk_identity, | ||
size_t | psk_identity_len | ||
) |
Configure an opaque pre-shared key (PSK) and identity to be used in PSK-based ciphersuites.
- Note:
- This is mainly useful for clients. Servers will usually want to use
mbedtls_ssl_conf_psk_cb()
instead.
- Warning:
- Currently, clients can only register a single pre-shared key. Calling this function or mbedtls_ssl_conf_psk() more than once will overwrite values configured in previous calls. Support for setting multiple PSKs on clients and selecting one based on the identity hint is not a planned feature, but feedback is welcomed.
- Parameters:
-
conf The SSL configuration to register the PSK with. psk The identifier of the key slot holding the PSK. Until conf
is destroyed or this function is successfully called again, the key slotpsk
must be populated with a key of type PSA_ALG_CATEGORY_KEY_DERIVATION whose policy allows its use for the key derivation algorithm applied in the handshake.psk_identity The pointer to the pre-shared key identity. psk_identity_len The length of the pre-shared key identity in bytes.
- Note:
- The PSK identity hint is copied internally and hence need not be preserved by the caller for the lifetime of the SSL configuration.
- Returns:
0
if successful.-
An
MBEDTLS_ERR_SSL_XXX
error code on failure.
void mbedtls_ssl_conf_read_timeout | ( | mbedtls_ssl_config * | conf, |
uint32_t | timeout | ||
) |
Set the timeout period for mbedtls_ssl_read() (Default: no timeout.)
- Parameters:
-
conf SSL configuration context timeout Timeout value in milliseconds. Use 0 for no timeout (default).
- Note:
- With blocking I/O, this will only work if a non-NULL
f_recv_timeout
was set withmbedtls_ssl_set_bio()
. With non-blocking I/O, this will only work if timer callbacks were set withmbedtls_ssl_set_timer_cb()
. - With non-blocking I/O, you may also skip this function altogether and handle timeouts at the application layer.
void mbedtls_ssl_conf_renegotiation | ( | mbedtls_ssl_config * | conf, |
int | renegotiation | ||
) |
Enable / Disable renegotiation support for connection when initiated by peer (Default: MBEDTLS_SSL_RENEGOTIATION_DISABLED)
- Warning:
- It is recommended to always disable renegotation unless you know you need it and you know what you're doing. In the past, there have been several issues associated with renegotiation or a poor understanding of its properties.
- Note:
- Server-side, enabling renegotiation also makes the server susceptible to a resource DoS by a malicious client.
- Parameters:
-
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.
- Note:
- With DTLS and server-initiated renegotiation, the HelloRequest is retransmited every time mbedtls_ssl_read() times out or receives Application Data, until:
- max_records records have beens seen, if it is >= 0, or
- the number of retransmits that would happen during an actual handshake has been reached. Please remember the request might be lost a few times if you consider setting max_records to a really low value.
- Warning:
- On client, the grace period can only happen during mbedtls_ssl_read(), as opposed to mbedtls_ssl_write() and mbedtls_ssl_renegotiate() which always behave as if max_record was 0. The reason is, if we receive application data from the server, we need a place to write it, which only happens during mbedtls_ssl_read().
- Parameters:
-
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.
- Note:
- When the configured transport is MBEDTLS_SSL_TRANSPORT_DATAGRAM the maximum renegotiation period is 2^48 - 1, and for MBEDTLS_SSL_TRANSPORT_STREAM, the maximum renegotiation period is 2^64 - 1.
- Parameters:
-
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 | ||
) |
void mbedtls_ssl_conf_session_cache | ( | mbedtls_ssl_config * | conf, |
void * | p_cache, | ||
int(*)(void *, mbedtls_ssl_session *) | f_get_cache, | ||
int(*)(void *, const mbedtls_ssl_session *) | 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.
- Parameters:
-
conf SSL configuration p_cache parmater (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 session tickets (client only).
(Default: MBEDTLS_SSL_SESSION_TICKETS_ENABLED.)
- Note:
- On server, use
mbedtls_ssl_conf_session_tickets_cb()
.
- Parameters:
-
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.)
- Note:
- On server, session tickets are enabled by providing non-NULL callbacks.
-
On client, use
mbedtls_ssl_conf_session_tickets()
.
- Parameters:
-
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
void mbedtls_ssl_conf_sig_hashes | ( | mbedtls_ssl_config * | conf, |
const int * | hashes | ||
) |
Set the allowed hashes for signatures during the handshake.
(Default: all available hashes except MD5.)
- Note:
- This only affects which hashes are offered and can be used for signatures during the handshake. Hashes for message authentication and the TLS PRF are controlled by the ciphersuite, see
mbedtls_ssl_conf_ciphersuites()
. Hashes used for certificate signature are controlled by the verification profile, seembedtls_ssl_conf_cert_profile()
. - This list should be ordered by decreasing preference (preferred hash first).
- Parameters:
-
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 must either set a default cert, or return non-zero to abort the handshake at this point.
- Parameters:
-
conf SSL configuration f_sni verification function p_sni verification parameter
void mbedtls_ssl_conf_transport | ( | mbedtls_ssl_config * | conf, |
int | transport | ||
) |
Set the transport type (TLS or DTLS).
Default: TLS
- Note:
- For DTLS, you must either provide a recv callback that doesn't block, or one that handles timeouts, see
mbedtls_ssl_set_bio()
. You also need to provide timer callbacks withmbedtls_ssl_set_timer_cb()
.
- Parameters:
-
conf SSL configuration transport transport type: MBEDTLS_SSL_TRANSPORT_STREAM for TLS, MBEDTLS_SSL_TRANSPORT_DATAGRAM for DTLS.
void mbedtls_ssl_conf_truncated_hmac | ( | mbedtls_ssl_config * | conf, |
int | truncate | ||
) |
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 mbedtls_x509_crt_verify()
.
- Note:
- For per context callbacks and contexts, please use mbedtls_ssl_set_verify() instead.
- Parameters:
-
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 reasonnable default SSL configuration values.
(You need to call mbedtls_ssl_config_init() first.)
- Parameters:
-
conf SSL configuration context endpoint MBEDTLS_SSL_IS_CLIENT or MBEDTLS_SSL_IS_SERVER transport MBEDTLS_SSL_TRANSPORT_STREAM for TLS, or MBEDTLS_SSL_TRANSPORT_DATAGRAM for DTLS preset a MBEDTLS_SSL_PRESET_XXX value
- Note:
- See
mbedtls_ssl_conf_transport()
for notes on DTLS.
- Returns:
- 0 if successful, or MBEDTLS_ERR_XXX_ALLOC_FAILED on memory allocation error.
void mbedtls_ssl_config_free | ( | mbedtls_ssl_config * | conf ) |
void mbedtls_ssl_config_init | ( | mbedtls_ssl_config * | conf ) |
Initialize an SSL configuration context Just makes the context ready for mbedtls_ssl_config_defaults() or mbedtls_ssl_config_free().
- Note:
- You need to call mbedtls_ssl_config_defaults() unless you manually set all of the relevant fields yourself.
- Parameters:
-
conf SSL configuration context
int mbedtls_ssl_context_load | ( | mbedtls_ssl_context * | ssl, |
const unsigned char * | buf, | ||
size_t | len | ||
) |
Load serialized connection data to an SSL context.
- See also:
- mbedtls_ssl_context_save()
- Warning:
- The same serialized data must never be loaded into more that one context. In order to ensure that, after successfully loading serialized data to an SSL context, you should immediately destroy or invalidate all copies of the serialized data that was loaded. Loading the same data in more than one context would cause severe security failures including but not limited to loss of confidentiality.
- Note:
- Before calling this function, the SSL context must be prepared in one of the two following ways. The first way is to take a context freshly initialised with mbedtls_ssl_init() and call mbedtls_ssl_setup() on it with the same mbedtls_ssl_config structure that was used in the original connection. The second way is to call mbedtls_ssl_session_reset() on a context that was previously prepared as above but used in the meantime. Either way, you must not use the context to perform a handshake between calling mbedtls_ssl_setup() or mbedtls_ssl_session_reset() and calling this function. You may however call other setter functions in that time frame as indicated in the note below.
- Before or after calling this function successfully, you also need to configure some connection-specific callbacks and settings before you can use the connection again (unless they were already set before calling mbedtls_ssl_session_reset() and the values are suitable for the present connection). Specifically, you want to call at least mbedtls_ssl_set_bio() and mbedtls_ssl_set_timer_cb(). All other SSL setter functions are not necessary to call, either because they're only used in handshakes, or because the setting is already saved. You might choose to call them anyway, for example in order to share code between the cases of establishing a new connection and the case of loading an already-established connection.
- If you have new information about the path MTU, you want to call mbedtls_ssl_set_mtu() after calling this function, as otherwise this function would overwrite your newly-configured value with the value that was active when the context was saved.
-
When this function returns an error code, it calls mbedtls_ssl_free() on
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.
- Parameters:
-
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.
- Returns:
0
if successful.- MBEDTLS_ERR_SSL_ALLOC_FAILED if memory allocation failed.
- MBEDTLS_ERR_SSL_VERSION_MISMATCH if the serialized data comes from a different Mbed TLS version or build.
- MBEDTLS_ERR_SSL_BAD_INPUT_DATA if input data is invalid.
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.
- See also:
- mbedtls_ssl_context_load()
- Note:
- This feature is currently only available under certain conditions, see the documentation of the return value MBEDTLS_ERR_SSL_BAD_INPUT_DATA for details.
-
When this function succeeds, it calls mbedtls_ssl_session_reset() on
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.
- Parameters:
-
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 beNULL
ifbuf_len
is0
.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
.
- Note:
olen
is updated to the correct value regardless of whetherbuf_len
was large enough. This makes it possible to determine the necessary size by calling this function withbuf
set toNULL
andbuf_len
to0
. However, the value ofolen
is only guaranteed to be correct when the function returns MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL or0
. If the return value is different, then the value ofolen
is undefined.
- Returns:
0
if successful.-
MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL if
buf
is too small. - MBEDTLS_ERR_SSL_ALLOC_FAILED if memory allocation failed while reseting the context.
- MBEDTLS_ERR_SSL_BAD_INPUT_DATA if a handshake is in progress, or there is pending data for reading or sending, or the connection does not use DTLS 1.2 with an AEAD ciphersuite, or renegotiation is enabled.
void mbedtls_ssl_free | ( | mbedtls_ssl_context * | ssl ) |
const char* mbedtls_ssl_get_alpn_protocol | ( | const mbedtls_ssl_context * | ssl ) |
void* mbedtls_ssl_get_async_operation_data | ( | const mbedtls_ssl_context * | ssl ) |
Retrieve the asynchronous operation user context.
- Note:
- This function may only be called while a handshake is in progress.
- Parameters:
-
ssl The SSL context to access.
- Returns:
- The asynchronous operation user context that was last set during the current handshake. If mbedtls_ssl_set_async_operation_data() has not yet been called during the current handshake, this function returns
NULL
.
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.
- Parameters:
-
ssl SSL context
- Returns:
- How many bytes are available in the application data record read buffer.
- Note:
- When working over a datagram transport, this is useful to detect the current datagram's boundary in case
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 ) |
int mbedtls_ssl_get_ciphersuite_id | ( | const char * | ciphersuite_name ) |
Return the ID of the ciphersuite associated with the given name.
- Parameters:
-
ciphersuite_name SSL ciphersuite name
- Returns:
- the ID with the ciphersuite or 0 if not found
Definition at line 2282 of file ssl_ciphersuites.c.
const char* mbedtls_ssl_get_ciphersuite_name | ( | const int | ciphersuite_id ) |
Return the name of the ciphersuite associated with the given ID.
- Parameters:
-
ciphersuite_id SSL ciphersuite ID
- Returns:
- a string containing the ciphersuite name
Definition at line 2270 of file ssl_ciphersuites.c.
size_t mbedtls_ssl_get_max_frag_len | ( | const mbedtls_ssl_context * | ssl ) |
Return the maximum fragment length (payload, in bytes).
This is the value negotiated with peer if any, or the locally configured value.
- See also:
- mbedtls_ssl_conf_max_frag_len()
- mbedtls_ssl_get_max_record_payload()
- Parameters:
-
ssl SSL context
- Returns:
- Current maximum fragment length.
int mbedtls_ssl_get_max_out_record_payload | ( | const mbedtls_ssl_context * | ssl ) |
Return the current maximum outgoing record payload in bytes.
This takes into account the config.h setting MBEDTLS_SSL_OUT_CONTENT_LEN
, the configured and negotiated max fragment length extension if used, and for DTLS the path MTU as configured and current record expansion.
- Note:
- With DTLS,
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 callmbedtls_ssl_write()
again in order to send the remaining bytes if any. - This function is not available (always returns an error) when record compression is enabled.
- Parameters:
-
ssl SSL context
- Returns:
- Current maximum payload for an outgoing record, or a negative error code.
const mbedtls_x509_crt* mbedtls_ssl_get_peer_cert | ( | const mbedtls_ssl_context * | ssl ) |
Return the peer certificate from the current connection.
- Parameters:
-
ssl The SSL context to use. This must be initialized and setup.
- Returns:
- The current peer certificate, if available. The returned certificate is owned by the SSL context and is valid only until the next call to the SSL API.
-
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.
- Note:
- For one-time inspection of the peer's certificate during the handshake, consider registering an X.509 CRT verification callback through mbedtls_ssl_conf_verify() instead of calling this function. Using mbedtls_ssl_conf_verify() also comes at the benefit of allowing you to influence the verification process, for example by masking expected and tolerated verification failures.
- Warning:
- You must not use the pointer returned by this function after any further call to the SSL API, including mbedtls_ssl_read() and mbedtls_ssl_write(); this is because the pointer might change during renegotiation, which happens transparently to the user. If you want to use the certificate across API calls, you must make a copy.
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.
- Parameters:
-
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 notNULL
,peer_cid_len
must not beNULL
.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 beNULL
in case the length of the peer CID isn't needed. If it isNULL
,peer_cid
must beNULL
, too.
- Note:
- This applies to the state of the CID negotiated in the last complete handshake. If a handshake is in progress, this function will attempt to complete the handshake first.
- If CID extensions have been exchanged but both client and server chose to use an empty CID, this function sets `*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).
- Returns:
0
on success.- A negative error code on failure.
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)
- Note:
- This function is not available (always returns an error) when record compression is enabled.
- Parameters:
-
ssl SSL context
- Returns:
- Current maximum record expansion in bytes, or MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE if compression is enabled, which makes expansion much less predictable
int mbedtls_ssl_get_session | ( | const mbedtls_ssl_context * | ssl, |
mbedtls_ssl_session * | session | ||
) |
Save session in order to resume it later (client-side only) Session data is copied to presented session structure.
- Parameters:
-
ssl SSL context session session context
- Returns:
- 0 if successful, MBEDTLS_ERR_SSL_ALLOC_FAILED if memory allocation failed, MBEDTLS_ERR_SSL_BAD_INPUT_DATA if used server-side or arguments are otherwise invalid.
- Note:
- Only the server certificate is copied, and not the full chain, so you should not attempt to validate the certificate again by calling
mbedtls_x509_crt_verify()
on it. Instead, you should use the results from the verification in the original handshake by callingmbedtls_ssl_get_verify_result()
after loading the session again into a new SSL context usingmbedtls_ssl_set_session()
. -
Once the session object is not needed anymore, you should free it by calling
mbedtls_ssl_session_free()
.
- See also:
- mbedtls_ssl_set_session()
const mbedtls_ssl_session* mbedtls_ssl_get_session_pointer | ( | const mbedtls_ssl_context * | ssl ) |
Get a pointer to the current session structure, for example to serialize it.
- Warning:
- Ownership of the session remains with the SSL context, and the returned pointer is only guaranteed to be valid until the next API call operating on the same
ssl
context.
- See also:
- mbedtls_ssl_session_save()
- Parameters:
-
ssl The SSL context.
- Returns:
- A pointer to the current session if successful.
-
NULL
if no session is active.
uint32_t mbedtls_ssl_get_verify_result | ( | const mbedtls_ssl_context * | ssl ) |
Return the result of the certificate verification.
- Parameters:
-
ssl The SSL context to use.
- Returns:
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. -
A bitwise combination of
MBEDTLS_X509_BADCERT_XXX
andMBEDTLS_X509_BADCRL_XXX
failure flags; see x509.h.
const char* mbedtls_ssl_get_version | ( | const mbedtls_ssl_context * | ssl ) |
int mbedtls_ssl_handshake | ( | mbedtls_ssl_context * | ssl ) |
Perform the SSL handshake.
- Parameters:
-
ssl SSL context
- Returns:
0
if successful.- MBEDTLS_ERR_SSL_WANT_READ or MBEDTLS_ERR_SSL_WANT_WRITE if the handshake is incomplete and waiting for data to be available for reading from or writing to the underlying transport - in this case you must call this function again when the underlying transport is ready for the operation.
- MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS if an asynchronous operation is in progress (see mbedtls_ssl_conf_async_private_cb()) - in this case you must call this function again when the operation is ready.
- MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS if a cryptographic operation is in progress (see mbedtls_ecp_set_max_ops()) - in this case you must call this function again to complete the handshake when you're done attending other tasks.
- MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED if DTLS is in use and the client did not demonstrate reachability yet - in this case you must stop using the context (see below).
- Another SSL error code - in this case you must stop using the context (see below).
- Warning:
- If this function returns something other than
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 callmbedtls_ssl_session_reset()
on it before re-using it for a new connection; the current connection must be closed.
- Note:
- If DTLS is in use, then you may choose to handle MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED specially for logging purposes, as it is an expected return value rather than an actual error, but you still need to reset/free the context.
- Remarks regarding event-driven DTLS: If the function returns MBEDTLS_ERR_SSL_WANT_READ, no datagram from the underlying transport layer is currently being processed, and it is safe to idle until the timer or the underlying transport signal a new event. This is not true for a successful handshake, in which case the datagram of the underlying transport that is currently being processed might or might not contain further DTLS records.
int mbedtls_ssl_handshake_step | ( | mbedtls_ssl_context * | ssl ) |
Perform a single step of the SSL handshake.
- Note:
- The state of the context (ssl->state) will be at the next state after this function returns
0
. Do not call this function if state is MBEDTLS_SSL_HANDSHAKE_OVER.
- Parameters:
-
ssl SSL context
- Returns:
- See mbedtls_ssl_handshake().
- Warning:
- If this function returns something other than
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 callmbedtls_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()
- Parameters:
-
ssl SSL context
int mbedtls_ssl_read | ( | mbedtls_ssl_context * | ssl, |
unsigned char * | buf, | ||
size_t | len | ||
) |
Read at most 'len' application data bytes.
- Parameters:
-
ssl SSL context buf buffer that will hold the data len maximum number of bytes to read
- Returns:
- The (positive) number of bytes read if successful.
-
0
if the read end of the underlying transport was closed- in this case you must stop using the context (see below).
- MBEDTLS_ERR_SSL_WANT_READ or MBEDTLS_ERR_SSL_WANT_WRITE if the handshake is incomplete and waiting for data to be available for reading from or writing to the underlying transport - in this case you must call this function again when the underlying transport is ready for the operation.
- MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS if an asynchronous operation is in progress (see mbedtls_ssl_conf_async_private_cb()) - in this case you must call this function again when the operation is ready.
- MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS if a cryptographic operation is in progress (see mbedtls_ecp_set_max_ops()) - in this case you must call this function again to complete the handshake when you're done attending other tasks.
- MBEDTLS_ERR_SSL_CLIENT_RECONNECT if we're at the server side of a DTLS connection and the client is initiating a new connection using the same source port. See below.
- Another SSL error code - in this case you must stop using the context (see below).
- Warning:
- If this function returns something other than a positive value, 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_CLIENT_RECONNECT, 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.
- Note:
- When this function returns MBEDTLS_ERR_SSL_CLIENT_RECONNECT (which can only happen server-side), it means that a client is initiating a new connection using the same source port. You can either treat that as a connection close and wait for the client to resend a ClientHello, or directly continue with
mbedtls_ssl_handshake()
with the same context (as it has 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! -
Remarks regarding event-driven DTLS:
- If the function returns MBEDTLS_ERR_SSL_WANT_READ, no datagram from the underlying transport layer is currently being processed, and it is safe to idle until the timer or the underlying transport signal a new event.
- This function may return MBEDTLS_ERR_SSL_WANT_READ even if data was initially available on the underlying transport, as this data may have been only e.g. duplicated messages or a renegotiation request. Therefore, you must be prepared to receive MBEDTLS_ERR_SSL_WANT_READ even when reacting to an incoming-data event from the underlying transport.
- On success, the datagram of the underlying transport that is currently being processed may contain further DTLS records. You should call
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.
- Parameters:
-
ssl SSL context
- Returns:
- 0 if successful, or any mbedtls_ssl_handshake() return value except MBEDTLS_ERR_SSL_CLIENT_RECONNECT that can't happen during a renegotiation.
- Warning:
- If this function returns something other than
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 callmbedtls_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.
- Parameters:
-
ssl SSL context level The alert level of the message (MBEDTLS_SSL_ALERT_LEVEL_WARNING or MBEDTLS_SSL_ALERT_LEVEL_FATAL) message The alert message (SSL_ALERT_MSG_*)
- Returns:
- 0 if successful, or a specific SSL error code.
- Note:
- If this function returns something other than 0 or MBEDTLS_ERR_SSL_WANT_READ/WRITE, 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_session_free | ( | mbedtls_ssl_session * | session ) |
void mbedtls_ssl_session_init | ( | mbedtls_ssl_session * | 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 mbedstls_ssl_set_session(). On server, this can be used for alternative implementations of session cache or session tickets.
- Warning:
- If a peer certificate chain is associated with the session, the serialized state will only contain the peer's end-entity certificate and the result of the chain verification (unless verification was disabled), but not the rest of the chain.
- Parameters:
-
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.
- Returns:
0
if successful.- MBEDTLS_ERR_SSL_ALLOC_FAILED if memory allocation failed.
- MBEDTLS_ERR_SSL_BAD_INPUT_DATA if input data is invalid.
- MBEDTLS_ERR_SSL_VERSION_MISMATCH if the serialized data was generated in a different version or configuration of Mbed TLS.
- Another negative value for other kinds of errors (for example, unsupported features in the embedded certificate).
int mbedtls_ssl_session_reset | ( | mbedtls_ssl_context * | ssl ) |
Reset an already initialized SSL context for re-use while retaining application-set variables, function pointers and data.
- Parameters:
-
ssl SSL context
- Returns:
- 0 if successful, or MBEDTLS_ERR_SSL_ALLOC_FAILED, MBEDTLS_ERR_SSL_HW_ACCEL_FAILED or MBEDTLS_ERR_SSL_COMPRESSION_FAILED
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.
- Parameters:
-
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 len
bytes, or may beNULL
iflen
is0
.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
.
- Note:
olen
is updated to the correct value regardless of whetherbuf_len
was large enough. This makes it possible to determine the necessary size by calling this function withbuf
set toNULL
andbuf_len
to0
.
- Returns:
0
if successful.-
MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL if
buf
is too small.
void mbedtls_ssl_set_async_operation_data | ( | mbedtls_ssl_context * | ssl, |
void * | ctx | ||
) |
Retrieve the asynchronous operation user context.
- Note:
- This function may only be called while a handshake is in progress.
- Parameters:
-
ssl The SSL context to access. ctx The new value of the asynchronous operation user context. Call mbedtls_ssl_get_async_operation_data() later during the same handshake to retrieve this value.
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.
- Parameters:
-
ssl SSL context p_bio parameter (context) shared by BIO callbacks f_send write callback f_recv read callback f_recv_timeout blocking read callback with timeout.
- Note:
- One of f_recv or f_recv_timeout can be NULL, in which case the other is used. If both are non-NULL, f_recv_timeout is used and f_recv is ignored (as if it were NULL).
-
The two most common use cases are:
- non-blocking I/O, f_recv != NULL, f_recv_timeout == NULL
- blocking I/O, f_recv == NULL, f_recv_timout != NULL
- For DTLS, you need to provide either a non-NULL f_recv_timeout callback, or a f_recv that doesn't block.
-
See the documentations of
mbedtls_ssl_sent_t
,mbedtls_ssl_recv_t
andmbedtls_ssl_recv_timeout_t
for the conventions those callbacks must follow. -
On some platforms, net_sockets.c provides
mbedtls_net_send()
,mbedtls_net_recv()
andmbedtls_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: draft-ietf-tls-dtls-connection-id-05 https://tools.ietf.org/html/draft-ietf-tls-dtls-connection-id-05
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.
- Parameters:
-
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: - MBEDTLS_SSL_CID_ENABLED to enable the use of the CID.
- MBEDTLS_SSL_CID_DISABLED (default) to disable the use of the CID.
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
ifown_cid_len
is0
. This parameter is unused ifenabled
is set to MBEDTLS_SSL_CID_DISABLED.own_cid_len The length of own_cid
. This parameter is unused ifenabled
is set to MBEDTLS_SSL_CID_DISABLED.
- Note:
- The value of
own_cid_len
must match the value of thelen
parameter passed to mbedtls_ssl_conf_cid() when configuring the mbedtls_ssl_config thatssl
is bound to. -
This CID configuration applies to subsequent handshakes performed on the SSL context
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. -
This call cannot guarantee that the use of the CID will be successfully negotiated in the next handshake, because the peer might not support it. Specifically:
- On the Client, enabling the use of the CID through this call implies that the `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.
- On the Server, enabling the use of the CID through this call implies that that the server will look for the CID extension in a `ClientHello` from the client, and, if present, reply with a CID extension in its `ServerHello`.
- To check whether the use of the CID was negotiated after the subsequent handshake has completed, please use the API mbedtls_ssl_get_peer_cid().
- Warning:
- If the use of the CID extension is enabled in this call and the subsequent handshake negotiates its use, Mbed TLS will silently drop every packet whose CID does not match the CID configured in
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.
- Returns:
0
on success. In this case, the CID configuration applies to the next handshake.- A negative error code on failure.
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.
- Parameters:
-
ssl SSL context info Transport-level info identifying the client (eg IP + port) ilen Length of info in bytes
- Note:
- An internal copy is made, so the info buffer can be reused.
- Returns:
- 0 on success, MBEDTLS_ERR_SSL_BAD_INPUT_DATA if used on client, MBEDTLS_ERR_SSL_ALLOC_FAILED if out of memory.
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.
- Parameters:
-
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 of1
means that, if space permits, multiple handshake messages (including CCS) belonging to a single flight may be packed within a single datagram.
- Note:
- This is enabled by default and should only be disabled for test purposes, or if datagram packing causes interoperability issues with peers that don't support it.
- Allowing datagram packing reduces the network load since there's less overhead if multiple messages share the same datagram. Also, it increases the handshake efficiency since messages belonging to a single datagram will not be reordered in transit, and so future message buffering or flight retransmission (if no buffering is used) as means to deal with reordering are needed less frequently.
- Application records are not affected by this option and are currently always sent in separate datagrams.
int mbedtls_ssl_set_hostname | ( | mbedtls_ssl_context * | ssl, |
const char * | hostname | ||
) |
Set or reset the hostname to check against the received server certificate.
It sets the ServerName TLS extension, too, if that extension is enabled. (client-side only)
- Parameters:
-
ssl SSL context hostname the server hostname, may be NULL to clear hostname
- Note:
- Maximum hostname length MBEDTLS_SSL_MAX_HOST_NAME_LEN.
- Returns:
- 0 if successful, MBEDTLS_ERR_SSL_ALLOC_FAILED on allocation failure, MBEDTLS_ERR_SSL_BAD_INPUT_DATA on too long input hostname.
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.
- Note:
- Same as
mbedtls_ssl_conf_authmode()
but for use within the SNI callback.
- Parameters:
-
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.
- Note:
- Same as
mbedtls_ssl_conf_ca_chain()
but for use within the SNI callback.
- Parameters:
-
ssl SSL context ca_chain trusted CA chain (meaning all fully trusted top-level CAs) ca_crl trusted CA CRLs
int mbedtls_ssl_set_hs_ecjpake_password | ( | mbedtls_ssl_context * | ssl, |
const unsigned char * | pw, | ||
size_t | pw_len | ||
) |
Set the EC J-PAKE password for current handshake.
- Note:
- An internal copy is made, and destroyed as soon as the handshake is completed, or when the SSL context is reset or freed.
-
The SSL context needs to be already set up. The right place to call this function is between
mbedtls_ssl_setup()
ormbedtls_ssl_reset()
andmbedtls_ssl_handshake()
.
- Parameters:
-
ssl SSL context pw EC J-PAKE password (pre-shared secret) pw_len length of pw in bytes
- Returns:
- 0 on success, or a negative error code.
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.
- Note:
- Same as
mbedtls_ssl_conf_own_cert()
but for use within the SNI callback.
- Parameters:
-
ssl SSL context own_cert own public certificate chain pk_key own private key
- Returns:
- 0 on success or MBEDTLS_ERR_SSL_ALLOC_FAILED
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.
- Note:
- This should only be called inside the PSK callback, i.e. the function passed to
mbedtls_ssl_conf_psk_cb()
.
- Parameters:
-
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.
- Returns:
0
if successful.-
An
MBEDTLS_ERR_SSL_XXX
error code on failure.
int mbedtls_ssl_set_hs_psk_opaque | ( | mbedtls_ssl_context * | ssl, |
psa_key_handle_t | psk | ||
) |
Set an opaque pre-shared Key (PSK) for the current handshake.
- Note:
- This should only be called inside the PSK callback, i.e. the function passed to
mbedtls_ssl_conf_psk_cb()
.
- Parameters:
-
ssl The SSL context to configure a PSK for. psk The identifier of the key slot holding the PSK. For the duration of the current handshake, the key slot must be populated with a key of type PSA_ALG_CATEGORY_KEY_DERIVATION whose policy allows its use for the key derivation algorithm applied in the handshake.
- Returns:
0
if successful.-
An
MBEDTLS_ERR_SSL_XXX
error code on failure.
void mbedtls_ssl_set_mtu | ( | mbedtls_ssl_context * | ssl, |
uint16_t | mtu | ||
) |
Set the Maximum Tranport 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()
.
- Note:
- The limit on datagram size is converted to a limit on record payload by subtracting the current overhead of encapsulation and encryption/authentication if any.
- This can be called at any point during the connection, for example when a Path Maximum Transfer Unit (PMTU) estimate becomes available from other sources, such as lower (or higher) protocol layers.
-
This setting only controls the size of the packets we send, and does not restrict the size of the datagrams we're willing to receive. Client-side, you can request the server to use smaller records with
mbedtls_ssl_conf_max_frag_len()
. - If both a MTU and a maximum fragment length have been configured (or negotiated with the peer), the resulting lower limit on record payload (see first note) is used.
- This can only be used to decrease the maximum size of datagrams (hence records, see first note) sent. It cannot be used to increase the maximum size of records over the limit set by MBEDTLS_SSL_OUT_CONTENT_LEN.
- Values lower than the current record layer expansion will result in an error when trying to send data.
- Using record compression together with a non-zero MTU value will result in an error when trying to send data.
- Parameters:
-
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 | ||
) |
Request resumption of session (client-side only) Session data is copied from presented session structure.
- Parameters:
-
ssl SSL context session session context
- Returns:
- 0 if successful, MBEDTLS_ERR_SSL_ALLOC_FAILED if memory allocation failed, MBEDTLS_ERR_SSL_BAD_INPUT_DATA if used server-side or arguments are otherwise invalid
- See also:
- mbedtls_ssl_get_session()
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.)
- Parameters:
-
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:
- Note:
- See the documentation of
mbedtls_ssl_set_timer_t
andmbedtls_ssl_get_timer_t
for the conventions this pair of callbacks must follow. -
On some platforms, timing.c provides
mbedtls_timing_set_delay()
andmbedtls_timing_get_delay()
that are suitable for using here, except if using an event-driven style. - See also the "DTLS tutorial" article in our knowledge base. https://tls.mbed.org/kb/how-to/dtls-tutorial
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 mbedtls_x509_crt_verify()
.
- Note:
- This call is analogous to mbedtls_ssl_conf_verify() but binds the verification callback and context to an SSL context as opposed to an SSL configuration. If mbedtls_ssl_conf_verify() and mbedtls_ssl_set_verify() are both used, mbedtls_ssl_set_verify() takes precedence.
- Parameters:
-
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.
- Note:
- No copy of the configuration context is made, it can be shared by many mbedtls_ssl_context structures.
- Warning:
- The conf structure will be accessed during the session. It must not be modified or freed as long as the session is active.
- This function must be called exactly once per context. Calling mbedtls_ssl_setup again is not supported, even if no session is active.
- Parameters:
-
ssl SSL context conf SSL configuration to use
- Returns:
- 0 if successful, or MBEDTLS_ERR_SSL_ALLOC_FAILED if memory allocation failed
int mbedtls_ssl_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.
- Parameters:
-
prf The tls_prf type funtion 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.
- Returns:
- 0 on sucess. An SSL specific error on failure.
int mbedtls_ssl_write | ( | mbedtls_ssl_context * | ssl, |
const unsigned char * | buf, | ||
size_t | len | ||
) |
Try to write exactly 'len' application data bytes.
- Warning:
- This function will do partial writes in some cases. If the return value is non-negative but less than length, the function must be called again with updated arguments: buf + ret, len - ret (if ret is the return value) until it returns a value equal to the last 'len' argument.
- Parameters:
-
ssl SSL context buf buffer holding the data len how many bytes must be written
- Returns:
- The (non-negative) number of bytes actually written if successful (may be less than
len
). - MBEDTLS_ERR_SSL_WANT_READ or MBEDTLS_ERR_SSL_WANT_WRITE if the handshake is incomplete and waiting for data to be available for reading from or writing to the underlying transport - in this case you must call this function again when the underlying transport is ready for the operation.
- MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS if an asynchronous operation is in progress (see mbedtls_ssl_conf_async_private_cb()) - in this case you must call this function again when the operation is ready.
- MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS if a cryptographic operation is in progress (see mbedtls_ecp_set_max_ops()) - in this case you must call this function again to complete the handshake when you're done attending other tasks.
- Another SSL error code - in this case you must stop using the context (see below).
- Warning:
- If this function returns something other than a non-negative value, 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.
- Note:
- When this function returns MBEDTLS_ERR_SSL_WANT_WRITE/READ, it must be called later with the *same* arguments, until it returns a value greater that or equal to 0. When the function returns MBEDTLS_ERR_SSL_WANT_WRITE there may be some partial data in the output buffer, however this is not yet sent.
-
If the requested length is greater than the maximum fragment length (either the built-in limit or the one set or negotiated with the peer), then:
- with TLS, less bytes than requested are written.
- with DTLS, MBEDTLS_ERR_SSL_BAD_INPUT_DATA is returned.
mbedtls_ssl_get_max_frag_len()
may be used to query the active maximum fragment length.
- Attempting to write 0 bytes will result in an empty TLS application record being sent.
Generated on Tue Jul 12 2022 13:55:19 by
