ssl.h File Reference

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 1189 of file ssl.h.

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 1172 of file ssl.h.

Callback type: Export key block and master secret.

Note:

This is required for certain uses of TLS, e.g. EAP-TLS (RFC 5216) and Thread. The key pointers are ephemeral and therefore must not be stored. The master secret and keys should not be used directly except as an input to a key derivation function.

Parameters:

p_expkey	Context for the callback
ms	Pointer to master secret (fixed length: 48 bytes)
kb	Pointer to key block, see RFC 5246 section 6.3 (variable length: 2 * maclen + 2 * keylen + 2 * ivlen).
maclen	MAC length
keylen	Key length
ivlen	IV length

Returns:

0 if successful, or a specific MBEDTLS_ERR_XXX code.

Definition at line 1085 of file ssl.h.

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 1116 of file ssl.h.

Callback type: generate and write session ticket.

Note:

This describes what a callback implementation should do. This callback should generate and 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 bo written in the ticket
start	Start of the outpur 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 1057 of file ssl.h.

Notify the peer that the connection is being closed.

Parameters:

ssl	SSL context

Definition at line 6831 of file ssl_tls.c.

Set the supported Application Layer Protocols.

Parameters:

conf	SSL configuration
protos	NULL-terminated list of supported protocols, in decreasing preference order.

Returns:

0 on success, or MBEDTLS_ERR_SSL_BAD_INPUT_DATA.

Definition at line 5944 of file ssl_tls.c.

Disable or enable support for RC4 (Default: MBEDTLS_SSL_ARC4_DISABLED)

Warning:

Use of RC4 in (D)TLS has been prohibited by RFC ???? for security reasons. Use at your own risks.

Note:

This function will likely be removed in future versions as RC4 will then be disabled by default at compile time.

Parameters:

conf	SSL configuration
arc4	MBEDTLS_SSL_ARC4_ENABLED or MBEDTLS_SSL_ARC4_DISABLED

Definition at line 6008 of file ssl_tls.c.

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.

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.

Definition at line 5541 of file ssl_tls.c.

Set the data required to verify peer certificate.

Parameters:

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

Definition at line 5703 of file ssl_tls.c.

Enable / Disable 1/n-1 record splitting (Default: MBEDTLS_SSL_CBC_RECORD_SPLITTING_ENABLED)

Note:

Only affects SSLv3 and TLS 1.0, not higher versions. Does not affect non-CBC ciphersuites in any version.

Parameters:

conf	SSL configuration
split	MBEDTLS_SSL_CBC_RECORD_SPLITTING_ENABLED or MBEDTLS_SSL_CBC_RECORD_SPLITTING_DISABLED

Definition at line 6037 of file ssl_tls.c.

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

Definition at line 5659 of file ssl_tls.c.

Set the list of allowed ciphersuites and the preference order.

First in the list has the highest preference. (Overrides all version specific lists)

The ciphersuites array is not copied, and must remain valid for the lifetime of the ssl_config.

Note: The server uses its own preferences over the preference of the client unless MBEDTLS_SSL_SRV_RESPECT_CLIENT_PREFERENCE is defined!

Parameters:

conf	SSL configuration
ciphersuites	0-terminated list of allowed ciphersuites

Definition at line 5636 of file ssl_tls.c.

Set the list of allowed ciphersuites and the preference order for a specific version of the protocol.

(Only useful on the server side)

The ciphersuites array is not copied, and must remain valid for the lifetime of the ssl_config.

Parameters:

conf	SSL configuration
ciphersuites	0-terminated list of allowed ciphersuites
major	Major version number (only MBEDTLS_SSL_MAJOR_VERSION_3 supported)
minor	Minor version number (MBEDTLS_SSL_MINOR_VERSION_0, MBEDTLS_SSL_MINOR_VERSION_1 and MBEDTLS_SSL_MINOR_VERSION_2, MBEDTLS_SSL_MINOR_VERSION_3 supported)

Note:

With DTLS, use MBEDTLS_SSL_MINOR_VERSION_2 for DTLS 1.0 and MBEDTLS_SSL_MINOR_VERSION_3 for DTLS 1.2

Definition at line 5645 of file ssl_tls.c.

Set the allowed curves in order of preference.

(Default: all defined curves.)

On server: this only affects selection of the ECDHE curve; the curves used for ECDH and ECDSA are determined by the list of available certificates instead.

On client: this affects the list of curves offered for any use. The server can override our preference order.

Both sides: limits the set of curves accepted for use in ECDHE and in the peer's end-entity certificate.

Note:

This has no influence on which curves are allowed inside the certificate chains, see mbedtls_ssl_conf_cert_profile() for that. For the end-entity certificate however, the key will be accepted only if it is allowed both by this list and by the cert profile.

This list should be ordered by decreasing preference (preferred curve first).

Parameters:

conf	SSL configuration
curves	Ordered list of allowed curves, terminated by MBEDTLS_ECP_DP_NONE.

Definition at line 5896 of file ssl_tls.c.

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

Definition at line 5564 of file ssl_tls.c.

Set the Diffie-Hellman public P and G values, read as hexadecimal strings (server-side only) (Default: MBEDTLS_DHM_RFC5114_MODP_2048_[PG])

Parameters:

conf	SSL configuration
dhm_P	Diffie-Hellman-Merkle modulus
dhm_G	Diffie-Hellman-Merkle generator

Returns:

0 if successful

Definition at line 5839 of file ssl_tls.c.

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

Definition at line 5854 of file ssl_tls.c.

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

Definition at line 5874 of file ssl_tls.c.

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.

Definition at line 5520 of file ssl_tls.c.

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.

Definition at line 5527 of file ssl_tls.c.

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

Definition at line 78 of file ssl_srv.c.

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

Definition at line 5994 of file ssl_tls.c.

Set the current endpoint type.

Parameters:

conf	SSL configuration
endpoint	must be MBEDTLS_SSL_IS_CLIENT or MBEDTLS_SSL_IS_SERVER

Definition at line 5509 of file ssl_tls.c.

Configure key export callback.

(Default: none.)

Note:

See mbedtls_ssl_export_keys_t.

Parameters:

conf	SSL configuration context
f_export_keys	Callback for exporting keys
p_export_keys	Context for the callback

Definition at line 6088 of file ssl_tls.c.

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

Definition at line 6001 of file ssl_tls.c.

Set the fallback flag (client-side only).

(Default: MBEDTLS_SSL_IS_NOT_FALLBACK).

Note:

Set to MBEDTLS_SSL_IS_FALLBACK when preparing a fallback connection, that is a connection with max_version set to a lower value than the value you're willing to use. Such fallback connections are not recommended but are sometimes necessary to interoperate with buggy (version-intolerant) servers.

Warning:

You should NOT set this to MBEDTLS_SSL_IS_FALLBACK for non-fallback connections! This would appear to work for a while, then cause failures when the server is upgraded to support a newer TLS version.

Parameters:

conf	SSL configuration
fallback	MBEDTLS_SSL_IS_NOT_FALLBACK or MBEDTLS_SSL_IS_FALLBACK

Definition at line 5987 of file ssl_tls.c.

Set retransmit timeout values for the DTLS handshale.

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

Higher values for initial timeout may increase average handshake latency. Lower values may increase the risk of network congestion by causing more retransmissions.

Definition at line 5534 of file ssl_tls.c.

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)

Definition at line 6043 of file ssl_tls.c.

Set the maximum fragment length to emit and/or negotiate (Default: MBEDTLS_SSL_MAX_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)

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

Definition at line 6015 of file ssl_tls.c.

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

Note:

This ignores ciphersuites from higher versions.

With DTLS, use MBEDTLS_SSL_MINOR_VERSION_2 for DTLS 1.0 and MBEDTLS_SSL_MINOR_VERSION_3 for DTLS 1.2

Parameters:

conf	SSL configuration
major	Major version number (only MBEDTLS_SSL_MAJOR_VERSION_3 supported)
minor	Minor version number (MBEDTLS_SSL_MINOR_VERSION_0, MBEDTLS_SSL_MINOR_VERSION_1 and MBEDTLS_SSL_MINOR_VERSION_2, MBEDTLS_SSL_MINOR_VERSION_3 supported)

Definition at line 5974 of file ssl_tls.c.

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

Note:

Input outside of the SSL_MAX_XXXXX_VERSION and SSL_MIN_XXXXX_VERSION range is ignored.

MBEDTLS_SSL_MINOR_VERSION_0 (SSL v3) should be avoided.

With DTLS, use MBEDTLS_SSL_MINOR_VERSION_2 for DTLS 1.0 and MBEDTLS_SSL_MINOR_VERSION_3 for DTLS 1.2

Parameters:

conf	SSL configuration
major	Major version number (only MBEDTLS_SSL_MAJOR_VERSION_3 supported)
minor	Minor version number (MBEDTLS_SSL_MINOR_VERSION_0, MBEDTLS_SSL_MINOR_VERSION_1 and MBEDTLS_SSL_MINOR_VERSION_2, MBEDTLS_SSL_MINOR_VERSION_3 supported)

Definition at line 5980 of file ssl_tls.c.

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

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

Definition at line 5696 of file ssl_tls.c.

Set the Pre Shared Key (PSK) and the expected identity name.

Note:

This is mainly useful for clients. Servers will usually want to use mbedtls_ssl_conf_psk_cb() instead.

Parameters:

conf	SSL configuration
psk	pointer to the pre-shared key
psk_len	pre-shared key length
psk_identity	pointer to the pre-shared key identity
psk_identity_len	identity key length

Returns:

0 if successful or MBEDTLS_ERR_SSL_ALLOC_FAILED

Definition at line 5763 of file ssl_tls.c.

Set the PSK callback (server-side only).

If set, the PSK callback is called for each handshake where a PSK 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 *parameter, mbedtls_ssl_context *ssl, const unsigned char *psk_identity, size_t identity_len) If a valid PSK identity is found, the callback should use mbedtls_ssl_set_hs_psk() on the ssl context to set the correct PSK and return 0. Any other return value will result in a denied PSK identity.

Note:

If you set a PSK callback using this function, then you don't need to set a PSK key and identity using mbedtls_ssl_conf_psk().

Parameters:

conf	SSL configuration
f_psk	PSK identity function
p_psk	PSK identity parameter

Definition at line 5828 of file ssl_tls.c.

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.

Definition at line 5584 of file ssl_tls.c.

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

Definition at line 6049 of file ssl_tls.c.

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.

Definition at line 6054 of file ssl_tls.c.

Set record counter threshold for periodic renegotiation.

(Default: 2^64 - 256.)

Renegotiation is automatically triggered when a record counter (outgoing or ingoing) 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".

Parameters:

conf	SSL configuration
period	The threshold value: a big-endian 64-bit number. Set to 2^64 - 1 to disable periodic renegotiation

Definition at line 6059 of file ssl_tls.c.

Set the random number generator callback.

Parameters:

conf	SSL configuration
f_rng	RNG function
p_rng	RNG parameter

Definition at line 5556 of file ssl_tls.c.

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

Definition at line 5603 of file ssl_tls.c.

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)

Definition at line 6068 of file ssl_tls.c.

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

Definition at line 6075 of file ssl_tls.c.

Set the allowed hashes for signatures during the handshake.

(Default: all available hashes.)

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

Parameters:

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

Definition at line 5885 of file ssl_tls.c.

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

Definition at line 5933 of file ssl_tls.c.

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.

Definition at line 5514 of file ssl_tls.c.

Activate negotiation of truncated HMAC (Default: MBEDTLS_SSL_TRUNC_HMAC_DISABLED)

Parameters:

conf	SSL configuration
truncate	Enable or disable (MBEDTLS_SSL_TRUNC_HMAC_ENABLED or MBEDTLS_SSL_TRUNC_HMAC_DISABLED)

Definition at line 6030 of file ssl_tls.c.

Set the verification callback (Optional).

If set, the verify callback is called for each certificate in the chain. For implementation information, please see x509parse_verify()

Parameters:

conf	SSL configuration
f_vrfy	verification function
p_vrfy	verification parameter

Definition at line 5547 of file ssl_tls.c.

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 (currently unused).

Note:

See mbedtls_ssl_conf_transport() for notes on DTLS.

Returns:

0 if successful, or MBEDTLS_ERR_XXX_ALLOC_FAILED on memory allocation error.

Definition at line 7099 of file ssl_tls.c.

Free an SSL configuration context.

Parameters:

conf	SSL configuration context

Definition at line 7248 of file ssl_tls.c.

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 relevent fields yourself.

Parameters:

conf	SSL configuration context

Definition at line 7069 of file ssl_tls.c.

Free referenced items in an SSL context and clear memory.

Parameters:

ssl	SSL context

Definition at line 6990 of file ssl_tls.c.

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.

Definition at line 5968 of file ssl_tls.c.

Return the number of data bytes available to read.

Parameters:

ssl	SSL context

Returns:

how many bytes are available in the read buffer

Definition at line 6100 of file ssl_tls.c.

Return the name of the current ciphersuite.

Parameters:

ssl	SSL context

Returns:

a string containing the ciphersuite name

Definition at line 6116 of file ssl_tls.c.

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

Parameters:

ciphersuite_name

SSL ciphersuite name

Returns:

the ID with the ciphersuite or 0 if not found

Definition at line 1781 of file ssl_ciphersuites.c.

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

Parameters:

ciphersuite_id

SSL ciphersuite ID

Returns:

a string containing the ciphersuite name

Definition at line 1769 of file ssl_ciphersuites.c.

Return the maximum fragment length (payload, in bytes).

This is the value negotiated with peer if any, or the locally configured value.

Note:

With DTLS, mbedtls_ssl_write() will return an error if called with a larger length value. With TLS, mbedtls_ssl_write() will fragment the input if necessary and return the number of bytes written; it is up to the caller to call mbedtls_ssl_write() again in order to send the remaining bytes if any.

Parameters:

ssl	SSL context

Returns:

Current maximum fragment length.

Definition at line 6197 of file ssl_tls.c.

Return the peer certificate from the current connection.

Note: Can be NULL in case no certificate was sent during the handshake. Different calls for the same connection can return the same or different pointers for the same certificate and even a different certificate altogether. The peer cert CAN change in a single connection if renegotiation is performed.

Parameters:

ssl	SSL context

Returns:

the current peer certificate

Definition at line 6220 of file ssl_tls.c.

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, or MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE if compression is enabled, which makes expansion much less predictable

Definition at line 6162 of file ssl_tls.c.

Save session in order to resume it later (client-side only) Session data is copied to presented session structure.

Warning:

Currently, peer certificate is lost in the operation.

Parameters:

ssl	SSL context
session	session context

Returns:

0 if successful, MBEDTLS_ERR_SSL_ALLOC_FAILED if memory allocation failed, MBEDTLS_ERR_SSL_BAD_INPUT_DATA if used server-side or arguments are otherwise invalid

See also:

mbedtls_ssl_set_session()

Definition at line 6230 of file ssl_tls.c.

Return the result of the certificate verification.

Parameters:

ssl	SSL context

Returns:

0 if successful, -1 if result is not available (eg because the handshake was aborted too early), or a combination of BADCERT_xxx and BADCRL_xxx flags, see x509.h

Definition at line 6105 of file ssl_tls.c.

Return the current SSL version (SSLv3/TLSv1/etc)

Parameters:

ssl	SSL context

Returns:

a string containing the SSL version

Definition at line 6124 of file ssl_tls.c.

Perform the SSL handshake.

Parameters:

ssl	SSL context

Returns:

0 if successful, or MBEDTLS_ERR_SSL_WANT_READ or MBEDTLS_ERR_SSL_WANT_WRITE, or MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED (see below), or a specific SSL error code.

Note:

If this function returns something other than 0 or MBEDTLS_ERR_SSL_WANT_READ/WRITE, then the ssl context becomes unusable, and you should either free it or call mbedtls_ssl_session_reset() on it before re-using it.

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.

Definition at line 6269 of file ssl_tls.c.

Perform a single step of the SSL handshake.

Note:

The state of the context (ssl->state) will be at the following state after execution of this function. Do not call this function if state is MBEDTLS_SSL_HANDSHAKE_OVER.

Parameters:

ssl	SSL context

Returns:

0 if successful, or MBEDTLS_ERR_SSL_WANT_READ or MBEDTLS_ERR_SSL_WANT_WRITE, or a specific SSL error code.

Definition at line 6247 of file ssl_tls.c.

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

Parameters:

ssl	SSL context

Definition at line 5326 of file ssl_tls.c.

Returns the list of ciphersuites supported by the SSL/TLS module.

Returns:

a statically allocated array of ciphersuites, the last entry is 0.

Definition at line 1702 of file ssl_ciphersuites.c.

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 number of bytes read, or 0 for EOF, or MBEDTLS_ERR_SSL_WANT_READ or MBEDTLS_ERR_SSL_WANT_WRITE, or MBEDTLS_ERR_SSL_CLIENT_RECONNECT (see below), or another negative error code.

Note:

When this function return 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 beeen reset internally). Either way, you should 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!

Definition at line 6446 of file ssl_tls.c.

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.

Definition at line 6367 of file ssl_tls.c.

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.

Definition at line 3969 of file ssl_tls.c.

Free referenced items in an SSL session including the peer certificate and clear memory.

Parameters:

session

SSL session

Definition at line 6967 of file ssl_tls.c.

Initialize SSL session structure.

Parameters:

session

SSL session

Definition at line 5220 of file ssl_tls.c.

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 POLASSL_ERR_SSL_MALLOC_FAILED, MBEDTLS_ERR_SSL_HW_ACCEL_FAILED or MBEDTLS_ERR_SSL_COMPRESSION_FAILED

Definition at line 5501 of file ssl_tls.c.

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. The last argument is the timeout in milliseconds, 0 means no timeout (block forever until a message comes)

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.

Definition at line 5572 of file ssl_tls.c.

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.

Definition at line 60 of file ssl_srv.c.

Set hostname for ServerName TLS extension (client-side only)

Parameters:

ssl	SSL context
hostname	the server hostname

Returns:

0 if successful or MBEDTLS_ERR_SSL_ALLOC_FAILED

Definition at line 5904 of file ssl_tls.c.

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

Definition at line 5729 of file ssl_tls.c.

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

Definition at line 5721 of file ssl_tls.c.

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.

Definition at line 5740 of file ssl_tls.c.

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

Definition at line 5713 of file ssl_tls.c.

Set the Pre Shared Key (PSK) for the current handshake.

Note:

This should only be called inside the PSK callback, ie the function passed to mbedtls_ssl_conf_psk_cb().

Parameters:

ssl	SSL context
psk	pointer to the pre-shared key
psk_len	pre-shared key length

Returns:

0 if successful or MBEDTLS_ERR_SSL_ALLOC_FAILED

Definition at line 5807 of file ssl_tls.c.

Request resumption of session (client-side only) Session data is copied from presented session structure.

Parameters:

ssl	SSL context
session	session context

Returns:

0 if successful, MBEDTLS_ERR_SSL_ALLOC_FAILED if memory allocation failed, MBEDTLS_ERR_SSL_BAD_INPUT_DATA if used server-side or arguments are otherwise invalid

See also:

mbedtls_ssl_get_session()

Definition at line 5615 of file ssl_tls.c.

Set the timer callbacks (Mandatory for DTLS.)

Parameters:

ssl	SSL context
p_timer	parameter (context) shared by timer callback
f_set_timer	set timer callback Accepts an intermediate and a final delay in milliseconcs If the final delay is 0, cancels the running timer.
f_get_timer	get timer callback. Must return: -1 if cancelled 0 if none of the delays is expired 1 if the intermediate delay only is expired 2 if the final delay is expired

Definition at line 5589 of file ssl_tls.c.

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:

Modifying the conf structure after is has been used in this function is unsupported!

Parameters:

ssl	SSL context
conf	SSL configuration to use

Returns:

0 if successful, or MBEDTLS_ERR_SSL_ALLOC_FAILED if memory allocation failed

Definition at line 5334 of file ssl_tls.c.

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 number of bytes actually written (may be less than len), or MBEDTLS_ERR_SSL_WANT_WRITE of MBEDTLS_ERR_SSL_WANT_READ, or another negative error code.

Note:

When this function returns MBEDTLS_ERR_SSL_WANT_WRITE/READ, it must be called later with the *same* arguments, until it returns a positive value.

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

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

Definition at line 6791 of file ssl_tls.c.