SSL/TLS functions. More...

#include "mbedtls/platform_util.h"
#include "mbedtls/private_access.h"
#include "mbedtls/build_info.h"
#include "mbedtls/bignum.h"
#include "mbedtls/ecp.h"
#include "mbedtls/ssl_ciphersuites.h"
#include "mbedtls/x509_crt.h"
#include "mbedtls/x509_crl.h"
#include "mbedtls/dhm.h"
#include "mbedtls/ecdh.h"
#include "mbedtls/platform_time.h"
#include "psa/crypto.h"

Include dependency graph for ssl.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
union	mbedtls_ssl_premaster_secret

struct	mbedtls_ssl_tls13_application_secrets

struct	mbedtls_dtls_srtp_info_t

struct	mbedtls_ssl_session

struct	mbedtls_ssl_config

struct	mbedtls_ssl_context

Macros
#define	MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS -0x7000

#define	MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE -0x7080

#define	MBEDTLS_ERR_SSL_BAD_INPUT_DATA -0x7100

#define	MBEDTLS_ERR_SSL_INVALID_MAC -0x7180

#define	MBEDTLS_ERR_SSL_INVALID_RECORD -0x7200

#define	MBEDTLS_ERR_SSL_CONN_EOF -0x7280

#define	MBEDTLS_ERR_SSL_DECODE_ERROR -0x7300

#define	MBEDTLS_ERR_SSL_NO_RNG -0x7400

#define	MBEDTLS_ERR_SSL_NO_CLIENT_CERTIFICATE -0x7480

#define	MBEDTLS_ERR_SSL_UNSUPPORTED_EXTENSION -0x7500

#define	MBEDTLS_ERR_SSL_NO_APPLICATION_PROTOCOL -0x7580

#define	MBEDTLS_ERR_SSL_PRIVATE_KEY_REQUIRED -0x7600

#define	MBEDTLS_ERR_SSL_CA_CHAIN_REQUIRED -0x7680

#define	MBEDTLS_ERR_SSL_UNEXPECTED_MESSAGE -0x7700

#define	MBEDTLS_ERR_SSL_FATAL_ALERT_MESSAGE -0x7780

#define	MBEDTLS_ERR_SSL_UNRECOGNIZED_NAME -0x7800

#define	MBEDTLS_ERR_SSL_PEER_CLOSE_NOTIFY -0x7880

#define	MBEDTLS_ERR_SSL_BAD_CERTIFICATE -0x7A00

#define	MBEDTLS_ERR_SSL_ALLOC_FAILED -0x7F00

#define	MBEDTLS_ERR_SSL_HW_ACCEL_FAILED -0x7F80

#define	MBEDTLS_ERR_SSL_HW_ACCEL_FALLTHROUGH -0x6F80

#define	MBEDTLS_ERR_SSL_BAD_PROTOCOL_VERSION -0x6E80

#define	MBEDTLS_ERR_SSL_HANDSHAKE_FAILURE -0x6E00

#define	MBEDTLS_ERR_SSL_SESSION_TICKET_EXPIRED -0x6D80

#define	MBEDTLS_ERR_SSL_PK_TYPE_MISMATCH -0x6D00

#define	MBEDTLS_ERR_SSL_UNKNOWN_IDENTITY -0x6C80

#define	MBEDTLS_ERR_SSL_INTERNAL_ERROR -0x6C00

#define	MBEDTLS_ERR_SSL_COUNTER_WRAPPING -0x6B80

#define	MBEDTLS_ERR_SSL_WAITING_SERVER_HELLO_RENEGO -0x6B00

#define	MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED -0x6A80

#define	MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL -0x6A00

#define	MBEDTLS_ERR_SSL_WANT_READ -0x6900

#define	MBEDTLS_ERR_SSL_WANT_WRITE -0x6880

#define	MBEDTLS_ERR_SSL_TIMEOUT -0x6800

#define	MBEDTLS_ERR_SSL_CLIENT_RECONNECT -0x6780

#define	MBEDTLS_ERR_SSL_UNEXPECTED_RECORD -0x6700

#define	MBEDTLS_ERR_SSL_NON_FATAL -0x6680

#define	MBEDTLS_ERR_SSL_ILLEGAL_PARAMETER -0x6600

#define	MBEDTLS_ERR_SSL_CONTINUE_PROCESSING -0x6580

#define	MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS -0x6500

#define	MBEDTLS_ERR_SSL_EARLY_MESSAGE -0x6480

#define	MBEDTLS_ERR_SSL_UNEXPECTED_CID -0x6000

#define	MBEDTLS_ERR_SSL_VERSION_MISMATCH -0x5F00

#define	MBEDTLS_ERR_SSL_BAD_CONFIG -0x5E80

#define	MBEDTLS_SSL_IANA_TLS_GROUP_NONE 0

#define	MBEDTLS_SSL_IANA_TLS_GROUP_SECP192K1 0x0012

#define	MBEDTLS_SSL_IANA_TLS_GROUP_SECP192R1 0x0013

#define	MBEDTLS_SSL_IANA_TLS_GROUP_SECP224K1 0x0014

#define	MBEDTLS_SSL_IANA_TLS_GROUP_SECP224R1 0x0015

#define	MBEDTLS_SSL_IANA_TLS_GROUP_SECP256K1 0x0016

#define	MBEDTLS_SSL_IANA_TLS_GROUP_SECP256R1 0x0017

#define	MBEDTLS_SSL_IANA_TLS_GROUP_SECP384R1 0x0018

#define	MBEDTLS_SSL_IANA_TLS_GROUP_SECP521R1 0x0019

#define	MBEDTLS_SSL_IANA_TLS_GROUP_BP256R1 0x001A

#define	MBEDTLS_SSL_IANA_TLS_GROUP_BP384R1 0x001B

#define	MBEDTLS_SSL_IANA_TLS_GROUP_BP512R1 0x001C

#define	MBEDTLS_SSL_IANA_TLS_GROUP_X25519 0x001D

#define	MBEDTLS_SSL_IANA_TLS_GROUP_X448 0x001E

#define	MBEDTLS_SSL_IANA_TLS_GROUP_FFDHE2048 0x0100

#define	MBEDTLS_SSL_IANA_TLS_GROUP_FFDHE3072 0x0101

#define	MBEDTLS_SSL_IANA_TLS_GROUP_FFDHE4096 0x0102

#define	MBEDTLS_SSL_IANA_TLS_GROUP_FFDHE6144 0x0103

#define	MBEDTLS_SSL_IANA_TLS_GROUP_FFDHE8192 0x0104

#define	MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK ( 1u << 0 )

#define	MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL ( 1u << 1 )

#define	MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL ( 1u << 2 )

#define	MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_ALL

#define	MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_ALL

#define	MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL_ALL

#define	MBEDTLS_SSL_MAJOR_VERSION_3 3

#define	MBEDTLS_SSL_MINOR_VERSION_3 3

#define	MBEDTLS_SSL_MINOR_VERSION_4 4

#define	MBEDTLS_SSL_TRANSPORT_STREAM 0

#define	MBEDTLS_SSL_TRANSPORT_DATAGRAM 1

#define	MBEDTLS_SSL_MAX_HOST_NAME_LEN 255

#define	MBEDTLS_SSL_MAX_ALPN_NAME_LEN 255

#define	MBEDTLS_SSL_MAX_ALPN_LIST_LEN 65535

#define	MBEDTLS_SSL_MAX_FRAG_LEN_NONE 0

#define	MBEDTLS_SSL_MAX_FRAG_LEN_512 1

#define	MBEDTLS_SSL_MAX_FRAG_LEN_1024 2

#define	MBEDTLS_SSL_MAX_FRAG_LEN_2048 3

#define	MBEDTLS_SSL_MAX_FRAG_LEN_4096 4

#define	MBEDTLS_SSL_MAX_FRAG_LEN_INVALID 5

#define	MBEDTLS_SSL_IS_CLIENT 0

#define	MBEDTLS_SSL_IS_SERVER 1

#define	MBEDTLS_SSL_EXTENDED_MS_DISABLED 0

#define	MBEDTLS_SSL_EXTENDED_MS_ENABLED 1

#define	MBEDTLS_SSL_CID_DISABLED 0

#define	MBEDTLS_SSL_CID_ENABLED 1

#define	MBEDTLS_SSL_ETM_DISABLED 0

#define	MBEDTLS_SSL_ETM_ENABLED 1

#define	MBEDTLS_SSL_COMPRESS_NULL 0

#define	MBEDTLS_SSL_VERIFY_NONE 0

#define	MBEDTLS_SSL_VERIFY_OPTIONAL 1

#define	MBEDTLS_SSL_VERIFY_REQUIRED 2

#define	MBEDTLS_SSL_VERIFY_UNSET 3 /* Used only for sni_authmode */

#define	MBEDTLS_SSL_LEGACY_RENEGOTIATION 0

#define	MBEDTLS_SSL_SECURE_RENEGOTIATION 1

#define	MBEDTLS_SSL_RENEGOTIATION_DISABLED 0

#define	MBEDTLS_SSL_RENEGOTIATION_ENABLED 1

#define	MBEDTLS_SSL_ANTI_REPLAY_DISABLED 0

#define	MBEDTLS_SSL_ANTI_REPLAY_ENABLED 1

#define	MBEDTLS_SSL_RENEGOTIATION_NOT_ENFORCED -1

#define	MBEDTLS_SSL_RENEGO_MAX_RECORDS_DEFAULT 16

#define	MBEDTLS_SSL_LEGACY_NO_RENEGOTIATION 0

#define	MBEDTLS_SSL_LEGACY_ALLOW_RENEGOTIATION 1

#define	MBEDTLS_SSL_LEGACY_BREAK_HANDSHAKE 2

#define	MBEDTLS_SSL_TRUNC_HMAC_DISABLED 0

#define	MBEDTLS_SSL_TRUNC_HMAC_ENABLED 1

#define	MBEDTLS_SSL_TRUNCATED_HMAC_LEN 10 /* 80 bits, rfc 6066 section 7 */

#define	MBEDTLS_SSL_SESSION_TICKETS_DISABLED 0

#define	MBEDTLS_SSL_SESSION_TICKETS_ENABLED 1

#define	MBEDTLS_SSL_PRESET_DEFAULT 0

#define	MBEDTLS_SSL_PRESET_SUITEB 2

#define	MBEDTLS_SSL_CERT_REQ_CA_LIST_ENABLED 1

#define	MBEDTLS_SSL_CERT_REQ_CA_LIST_DISABLED 0

#define	MBEDTLS_SSL_DTLS_SRTP_MKI_UNSUPPORTED 0

#define	MBEDTLS_SSL_DTLS_SRTP_MKI_SUPPORTED 1

#define	MBEDTLS_SSL_SRV_CIPHERSUITE_ORDER_CLIENT 1

#define	MBEDTLS_SSL_SRV_CIPHERSUITE_ORDER_SERVER 0

#define	MBEDTLS_SSL_DTLS_TIMEOUT_DFL_MIN 1000

#define	MBEDTLS_SSL_DTLS_TIMEOUT_DFL_MAX 60000

#define	MBEDTLS_SSL_VERIFY_DATA_MAX_LEN 12

#define	MBEDTLS_SSL_EMPTY_RENEGOTIATION_INFO 0xFF

#define	MBEDTLS_SSL_HASH_NONE 0

#define	MBEDTLS_SSL_HASH_MD5 1

#define	MBEDTLS_SSL_HASH_SHA1 2

#define	MBEDTLS_SSL_HASH_SHA224 3

#define	MBEDTLS_SSL_HASH_SHA256 4

#define	MBEDTLS_SSL_HASH_SHA384 5

#define	MBEDTLS_SSL_HASH_SHA512 6

#define	MBEDTLS_SSL_SIG_ANON 0

#define	MBEDTLS_SSL_SIG_RSA 1

#define	MBEDTLS_SSL_SIG_ECDSA 3

#define	MBEDTLS_TLS1_3_SIG_RSA_PKCS1_SHA256 0x0401

#define	MBEDTLS_TLS1_3_SIG_RSA_PKCS1_SHA384 0x0501

#define	MBEDTLS_TLS1_3_SIG_RSA_PKCS1_SHA512 0x0601

#define	MBEDTLS_TLS1_3_SIG_ECDSA_SECP256R1_SHA256 0x0403

#define	MBEDTLS_TLS1_3_SIG_ECDSA_SECP384R1_SHA384 0x0503

#define	MBEDTLS_TLS1_3_SIG_ECDSA_SECP521R1_SHA512 0x0603

#define	MBEDTLS_TLS1_3_SIG_RSA_PSS_RSAE_SHA256 0x0804

#define	MBEDTLS_TLS1_3_SIG_RSA_PSS_RSAE_SHA384 0x0805

#define	MBEDTLS_TLS1_3_SIG_RSA_PSS_RSAE_SHA512 0x0806

#define	MBEDTLS_TLS1_3_SIG_ED25519 0x0807

#define	MBEDTLS_TLS1_3_SIG_ED448 0x0808

#define	MBEDTLS_TLS1_3_SIG_RSA_PSS_PSS_SHA256 0x0809

#define	MBEDTLS_TLS1_3_SIG_RSA_PSS_PSS_SHA384 0x080A

#define	MBEDTLS_TLS1_3_SIG_RSA_PSS_PSS_SHA512 0x080B

#define	MBEDTLS_TLS1_3_SIG_RSA_PKCS1_SHA1 0x0201

#define	MBEDTLS_TLS1_3_SIG_ECDSA_SHA1 0x0203

#define	MBEDTLS_TLS1_3_SIG_NONE 0x0

#define	MBEDTLS_SSL_CERT_TYPE_RSA_SIGN 1

#define	MBEDTLS_SSL_CERT_TYPE_ECDSA_SIGN 64

#define	MBEDTLS_SSL_MSG_CHANGE_CIPHER_SPEC 20

#define	MBEDTLS_SSL_MSG_ALERT 21

#define	MBEDTLS_SSL_MSG_HANDSHAKE 22

#define	MBEDTLS_SSL_MSG_APPLICATION_DATA 23

#define	MBEDTLS_SSL_MSG_CID 25

#define	MBEDTLS_SSL_ALERT_LEVEL_WARNING 1

#define	MBEDTLS_SSL_ALERT_LEVEL_FATAL 2

#define	MBEDTLS_SSL_ALERT_MSG_CLOSE_NOTIFY 0 /* 0x00 */

#define	MBEDTLS_SSL_ALERT_MSG_UNEXPECTED_MESSAGE 10 /* 0x0A */

#define	MBEDTLS_SSL_ALERT_MSG_BAD_RECORD_MAC 20 /* 0x14 */

#define	MBEDTLS_SSL_ALERT_MSG_DECRYPTION_FAILED 21 /* 0x15 */

#define	MBEDTLS_SSL_ALERT_MSG_RECORD_OVERFLOW 22 /* 0x16 */

#define	MBEDTLS_SSL_ALERT_MSG_DECOMPRESSION_FAILURE 30 /* 0x1E */

#define	MBEDTLS_SSL_ALERT_MSG_HANDSHAKE_FAILURE 40 /* 0x28 */

#define	MBEDTLS_SSL_ALERT_MSG_NO_CERT 41 /* 0x29 */

#define	MBEDTLS_SSL_ALERT_MSG_BAD_CERT 42 /* 0x2A */

#define	MBEDTLS_SSL_ALERT_MSG_UNSUPPORTED_CERT 43 /* 0x2B */

#define	MBEDTLS_SSL_ALERT_MSG_CERT_REVOKED 44 /* 0x2C */

#define	MBEDTLS_SSL_ALERT_MSG_CERT_EXPIRED 45 /* 0x2D */

#define	MBEDTLS_SSL_ALERT_MSG_CERT_UNKNOWN 46 /* 0x2E */

#define	MBEDTLS_SSL_ALERT_MSG_ILLEGAL_PARAMETER 47 /* 0x2F */

#define	MBEDTLS_SSL_ALERT_MSG_UNKNOWN_CA 48 /* 0x30 */

#define	MBEDTLS_SSL_ALERT_MSG_ACCESS_DENIED 49 /* 0x31 */

#define	MBEDTLS_SSL_ALERT_MSG_DECODE_ERROR 50 /* 0x32 */

#define	MBEDTLS_SSL_ALERT_MSG_DECRYPT_ERROR 51 /* 0x33 */

#define	MBEDTLS_SSL_ALERT_MSG_EXPORT_RESTRICTION 60 /* 0x3C */

#define	MBEDTLS_SSL_ALERT_MSG_PROTOCOL_VERSION 70 /* 0x46 */

#define	MBEDTLS_SSL_ALERT_MSG_INSUFFICIENT_SECURITY 71 /* 0x47 */

#define	MBEDTLS_SSL_ALERT_MSG_INTERNAL_ERROR 80 /* 0x50 */

#define	MBEDTLS_SSL_ALERT_MSG_INAPROPRIATE_FALLBACK 86 /* 0x56 */

#define	MBEDTLS_SSL_ALERT_MSG_USER_CANCELED 90 /* 0x5A */

#define	MBEDTLS_SSL_ALERT_MSG_NO_RENEGOTIATION 100 /* 0x64 */

#define	MBEDTLS_SSL_ALERT_MSG_UNSUPPORTED_EXT 110 /* 0x6E */

#define	MBEDTLS_SSL_ALERT_MSG_UNRECOGNIZED_NAME 112 /* 0x70 */

#define	MBEDTLS_SSL_ALERT_MSG_UNKNOWN_PSK_IDENTITY 115 /* 0x73 */

#define	MBEDTLS_SSL_ALERT_MSG_NO_APPLICATION_PROTOCOL 120 /* 0x78 */

#define	MBEDTLS_SSL_HS_HELLO_REQUEST 0

#define	MBEDTLS_SSL_HS_CLIENT_HELLO 1

#define	MBEDTLS_SSL_HS_SERVER_HELLO 2

#define	MBEDTLS_SSL_HS_HELLO_VERIFY_REQUEST 3

#define	MBEDTLS_SSL_HS_NEW_SESSION_TICKET 4

#define	MBEDTLS_SSL_HS_ENCRYPTED_EXTENSIONS 8

#define	MBEDTLS_SSL_HS_CERTIFICATE 11

#define	MBEDTLS_SSL_HS_SERVER_KEY_EXCHANGE 12

#define	MBEDTLS_SSL_HS_CERTIFICATE_REQUEST 13

#define	MBEDTLS_SSL_HS_SERVER_HELLO_DONE 14

#define	MBEDTLS_SSL_HS_CERTIFICATE_VERIFY 15

#define	MBEDTLS_SSL_HS_CLIENT_KEY_EXCHANGE 16

#define	MBEDTLS_SSL_HS_FINISHED 20

#define	MBEDTLS_TLS_EXT_SERVERNAME 0

#define	MBEDTLS_TLS_EXT_SERVERNAME_HOSTNAME 0

#define	MBEDTLS_TLS_EXT_MAX_FRAGMENT_LENGTH 1

#define	MBEDTLS_TLS_EXT_TRUNCATED_HMAC 4

#define	MBEDTLS_TLS_EXT_STATUS_REQUEST 5 /* RFC 6066 TLS 1.2 and 1.3 */

#define	MBEDTLS_TLS_EXT_SUPPORTED_ELLIPTIC_CURVES 10

#define	MBEDTLS_TLS_EXT_SUPPORTED_GROUPS 10 /* RFC 8422,7919 TLS 1.2 and 1.3 */

#define	MBEDTLS_TLS_EXT_SUPPORTED_POINT_FORMATS 11

#define	MBEDTLS_TLS_EXT_SIG_ALG 13 /* RFC 8446 TLS 1.3 */

#define	MBEDTLS_TLS_EXT_USE_SRTP 14

#define	MBEDTLS_TLS_EXT_HEARTBEAT 15 /* RFC 6520 TLS 1.2 and 1.3 */

#define	MBEDTLS_TLS_EXT_ALPN 16

#define	MBEDTLS_TLS_EXT_SCT 18 /* RFC 6962 TLS 1.2 and 1.3 */

#define	MBEDTLS_TLS_EXT_CLI_CERT_TYPE 19 /* RFC 7250 TLS 1.2 and 1.3 */

#define	MBEDTLS_TLS_EXT_SERV_CERT_TYPE 20 /* RFC 7250 TLS 1.2 and 1.3 */

#define	MBEDTLS_TLS_EXT_PADDING 21 /* RFC 7685 TLS 1.2 and 1.3 */

#define	MBEDTLS_TLS_EXT_ENCRYPT_THEN_MAC 22 /* 0x16 */

#define	MBEDTLS_TLS_EXT_EXTENDED_MASTER_SECRET 0x0017 /* 23 */

#define	MBEDTLS_TLS_EXT_SESSION_TICKET 35

#define	MBEDTLS_TLS_EXT_PRE_SHARED_KEY 41 /* RFC 8446 TLS 1.3 */

#define	MBEDTLS_TLS_EXT_EARLY_DATA 42 /* RFC 8446 TLS 1.3 */

#define	MBEDTLS_TLS_EXT_SUPPORTED_VERSIONS 43 /* RFC 8446 TLS 1.3 */

#define	MBEDTLS_TLS_EXT_COOKIE 44 /* RFC 8446 TLS 1.3 */

#define	MBEDTLS_TLS_EXT_PSK_KEY_EXCHANGE_MODES 45 /* RFC 8446 TLS 1.3 */

#define	MBEDTLS_TLS_EXT_CERT_AUTH 47 /* RFC 8446 TLS 1.3 */

#define	MBEDTLS_TLS_EXT_OID_FILTERS 48 /* RFC 8446 TLS 1.3 */

#define	MBEDTLS_TLS_EXT_POST_HANDSHAKE_AUTH 49 /* RFC 8446 TLS 1.3 */

#define	MBEDTLS_TLS_EXT_SIG_ALG_CERT 50 /* RFC 8446 TLS 1.3 */

#define	MBEDTLS_TLS_EXT_KEY_SHARE 51 /* RFC 8446 TLS 1.3 */

#define	MBEDTLS_TLS_EXT_ECJPAKE_KKPP 256 /* experimental */

#define	MBEDTLS_TLS_EXT_RENEGOTIATION_INFO 0xFF01

#define	MBEDTLS_PSK_MAX_LEN 32 /* 256 bits */

#define	MBEDTLS_PREMASTER_SIZE sizeof( union mbedtls_ssl_premaster_secret )

#define	MBEDTLS_TLS1_3_MD_MAX_SIZE MBEDTLS_MD_MAX_SIZE

#define	MBEDTLS_SSL_SEQUENCE_NUMBER_LEN 8

#define	MBEDTLS_TLS_SRTP_MAX_MKI_LENGTH 255

#define	MBEDTLS_TLS_SRTP_MAX_PROFILE_LIST_LENGTH 4

#define	MBEDTLS_TLS_SRTP_AES128_CM_HMAC_SHA1_80 ( (uint16_t) 0x0001)

#define	MBEDTLS_TLS_SRTP_AES128_CM_HMAC_SHA1_32 ( (uint16_t) 0x0002)

#define	MBEDTLS_TLS_SRTP_NULL_HMAC_SHA1_80 ( (uint16_t) 0x0005)

#define	MBEDTLS_TLS_SRTP_NULL_HMAC_SHA1_32 ( (uint16_t) 0x0006)

#define	MBEDTLS_TLS_SRTP_UNSET ( (uint16_t) 0x0000)

#define	MBEDTLS_SSL_UNEXPECTED_CID_IGNORE 0

#define	MBEDTLS_SSL_UNEXPECTED_CID_FAIL 1

SECTION: Module settings
The configuration options you can set for this module are in this section. Either change them in mbedtls_config.h or define them on the compiler command line.
#define	MBEDTLS_SSL_IN_CONTENT_LEN 16384

#define	MBEDTLS_SSL_OUT_CONTENT_LEN 16384

#define	MBEDTLS_SSL_DTLS_MAX_BUFFERING 32768

#define	MBEDTLS_SSL_CID_IN_LEN_MAX 32

#define	MBEDTLS_SSL_CID_OUT_LEN_MAX 32

#define	MBEDTLS_SSL_CID_TLS1_3_PADDING_GRANULARITY 16

SECTION: Module configuration options
This section allows for the setting of module specific sizes and configuration options. The default values are already present in the relevant header files and should suffice for the regular use cases. Our advice is to enable options and change their values here only if you have a good reason and know the consequences. Please check the respective header file for documentation on these parameters (to prevent duplicate documentation).
#define	MBEDTLS_TLS_EXT_CID 254 /* TBD */

Typedefs
typedef int	mbedtls_ssl_send_t (void ctx, const unsigned char buf, size_t len)
	Callback type: send data on the network. More...

typedef int	mbedtls_ssl_recv_t (void ctx, unsigned char buf, size_t len)
	Callback type: receive data from the network. More...

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. More...

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. More...

typedef int	mbedtls_ssl_get_timer_t (void *ctx)
	Callback type: get status of timers/delays. More...

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. More...

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. More...

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. More...

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. More...

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. More...

typedef void	mbedtls_ssl_async_cancel_t (mbedtls_ssl_context *ssl)
	Callback type: cancel external operation. More...

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. More...

typedef int	mbedtls_ssl_ticket_write_t (void p_ticket, const mbedtls_ssl_session session, unsigned char start, const unsigned char end, size_t tlen, uint32_t lifetime)
	Callback type: generate and write session ticket. More...

typedef int	mbedtls_ssl_ticket_parse_t (void p_ticket, mbedtls_ssl_session session, unsigned char *buf, size_t len)
	Callback type: parse and load session ticket. More...

typedef int	mbedtls_ssl_cookie_write_t (void ctx, unsigned char p, unsigned char end, const unsigned char *info, size_t ilen)
	Callback type: generate a cookie. More...

typedef int	mbedtls_ssl_cookie_check_t (void ctx, const unsigned char cookie, size_t clen, const unsigned char *info, size_t ilen)
	Callback type: verify a cookie. More...

Enumerations
enum	mbedtls_ssl_states { MBEDTLS_SSL_HELLO_REQUEST, MBEDTLS_SSL_CLIENT_HELLO, MBEDTLS_SSL_SERVER_HELLO, MBEDTLS_SSL_SERVER_CERTIFICATE, MBEDTLS_SSL_SERVER_KEY_EXCHANGE, MBEDTLS_SSL_CERTIFICATE_REQUEST, MBEDTLS_SSL_SERVER_HELLO_DONE, MBEDTLS_SSL_CLIENT_CERTIFICATE, MBEDTLS_SSL_CLIENT_KEY_EXCHANGE, MBEDTLS_SSL_CERTIFICATE_VERIFY, MBEDTLS_SSL_CLIENT_CHANGE_CIPHER_SPEC, MBEDTLS_SSL_CLIENT_FINISHED, MBEDTLS_SSL_SERVER_CHANGE_CIPHER_SPEC, MBEDTLS_SSL_SERVER_FINISHED, MBEDTLS_SSL_FLUSH_BUFFERS, MBEDTLS_SSL_HANDSHAKE_WRAPUP, MBEDTLS_SSL_HANDSHAKE_OVER, MBEDTLS_SSL_SERVER_NEW_SESSION_TICKET, MBEDTLS_SSL_SERVER_HELLO_VERIFY_REQUEST_SENT, MBEDTLS_SSL_ENCRYPTED_EXTENSIONS, MBEDTLS_SSL_CLIENT_CERTIFICATE_VERIFY, MBEDTLS_SSL_CLIENT_CCS_AFTER_SERVER_FINISHED }

enum	mbedtls_tls_prf_types { MBEDTLS_SSL_TLS_PRF_NONE, MBEDTLS_SSL_TLS_PRF_SHA384, MBEDTLS_SSL_TLS_PRF_SHA256, MBEDTLS_SSL_HKDF_EXPAND_SHA384, MBEDTLS_SSL_HKDF_EXPAND_SHA256 }

enum	mbedtls_ssl_key_export_type { MBEDTLS_SSL_KEY_EXPORT_TLS12_MASTER_SECRET = 0, MBEDTLS_SSL_KEY_EXPORT_TLS1_3_CLIENT_EARLY_SECRET, MBEDTLS_SSL_KEY_EXPORT_TLS1_3_EARLY_EXPORTER_SECRET, MBEDTLS_SSL_KEY_EXPORT_TLS1_3_CLIENT_HANDSHAKE_TRAFFIC_SECRET, MBEDTLS_SSL_KEY_EXPORT_TLS1_3_SERVER_HANDSHAKE_TRAFFIC_SECRET, MBEDTLS_SSL_KEY_EXPORT_TLS1_3_CLIENT_APPLICATION_TRAFFIC_SECRET, MBEDTLS_SSL_KEY_EXPORT_TLS1_3_SERVER_APPLICATION_TRAFFIC_SECRET }

Functions
const char *	mbedtls_ssl_get_ciphersuite_name (const int ciphersuite_id)
	Return the name of the ciphersuite associated with the given ID. More...

int	mbedtls_ssl_get_ciphersuite_id (const char *ciphersuite_name)
	Return the ID of the ciphersuite associated with the given name. More...

void	mbedtls_ssl_init (mbedtls_ssl_context *ssl)
	Initialize an SSL context Just makes the context ready for mbedtls_ssl_setup() or mbedtls_ssl_free() More...

int	mbedtls_ssl_setup (mbedtls_ssl_context ssl, const mbedtls_ssl_config conf)
	Set up an SSL context for use. More...

int	mbedtls_ssl_session_reset (mbedtls_ssl_context *ssl)
	Reset an already initialized SSL context for re-use while retaining application-set variables, function pointers and data. More...

void	mbedtls_ssl_conf_endpoint (mbedtls_ssl_config *conf, int endpoint)
	Set the current endpoint type. More...

void	mbedtls_ssl_conf_transport (mbedtls_ssl_config *conf, int transport)
	Set the transport type (TLS or DTLS). Default: TLS. More...

void	mbedtls_ssl_conf_authmode (mbedtls_ssl_config *conf, int authmode)
	Set the certificate verification mode Default: NONE on server, REQUIRED on client. More...

void	mbedtls_ssl_conf_verify (mbedtls_ssl_config conf, int(f_vrfy)(void , mbedtls_x509_crt , int, uint32_t ), void p_vrfy)
	Set the verification callback (Optional). More...

void	mbedtls_ssl_conf_rng (mbedtls_ssl_config conf, int(f_rng)(void , unsigned char , size_t), void *p_rng)
	Set the random number generator callback. More...

void	mbedtls_ssl_conf_dbg (mbedtls_ssl_config conf, void(f_dbg)(void , int, const char , int, const char ), void p_dbg)
	Set the debug callback. More...

void	mbedtls_ssl_set_bio (mbedtls_ssl_context ssl, void p_bio, 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. More...

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. More...

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. More...

void	mbedtls_ssl_set_mtu (mbedtls_ssl_context *ssl, uint16_t mtu)
	Set the Maximum Tranport Unit (MTU). Special value: 0 means unset (no limit). This represents the maximum size of a datagram payload handled by the transport layer (usually UDP) as determined by the network link and stack. In practice, this controls the maximum size datagram the DTLS layer will pass to the `f_send()` callback set using `mbedtls_ssl_set_bio()`. More...

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). More...

void	mbedtls_ssl_conf_read_timeout (mbedtls_ssl_config *conf, uint32_t timeout)
	Set the timeout period for mbedtls_ssl_read() (Default: no timeout.) More...

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). More...

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.) More...

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.) More...

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.) More...

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. More...

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(). More...

void *	mbedtls_ssl_get_async_operation_data (const mbedtls_ssl_context *ssl)
	Retrieve the asynchronous operation user context. More...

void	mbedtls_ssl_set_async_operation_data (mbedtls_ssl_context ssl, void ctx)
	Retrieve the asynchronous operation user context. More...

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.) More...

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.) More...

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. More...

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). More...

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. More...

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.) More...

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). More...

int	mbedtls_ssl_set_session (mbedtls_ssl_context ssl, const mbedtls_ssl_session session)
	Load a session for session resumption. More...

int	mbedtls_ssl_session_load (mbedtls_ssl_session session, const unsigned char buf, size_t len)
	Load serialized session data into a session structure. On client, this can be used for loading saved sessions before resuming them with mbedstls_ssl_set_session(). On server, this can be used for alternative implementations of session cache or session tickets. More...

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. More...

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. More...

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. More...

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. More...

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. More...

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. More...

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. More...

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. More...

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. More...

int	mbedtls_ssl_conf_psk_opaque (mbedtls_ssl_config conf, psa_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. More...

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. More...

int	mbedtls_ssl_set_hs_psk_opaque (mbedtls_ssl_context *ssl, psa_key_id_t psk)
	Set an opaque pre-shared Key (PSK) for the current handshake. More...

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). More...

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) More...

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) More...

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.) More...

void	mbedtls_ssl_conf_groups (mbedtls_ssl_config conf, const uint16_t groups)
	Set the allowed groups in order of preference. More...

void	mbedtls_ssl_conf_sig_hashes (mbedtls_ssl_config conf, const int hashes)
	Set the allowed hashes for signatures during the handshake. More...

void	mbedtls_ssl_conf_sig_algs (mbedtls_ssl_config conf, const uint16_t sig_algs)
	Configure allowed signature algorithms for use in TLS 1.3. More...

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) More...

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. More...

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. More...

void	mbedtls_ssl_set_hs_authmode (mbedtls_ssl_context *ssl, int authmode)
	Set authmode for the current handshake. More...

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). More...

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. More...

int	mbedtls_ssl_conf_alpn_protocols (mbedtls_ssl_config conf, const char *protos)
	Set the supported Application Layer Protocols. More...

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. More...

static 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. More...

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. More...

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. More...

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 informations: Protection profile and MKI value. More...

void	mbedtls_ssl_conf_max_version (mbedtls_ssl_config *conf, int major, int minor)
	Set the maximum supported version sent from the client side and/or accepted at the server side (Default: MBEDTLS_SSL_MAX_MAJOR_VERSION, MBEDTLS_SSL_MAX_MINOR_VERSION) More...

void	mbedtls_ssl_conf_min_version (mbedtls_ssl_config *conf, int major, int minor)
	Set the minimum accepted SSL/TLS protocol version (Default: TLS 1.2) More...

void	mbedtls_ssl_conf_encrypt_then_mac (mbedtls_ssl_config *conf, char etm)
	Enable or disable Encrypt-then-MAC (Default: MBEDTLS_SSL_ETM_ENABLED) More...

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) More...

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) More...

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) More...

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) More...

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.) More...

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) More...

void	mbedtls_ssl_conf_legacy_renegotiation (mbedtls_ssl_config *conf, int allow_legacy)
	Prevent or allow legacy renegotiation. (Default: MBEDTLS_SSL_LEGACY_NO_RENEGOTIATION) More...

void	mbedtls_ssl_conf_renegotiation_enforced (mbedtls_ssl_config *conf, int max_records)
	Enforce renegotiation requests. (Default: enforced, max_records = 16) More...

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) More...

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. More...

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. More...

uint32_t	mbedtls_ssl_get_verify_result (const mbedtls_ssl_context *ssl)
	Return the result of the certificate verification. More...

const char *	mbedtls_ssl_get_ciphersuite (const mbedtls_ssl_context *ssl)
	Return the name of the current ciphersuite. More...

const char *	mbedtls_ssl_get_version (const mbedtls_ssl_context *ssl)
	Return the current TLS version. More...

int	mbedtls_ssl_get_record_expansion (const mbedtls_ssl_context *ssl)
	Return the (maximum) number of bytes added by the record layer: header + encryption/MAC overhead (inc. padding) More...

int	mbedtls_ssl_get_max_out_record_payload (const mbedtls_ssl_context *ssl)
	Return the current maximum outgoing record payload in bytes. More...

int	mbedtls_ssl_get_max_in_record_payload (const mbedtls_ssl_context *ssl)
	Return the current maximum incoming record payload in bytes. More...

const mbedtls_x509_crt *	mbedtls_ssl_get_peer_cert (const mbedtls_ssl_context *ssl)
	Return the peer certificate from the current connection. More...

int	mbedtls_ssl_get_session (const mbedtls_ssl_context ssl, mbedtls_ssl_session session)
	Export a session in order to resume it later. More...

int	mbedtls_ssl_handshake (mbedtls_ssl_context *ssl)
	Perform the SSL handshake. More...

int	mbedtls_ssl_handshake_step (mbedtls_ssl_context *ssl)
	Perform a single step of the SSL handshake. More...

int	mbedtls_ssl_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. More...

int	mbedtls_ssl_read (mbedtls_ssl_context ssl, unsigned char buf, size_t len)
	Read at most 'len' application data bytes. More...

int	mbedtls_ssl_write (mbedtls_ssl_context ssl, const unsigned char buf, size_t len)
	Try to write exactly 'len' application data bytes. More...

int	mbedtls_ssl_send_alert_message (mbedtls_ssl_context *ssl, unsigned char level, unsigned char message)
	Send an alert message. More...

int	mbedtls_ssl_close_notify (mbedtls_ssl_context *ssl)
	Notify the peer that the connection is being closed. More...

void	mbedtls_ssl_free (mbedtls_ssl_context *ssl)
	Free referenced items in an SSL context and clear memory. More...

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. More...

int	mbedtls_ssl_context_load (mbedtls_ssl_context ssl, const unsigned char buf, size_t len)
	Load serialized connection data to an SSL context. More...

void	mbedtls_ssl_config_init (mbedtls_ssl_config *conf)
	Initialize an SSL configuration context Just makes the context ready for mbedtls_ssl_config_defaults() or mbedtls_ssl_config_free(). More...

int	mbedtls_ssl_config_defaults (mbedtls_ssl_config *conf, int endpoint, int transport, int preset)
	Load reasonnable default SSL configuration values. (You need to call mbedtls_ssl_config_init() first.) More...

void	mbedtls_ssl_config_free (mbedtls_ssl_config *conf)
	Free an SSL configuration context. More...

void	mbedtls_ssl_session_init (mbedtls_ssl_session *session)
	Initialize SSL session structure. More...

void	mbedtls_ssl_session_free (mbedtls_ssl_session *session)
	Free referenced items in an SSL session including the peer certificate and clear memory. More...

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. More...

Detailed Description

SSL/TLS functions.

Definition in file ssl.h.

Macro Definition Documentation

#define MBEDTLS_ERR_SSL_ALLOC_FAILED -0x7F00

Memory allocation failed

Definition at line 112 of file ssl.h.

#define MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS -0x6500

The asynchronous operation is not completed yet.

Definition at line 155 of file ssl.h.

#define MBEDTLS_ERR_SSL_BAD_CERTIFICATE -0x7A00

Processing of the Certificate handshake message failed.

Definition at line 101 of file ssl.h.

#define MBEDTLS_ERR_SSL_BAD_CONFIG -0x5E80

Invalid value in SSL config

Definition at line 171 of file ssl.h.

#define MBEDTLS_ERR_SSL_BAD_INPUT_DATA -0x7100

Bad input parameters to function.

Definition at line 68 of file ssl.h.

#define MBEDTLS_ERR_SSL_BAD_PROTOCOL_VERSION -0x6E80

Handshake protocol not within min/max boundaries

Definition at line 118 of file ssl.h.

#define MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL -0x6A00

A buffer is too small to receive or write a message

Definition at line 136 of file ssl.h.

#define MBEDTLS_ERR_SSL_CA_CHAIN_REQUIRED -0x7680

No CA Chain is set, but required to operate.

Definition at line 89 of file ssl.h.

#define MBEDTLS_ERR_SSL_CLIENT_RECONNECT -0x6780

The client initiated a reconnect from the same port.

Definition at line 145 of file ssl.h.

#define MBEDTLS_ERR_SSL_CONN_EOF -0x7280

The connection indicated an EOF.

Definition at line 74 of file ssl.h.

#define MBEDTLS_ERR_SSL_CONTINUE_PROCESSING -0x6580

Internal-only message signaling that further message-processing should be done

Definition at line 153 of file ssl.h.

#define MBEDTLS_ERR_SSL_COUNTER_WRAPPING -0x6B80

A counter would wrap (eg, too many messages exchanged).

Definition at line 130 of file ssl.h.

#define MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS -0x7000

A cryptographic operation is in progress. Try again later.

Definition at line 64 of file ssl.h.

#define MBEDTLS_ERR_SSL_DECODE_ERROR -0x7300

A message could not be parsed due to a syntactic error.

Definition at line 76 of file ssl.h.

#define MBEDTLS_ERR_SSL_EARLY_MESSAGE -0x6480

Internal-only message signaling that a message arrived early.

Definition at line 157 of file ssl.h.

#define MBEDTLS_ERR_SSL_FATAL_ALERT_MESSAGE -0x7780

A fatal alert message was received from our peer.

Definition at line 93 of file ssl.h.

#define MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE -0x7080

The requested feature is not available.

Definition at line 66 of file ssl.h.

#define MBEDTLS_ERR_SSL_HANDSHAKE_FAILURE -0x6E00

The handshake negotiation failed.

Definition at line 120 of file ssl.h.

#define MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED -0x6A80

DTLS client must retry for hello verification

Definition at line 134 of file ssl.h.

#define MBEDTLS_ERR_SSL_HW_ACCEL_FAILED -0x7F80

Hardware acceleration function returned with error

Definition at line 114 of file ssl.h.

#define MBEDTLS_ERR_SSL_HW_ACCEL_FALLTHROUGH -0x6F80

Hardware acceleration function skipped / left alone data

Definition at line 116 of file ssl.h.

#define MBEDTLS_ERR_SSL_ILLEGAL_PARAMETER -0x6600

A field in a message was incorrect or inconsistent with other fields.

Definition at line 151 of file ssl.h.

#define MBEDTLS_ERR_SSL_INTERNAL_ERROR -0x6C00

Internal error (eg, unexpected failure in lower-level module)

Definition at line 128 of file ssl.h.

#define MBEDTLS_ERR_SSL_INVALID_MAC -0x7180

Verification of the message MAC failed.

Definition at line 70 of file ssl.h.

#define MBEDTLS_ERR_SSL_INVALID_RECORD -0x7200

An invalid SSL record was received.

Definition at line 72 of file ssl.h.

#define MBEDTLS_ERR_SSL_NO_APPLICATION_PROTOCOL -0x7580

No ALPN protocols supported that the client advertises

Definition at line 85 of file ssl.h.

#define MBEDTLS_ERR_SSL_NO_CLIENT_CERTIFICATE -0x7480

No client certification received from the client, but required by the authentication mode.

Definition at line 81 of file ssl.h.

#define MBEDTLS_ERR_SSL_NO_RNG -0x7400

No RNG was provided to the SSL module.

Definition at line 79 of file ssl.h.

#define MBEDTLS_ERR_SSL_NON_FATAL -0x6680

The alert message received indicates a non-fatal error.

Definition at line 149 of file ssl.h.

#define MBEDTLS_ERR_SSL_PEER_CLOSE_NOTIFY -0x7880

The peer notified us that the connection is going to be closed.

Definition at line 97 of file ssl.h.

#define MBEDTLS_ERR_SSL_PK_TYPE_MISMATCH -0x6D00

Public key type mismatch (eg, asked for RSA key exchange and presented EC key)

Definition at line 124 of file ssl.h.

#define MBEDTLS_ERR_SSL_PRIVATE_KEY_REQUIRED -0x7600

The own private key or pre-shared key is not set, but needed.

Definition at line 87 of file ssl.h.

#define MBEDTLS_ERR_SSL_SESSION_TICKET_EXPIRED -0x6D80

Session ticket has expired.

Definition at line 122 of file ssl.h.

#define MBEDTLS_ERR_SSL_TIMEOUT -0x6800

The operation timed out.

Definition at line 143 of file ssl.h.

#define MBEDTLS_ERR_SSL_UNEXPECTED_CID -0x6000

An encrypted DTLS-frame with an unexpected CID was received.

Definition at line 167 of file ssl.h.

#define MBEDTLS_ERR_SSL_UNEXPECTED_MESSAGE -0x7700

An unexpected message was received from our peer.

Definition at line 91 of file ssl.h.

#define MBEDTLS_ERR_SSL_UNEXPECTED_RECORD -0x6700

Record header looks valid but is not expected.

Definition at line 147 of file ssl.h.

#define MBEDTLS_ERR_SSL_UNKNOWN_IDENTITY -0x6C80

Unknown identity received (eg, PSK identity)

Definition at line 126 of file ssl.h.

#define MBEDTLS_ERR_SSL_UNRECOGNIZED_NAME -0x7800

No server could be identified matching the client's SNI.

Definition at line 95 of file ssl.h.

#define MBEDTLS_ERR_SSL_UNSUPPORTED_EXTENSION -0x7500

Client received an extended server hello containing an unsupported extension

Definition at line 83 of file ssl.h.

#define MBEDTLS_ERR_SSL_VERSION_MISMATCH -0x5F00

An operation failed due to an unexpected version or configuration.

Definition at line 169 of file ssl.h.

#define MBEDTLS_ERR_SSL_WAITING_SERVER_HELLO_RENEGO -0x6B00

Unexpected message at ServerHello in renegotiation.

Definition at line 132 of file ssl.h.

#define MBEDTLS_ERR_SSL_WANT_READ -0x6900

No data of requested type currently available on underlying transport.

Definition at line 139 of file ssl.h.

#define MBEDTLS_ERR_SSL_WANT_WRITE -0x6880

Connection requires a write call.

Definition at line 141 of file ssl.h.

#define MBEDTLS_PREMASTER_SIZE sizeof( union mbedtls_ssl_premaster_secret )

Definition at line 612 of file ssl.h.

#define MBEDTLS_PSK_MAX_LEN 32 /* 256 bits */

Definition at line 575 of file ssl.h.

#define MBEDTLS_SSL_ALERT_LEVEL_FATAL 2

Definition at line 469 of file ssl.h.

#define MBEDTLS_SSL_ALERT_LEVEL_WARNING 1

Definition at line 468 of file ssl.h.

#define MBEDTLS_SSL_ALERT_MSG_ACCESS_DENIED 49 /* 0x31 */

Definition at line 486 of file ssl.h.

#define MBEDTLS_SSL_ALERT_MSG_BAD_CERT 42 /* 0x2A */

Definition at line 479 of file ssl.h.

#define MBEDTLS_SSL_ALERT_MSG_BAD_RECORD_MAC 20 /* 0x14 */

Definition at line 473 of file ssl.h.

#define MBEDTLS_SSL_ALERT_MSG_CERT_EXPIRED 45 /* 0x2D */

Definition at line 482 of file ssl.h.

#define MBEDTLS_SSL_ALERT_MSG_CERT_REVOKED 44 /* 0x2C */

Definition at line 481 of file ssl.h.

#define MBEDTLS_SSL_ALERT_MSG_CERT_UNKNOWN 46 /* 0x2E */

Definition at line 483 of file ssl.h.

#define MBEDTLS_SSL_ALERT_MSG_CLOSE_NOTIFY 0 /* 0x00 */

Definition at line 471 of file ssl.h.

#define MBEDTLS_SSL_ALERT_MSG_DECODE_ERROR 50 /* 0x32 */

Definition at line 487 of file ssl.h.

#define MBEDTLS_SSL_ALERT_MSG_DECOMPRESSION_FAILURE 30 /* 0x1E */

Definition at line 476 of file ssl.h.

#define MBEDTLS_SSL_ALERT_MSG_DECRYPT_ERROR 51 /* 0x33 */

Definition at line 488 of file ssl.h.

#define MBEDTLS_SSL_ALERT_MSG_DECRYPTION_FAILED 21 /* 0x15 */

Definition at line 474 of file ssl.h.

#define MBEDTLS_SSL_ALERT_MSG_EXPORT_RESTRICTION 60 /* 0x3C */

Definition at line 489 of file ssl.h.

#define MBEDTLS_SSL_ALERT_MSG_HANDSHAKE_FAILURE 40 /* 0x28 */

Definition at line 477 of file ssl.h.

#define MBEDTLS_SSL_ALERT_MSG_ILLEGAL_PARAMETER 47 /* 0x2F */

Definition at line 484 of file ssl.h.

#define MBEDTLS_SSL_ALERT_MSG_INAPROPRIATE_FALLBACK 86 /* 0x56 */

Definition at line 493 of file ssl.h.

#define MBEDTLS_SSL_ALERT_MSG_INSUFFICIENT_SECURITY 71 /* 0x47 */

Definition at line 491 of file ssl.h.

#define MBEDTLS_SSL_ALERT_MSG_INTERNAL_ERROR 80 /* 0x50 */

Definition at line 492 of file ssl.h.

#define MBEDTLS_SSL_ALERT_MSG_NO_APPLICATION_PROTOCOL 120 /* 0x78 */

Definition at line 499 of file ssl.h.

#define MBEDTLS_SSL_ALERT_MSG_NO_CERT 41 /* 0x29 */

Definition at line 478 of file ssl.h.

#define MBEDTLS_SSL_ALERT_MSG_NO_RENEGOTIATION 100 /* 0x64 */

Definition at line 495 of file ssl.h.

#define MBEDTLS_SSL_ALERT_MSG_PROTOCOL_VERSION 70 /* 0x46 */

Definition at line 490 of file ssl.h.

#define MBEDTLS_SSL_ALERT_MSG_RECORD_OVERFLOW 22 /* 0x16 */

Definition at line 475 of file ssl.h.

#define MBEDTLS_SSL_ALERT_MSG_UNEXPECTED_MESSAGE 10 /* 0x0A */

Definition at line 472 of file ssl.h.

#define MBEDTLS_SSL_ALERT_MSG_UNKNOWN_CA 48 /* 0x30 */

Definition at line 485 of file ssl.h.

#define MBEDTLS_SSL_ALERT_MSG_UNKNOWN_PSK_IDENTITY 115 /* 0x73 */

Definition at line 498 of file ssl.h.

#define MBEDTLS_SSL_ALERT_MSG_UNRECOGNIZED_NAME 112 /* 0x70 */

Definition at line 497 of file ssl.h.

#define MBEDTLS_SSL_ALERT_MSG_UNSUPPORTED_CERT 43 /* 0x2B */

Definition at line 480 of file ssl.h.

#define MBEDTLS_SSL_ALERT_MSG_UNSUPPORTED_EXT 110 /* 0x6E */

Definition at line 496 of file ssl.h.

#define MBEDTLS_SSL_ALERT_MSG_USER_CANCELED 90 /* 0x5A */

Definition at line 494 of file ssl.h.

#define MBEDTLS_SSL_ANTI_REPLAY_DISABLED 0

Definition at line 303 of file ssl.h.

#define MBEDTLS_SSL_ANTI_REPLAY_ENABLED 1

Definition at line 304 of file ssl.h.

#define MBEDTLS_SSL_CERT_REQ_CA_LIST_DISABLED 0

Definition at line 324 of file ssl.h.

#define MBEDTLS_SSL_CERT_REQ_CA_LIST_ENABLED 1

Definition at line 323 of file ssl.h.

#define MBEDTLS_SSL_CERT_TYPE_ECDSA_SIGN 64

Definition at line 457 of file ssl.h.

#define MBEDTLS_SSL_CERT_TYPE_RSA_SIGN 1

Definition at line 456 of file ssl.h.

#define MBEDTLS_SSL_CID_DISABLED 0

Definition at line 284 of file ssl.h.

#define MBEDTLS_SSL_CID_ENABLED 1

Definition at line 285 of file ssl.h.

#define MBEDTLS_SSL_CID_IN_LEN_MAX 32

The maximum length of CIDs used for incoming DTLS messages.

Definition at line 378 of file ssl.h.

#define MBEDTLS_SSL_CID_OUT_LEN_MAX 32

The maximum length of CIDs used for outgoing DTLS messages.

Definition at line 382 of file ssl.h.

#define MBEDTLS_SSL_CID_TLS1_3_PADDING_GRANULARITY 16

This option controls the use of record plaintext padding in TLS 1.3 and when using the Connection ID extension in DTLS 1.2.

The padding will always be chosen so that the length of the padded plaintext is a multiple of the value of this option.

Note: A value of 1 means that no padding will be used for outgoing records.

Note: On systems lacking division instructions, a power of two should be preferred.

Definition at line 386 of file ssl.h.

#define MBEDTLS_SSL_COMPRESS_NULL 0

Definition at line 290 of file ssl.h.

#define MBEDTLS_SSL_DTLS_MAX_BUFFERING 32768

Maximum number of heap-allocated bytes for the purpose of DTLS handshake message reassembly and future message buffering.

This should be at least 9/8 * MBEDTLS_SSL_IN_CONTENT_LEN to account for a reassembled handshake message of maximum size, together with its reassembly bitmap.

A value of 2 * MBEDTLS_SSL_IN_CONTENT_LEN (32768 by default) should be sufficient for all practical situations as it allows to reassembly a large handshake message (such as a certificate) while buffering multiple smaller handshake messages.

Definition at line 371 of file ssl.h.

#define MBEDTLS_SSL_DTLS_SRTP_MKI_SUPPORTED 1

Definition at line 327 of file ssl.h.

#define MBEDTLS_SSL_DTLS_SRTP_MKI_UNSUPPORTED 0

Definition at line 326 of file ssl.h.

#define MBEDTLS_SSL_DTLS_TIMEOUT_DFL_MAX 60000

Definition at line 337 of file ssl.h.

#define MBEDTLS_SSL_DTLS_TIMEOUT_DFL_MIN 1000

Definition at line 336 of file ssl.h.

#define MBEDTLS_SSL_EMPTY_RENEGOTIATION_INFO 0xFF

renegotiation info ext

Definition at line 399 of file ssl.h.

#define MBEDTLS_SSL_ETM_DISABLED 0

Definition at line 287 of file ssl.h.

#define MBEDTLS_SSL_ETM_ENABLED 1

Definition at line 288 of file ssl.h.

#define MBEDTLS_SSL_EXTENDED_MS_DISABLED 0

Definition at line 281 of file ssl.h.

#define MBEDTLS_SSL_EXTENDED_MS_ENABLED 1

Definition at line 282 of file ssl.h.

#define MBEDTLS_SSL_HASH_MD5 1

Definition at line 406 of file ssl.h.

#define MBEDTLS_SSL_HASH_NONE 0

Definition at line 405 of file ssl.h.

#define MBEDTLS_SSL_HASH_SHA1 2

Definition at line 407 of file ssl.h.

#define MBEDTLS_SSL_HASH_SHA224 3

Definition at line 408 of file ssl.h.

#define MBEDTLS_SSL_HASH_SHA256 4

Definition at line 409 of file ssl.h.

#define MBEDTLS_SSL_HASH_SHA384 5

Definition at line 410 of file ssl.h.

#define MBEDTLS_SSL_HASH_SHA512 6

Definition at line 411 of file ssl.h.

#define MBEDTLS_SSL_HS_CERTIFICATE 11

Definition at line 507 of file ssl.h.

#define MBEDTLS_SSL_HS_CERTIFICATE_REQUEST 13

Definition at line 509 of file ssl.h.

#define MBEDTLS_SSL_HS_CERTIFICATE_VERIFY 15

Definition at line 511 of file ssl.h.

#define MBEDTLS_SSL_HS_CLIENT_HELLO 1

Definition at line 502 of file ssl.h.

#define MBEDTLS_SSL_HS_CLIENT_KEY_EXCHANGE 16

Definition at line 512 of file ssl.h.

#define MBEDTLS_SSL_HS_ENCRYPTED_EXTENSIONS 8

Definition at line 506 of file ssl.h.

#define MBEDTLS_SSL_HS_FINISHED 20

Definition at line 513 of file ssl.h.

#define MBEDTLS_SSL_HS_HELLO_REQUEST 0

Definition at line 501 of file ssl.h.

#define MBEDTLS_SSL_HS_HELLO_VERIFY_REQUEST 3

Definition at line 504 of file ssl.h.

#define MBEDTLS_SSL_HS_NEW_SESSION_TICKET 4

Definition at line 505 of file ssl.h.

#define MBEDTLS_SSL_HS_SERVER_HELLO 2

Definition at line 503 of file ssl.h.

#define MBEDTLS_SSL_HS_SERVER_HELLO_DONE 14

Definition at line 510 of file ssl.h.

#define MBEDTLS_SSL_HS_SERVER_KEY_EXCHANGE 12

Definition at line 508 of file ssl.h.

#define MBEDTLS_SSL_IANA_TLS_GROUP_BP256R1 0x001A

Definition at line 202 of file ssl.h.

#define MBEDTLS_SSL_IANA_TLS_GROUP_BP384R1 0x001B

Definition at line 203 of file ssl.h.

#define MBEDTLS_SSL_IANA_TLS_GROUP_BP512R1 0x001C

Definition at line 204 of file ssl.h.

#define MBEDTLS_SSL_IANA_TLS_GROUP_FFDHE2048 0x0100

Definition at line 208 of file ssl.h.

#define MBEDTLS_SSL_IANA_TLS_GROUP_FFDHE3072 0x0101

Definition at line 209 of file ssl.h.

#define MBEDTLS_SSL_IANA_TLS_GROUP_FFDHE4096 0x0102

Definition at line 210 of file ssl.h.

#define MBEDTLS_SSL_IANA_TLS_GROUP_FFDHE6144 0x0103

Definition at line 211 of file ssl.h.

#define MBEDTLS_SSL_IANA_TLS_GROUP_FFDHE8192 0x0104

Definition at line 212 of file ssl.h.

#define MBEDTLS_SSL_IANA_TLS_GROUP_NONE 0

Definition at line 193 of file ssl.h.

#define MBEDTLS_SSL_IANA_TLS_GROUP_SECP192K1 0x0012

Definition at line 194 of file ssl.h.

#define MBEDTLS_SSL_IANA_TLS_GROUP_SECP192R1 0x0013

Definition at line 195 of file ssl.h.

#define MBEDTLS_SSL_IANA_TLS_GROUP_SECP224K1 0x0014

Definition at line 196 of file ssl.h.

#define MBEDTLS_SSL_IANA_TLS_GROUP_SECP224R1 0x0015

Definition at line 197 of file ssl.h.

#define MBEDTLS_SSL_IANA_TLS_GROUP_SECP256K1 0x0016

Definition at line 198 of file ssl.h.

#define MBEDTLS_SSL_IANA_TLS_GROUP_SECP256R1 0x0017

Definition at line 199 of file ssl.h.

#define MBEDTLS_SSL_IANA_TLS_GROUP_SECP384R1 0x0018

Definition at line 200 of file ssl.h.

#define MBEDTLS_SSL_IANA_TLS_GROUP_SECP521R1 0x0019

Definition at line 201 of file ssl.h.

#define MBEDTLS_SSL_IANA_TLS_GROUP_X25519 0x001D

Definition at line 205 of file ssl.h.

#define MBEDTLS_SSL_IANA_TLS_GROUP_X448 0x001E

Definition at line 206 of file ssl.h.

#define MBEDTLS_SSL_IN_CONTENT_LEN 16384

Maximum length (in bytes) of incoming plaintext fragments.

This determines the size of the incoming TLS I/O buffer in such a way that it is capable of holding the specified amount of plaintext data, regardless of the protection mechanism used.

Note: When using a value less than the default of 16KB on the client, it is recommended to use the Maximum Fragment Length (MFL) extension to inform the server about this limitation. On the server, there is no supported, standardized way of informing the client about restriction on the maximum size of incoming messages, and unless the limitation has been communicated by other means, it is recommended to only change the outgoing buffer size MBEDTLS_SSL_OUT_CONTENT_LEN while keeping the default value of 16KB for the incoming buffer.

Uncomment to set the maximum plaintext size of the incoming I/O buffer.

Definition at line 359 of file ssl.h.

#define MBEDTLS_SSL_IS_CLIENT 0

Definition at line 278 of file ssl.h.

#define MBEDTLS_SSL_IS_SERVER 1

Definition at line 279 of file ssl.h.

#define MBEDTLS_SSL_LEGACY_ALLOW_RENEGOTIATION 1

Definition at line 310 of file ssl.h.

#define MBEDTLS_SSL_LEGACY_BREAK_HANDSHAKE 2

Definition at line 311 of file ssl.h.

#define MBEDTLS_SSL_LEGACY_NO_RENEGOTIATION 0

Definition at line 309 of file ssl.h.

#define MBEDTLS_SSL_LEGACY_RENEGOTIATION 0

Definition at line 297 of file ssl.h.

#define MBEDTLS_SSL_MAJOR_VERSION_3 3

Definition at line 257 of file ssl.h.

#define MBEDTLS_SSL_MAX_ALPN_LIST_LEN 65535

Maximum size in bytes of list in alpn ext., RFC 7301

Definition at line 267 of file ssl.h.

#define MBEDTLS_SSL_MAX_ALPN_NAME_LEN 255

Maximum size in bytes of a protocol name in alpn ext., RFC 7301

Definition at line 265 of file ssl.h.

#define MBEDTLS_SSL_MAX_FRAG_LEN_1024 2

MaxFragmentLength 2^10

Definition at line 273 of file ssl.h.

#define MBEDTLS_SSL_MAX_FRAG_LEN_2048 3

MaxFragmentLength 2^11

Definition at line 274 of file ssl.h.

#define MBEDTLS_SSL_MAX_FRAG_LEN_4096 4

MaxFragmentLength 2^12

Definition at line 275 of file ssl.h.

#define MBEDTLS_SSL_MAX_FRAG_LEN_512 1

MaxFragmentLength 2^9

Definition at line 272 of file ssl.h.

#define MBEDTLS_SSL_MAX_FRAG_LEN_INVALID 5

first invalid value

Definition at line 276 of file ssl.h.

#define MBEDTLS_SSL_MAX_FRAG_LEN_NONE 0

don't use this extension

Definition at line 271 of file ssl.h.

#define MBEDTLS_SSL_MAX_HOST_NAME_LEN 255

Maximum host name defined in RFC 1035

Definition at line 264 of file ssl.h.

#define MBEDTLS_SSL_MINOR_VERSION_3 3

TLS v1.2

Definition at line 258 of file ssl.h.

#define MBEDTLS_SSL_MINOR_VERSION_4 4

TLS v1.3

Definition at line 259 of file ssl.h.

#define MBEDTLS_SSL_MSG_ALERT 21

Definition at line 463 of file ssl.h.

#define MBEDTLS_SSL_MSG_APPLICATION_DATA 23

Definition at line 465 of file ssl.h.

#define MBEDTLS_SSL_MSG_CHANGE_CIPHER_SPEC 20

Definition at line 462 of file ssl.h.

#define MBEDTLS_SSL_MSG_CID 25

Definition at line 466 of file ssl.h.

#define MBEDTLS_SSL_MSG_HANDSHAKE 22

Definition at line 464 of file ssl.h.

#define MBEDTLS_SSL_OUT_CONTENT_LEN 16384

Maximum length (in bytes) of outgoing plaintext fragments.

This determines the size of the outgoing TLS I/O buffer in such a way that it is capable of holding the specified amount of plaintext data, regardless of the protection mechanism used.

It is possible to save RAM by setting a smaller outward buffer, while keeping the default inward 16384 byte buffer to conform to the TLS specification.

The minimum required outward buffer size is determined by the handshake protocol's usage. Handshaking will fail if the outward buffer is too small. The specific size requirement depends on the configured ciphers and any certificate data which is sent during the handshake.

Uncomment to set the maximum plaintext size of the outgoing I/O buffer.

Definition at line 363 of file ssl.h.

#define MBEDTLS_SSL_PRESET_DEFAULT 0

Definition at line 320 of file ssl.h.

#define MBEDTLS_SSL_PRESET_SUITEB 2

Definition at line 321 of file ssl.h.

#define MBEDTLS_SSL_RENEGO_MAX_RECORDS_DEFAULT 16

Definition at line 307 of file ssl.h.

#define MBEDTLS_SSL_RENEGOTIATION_DISABLED 0

Definition at line 300 of file ssl.h.

#define MBEDTLS_SSL_RENEGOTIATION_ENABLED 1

Definition at line 301 of file ssl.h.

#define MBEDTLS_SSL_RENEGOTIATION_NOT_ENFORCED -1

Definition at line 306 of file ssl.h.

#define MBEDTLS_SSL_SECURE_RENEGOTIATION 1

Definition at line 298 of file ssl.h.

#define MBEDTLS_SSL_SEQUENCE_NUMBER_LEN 8

Definition at line 617 of file ssl.h.

#define MBEDTLS_SSL_SESSION_TICKETS_DISABLED 0

Definition at line 317 of file ssl.h.

#define MBEDTLS_SSL_SESSION_TICKETS_ENABLED 1

Definition at line 318 of file ssl.h.

#define MBEDTLS_SSL_SIG_ANON 0

Definition at line 413 of file ssl.h.

#define MBEDTLS_SSL_SIG_ECDSA 3

Definition at line 415 of file ssl.h.

#define MBEDTLS_SSL_SIG_RSA 1

Definition at line 414 of file ssl.h.

#define MBEDTLS_SSL_SRV_CIPHERSUITE_ORDER_CLIENT 1

Definition at line 329 of file ssl.h.

#define MBEDTLS_SSL_SRV_CIPHERSUITE_ORDER_SERVER 0

Definition at line 330 of file ssl.h.

#define MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_ALL

Value:

( MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK              |            \
      MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL    |            \
      MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL )

All TLS 1.3 key exchanges

Definition at line 238 of file ssl.h.

#define MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL ( 1u << 1 )

Pure-Ephemeral TLS 1.3 key exchanges, including for example ECDHE and DHE key exchanges.

Definition at line 226 of file ssl.h.

#define MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL_ALL

Value:

( MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL | \

MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL )

MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL

#define MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL

Definition: ssl.h:226

MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL

#define MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL

Definition: ssl.h:231

All ephemeral TLS 1.3 key exchanges

Definition at line 245 of file ssl.h.

#define MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK ( 1u << 0 )

Pure-PSK TLS 1.3 key exchange, encompassing both externally agreed PSKs as well as resumption PSKs.

Definition at line 221 of file ssl.h.

#define MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_ALL

Value:

( MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK | \

MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL )

MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK

#define MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK

Definition: ssl.h:221

MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL

#define MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL

Definition: ssl.h:231

All PSK-based TLS 1.3 key exchanges

Definition at line 242 of file ssl.h.

#define MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL ( 1u << 2 )

PSK-Ephemeral TLS 1.3 key exchanges, using both a PSK and an ephemeral key exchange.

Definition at line 231 of file ssl.h.

#define MBEDTLS_SSL_TRANSPORT_DATAGRAM 1

DTLS

Definition at line 262 of file ssl.h.

#define MBEDTLS_SSL_TRANSPORT_STREAM 0

TLS

Definition at line 261 of file ssl.h.

#define MBEDTLS_SSL_TRUNC_HMAC_DISABLED 0

Definition at line 313 of file ssl.h.

#define MBEDTLS_SSL_TRUNC_HMAC_ENABLED 1

Definition at line 314 of file ssl.h.

#define MBEDTLS_SSL_TRUNCATED_HMAC_LEN 10 /* 80 bits, rfc 6066 section 7 */

Definition at line 315 of file ssl.h.

#define MBEDTLS_SSL_UNEXPECTED_CID_FAIL 1

Definition at line 2811 of file ssl.h.

#define MBEDTLS_SSL_UNEXPECTED_CID_IGNORE 0

Definition at line 2810 of file ssl.h.

#define MBEDTLS_SSL_VERIFY_DATA_MAX_LEN 12

Definition at line 394 of file ssl.h.

#define MBEDTLS_SSL_VERIFY_NONE 0

Definition at line 292 of file ssl.h.

#define MBEDTLS_SSL_VERIFY_OPTIONAL 1

Definition at line 293 of file ssl.h.

#define MBEDTLS_SSL_VERIFY_REQUIRED 2

Definition at line 294 of file ssl.h.

#define MBEDTLS_SSL_VERIFY_UNSET 3 /* Used only for sni_authmode */

Definition at line 295 of file ssl.h.

#define MBEDTLS_TLS1_3_MD_MAX_SIZE MBEDTLS_MD_MAX_SIZE

Definition at line 614 of file ssl.h.

#define MBEDTLS_TLS1_3_SIG_ECDSA_SECP256R1_SHA256 0x0403

Definition at line 428 of file ssl.h.

#define MBEDTLS_TLS1_3_SIG_ECDSA_SECP384R1_SHA384 0x0503

Definition at line 429 of file ssl.h.

#define MBEDTLS_TLS1_3_SIG_ECDSA_SECP521R1_SHA512 0x0603

Definition at line 430 of file ssl.h.

#define MBEDTLS_TLS1_3_SIG_ECDSA_SHA1 0x0203

Definition at line 448 of file ssl.h.

#define MBEDTLS_TLS1_3_SIG_ED25519 0x0807

Definition at line 438 of file ssl.h.

#define MBEDTLS_TLS1_3_SIG_ED448 0x0808

Definition at line 439 of file ssl.h.

#define MBEDTLS_TLS1_3_SIG_NONE 0x0

Definition at line 450 of file ssl.h.

#define MBEDTLS_TLS1_3_SIG_RSA_PKCS1_SHA1 0x0201

Definition at line 447 of file ssl.h.

#define MBEDTLS_TLS1_3_SIG_RSA_PKCS1_SHA256 0x0401

Definition at line 423 of file ssl.h.

#define MBEDTLS_TLS1_3_SIG_RSA_PKCS1_SHA384 0x0501

Definition at line 424 of file ssl.h.

#define MBEDTLS_TLS1_3_SIG_RSA_PKCS1_SHA512 0x0601

Definition at line 425 of file ssl.h.

#define MBEDTLS_TLS1_3_SIG_RSA_PSS_PSS_SHA256 0x0809

Definition at line 442 of file ssl.h.

#define MBEDTLS_TLS1_3_SIG_RSA_PSS_PSS_SHA384 0x080A

Definition at line 443 of file ssl.h.

#define MBEDTLS_TLS1_3_SIG_RSA_PSS_PSS_SHA512 0x080B

Definition at line 444 of file ssl.h.

#define MBEDTLS_TLS1_3_SIG_RSA_PSS_RSAE_SHA256 0x0804

Definition at line 433 of file ssl.h.

#define MBEDTLS_TLS1_3_SIG_RSA_PSS_RSAE_SHA384 0x0805

Definition at line 434 of file ssl.h.

#define MBEDTLS_TLS1_3_SIG_RSA_PSS_RSAE_SHA512 0x0806

Definition at line 435 of file ssl.h.

#define MBEDTLS_TLS_EXT_ALPN 16

Definition at line 533 of file ssl.h.

#define MBEDTLS_TLS_EXT_CERT_AUTH 47 /* RFC 8446 TLS 1.3 */

Definition at line 550 of file ssl.h.

#define MBEDTLS_TLS_EXT_CID 254 /* TBD */

At the time of writing, the CID extension has not been assigned its final value. Set this configuration option to make Mbed TLS use a different value.

A future minor revision of Mbed TLS may change the default value of this option to match evolving standards and usage.

Definition at line 564 of file ssl.h.

#define MBEDTLS_TLS_EXT_CLI_CERT_TYPE 19 /* RFC 7250 TLS 1.2 and 1.3 */

Definition at line 536 of file ssl.h.

#define MBEDTLS_TLS_EXT_COOKIE 44 /* RFC 8446 TLS 1.3 */

Definition at line 547 of file ssl.h.

#define MBEDTLS_TLS_EXT_EARLY_DATA 42 /* RFC 8446 TLS 1.3 */

Definition at line 545 of file ssl.h.

#define MBEDTLS_TLS_EXT_ECJPAKE_KKPP 256 /* experimental */

Definition at line 567 of file ssl.h.

#define MBEDTLS_TLS_EXT_ENCRYPT_THEN_MAC 22 /* 0x16 */

Definition at line 539 of file ssl.h.

#define MBEDTLS_TLS_EXT_EXTENDED_MASTER_SECRET 0x0017 /* 23 */

Definition at line 540 of file ssl.h.

#define MBEDTLS_TLS_EXT_HEARTBEAT 15 /* RFC 6520 TLS 1.2 and 1.3 */

Definition at line 532 of file ssl.h.

#define MBEDTLS_TLS_EXT_KEY_SHARE 51 /* RFC 8446 TLS 1.3 */

Definition at line 554 of file ssl.h.

#define MBEDTLS_TLS_EXT_MAX_FRAGMENT_LENGTH 1

Definition at line 521 of file ssl.h.

#define MBEDTLS_TLS_EXT_OID_FILTERS 48 /* RFC 8446 TLS 1.3 */

Definition at line 551 of file ssl.h.

#define MBEDTLS_TLS_EXT_PADDING 21 /* RFC 7685 TLS 1.2 and 1.3 */

Definition at line 538 of file ssl.h.

#define MBEDTLS_TLS_EXT_POST_HANDSHAKE_AUTH 49 /* RFC 8446 TLS 1.3 */

Definition at line 552 of file ssl.h.

#define MBEDTLS_TLS_EXT_PRE_SHARED_KEY 41 /* RFC 8446 TLS 1.3 */

Definition at line 544 of file ssl.h.

#define MBEDTLS_TLS_EXT_PSK_KEY_EXCHANGE_MODES 45 /* RFC 8446 TLS 1.3 */

Definition at line 548 of file ssl.h.

#define MBEDTLS_TLS_EXT_RENEGOTIATION_INFO 0xFF01

Definition at line 569 of file ssl.h.

#define MBEDTLS_TLS_EXT_SCT 18 /* RFC 6962 TLS 1.2 and 1.3 */

Definition at line 535 of file ssl.h.

#define MBEDTLS_TLS_EXT_SERV_CERT_TYPE 20 /* RFC 7250 TLS 1.2 and 1.3 */

Definition at line 537 of file ssl.h.

#define MBEDTLS_TLS_EXT_SERVERNAME 0

Definition at line 518 of file ssl.h.

#define MBEDTLS_TLS_EXT_SERVERNAME_HOSTNAME 0

Definition at line 519 of file ssl.h.

#define MBEDTLS_TLS_EXT_SESSION_TICKET 35

Definition at line 542 of file ssl.h.

#define MBEDTLS_TLS_EXT_SIG_ALG 13 /* RFC 8446 TLS 1.3 */

Definition at line 530 of file ssl.h.

#define MBEDTLS_TLS_EXT_SIG_ALG_CERT 50 /* RFC 8446 TLS 1.3 */

Definition at line 553 of file ssl.h.

#define MBEDTLS_TLS_EXT_STATUS_REQUEST 5 /* RFC 6066 TLS 1.2 and 1.3 */

Definition at line 524 of file ssl.h.

#define MBEDTLS_TLS_EXT_SUPPORTED_ELLIPTIC_CURVES 10

Definition at line 526 of file ssl.h.

#define MBEDTLS_TLS_EXT_SUPPORTED_GROUPS 10 /* RFC 8422,7919 TLS 1.2 and 1.3 */

Definition at line 527 of file ssl.h.

#define MBEDTLS_TLS_EXT_SUPPORTED_POINT_FORMATS 11

Definition at line 528 of file ssl.h.

#define MBEDTLS_TLS_EXT_SUPPORTED_VERSIONS 43 /* RFC 8446 TLS 1.3 */

Definition at line 546 of file ssl.h.

#define MBEDTLS_TLS_EXT_TRUNCATED_HMAC 4

Definition at line 523 of file ssl.h.

#define MBEDTLS_TLS_EXT_USE_SRTP 14

Definition at line 531 of file ssl.h.

#define MBEDTLS_TLS_SRTP_AES128_CM_HMAC_SHA1_32 ( (uint16_t) 0x0002)

Definition at line 1086 of file ssl.h.

#define MBEDTLS_TLS_SRTP_AES128_CM_HMAC_SHA1_80 ( (uint16_t) 0x0001)

Definition at line 1085 of file ssl.h.

#define MBEDTLS_TLS_SRTP_MAX_MKI_LENGTH 255

Definition at line 1074 of file ssl.h.

#define MBEDTLS_TLS_SRTP_MAX_PROFILE_LIST_LENGTH 4

Definition at line 1075 of file ssl.h.

#define MBEDTLS_TLS_SRTP_NULL_HMAC_SHA1_32 ( (uint16_t) 0x0006)

Definition at line 1088 of file ssl.h.

#define MBEDTLS_TLS_SRTP_NULL_HMAC_SHA1_80 ( (uint16_t) 0x0005)

Definition at line 1087 of file ssl.h.

#define MBEDTLS_TLS_SRTP_UNSET ( (uint16_t) 0x0000)

Definition at line 1090 of file ssl.h.

Typedef Documentation

typedef struct mbedtls_dtls_srtp_info_t mbedtls_dtls_srtp_info

typedef void mbedtls_ssl_async_cancel_t(mbedtls_ssl_context *ssl)

Callback type: cancel external operation.

This callback is called if an SSL connection is closed while an asynchronous operation is in progress. Note that this callback is not called if the mbedtls_ssl_async_resume_t callback has run and has returned a value other than MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS, since in that case the asynchronous operation has already completed.

This function may call mbedtls_ssl_get_async_operation_data() to retrieve an operation context set by the start callback.

Parameters

ssl	The SSL connection instance. It should not be modified.

Definition at line 1042 of file ssl.h.

typedef int mbedtls_ssl_async_decrypt_t(mbedtls_ssl_context *ssl, mbedtls_x509_crt *cert, const unsigned char *input, size_t input_len)

Callback type: start external decryption operation.

This callback is called during an SSL handshake to start an RSA decryption operation using an external processor. The parameter cert contains the public key; it is up to the callback function to determine how to access the associated private key.

This function typically sends or enqueues a request, and does not wait for the operation to complete. This allows the handshake step to be non-blocking.

The parameters ssl and cert are guaranteed to remain valid throughout the handshake. On the other hand, this function must save the contents of input if the value is needed for later processing, because the input buffer is no longer valid after this function returns.

This function may call mbedtls_ssl_set_async_operation_data() to store an operation context for later retrieval by the resume or cancel callback.

Warning: RSA decryption as used in TLS is subject to a potential timing side channel attack first discovered by Bleichenbacher in 1998. This attack can be remotely exploitable in practice. To avoid this attack, you must ensure that if the callback performs an RSA decryption, the time it takes to execute and return the result does not depend on whether the RSA decryption succeeded or reported invalid padding.

Parameters

ssl	The SSL connection instance. It should not be modified other than via mbedtls_ssl_set_async_operation_data().
cert	Certificate containing the public key. In simple cases, this is one of the pointers passed to mbedtls_ssl_conf_own_cert() when configuring the SSL connection. However, if other callbacks are used, this property may not hold. For example, if an SNI callback is registered with mbedtls_ssl_conf_sni(), then this callback determines what certificate is used.
input	Buffer containing the input ciphertext. This buffer is no longer valid when the function returns.
input_len	Size of the `input` buffer in bytes.

Returns: 0 if the operation was started successfully and the SSL stack should call the resume callback immediately.; MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS if the operation was started successfully and the SSL stack should return immediately without calling the resume callback yet.; MBEDTLS_ERR_SSL_HW_ACCEL_FALLTHROUGH if the external processor does not support this key. The SSL stack will use the private key object instead.; Any other error indicates a fatal failure and is propagated up the call chain. The callback should use MBEDTLS_ERR_PK_xxx error codes, and must not use MBEDTLS_ERR_SSL_xxx error codes except as directed in the documentation of this callback.

Definition at line 972 of file ssl.h.

typedef int mbedtls_ssl_async_resume_t(mbedtls_ssl_context *ssl, unsigned char *output, size_t *output_len, size_t output_size)

Callback type: resume external operation.

This callback is called during an SSL handshake to resume an external operation started by the mbedtls_ssl_async_sign_t or mbedtls_ssl_async_decrypt_t callback.

This function typically checks the status of a pending request or causes the request queue to make progress, and does not wait for the operation to complete. This allows the handshake step to be non-blocking.

This function may call mbedtls_ssl_get_async_operation_data() to retrieve an operation context set by the start callback. It may call mbedtls_ssl_set_async_operation_data() to modify this context.

Note that when this function returns a status other than MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS, it must free any resources associated with the operation.

Parameters

ssl	The SSL connection instance. It should not be modified other than via mbedtls_ssl_set_async_operation_data().
output	Buffer containing the output (signature or decrypted data) on success.
output_len	On success, number of bytes written to `output`.
output_size	Size of the `output` buffer in bytes.

Returns: 0 if output of the operation is available in the output buffer.; MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS if the operation is still in progress. Subsequent requests for progress on the SSL connection will call the resume callback again.; Any other error means that the operation is aborted. The SSL handshake is aborted. The callback should use MBEDTLS_ERR_PK_xxx error codes, and must not use MBEDTLS_ERR_SSL_xxx error codes except as directed in the documentation of this callback.

Definition at line 1020 of file ssl.h.

typedef int mbedtls_ssl_async_sign_t(mbedtls_ssl_context *ssl, mbedtls_x509_crt *cert, mbedtls_md_type_t md_alg, const unsigned char *hash, size_t hash_len)

Callback type: start external signature operation.

This callback is called during an SSL handshake to start a signature decryption operation using an external processor. The parameter cert contains the public key; it is up to the callback function to determine how to access the associated private key.

This function typically sends or enqueues a request, and does not wait for the operation to complete. This allows the handshake step to be non-blocking.

The parameters ssl and cert are guaranteed to remain valid throughout the handshake. On the other hand, this function must save the contents of hash if the value is needed for later processing, because the hash buffer is no longer valid after this function returns.

This function may call mbedtls_ssl_set_async_operation_data() to store an operation context for later retrieval by the resume or cancel callback.

Note

For RSA signatures, this function must produce output that is consistent with PKCS#1 v1.5 in the same way as mbedtls_rsa_pkcs1_sign(). Before the private key operation, apply the padding steps described in RFC 8017, section 9.2 "EMSA-PKCS1-v1_5" as follows.

If md_alg is MBEDTLS_MD_NONE, apply the PKCS#1 v1.5 encoding, treating hash as the DigestInfo to be padded. In other words, apply EMSA-PKCS1-v1_5 starting from step 3, with T = hash and tLen = hash_len.
If md_alg != MBEDTLS_MD_NONE, apply the PKCS#1 v1.5 encoding, treating hash as the hash to be encoded and padded. In other words, apply EMSA-PKCS1-v1_5 starting from step 2, with digestAlgorithm obtained by calling mbedtls_oid_get_oid_by_md() on md_alg.

For ECDSA signatures, the output format is the DER encoding Ecdsa-Sig-Value defined in RFC 4492 section 5.4.

Parameters

ssl	The SSL connection instance. It should not be modified other than via mbedtls_ssl_set_async_operation_data().
cert	Certificate containing the public key. In simple cases, this is one of the pointers passed to mbedtls_ssl_conf_own_cert() when configuring the SSL connection. However, if other callbacks are used, this property may not hold. For example, if an SNI callback is registered with mbedtls_ssl_conf_sni(), then this callback determines what certificate is used.
md_alg	Hash algorithm.
hash	Buffer containing the hash. This buffer is no longer valid when the function returns.
hash_len	Size of the `hash` buffer in bytes.

Returns: 0 if the operation was started successfully and the SSL stack should call the resume callback immediately.; MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS if the operation was started successfully and the SSL stack should return immediately without calling the resume callback yet.; MBEDTLS_ERR_SSL_HW_ACCEL_FALLTHROUGH if the external processor does not support this key. The SSL stack will use the private key object instead.; Any other error indicates a fatal failure and is propagated up the call chain. The callback should use MBEDTLS_ERR_PK_xxx error codes, and must not use MBEDTLS_ERR_SSL_xxx error codes except as directed in the documentation of this callback.

Definition at line 906 of file ssl.h.

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.

Parameters

data	The address of the session cache structure to query.
session_id	The buffer holding the session ID to query.
session_id_len	The length of `session_id` in Bytes.
session	The address of the session structure to populate. It is initialized with mbdtls_ssl_session_init(), and the callback must always leave it in a state where it can safely be freed via mbedtls_ssl_session_free() independent of the return code of this function.

Returns: 0 on success; A non-zero return value on failure.

Definition at line 806 of file ssl.h.

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.

Parameters

data	The address of the session cache structure to modify.
session_id	The buffer holding the session ID to query.
session_id_len	The length of `session_id` in Bytes.
session	The address of the session to be stored in the session cache.

Returns: 0 on success; A non-zero return value on failure.

Definition at line 828 of file ssl.h.

typedef struct mbedtls_ssl_config mbedtls_ssl_config

Definition at line 770 of file ssl.h.

typedef struct mbedtls_ssl_context mbedtls_ssl_context

Definition at line 769 of file ssl.h.

typedef int mbedtls_ssl_cookie_check_t(void *ctx, const unsigned char *cookie, size_t clen, const unsigned char *info, size_t ilen)

Callback type: verify a cookie.

Parameters

ctx	Context for the callback
cookie	Cookie to verify
clen	Length of cookie
info	Client ID info that was passed to `mbedtls_ssl_set_client_transport_id()`
ilen	Length of info in bytes

Returns: The callback must return 0 if cookie is valid, or a negative error code.

Definition at line 2385 of file ssl.h.

typedef int mbedtls_ssl_cookie_write_t(void *ctx, unsigned char **p, unsigned char *end, const unsigned char *info, size_t ilen)

Callback type: generate a cookie.

Parameters

ctx	Context for the callback
p	Buffer to write to, must be updated to point right after the cookie
end	Pointer to one past the end of the output buffer
info	Client ID info that was passed to `mbedtls_ssl_set_client_transport_id()`
ilen	Length of info in bytes

Returns: The callback must return 0 on success, or a negative error code.

Definition at line 2368 of file ssl.h.

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.

Parameters

p_expkey	Context for the callback.
type	The type of the key that is being exported.
secret	The address of the buffer holding the secret that's being exporterd.
secret_len	The length of `secret` in bytes.
client_random	The client random bytes.
server_random	The server random bytes.
tls_prf_type	The identifier for the PRF used in the handshake to which the key belongs.

Definition at line 1209 of file ssl.h.

typedef struct mbedtls_ssl_flight_item mbedtls_ssl_flight_item

Definition at line 780 of file ssl.h.

typedef int mbedtls_ssl_get_timer_t(void *ctx)

Callback type: get status of timers/delays.

Parameters

ctx	Context pointer

Returns: 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.

Definition at line 765 of file ssl.h.

typedef struct mbedtls_ssl_handshake_params mbedtls_ssl_handshake_params

Definition at line 774 of file ssl.h.

typedef struct mbedtls_ssl_key_cert mbedtls_ssl_key_cert

Definition at line 777 of file ssl.h.

typedef int mbedtls_ssl_recv_t(void *ctx, unsigned char *buf, size_t len)

Callback type: receive data from the network.

Note: That callback may be either blocking or non-blocking.

Parameters

ctx	Context for the receive callback (typically a file descriptor)
buf	Buffer to write the received data to
len	Length of the receive buffer

Returns: If data has been received, the positive number of bytes received.; 0 if the connection has been closed.; If performing non-blocking I/O, MBEDTLS_ERR_SSL_WANT_READ must be returned when the operation would block.; Another negative error code on other kinds of failures.

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.

Definition at line 698 of file ssl.h.

typedef int mbedtls_ssl_recv_timeout_t(void *ctx, unsigned char *buf, size_t len, uint32_t timeout)

Callback type: receive data from the network, with timeout.

Note: That callback must block until data is received, or the timeout delay expires, or the operation is interrupted by a signal.

Parameters

ctx	Context for the receive callback (typically a file descriptor)
buf	Buffer to write the received data to
len	Length of the receive buffer
timeout	Maximum number of milliseconds to wait for data 0 means no timeout (potentially waiting forever)

Returns: The callback must return the number of bytes received, or a non-zero error code: MBEDTLS_ERR_SSL_TIMEOUT if the operation timed out, MBEDTLS_ERR_SSL_WANT_READ if interrupted by a signal.

Note: The callback may receive fewer bytes than the length of the buffer. It must always return the number of bytes actually received and written to the buffer.

Definition at line 724 of file ssl.h.

typedef int mbedtls_ssl_send_t(void *ctx, const unsigned char *buf, size_t len)

Callback type: send data on the network.

Note: That callback may be either blocking or non-blocking.

Parameters

ctx	Context for the send callback (typically a file descriptor)
buf	Buffer holding the data to send
len	Length of the data to send

Returns: The callback must return the number of bytes sent if any, or a non-zero error code. If performing non-blocking I/O, MBEDTLS_ERR_SSL_WANT_WRITE must be returned when the operation would block.

Note: The callback is allowed to send fewer bytes than requested. It must always return the number of bytes actually sent.

Definition at line 674 of file ssl.h.

typedef struct mbedtls_ssl_session mbedtls_ssl_session

Definition at line 768 of file ssl.h.

typedef void mbedtls_ssl_set_timer_t(void *ctx, uint32_t int_ms, uint32_t fin_ms)

Callback type: set a pair of timers/delays to watch.

Parameters

ctx	Context pointer
int_ms	Intermediate delay in milliseconds
fin_ms	Final delay in milliseconds 0 cancels the current timer.

Note: This callback must at least store the necessary information for the associated mbedtls_ssl_get_timer_t callback to return correct information.; If using a event-driven style of programming, an event must be generated when the final delay is passed. The event must cause a call to mbedtls_ssl_handshake() with the proper SSL context to be scheduled. Care must be taken to ensure that at most one such call happens at a time.; Only one timer at a time must be running. Calling this function while a timer is running must cancel it. Cancelled timers must not generate any event.

Definition at line 750 of file ssl.h.

typedef struct mbedtls_ssl_sig_hash_set_t mbedtls_ssl_sig_hash_set_t

Definition at line 775 of file ssl.h.

typedef uint16_t mbedtls_ssl_srtp_profile

Definition at line 1092 of file ssl.h.

typedef int mbedtls_ssl_ticket_parse_t(void *p_ticket, mbedtls_ssl_session *session, unsigned char *buf, size_t len)

Callback type: parse and load session ticket.

Note: This describes what a callback implementation should do. This callback should parse a session ticket as generated by the corresponding mbedtls_ssl_ticket_write_t function, and, if the ticket is authentic and valid, load the session.; The implementation is allowed to modify the first len bytes of the input buffer, eg to use it as a temporary area for the decrypted ticket contents.

Parameters

p_ticket	Context for the callback
session	SSL session to be loaded
buf	Start of the buffer containing the ticket
len	Length of the ticket.

Returns: 0 if successful, or MBEDTLS_ERR_SSL_INVALID_MAC if not authentic, or MBEDTLS_ERR_SSL_SESSION_TICKET_EXPIRED if expired, or any other non-zero code for other failures.

Definition at line 2227 of file ssl.h.

typedef int mbedtls_ssl_ticket_write_t(void *p_ticket, const mbedtls_ssl_session *session, unsigned char *start, const unsigned char *end, size_t *tlen, uint32_t *lifetime)

Callback type: generate and write session ticket.

Note: This describes what a callback implementation should do. This callback should generate an encrypted and authenticated ticket for the session and write it to the output buffer. Here, ticket means the opaque ticket part of the NewSessionTicket structure of RFC 5077.

Parameters

p_ticket	Context for the callback
session	SSL session to be written in the ticket
start	Start of the output buffer
end	End of the output buffer
tlen	On exit, holds the length written
lifetime	On exit, holds the lifetime of the ticket in seconds

Returns: 0 if successful, or a specific MBEDTLS_ERR_XXX code.

Definition at line 2197 of file ssl.h.

typedef struct mbedtls_ssl_transform mbedtls_ssl_transform

Definition at line 773 of file ssl.h.

Enumeration Type Documentation

enum mbedtls_ssl_key_export_type

Enumerator
MBEDTLS_SSL_KEY_EXPORT_TLS12_MASTER_SECRET
MBEDTLS_SSL_KEY_EXPORT_TLS1_3_CLIENT_EARLY_SECRET
MBEDTLS_SSL_KEY_EXPORT_TLS1_3_EARLY_EXPORTER_SECRET
MBEDTLS_SSL_KEY_EXPORT_TLS1_3_CLIENT_HANDSHAKE_TRAFFIC_SECRET
MBEDTLS_SSL_KEY_EXPORT_TLS1_3_SERVER_HANDSHAKE_TRAFFIC_SECRET
MBEDTLS_SSL_KEY_EXPORT_TLS1_3_CLIENT_APPLICATION_TRAFFIC_SECRET
MBEDTLS_SSL_KEY_EXPORT_TLS1_3_SERVER_APPLICATION_TRAFFIC_SECRET

Definition at line 1181 of file ssl.h.

enum mbedtls_ssl_states

Enumerator
MBEDTLS_SSL_HELLO_REQUEST
MBEDTLS_SSL_CLIENT_HELLO
MBEDTLS_SSL_SERVER_HELLO
MBEDTLS_SSL_SERVER_CERTIFICATE
MBEDTLS_SSL_SERVER_KEY_EXCHANGE
MBEDTLS_SSL_CERTIFICATE_REQUEST
MBEDTLS_SSL_SERVER_HELLO_DONE
MBEDTLS_SSL_CLIENT_CERTIFICATE
MBEDTLS_SSL_CLIENT_KEY_EXCHANGE
MBEDTLS_SSL_CERTIFICATE_VERIFY
MBEDTLS_SSL_CLIENT_CHANGE_CIPHER_SPEC
MBEDTLS_SSL_CLIENT_FINISHED
MBEDTLS_SSL_SERVER_CHANGE_CIPHER_SPEC
MBEDTLS_SSL_SERVER_FINISHED
MBEDTLS_SSL_FLUSH_BUFFERS
MBEDTLS_SSL_HANDSHAKE_WRAPUP
MBEDTLS_SSL_HANDSHAKE_OVER
MBEDTLS_SSL_SERVER_NEW_SESSION_TICKET
MBEDTLS_SSL_SERVER_HELLO_VERIFY_REQUEST_SENT
MBEDTLS_SSL_ENCRYPTED_EXTENSIONS
MBEDTLS_SSL_CLIENT_CERTIFICATE_VERIFY
MBEDTLS_SSL_CLIENT_CCS_AFTER_SERVER_FINISHED

Definition at line 626 of file ssl.h.

enum mbedtls_tls_prf_types

Enumerator
MBEDTLS_SSL_TLS_PRF_NONE
MBEDTLS_SSL_TLS_PRF_SHA384
MBEDTLS_SSL_TLS_PRF_SHA256
MBEDTLS_SSL_HKDF_EXPAND_SHA384
MBEDTLS_SSL_HKDF_EXPAND_SHA256

Definition at line 1171 of file ssl.h.

Function Documentation

int mbedtls_ssl_check_pending ( const mbedtls_ssl_context * ssl )

Check if there is data already read from the underlying transport but not yet processed.

Parameters

ssl	SSL context

Returns: 0 if nothing's pending, 1 otherwise.

Note: This is different in purpose and behaviour from mbedtls_ssl_get_bytes_avail in that it considers any kind of unprocessed data, not only unread application data. If mbedtls_ssl_get_bytes returns a non-zero value, this function will also signal pending data, but the converse does not hold. For example, in DTLS there might be further records waiting to be processed from the current underlying transport's datagram.; If this function returns 1 (data pending), this does not imply that a subsequent call to mbedtls_ssl_read will provide any data; e.g., the unprocessed data might turn out to be an alert or a handshake message.; This function is useful in the following situation: If the SSL/TLS module successfully returns from an operation - e.g. a handshake or an application record read - and you're awaiting incoming data next, you must not immediately idle on the underlying transport to have data ready, but you need to check the value of this function first. The reason is that the desired data might already be read but not yet processed. If, in contrast, a previous call to the SSL/TLS module returned MBEDTLS_ERR_SSL_WANT_READ, it is not necessary to call this function, as the latter error code entails that all internal data has been processed.

int mbedtls_ssl_check_record	(	mbedtls_ssl_context const *	ssl,
		unsigned char *	buf,
		size_t	buflen
	)

Check whether a buffer contains a valid and authentic record that has not been seen before. (DTLS only).

This function does not change the user-visible state of the SSL context. Its sole purpose is to provide an indication of the legitimacy of an incoming record.

This can be useful e.g. in distributed server environments using the DTLS Connection ID feature, in which connections might need to be passed between service instances on a change of peer address, but where such disruptive operations should only happen after the validity of incoming records has been confirmed.

Parameters

ssl	The SSL context to use.
buf	The address of the buffer holding the record to be checked. This must be a read/write buffer of length `buflen` Bytes.
buflen	The length of `buf` in Bytes.

Note: This routine only checks whether the provided buffer begins with a valid and authentic record that has not been seen before, but does not check potential data following the initial record. In particular, it is possible to pass DTLS datagrams containing multiple records, in which case only the first record is checked.; This function modifies the input buffer buf. If you need to preserve the original record, you have to maintain a copy.

Returns: 0 if the record is valid and authentic and has not been seen before.; MBEDTLS_ERR_SSL_INVALID_MAC if the check completed successfully but the record was found to be not authentic.; MBEDTLS_ERR_SSL_INVALID_RECORD if the check completed successfully but the record was found to be invalid for a reason different from authenticity checking.; MBEDTLS_ERR_SSL_UNEXPECTED_RECORD if the check completed successfully but the record was found to be unexpected in the state of the SSL context, including replayed records.; Another negative error code on different kinds of failure. In this case, the SSL context becomes unusable and needs to be freed or reset before reuse.

int mbedtls_ssl_close_notify ( mbedtls_ssl_context * ssl )

Notify the peer that the connection is being closed.

Parameters

ssl	SSL context

Returns: 0 if successful, or a specific SSL error code.

Note: If this function returns something other than 0 or MBEDTLS_ERR_SSL_WANT_READ/WRITE, you must stop using the SSL context for reading or writing, and either free it or call mbedtls_ssl_session_reset() on it before re-using it for a new connection; the current connection must be closed.

int mbedtls_ssl_conf_alpn_protocols	(	mbedtls_ssl_config *	conf,
		const char **	protos
	)

Set the supported Application Layer Protocols.

Parameters

conf	SSL configuration
protos	Pointer to a NULL-terminated list of supported protocols, in decreasing preference order. The pointer to the list is recorded by the library for later reference as required, so the lifetime of the table must be atleast as long as the lifetime of the SSL configuration structure.

Returns: 0 on success, or MBEDTLS_ERR_SSL_BAD_INPUT_DATA.

void mbedtls_ssl_conf_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` unless `f_async_sign` and `f_async_decrypt` are both `NULL`.
f_async_cancel	Callback to cancel an asynchronous operation. See the description of mbedtls_ssl_async_cancel_t for more information. This may be `NULL` if no cleanup is needed.
config_data	A pointer to configuration data which can be retrieved with mbedtls_ssl_conf_get_async_config_data(). The library stores this value without dereferencing it.

void mbedtls_ssl_conf_authmode	(	mbedtls_ssl_config *	conf,
		int	authmode
	)

Set the certificate verification mode Default: NONE on server, REQUIRED on client.

Parameters

conf	SSL configuration
authmode	can be:

MBEDTLS_SSL_VERIFY_NONE: peer certificate is not checked (default on server) (insecure on client)

MBEDTLS_SSL_VERIFY_OPTIONAL: peer certificate is checked, however the handshake continues even if verification failed; mbedtls_ssl_get_verify_result() can be called after the handshake is complete.

MBEDTLS_SSL_VERIFY_REQUIRED: peer must present a valid certificate, handshake is aborted if verification failed. (default on client)

Note: On client, MBEDTLS_SSL_VERIFY_REQUIRED is the recommended mode. With MBEDTLS_SSL_VERIFY_OPTIONAL, the user needs to call mbedtls_ssl_get_verify_result() at the right time(s), which may not be obvious, while REQUIRED always perform the verification as soon as possible. For example, REQUIRED was protecting against the "triple handshake" attack even before it was found.

void mbedtls_ssl_conf_ca_cb	(	mbedtls_ssl_config *	conf,
		mbedtls_x509_crt_ca_cb_t	f_ca_cb,
		void *	p_ca_cb
	)

Set the trusted certificate callback.

This API allows to register the set of trusted certificates through a callback, instead of a linked list as configured by mbedtls_ssl_conf_ca_chain().

This is useful for example in contexts where a large number of CAs are used, and the inefficiency of maintaining them in a linked list cannot be tolerated. It is also useful when the set of trusted CAs needs to be modified frequently.

See the documentation of mbedtls_x509_crt_ca_cb_t for more information.

Parameters

conf	The SSL configuration to register the callback with.
f_ca_cb	The trusted certificate callback to use when verifying certificate chains.
p_ca_cb	The context to be passed to `f_ca_cb` (for example, a reference to a trusted CA database).

Note: This API is incompatible with mbedtls_ssl_conf_ca_chain(): Any call to this function overwrites the values set through earlier calls to mbedtls_ssl_conf_ca_chain() or mbedtls_ssl_conf_ca_cb().; This API is incompatible with CA indication in CertificateRequest messages: A server-side SSL context which is bound to an SSL configuration that uses a CA callback configured via mbedtls_ssl_conf_ca_cb(), and which requires client authentication, will send an empty CA list in the corresponding CertificateRequest message.; This API is incompatible with mbedtls_ssl_set_hs_ca_chain(): If an SSL context is bound to an SSL configuration which uses CA callbacks configured via mbedtls_ssl_conf_ca_cb(), then calls to mbedtls_ssl_set_hs_ca_chain() have no effect.; The use of this API disables the use of restartable ECC during X.509 CRT signature verification (but doesn't affect other uses).

Warning: This API is incompatible with the use of CRLs. Any call to mbedtls_ssl_conf_ca_cb() unsets CRLs configured through earlier calls to mbedtls_ssl_conf_ca_chain().; In multi-threaded environments, the callback f_ca_cb must be thread-safe, and it is the user's responsibility to guarantee this (for example through a mutex contained in the callback context pointed to by p_ca_cb).

void mbedtls_ssl_conf_ca_chain	(	mbedtls_ssl_config *	conf,
		mbedtls_x509_crt *	ca_chain,
		mbedtls_x509_crl *	ca_crl
	)

Set the data required to verify peer certificate.

Note: See mbedtls_x509_crt_verify() for notes regarding the parameters ca_chain (maps to trust_ca for that function) and ca_crl.

Parameters

conf	SSL configuration
ca_chain	trusted CA chain (meaning all fully trusted top-level CAs)
ca_crl	trusted CA CRLs

void mbedtls_ssl_conf_cert_profile	(	mbedtls_ssl_config *	conf,
		const mbedtls_x509_crt_profile *	profile
	)

Set the X.509 security profile used for verification.

Note: The restrictions are enforced for all certificates in the chain. However, signatures in the handshake are not covered by this setting but by mbedtls_ssl_conf_sig_hashes().

Parameters

conf	SSL configuration
profile	Profile to use

void mbedtls_ssl_conf_cert_req_ca_list	(	mbedtls_ssl_config *	conf,
		char	cert_req_ca_list
	)

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_cid	(	mbedtls_ssl_config *	conf,
		size_t	len,
		int	ignore_other_cids
	)

Specify the length of Connection IDs for incoming encrypted DTLS records, as well as the behaviour on unexpected CIDs.

By default, the CID length is set to 0, and unexpected CIDs are silently ignored.

Parameters

conf	The SSL configuration to modify.
len	The length in Bytes of the CID fields in encrypted DTLS records using the CID mechanism. This must not be larger than MBEDTLS_SSL_CID_OUT_LEN_MAX.
ignore_other_cids	This determines the stack's behaviour when receiving a record with an unexpected CID. Possible values are: MBEDTLS_SSL_UNEXPECTED_CID_IGNORE In this case, the record is silently ignored. MBEDTLS_SSL_UNEXPECTED_CID_FAIL In this case, the stack fails with the specific error code MBEDTLS_ERR_SSL_UNEXPECTED_CID.

Note: The CID specification allows implementations to either use a common length for all incoming connection IDs or allow variable-length incoming IDs. Mbed TLS currently requires a common length for all connections sharing the same SSL configuration; this allows simpler parsing of record headers.

Returns: 0 on success.; MBEDTLS_ERR_SSL_BAD_INPUT_DATA if own_cid_len is too large.

void mbedtls_ssl_conf_ciphersuites	(	mbedtls_ssl_config *	conf,
		const int *	ciphersuites
	)

Set the list of allowed ciphersuites and the preference order. First in the list has the highest preference.

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 configuration conf.

Parameters

conf	The SSL configuration to modify.
ciphersuites	A 0-terminated list of IANA identifiers of supported ciphersuites, accessible through `MBEDTLS_TLS_XXX` and `MBEDTLS_TLS1_3_XXX` macros defined in ssl_ciphersuites.h.

void mbedtls_ssl_conf_dbg	(	mbedtls_ssl_config *	conf,
		void()(void , int, const char , int, const char )	f_dbg,
		void *	p_dbg
	)

Set the debug callback.

The callback has the following argument: void * opaque context for the callback int debug level const char * file name int line number const char * message

Parameters

conf	SSL configuration
f_dbg	debug function
p_dbg	debug parameter

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_dtls_anti_replay	(	mbedtls_ssl_config *	conf,
		char	mode
	)

Enable or disable anti-replay protection for DTLS. (DTLS only, no effect on TLS.) Default: enabled.

Parameters

conf	SSL configuration
mode	MBEDTLS_SSL_ANTI_REPLAY_ENABLED or MBEDTLS_SSL_ANTI_REPLAY_DISABLED.

Warning: Disabling this is a security risk unless the application protocol handles duplicated packets in a safe way. You should not disable this without careful consideration. However, if your application already detects duplicated packets and needs information about them to adjust its transmission strategy, then you'll want to disable this.

void mbedtls_ssl_conf_dtls_badmac_limit	(	mbedtls_ssl_config *	conf,
		unsigned	limit
	)

Set a limit on the number of records with a bad MAC before terminating the connection. (DTLS only, no effect on TLS.) Default: 0 (disabled).

Parameters

conf	SSL configuration
limit	Limit, or 0 to disable.

Note: If the limit is N, then the connection is terminated when the Nth non-authentic record is seen.; Records with an invalid header are not counted, only the ones going through the authentication-decryption phase.; This is a security trade-off related to the fact that it's often relatively easy for an active attacker ot inject UDP datagrams. On one hand, setting a low limit here makes it easier for such an attacker to forcibly terminated a connection. On the other hand, a high limit or no limit might make us waste resources checking authentication on many bogus packets.

void mbedtls_ssl_conf_dtls_cookies	(	mbedtls_ssl_config *	conf,
		mbedtls_ssl_cookie_write_t *	f_cookie_write,
		mbedtls_ssl_cookie_check_t *	f_cookie_check,
		void *	p_cookie
	)

Register callbacks for DTLS cookies (Server only. DTLS only.)

Default: dummy callbacks that fail, in order to force you to register working callbacks (and initialize their context).

To disable HelloVerifyRequest, register NULL callbacks.

Warning: Disabling hello verification allows your server to be used for amplification in DoS attacks against other hosts. Only disable if you known this can't happen in your particular environment.

Note: See comments on mbedtls_ssl_handshake() about handling the MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED that is expected on the first handshake attempt when this is enabled.; This is also necessary to handle client reconnection from the same port as described in RFC 6347 section 4.2.8 (only the variant with cookies is supported currently). See comments on mbedtls_ssl_read() for details.

Parameters

conf	SSL configuration
f_cookie_write	Cookie write callback
f_cookie_check	Cookie check callback
p_cookie	Context for both callbacks

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; MBEDTLS_ERR_SSL_BAD_INPUT_DATA when the list of protection profiles is incorrect.

void mbedtls_ssl_conf_encrypt_then_mac	(	mbedtls_ssl_config *	conf,
		char	etm
	)

Enable or disable Encrypt-then-MAC (Default: MBEDTLS_SSL_ETM_ENABLED)

Note: This should always be enabled, it is a security improvement, and should not cause any interoperability issue (used only if the peer supports it too).

Parameters

conf	SSL configuration
etm	MBEDTLS_SSL_ETM_ENABLED or MBEDTLS_SSL_ETM_DISABLED

void mbedtls_ssl_conf_endpoint	(	mbedtls_ssl_config *	conf,
		int	endpoint
	)

Set the current endpoint type.

Parameters

conf	SSL configuration
endpoint	must be MBEDTLS_SSL_IS_CLIENT or MBEDTLS_SSL_IS_SERVER

void mbedtls_ssl_conf_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_get_async_config_data ( const mbedtls_ssl_config * conf )

Retrieve the configuration data set by mbedtls_ssl_conf_async_private_cb().

Parameters

conf	SSL configuration context

Returns: The configuration data set by mbedtls_ssl_conf_async_private_cb().

void mbedtls_ssl_conf_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.; The most recent invocation of either mbedtls_ssl_conf_curves() or mbedtls_ssl_conf_groups() nullifies all previous invocations of both.; This list should be ordered by decreasing preference (preferred group first).; 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.; 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_handshake_timeout	(	mbedtls_ssl_config *	conf,
		uint32_t	min,
		uint32_t	max
	)

Set retransmit timeout values for the DTLS handshake. (DTLS only, no effect on TLS.)

Parameters

conf	SSL configuration
min	Initial timeout value in milliseconds. Default: 1000 (1 second).
max	Maximum timeout value in milliseconds. Default: 60000 (60 seconds).

Note: Default values are from RFC 6347 section 4.2.4.1.; The 'min' value should typically be slightly above the expected round-trip time to your peer, plus whatever time it takes for the peer to process the message. For example, if your RTT is about 600ms and you peer needs up to 1s to do the cryptographic operations in the handshake, then you should set 'min' slightly above 1600. Lower values of 'min' might cause spurious resends which waste network resources, while larger value of 'min' will increase overall latency on unreliable network links.; The more unreliable your network connection is, the larger your max / min ratio needs to be in order to achieve reliable handshakes.; Messages are retransmitted up to log2(ceil(max/min)) times. For example, if min = 1s and max = 5s, the retransmit plan goes: send ... 1s -> resend ... 2s -> resend ... 4s -> resend ... 5s -> give up and return a timeout error.

void mbedtls_ssl_conf_legacy_renegotiation	(	mbedtls_ssl_config *	conf,
		int	allow_legacy
	)

Prevent or allow legacy renegotiation. (Default: MBEDTLS_SSL_LEGACY_NO_RENEGOTIATION)

MBEDTLS_SSL_LEGACY_NO_RENEGOTIATION allows connections to be established even if the peer does not support secure renegotiation, but does not allow renegotiation to take place if not secure. (Interoperable and secure option)

MBEDTLS_SSL_LEGACY_ALLOW_RENEGOTIATION allows renegotiations with non-upgraded peers. Allowing legacy renegotiation makes the connection vulnerable to specific man in the middle attacks. (See RFC 5746) (Most interoperable and least secure option)

MBEDTLS_SSL_LEGACY_BREAK_HANDSHAKE breaks off connections if peer does not support secure renegotiation. Results in interoperability issues with non-upgraded peers that do not support renegotiation altogether. (Most secure option, interoperability issues)

Parameters

conf	SSL configuration
allow_legacy	Prevent or allow (SSL_NO_LEGACY_RENEGOTIATION, SSL_ALLOW_LEGACY_RENEGOTIATION or MBEDTLS_SSL_LEGACY_BREAK_HANDSHAKE)

int mbedtls_ssl_conf_max_frag_len	(	mbedtls_ssl_config *	conf,
		unsigned char	mfl_code
	)

Set the maximum fragment length to emit and/or negotiate. (Typical: the smaller of MBEDTLS_SSL_IN_CONTENT_LEN and MBEDTLS_SSL_OUT_CONTENT_LEN, usually 2^14 bytes) (Server: set maximum fragment length to emit, usually negotiated by the client during handshake) (Client: set maximum fragment length to emit and negotiate with the server during handshake) (Default: MBEDTLS_SSL_MAX_FRAG_LEN_NONE)

Note: On the client side, the maximum fragment length extension will not be used, unless the maximum fragment length has been set via this function to a value different than MBEDTLS_SSL_MAX_FRAG_LEN_NONE.; With TLS, this currently only affects ApplicationData (sent with mbedtls_ssl_read()), not handshake messages. With DTLS, this affects both ApplicationData and handshake.; This sets the maximum length for a record's payload, excluding record overhead that will be added to it, see mbedtls_ssl_get_record_expansion().; For DTLS, it is also possible to set a limit for the total size of daragrams passed to the transport layer, including record overhead, see mbedtls_ssl_set_mtu().

Parameters

conf	SSL configuration
mfl_code	Code for maximum fragment length (allowed values: MBEDTLS_SSL_MAX_FRAG_LEN_512, MBEDTLS_SSL_MAX_FRAG_LEN_1024, MBEDTLS_SSL_MAX_FRAG_LEN_2048, MBEDTLS_SSL_MAX_FRAG_LEN_4096)

Returns: 0 if successful or MBEDTLS_ERR_SSL_BAD_INPUT_DATA

void mbedtls_ssl_conf_max_version	(	mbedtls_ssl_config *	conf,
		int	major,
		int	minor
	)

Set the maximum supported version sent from the client side and/or accepted at the server side (Default: MBEDTLS_SSL_MAX_MAJOR_VERSION, MBEDTLS_SSL_MAX_MINOR_VERSION)

Note: This ignores ciphersuites from higher versions.; With DTLS, use MBEDTLS_SSL_MINOR_VERSION_3 for DTLS 1.2

Parameters

conf	SSL configuration
major	Major version number (only MBEDTLS_SSL_MAJOR_VERSION_3 supported)
minor	Minor version number (only MBEDTLS_SSL_MINOR_VERSION_3 supported)

void mbedtls_ssl_conf_min_version	(	mbedtls_ssl_config *	conf,
		int	major,
		int	minor
	)

Set the minimum accepted SSL/TLS protocol version (Default: TLS 1.2)

Note: Input outside of the SSL_MAX_XXXXX_VERSION and SSL_MIN_XXXXX_VERSION range is ignored.; With DTLS, use MBEDTLS_SSL_MINOR_VERSION_3 for DTLS 1.2

Parameters

conf	SSL configuration
major	Major version number (only MBEDTLS_SSL_MAJOR_VERSION_3 supported)
minor	Minor version number (only MBEDTLS_SSL_MINOR_VERSION_3 supported)

int mbedtls_ssl_conf_own_cert	(	mbedtls_ssl_config *	conf,
		mbedtls_x509_crt *	own_cert,
		mbedtls_pk_context *	pk_key
	)

Set own certificate chain and private key.

Note: own_cert should contain in order from the bottom up your certificate chain. The top certificate (self-signed) can be omitted.; On server, this function can be called multiple times to provision more than one cert/key pair (eg one ECDSA, one RSA with SHA-256, one RSA with SHA-1). An adequate certificate will be selected according to the client's advertised capabilities. In case multiple certificates are adequate, preference is given to the one set by the first call to this function, then second, etc.; On client, only the first call has any effect. That is, only one client certificate can be provisioned. The server's preferences in its CertficateRequest message will be ignored and our only cert will be sent regardless of whether it matches those preferences - the server can then decide what it wants to do with it.; The provided pk_key needs to match the public key in the first certificate in own_cert, or all handshakes using that certificate will fail. It is your responsibility to ensure that; this function will not perform any check. You may use mbedtls_pk_check_pair() in order to perform this check yourself, but be aware that this function can be computationally expensive on some key types.

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

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)

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.; A PSK set by mbedtls_ssl_set_hs_psk() in the PSK callback takes precedence over a PSK configured by this function.

Parameters

conf	The SSL configuration to register the PSK with.
psk	The pointer to the pre-shared key to use.
psk_len	The length of the pre-shared key in bytes.
psk_identity	The pointer to the pre-shared key identity.
psk_identity_len	The length of the pre-shared key identity in bytes.

Note: The PSK and its identity are copied internally and hence need not be preserved by the caller for the lifetime of the SSL configuration.

Returns: 0 if successful.; MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE if no more PSKs can be configured. In this case, the old PSK(s) remain intact.; Another negative error code on other kinds of failure.

void mbedtls_ssl_conf_psk_cb	(	mbedtls_ssl_config *	conf,
		int()(void , mbedtls_ssl_context , const unsigned char , size_t)	f_psk,
		void *	p_psk
	)

Set the PSK callback (server-side only).

If set, the PSK callback is called for each handshake where a PSK-based ciphersuite was negotiated. The caller provides the identity received and wants to receive the actual PSK data and length.

The callback has the following parameters:

void*: The opaque pointer p_psk.
mbedtls_ssl_context*: The SSL context to which the operation applies.
const unsigned char*: The PSK identity selected by the client.
size_t: The length of the PSK identity selected by the client.

If a valid PSK identity is found, the callback should use mbedtls_ssl_set_hs_psk() or mbedtls_ssl_set_hs_psk_opaque() on the SSL context to set the correct PSK and return 0. Any other return value will result in a denied PSK identity.

Note: A dynamic PSK (i.e. set by the PSK callback) takes precedence over a static PSK (i.e. set by mbedtls_ssl_conf_psk() or mbedtls_ssl_conf_psk_opaque()). This means that if you set a PSK callback using this function, you don't need to set a PSK using mbedtls_ssl_conf_psk() or mbedtls_ssl_conf_psk_opaque()).

Parameters

conf	The SSL configuration to register the callback with.
f_psk	The callback for selecting and setting the PSK based in the PSK identity chosen by the client.
p_psk	A pointer to an opaque structure to be passed to the callback, for example a PSK store.

int mbedtls_ssl_conf_psk_opaque	(	mbedtls_ssl_config *	conf,
		psa_key_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.; 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.

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 slot `psk` must be populated with a key of type PSA_ALG_CATEGORY_KEY_DERIVATION whose policy allows its use for the key derivation algorithm applied in the handshake.
psk_identity	The pointer to the pre-shared key identity.
psk_identity_len	The length of the pre-shared key identity in bytes.

Note: The PSK identity hint is copied internally and hence need not be preserved by the caller for the lifetime of the SSL configuration.

Returns: 0 if successful.; MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE if no more PSKs can be configured. In this case, the old PSK(s) remain intact.; Another negative error code on other kinds of failure.

void mbedtls_ssl_conf_read_timeout	(	mbedtls_ssl_config *	conf,
		uint32_t	timeout
	)

Set the timeout period for mbedtls_ssl_read() (Default: no timeout.)

Parameters

conf	SSL configuration context
timeout	Timeout value in milliseconds. Use 0 for no timeout (default).

Note: With blocking I/O, this will only work if a non-NULL f_recv_timeout was set with mbedtls_ssl_set_bio(). With non-blocking I/O, this will only work if timer callbacks were set with mbedtls_ssl_set_timer_cb().; With non-blocking I/O, you may also skip this function altogether and handle timeouts at the application layer.

void mbedtls_ssl_conf_renegotiation	(	mbedtls_ssl_config *	conf,
		int	renegotiation
	)

Enable / Disable renegotiation support for connection when initiated by peer (Default: MBEDTLS_SSL_RENEGOTIATION_DISABLED)

Warning: It is recommended to always disable renegotation unless you know you need it and you know what you're doing. In the past, there have been several issues associated with renegotiation or a poor understanding of its properties.

Note: Server-side, enabling renegotiation also makes the server susceptible to a resource DoS by a malicious client.

Parameters

conf	SSL configuration
renegotiation	Enable or disable (MBEDTLS_SSL_RENEGOTIATION_ENABLED or MBEDTLS_SSL_RENEGOTIATION_DISABLED)

void mbedtls_ssl_conf_renegotiation_enforced	(	mbedtls_ssl_config *	conf,
		int	max_records
	)

Enforce renegotiation requests. (Default: enforced, max_records = 16)

When we request a renegotiation, the peer can comply or ignore the request. This function allows us to decide whether to enforce our renegotiation requests by closing the connection if the peer doesn't comply.

However, records could already be in transit from the peer when the request is emitted. In order to increase reliability, we can accept a number of records before the expected handshake records.

The optimal value is highly dependent on the specific usage scenario.

Note

With DTLS and server-initiated renegotiation, the HelloRequest is retransmited every time mbedtls_ssl_read() times out or receives Application Data, until:

max_records records have beens seen, if it is >= 0, or
the number of retransmits that would happen during an actual handshake has been reached. Please remember the request might be lost a few times if you consider setting max_records to a really low value.

Warning: On client, the grace period can only happen during mbedtls_ssl_read(), as opposed to mbedtls_ssl_write() and mbedtls_ssl_renegotiate() which always behave as if max_record was 0. The reason is, if we receive application data from the server, we need a place to write it, which only happens during mbedtls_ssl_read().

Parameters

conf	SSL configuration
max_records	Use MBEDTLS_SSL_RENEGOTIATION_NOT_ENFORCED if you don't want to enforce renegotiation, or a non-negative value to enforce it but allow for a grace period of max_records records.

void mbedtls_ssl_conf_renegotiation_period	(	mbedtls_ssl_config *	conf,
		const unsigned char	period[8]
	)

Set record counter threshold for periodic renegotiation. (Default: 2^48 - 1)

Renegotiation is automatically triggered when a record counter (outgoing or incoming) crosses the defined threshold. The default value is meant to prevent the connection from being closed when the counter is about to reached its maximal value (it is not allowed to wrap).

Lower values can be used to enforce policies such as "keys must be refreshed every N packets with cipher X".

The renegotiation period can be disabled by setting conf->disable_renegotiation to MBEDTLS_SSL_RENEGOTIATION_DISABLED.

Note: When the configured transport is MBEDTLS_SSL_TRANSPORT_DATAGRAM the maximum renegotiation period is 2^48 - 1, and for MBEDTLS_SSL_TRANSPORT_STREAM, the maximum renegotiation period is 2^64 - 1.

Parameters

conf	SSL configuration
period	The threshold value: a big-endian 64-bit number.

void mbedtls_ssl_conf_rng	(	mbedtls_ssl_config *	conf,
		int()(void , unsigned char *, size_t)	f_rng,
		void *	p_rng
	)

Set the random number generator callback.

Parameters

conf	SSL configuration
f_rng	RNG function (mandatory)
p_rng	RNG parameter

void mbedtls_ssl_conf_session_cache	(	mbedtls_ssl_config *	conf,
		void *	p_cache,
		mbedtls_ssl_cache_get_t *	f_get_cache,
		mbedtls_ssl_cache_set_t *	f_set_cache
	)

Set the session cache callbacks (server-side only) If not set, no session resuming is done (except if session tickets are enabled too).

The session cache has the responsibility to check for stale entries based on timeout. See RFC 5246 for recommendations.

Warning: session.peer_cert is cleared by the SSL/TLS layer on connection shutdown, so do not cache the pointer! Either set it to NULL or make a full copy of the certificate.

The get callback is called once during the initial handshake to enable session resuming. The get function has the following parameters: (void *parameter, mbedtls_ssl_session *session) If a valid entry is found, it should fill the master of the session object with the cached values and return 0, return 1 otherwise. Optionally peer_cert can be set as well if it is properly present in cache entry.

The set callback is called once during the initial handshake to enable session resuming after the entire handshake has been finished. The set function has the following parameters: (void *parameter, const mbedtls_ssl_session *session). The function should create a cache entry for future retrieval based on the data in the session structure and should keep in mind that the mbedtls_ssl_session object presented (and all its referenced data) is cleared by the SSL/TLS layer when the connection is terminated. It is recommended to add metadata to determine if an entry is still valid in the future. Return 0 if successfully cached, return 1 otherwise.

Parameters

conf	SSL configuration
p_cache	parmater (context) for both callbacks
f_get_cache	session get callback
f_set_cache	session set callback

void mbedtls_ssl_conf_session_tickets	(	mbedtls_ssl_config *	conf,
		int	use_tickets
	)

Enable / Disable session tickets (client only). (Default: MBEDTLS_SSL_SESSION_TICKETS_ENABLED.)

Note: On server, use mbedtls_ssl_conf_session_tickets_cb().

Parameters

conf	SSL configuration
use_tickets	Enable or disable (MBEDTLS_SSL_SESSION_TICKETS_ENABLED or MBEDTLS_SSL_SESSION_TICKETS_DISABLED)

void mbedtls_ssl_conf_session_tickets_cb	(	mbedtls_ssl_config *	conf,
		mbedtls_ssl_ticket_write_t *	f_ticket_write,
		mbedtls_ssl_ticket_parse_t *	f_ticket_parse,
		void *	p_ticket
	)

Configure SSL session ticket callbacks (server only). (Default: none.)

Note: On server, session tickets are enabled by providing non-NULL callbacks.; On client, use mbedtls_ssl_conf_session_tickets().

Parameters

conf	SSL configuration context
f_ticket_write	Callback for writing a ticket
f_ticket_parse	Callback for parsing a ticket
p_ticket	Context shared by the two callbacks

void mbedtls_ssl_conf_sig_algs	(	mbedtls_ssl_config *	conf,
		const uint16_t *	sig_algs
	)

Configure allowed signature algorithms for use in TLS 1.3.

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. Supported values are available as `MBEDTLS_TLS1_3_SIG_XXXX`

void mbedtls_ssl_conf_sig_hashes	(	mbedtls_ssl_config *	conf,
		const int *	hashes
	)

Set the allowed hashes for signatures during the handshake.

Note: This only affects which hashes are offered and can be used for signatures during the handshake. Hashes for message authentication and the TLS PRF are controlled by the ciphersuite, see mbedtls_ssl_conf_ciphersuites(). Hashes used for certificate signature are controlled by the verification profile, see mbedtls_ssl_conf_cert_profile().; This list should be ordered by decreasing preference (preferred hash first).; By default, all supported hashes whose length is at least 256 bits are allowed. This is the same set as the default for certificate verification (mbedtls_x509_crt_profile_default). The preference order is currently unspecified and may change in future versions.; New minor versions of Mbed TLS may extend this list, for example if new curves are added to the library. New minor versions of Mbed TLS will not remove items from this list unless serious security concerns require it.

Parameters

conf	SSL configuration
hashes	Ordered list of allowed signature hashes, terminated by `MBEDTLS_MD_NONE`.

void mbedtls_ssl_conf_sni	(	mbedtls_ssl_config *	conf,
		int()(void , mbedtls_ssl_context , const unsigned char , size_t)	f_sni,
		void *	p_sni
	)

Set server side ServerName TLS extension callback (optional, server-side only).

If set, the ServerName callback is called whenever the server receives a ServerName TLS extension from the client during a handshake. The ServerName callback has the following parameters: (void *parameter, mbedtls_ssl_context *ssl, const unsigned char *hostname, size_t len). If a suitable certificate is found, the callback must set the certificate(s) and key(s) to use with mbedtls_ssl_set_hs_own_cert() (can be called repeatedly), and may optionally adjust the CA and associated CRL with mbedtls_ssl_set_hs_ca_chain() as well as the client authentication mode with mbedtls_ssl_set_hs_authmode(), then must return 0. If no matching name is found, the callback must either set a default cert, or return non-zero to abort the handshake at this point.

Parameters

conf	SSL configuration
f_sni	verification function
p_sni	verification parameter

void mbedtls_ssl_conf_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.

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.

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.

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.; If a pure-ephemeral key exchange mode shall be supported, server-side applications must also provide a certificate via mbedtls_ssl_conf_own_cert().

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 with mbedtls_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_verify	(	mbedtls_ssl_config *	conf,
		int()(void , mbedtls_x509_crt , int, uint32_t )	f_vrfy,
		void *	p_vrfy
	)

Set the verification callback (Optional).

If set, the provided verify callback is called for each certificate in the peer's CRT chain, including the trusted root. For more information, please see the documentation of mbedtls_x509_crt_verify().

Note: For per context callbacks and contexts, please use mbedtls_ssl_set_verify() instead.

Parameters

conf	The SSL configuration to use.
f_vrfy	The verification callback to use during CRT verification.
p_vrfy	The opaque context to be passed to the callback.

int mbedtls_ssl_config_defaults	(	mbedtls_ssl_config *	conf,
		int	endpoint,
		int	transport,
		int	preset
	)

Load reasonnable default SSL configuration values. (You need to call mbedtls_ssl_config_init() first.)

Parameters

conf	SSL configuration context
endpoint	MBEDTLS_SSL_IS_CLIENT or MBEDTLS_SSL_IS_SERVER
transport	MBEDTLS_SSL_TRANSPORT_STREAM for TLS, or MBEDTLS_SSL_TRANSPORT_DATAGRAM for DTLS
preset	a MBEDTLS_SSL_PRESET_XXX value

Note: See mbedtls_ssl_conf_transport() for notes on DTLS.

Returns: 0 if successful, or MBEDTLS_ERR_XXX_ALLOC_FAILED on memory allocation error.

void mbedtls_ssl_config_free ( mbedtls_ssl_config * conf )

Free an SSL configuration context.

Parameters

conf	SSL configuration context

void mbedtls_ssl_config_init ( mbedtls_ssl_config * conf )

Initialize an SSL configuration context Just makes the context ready for mbedtls_ssl_config_defaults() or mbedtls_ssl_config_free().

Note: You need to call mbedtls_ssl_config_defaults() unless you manually set all of the relevant fields yourself.

Parameters

conf	SSL configuration context

int mbedtls_ssl_context_load	(	mbedtls_ssl_context *	ssl,
		const unsigned char *	buf,
		size_t	len
	)

Load serialized connection data to an SSL context.

See Also: mbedtls_ssl_context_save()

Warning: The same serialized data must never be loaded into more that one context. In order to ensure that, after successfully loading serialized data to an SSL context, you should immediately destroy or invalidate all copies of the serialized data that was loaded. Loading the same data in more than one context would cause severe security failures including but not limited to loss of confidentiality.

Note: Before calling this function, the SSL context must be prepared in one of the two following ways. The first way is to take a context freshly initialised with mbedtls_ssl_init() and call mbedtls_ssl_setup() on it with the same mbedtls_ssl_config structure that was used in the original connection. The second way is to call mbedtls_ssl_session_reset() on a context that was previously prepared as above but used in the meantime. Either way, you must not use the context to perform a handshake between calling mbedtls_ssl_setup() or mbedtls_ssl_session_reset() and calling this function. You may however call other setter functions in that time frame as indicated in the note below.; Before or after calling this function successfully, you also need to configure some connection-specific callbacks and settings before you can use the connection again (unless they were already set before calling mbedtls_ssl_session_reset() and the values are suitable for the present connection). Specifically, you want to call at least mbedtls_ssl_set_bio() and mbedtls_ssl_set_timer_cb(). All other SSL setter functions are not necessary to call, either because they're only used in handshakes, or because the setting is already saved. You might choose to call them anyway, for example in order to share code between the cases of establishing a new connection and the case of loading an already-established connection.; If you have new information about the path MTU, you want to call mbedtls_ssl_set_mtu() after calling this function, as otherwise this function would overwrite your newly-configured value with the value that was active when the context was saved.; When this function returns an error code, it calls mbedtls_ssl_free() on ssl. In this case, you need to prepare the context with the usual sequence starting with a call to mbedtls_ssl_init() if you want to use it again.

Parameters

ssl	The SSL context structure to be populated. It must have been prepared as described in the note above.
buf	The buffer holding the serialized connection data. It must be a readable buffer of at least `len` bytes.
len	The size of the serialized data in bytes.

Returns: 0 if successful.; MBEDTLS_ERR_SSL_ALLOC_FAILED if memory allocation failed.; MBEDTLS_ERR_SSL_VERSION_MISMATCH if the serialized data comes from a different Mbed TLS version or build.; MBEDTLS_ERR_SSL_BAD_INPUT_DATA if input data is invalid.

int mbedtls_ssl_context_save	(	mbedtls_ssl_context *	ssl,
		unsigned char *	buf,
		size_t	buf_len,
		size_t *	olen
	)

Save an active connection as serialized data in a buffer. This allows the freeing or re-using of the SSL context while still picking up the connection later in a way that it entirely transparent to the peer.

See Also: mbedtls_ssl_context_load()

Note: This feature is currently only available under certain conditions, see the documentation of the return value MBEDTLS_ERR_SSL_BAD_INPUT_DATA for details.; When this function succeeds, it calls mbedtls_ssl_session_reset() on ssl which as a result is no longer associated with the connection that has been serialized. This avoids creating copies of the connection state. You're then free to either re-use the context structure for a different connection, or call mbedtls_ssl_free() on it. See the documentation of mbedtls_ssl_session_reset() for more details.

Parameters

ssl	The SSL context to save. On success, it is no longer associated with the connection that has been serialized.
buf	The buffer to write the serialized data to. It must be a writeable buffer of at least `buf_len` bytes, or may be `NULL` if `buf_len` is `0`.
buf_len	The number of bytes available for writing in `buf`.
olen	The size in bytes of the data that has been or would have been written. It must point to a valid `size_t`.

Note: olen is updated to the correct value regardless of whether buf_len was large enough. This makes it possible to determine the necessary size by calling this function with buf set to NULL and buf_len to 0. However, the value of olen is only guaranteed to be correct when the function returns MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL or 0. If the return value is different, then the value of olen is undefined.

Returns: 0 if successful.; MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL if buf is too small.; MBEDTLS_ERR_SSL_ALLOC_FAILED if memory allocation failed while reseting the context.; MBEDTLS_ERR_SSL_BAD_INPUT_DATA if a handshake is in progress, or there is pending data for reading or sending, or the connection does not use DTLS 1.2 with an AEAD ciphersuite, or renegotiation is enabled.

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.

Parameters

ssl	SSL context to use.
mki_value	The MKI value to set.
mki_len	The length of the MKI value.

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.

Returns: 0 on success; MBEDTLS_ERR_SSL_BAD_INPUT_DATA; MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE

void mbedtls_ssl_free ( mbedtls_ssl_context * ssl )

Free referenced items in an SSL context and clear memory.

Parameters

ssl	SSL context

const char* mbedtls_ssl_get_alpn_protocol ( const mbedtls_ssl_context * ssl )

Get the name of the negotiated Application Layer Protocol. This function should be called after the handshake is completed.

Parameters

ssl	SSL context

Returns: Protcol name, or NULL if no protocol was negotiated.

void* mbedtls_ssl_get_async_operation_data ( const mbedtls_ssl_context * ssl )

Retrieve the asynchronous operation user context.

Note: This function may only be called while a handshake is in progress.

Parameters

ssl	The SSL context to access.

Returns: The asynchronous operation user context that was last set during the current handshake. If mbedtls_ssl_set_async_operation_data() has not yet been called during the current handshake, this function returns NULL.

size_t mbedtls_ssl_get_bytes_avail ( const mbedtls_ssl_context * ssl )

Return the number of application data bytes remaining to be read from the current record.

Parameters

ssl	SSL context

Returns: How many bytes are available in the application data record read buffer.

Note: When working over a datagram transport, this is useful to detect the current datagram's boundary in case mbedtls_ssl_read has written the maximal amount of data fitting into the input buffer.

const char* mbedtls_ssl_get_ciphersuite ( const mbedtls_ssl_context * ssl )

Return the name of the current ciphersuite.

Parameters

ssl	SSL context

Returns: a string containing the ciphersuite name

int mbedtls_ssl_get_ciphersuite_id ( const char * ciphersuite_name )

Return the ID of the ciphersuite associated with the given name.

Parameters

ciphersuite_name SSL ciphersuite name

Returns: the ID with the ciphersuite or 0 if not found

const char* mbedtls_ssl_get_ciphersuite_name ( const int ciphersuite_id )

Return the name of the ciphersuite associated with the given ID.

Parameters

ciphersuite_id SSL ciphersuite ID

Returns: a string containing the ciphersuite name

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 informations: 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 informations: 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 ).

int mbedtls_ssl_get_max_in_record_payload ( const mbedtls_ssl_context * ssl )

Return the current maximum incoming record payload in bytes.

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_IN_CONTENT_LEN, extensions such as the max fragment length extension or record size limit extension if used, and the current record expansion.

See Also: mbedtls_ssl_set_mtu(); mbedtls_ssl_get_max_in_record_payload(); mbedtls_ssl_get_record_expansion()

Parameters

ssl	SSL context

Returns: Current maximum payload for an outgoing record, or a negative error code.

int mbedtls_ssl_get_max_out_record_payload ( const mbedtls_ssl_context * ssl )

Return the current maximum outgoing record payload in bytes.

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.; 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 call mbedtls_ssl_write() again in order to send the remaining bytes if any.

See Also: mbedtls_ssl_get_max_out_record_payload(); mbedtls_ssl_get_record_expansion()

Parameters

ssl	SSL context

Returns: Current maximum payload for an outgoing record, or a negative error code.

const mbedtls_x509_crt* mbedtls_ssl_get_peer_cert ( const mbedtls_ssl_context * ssl )

Return the peer certificate from the current connection.

Parameters

ssl	The SSL context to use. This must be initialized and setup.

Returns: The current peer certificate, if available. The returned certificate is owned by the SSL context and is valid only until the next call to the SSL API.; NULL if no peer certificate is available. This might be because the chosen ciphersuite doesn't use CRTs (PSK-based ciphersuites, for example), or because MBEDTLS_SSL_KEEP_PEER_CERTIFICATE has been disabled, allowing the stack to free the peer's CRT to save memory.

Note: For one-time inspection of the peer's certificate during the handshake, consider registering an X.509 CRT verification callback through mbedtls_ssl_conf_verify() instead of calling this function. Using mbedtls_ssl_conf_verify() also comes at the benefit of allowing you to influence the verification process, for example by masking expected and tolerated verification failures.

Warning: You must not use the pointer returned by this function after any further call to the SSL API, including mbedtls_ssl_read() and mbedtls_ssl_write(); this is because the pointer might change during renegotiation, which happens transparently to the user. If you want to use the certificate across API calls, you must make a copy.

int mbedtls_ssl_get_peer_cid	(	mbedtls_ssl_context *	ssl,
		int *	enabled,
		unsigned char	peer_cid[MBEDTLS_SSL_CID_OUT_LEN_MAX],
		size_t *	peer_cid_len
	)

Get information about the use of the CID extension in the current connection.

Parameters

ssl	The SSL context to query.
enabled	The address at which to store whether the CID extension is currently in use or not. If the CID is in use, `*enabled` is set to MBEDTLS_SSL_CID_ENABLED; otherwise, it is set to MBEDTLS_SSL_CID_DISABLED.
peer_cid	The address of the buffer in which to store the CID chosen by the peer (if the CID extension is used). This may be `NULL` in case the value of peer CID isn't needed. If it is not `NULL`, `peer_cid_len` must not be `NULL`.
peer_cid_len	The address at which to store the size of the CID chosen by the peer (if the CID extension is used). This is also the number of Bytes in `peer_cid` that have been written. This may be `NULL` in case the length of the peer CID isn't needed. If it is `NULL`, `peer_cid` must be `NULL`, too.

Note: This applies to the state of the CID negotiated in the last complete handshake. If a handshake is in progress, this function will attempt to complete the handshake first.; If CID extensions have been exchanged but both client and server chose to use an empty CID, this function sets *enabled to MBEDTLS_SSL_CID_DISABLED (the rationale for this is that the resulting communication is the same as if the CID extensions hadn't been used).

Returns: 0 on success.; A negative error code on failure.

int mbedtls_ssl_get_record_expansion ( const mbedtls_ssl_context * ssl )

Return the (maximum) number of bytes added by the record layer: header + encryption/MAC overhead (inc. padding)

Parameters

ssl	SSL context

Returns: Current maximum record expansion in bytes

int mbedtls_ssl_get_session	(	const mbedtls_ssl_context *	ssl,
		mbedtls_ssl_session *	session
	)

Export a session in order to resume it later.

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_init_session() but otherwise be unused.

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, once implemented, sessions equate to tickets, and calling this function multiple times will export the available tickets one a time until no further tickets are available, in which case MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE will be returned.; Calling this function multiple times will only be useful once TLS 1.3 is supported. For TLS 1.2 connections, this function should be called at most once.

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().; MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE if no further session is available for export. This error is a non-fatal, and has no observable effect on the SSL context or the destination session.; Another negative error code on other kinds of failure.

See Also: mbedtls_ssl_set_session(); mbedtls_ssl_session_save()

static const char* mbedtls_ssl_get_srtp_profile_as_string ( mbedtls_ssl_srtp_profile profile )

inlinestatic

Definition at line 3471 of file ssl.h.

uint32_t mbedtls_ssl_get_verify_result ( const mbedtls_ssl_context * ssl )

Return the result of the certificate verification.

Parameters

ssl	The SSL context to use.

Returns: 0 if the certificate verification was successful.; -1u if the result is not available. This may happen e.g. if the handshake aborts early, or a verification callback returned a fatal error.; A bitwise combination of MBEDTLS_X509_BADCERT_XXX and MBEDTLS_X509_BADCRL_XXX failure flags; see x509.h.

const char* mbedtls_ssl_get_version ( const mbedtls_ssl_context * ssl )

Return the current TLS version.

Parameters

ssl	SSL context

Returns: a string containing the TLS version

int mbedtls_ssl_handshake ( mbedtls_ssl_context * ssl )

Perform the SSL handshake.

Parameters

ssl	SSL context

Returns: 0 if successful.; MBEDTLS_ERR_SSL_WANT_READ or MBEDTLS_ERR_SSL_WANT_WRITE if the handshake is incomplete and waiting for data to be available for reading from or writing to the underlying transport - in this case you must call this function again when the underlying transport is ready for the operation.; MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS if an asynchronous operation is in progress (see mbedtls_ssl_conf_async_private_cb()) - in this case you must call this function again when the operation is ready.; MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS if a cryptographic operation is in progress (see mbedtls_ecp_set_max_ops()) - in this case you must call this function again to complete the handshake when you're done attending other tasks.; MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED if DTLS is in use and the client did not demonstrate reachability yet - in this case you must stop using the context (see below).; Another SSL error code - in this case you must stop using the context (see below).

Warning: If this function returns something other than 0, MBEDTLS_ERR_SSL_WANT_READ, MBEDTLS_ERR_SSL_WANT_WRITE, MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS or MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS, you must stop using the SSL context for reading or writing, and either free it or call mbedtls_ssl_session_reset() on it before re-using it for a new connection; the current connection must be closed.

Note: If DTLS is in use, then you may choose to handle MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED specially for logging purposes, as it is an expected return value rather than an actual error, but you still need to reset/free the context.; Remarks regarding event-driven DTLS: If the function returns MBEDTLS_ERR_SSL_WANT_READ, no datagram from the underlying transport layer is currently being processed, and it is safe to idle until the timer or the underlying transport signal a new event. This is not true for a successful handshake, in which case the datagram of the underlying transport that is currently being processed might or might not contain further DTLS records.

int mbedtls_ssl_handshake_step ( mbedtls_ssl_context * ssl )

Perform a single step of the SSL handshake.

Note: The state of the context (ssl->state) will be at the next state after this function returns 0. Do not call this function if state is MBEDTLS_SSL_HANDSHAKE_OVER.

Parameters

ssl	SSL context

Returns: See mbedtls_ssl_handshake().

Warning: If this function returns something other than 0, MBEDTLS_ERR_SSL_WANT_READ, MBEDTLS_ERR_SSL_WANT_WRITE, MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS or MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS, you must stop using the SSL context for reading or writing, and either free it or call mbedtls_ssl_session_reset() on it before re-using it for a new connection; the current connection must be closed.

void mbedtls_ssl_init ( mbedtls_ssl_context * ssl )

Initialize an SSL context Just makes the context ready for mbedtls_ssl_setup() or mbedtls_ssl_free()

Parameters

ssl	SSL context

int mbedtls_ssl_read	(	mbedtls_ssl_context *	ssl,
		unsigned char *	buf,
		size_t	len
	)

Read at most 'len' application data bytes.

Parameters

ssl	SSL context
buf	buffer that will hold the data
len	maximum number of bytes to read

Returns: The (positive) number of bytes read if successful.; 0 if the read end of the underlying transport was closed without sending a CloseNotify beforehand, which might happen because of various reasons (internal error of an underlying stack, non-conformant peer not sending a CloseNotify and such) - in this case you must stop using the context (see below).; MBEDTLS_ERR_SSL_PEER_CLOSE_NOTIFY if the underlying transport is still functional, but the peer has acknowledged to not send anything anymore.; MBEDTLS_ERR_SSL_WANT_READ or MBEDTLS_ERR_SSL_WANT_WRITE if the handshake is incomplete and waiting for data to be available for reading from or writing to the underlying transport - in this case you must call this function again when the underlying transport is ready for the operation.; MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS if an asynchronous operation is in progress (see mbedtls_ssl_conf_async_private_cb()) - in this case you must call this function again when the operation is ready.; MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS if a cryptographic operation is in progress (see mbedtls_ecp_set_max_ops()) - in this case you must call this function again to complete the handshake when you're done attending other tasks.; MBEDTLS_ERR_SSL_CLIENT_RECONNECT if we're at the server side of a DTLS connection and the client is initiating a new connection using the same source port. See below.; Another SSL error code - in this case you must stop using the context (see below).

Warning: If this function returns something other than a positive value, MBEDTLS_ERR_SSL_WANT_READ, MBEDTLS_ERR_SSL_WANT_WRITE, MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS, MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS or MBEDTLS_ERR_SSL_CLIENT_RECONNECT, you must stop using the SSL context for reading or writing, and either free it or call mbedtls_ssl_session_reset() on it before re-using it for a new connection; the current connection must be closed.

Note

When this function returns MBEDTLS_ERR_SSL_CLIENT_RECONNECT (which can only happen server-side), it means that a client is initiating a new connection using the same source port. You can either treat that as a connection close and wait for the client to resend a ClientHello, or directly continue with mbedtls_ssl_handshake() with the same context (as it has been reset internally). Either way, you must make sure this is seen by the application as a new connection: application state, if any, should be reset, and most importantly the identity of the client must be checked again. WARNING: not validating the identity of the client again, or not transmitting the new identity to the application layer, would allow authentication bypass!

Remarks regarding event-driven DTLS:

If the function returns MBEDTLS_ERR_SSL_WANT_READ, no datagram from the underlying transport layer is currently being processed, and it is safe to idle until the timer or the underlying transport signal a new event.
This function may return MBEDTLS_ERR_SSL_WANT_READ even if data was initially available on the underlying transport, as this data may have been only e.g. duplicated messages or a renegotiation request. Therefore, you must be prepared to receive MBEDTLS_ERR_SSL_WANT_READ even when reacting to an incoming-data event from the underlying transport.
On success, the datagram of the underlying transport that is currently being processed may contain further DTLS records. You should call mbedtls_ssl_check_pending to check for remaining records.

int mbedtls_ssl_renegotiate ( mbedtls_ssl_context * ssl )

Initiate an SSL renegotiation on the running connection. Client: perform the renegotiation right now. Server: request renegotiation, which will be performed during the next call to mbedtls_ssl_read() if honored by client.

Parameters

ssl	SSL context

Returns: 0 if successful, or any mbedtls_ssl_handshake() return value except MBEDTLS_ERR_SSL_CLIENT_RECONNECT that can't happen during a renegotiation.

Warning: If this function returns something other than 0, MBEDTLS_ERR_SSL_WANT_READ, MBEDTLS_ERR_SSL_WANT_WRITE, MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS or MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS, you must stop using the SSL context for reading or writing, and either free it or call mbedtls_ssl_session_reset() on it before re-using it for a new connection; the current connection must be closed.

int mbedtls_ssl_send_alert_message	(	mbedtls_ssl_context *	ssl,
		unsigned char	level,
		unsigned char	message
	)

Send an alert message.

Parameters

ssl	SSL context
level	The alert level of the message (MBEDTLS_SSL_ALERT_LEVEL_WARNING or MBEDTLS_SSL_ALERT_LEVEL_FATAL)
message	The alert message (SSL_ALERT_MSG_*)

Returns: 0 if successful, or a specific SSL error code.

Note: If this function returns something other than 0 or MBEDTLS_ERR_SSL_WANT_READ/WRITE, you must stop using the SSL context for reading or writing, and either free it or call mbedtls_ssl_session_reset() on it before re-using it for a new connection; the current connection must be closed.

void mbedtls_ssl_session_free ( mbedtls_ssl_session * session )

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

void mbedtls_ssl_session_init ( mbedtls_ssl_session * session )

Initialize SSL session structure.

Parameters

session SSL session

int mbedtls_ssl_session_load	(	mbedtls_ssl_session *	session,
		const unsigned char *	buf,
		size_t	len
	)

Load serialized session data into a session structure. On client, this can be used for loading saved sessions before resuming them with mbedstls_ssl_set_session(). On server, this can be used for alternative implementations of session cache or session tickets.

Warning: If a peer certificate chain is associated with the session, the serialized state will only contain the peer's end-entity certificate and the result of the chain verification (unless verification was disabled), but not the rest of the chain.

See Also: mbedtls_ssl_session_save(); mbedtls_ssl_set_session()

Parameters

session	The session structure to be populated. It must have been initialised with mbedtls_ssl_session_init() but not populated yet.
buf	The buffer holding the serialized session data. It must be a readable buffer of at least `len` bytes.
len	The size of the serialized data in bytes.

Returns: 0 if successful.; MBEDTLS_ERR_SSL_ALLOC_FAILED if memory allocation failed.; MBEDTLS_ERR_SSL_BAD_INPUT_DATA if input data is invalid.; MBEDTLS_ERR_SSL_VERSION_MISMATCH if the serialized data was generated in a different version or configuration of Mbed TLS.; Another negative value for other kinds of errors (for example, unsupported features in the embedded certificate).

int mbedtls_ssl_session_reset ( mbedtls_ssl_context * ssl )

Reset an already initialized SSL context for re-use while retaining application-set variables, function pointers and data.

Parameters

ssl	SSL context

Returns: 0 if successful, or MBEDTLS_ERR_SSL_ALLOC_FAILED or MBEDTLS_ERR_SSL_HW_ACCEL_FAILED

int mbedtls_ssl_session_save	(	const mbedtls_ssl_session *	session,
		unsigned char *	buf,
		size_t	buf_len,
		size_t *	olen
	)

Save session structure as serialized data in a buffer. On client, this can be used for saving session data, potentially in non-volatile storage, for resuming later. On server, this can be used for alternative implementations of session cache or session tickets.

See Also: mbedtls_ssl_session_load()

Parameters

session	The session structure to be saved.
buf	The buffer to write the serialized data to. It must be a writeable buffer of at least `len` bytes, or may be `NULL` if `len` is `0`.
buf_len	The number of bytes available for writing in `buf`.
olen	The size in bytes of the data that has been or would have been written. It must point to a valid `size_t`.

Note: olen is updated to the correct value regardless of whether buf_len was large enough. This makes it possible to determine the necessary size by calling this function with buf set to NULL and buf_len to 0.

Returns: 0 if successful.; MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL if buf is too small.

void mbedtls_ssl_set_async_operation_data	(	mbedtls_ssl_context *	ssl,
		void *	ctx
	)

Retrieve the asynchronous operation user context.

Note: This function may only be called while a handshake is in progress.

Parameters

ssl	The SSL context to access.
ctx	The new value of the asynchronous operation user context. Call mbedtls_ssl_get_async_operation_data() later during the same handshake to retrieve this value.

void mbedtls_ssl_set_bio	(	mbedtls_ssl_context *	ssl,
		void *	p_bio,
		mbedtls_ssl_send_t *	f_send,
		mbedtls_ssl_recv_t *	f_recv,
		mbedtls_ssl_recv_timeout_t *	f_recv_timeout
	)

Set the underlying BIO callbacks for write, read and read-with-timeout.

Parameters

ssl	SSL context
p_bio	parameter (context) shared by BIO callbacks
f_send	write callback
f_recv	read callback
f_recv_timeout	blocking read callback with timeout.

Note

One of f_recv or f_recv_timeout can be NULL, in which case the other is used. If both are non-NULL, f_recv_timeout is used and f_recv is ignored (as if it were NULL).

The two most common use cases are:

non-blocking I/O, f_recv != NULL, f_recv_timeout == NULL
blocking I/O, f_recv == NULL, f_recv_timout != NULL

For DTLS, you need to provide either a non-NULL f_recv_timeout callback, or a f_recv that doesn't block.

See the documentations of mbedtls_ssl_send_t, mbedtls_ssl_recv_t and mbedtls_ssl_recv_timeout_t for the conventions those callbacks must follow.

On some platforms, net_sockets.c provides mbedtls_net_send(), mbedtls_net_recv() and mbedtls_net_recv_timeout() that are suitable to be used here.

int mbedtls_ssl_set_cid	(	mbedtls_ssl_context *	ssl,
		int	enable,
		unsigned char const *	own_cid,
		size_t	own_cid_len
	)

Configure the use of the Connection ID (CID) extension in the next handshake.

Reference: draft-ietf-tls-dtls-connection-id-05 https://tools.ietf.org/html/draft-ietf-tls-dtls-connection-id-05

The DTLS CID extension allows the reliable association of DTLS records to DTLS connections across changes in the underlying transport (changed IP and Port metadata) by adding explicit connection identifiers (CIDs) to the headers of encrypted DTLS records. The desired CIDs are configured by the application layer and are exchanged in new ClientHello / ServerHello extensions during the handshake, where each side indicates the CID it wants the peer to use when writing encrypted messages. The CIDs are put to use once records get encrypted: the stack discards any incoming records that don't include the configured CID in their header, and adds the peer's requested CID to the headers of outgoing messages.

This API enables or disables the use of the CID extension in the next handshake and sets the value of the CID to be used for incoming messages.

Parameters

ssl	The SSL context to configure. This must be initialized.
enable	This value determines whether the CID extension should be used or not. Possible values are: MBEDTLS_SSL_CID_ENABLED to enable the use of the CID. MBEDTLS_SSL_CID_DISABLED (default) to disable the use of the CID.
own_cid	The address of the readable buffer holding the CID we want the peer to use when sending encrypted messages to us. This may be `NULL` if `own_cid_len` is `0`. This parameter is unused if `enabled` is set to MBEDTLS_SSL_CID_DISABLED.
own_cid_len	The length of `own_cid`. This parameter is unused if `enabled` is set to MBEDTLS_SSL_CID_DISABLED.

Note

The value of own_cid_len must match the value of the len parameter passed to mbedtls_ssl_conf_cid() when configuring the mbedtls_ssl_config that ssl is bound to.

This CID configuration applies to subsequent handshakes performed on the SSL context ssl, but does not trigger one. You still have to call mbedtls_ssl_handshake() (for the initial handshake) or mbedtls_ssl_renegotiate() (for a renegotiation handshake) explicitly after a successful call to this function to run the handshake.

This call cannot guarantee that the use of the CID will be successfully negotiated in the next handshake, because the peer might not support it. Specifically:

On the Client, enabling the use of the CID through this call implies that the ClientHello in the next handshake will include the CID extension, thereby offering the use of the CID to the server. Only if the ServerHello contains the CID extension, too, the CID extension will actually be put to use.
On the Server, enabling the use of the CID through this call implies that that the server will look for the CID extension in a ClientHello from the client, and, if present, reply with a CID extension in its ServerHello.

To check whether the use of the CID was negotiated after the subsequent handshake has completed, please use the API mbedtls_ssl_get_peer_cid().

Warning: If the use of the CID extension is enabled in this call and the subsequent handshake negotiates its use, Mbed TLS will silently drop every packet whose CID does not match the CID configured in own_cid. It is the responsibility of the user to adapt the underlying transport to take care of CID-based demultiplexing before handing datagrams to Mbed TLS.

Returns: 0 on success. In this case, the CID configuration applies to the next handshake.; A negative error code on failure.

int mbedtls_ssl_set_client_transport_id	(	mbedtls_ssl_context *	ssl,
		const unsigned char *	info,
		size_t	ilen
	)

Set client's transport-level identification info. (Server only. DTLS only.)

This is usually the IP address (and port), but could be anything identify the client depending on the underlying network stack. Used for HelloVerifyRequest with DTLS. This is not used to route the actual packets.

Parameters

ssl	SSL context
info	Transport-level info identifying the client (eg IP + port)
ilen	Length of info in bytes

Note: An internal copy is made, so the info buffer can be reused.

Returns: 0 on success, MBEDTLS_ERR_SSL_BAD_INPUT_DATA if used on client, MBEDTLS_ERR_SSL_ALLOC_FAILED if out of memory.

void mbedtls_ssl_set_datagram_packing	(	mbedtls_ssl_context *	ssl,
		unsigned	allow_packing
	)

Allow or disallow packing of multiple handshake records within a single datagram.

Parameters

ssl	The SSL context to configure.
allow_packing	This determines whether datagram packing may be used or not. A value of `0` means that every record will be sent in a separate datagram; a value of `1` means that, if space permits, multiple handshake messages (including CCS) belonging to a single flight may be packed within a single datagram.

Note: This is enabled by default and should only be disabled for test purposes, or if datagram packing causes interoperability issues with peers that don't support it.; Allowing datagram packing reduces the network load since there's less overhead if multiple messages share the same datagram. Also, it increases the handshake efficiency since messages belonging to a single datagram will not be reordered in transit, and so future message buffering or flight retransmission (if no buffering is used) as means to deal with reordering are needed less frequently.; Application records are not affected by this option and are currently always sent in separate datagrams.

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`.

int mbedtls_ssl_set_hostname	(	mbedtls_ssl_context *	ssl,
		const char *	hostname
	)

Set or reset the hostname to check against the received server certificate. It sets the ServerName TLS extension, too, if that extension is enabled. (client-side only)

Parameters

ssl	SSL context
hostname	the server hostname, may be NULL to clear hostname

Note: Maximum hostname length MBEDTLS_SSL_MAX_HOST_NAME_LEN.

Returns: 0 if successful, MBEDTLS_ERR_SSL_ALLOC_FAILED on allocation failure, MBEDTLS_ERR_SSL_BAD_INPUT_DATA on too long input hostname.

Hostname set to the one provided on success (cleared when NULL). On allocation failure hostname is cleared. On too long input failure, old hostname is unchanged.

void mbedtls_ssl_set_hs_authmode	(	mbedtls_ssl_context *	ssl,
		int	authmode
	)

Set authmode for the current handshake.

Note: Same as mbedtls_ssl_conf_authmode() but for use within the SNI callback.

Parameters

ssl	SSL context
authmode	MBEDTLS_SSL_VERIFY_NONE, MBEDTLS_SSL_VERIFY_OPTIONAL or MBEDTLS_SSL_VERIFY_REQUIRED

void mbedtls_ssl_set_hs_ca_chain	(	mbedtls_ssl_context *	ssl,
		mbedtls_x509_crt *	ca_chain,
		mbedtls_x509_crl *	ca_crl
	)

Set the data required to verify peer certificate for the current handshake.

Note: Same as mbedtls_ssl_conf_ca_chain() but for use within the SNI callback.

Parameters

ssl	SSL context
ca_chain	trusted CA chain (meaning all fully trusted top-level CAs)
ca_crl	trusted CA CRLs

int mbedtls_ssl_set_hs_ecjpake_password	(	mbedtls_ssl_context *	ssl,
		const unsigned char *	pw,
		size_t	pw_len
	)

Set the EC J-PAKE password for current handshake.

Note: An internal copy is made, and destroyed as soon as the handshake is completed, or when the SSL context is reset or freed.; The SSL context needs to be already set up. The right place to call this function is between mbedtls_ssl_setup() or mbedtls_ssl_reset() and mbedtls_ssl_handshake().

Parameters

ssl	SSL context
pw	EC J-PAKE password (pre-shared secret)
pw_len	length of pw in bytes

Returns: 0 on success, or a negative error code.

int mbedtls_ssl_set_hs_own_cert	(	mbedtls_ssl_context *	ssl,
		mbedtls_x509_crt *	own_cert,
		mbedtls_pk_context *	pk_key
	)

Set own certificate and key for the current handshake.

Note: Same as mbedtls_ssl_conf_own_cert() but for use within the SNI callback.

Parameters

ssl	SSL context
own_cert	own public certificate chain
pk_key	own private key

Returns: 0 on success or MBEDTLS_ERR_SSL_ALLOC_FAILED

int mbedtls_ssl_set_hs_psk	(	mbedtls_ssl_context *	ssl,
		const unsigned char *	psk,
		size_t	psk_len
	)

Set the pre-shared Key (PSK) for the current handshake.

Note: This should only be called inside the PSK callback, i.e. the function passed to mbedtls_ssl_conf_psk_cb().; 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.; An MBEDTLS_ERR_SSL_XXX error code on failure.

int mbedtls_ssl_set_hs_psk_opaque	(	mbedtls_ssl_context *	ssl,
		psa_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().; 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.; An MBEDTLS_ERR_SSL_XXX error code on failure.

void mbedtls_ssl_set_mtu	(	mbedtls_ssl_context *	ssl,
		uint16_t	mtu
	)

Set the Maximum Tranport Unit (MTU). Special value: 0 means unset (no limit). This represents the maximum size of a datagram payload handled by the transport layer (usually UDP) as determined by the network link and stack. In practice, this controls the maximum size datagram the DTLS layer will pass to the f_send() callback set using mbedtls_ssl_set_bio().

Note: The limit on datagram size is converted to a limit on record payload by subtracting the current overhead of encapsulation and encryption/authentication if any.; This can be called at any point during the connection, for example when a Path Maximum Transfer Unit (PMTU) estimate becomes available from other sources, such as lower (or higher) protocol layers.; This setting only controls the size of the packets we send, and does not restrict the size of the datagrams we're willing to receive. Client-side, you can request the server to use smaller records with mbedtls_ssl_conf_max_frag_len().; If both a MTU and a maximum fragment length have been configured (or negotiated with the peer), the resulting lower limit on record payload (see first note) is used.; This can only be used to decrease the maximum size of datagrams (hence records, see first note) sent. It cannot be used to increase the maximum size of records over the limit set by MBEDTLS_SSL_OUT_CONTENT_LEN.; Values lower than the current record layer expansion will result in an error when trying to send data.

Parameters

ssl	SSL context
mtu	Value of the path MTU in bytes

int mbedtls_ssl_set_session	(	mbedtls_ssl_context *	ssl,
		const mbedtls_ssl_session *	session
	)

Load a session for session resumption.

Sessions loaded through this call will be considered for session resumption in the next handshake.

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.; 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, once implemented, sessions equate to tickets, and loading one or more sessions via this call will lead to their corresponding tickets being advertised as resumption PSKs by the client.; Calling this function multiple times will only be useful once TLS 1.3 is supported. For TLS 1.2 connections, this function should be called at most once.

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.; MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE if the session could not be loaded because of an implementation limitation. This error is non-fatal, and has no observable effect on the SSL context or the session that was attempted to be loaded.; Another negative error code on other kinds of failure.

See Also: mbedtls_ssl_get_session(); mbedtls_ssl_session_load()

void mbedtls_ssl_set_timer_cb	(	mbedtls_ssl_context *	ssl,
		void *	p_timer,
		mbedtls_ssl_set_timer_t *	f_set_timer,
		mbedtls_ssl_get_timer_t *	f_get_timer
	)

Set the timer callbacks (Mandatory for DTLS.)

Parameters

ssl	SSL context
p_timer	parameter (context) shared by timer callbacks
f_set_timer	set timer callback
f_get_timer	get timer callback. Must return:

Note: See the documentation of mbedtls_ssl_set_timer_t and mbedtls_ssl_get_timer_t for the conventions this pair of callbacks must follow.; On some platforms, timing.c provides mbedtls_timing_set_delay() and mbedtls_timing_get_delay() that are suitable for using here, except if using an event-driven style.; See also the "DTLS tutorial" article in our knowledge base. https://tls.mbed.org/kb/how-to/dtls-tutorial

void mbedtls_ssl_set_verify	(	mbedtls_ssl_context *	ssl,
		int()(void , mbedtls_x509_crt , int, uint32_t )	f_vrfy,
		void *	p_vrfy
	)

Set a connection-specific verification callback (optional).

If set, the provided verify callback is called for each certificate in the peer's CRT chain, including the trusted root. For more information, please see the documentation of mbedtls_x509_crt_verify().

Note: This call is analogous to mbedtls_ssl_conf_verify() but binds the verification callback and context to an SSL context as opposed to an SSL configuration. If mbedtls_ssl_conf_verify() and mbedtls_ssl_set_verify() are both used, mbedtls_ssl_set_verify() takes precedence.

Parameters

ssl	The SSL context to use.
f_vrfy	The verification callback to use during CRT verification.
p_vrfy	The opaque context to be passed to the callback.

int mbedtls_ssl_setup	(	mbedtls_ssl_context *	ssl,
		const mbedtls_ssl_config *	conf
	)

Set up an SSL context for use.

Note: No copy of the configuration context is made, it can be shared by many mbedtls_ssl_context structures.

Warning: The conf structure will be accessed during the session. It must not be modified or freed as long as the session is active.; This function must be called exactly once per context. Calling mbedtls_ssl_setup again is not supported, even if no session is active.

Parameters

ssl	SSL context
conf	SSL configuration to use

Returns: 0 if successful, or MBEDTLS_ERR_SSL_ALLOC_FAILED if memory allocation failed

int mbedtls_ssl_tls_prf	(	const mbedtls_tls_prf_types	prf,
		const unsigned char *	secret,
		size_t	slen,
		const char *	label,
		const unsigned char *	random,
		size_t	rlen,
		unsigned char *	dstbuf,
		size_t	dlen
	)

TLS-PRF function for key derivation.

Parameters

prf	The tls_prf type 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.

int mbedtls_ssl_write	(	mbedtls_ssl_context *	ssl,
		const unsigned char *	buf,
		size_t	len
	)

Try to write exactly 'len' application data bytes.

Warning: This function will do partial writes in some cases. If the return value is non-negative but less than length, the function must be called again with updated arguments: buf + ret, len - ret (if ret is the return value) until it returns a value equal to the last 'len' argument.

Parameters

ssl	SSL context
buf	buffer holding the data
len	how many bytes must be written

Returns: The (non-negative) number of bytes actually written if successful (may be less than len).; MBEDTLS_ERR_SSL_WANT_READ or MBEDTLS_ERR_SSL_WANT_WRITE if the handshake is incomplete and waiting for data to be available for reading from or writing to the underlying transport - in this case you must call this function again when the underlying transport is ready for the operation.; MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS if an asynchronous operation is in progress (see mbedtls_ssl_conf_async_private_cb()) - in this case you must call this function again when the operation is ready.; MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS if a cryptographic operation is in progress (see mbedtls_ecp_set_max_ops()) - in this case you must call this function again to complete the handshake when you're done attending other tasks.; Another SSL error code - in this case you must stop using the context (see below).

Warning: If this function returns something other than a non-negative value, MBEDTLS_ERR_SSL_WANT_READ, MBEDTLS_ERR_SSL_WANT_WRITE, MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS or MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS, you must stop using the SSL context for reading or writing, and either free it or call mbedtls_ssl_session_reset() on it before re-using it for a new connection; the current connection must be closed.

Note

When this function returns MBEDTLS_ERR_SSL_WANT_WRITE/READ, it must be called later with the same arguments, until it returns a value greater that or equal to 0. When the function returns MBEDTLS_ERR_SSL_WANT_WRITE there may be some partial data in the output buffer, however this is not yet sent.

If the requested length is greater than the maximum fragment length (either the built-in limit or the one set or negotiated with the peer), then:

with TLS, less bytes than requested are written.
with DTLS, MBEDTLS_ERR_SSL_BAD_INPUT_DATA is returned. mbedtls_ssl_get_max_out_record_payload() may be used to query the active maximum fragment length.

Attempting to write 0 bytes will result in an empty TLS application record being sent.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation