File ssl.h
SSL/TLS functions.
Defines
-
MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS
A cryptographic operation is in progress. Try again later.
-
MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE
The requested feature is not available.
-
MBEDTLS_ERR_SSL_BAD_INPUT_DATA
Bad input parameters to function.
-
MBEDTLS_ERR_SSL_INVALID_MAC
Verification of the message MAC failed.
-
MBEDTLS_ERR_SSL_INVALID_RECORD
An invalid SSL record was received.
-
MBEDTLS_ERR_SSL_CONN_EOF
The connection indicated an EOF.
-
MBEDTLS_ERR_SSL_DECODE_ERROR
A message could not be parsed due to a syntactic error.
-
MBEDTLS_ERR_SSL_NO_RNG
No RNG was provided to the SSL module.
-
MBEDTLS_ERR_SSL_NO_CLIENT_CERTIFICATE
No client certification received from the client, but required by the authentication mode.
-
MBEDTLS_ERR_SSL_UNSUPPORTED_EXTENSION
Client received an extended server hello containing an unsupported extension
-
MBEDTLS_ERR_SSL_NO_APPLICATION_PROTOCOL
No ALPN protocols supported that the client advertises
-
MBEDTLS_ERR_SSL_PRIVATE_KEY_REQUIRED
The own private key or pre-shared key is not set, but needed.
-
MBEDTLS_ERR_SSL_CA_CHAIN_REQUIRED
No CA Chain is set, but required to operate.
-
MBEDTLS_ERR_SSL_UNEXPECTED_MESSAGE
An unexpected message was received from our peer.
-
MBEDTLS_ERR_SSL_FATAL_ALERT_MESSAGE
A fatal alert message was received from our peer.
-
MBEDTLS_ERR_SSL_UNRECOGNIZED_NAME
No server could be identified matching the client’s SNI.
-
MBEDTLS_ERR_SSL_PEER_CLOSE_NOTIFY
The peer notified us that the connection is going to be closed.
-
MBEDTLS_ERR_SSL_BAD_CERTIFICATE
Processing of the Certificate handshake message failed.
-
MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET
Received NewSessionTicket Post Handshake Message. This error code is experimental and may be changed or removed without notice.
-
MBEDTLS_ERR_SSL_CANNOT_READ_EARLY_DATA
Not possible to read early data
-
MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA
Early data has been received as part of an on-going handshake. This error code can be returned only on server side if and only if early data has been enabled by means of the mbedtls_ssl_conf_early_data() API. This error code can then be returned by mbedtls_ssl_handshake(), mbedtls_ssl_handshake_step(), mbedtls_ssl_read() or mbedtls_ssl_write() if early data has been received as part of the handshake sequence they triggered. To read the early data, call mbedtls_ssl_read_early_data().
-
MBEDTLS_ERR_SSL_CANNOT_WRITE_EARLY_DATA
Not possible to write early data
-
MBEDTLS_ERR_SSL_CACHE_ENTRY_NOT_FOUND
Cache entry not found
-
MBEDTLS_ERR_SSL_ALLOC_FAILED
Memory allocation failed
-
MBEDTLS_ERR_SSL_HW_ACCEL_FAILED
Hardware acceleration function returned with error
-
MBEDTLS_ERR_SSL_HW_ACCEL_FALLTHROUGH
Hardware acceleration function skipped / left alone data
-
MBEDTLS_ERR_SSL_BAD_PROTOCOL_VERSION
Handshake protocol not within min/max boundaries
-
MBEDTLS_ERR_SSL_HANDSHAKE_FAILURE
The handshake negotiation failed.
-
MBEDTLS_ERR_SSL_SESSION_TICKET_EXPIRED
Session ticket has expired.
-
MBEDTLS_ERR_SSL_PK_TYPE_MISMATCH
Public key type mismatch (eg, asked for RSA key exchange and presented EC key)
-
MBEDTLS_ERR_SSL_UNKNOWN_IDENTITY
Unknown identity received (eg, PSK identity)
-
MBEDTLS_ERR_SSL_INTERNAL_ERROR
Internal error (eg, unexpected failure in lower-level module)
-
MBEDTLS_ERR_SSL_COUNTER_WRAPPING
A counter would wrap (eg, too many messages exchanged).
-
MBEDTLS_ERR_SSL_WAITING_SERVER_HELLO_RENEGO
Unexpected message at ServerHello in renegotiation.
-
MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED
DTLS client must retry for hello verification
-
MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL
A buffer is too small to receive or write a message
-
MBEDTLS_ERR_SSL_WANT_READ
No data of requested type currently available on underlying transport.
-
MBEDTLS_ERR_SSL_WANT_WRITE
Connection requires a write call.
-
MBEDTLS_ERR_SSL_TIMEOUT
The operation timed out.
-
MBEDTLS_ERR_SSL_CLIENT_RECONNECT
The client initiated a reconnect from the same port.
-
MBEDTLS_ERR_SSL_UNEXPECTED_RECORD
Record header looks valid but is not expected.
-
MBEDTLS_ERR_SSL_NON_FATAL
The alert message received indicates a non-fatal error.
-
MBEDTLS_ERR_SSL_ILLEGAL_PARAMETER
A field in a message was incorrect or inconsistent with other fields.
-
MBEDTLS_ERR_SSL_CONTINUE_PROCESSING
Internal-only message signaling that further message-processing should be done
-
MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS
The asynchronous operation is not completed yet.
-
MBEDTLS_ERR_SSL_EARLY_MESSAGE
Internal-only message signaling that a message arrived early.
-
MBEDTLS_ERR_SSL_UNEXPECTED_CID
An encrypted DTLS-frame with an unexpected CID was received.
-
MBEDTLS_ERR_SSL_VERSION_MISMATCH
An operation failed due to an unexpected version or configuration.
-
MBEDTLS_ERR_SSL_BAD_CONFIG
Invalid value in SSL config
-
MBEDTLS_SSL_TLS1_3_PSK_MODE_PURE
-
MBEDTLS_SSL_TLS1_3_PSK_MODE_ECDHE
-
MBEDTLS_SSL_IANA_TLS_GROUP_NONE
-
MBEDTLS_SSL_IANA_TLS_GROUP_SECP192K1
-
MBEDTLS_SSL_IANA_TLS_GROUP_SECP192R1
-
MBEDTLS_SSL_IANA_TLS_GROUP_SECP224K1
-
MBEDTLS_SSL_IANA_TLS_GROUP_SECP224R1
-
MBEDTLS_SSL_IANA_TLS_GROUP_SECP256K1
-
MBEDTLS_SSL_IANA_TLS_GROUP_SECP256R1
-
MBEDTLS_SSL_IANA_TLS_GROUP_SECP384R1
-
MBEDTLS_SSL_IANA_TLS_GROUP_SECP521R1
-
MBEDTLS_SSL_IANA_TLS_GROUP_BP256R1
-
MBEDTLS_SSL_IANA_TLS_GROUP_BP384R1
-
MBEDTLS_SSL_IANA_TLS_GROUP_BP512R1
-
MBEDTLS_SSL_IANA_TLS_GROUP_X25519
-
MBEDTLS_SSL_IANA_TLS_GROUP_X448
-
MBEDTLS_SSL_IANA_TLS_GROUP_FFDHE2048
-
MBEDTLS_SSL_IANA_TLS_GROUP_FFDHE3072
-
MBEDTLS_SSL_IANA_TLS_GROUP_FFDHE4096
-
MBEDTLS_SSL_IANA_TLS_GROUP_FFDHE6144
-
MBEDTLS_SSL_IANA_TLS_GROUP_FFDHE8192
-
MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK
Pure-PSK TLS 1.3 key exchange, encompassing both externally agreed PSKs as well as resumption PSKs.
-
MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL
Pure-Ephemeral TLS 1.3 key exchanges, including for example ECDHE and DHE key exchanges.
-
MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL
PSK-Ephemeral TLS 1.3 key exchanges, using both a PSK and an ephemeral key exchange.
-
MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_ALL
All TLS 1.3 key exchanges
-
MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_ALL
All PSK-based TLS 1.3 key exchanges
-
MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL_ALL
All ephemeral TLS 1.3 key exchanges
-
MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_NONE
-
MBEDTLS_SSL_TRANSPORT_STREAM
TLS
-
MBEDTLS_SSL_TRANSPORT_DATAGRAM
DTLS
-
MBEDTLS_SSL_MAX_HOST_NAME_LEN
Maximum host name defined in RFC 1035
-
MBEDTLS_SSL_MAX_ALPN_NAME_LEN
Maximum size in bytes of a protocol name in alpn ext., RFC 7301
-
MBEDTLS_SSL_MAX_ALPN_LIST_LEN
Maximum size in bytes of list in alpn ext., RFC 7301
-
MBEDTLS_SSL_MAX_FRAG_LEN_NONE
don’t use this extension
-
MBEDTLS_SSL_MAX_FRAG_LEN_512
MaxFragmentLength 2^9
-
MBEDTLS_SSL_MAX_FRAG_LEN_1024
MaxFragmentLength 2^10
-
MBEDTLS_SSL_MAX_FRAG_LEN_2048
MaxFragmentLength 2^11
-
MBEDTLS_SSL_MAX_FRAG_LEN_4096
MaxFragmentLength 2^12
-
MBEDTLS_SSL_MAX_FRAG_LEN_INVALID
first invalid value
-
MBEDTLS_SSL_IS_CLIENT
-
MBEDTLS_SSL_IS_SERVER
-
MBEDTLS_SSL_EXTENDED_MS_DISABLED
-
MBEDTLS_SSL_EXTENDED_MS_ENABLED
-
MBEDTLS_SSL_CID_DISABLED
-
MBEDTLS_SSL_CID_ENABLED
-
MBEDTLS_SSL_ETM_DISABLED
-
MBEDTLS_SSL_ETM_ENABLED
-
MBEDTLS_SSL_COMPRESS_NULL
-
MBEDTLS_SSL_VERIFY_NONE
-
MBEDTLS_SSL_VERIFY_OPTIONAL
-
MBEDTLS_SSL_VERIFY_REQUIRED
-
MBEDTLS_SSL_VERIFY_UNSET
-
MBEDTLS_SSL_LEGACY_RENEGOTIATION
-
MBEDTLS_SSL_SECURE_RENEGOTIATION
-
MBEDTLS_SSL_RENEGOTIATION_DISABLED
-
MBEDTLS_SSL_RENEGOTIATION_ENABLED
-
MBEDTLS_SSL_ANTI_REPLAY_DISABLED
-
MBEDTLS_SSL_ANTI_REPLAY_ENABLED
-
MBEDTLS_SSL_RENEGOTIATION_NOT_ENFORCED
-
MBEDTLS_SSL_RENEGO_MAX_RECORDS_DEFAULT
-
MBEDTLS_SSL_LEGACY_NO_RENEGOTIATION
-
MBEDTLS_SSL_LEGACY_ALLOW_RENEGOTIATION
-
MBEDTLS_SSL_LEGACY_BREAK_HANDSHAKE
-
MBEDTLS_SSL_TRUNC_HMAC_DISABLED
-
MBEDTLS_SSL_TRUNC_HMAC_ENABLED
-
MBEDTLS_SSL_TRUNCATED_HMAC_LEN
-
MBEDTLS_SSL_SESSION_TICKETS_DISABLED
-
MBEDTLS_SSL_SESSION_TICKETS_ENABLED
-
MBEDTLS_SSL_PRESET_DEFAULT
-
MBEDTLS_SSL_PRESET_SUITEB
-
MBEDTLS_SSL_CERT_REQ_CA_LIST_ENABLED
-
MBEDTLS_SSL_CERT_REQ_CA_LIST_DISABLED
-
MBEDTLS_SSL_EARLY_DATA_DISABLED
-
MBEDTLS_SSL_EARLY_DATA_ENABLED
-
MBEDTLS_SSL_DTLS_SRTP_MKI_UNSUPPORTED
-
MBEDTLS_SSL_DTLS_SRTP_MKI_SUPPORTED
-
MBEDTLS_SSL_SRV_CIPHERSUITE_ORDER_CLIENT
-
MBEDTLS_SSL_SRV_CIPHERSUITE_ORDER_SERVER
-
MBEDTLS_SSL_TLS1_3_TICKET_RESUMPTION_KEY_LEN
-
MBEDTLS_SSL_DTLS_TIMEOUT_DFL_MIN
-
MBEDTLS_SSL_DTLS_TIMEOUT_DFL_MAX
-
MBEDTLS_SSL_EARLY_DATA_NO_DISCARD
-
MBEDTLS_SSL_EARLY_DATA_TRY_TO_DEPROTECT_AND_DISCARD
-
MBEDTLS_SSL_EARLY_DATA_DISCARD
-
MBEDTLS_SSL_VERIFY_DATA_MAX_LEN
-
MBEDTLS_SSL_EMPTY_RENEGOTIATION_INFO
renegotiation info ext
-
MBEDTLS_SSL_HASH_NONE
-
MBEDTLS_SSL_HASH_MD5
-
MBEDTLS_SSL_HASH_SHA1
-
MBEDTLS_SSL_HASH_SHA224
-
MBEDTLS_SSL_HASH_SHA256
-
MBEDTLS_SSL_HASH_SHA384
-
MBEDTLS_SSL_HASH_SHA512
-
MBEDTLS_SSL_SIG_ANON
-
MBEDTLS_SSL_SIG_RSA
-
MBEDTLS_SSL_SIG_ECDSA
-
MBEDTLS_TLS1_3_SIG_RSA_PKCS1_SHA256
-
MBEDTLS_TLS1_3_SIG_RSA_PKCS1_SHA384
-
MBEDTLS_TLS1_3_SIG_RSA_PKCS1_SHA512
-
MBEDTLS_TLS1_3_SIG_ECDSA_SECP256R1_SHA256
-
MBEDTLS_TLS1_3_SIG_ECDSA_SECP384R1_SHA384
-
MBEDTLS_TLS1_3_SIG_ECDSA_SECP521R1_SHA512
-
MBEDTLS_TLS1_3_SIG_RSA_PSS_RSAE_SHA256
-
MBEDTLS_TLS1_3_SIG_RSA_PSS_RSAE_SHA384
-
MBEDTLS_TLS1_3_SIG_RSA_PSS_RSAE_SHA512
-
MBEDTLS_TLS1_3_SIG_ED25519
-
MBEDTLS_TLS1_3_SIG_ED448
-
MBEDTLS_TLS1_3_SIG_RSA_PSS_PSS_SHA256
-
MBEDTLS_TLS1_3_SIG_RSA_PSS_PSS_SHA384
-
MBEDTLS_TLS1_3_SIG_RSA_PSS_PSS_SHA512
-
MBEDTLS_TLS1_3_SIG_RSA_PKCS1_SHA1
-
MBEDTLS_TLS1_3_SIG_ECDSA_SHA1
-
MBEDTLS_TLS1_3_SIG_NONE
-
MBEDTLS_SSL_CERT_TYPE_RSA_SIGN
-
MBEDTLS_SSL_CERT_TYPE_ECDSA_SIGN
-
MBEDTLS_SSL_MSG_CHANGE_CIPHER_SPEC
-
MBEDTLS_SSL_MSG_ALERT
-
MBEDTLS_SSL_MSG_HANDSHAKE
-
MBEDTLS_SSL_MSG_APPLICATION_DATA
-
MBEDTLS_SSL_MSG_CID
-
MBEDTLS_SSL_ALERT_LEVEL_WARNING
-
MBEDTLS_SSL_ALERT_LEVEL_FATAL
-
MBEDTLS_SSL_ALERT_MSG_CLOSE_NOTIFY
-
MBEDTLS_SSL_ALERT_MSG_UNEXPECTED_MESSAGE
-
MBEDTLS_SSL_ALERT_MSG_BAD_RECORD_MAC
-
MBEDTLS_SSL_ALERT_MSG_DECRYPTION_FAILED
-
MBEDTLS_SSL_ALERT_MSG_RECORD_OVERFLOW
-
MBEDTLS_SSL_ALERT_MSG_DECOMPRESSION_FAILURE
-
MBEDTLS_SSL_ALERT_MSG_HANDSHAKE_FAILURE
-
MBEDTLS_SSL_ALERT_MSG_NO_CERT
-
MBEDTLS_SSL_ALERT_MSG_BAD_CERT
-
MBEDTLS_SSL_ALERT_MSG_UNSUPPORTED_CERT
-
MBEDTLS_SSL_ALERT_MSG_CERT_REVOKED
-
MBEDTLS_SSL_ALERT_MSG_CERT_EXPIRED
-
MBEDTLS_SSL_ALERT_MSG_CERT_UNKNOWN
-
MBEDTLS_SSL_ALERT_MSG_ILLEGAL_PARAMETER
-
MBEDTLS_SSL_ALERT_MSG_UNKNOWN_CA
-
MBEDTLS_SSL_ALERT_MSG_ACCESS_DENIED
-
MBEDTLS_SSL_ALERT_MSG_DECODE_ERROR
-
MBEDTLS_SSL_ALERT_MSG_DECRYPT_ERROR
-
MBEDTLS_SSL_ALERT_MSG_EXPORT_RESTRICTION
-
MBEDTLS_SSL_ALERT_MSG_PROTOCOL_VERSION
-
MBEDTLS_SSL_ALERT_MSG_INSUFFICIENT_SECURITY
-
MBEDTLS_SSL_ALERT_MSG_INTERNAL_ERROR
-
MBEDTLS_SSL_ALERT_MSG_INAPROPRIATE_FALLBACK
-
MBEDTLS_SSL_ALERT_MSG_USER_CANCELED
-
MBEDTLS_SSL_ALERT_MSG_NO_RENEGOTIATION
-
MBEDTLS_SSL_ALERT_MSG_MISSING_EXTENSION
-
MBEDTLS_SSL_ALERT_MSG_UNSUPPORTED_EXT
-
MBEDTLS_SSL_ALERT_MSG_UNRECOGNIZED_NAME
-
MBEDTLS_SSL_ALERT_MSG_UNKNOWN_PSK_IDENTITY
-
MBEDTLS_SSL_ALERT_MSG_CERT_REQUIRED
-
MBEDTLS_SSL_ALERT_MSG_NO_APPLICATION_PROTOCOL
-
MBEDTLS_SSL_HS_HELLO_REQUEST
-
MBEDTLS_SSL_HS_CLIENT_HELLO
-
MBEDTLS_SSL_HS_SERVER_HELLO
-
MBEDTLS_SSL_HS_HELLO_VERIFY_REQUEST
-
MBEDTLS_SSL_HS_NEW_SESSION_TICKET
-
MBEDTLS_SSL_HS_END_OF_EARLY_DATA
-
MBEDTLS_SSL_HS_ENCRYPTED_EXTENSIONS
-
MBEDTLS_SSL_HS_CERTIFICATE
-
MBEDTLS_SSL_HS_SERVER_KEY_EXCHANGE
-
MBEDTLS_SSL_HS_CERTIFICATE_REQUEST
-
MBEDTLS_SSL_HS_SERVER_HELLO_DONE
-
MBEDTLS_SSL_HS_CERTIFICATE_VERIFY
-
MBEDTLS_SSL_HS_CLIENT_KEY_EXCHANGE
-
MBEDTLS_SSL_HS_FINISHED
-
MBEDTLS_SSL_HS_MESSAGE_HASH
-
MBEDTLS_TLS_EXT_SERVERNAME
-
MBEDTLS_TLS_EXT_SERVERNAME_HOSTNAME
-
MBEDTLS_TLS_EXT_MAX_FRAGMENT_LENGTH
-
MBEDTLS_TLS_EXT_TRUNCATED_HMAC
-
MBEDTLS_TLS_EXT_STATUS_REQUEST
-
MBEDTLS_TLS_EXT_SUPPORTED_ELLIPTIC_CURVES
-
MBEDTLS_TLS_EXT_SUPPORTED_GROUPS
-
MBEDTLS_TLS_EXT_SUPPORTED_POINT_FORMATS
-
MBEDTLS_TLS_EXT_SIG_ALG
-
MBEDTLS_TLS_EXT_USE_SRTP
-
MBEDTLS_TLS_EXT_HEARTBEAT
-
MBEDTLS_TLS_EXT_ALPN
-
MBEDTLS_TLS_EXT_SCT
-
MBEDTLS_TLS_EXT_CLI_CERT_TYPE
-
MBEDTLS_TLS_EXT_SERV_CERT_TYPE
-
MBEDTLS_TLS_EXT_PADDING
-
MBEDTLS_TLS_EXT_ENCRYPT_THEN_MAC
-
MBEDTLS_TLS_EXT_EXTENDED_MASTER_SECRET
-
MBEDTLS_TLS_EXT_RECORD_SIZE_LIMIT
-
MBEDTLS_TLS_EXT_SESSION_TICKET
-
MBEDTLS_TLS_EXT_PRE_SHARED_KEY
-
MBEDTLS_TLS_EXT_EARLY_DATA
-
MBEDTLS_TLS_EXT_SUPPORTED_VERSIONS
-
MBEDTLS_TLS_EXT_COOKIE
-
MBEDTLS_TLS_EXT_PSK_KEY_EXCHANGE_MODES
-
MBEDTLS_TLS_EXT_CERT_AUTH
-
MBEDTLS_TLS_EXT_OID_FILTERS
-
MBEDTLS_TLS_EXT_POST_HANDSHAKE_AUTH
-
MBEDTLS_TLS_EXT_SIG_ALG_CERT
-
MBEDTLS_TLS_EXT_KEY_SHARE
-
MBEDTLS_TLS_EXT_CID
-
MBEDTLS_TLS_EXT_ECJPAKE_KKPP
-
MBEDTLS_TLS_EXT_RENEGOTIATION_INFO
-
MBEDTLS_PREMASTER_SIZE
-
MBEDTLS_TLS1_3_MD_MAX_SIZE
-
MBEDTLS_SSL_SEQUENCE_NUMBER_LEN
-
MBEDTLS_SSL_TLS1_3_TICKET_ALLOW_PSK_RESUMPTION
-
MBEDTLS_SSL_TLS1_3_TICKET_ALLOW_PSK_EPHEMERAL_RESUMPTION
-
MBEDTLS_SSL_TLS1_3_TICKET_ALLOW_EARLY_DATA
-
MBEDTLS_SSL_TLS1_3_TICKET_FLAGS_MASK
-
MBEDTLS_TLS_SRTP_MAX_MKI_LENGTH
-
MBEDTLS_TLS_SRTP_MAX_PROFILE_LIST_LENGTH
-
MBEDTLS_TLS_SRTP_AES128_CM_HMAC_SHA1_80
-
MBEDTLS_TLS_SRTP_AES128_CM_HMAC_SHA1_32
-
MBEDTLS_TLS_SRTP_NULL_HMAC_SHA1_80
-
MBEDTLS_TLS_SRTP_NULL_HMAC_SHA1_32
-
MBEDTLS_TLS_SRTP_UNSET
-
MBEDTLS_SSL_UNEXPECTED_CID_IGNORE
-
MBEDTLS_SSL_UNEXPECTED_CID_FAIL
Typedefs
-
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.
Note
The callback is allowed to send fewer bytes than requested. It must always return the number of bytes actually sent.
- Param ctx:
Context for the send callback (typically a file descriptor)
- Param buf:
Buffer holding the data to send
- Param len:
Length of the data to send
- Return:
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.
-
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.
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.
- Param ctx:
Context for the receive callback (typically a file descriptor)
- Param buf:
Buffer to write the received data to
- Param len:
Length of the receive buffer
- Return:
If data has been received, the positive number of bytes received.
- Return:
0
if the connection has been closed.- Return:
If performing non-blocking I/O,
MBEDTLS_ERR_SSL_WANT_READ
must be returned when the operation would block.- Return:
Another negative error code on other kinds of failures.
-
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.
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.
- Param ctx:
Context for the receive callback (typically a file descriptor)
- Param buf:
Buffer to write the received data to
- Param len:
Length of the receive buffer
- Param timeout:
Maximum number of milliseconds to wait for data 0 means no timeout (potentially waiting forever)
- Return:
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.
-
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.
Note
This callback must at least store the necessary information for the associated
mbedtls_ssl_get_timer_t
callback to return correct information.Note
If using an 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.Note
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.
- Param ctx:
Context pointer
- Param int_ms:
Intermediate delay in milliseconds
- Param fin_ms:
Final delay in milliseconds 0 cancels the current timer.
-
typedef int mbedtls_ssl_get_timer_t(void *ctx)
Callback type: get status of timers/delays.
- Param ctx:
Context pointer
- Return:
This callback must return: -1 if cancelled (fin_ms == 0), 0 if none of the delays have passed, 1 if only the intermediate delay has passed, 2 if the final delay has passed.
-
typedef struct mbedtls_ssl_session mbedtls_ssl_session
-
typedef struct mbedtls_ssl_context mbedtls_ssl_context
-
typedef struct mbedtls_ssl_config mbedtls_ssl_config
-
typedef struct mbedtls_ssl_transform mbedtls_ssl_transform
-
typedef struct mbedtls_ssl_handshake_params mbedtls_ssl_handshake_params
-
typedef struct mbedtls_ssl_sig_hash_set_t mbedtls_ssl_sig_hash_set_t
-
typedef struct mbedtls_ssl_key_cert mbedtls_ssl_key_cert
-
typedef struct mbedtls_ssl_flight_item mbedtls_ssl_flight_item
-
typedef int mbedtls_ssl_cache_get_t(void *data, unsigned char const *session_id, size_t session_id_len, mbedtls_ssl_session *session)
Callback type: server-side session cache getter.
The session cache is logically a key value store, with keys being session IDs and values being instances of mbedtls_ssl_session. This callback retrieves an entry in this key-value store.
- Param data:
The address of the session cache structure to query.
- Param session_id:
The buffer holding the session ID to query.
- Param session_id_len:
The length of
session_id
in Bytes.- Param session:
The address of the session structure to populate. It is initialized with mbdtls_ssl_session_init(), and the callback must always leave it in a state where it can safely be freed via mbedtls_ssl_session_free() independent of the return code of this function.
- Return:
0
on success- Return:
A non-zero return value on failure.
-
typedef int mbedtls_ssl_cache_set_t(void *data, unsigned char const *session_id, size_t session_id_len, const mbedtls_ssl_session *session)
Callback type: server-side session cache setter.
The session cache is logically a key value store, with keys being session IDs and values being instances of mbedtls_ssl_session. This callback sets an entry in this key-value store.
- Param data:
The address of the session cache structure to modify.
- Param session_id:
The buffer holding the session ID to query.
- Param session_id_len:
The length of
session_id
in Bytes.- Param session:
The address of the session to be stored in the session cache.
- Return:
0
on success- Return:
A non-zero return value on failure.
-
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 \p 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 \p ssl and \p cert are guaranteed to remain valid throughout the handshake. On the other hand, this function must save the contents of \p hash if the value is needed for later processing, because the \p 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, withT = hash
andtLen = hash_len
.If
md_alg != MBEDTLS_MD_NONE
, apply the PKCS#1 v1.5 encoding, treatinghash
as the hash to be encoded and padded. In other words, apply EMSA-PKCS1-v1_5 starting from step 2, withdigestAlgorithm
obtained by calling mbedtls_oid_get_oid_by_md() onmd_alg
.
Note
For ECDSA signatures, the output format is the DER encoding
Ecdsa-Sig-Value
defined in RFC 4492 section 5.4.- Param ssl:
The SSL connection instance. It should not be modified other than via mbedtls_ssl_set_async_operation_data().
- Param 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.
- Param md_alg:
Hash algorithm.
- Param hash:
Buffer containing the hash. This buffer is no longer valid when the function returns.
- Param hash_len:
Size of the
hash
buffer in bytes.- Return:
0 if the operation was started successfully and the SSL stack should call the resume callback immediately.
- Return:
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.
- Return:
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.
- Return:
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_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 \p 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 \p ssl and \p cert are guaranteed to remain valid throughout the handshake. On the other hand, this function must save the contents of \p input if the value is needed for later processing, because the \p 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.
- Param ssl:
The SSL connection instance. It should not be modified other than via mbedtls_ssl_set_async_operation_data().
- Param 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.
- Param input:
Buffer containing the input ciphertext. This buffer is no longer valid when the function returns.
- Param input_len:
Size of the
input
buffer in bytes.- Return:
0 if the operation was started successfully and the SSL stack should call the resume callback immediately.
- Return:
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.
- Return:
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.
- Return:
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.
- Param ssl:
The SSL connection instance. It should not be modified other than via mbedtls_ssl_set_async_operation_data().
- Param output:
Buffer containing the output (signature or decrypted data) on success.
- Param output_len:
On success, number of bytes written to
output
.- Param output_size:
Size of the
output
buffer in bytes.- Return:
0 if output of the operation is available in the
output
buffer.- Return:
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.
- Return:
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 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.
- Param ssl:
The SSL connection instance. It should not be modified.
-
typedef uint16_t mbedtls_ssl_srtp_profile
-
typedef struct mbedtls_dtls_srtp_info_t mbedtls_dtls_srtp_info
-
typedef void mbedtls_ssl_export_keys_t(void *p_expkey, mbedtls_ssl_key_export_type type, const unsigned char *secret, size_t secret_len, const unsigned char client_random[32], const unsigned char server_random[32], mbedtls_tls_prf_types tls_prf_type)
Callback type: Export key alongside random values for session identification, and PRF for implementation of TLS key exporters.
- Param p_expkey:
Context for the callback.
- Param type:
The type of the key that is being exported.
- Param secret:
The address of the buffer holding the secret that’s being exporterd.
- Param secret_len:
The length of
secret
in bytes.- Param client_random:
The client random bytes.
- Param server_random:
The server random bytes.
- Param tls_prf_type:
The identifier for the PRF used in the handshake to which the key belongs.
-
typedef int (*mbedtls_ssl_hs_cb_t)(mbedtls_ssl_context *ssl)
Callback type: generic handshake callback.
Note
Callbacks may use user_data funcs to set/get app user data. See
mbedtls_ssl_get_user_data_p()
mbedtls_ssl_get_user_data_n()
mbedtls_ssl_conf_get_user_data_p()
mbedtls_ssl_conf_get_user_data_n()
- Param ssl:
mbedtls_ssl_context
on which the callback is run- Return:
The return value of the callback is 0 if successful, or a specific MBEDTLS_ERR_XXX code, which will cause the handshake to be aborted.
-
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.
- Param p_ticket:
Context for the callback
- Param session:
SSL session to be written in the ticket
- Param start:
Start of the output buffer
- Param end:
End of the output buffer
- Param tlen:
On exit, holds the length written
- Param lifetime:
On exit, holds the lifetime of the ticket in seconds
- Return:
0 if successful, or a specific MBEDTLS_ERR_XXX code.
-
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.
Note
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.
- Param p_ticket:
Context for the callback
- Param session:
SSL session to be loaded
- Param buf:
Start of the buffer containing the ticket
- Param len:
Length of the ticket.
- Return:
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_cookie_write_t(void *ctx, unsigned char **p, unsigned char *end, const unsigned char *info, size_t ilen)
Callback type: generate a cookie.
- Param ctx:
Context for the callback
- Param p:
Buffer to write to, must be updated to point right after the cookie
- Param end:
Pointer to one past the end of the output buffer
- Param info:
Client ID info that was passed to
mbedtls_ssl_set_client_transport_id()
- Param ilen:
Length of info in bytes
- Return:
The callback must return 0 on success, or a negative error code.
-
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.
- Param ctx:
Context for the callback
- Param cookie:
Cookie to verify
- Param clen:
Length of cookie
- Param info:
Client ID info that was passed to
mbedtls_ssl_set_client_transport_id()
- Param ilen:
Length of info in bytes
- Return:
The callback must return 0 if cookie is valid, or a negative error code.
Enums
-
enum mbedtls_ssl_states
Values:
-
enumerator MBEDTLS_SSL_HELLO_REQUEST
-
enumerator MBEDTLS_SSL_CLIENT_HELLO
-
enumerator MBEDTLS_SSL_SERVER_HELLO
-
enumerator MBEDTLS_SSL_SERVER_CERTIFICATE
-
enumerator MBEDTLS_SSL_SERVER_KEY_EXCHANGE
-
enumerator MBEDTLS_SSL_CERTIFICATE_REQUEST
-
enumerator MBEDTLS_SSL_SERVER_HELLO_DONE
-
enumerator MBEDTLS_SSL_CLIENT_CERTIFICATE
-
enumerator MBEDTLS_SSL_CLIENT_KEY_EXCHANGE
-
enumerator MBEDTLS_SSL_CERTIFICATE_VERIFY
-
enumerator MBEDTLS_SSL_CLIENT_CHANGE_CIPHER_SPEC
-
enumerator MBEDTLS_SSL_CLIENT_FINISHED
-
enumerator MBEDTLS_SSL_SERVER_CHANGE_CIPHER_SPEC
-
enumerator MBEDTLS_SSL_SERVER_FINISHED
-
enumerator MBEDTLS_SSL_FLUSH_BUFFERS
-
enumerator MBEDTLS_SSL_HANDSHAKE_WRAPUP
-
enumerator MBEDTLS_SSL_NEW_SESSION_TICKET
-
enumerator MBEDTLS_SSL_SERVER_HELLO_VERIFY_REQUEST_SENT
-
enumerator MBEDTLS_SSL_HELLO_RETRY_REQUEST
-
enumerator MBEDTLS_SSL_ENCRYPTED_EXTENSIONS
-
enumerator MBEDTLS_SSL_END_OF_EARLY_DATA
-
enumerator MBEDTLS_SSL_CLIENT_CERTIFICATE_VERIFY
-
enumerator MBEDTLS_SSL_CLIENT_CCS_AFTER_SERVER_FINISHED
-
enumerator MBEDTLS_SSL_CLIENT_CCS_BEFORE_2ND_CLIENT_HELLO
-
enumerator MBEDTLS_SSL_SERVER_CCS_AFTER_SERVER_HELLO
-
enumerator MBEDTLS_SSL_CLIENT_CCS_AFTER_CLIENT_HELLO
-
enumerator MBEDTLS_SSL_SERVER_CCS_AFTER_HELLO_RETRY_REQUEST
-
enumerator MBEDTLS_SSL_HANDSHAKE_OVER
-
enumerator MBEDTLS_SSL_TLS1_3_NEW_SESSION_TICKET
-
enumerator MBEDTLS_SSL_TLS1_3_NEW_SESSION_TICKET_FLUSH
-
enumerator MBEDTLS_SSL_HELLO_REQUEST
-
enum mbedtls_ssl_early_data_status
Values:
-
enumerator MBEDTLS_SSL_EARLY_DATA_STATUS_NOT_INDICATED
-
enumerator MBEDTLS_SSL_EARLY_DATA_STATUS_ACCEPTED
-
enumerator MBEDTLS_SSL_EARLY_DATA_STATUS_REJECTED
-
enumerator MBEDTLS_SSL_EARLY_DATA_STATUS_NOT_INDICATED
-
enum mbedtls_ssl_protocol_version
Human-friendly representation of the (D)TLS protocol version.
Values:
-
enumerator MBEDTLS_SSL_VERSION_UNKNOWN
Context not in use or version not yet negotiated.
-
enumerator MBEDTLS_SSL_VERSION_TLS1_2
(D)TLS 1.2
-
enumerator MBEDTLS_SSL_VERSION_TLS1_3
(D)TLS 1.3
-
enumerator MBEDTLS_SSL_VERSION_UNKNOWN
-
enum mbedtls_tls_prf_types
Values:
-
enumerator MBEDTLS_SSL_TLS_PRF_NONE
-
enumerator MBEDTLS_SSL_TLS_PRF_SHA384
-
enumerator MBEDTLS_SSL_TLS_PRF_SHA256
-
enumerator MBEDTLS_SSL_HKDF_EXPAND_SHA384
-
enumerator MBEDTLS_SSL_HKDF_EXPAND_SHA256
-
enumerator MBEDTLS_SSL_TLS_PRF_NONE
-
enum mbedtls_ssl_key_export_type
Values:
-
enumerator MBEDTLS_SSL_KEY_EXPORT_TLS12_MASTER_SECRET
-
enumerator MBEDTLS_SSL_KEY_EXPORT_TLS1_3_CLIENT_EARLY_SECRET
-
enumerator MBEDTLS_SSL_KEY_EXPORT_TLS1_3_EARLY_EXPORTER_SECRET
-
enumerator MBEDTLS_SSL_KEY_EXPORT_TLS1_3_CLIENT_HANDSHAKE_TRAFFIC_SECRET
-
enumerator MBEDTLS_SSL_KEY_EXPORT_TLS1_3_SERVER_HANDSHAKE_TRAFFIC_SECRET
-
enumerator MBEDTLS_SSL_KEY_EXPORT_TLS1_3_CLIENT_APPLICATION_TRAFFIC_SECRET
-
enumerator MBEDTLS_SSL_KEY_EXPORT_TLS1_3_SERVER_APPLICATION_TRAFFIC_SECRET
-
enumerator MBEDTLS_SSL_KEY_EXPORT_TLS12_MASTER_SECRET
Functions
-
const char *mbedtls_ssl_get_ciphersuite_name(const int ciphersuite_id)
Return the name of the ciphersuite associated with the given ID.
- Parameters:
ciphersuite_id – SSL ciphersuite ID
- Returns:
a string containing the ciphersuite name
-
int mbedtls_ssl_get_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
-
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_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.
Note
If MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto subsystem must have been initialized by calling psa_crypto_init() before calling this function.
Warning
The conf structure will be accessed during the session. It must not be modified or freed as long as the session is active.
Warning
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_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 or MBEDTLS_ERR_SSL_HW_ACCEL_FAILED
-
void mbedtls_ssl_conf_endpoint(mbedtls_ssl_config *conf, int endpoint)
Set the current endpoint type.
- Parameters:
conf – SSL configuration
endpoint – must be MBEDTLS_SSL_IS_CLIENT or MBEDTLS_SSL_IS_SERVER
-
static inline int mbedtls_ssl_conf_get_endpoint(const mbedtls_ssl_config *conf)
Get the current endpoint type.
- Parameters:
conf – SSL configuration
- Returns:
Endpoint type, either MBEDTLS_SSL_IS_CLIENT or MBEDTLS_SSL_IS_SERVER
-
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_authmode(mbedtls_ssl_config *conf, int authmode)
Set the certificate verification mode Default: NONE on server, REQUIRED on client.
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.
- Parameters:
conf – SSL configuration
authmode – can be:
-
void mbedtls_ssl_conf_early_data(mbedtls_ssl_config *conf, int early_data_enabled)
Set the early data mode Default: disabled on server and client.
MBEDTLS_SSL_EARLY_DATA_DISABLED: Early data functionality is disabled. This is the default on client and server.
MBEDTLS_SSL_EARLY_DATA_ENABLED: Early data functionality is enabled and may be negotiated in the handshake. Application using early data functionality needs to be aware that the security properties for early data (also refered to as 0-RTT data) are weaker than those for other kinds of TLS data. See the documentation of mbedtls_ssl_write_early_data() and mbedtls_ssl_read_early_data() for more information. When early data functionality is enabled on server and only in that case, the call to one of the APIs that trigger or resume an handshake sequence, namely mbedtls_ssl_handshake(), mbedtls_ssl_handshake_step(), mbedtls_ssl_read() or mbedtls_ssl_write() may return with the error code MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA indicating that some early data have been received. To read the early data, call mbedtls_ssl_read_early_data() before calling the original function again.
- Parameters:
conf – The SSL configuration to use.
early_data_enabled – can be:
-
void mbedtls_ssl_conf_max_early_data_size(mbedtls_ssl_config *conf, uint32_t max_early_data_size)
Set the maximum amount of 0-RTT data in bytes Default: MBEDTLS_SSL_MAX_EARLY_DATA_SIZE.
This function sets the value of the max_early_data_size field of the early data indication extension included in the NewSessionTicket messages that the server may send.
The value defines the maximum amount of 0-RTT data in bytes that a client will be allowed to send when using one of the tickets defined by the NewSessionTicket messages.
Note
When resuming a session using a ticket, if the server receives more early data than allowed for the ticket, it terminates the connection. The maximum amount of 0-RTT data should thus be large enough to allow a minimum of early data to be exchanged.
Warning
This interface DOES NOT influence/limit the amount of early data that can be received through previously created and issued tickets, which clients may have stored.
- Parameters:
conf – [in] The SSL configuration to use.
max_early_data_size – [in] The maximum amount of 0-RTT data.
-
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).
If set, the provided verify callback is called for each certificate in the peer's CRT chain, including the trusted root. For more information, please see the documentation of \c mbedtls_x509_crt_verify().
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.
-
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.
- Parameters:
conf – SSL configuration
f_rng – RNG function (mandatory)
p_rng – RNG parameter
-
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.
The callback has the following argument: void * opaque context for the callback int debug level const char * file name int line number const char * message
- Parameters:
conf – SSL configuration
f_dbg – debug function
p_dbg – debug parameter
-
static inline const mbedtls_ssl_config *mbedtls_ssl_context_get_config(const mbedtls_ssl_context *ssl)
Return the SSL configuration structure associated with the given SSL context.
Note
The pointer returned by this function is guaranteed to remain valid until the context is freed.
- Parameters:
ssl – The SSL context to query.
- Returns:
Pointer to the SSL configuration associated with
ssl
.
-
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.
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).
Note
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_timeout != NULL
Note
For DTLS, you need to provide either a non-NULL f_recv_timeout callback, or a f_recv that doesn’t block.
Note
See the documentations of
mbedtls_ssl_send_t
,mbedtls_ssl_recv_t
andmbedtls_ssl_recv_timeout_t
for the conventions those callbacks must follow.Note
On some platforms, net_sockets.c provides
mbedtls_net_send()
,mbedtls_net_recv()
andmbedtls_net_recv_timeout()
that are suitable to be used here.- 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.
-
int mbedtls_ssl_set_cid(mbedtls_ssl_context *ssl, int enable, unsigned char const *own_cid, size_t own_cid_len)
Configure the use of the Connection ID (CID) extension in the next handshake.
Reference: RFC 9146 (or draft-ietf-tls-dtls-connection-id-05 https://tools.ietf.org/html/draft-ietf-tls-dtls-connection-id-05 for legacy version)
The DTLS CID extension allows the reliable association of DTLS records to DTLS connections across changes in the underlying transport (changed IP and Port metadata) by adding explicit connection identifiers (CIDs) to the headers of encrypted DTLS records. The desired CIDs are configured by the application layer and are exchanged in new
ClientHello
/ServerHello
extensions during the handshake, where each side indicates the CID it wants the peer to use when writing encrypted messages. The CIDs are put to use once records get encrypted: the stack discards any incoming records that don’t include the configured CID in their header, and adds the peer’s requested CID to the headers of outgoing messages.This API enables or disables the use of the CID extension in the next handshake and sets the value of the CID to be used for incoming messages.
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.Note
This CID configuration applies to subsequent handshakes performed on the SSL context
ssl
, but does not trigger one. You still have to callmbedtls_ssl_handshake()
(for the initial handshake) ormbedtls_ssl_renegotiate()
(for a renegotiation handshake) explicitly after a successful call to this function to run the handshake.Note
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 theServerHello
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 the server will look for the CID extension in a
ClientHello
from the client, and, if present, reply with a CID extension in itsServerHello
.
Note
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.- 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 ifenable
is set to MBEDTLS_SSL_CID_DISABLED.own_cid_len – The length of
own_cid
. This parameter is unused ifenable
is set to MBEDTLS_SSL_CID_DISABLED.
- Returns:
0
on success. In this case, the CID configuration applies to the next handshake.- Returns:
A negative error code on failure.
-
int mbedtls_ssl_get_own_cid(mbedtls_ssl_context *ssl, int *enabled, unsigned char own_cid[MBEDTLS_SSL_CID_IN_LEN_MAX], size_t *own_cid_len)
Get information about our request for usage of the CID extension in the current connection.
Note
If we are requesting an empty CID this function sets
*enabled
to MBEDTLS_SSL_CID_DISABLED (the rationale for this is that the resulting outcome is the same as if the CID extensions wasn’t requested).- Parameters:
ssl – The SSL context to query.
enabled – The address at which to store whether the CID extension is requested to be used or not. If the CID is requested,
*enabled
is set to MBEDTLS_SSL_CID_ENABLED; otherwise, it is set to MBEDTLS_SSL_CID_DISABLED.own_cid – The address of the buffer in which to store our own CID (if the CID extension is requested). This may be
NULL
in case the value of our CID isn’t needed. If it is notNULL
,own_cid_len
must not beNULL
.own_cid_len – The address at which to store the size of our own CID (if the CID extension is requested). This is also the number of Bytes in
own_cid
that have been written. This may beNULL
in case the length of our own CID isn’t needed. If it isNULL
,own_cid
must beNULL
, too.
- Returns:
0
on success.- Returns:
A negative error code on failure.
-
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.
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.
Note
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).- 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.
- Returns:
0
on success.- Returns:
A negative error code on failure.
-
void mbedtls_ssl_set_mtu(mbedtls_ssl_context *ssl, uint16_t mtu)
Set the Maximum Transport Unit (MTU). Special value: 0 means unset (no limit). This represents the maximum size of a datagram payload handled by the transport layer (usually UDP) as determined by the network link and stack. In practice, this controls the maximum size datagram the DTLS layer will pass to the
f_send()
callback set usingmbedtls_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.
Note
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.
Note
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()
.Note
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.
Note
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.
Note
Values lower than the current record layer expansion will result in an error when trying to send data.
- Parameters:
ssl – SSL context
mtu – Value of the path MTU in bytes
-
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).
If set, the provided verify callback is called for each certificate in the peer's CRT chain, including the trusted root. For more information, please see the documentation of \c mbedtls_x509_crt_verify().
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.
-
void mbedtls_ssl_conf_read_timeout(mbedtls_ssl_config *conf, uint32_t timeout)
Set the timeout period for mbedtls_ssl_read() (Default: no timeout.)
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()
.Note
With non-blocking I/O, you may also skip this function altogether and handle timeouts at the application layer.
- Parameters:
conf – SSL configuration context
timeout – Timeout value in milliseconds. Use 0 for no timeout (default).
-
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.
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.
Note
This function modifies the input buffer
buf
. If you need to preserve the original record, you have to maintain a copy.- 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.
- Returns:
0
if the record is valid and authentic and has not been seen before.- Returns:
MBEDTLS_ERR_SSL_INVALID_MAC if the check completed successfully but the record was found to be not authentic.
- Returns:
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.
- Returns:
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.
- Returns:
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.
-
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.)
Note
See the documentation of
mbedtls_ssl_set_timer_t
andmbedtls_ssl_get_timer_t
for the conventions this pair of callbacks must follow.Note
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.Note
See also the “DTLS tutorial” article in our knowledge base. https://mbed-tls.readthedocs.io/en/latest/kb/how-to/dtls-tutorial
- 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:
-
static inline void mbedtls_ssl_conf_cert_cb(mbedtls_ssl_config *conf, mbedtls_ssl_hs_cb_t f_cert_cb)
Set the certificate selection callback (server-side only).
If set, the callback is always called for each handshake, after `ClientHello` processing has finished.
- Parameters:
conf – The SSL configuration to register the callback with.
f_cert_cb – The callback for selecting server certificate after
ClientHello
processing has finished.
-
void mbedtls_ssl_conf_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.
Note
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
-
static inline int mbedtls_ssl_session_get_ticket_creation_time(mbedtls_ssl_session *session, mbedtls_ms_time_t *ticket_creation_time)
Get the creation time of a session ticket.
Note
See the documentation of
ticket_creation_time
for information about the intended usage of this function.- Parameters:
session – SSL session
ticket_creation_time – On exit, holds the ticket creation time in milliseconds.
- Returns:
0 on success, MBEDTLS_ERR_SSL_BAD_INPUT_DATA if an input is not valid.
-
static inline const unsigned char (*mbedtls_ssl_session_get_id(const mbedtls_ssl_session *session))[32]
Get the session-id buffer.
- Parameters:
session – SSL session.
- Returns:
The address of the session-id buffer.
-
static inline size_t mbedtls_ssl_session_get_id_len(const mbedtls_ssl_session *session)
Get the size of the session-id.
- Parameters:
session – SSL session.
- Returns:
size_t size of session-id buffer.
-
static inline int mbedtls_ssl_session_get_ciphersuite_id(const mbedtls_ssl_session *session)
Get the ciphersuite-id.
- Parameters:
session – SSL session.
- Returns:
int represetation for ciphersuite.
-
void mbedtls_ssl_set_export_keys_cb(mbedtls_ssl_context *ssl, mbedtls_ssl_export_keys_t *f_export_keys, void *p_export_keys)
Configure a key export callback. (Default: none.)
This API can be used for two purposes:
Debugging: Use this API to e.g. generate an NSSKeylog file and use it to inspect encrypted traffic in tools such as Wireshark.
Application-specific export: Use this API to implement key exporters, e.g. for EAP-TLS or DTLS-SRTP.
- Parameters:
ssl – The SSL context to which the export callback should be attached.
f_export_keys – The callback for the key export.
p_export_keys – The opaque context pointer to be passed to the callback
f_export_keys
.
-
static inline void mbedtls_ssl_conf_set_user_data_p(mbedtls_ssl_config *conf, void *p)
Set the user data in an SSL configuration to a pointer.
You can retrieve this value later with mbedtls_ssl_conf_get_user_data_p().
Note
The library stores
p
without accessing it. It is the responsibility of the caller to ensure that the pointer remains valid.- Parameters:
conf – The SSL configuration context to modify.
p – The new value of the user data.
-
static inline void mbedtls_ssl_conf_set_user_data_n(mbedtls_ssl_config *conf, uintptr_t n)
Set the user data in an SSL configuration to an integer.
You can retrieve this value later with mbedtls_ssl_conf_get_user_data_n().
- Parameters:
conf – The SSL configuration context to modify.
n – The new value of the user data.
-
static inline void *mbedtls_ssl_conf_get_user_data_p(mbedtls_ssl_config *conf)
Retrieve the user data in an SSL configuration as a pointer.
This is the value last set with mbedtls_ssl_conf_set_user_data_p(), or
NULL
if mbedtls_ssl_conf_set_user_data_p() has not previously been called. The value is undefined if mbedtls_ssl_conf_set_user_data_n() has been called without a subsequent call to mbedtls_ssl_conf_set_user_data_p().- Parameters:
conf – The SSL configuration context to modify.
- Returns:
The current value of the user data.
-
static inline uintptr_t mbedtls_ssl_conf_get_user_data_n(mbedtls_ssl_config *conf)
Retrieve the user data in an SSL configuration as an integer.
This is the value last set with mbedtls_ssl_conf_set_user_data_n(), or
0
if mbedtls_ssl_conf_set_user_data_n() has not previously been called. The value is undefined if mbedtls_ssl_conf_set_user_data_p() has been called without a subsequent call to mbedtls_ssl_conf_set_user_data_n().- Parameters:
conf – The SSL configuration context to modify.
- Returns:
The current value of the user data.
-
static inline void mbedtls_ssl_set_user_data_p(mbedtls_ssl_context *ssl, void *p)
Set the user data in an SSL context to a pointer.
You can retrieve this value later with mbedtls_ssl_get_user_data_p().
Note
The library stores
p
without accessing it. It is the responsibility of the caller to ensure that the pointer remains valid.- Parameters:
ssl – The SSL context to modify.
p – The new value of the user data.
-
static inline void mbedtls_ssl_set_user_data_n(mbedtls_ssl_context *ssl, uintptr_t n)
Set the user data in an SSL context to an integer.
You can retrieve this value later with mbedtls_ssl_get_user_data_n().
- Parameters:
ssl – The SSL context to modify.
n – The new value of the user data.
-
static inline void *mbedtls_ssl_get_user_data_p(mbedtls_ssl_context *ssl)
Retrieve the user data in an SSL context as a pointer.
This is the value last set with mbedtls_ssl_set_user_data_p(), or
NULL
if mbedtls_ssl_set_user_data_p() has not previously been called. The value is undefined if mbedtls_ssl_set_user_data_n() has been called without a subsequent call to mbedtls_ssl_set_user_data_p().- Parameters:
ssl – The SSL context to modify.
- Returns:
The current value of the user data.
-
static inline uintptr_t mbedtls_ssl_get_user_data_n(mbedtls_ssl_context *ssl)
Retrieve the user data in an SSL context as an integer.
This is the value last set with mbedtls_ssl_set_user_data_n(), or
0
if mbedtls_ssl_set_user_data_n() has not previously been called. The value is undefined if mbedtls_ssl_set_user_data_p() has been called without a subsequent call to mbedtls_ssl_set_user_data_n().- Parameters:
ssl – The SSL context to modify.
- Returns:
The current value of the user data.
-
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_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_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
.
-
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_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.
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.Note
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.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.
- Parameters:
conf – SSL configuration
f_cookie_write – Cookie write callback
f_cookie_check – Cookie check callback
p_cookie – Context for both callbacks
-
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.
Note
An internal copy is made, so the info buffer can be reused.
- Parameters:
ssl – SSL context
info – Transport-level info identifying the client (eg IP + port)
ilen – Length of info in bytes
- 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_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.
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.
- Parameters:
conf – SSL configuration
mode – MBEDTLS_SSL_ANTI_REPLAY_ENABLED or MBEDTLS_SSL_ANTI_REPLAY_DISABLED.
-
void mbedtls_ssl_conf_dtls_badmac_limit(mbedtls_ssl_config *conf, unsigned limit)
Set a limit on the number of records with a bad MAC before terminating the connection. (DTLS only, no effect on TLS.) Default: 0 (disabled).
Note
If the limit is N, then the connection is terminated when the Nth non-authentic record is seen.
Note
Records with an invalid header are not counted, only the ones going through the authentication-decryption phase.
Note
This is a security trade-off related to the fact that it’s often relatively easy for an active attacker to 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.
- Parameters:
conf – SSL configuration
limit – Limit, or 0 to disable.
-
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.
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.
Note
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.
Note
Application records are not affected by this option and are currently always sent in separate datagrams.
- 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.
-
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.)
Note
Default values are from RFC 6347 section 4.2.4.1.
Note
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.
Note
The more unreliable your network connection is, the larger your max / min ratio needs to be in order to achieve reliable handshakes.
Note
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.
- Parameters:
conf – SSL configuration
min – Initial timeout value in milliseconds. Default: 1000 (1 second).
max – Maximum timeout value in milliseconds. Default: 60000 (60 seconds).
-
void mbedtls_ssl_conf_session_cache(mbedtls_ssl_config *conf, void *p_cache, mbedtls_ssl_cache_get_t *f_get_cache, mbedtls_ssl_cache_set_t *f_set_cache)
Set the session cache callbacks (server-side only) If not set, no session resuming is done (except if session tickets are enabled too).
The session cache has the responsibility to check for stale entries based on timeout. See RFC 5246 for recommendations.
Warning: session.peer_cert is cleared by the SSL/TLS layer on connection shutdown, so do not cache the pointer! Either set it to NULL or make a full copy of the certificate.
The get callback is called once during the initial handshake to enable session resuming. The get function has the following parameters: (void *parameter, mbedtls_ssl_session *session) If a valid entry is found, it should fill the master of the session object with the cached values and return 0, return 1 otherwise. Optionally peer_cert can be set as well if it is properly present in cache entry.
The set callback is called once during the initial handshake to enable session resuming after the entire handshake has been finished. The set function has the following parameters: (void *parameter, const mbedtls_ssl_session *session). The function should create a cache entry for future retrieval based on the data in the session structure and should keep in mind that the mbedtls_ssl_session object presented (and all its referenced data) is cleared by the SSL/TLS layer when the connection is terminated. It is recommended to add metadata to determine if an entry is still valid in the future. Return 0 if successfully cached, return 1 otherwise.
- Parameters:
conf – SSL configuration
p_cache – parameter (context) for both callbacks
f_get_cache – session get callback
f_set_cache – session set callback
-
int mbedtls_ssl_set_session(mbedtls_ssl_context *ssl, const mbedtls_ssl_session *session)
Load a session for session resumption.
Sessions loaded through this call will be considered for session resumption in the next handshake.
See also
See also
Note
Even if this call succeeds, it is not guaranteed that the next handshake will indeed be shortened through the use of session resumption: The server is always free to reject any attempt for resumption and fall back to a full handshake.
Note
This function can handle a variety of mechanisms for session resumption: For TLS 1.2, both session ID-based resumption and ticket-based resumption will be considered. For TLS 1.3, sessions equate to tickets, and loading one session by calling this function will lead to its corresponding ticket being advertised as resumption PSK by the client. This depends on session tickets being enabled (see MBEDTLS_SSL_SESSION_TICKETS configuration option) though. If session tickets are disabled, a call to this function with a TLS 1.3 session, will not have any effect on the next handshake for the SSL context
ssl
.- Parameters:
ssl – The SSL context representing the connection which should be attempted to be setup using session resumption. This must be initialized via mbedtls_ssl_init() and bound to an SSL configuration via mbedtls_ssl_setup(), but the handshake must not yet have been started.
session – The session to be considered for session resumption. This must be a session previously exported via mbedtls_ssl_get_session(), and potentially serialized and deserialized through mbedtls_ssl_session_save() and mbedtls_ssl_session_load() in the meantime.
- Returns:
0
if successful.- Returns:
MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE
if the session could not be loaded because one session has already been loaded. This error is non-fatal, and has no observable effect on the SSL context or the session that was attempted to be loaded.- Returns:
Another negative error code on other kinds of failure.
-
int mbedtls_ssl_session_load(mbedtls_ssl_session *session, const unsigned char *buf, size_t len)
Load serialized session data into a session structure. On client, this can be used for loading saved sessions before resuming them with mbedtls_ssl_set_session(). On server, this can be used for alternative implementations of session cache or session tickets.
See also
See also
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.- Returns:
MBEDTLS_ERR_SSL_ALLOC_FAILED if memory allocation failed.
- Returns:
MBEDTLS_ERR_SSL_BAD_INPUT_DATA if input data is invalid.
- Returns:
MBEDTLS_ERR_SSL_VERSION_MISMATCH if the serialized data was generated in a different version or configuration of Mbed TLS.
- Returns:
Another negative value for other kinds of errors (for example, unsupported features in the embedded certificate).
-
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.
See also
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
.Note
For TLS 1.3 sessions, this feature is supported only if the MBEDTLS_SSL_SESSION_TICKETS configuration option is enabled, as in TLS 1.3 session resumption is possible only with 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
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
.
- Returns:
0
if successful.- Returns:
MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL if
buf
is too small.- Returns:
MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE if the MBEDTLS_SSL_SESSION_TICKETS configuration option is disabled and the session is a TLS 1.3 session.
-
void mbedtls_ssl_conf_ciphersuites(mbedtls_ssl_config *conf, const int *ciphersuites)
Set the list of allowed ciphersuites and the preference order. First in the list has the highest preference.
For TLS 1.2, the notion of ciphersuite determines both the key exchange mechanism and the suite of symmetric algorithms to be used during and after the handshake.
For TLS 1.3 (in development), the notion of ciphersuite only determines the suite of symmetric algorithms to be used during and after the handshake, while key exchange mechanisms are configured separately.
In Mbed TLS, ciphersuites for both TLS 1.2 and TLS 1.3 are configured via this function. For users of TLS 1.3, there will be separate API for the configuration of key exchange mechanisms.
The list of ciphersuites passed to this function may contain a mixture of TLS 1.2 and TLS 1.3 ciphersuite identifiers. This is useful if negotiation of TLS 1.3 should be attempted, but a fallback to TLS 1.2 would be tolerated.
Note
By default, the server chooses its preferred ciphersuite among those that the client supports. If mbedtls_ssl_conf_preference_order() is called to prefer the client’s preferences, the server instead chooses the client’s preferred ciphersuite among those that the server supports.
Warning
The ciphersuites array
ciphersuites
is not copied. It must remain valid for the lifetime of the SSL configurationconf
.- Parameters:
conf – The SSL configuration to modify.
ciphersuites – A 0-terminated list of IANA identifiers of supported ciphersuites, accessible through
MBEDTLS_TLS_XXX
andMBEDTLS_TLS1_3_XXX
macros defined in ssl_ciphersuites.h.
-
void mbedtls_ssl_conf_tls13_key_exchange_modes(mbedtls_ssl_config *conf, const int kex_modes)
Set the supported key exchange modes for TLS 1.3 connections.
In contrast to TLS 1.2, the ciphersuite concept in TLS 1.3 does not include the choice of key exchange mechanism. It is therefore not covered by the API mbedtls_ssl_conf_ciphersuites(). See the documentation of mbedtls_ssl_conf_ciphersuites() for more information on the ciphersuite concept in TLS 1.2 and TLS 1.3. The present function is specific to TLS 1.3 and allows users to configure the set of supported key exchange mechanisms in TLS 1.3.
Note
If a PSK-based key exchange mode shall be supported, applications must also use the APIs mbedtls_ssl_conf_psk() or mbedtls_ssl_conf_psk_cb() or mbedtls_ssl_conf_psk_opaque() to configure the PSKs to be used.
Note
If a pure-ephemeral key exchange mode shall be supported, server-side applications must also provide a certificate via mbedtls_ssl_conf_own_cert().
- Parameters:
conf – The SSL configuration the change should apply to.
kex_modes – A bitwise combination of one or more of the following:
MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK This flag enables pure-PSK key exchanges.
MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL This flag enables combined PSK-ephemeral key exchanges.
MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL This flag enables pure-ephemeral key exchanges. For convenience, the following pre-defined macros are available for combinations of the above:
MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_ALL Includes all of pure-PSK, PSK-ephemeral and pure-ephemeral.
MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_ALL Includes both pure-PSK and combined PSK-ephemeral key exchanges, but excludes pure-ephemeral key exchanges.
MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL_ALL Includes both pure-ephemeral and combined PSK-ephemeral key exchanges.
-
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.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.
- 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.
- Returns:
0
on success.- Returns:
MBEDTLS_ERR_SSL_BAD_INPUT_DATA if
len
is too large.
-
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_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
-
static inline void mbedtls_ssl_conf_dn_hints(mbedtls_ssl_config *conf, const mbedtls_x509_crt *crt)
Set DN hints sent to client in CertificateRequest message.
Note
If not set, subject distinguished names (DNs) are taken from
mbedtls_ssl_conf_ca_chain()
ormbedtls_ssl_set_hs_ca_chain()
)- Parameters:
conf – SSL configuration
crt – crt chain whose subject DNs are issuer DNs of client certs from which the client should select client peer certificate.
-
void mbedtls_ssl_conf_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.
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().
Note
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.
Note
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.
Note
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().
Warning
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
).- 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).
-
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.
Note
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.
Note
On client, only the first call has any effect. That is, only one client certificate can be provisioned. The server’s preferences in its CertificateRequest 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.
Note
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 pre-shared keys (PSKs) and their identities to be used in PSK-based ciphersuites.
Only one PSK can be registered, through either mbedtls_ssl_conf_psk() or mbedtls_ssl_conf_psk_opaque(). If you attempt to register more than one PSK, this function fails, though this may change in future versions, which may add support for multiple PSKs.
Note
This is mainly useful for clients. Servers will usually want to use
mbedtls_ssl_conf_psk_cb()
instead.Note
A PSK set by
mbedtls_ssl_set_hs_psk()
in the PSK callback takes precedence over a PSK configured by this function.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.
- 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.
- Returns:
0
if successful.- Returns:
MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE if no more PSKs can be configured. In this case, the old PSK(s) remain intact.
- Returns:
Another negative error code on other kinds of failure.
-
int mbedtls_ssl_conf_psk_opaque(mbedtls_ssl_config *conf, mbedtls_svc_key_id_t psk, const unsigned char *psk_identity, size_t psk_identity_len)
Configure one or more opaque pre-shared keys (PSKs) and their identities to be used in PSK-based ciphersuites.
Only one PSK can be registered, through either mbedtls_ssl_conf_psk() or mbedtls_ssl_conf_psk_opaque(). If you attempt to register more than one PSK, this function fails, though this may change in future versions, which may add support for multiple PSKs.
Note
This is mainly useful for clients. Servers will usually want to use
mbedtls_ssl_conf_psk_cb()
instead.Note
An opaque PSK set by
mbedtls_ssl_set_hs_psk_opaque()
in the PSK callback takes precedence over an opaque PSK configured by this function.Note
The PSK identity hint is copied internally and hence need not be preserved by the caller for the lifetime of the SSL configuration.
- 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.
- Returns:
0
if successful.- Returns:
MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE if no more PSKs can be configured. In this case, the old PSK(s) remain intact.
- Returns:
Another negative error code on other kinds of failure.
-
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()
.Note
A PSK set by this function takes precedence over a PSK configured by
mbedtls_ssl_conf_psk()
.- 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.- Returns:
An
MBEDTLS_ERR_SSL_XXX
error code on failure.
-
int mbedtls_ssl_set_hs_psk_opaque(mbedtls_ssl_context *ssl, mbedtls_svc_key_id_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()
.Note
An opaque PSK set by this function takes precedence over an opaque PSK configured by
mbedtls_ssl_conf_psk_opaque()
.- 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.- Returns:
An
MBEDTLS_ERR_SSL_XXX
error code on failure.
-
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).
If set, the PSK callback is called for each handshake where a PSK-based ciphersuite was negotiated. The caller provides the identity received and wants to receive the actual PSK data and length. The callback has the following parameters: - \c void*: The opaque pointer \p p_psk. - \c mbedtls_ssl_context*: The SSL context to which the operation applies. - \c const unsigned char*: The PSK identity selected by the client. - \c size_t: The length of the PSK identity selected by the client. If a valid PSK identity is found, the callback should use \c mbedtls_ssl_set_hs_psk() or \c mbedtls_ssl_set_hs_psk_opaque() on the SSL context to set the correct PSK and return \c 0. Any other return value will result in a denied PSK identity.
Note
A dynamic PSK (i.e. set by the PSK callback) takes precedence over a static PSK (i.e. set by
mbedtls_ssl_conf_psk()
ormbedtls_ssl_conf_psk_opaque()
). This means that if you set a PSK callback using this function, you don’t need to set a PSK usingmbedtls_ssl_conf_psk()
ormbedtls_ssl_conf_psk_opaque()
).- 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_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)
Set the Diffie-Hellman public P and G values, read from existing context (server-side only)
- Parameters:
conf – SSL configuration
dhm_ctx – Diffie-Hellman-Merkle context
- Returns:
0 if successful
-
void mbedtls_ssl_conf_dhm_min_bitlen(mbedtls_ssl_config *conf, unsigned int bitlen)
Set the minimum length for Diffie-Hellman parameters. (Client-side only.) (Default: 1024 bits.)
- Parameters:
conf – SSL configuration
bitlen – Minimum bit length of the DHM prime
-
void mbedtls_ssl_conf_groups(mbedtls_ssl_config *conf, const uint16_t *groups)
Set the allowed groups in order of preference.
On server: This only affects the choice of key agreement mechanism On client: this affects the list of groups offered for any use. The server can override our preference order. Both sides: limits the set of groups accepted for use in key sharing.
Note
This function replaces the deprecated mbedtls_ssl_conf_curves(), which only allows ECP curves to be configured.
Note
The most recent invocation of either mbedtls_ssl_conf_curves() or mbedtls_ssl_conf_groups() nullifies all previous invocations of both.
Note
This list should be ordered by decreasing preference (preferred group first).
Note
When this function is not called, a default list is used, consisting of all supported curves at 255 bits and above, and all supported finite fields at 2048 bits and above. The order favors groups with the lowest resource usage.
Note
New minor versions of Mbed TLS will not remove items from the default list unless serious security concerns require it. New minor versions of Mbed TLS may change the order in keeping with the general principle of favoring the lowest resource usage.
- Parameters:
conf – SSL configuration
groups – List of allowed groups ordered by preference, terminated by 0. Must contain valid IANA NamedGroup IDs (provided via either an integer or using MBEDTLS_TLS1_3_NAMED_GROUP_XXX macros).
-
void mbedtls_ssl_conf_sig_algs(mbedtls_ssl_config *conf, const uint16_t *sig_algs)
Configure allowed signature algorithms for use in TLS.
- Parameters:
conf – The SSL configuration to use.
sig_algs – List of allowed IANA values for TLS 1.3 signature algorithms, terminated by MBEDTLS_TLS1_3_SIG_NONE. The list must remain available throughout the lifetime of the conf object.
For TLS 1.3, values of
MBEDTLS_TLS1_3_SIG_XXXX
should be used.For TLS 1.2, values should be given as “(HashAlgorithm << 8) | SignatureAlgorithm”.
-
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)
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.
Note
Maximum hostname length MBEDTLS_SSL_MAX_HOST_NAME_LEN.
- Parameters:
ssl – SSL context
hostname – the server hostname, may be NULL to clear hostname
- Returns:
0 if successful, MBEDTLS_ERR_SSL_ALLOC_FAILED on allocation failure, MBEDTLS_ERR_SSL_BAD_INPUT_DATA on too long input hostname.
-
static inline const char *mbedtls_ssl_get_hostname(mbedtls_ssl_context *ssl)
Get the hostname that checked against the received server certificate. It is used to set the ServerName TLS extension, too, if that extension is enabled. (client-side only)
- Parameters:
ssl – SSL context
- Returns:
const pointer to the hostname value
-
const unsigned char *mbedtls_ssl_get_hs_sni(mbedtls_ssl_context *ssl, size_t *name_len)
Retrieve SNI extension value for the current handshake. Available in
f_cert_cb
ofmbedtls_ssl_conf_cert_cb()
, this is the same value passed tof_sni
callback ofmbedtls_ssl_conf_sni()
and may be used instead ofmbedtls_ssl_conf_sni()
.- Parameters:
ssl – SSL context
name_len – pointer into which to store length of returned value. 0 if SNI extension is not present or not yet processed.
- Returns:
const pointer to SNI extension value.
value is valid only when called in
f_cert_cb
registered withmbedtls_ssl_conf_cert_cb()
.value is NULL if SNI extension is not present.
value is not ‘\0’-terminated. Use
name_len
for len.value must not be freed.
-
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 or the certificate selection callback.Note
Passing null
own_cert
clears the certificate list for the current handshake.- 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
-
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 or the certificate selection callback.- Parameters:
ssl – SSL context
ca_chain – trusted CA chain (meaning all fully trusted top-level CAs)
ca_crl – trusted CA CRLs
-
void mbedtls_ssl_set_hs_dn_hints(mbedtls_ssl_context *ssl, const mbedtls_x509_crt *crt)
Set DN hints sent to client in CertificateRequest message.
Note
Same as
mbedtls_ssl_conf_dn_hints()
but for use within the SNI callback or the certificate selection callback.- Parameters:
ssl – SSL context
crt – crt chain whose subject DNs are issuer DNs of client certs from which the client should select client peer certificate.
-
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 or the certificate selection callback.- Parameters:
ssl – SSL context
authmode – MBEDTLS_SSL_VERIFY_NONE, MBEDTLS_SSL_VERIFY_OPTIONAL or MBEDTLS_SSL_VERIFY_REQUIRED
-
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).
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 withmbedtls_ssl_set_hs_ca_chain()
as well as the client authentication mode withmbedtls_ssl_set_hs_authmode()
, then must return 0. If no matching name is found, the callback may return non-zero to abort the handshake.- Parameters:
conf – SSL configuration
f_sni – verification function
p_sni – verification parameter
-
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.
Note
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()
. Password cannot be empty (see RFC 8236).- Parameters:
ssl – SSL context
pw – EC J-PAKE password (pre-shared secret). It cannot be empty
pw_len – length of pw in bytes
- Returns:
0 on success, or a negative error code.
-
int mbedtls_ssl_set_hs_ecjpake_password_opaque(mbedtls_ssl_context *ssl, mbedtls_svc_key_id_t pwd)
Set the EC J-PAKE opaque password for current handshake.
Note
The key must remain valid until the handshake is over.
Note
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
pwd – EC J-PAKE opaque password
- Returns:
0 on success, or a negative error code.
-
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 at least as long as the lifetime of the SSL configuration structure.
- Returns:
0 on success, or MBEDTLS_ERR_SSL_BAD_INPUT_DATA.
-
const char *mbedtls_ssl_get_alpn_protocol(const mbedtls_ssl_context *ssl)
Get the name of the negotiated Application Layer Protocol. This function should be called after the handshake is completed.
- Parameters:
ssl – SSL context
- Returns:
Protocol name, or NULL if no protocol was negotiated.
-
static inline const char *mbedtls_ssl_get_srtp_profile_as_string(mbedtls_ssl_srtp_profile profile)
-
void mbedtls_ssl_conf_srtp_mki_value_supported(mbedtls_ssl_config *conf, int support_mki_value)
Manage support for mki(master key id) value in use_srtp extension. MKI is an optional part of SRTP used for key management and re-keying. See RFC3711 section 3.1 for details. The default value is MBEDTLS_SSL_DTLS_SRTP_MKI_UNSUPPORTED.
- Parameters:
conf – The SSL configuration to manage mki support.
support_mki_value – Enable or disable mki usage. Values are MBEDTLS_SSL_DTLS_SRTP_MKI_UNSUPPORTED or MBEDTLS_SSL_DTLS_SRTP_MKI_SUPPORTED.
-
int mbedtls_ssl_conf_dtls_srtp_protection_profiles(mbedtls_ssl_config *conf, const mbedtls_ssl_srtp_profile *profiles)
Set the supported DTLS-SRTP protection profiles.
- Parameters:
conf – SSL configuration
profiles – Pointer to a List of MBEDTLS_TLS_SRTP_UNSET terminated supported protection profiles in decreasing preference order. The pointer to the list is recorded by the library for later reference as required, so the lifetime of the table must be at least as long as the lifetime of the SSL configuration structure. The list must not hold more than MBEDTLS_TLS_SRTP_MAX_PROFILE_LIST_LENGTH elements (excluding the terminating MBEDTLS_TLS_SRTP_UNSET).
- Returns:
0 on success
- Returns:
MBEDTLS_ERR_SSL_BAD_INPUT_DATA when the list of protection profiles is incorrect.
-
int mbedtls_ssl_dtls_srtp_set_mki_value(mbedtls_ssl_context *ssl, unsigned char *mki_value, uint16_t mki_len)
Set the mki_value for the current DTLS-SRTP session.
Note
This function is relevant on client side only. The server discovers the mki value during handshake. A mki value set on server side using this function is ignored.
- Parameters:
ssl – SSL context to use.
mki_value – The MKI value to set.
mki_len – The length of the MKI value.
- Returns:
0 on success
- Returns:
- Returns:
-
void mbedtls_ssl_get_dtls_srtp_negotiation_result(const mbedtls_ssl_context *ssl, mbedtls_dtls_srtp_info *dtls_srtp_info)
Get the negotiated DTLS-SRTP information: Protection profile and MKI value.
Warning
This function must be called after the handshake is completed. The value returned by this function must not be trusted or acted upon before the handshake completes.
- Parameters:
ssl – The SSL context to query.
dtls_srtp_info – The negotiated DTLS-SRTP information:
Protection profile in use. A direct mapping of the iana defined value for protection profile on an uint16_t. http://www.iana.org/assignments/srtp-protection/srtp-protection.xhtml MBEDTLS_TLS_SRTP_UNSET if the use of SRTP was not negotiated or peer’s Hello packet was not parsed yet.
mki size and value( if size is > 0 ).
-
static inline void mbedtls_ssl_conf_max_tls_version(mbedtls_ssl_config *conf, mbedtls_ssl_protocol_version tls_version)
Set the maximum supported version sent from the client side and/or accepted at the server side.
Note
After the handshake, you can call mbedtls_ssl_get_version_number() to see what version was negotiated.
- Parameters:
conf – SSL configuration
tls_version – TLS protocol version number (
mbedtls_ssl_protocol_version
) (MBEDTLS_SSL_VERSION_UNKNOWN is not valid)
-
static inline void mbedtls_ssl_conf_min_tls_version(mbedtls_ssl_config *conf, mbedtls_ssl_protocol_version tls_version)
Set the minimum supported version sent from the client side and/or accepted at the server side.
Note
After the handshake, you can call mbedtls_ssl_get_version_number() to see what version was negotiated.
- Parameters:
conf – SSL configuration
tls_version – TLS protocol version number (
mbedtls_ssl_protocol_version
) (MBEDTLS_SSL_VERSION_UNKNOWN is not valid)
-
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_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_cert_req_ca_list(mbedtls_ssl_config *conf, char cert_req_ca_list)
Whether to send a list of acceptable CAs in CertificateRequest messages. (Default: do send)
- Parameters:
conf – SSL configuration
cert_req_ca_list – MBEDTLS_SSL_CERT_REQ_CA_LIST_ENABLED or MBEDTLS_SSL_CERT_REQ_CA_LIST_DISABLED
-
int mbedtls_ssl_conf_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.
Note
With TLS, this currently only affects ApplicationData (sent with
mbedtls_ssl_read()
), not handshake messages. With DTLS, this affects both ApplicationData and handshake.Note
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()
.Note
For DTLS, it is also possible to set a limit for the total size of datagrams 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_preference_order(mbedtls_ssl_config *conf, int order)
Pick the ciphersuites order according to the second parameter in the SSL Server module (MBEDTLS_SSL_SRV_C). (Default, if never called: MBEDTLS_SSL_SRV_CIPHERSUITE_ORDER_SERVER)
- Parameters:
conf – SSL configuration
order – Server or client (MBEDTLS_SSL_SRV_CIPHERSUITE_ORDER_SERVER or MBEDTLS_SSL_SRV_CIPHERSUITE_ORDER_CLIENT)
-
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_new_session_tickets(mbedtls_ssl_config *conf, uint16_t num_tickets)
Number of NewSessionTicket messages for the server to send after handshake completion.
Note
The default value is
MBEDTLS_SSL_TLS1_3_DEFAULT_NEW_SESSION_TICKETS
.Note
In case of a session resumption, this setting only partially apply. At most one ticket is sent in that case to just renew the pool of tickets of the client. The rationale is to avoid the number of tickets on the server to become rapidly out of control when the server has the same configuration for all its connection instances.
- Parameters:
conf – SSL configuration
num_tickets – Number of NewSessionTicket.
-
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)
Note
Server-side, enabling renegotiation also makes the server susceptible to a resource DoS by a malicious client.
Warning
It is recommended to always disable renegotiation 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.
- Parameters:
conf – SSL configuration
renegotiation – Enable or disable (MBEDTLS_SSL_RENEGOTIATION_ENABLED or MBEDTLS_SSL_RENEGOTIATION_DISABLED)
-
void mbedtls_ssl_conf_legacy_renegotiation(mbedtls_ssl_config *conf, int allow_legacy)
Prevent or allow legacy renegotiation. (Default: MBEDTLS_SSL_LEGACY_NO_RENEGOTIATION)
MBEDTLS_SSL_LEGACY_NO_RENEGOTIATION allows connections to be established even if the peer does not support secure renegotiation, but does not allow renegotiation to take place if not secure. (Interoperable and secure option)
MBEDTLS_SSL_LEGACY_ALLOW_RENEGOTIATION allows renegotiations with non-upgraded peers. Allowing legacy renegotiation makes the connection vulnerable to specific man in the middle attacks. (See RFC 5746) (Most interoperable and least secure option)
MBEDTLS_SSL_LEGACY_BREAK_HANDSHAKE breaks off connections if peer does not support secure renegotiation. Results in interoperability issues with non-upgraded peers that do not support renegotiation altogether. (Most secure option, interoperability issues)
- Parameters:
conf – SSL configuration
allow_legacy – Prevent or allow (SSL_NO_LEGACY_RENEGOTIATION, SSL_ALLOW_LEGACY_RENEGOTIATION or MBEDTLS_SSL_LEGACY_BREAK_HANDSHAKE)
-
void mbedtls_ssl_conf_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 retransmitted 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.
-
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.
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.Note
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.Note
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.
- Parameters:
ssl – SSL context
- Returns:
0 if nothing’s pending, 1 otherwise.
-
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.
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.- Parameters:
ssl – SSL context
- Returns:
How many bytes are available in the application data record read buffer.
-
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.- Returns:
-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.- Returns:
A bitwise combination of
MBEDTLS_X509_BADCERT_XXX
andMBEDTLS_X509_BADCRL_XXX
failure flags; see x509.h.
-
int mbedtls_ssl_get_ciphersuite_id_from_ssl(const mbedtls_ssl_context *ssl)
Return the id of the current ciphersuite.
- Parameters:
ssl – SSL context
- Returns:
a ciphersuite id
-
const char *mbedtls_ssl_get_ciphersuite(const mbedtls_ssl_context *ssl)
Return the name of the current ciphersuite.
- Parameters:
ssl – SSL context
- Returns:
a string containing the ciphersuite name
-
static inline mbedtls_ssl_protocol_version mbedtls_ssl_get_version_number(const mbedtls_ssl_context *ssl)
Return the (D)TLS protocol version negotiated in the given connection.
Note
If you call this function too early during the initial handshake, before the two sides have agreed on a version, this function returns MBEDTLS_SSL_VERSION_UNKNOWN.
- Parameters:
ssl – The SSL context to query.
- Returns:
The negotiated protocol version.
-
const char *mbedtls_ssl_get_version(const mbedtls_ssl_context *ssl)
Return the current TLS version.
- Parameters:
ssl – SSL context
- Returns:
a string containing the TLS version
-
int mbedtls_ssl_get_record_expansion(const mbedtls_ssl_context *ssl)
Return the (maximum) number of bytes added by the record layer: header + encryption/MAC overhead (inc. padding)
- Parameters:
ssl – SSL context
- Returns:
Current maximum record expansion in bytes
-
int mbedtls_ssl_get_max_out_record_payload(const mbedtls_ssl_context *ssl)
Return the current maximum outgoing record payload in bytes.
See also
Note
The logic to determine the maximum outgoing record payload is version-specific. It takes into account various factors, such as the mbedtls_config.h setting
MBEDTLS_SSL_OUT_CONTENT_LEN
, extensions such as the max fragment length or record size limit extension if used, and for DTLS the path MTU as configured and current record expansion.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.- Parameters:
ssl – SSL context
- Returns:
Current maximum payload for an outgoing record, or a negative error code.
-
int mbedtls_ssl_get_max_in_record_payload(const mbedtls_ssl_context *ssl)
Return the current maximum incoming record payload in bytes.
See also
See also
Note
The logic to determine the maximum incoming record payload is version-specific. It takes into account various factors, such as the mbedtls_config.h setting
MBEDTLS_SSL_IN_CONTENT_LEN
, extensions such as the max fragment length extension or record size limit extension if used, and the current record expansion.- Parameters:
ssl – SSL context
- Returns:
Current maximum payload for an incoming 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.
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.
- 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.
- Returns:
NULL
if no peer certificate is available. This might be because the chosen ciphersuite doesn’t use CRTs (PSK-based ciphersuites, for example), or because MBEDTLS_SSL_KEEP_PEER_CERTIFICATE has been disabled, allowing the stack to free the peer’s CRT to save memory.
-
int mbedtls_ssl_get_session(const mbedtls_ssl_context *ssl, mbedtls_ssl_session *session)
Export a session in order to resume it later.
See also
See also
Note
This function can handle a variety of mechanisms for session resumption: For TLS 1.2, both session ID-based resumption and ticket-based resumption will be considered. For TLS 1.3, sessions equate to tickets, and if session tickets are enabled (see MBEDTLS_SSL_SESSION_TICKETS configuration option), this function exports the last received ticket and the exported session may be used to resume the TLS 1.3 session. If session tickets are disabled, exported sessions cannot be used to resume a TLS 1.3 session.
- Parameters:
ssl – The SSL context representing the connection for which to to export a session structure for later resumption.
session – The target structure in which to store the exported session. This must have been initialized with mbedtls_ssl_session_init() but otherwise be unused.
- Returns:
0
if successful. In this case,session
can be used for session resumption by passing it to mbedtls_ssl_set_session(), and serialized for storage via mbedtls_ssl_session_save().- Returns:
Another negative error code on other kinds of failure.
-
int mbedtls_ssl_handshake(mbedtls_ssl_context *ssl)
Perform the SSL handshake.
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.
Note
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.
Note
If the context is configured to allow TLS 1.3, or if MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto subsystem must have been initialized by calling psa_crypto_init() before calling this function.
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 or MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA, 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.- Parameters:
ssl – SSL context
- Returns:
0
if successful.- Returns:
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.
- Returns:
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.
- Returns:
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.
- Returns:
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).
- Returns:
MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA if early data, as defined in RFC 8446 (TLS 1.3 specification), has been received as part of the handshake. This is server specific and may occur only if the early data feature has been enabled on server (see mbedtls_ssl_conf_early_data() documentation). You must call mbedtls_ssl_read_early_data() to read the early data before resuming the handshake.
- Returns:
Another SSL error code - in this case you must stop using the context (see below).
-
static inline int mbedtls_ssl_is_handshake_over(mbedtls_ssl_context *ssl)
After calling mbedtls_ssl_handshake() to start the SSL handshake you can call this function to check whether the handshake is over for a given SSL context. This function should be also used to determine when to stop calling mbedtls_handshake_step() for that context.
- Parameters:
ssl – SSL context
- Returns:
1
if handshake is over,0
if it is still ongoing.
-
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 mbedtls_ssl_is_handshake_over() returns1
.Warning
Whilst in the past you may have used direct access to the context state (ssl->state) in order to ascertain when to stop calling this function and although you can still do so with something like ssl->MBEDTLS_PRIVATE(state) or by defining MBEDTLS_ALLOW_PRIVATE_ACCESS, this is now considered deprecated and could be broken in any future release. If you still find you have good reason for such direct access, then please do contact the team to explain this (raise an issue or post to the mailing list), so that we can add a solution to your problem that will be guaranteed to work in the future.
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, MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS or MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA, 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.- Parameters:
ssl – SSL context
- Returns:
-
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.
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.- 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.
-
int mbedtls_ssl_read(mbedtls_ssl_context *ssl, unsigned char *buf, size_t len)
Read at most ‘len’ application data bytes.
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!Note
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.
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, MBEDTLS_ERR_SSL_CLIENT_RECONNECT or MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA, you must stop using the SSL context for reading or writing, and either free it or call
mbedtls_ssl_session_reset()
on it before re-using it for a new connection; the current connection must be closed.- 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.
- Returns:
0
if the read end of the underlying transport was closed without sending a CloseNotify beforehand, which might happen because of various reasons (internal error of an underlying stack, non-conformant peer not sending a CloseNotify and such) - in this case you must stop using the context (see below).- Returns:
MBEDTLS_ERR_SSL_PEER_CLOSE_NOTIFY if the underlying transport is still functional, but the peer has acknowledged to not send anything anymore.
- Returns:
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.
- Returns:
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.
- Returns:
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.
- Returns:
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.
- Returns:
MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA if early data, as defined in RFC 8446 (TLS 1.3 specification), has been received as part of the handshake. This is server specific and may occur only if the early data feature has been enabled on server (see mbedtls_ssl_conf_early_data() documentation). You must call mbedtls_ssl_read_early_data() to read the early data before resuming the handshake.
- Returns:
Another SSL error code - in this case you must stop using the context (see below).
-
int mbedtls_ssl_write(mbedtls_ssl_context *ssl, const unsigned char *buf, size_t len)
Try to write exactly ‘len’ application data bytes.
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 than 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.
Note
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_out_record_payload()
may be used to query the active maximum fragment length.
Note
Attempting to write 0 bytes will result in an empty TLS application record being sent.
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.
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, MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS or MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA, you must stop using the SSL context for reading or writing, and either free it or call
mbedtls_ssl_session_reset()
on it before re-using it for a new connection; the current connection must be closed.- 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
).- Returns:
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.
- Returns:
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.
- Returns:
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.
- Returns:
MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA if early data, as defined in RFC 8446 (TLS 1.3 specification), has been received as part of the handshake. This is server specific and may occur only if the early data feature has been enabled on server (see mbedtls_ssl_conf_early_data() documentation). You must call mbedtls_ssl_read_early_data() to read the early data before resuming the handshake.
- Returns:
Another SSL error code - in this case you must stop using the context (see below).
-
int mbedtls_ssl_send_alert_message(mbedtls_ssl_context *ssl, unsigned char level, unsigned char message)
Send an alert message.
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.- 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.
-
int mbedtls_ssl_close_notify(mbedtls_ssl_context *ssl)
Notify the peer that the connection is being closed.
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.- Parameters:
ssl – SSL context
- Returns:
0 if successful, or a specific SSL error code.
-
int mbedtls_ssl_read_early_data(mbedtls_ssl_context *ssl, unsigned char *buf, size_t len)
Read at most ‘len’ bytes of early data.
The security properties for 0-RTT data are weaker than those for other kinds of TLS data. Specifically:
This data is not forward secret, as it is encrypted solely under keys derived using the offered PSK.
There are no guarantees of non-replay between connections. Protection against replay for ordinary TLS 1.3 1-RTT data is provided via the server’s Random value, but 0-RTT data does not depend on the ServerHello and therefore has weaker guarantees. This is especially relevant if the data is authenticated either with TLS client authentication or inside the application protocol. The same warnings apply to any use of the early_exporter_master_secret.
Note
This API is server specific.
Warning
Early data is defined in the TLS 1.3 specification, RFC 8446. IMPORTANT NOTE from section 2.3 of the specification:
Note
This function is used in conjunction with mbedtls_ssl_handshake(), mbedtls_ssl_handshake_step(), mbedtls_ssl_read() and mbedtls_ssl_write() to read early data when these functions return MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA.
Warning
Mbed TLS does not implement any of the anti-replay defenses defined in section 8 of the TLS 1.3 specification: single-use of tickets or ClientHello recording within a given time window.
- Parameters:
ssl – SSL context, it must have been initialized and set up.
buf – buffer that will hold the data
len – maximum number of bytes to read
- Returns:
The (positive) number of bytes read if successful.
- Returns:
MBEDTLS_ERR_SSL_BAD_INPUT_DATA if input data is invalid.
- Returns:
MBEDTLS_ERR_SSL_CANNOT_READ_EARLY_DATA if it is not possible to read early data for the SSL context
ssl
. Note that this function is intended to be called for an SSL contextssl
only after a call to mbedtls_ssl_handshake(), mbedtls_ssl_handshake_step(), mbedtls_ssl_read() or mbedtls_ssl_write() forssl
that has returned MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA.
-
int mbedtls_ssl_write_early_data(mbedtls_ssl_context *ssl, const unsigned char *buf, size_t len)
Try to write exactly ‘len’ application data bytes while performing the handshake (early data).
The security properties for 0-RTT data are weaker than those for other kinds of TLS data. Specifically:
This data is not forward secret, as it is encrypted solely under keys derived using the offered PSK.
There are no guarantees of non-replay between connections. Protection against replay for ordinary TLS 1.3 1-RTT data is provided via the server’s Random value, but 0-RTT data does not depend on the ServerHello and therefore has weaker guarantees. This is especially relevant if the data is authenticated either with TLS client authentication or inside the application protocol. The same warnings apply to any use of the early_exporter_master_secret.
MBEDTLS_ERR_SSL_CANNOT_WRITE_EARLY_DATA is returned when it is not possible to write early data for the SSL context
ssl
.It may have been possible and it is not possible anymore because the client received the server Finished message, the server rejected early data or the maximum number of allowed early data for the PSK in use has been reached.
It may never have been possible and will never be possible for the SSL context
ssl
because the use of early data is disabled for that context or more generally the context is not suitably configured to enable early data or the first call to the function was done while the handshake was already completed.It is not possible to write early data for the SSL context
ssl
and any subsequent call to this API will return this error code. But this does not preclude for using it with mbedtls_ssl_write(), mbedtls_ssl_read() or mbedtls_ssl_handshake() and the handshake can be completed by calling one of these APIs.Warning
Early data is defined in the TLS 1.3 specification, RFC 8446. IMPORTANT NOTE from section 2.3 of the specification:
Note
This function behaves mainly as mbedtls_ssl_write(). The specification of mbedtls_ssl_write() relevant to TLS 1.3 (thus not the parts specific to (D)TLS1.2) applies to this function and the present documentation is mainly restricted to the differences with mbedtls_ssl_write(). One noticeable difference though is that mbedtls_ssl_write() aims to complete the handshake before to write application data while mbedtls_ssl_write_early() aims to drive the handshake just past the point where it is not possible to send early data anymore.
Note
This function may write early data only if the SSL context has been configured for the handshake with a PSK for which early data is allowed.
Note
To maximize the number of early data that can be written in the course of the handshake, it is expected that this function starts the handshake for the SSL context
ssl
. But this is not mandatory.Note
This function does not provide any information on whether the server has accepted or will accept early data or not. When it returns a positive value, it just means that it has written early data to the server. To know whether the server has accepted early data or not, you should call mbedtls_ssl_get_early_data_status() with the handshake completed.
- 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
).- Returns:
One additional specific error code compared to mbedtls_ssl_write(): MBEDTLS_ERR_SSL_CANNOT_WRITE_EARLY_DATA.
-
int mbedtls_ssl_get_early_data_status(mbedtls_ssl_context *ssl)
Get the status of the negotiation of the use of early data.
- Parameters:
ssl – The SSL context to query
- Returns:
MBEDTLS_ERR_SSL_BAD_INPUT_DATA if this function is called from the server-side.
- Returns:
MBEDTLS_ERR_SSL_BAD_INPUT_DATA if this function is called prior to completion of the handshake.
- Returns:
MBEDTLS_SSL_EARLY_DATA_STATUS_NOT_INDICATED if the client has not indicated the use of early data to the server.
- Returns:
MBEDTLS_SSL_EARLY_DATA_STATUS_ACCEPTED if the client has indicated the use of early data and the server has accepted it.
- Returns:
MBEDTLS_SSL_EARLY_DATA_STATUS_REJECTED if the client has indicated the use of early data but the server has rejected it. In this situation, the client may want to re-send the early data it may have tried to send by calling mbedtls_ssl_write_early_data() as ordinary post-handshake application data by calling mbedtls_ssl_write().
-
void mbedtls_ssl_free(mbedtls_ssl_context *ssl)
Free referenced items in an SSL context and clear memory.
- Parameters:
ssl – SSL context
-
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
Note
The serialized data only contains the data that is necessary to resume the connection: negotiated protocol options, session identifier, keys, etc. Loading a saved SSL context does not restore settings and state related to how the application accesses the context, such as configured callback functions, user data, pending incoming or outgoing data, etc.
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.
Note
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.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.- 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
.
- Returns:
0
if successful.- Returns:
MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL if
buf
is too small.- Returns:
MBEDTLS_ERR_SSL_ALLOC_FAILED if memory allocation failed while resetting the context.
- Returns:
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.
-
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
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.
Note
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(), mbedtls_ssl_set_timer_cb(), and mbedtls_ssl_set_user_data_n() or mbedtls_ssl_set_user_data_p() if they were set originally. 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.
Note
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.
Note
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.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.
- 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.- Returns:
MBEDTLS_ERR_SSL_ALLOC_FAILED if memory allocation failed.
- Returns:
MBEDTLS_ERR_SSL_VERSION_MISMATCH if the serialized data comes from a different Mbed TLS version or build.
- Returns:
MBEDTLS_ERR_SSL_BAD_INPUT_DATA if input data is invalid.
-
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_config_defaults(mbedtls_ssl_config *conf, int endpoint, int transport, int preset)
Load reasonable default SSL configuration values. (You need to call mbedtls_ssl_config_init() first.)
Note
See
mbedtls_ssl_conf_transport()
for notes on DTLS.- 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
- Returns:
0 if successful, or MBEDTLS_ERR_XXX_ALLOC_FAILED on memory allocation error.
-
void mbedtls_ssl_config_free(mbedtls_ssl_config *conf)
Free an SSL configuration context.
- Parameters:
conf – SSL configuration context
-
void mbedtls_ssl_session_init(mbedtls_ssl_session *session)
Initialize SSL session structure.
- Parameters:
session – SSL session
-
void mbedtls_ssl_session_free(mbedtls_ssl_session *session)
Free referenced items in an SSL session including the peer certificate and clear memory.
Note
A session object can be freed even if the SSL context that was used to retrieve the session is still in use.
- Parameters:
session – SSL session
-
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 function type to be used.
secret – Secret for the key derivation function.
slen – Length of the secret.
label – String label for the key derivation function, terminated with null character.
random – Random bytes.
rlen – Length of the random bytes buffer.
dstbuf – The buffer holding the derived key.
dlen – Length of the output buffer.
- Returns:
0 on success. An SSL specific error on failure.
-
union mbedtls_ssl_premaster_secret
- #include <ssl.h>
Public Members
-
unsigned char dummy
-
unsigned char _pms_rsa[48]
-
unsigned char _pms_dhm[MBEDTLS_MPI_MAX_SIZE]
-
unsigned char _pms_ecdh[MBEDTLS_ECP_MAX_BYTES]
-
unsigned char _pms_psk[4 + 2 * MBEDTLS_PSK_MAX_LEN]
-
unsigned char _pms_dhe_psk[4 + MBEDTLS_MPI_MAX_SIZE + MBEDTLS_PSK_MAX_LEN]
-
unsigned char _pms_ecdhe_psk[4 + MBEDTLS_ECP_MAX_BYTES + MBEDTLS_PSK_MAX_LEN]
-
unsigned char _pms_ecjpake[32]
-
unsigned char dummy
-
struct mbedtls_ssl_tls13_application_secrets
- #include <ssl.h>
Public Members
-
unsigned char client_application_traffic_secret_N[MBEDTLS_TLS1_3_MD_MAX_SIZE]
-
unsigned char server_application_traffic_secret_N[MBEDTLS_TLS1_3_MD_MAX_SIZE]
-
unsigned char exporter_master_secret[MBEDTLS_TLS1_3_MD_MAX_SIZE]
-
unsigned char resumption_master_secret[MBEDTLS_TLS1_3_MD_MAX_SIZE]
-
unsigned char client_application_traffic_secret_N[MBEDTLS_TLS1_3_MD_MAX_SIZE]
-
struct mbedtls_dtls_srtp_info_t
- #include <ssl.h>
Public Members
-
mbedtls_ssl_srtp_profile private_chosen_dtls_srtp_profile
The SRTP profile that was negotiated.
-
uint16_t private_mki_len
The length of mki_value.
-
unsigned char private_mki_value[MBEDTLS_TLS_SRTP_MAX_MKI_LENGTH]
The mki_value used, with max size of 256 bytes.
-
mbedtls_ssl_srtp_profile private_chosen_dtls_srtp_profile
-
struct mbedtls_ssl_session
- #include <ssl.h>
Public Members
-
unsigned char private_mfl_code
MaxFragmentLength negotiated by peer
-
uint16_t private_record_size_limit
< RecordSizeLimit received from the peer
-
unsigned char private_exported
-
uint8_t private_endpoint
0: client, 1: server
-
mbedtls_ssl_protocol_version private_tls_version
TLS version negotiated in the session. Used if and when renegotiating or resuming a session instead of the configured minor TLS version.
-
mbedtls_time_t private_start
start time of current session
-
int private_ciphersuite
chosen ciphersuite
-
size_t private_id_len
session id length
-
unsigned char private_id[32]
session identifier
-
unsigned char private_master[48]
the master secret
-
mbedtls_x509_crt *private_peer_cert
peer X.509 cert chain
-
uint32_t private_verify_result
verification result
-
unsigned char *private_ticket
RFC 5077 session ticket
-
size_t private_ticket_len
session ticket length
-
uint32_t private_ticket_lifetime
ticket lifetime hint
-
mbedtls_ms_time_t private_ticket_creation_time
When a ticket is created by a TLS server as part of an established TLS session, the ticket creation time may need to be saved for the ticket module to be able to check the ticket age when the ticket is used. That’s the purpose of this field. Before creating a new ticket, an Mbed TLS server set this field with its current time in milliseconds. This time may then be saved in the session ticket data by the session ticket writing function and recovered by the ticket parsing function later when the ticket is used. The ticket module may then use this time to compute the ticket age and determine if it has expired or not. The Mbed TLS implementations of the session ticket writing and parsing functions save and retrieve the ticket creation time as part of the session ticket data. The session ticket parsing function relies on the mbedtls_ssl_session_get_ticket_creation_time() API to get the ticket creation time from the session ticket data.
-
uint32_t private_ticket_age_add
Randomly generated value used to obscure the age of the ticket
-
uint8_t private_ticket_flags
Ticket flags
-
uint8_t private_resumption_key_len
resumption_key length
-
unsigned char private_resumption_key[MBEDTLS_SSL_TLS1_3_TICKET_RESUMPTION_KEY_LEN]
-
char *private_hostname
host name binded with tickets
-
char *ticket_alpn
ALPN negotiated in the session during which the ticket was generated.
-
mbedtls_ms_time_t private_ticket_reception_time
Time in milliseconds when the last ticket was received.
-
uint32_t private_max_early_data_size
maximum amount of early data in tickets
-
int private_encrypt_then_mac
flag for EtM activation
-
mbedtls_ssl_tls13_application_secrets private_app_secrets
-
unsigned char private_mfl_code
-
union mbedtls_ssl_user_data_t
- #include <ssl.h>
-
struct mbedtls_ssl_config
- #include <ssl.h>
SSL/TLS configuration to be shared between mbedtls_ssl_context structures.
Public Members
-
mbedtls_ssl_protocol_version private_max_tls_version
max. TLS version used
-
mbedtls_ssl_protocol_version private_min_tls_version
min. TLS version used
-
uint8_t private_endpoint
0: client, 1: server
-
uint8_t private_transport
0: stream (TLS), 1: datagram (DTLS)
-
uint8_t private_authmode
MBEDTLS_SSL_VERIFY_XXX
-
uint8_t private_allow_legacy_renegotiation
MBEDTLS_LEGACY_XXX
-
uint8_t private_mfl_code
desired fragment length indicator (MBEDTLS_SSL_MAX_FRAG_LEN_XXX)
-
uint8_t private_encrypt_then_mac
negotiate encrypt-then-mac?
-
uint8_t private_extended_ms
negotiate extended master secret?
-
uint8_t private_anti_replay
detect and prevent replay?
-
uint8_t private_disable_renegotiation
disable renegotiation?
-
uint8_t private_session_tickets
use session tickets?
-
uint16_t private_new_session_tickets_count
number of NewSessionTicket
-
uint8_t private_cert_req_ca_list
enable sending CA list in Certificate Request messages?
-
uint8_t private_respect_cli_pref
pick the ciphersuite according to the client’s preferences rather than ours?
-
uint8_t private_ignore_unexpected_cid
Should DTLS record with unexpected CID lead to failure?
-
uint8_t private_dtls_srtp_mki_support
-
const int *private_ciphersuite_list
Allowed ciphersuites for (D)TLS 1.2 (0-terminated)
-
int private_tls13_kex_modes
Allowed TLS 1.3 key exchange modes.
-
void (*private_f_dbg)(void*, int, const char*, int, const char*)
Callback for printing debug output
-
void *private_p_dbg
context for the debug function
-
int (*private_f_rng)(void*, unsigned char*, size_t)
Callback for getting (pseudo-)random numbers
-
void *private_p_rng
context for the RNG function
-
mbedtls_ssl_cache_get_t *private_f_get_cache
Callback to retrieve a session from the cache
-
mbedtls_ssl_cache_set_t *private_f_set_cache
Callback to store a session into the cache
-
void *private_p_cache
context for cache callbacks
-
int (*private_f_sni)(void*, mbedtls_ssl_context*, const unsigned char*, size_t)
Callback for setting cert according to SNI extension
-
void *private_p_sni
context for SNI callback
-
int (*private_f_vrfy)(void*, mbedtls_x509_crt*, int, uint32_t*)
Callback to customize X.509 certificate chain verification
-
void *private_p_vrfy
context for X.509 verify calllback
-
int (*private_f_psk)(void*, mbedtls_ssl_context*, const unsigned char*, size_t)
Callback to retrieve PSK key from identity
-
void *private_p_psk
context for PSK callback
-
int (*private_f_cookie_write)(void*, unsigned char**, unsigned char*, const unsigned char*, size_t)
Callback to create & write a cookie for ClientHello verification
-
int (*private_f_cookie_check)(void*, const unsigned char*, size_t, const unsigned char*, size_t)
Callback to verify validity of a ClientHello cookie
-
void *private_p_cookie
context for the cookie callbacks
-
int (*private_f_ticket_write)(void*, const mbedtls_ssl_session*, unsigned char*, const unsigned char*, size_t*, uint32_t*)
Callback to create & write a session ticket
-
int (*private_f_ticket_parse)(void*, mbedtls_ssl_session*, unsigned char*, size_t)
Callback to parse a session ticket into a session structure
-
void *private_p_ticket
context for the ticket callbacks
-
size_t private_cid_len
The length of CIDs for incoming DTLS records.
-
const mbedtls_x509_crt_profile *private_cert_profile
verification profile
-
mbedtls_ssl_key_cert *private_key_cert
own certificate/key pair(s)
-
mbedtls_x509_crt *private_ca_chain
trusted CAs
-
mbedtls_x509_crl *private_ca_crl
trusted CAs CRLs
-
mbedtls_x509_crt_ca_cb_t private_f_ca_cb
-
void *private_p_ca_cb
-
mbedtls_ssl_async_sign_t *private_f_async_sign_start
start asynchronous signature operation
-
mbedtls_ssl_async_decrypt_t *private_f_async_decrypt_start
start asynchronous decryption operation
-
mbedtls_ssl_async_resume_t *private_f_async_resume
resume asynchronous operation
-
mbedtls_ssl_async_cancel_t *private_f_async_cancel
cancel asynchronous operation
-
void *private_p_async_config_data
Configuration data set by mbedtls_ssl_conf_async_private_cb().
-
const uint16_t *private_sig_algs
allowed signature algorithms
-
const uint16_t *private_group_list
allowed IANA NamedGroups
-
mbedtls_mpi private_dhm_P
prime modulus for DHM
-
mbedtls_mpi private_dhm_G
generator for DHM
-
mbedtls_svc_key_id_t private_psk_opaque
PSA key slot holding opaque PSK. This field should only be set via mbedtls_ssl_conf_psk_opaque(). If either no PSK or a raw PSK have been configured, this has value
0
.
-
unsigned char *private_psk
The raw pre-shared key. This field should only be set via mbedtls_ssl_conf_psk(). If either no PSK or an opaque PSK have been configured, this has value NULL.
-
size_t private_psk_len
The length of the raw pre-shared key. This field should only be set via mbedtls_ssl_conf_psk(). Its value is non-zero if and only if
psk
is notNULL
.
-
unsigned char *private_psk_identity
The PSK identity for PSK negotiation. This field should only be set via mbedtls_ssl_conf_psk(). This is set if and only if either
psk
orpsk_opaque
are set.
-
size_t private_psk_identity_len
The length of PSK identity. This field should only be set via mbedtls_ssl_conf_psk(). Its value is non-zero if and only if
psk
is notNULL
orpsk_opaque
is not0
.
-
int private_early_data_enabled
Early data enablement:
MBEDTLS_SSL_EARLY_DATA_DISABLED,
MBEDTLS_SSL_EARLY_DATA_ENABLED
-
uint32_t private_max_early_data_size
-
const char **private_alpn_list
ordered list of protocols
-
const mbedtls_ssl_srtp_profile *private_dtls_srtp_profile_list
ordered list of supported srtp profile
-
size_t private_dtls_srtp_profile_list_len
number of supported profiles
-
uint32_t private_read_timeout
timeout for mbedtls_ssl_read (ms)
-
uint32_t private_hs_timeout_min
initial value of the handshake retransmission timeout (ms)
-
uint32_t private_hs_timeout_max
maximum value of the handshake retransmission timeout (ms)
-
int private_renego_max_records
grace period for renegotiation
-
unsigned char private_renego_period[8]
value of the record counters that triggers renegotiation
-
unsigned int private_badmac_limit
limit of records with a bad MAC
-
unsigned int private_dhm_min_bitlen
min. bit length of the DHM prime
-
mbedtls_ssl_user_data_t private_user_data
User data pointer or handle.
The library sets this to
0
when creating a context and does not access it afterwards.
-
mbedtls_ssl_hs_cb_t private_f_cert_cb
certificate selection callback
-
const mbedtls_x509_crt *private_dn_hints
acceptable client cert issuers
-
mbedtls_ssl_protocol_version private_max_tls_version
-
struct mbedtls_ssl_context
- #include <ssl.h>
Public Members
-
const mbedtls_ssl_config *private_conf
configuration information
-
int private_state
SSL handshake: current state
-
int private_renego_status
Initial, in progress, pending?
-
int private_renego_records_seen
Records since renego request, or with DTLS, number of retransmissions of request if renego_max_records is < 0
-
mbedtls_ssl_protocol_version private_tls_version
Maximum TLS version to be negotiated, then negotiated TLS version.
It is initialized as the configured maximum TLS version to be negotiated by mbedtls_ssl_setup().
When renegotiating or resuming a session, it is overwritten in the ClientHello writing preparation stage with the previously negotiated TLS version.
On client side, it is updated to the TLS version selected by the server for the handshake when the ServerHello is received.
On server side, it is updated to the TLS version the server selects for the handshake when the ClientHello is received.
-
int private_early_data_state
State of the negotiation and transfer of early data. Reset to MBEDTLS_SSL_EARLY_DATA_STATE_IDLE when the context is reset.
-
unsigned private_badmac_seen
records with a bad MAC received
-
int (*private_f_vrfy)(void*, mbedtls_x509_crt*, int, uint32_t*)
Callback to customize X.509 certificate chain verification
-
void *private_p_vrfy
context for X.509 verify callback
-
mbedtls_ssl_send_t *private_f_send
Callback for network send
-
mbedtls_ssl_recv_t *private_f_recv
Callback for network receive
-
mbedtls_ssl_recv_timeout_t *private_f_recv_timeout
Callback for network receive with timeout
-
void *private_p_bio
context for I/O operations
-
mbedtls_ssl_session *private_session_in
current session data (in)
-
mbedtls_ssl_session *private_session_out
current session data (out)
-
mbedtls_ssl_session *private_session
negotiated session data
-
mbedtls_ssl_session *private_session_negotiate
session data in negotiation
-
mbedtls_ssl_handshake_params *private_handshake
params required only during the handshake process
-
mbedtls_ssl_transform *private_transform_in
current transform params (in) This is always a reference, never an owning pointer.
-
mbedtls_ssl_transform *private_transform_out
current transform params (out) This is always a reference, never an owning pointer.
-
mbedtls_ssl_transform *private_transform
negotiated transform params This pointer owns the transform it references.
-
mbedtls_ssl_transform *private_transform_negotiate
transform params in negotiation This pointer owns the transform it references.
-
mbedtls_ssl_transform *private_transform_application
The application data transform in TLS 1.3. This pointer owns the transform it references.
-
void *private_p_timer
context for the timer callbacks
-
mbedtls_ssl_set_timer_t *private_f_set_timer
set timer callback
-
mbedtls_ssl_get_timer_t *private_f_get_timer
get timer callback
-
unsigned char *private_in_buf
input buffer
-
unsigned char *private_in_ctr
64-bit incoming message counter TLS: maintained by us DTLS: read from peer
-
unsigned char *private_in_hdr
start of record header
-
unsigned char *private_in_cid
The start of the CID; (the end is marked by in_len).
-
unsigned char *private_in_len
two-bytes message length field
-
unsigned char *private_in_iv
ivlen-byte IV
-
unsigned char *private_in_msg
message contents (in_iv+ivlen)
-
unsigned char *private_in_offt
read offset in application data
-
int private_in_msgtype
record header: message type
-
size_t private_in_msglen
record header: message length
-
size_t private_in_left
amount of data read so far
-
size_t private_in_buf_len
length of input buffer
-
uint16_t private_in_epoch
DTLS epoch for incoming records
-
size_t private_next_record_offset
offset of the next record in datagram (equal to in_left if none)
-
uint64_t private_in_window_top
last validated record seq_num
-
uint64_t private_in_window
bitmask for replay detection
-
size_t private_in_hslen
current handshake message length, including the handshake header
-
int private_keep_current_message
drop or reuse current message on next call to record layer?
-
unsigned char private_send_alert
Determines if a fatal alert should be sent. Values:
0
, no alert is to be sent.1
, alert is to be sent.
-
unsigned char private_alert_type
Type of alert if send_alert != 0
-
int private_alert_reason
The error code to be returned to the user once the fatal alert has been sent.
-
uint8_t private_disable_datagram_packing
Disable packing multiple records within a single datagram.
-
uint8_t private_discard_early_data_record
-
uint32_t private_total_early_data_size
Number of received/written early data bytes
-
unsigned char *private_out_buf
output buffer
-
unsigned char *private_out_ctr
64-bit outgoing message counter
-
unsigned char *private_out_hdr
start of record header
-
unsigned char *private_out_cid
The start of the CID; (the end is marked by in_len).
-
unsigned char *private_out_len
two-bytes message length field
-
unsigned char *private_out_iv
ivlen-byte IV
-
unsigned char *private_out_msg
message contents (out_iv+ivlen)
-
int private_out_msgtype
record header: message type
-
size_t private_out_msglen
record header: message length
-
size_t private_out_left
amount of data not yet written
-
size_t private_out_buf_len
length of output buffer
-
unsigned char private_cur_out_ctr[MBEDTLS_SSL_SEQUENCE_NUMBER_LEN]
Outgoing record sequence number.
-
uint16_t private_mtu
path mtu, used to fragment outgoing messages
-
char *private_hostname
expected peer CN for verification (and SNI if available)
-
const char *private_alpn_chosen
negotiated protocol
-
mbedtls_dtls_srtp_info private_dtls_srtp_info
-
unsigned char *private_cli_id
transport-level ID of the client
-
size_t private_cli_id_len
length of cli_id
-
int private_secure_renegotiation
does peer support legacy or secure renegotiation
-
size_t private_verify_data_len
length of verify data stored
-
char private_own_verify_data[MBEDTLS_SSL_VERIFY_DATA_MAX_LEN]
previous handshake verify data
-
char private_peer_verify_data[MBEDTLS_SSL_VERIFY_DATA_MAX_LEN]
previous handshake verify data
-
unsigned char private_own_cid[MBEDTLS_SSL_CID_IN_LEN_MAX]
The next incoming CID, chosen by the user and applying to all subsequent handshakes. This may be different from the CID currently used in case the user has re-configured the CID after an initial handshake.
-
uint8_t private_own_cid_len
The length of
own_cid
.
-
uint8_t private_negotiate_cid
This indicates whether the CID extension should be negotiated in the next handshake or not. Possible values are MBEDTLS_SSL_CID_ENABLED and MBEDTLS_SSL_CID_DISABLED.
-
mbedtls_ssl_export_keys_t *private_f_export_keys
Callback to export key block and master secret
-
void *private_p_export_keys
context for key export callback
-
mbedtls_ssl_user_data_t private_user_data
User data pointer or handle.
The library sets this to
0
when creating a context and does not access it afterwards.Warning
Serializing and restoring an SSL context with mbedtls_ssl_context_save() and mbedtls_ssl_context_load() does not currently restore the user data.
-
const mbedtls_ssl_config *private_conf