mbedtls_ssl_config_init() function

SSL configuration context

Set the certificate verification mode Default: NONE on server, REQUIRED on client MBEDTLS_SSL_VERIFY_NONE: peer certificate is not checked (default on server) (insecure on client) MBEDTLS_SSL_VERIFY_OPTIONAL: peer certificate is checked, however the handshake continues even if verification failed; mbedtls_ssl_get_verify_result() can be called after the handshake is complete. MBEDTLS_SSL_VERIFY_REQUIRED: peer *must* present a valid certificate, handshake is aborted if verification failed. (default on client)

Set the data required to verify peer certificate

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

Set up an SSL context for use \warning The conf structure will be accessed during the session. It must not be modified or freed as long as the session is active. \warning This function must be called exactly once per context. Calling mbedtls_ssl_setup again is not supported, even if no session is active.

Set the random number generator callback

Free an SSL configuration context

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. \warning The ciphersuites array \p ciphersuites is not copied. It must remain valid for the lifetime of the SSL configuration \p conf.

Set own certificate chain and private key

Configure allowed signature algorithms for use in TLS

Set the supported Application Layer Protocols.

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

Set the maximum supported version sent from the client side and/or accepted at the server side.

Set the minimum supported version sent from the client side and/or accepted at the server side.

Set the X.509 security profile used for verification

Enable / Disable renegotiation support for connection when initiated by peer (Default: MBEDTLS_SSL_RENEGOTIATION_DISABLED) \warning It is recommended to always disable renegotiation unless you know you need it and you know what you're doing. In the past, there have been several issues associated with renegotiation or a poor understanding of its properties.

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

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.

Set the current endpoint type

Set the transport type (TLS or DTLS). Default: TLS

Enable / Disable TLS 1.2 session tickets (client only, TLS 1.2 only). Enabled by default.

Set the Diffie-Hellman public P and G values from big-endian binary presentations. (Default values: MBEDTLS_DHM_RFC3526_MODP_2048_[PG]_BIN)

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.

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

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.

Set the user data in an SSL configuration to a pointer. You can retrieve this value later with mbedtls_ssl_conf_get_user_data_p().

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

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

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

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.

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 \c mbedtls_ssl_set_hs_own_cert() (can be called repeatedly), and may optionally adjust the CA and associated CRL with \c mbedtls_ssl_set_hs_ca_chain() as well as the client authentication mode with \c mbedtls_ssl_set_hs_authmode(), then must return 0. If no matching name is found, the callback may return non-zero to abort the handshake.

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

Enable or disable Extended Master Secret negotiation. (Default: MBEDTLS_SSL_EXTENDED_MS_ENABLED)

Whether to send a list of acceptable CAs in CertificateRequest messages. (Default: do send)

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)

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)

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)

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

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.

Disable and dealloc the certification bundle Removes the certificate verification callback and deallocates used resources

Set the Diffie-Hellman public P and G values, read from existing context (server-side only)

Set the minimum length for Diffie-Hellman parameters. (Client-side only.) (Default: 1024 bits.)

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.

Set the supported DTLS-SRTP protection profiles.

Enable or disable anti-replay protection for DTLS. (DTLS only, no effect on TLS.) Default: enabled. \warning Disabling this is a security risk unless the application protocol handles duplicated packets in a safe way. You should not disable this without careful consideration. However, if your application already detects duplicated packets and needs information about them to adjust its transmission strategy, then you'll want to disable this.

Set the PSK callback (server-side only). If set, the PSK callback is called for each handshake where a PSK-based ciphersuite was negotiated. The caller provides the identity received and wants to receive the actual PSK data and length. The callback has the following parameters: - \c void*: The opaque pointer \p p_psk. - \c mbedtls_ssl_context*: The SSL context to which the operation applies. - \c const unsigned char*: The PSK identity selected by the client. - \c size_t: The length of the PSK identity selected by the client. If a valid PSK identity is found, the callback should use \c mbedtls_ssl_set_hs_psk() or \c mbedtls_ssl_set_hs_psk_opaque() on the SSL context to set the correct PSK and return \c 0. Any other return value will result in a denied PSK identity.

Get the current endpoint type

Set the certificate selection callback (server-side only). If set, the callback is always called for each handshake, after `ClientHello` processing has finished.

Set the user data in an SSL configuration to an integer. You can retrieve this value later with mbedtls_ssl_conf_get_user_data_n().

Retrieve the user data in an SSL configuration as a pointer. This is the value last set with mbedtls_ssl_conf_set_user_data_p(), or \c NULL if mbedtls_ssl_conf_set_user_data_p() has not previously been called. The value is undefined if mbedtls_ssl_conf_set_user_data_n() has been called without a subsequent call to mbedtls_ssl_conf_set_user_data_p().

Retrieve the user data in an SSL configuration as an integer. This is the value last set with mbedtls_ssl_conf_set_user_data_n(), or \c 0 if mbedtls_ssl_conf_set_user_data_n() has not previously been called. The value is undefined if mbedtls_ssl_conf_set_user_data_p() has been called without a subsequent call to mbedtls_ssl_conf_set_user_data_n().

Set DN hints sent to client in CertificateRequest message