SSL/TLS functions. More...

Functions
const int *	ssl_list_ciphersuites (void)
	Returns the list of ciphersuites supported by the SSL/TLS module.
const char *	ssl_get_ciphersuite_name (const int ciphersuite_id)
	Return the name of the ciphersuite associated with the given ID.
int	ssl_get_ciphersuite_id (const char *ciphersuite_name)
	Return the ID of the ciphersuite associated with the given name.
int	ssl_init (ssl_context *ssl)
	Initialize an SSL context (An individual SSL context is not thread-safe)
int	ssl_session_reset (ssl_context *ssl)
	Reset an already initialized SSL context for re-use while retaining application-set variables, function pointers and data.
void	ssl_set_endpoint (ssl_context *ssl, int endpoint)
	Set the current endpoint type.
void	ssl_set_authmode (ssl_context *ssl, int authmode)
	Set the certificate verification mode.
void	ssl_set_verify (ssl_context ssl, int(f_vrfy)(void , x509_crt , int, int ), void p_vrfy)
	Set the verification callback (Optional).
void	ssl_set_rng (ssl_context ssl, int(f_rng)(void , unsigned char , size_t), void *p_rng)
	Set the random number generator callback.
void	ssl_set_dbg (ssl_context ssl, void(f_dbg)(void , int, const char ), void *p_dbg)
	Set the debug callback.
void	ssl_set_bio (ssl_context ssl, int(f_recv)(void , unsigned char , size_t), void p_recv, int(f_send)(void , const unsigned char , size_t), void *p_send)
	Set the underlying BIO read and write callbacks.
void	ssl_set_session_cache (ssl_context ssl, int(f_get_cache)(void , ssl_session ), void p_get_cache, int(f_set_cache)(void , const ssl_session ), void *p_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).
int	ssl_set_session (ssl_context ssl, const ssl_session session)
	Request resumption of session (client-side only) Session data is copied from presented session structure.
void	ssl_set_ciphersuites (ssl_context ssl, const int ciphersuites)
	Set the list of allowed ciphersuites and the preference order.
void	ssl_set_ciphersuites_for_version (ssl_context ssl, const int ciphersuites, int major, int minor)
	Set the list of allowed ciphersuites and the preference order for a specific version of the protocol.
void	ssl_set_ca_chain (ssl_context ssl, x509_crt ca_chain, x509_crl ca_crl, const char peer_cn)
	Set the data required to verify peer certificate.
int	ssl_set_own_cert (ssl_context ssl, x509_crt own_cert, pk_context *pk_key)
	Set own certificate chain and private key.
int	ssl_set_own_cert_rsa (ssl_context ssl, x509_crt own_cert, rsa_context *rsa_key) DEPRECATED
	Set own certificate chain and private RSA key.
int	ssl_set_own_cert_alt (ssl_context ssl, x509_crt own_cert, void *rsa_key, rsa_decrypt_func rsa_decrypt, rsa_sign_func rsa_sign, rsa_key_len_func rsa_key_len) DEPRECATED
	Set own certificate and external RSA private key and handling callbacks, such as the PKCS#11 wrappers or any other external private key handler.
int	ssl_set_psk (ssl_context ssl, const unsigned char psk, size_t psk_len, const unsigned char *psk_identity, size_t psk_identity_len)
	Set the Pre Shared Key (PSK) and the identity name connected to it.
void	ssl_set_psk_cb (ssl_context ssl, int(f_psk)(void , ssl_context , const unsigned char , size_t), void p_psk)
	Set the PSK callback (server-side only) (Optional).
int	ssl_set_dh_param (ssl_context ssl, const char dhm_P, const char *dhm_G)
	Set the Diffie-Hellman public P and G values, read as hexadecimal strings (server-side only) (Default: POLARSSL_DHM_RFC5114_MODP_1024_[PG])
int	ssl_set_dh_param_ctx (ssl_context ssl, dhm_context dhm_ctx)
	Set the Diffie-Hellman public P and G values, read from existing context (server-side only)
void	ssl_set_curves (ssl_context ssl, const ecp_group_id curves)
	Set the allowed curves in order of preference.
int	ssl_set_hostname (ssl_context ssl, const char hostname)
	Set hostname for ServerName TLS extension (client-side only)
void	ssl_set_sni (ssl_context ssl, int(f_sni)(void , ssl_context , const unsigned char , size_t), void p_sni)
	Set server side ServerName TLS extension callback (optional, server-side only).
int	ssl_set_alpn_protocols (ssl_context ssl, const char *protos)
	Set the supported Application Layer Protocols.
const char *	ssl_get_alpn_protocol (const ssl_context *ssl)
	Get the name of the negotiated Application Layer Protocol.
void	ssl_set_max_version (ssl_context *ssl, int major, int minor)
	Set the maximum supported version sent from the client side and/or accepted at the server side (Default: SSL_MAX_MAJOR_VERSION, SSL_MAX_MINOR_VERSION)
void	ssl_set_min_version (ssl_context *ssl, int major, int minor)
	Set the minimum accepted SSL/TLS protocol version (Default: SSL_MIN_MAJOR_VERSION, SSL_MIN_MINOR_VERSION)
void	ssl_set_fallback (ssl_context *ssl, char fallback)
	Set the fallback flag (client-side only).
void	ssl_set_encrypt_then_mac (ssl_context *ssl, char etm)
	Enable or disable Encrypt-then-MAC (Default: SSL_ETM_ENABLED)
void	ssl_set_extended_master_secret (ssl_context *ssl, char ems)
	Enable or disable Extended Master Secret negotiation.
void	ssl_set_arc4_support (ssl_context *ssl, char arc4)
	Disable or enable support for RC4 (Default: SSL_ARC4_ENABLED)
int	ssl_set_max_frag_len (ssl_context *ssl, unsigned char mfl_code)
	Set the maximum fragment length to emit and/or negotiate (Default: 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)
int	ssl_set_truncated_hmac (ssl_context *ssl, int truncate)
	Activate negotiation of truncated HMAC (Default: SSL_TRUNC_HMAC_DISABLED on client, SSL_TRUNC_HMAC_ENABLED on server.)
void	ssl_set_cbc_record_splitting (ssl_context *ssl, char split)
	Enable / Disable 1/n-1 record splitting (Default: SSL_CBC_RECORD_SPLITTING_ENABLED)
int	ssl_set_session_tickets (ssl_context *ssl, int use_tickets)
	Enable / Disable session tickets (Default: SSL_SESSION_TICKETS_ENABLED on client, SSL_SESSION_TICKETS_DISABLED on server)
void	ssl_set_session_ticket_lifetime (ssl_context *ssl, int lifetime)
	Set session ticket lifetime (server only) (Default: SSL_DEFAULT_TICKET_LIFETIME (86400 secs / 1 day))
void	ssl_set_renegotiation (ssl_context *ssl, int renegotiation)
	Enable / Disable renegotiation support for connection when initiated by peer (Default: SSL_RENEGOTIATION_DISABLED)
void	ssl_legacy_renegotiation (ssl_context *ssl, int allow_legacy)
	Prevent or allow legacy renegotiation.
void	ssl_set_renegotiation_enforced (ssl_context *ssl, int max_records)
	Enforce requested renegotiation.
void	ssl_set_renegotiation_period (ssl_context *ssl, const unsigned char period[8])
	Set record counter threshold for periodic renegotiation.
size_t	ssl_get_bytes_avail (const ssl_context *ssl)
	Return the number of data bytes available to read.
int	ssl_get_verify_result (const ssl_context *ssl)
	Return the result of the certificate verification.
const char *	ssl_get_ciphersuite (const ssl_context *ssl)
	Return the name of the current ciphersuite.
const char *	ssl_get_version (const ssl_context *ssl)
	Return the current SSL version (SSLv3/TLSv1/etc)
const x509_crt *	ssl_get_peer_cert (const ssl_context *ssl)
	Return the peer certificate from the current connection.
int	ssl_get_session (const ssl_context ssl, ssl_session session)
	Save session in order to resume it later (client-side only) Session data is copied to presented session structure.
int	ssl_handshake (ssl_context *ssl)
	Perform the SSL handshake.
int	ssl_handshake_step (ssl_context *ssl)
	Perform a single step of the SSL handshake.
int	ssl_renegotiate (ssl_context *ssl)
	Initiate an SSL renegotiation on the running connection.
int	ssl_read (ssl_context ssl, unsigned char buf, size_t len)
	Read at most 'len' application data bytes.
int	ssl_write (ssl_context ssl, const unsigned char buf, size_t len)
	Write exactly 'len' application data bytes.
int	ssl_send_alert_message (ssl_context *ssl, unsigned char level, unsigned char message)
	Send an alert message.
int	ssl_close_notify (ssl_context *ssl)
	Notify the peer that the connection is being closed.
void	ssl_free (ssl_context *ssl)
	Free referenced items in an SSL context and clear memory.
void	ssl_session_init (ssl_session *session)
	Initialize SSL session structure.
void	ssl_session_free (ssl_session *session)
	Free referenced items in an SSL session including the peer certificate and clear memory.
void	ssl_transform_free (ssl_transform *transform)
	Free referenced items in an SSL transform context and clear memory.
void	ssl_handshake_free (ssl_handshake_params *handshake)
	Free referenced items in an SSL handshake context and clear memory.
int	ssl_fetch_input (ssl_context *ssl, size_t nb_want)

Detailed Description

SSL/TLS functions.

This file is part of mbed TLS (https://tls.mbed.org)

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

Definition in file ssl.h.

Function Documentation

int ssl_close_notify ( ssl_context * ssl )

Notify the peer that the connection is being closed.

Parameters:

ssl	SSL context

Definition at line 4888 of file ssl_tls.c.

int ssl_fetch_input	(	ssl_context *	ssl,
		size_t	nb_want
	)

Returns:: 0 if successful, POLARSSL_ERR_SSL_CONN_EOF on EOF or another negative error code.

Definition at line 2009 of file ssl_tls.c.

void ssl_free ( ssl_context * ssl )

Free referenced items in an SSL context and clear memory.

Parameters:

ssl	SSL context

Definition at line 5015 of file ssl_tls.c.

const char* ssl_get_alpn_protocol ( const 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.

Definition at line 4194 of file ssl_tls.c.

size_t ssl_get_bytes_avail ( const ssl_context * ssl )

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 4328 of file ssl_tls.c.

const char* ssl_get_ciphersuite ( const ssl_context * ssl )

Return the name of the current ciphersuite.

Parameters:

ssl	SSL context

Returns:: a string containing the ciphersuite name

Definition at line 4344 of file ssl_tls.c.

int ssl_get_ciphersuite_id ( const char * ciphersuite_name )

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

Parameters:

ciphersuite_name SSL ciphersuite name

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

Definition at line 1772 of file ssl_ciphersuites.c.

const char* ssl_get_ciphersuite_name ( const int ciphersuite_id )

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

Parameters:

ciphersuite_id SSL ciphersuite ID

Returns:: a string containing the ciphersuite name

Definition at line 1760 of file ssl_ciphersuites.c.

const x509_crt* ssl_get_peer_cert ( const ssl_context * ssl )

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 4375 of file ssl_tls.c.

int ssl_get_session	(	const ssl_context *	ssl,
		ssl_session *	session
	)

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, POLARSSL_ERR_SSL_MALLOC_FAILED if memory allocation failed, POLARSSL_ERR_SSL_BAD_INPUT_DATA if used server-side or arguments are otherwise invalid

See also:: ssl_set_session()

Definition at line 4385 of file ssl_tls.c.

int ssl_get_verify_result ( const ssl_context * ssl )

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 4333 of file ssl_tls.c.

const char* ssl_get_version ( const ssl_context * ssl )

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

Parameters:

ssl	SSL context

Returns:: a string containing the SSL version

Definition at line 4352 of file ssl_tls.c.

int ssl_handshake ( ssl_context * ssl )

Perform the SSL handshake.

Parameters:

ssl	SSL context

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

Definition at line 4421 of file ssl_tls.c.

void ssl_handshake_free ( ssl_handshake_params * handshake )

Free referenced items in an SSL handshake context and clear memory.

Parameters:

handshake SSL handshake context

Definition at line 4953 of file ssl_tls.c.

int ssl_handshake_step ( ssl_context * ssl )

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

Parameters:

ssl	SSL context

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

Definition at line 4402 of file ssl_tls.c.

int ssl_init ( ssl_context * ssl )

Initialize an SSL context (An individual SSL context is not thread-safe)

Parameters:

ssl	SSL context

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

Definition at line 3596 of file ssl_tls.c.

void ssl_legacy_renegotiation	(	ssl_context *	ssl,
		int	allow_legacy
	)

Prevent or allow legacy renegotiation.

(Default: SSL_LEGACY_NO_RENEGOTIATION)

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)

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)

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:

ssl	SSL context
allow_legacy	Prevent or allow (SSL_NO_LEGACY_RENEGOTIATION, SSL_ALLOW_LEGACY_RENEGOTIATION or SSL_LEGACY_BREAK_HANDSHAKE)

Definition at line 4277 of file ssl_tls.c.

const int * ssl_list_ciphersuites ( void )

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 1693 of file ssl_ciphersuites.c.

int ssl_read	(	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:: This function returns the number of bytes read, 0 for EOF, or a negative error code.

Definition at line 4580 of file ssl_tls.c.

int ssl_renegotiate ( 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 ssl_read() if honored by client.

Parameters:

ssl	SSL context

Returns:: 0 if successful, or any ssl_handshake() return value.

Definition at line 4503 of file ssl_tls.c.

int ssl_send_alert_message	(	ssl_context *	ssl,
		unsigned char	level,
		unsigned char	message
	)

Send an alert message.

Parameters:

ssl	SSL context
level	The alert level of the message (SSL_ALERT_LEVEL_WARNING or SSL_ALERT_LEVEL_FATAL)
message	The alert message (SSL_ALERT_MSG_*)

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

Definition at line 2451 of file ssl_tls.c.

void ssl_session_free ( ssl_session * session )

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

Parameters:

session SSL session

Definition at line 4992 of file ssl_tls.c.

void ssl_session_init ( ssl_session * session )

Initialize SSL session structure.

Parameters:

session SSL session

Definition at line 3529 of file ssl_tls.c.

int ssl_session_reset ( 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 POLASSL_ERR_SSL_MALLOC_FAILED, POLARSSL_ERR_SSL_HW_ACCEL_FAILED or POLARSSL_ERR_SSL_COMPRESSION_FAILED

Definition at line 3679 of file ssl_tls.c.

int ssl_set_alpn_protocols	(	ssl_context *	ssl,
		const char **	protos
	)

Set the supported Application Layer Protocols.

Parameters:

ssl	SSL context
protos	NULL-terminated list of supported protocols, in decreasing preference order.

Returns:: 0 on success, or POLARSSL_ERR_SSL_BAD_INPUT_DATA.

Definition at line 4170 of file ssl_tls.c.

void ssl_set_arc4_support	(	ssl_context *	ssl,
		char	arc4
	)

Disable or enable support for RC4 (Default: SSL_ARC4_ENABLED)

Note:: Though the default is RC4 for compatibility reasons in the 1.3 branch, the recommended value is SSL_ARC4_DISABLED.; This function will likely be removed in future versions as RC4 will then be disabled by default at compile time.

Parameters:

ssl	SSL context
arc4	SSL_ARC4_ENABLED or SSL_ARC4_DISABLED

Definition at line 4241 of file ssl_tls.c.

void ssl_set_authmode	(	ssl_context *	ssl,
		int	authmode
	)

Set the certificate verification mode.

Parameters:

ssl	SSL context
authmode	can be:

SSL_VERIFY_NONE: peer certificate is not checked (default), this is insecure and SHOULD be avoided.

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

SSL_VERIFY_REQUIRED: peer *must* present a valid certificate, handshake is aborted if verification failed.

Note:: On client, SSL_VERIFY_REQUIRED is the recommended mode. With SSL_VERIFY_OPTIONAL, the user needs to call 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 3833 of file ssl_tls.c.

void ssl_set_bio	(	ssl_context *	ssl,
		int()(void , unsigned char *, size_t)	f_recv,
		void *	p_recv,
		int()(void , const unsigned char *, size_t)	f_send,
		void *	p_send
	)

Set the underlying BIO read and write callbacks.

Parameters:

ssl	SSL context
f_recv	read callback
p_recv	read parameter
f_send	write callback
p_send	write parameter

Definition at line 3864 of file ssl_tls.c.

void ssl_set_ca_chain	(	ssl_context *	ssl,
		x509_crt *	ca_chain,
		x509_crl *	ca_crl,
		const char *	peer_cn
	)

Set the data required to verify peer certificate.

Parameters:

ssl	SSL context
ca_chain	trusted CA chain (meaning all fully trusted top-level CAs)
ca_crl	trusted CA CRLs
peer_cn	expected peer CommonName (or NULL)

Definition at line 3959 of file ssl_tls.c.

void ssl_set_cbc_record_splitting	(	ssl_context *	ssl,
		char	split
	)

Enable / Disable 1/n-1 record splitting (Default: 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:

ssl	SSL context
split	SSL_CBC_RECORD_SPLITTING_ENABLED or SSL_CBC_RECORD_SPLITTING_DISABLED

Definition at line 4271 of file ssl_tls.c.

void ssl_set_ciphersuites	(	ssl_context *	ssl,
		const int *	ciphersuites
	)

Set the list of allowed ciphersuites and the preference order.

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

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

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

Parameters:

ssl	SSL context
ciphersuites	0-terminated list of allowed ciphersuites

Definition at line 3908 of file ssl_tls.c.

void ssl_set_ciphersuites_for_version	(	ssl_context *	ssl,
		const int *	ciphersuites,
		int	major,
		int	minor
	)

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

(Only useful on the server side)

Parameters:

ssl	SSL context
ciphersuites	0-terminated list of allowed ciphersuites
major	Major version number (only SSL_MAJOR_VERSION_3 supported)
minor	Minor version number (SSL_MINOR_VERSION_0, SSL_MINOR_VERSION_1 and SSL_MINOR_VERSION_2, SSL_MINOR_VERSION_3 supported)

Definition at line 3916 of file ssl_tls.c.

void ssl_set_curves	(	ssl_context *	ssl,
		const ecp_group_id *	curves
	)

Set the allowed curves in order of preference.

(Default: all defined curves.)

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

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

Both sides: limits the set of curves used by peer to the listed curves for any use (ECDH(E), certificates).

Parameters:

ssl	SSL context
curves	Ordered list of allowed curves, terminated by POLARSSL_ECP_DP_NONE.

Definition at line 4129 of file ssl_tls.c.

void ssl_set_dbg	(	ssl_context *	ssl,
		void()(void , int, const char *)	f_dbg,
		void *	p_dbg
	)

Set the debug callback.

Parameters:

ssl	SSL context
f_dbg	debug function
p_dbg	debug parameter

Definition at line 3856 of file ssl_tls.c.

int ssl_set_dh_param	(	ssl_context *	ssl,
		const char *	dhm_P,
		const char *	dhm_G
	)

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

Parameters:

ssl	SSL context
dhm_P	Diffie-Hellman-Merkle modulus
dhm_G	Diffie-Hellman-Merkle generator

Returns:: 0 if successful

Definition at line 4086 of file ssl_tls.c.

int ssl_set_dh_param_ctx	(	ssl_context *	ssl,
		dhm_context *	dhm_ctx
	)

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

Parameters:

ssl	SSL context
dhm_ctx	Diffie-Hellman-Merkle context

Returns:: 0 if successful

Definition at line 4105 of file ssl_tls.c.

void ssl_set_encrypt_then_mac	(	ssl_context *	ssl,
		char	etm
	)

Enable or disable Encrypt-then-MAC (Default: 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:

ssl	SSL context
etm	SSL_ETM_ENABLED or SSL_ETM_DISABLED

Definition at line 4228 of file ssl_tls.c.

void ssl_set_endpoint	(	ssl_context *	ssl,
		int	endpoint
	)

Set the current endpoint type.

Parameters:

ssl	SSL context
endpoint	must be SSL_IS_CLIENT or SSL_IS_SERVER

Note:: This function should be called right after ssl_init() since some other ssl_set_foo() functions depend on it.

Definition at line 3817 of file ssl_tls.c.

void ssl_set_extended_master_secret	(	ssl_context *	ssl,
		char	ems
	)

Enable or disable Extended Master Secret negotiation.

(Default: 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:

ssl	SSL context
ems	SSL_EXTENDED_MS_ENABLED or SSL_EXTENDED_MS_DISABLED

Definition at line 4235 of file ssl_tls.c.

void ssl_set_fallback	(	ssl_context *	ssl,
		char	fallback
	)

Set the fallback flag (client-side only).

(Default: SSL_IS_NOT_FALLBACK).

Note:: Set to 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 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:

ssl	SSL context
fallback	SSL_IS_NOT_FALLBACK or SSL_IS_FALLBACK

Definition at line 4221 of file ssl_tls.c.

int ssl_set_hostname	(	ssl_context *	ssl,
		const char *	hostname
	)

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

Parameters:

ssl	SSL context
hostname	the server hostname

Returns:: 0 if successful or POLARSSL_ERR_SSL_MALLOC_FAILED

Definition at line 4136 of file ssl_tls.c.

int ssl_set_max_frag_len	(	ssl_context *	ssl,
		unsigned char	mfl_code
	)

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

ssl	SSL context
mfl_code	Code for maximum fragment length (allowed values: SSL_MAX_FRAG_LEN_512, SSL_MAX_FRAG_LEN_1024, SSL_MAX_FRAG_LEN_2048, SSL_MAX_FRAG_LEN_4096)

Returns:: 0 if successful or POLARSSL_ERR_SSL_BAD_INPUT_DATA

Definition at line 4247 of file ssl_tls.c.

void ssl_set_max_version	(	ssl_context *	ssl,
		int	major,
		int	minor
	)

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

Note: This ignores ciphersuites from 'higher' versions. Note: Input outside of the SSL_MAX_XXXXX_VERSION and SSL_MIN_XXXXX_VERSION range is ignored.

Parameters:

ssl	SSL context
major	Major version number (only SSL_MAJOR_VERSION_3 supported)
minor	Minor version number (SSL_MINOR_VERSION_0, SSL_MINOR_VERSION_1 and SSL_MINOR_VERSION_2, SSL_MINOR_VERSION_3 supported)

Definition at line 4200 of file ssl_tls.c.

void ssl_set_min_version	(	ssl_context *	ssl,
		int	major,
		int	minor
	)

Set the minimum accepted SSL/TLS protocol version (Default: SSL_MIN_MAJOR_VERSION, SSL_MIN_MINOR_VERSION)

Note:: Input outside of the SSL_MAX_XXXXX_VERSION and SSL_MIN_XXXXX_VERSION range is ignored.; SSL_MINOR_VERSION_0 (SSL v3) should be avoided.

Parameters:

ssl	SSL context
major	Major version number (only SSL_MAJOR_VERSION_3 supported)
minor	Minor version number (SSL_MINOR_VERSION_0, SSL_MINOR_VERSION_1 and SSL_MINOR_VERSION_2, SSL_MINOR_VERSION_3 supported)

Definition at line 4210 of file ssl_tls.c.

int ssl_set_own_cert	(	ssl_context *	ssl,
		x509_crt *	own_cert,
		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.; This function may be called more than once if you want to support multiple certificates (eg, one using RSA and one using ECDSA). However, on client, currently only the first certificate is used (subsequent calls have no effect).

Parameters:

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

Returns:: 0 on success or POLARSSL_ERR_SSL_MALLOC_FAILED

Definition at line 3967 of file ssl_tls.c.

int ssl_set_own_cert_alt	(	ssl_context *	ssl,
		x509_crt *	own_cert,
		void *	rsa_key,
		rsa_decrypt_func	rsa_decrypt,
		rsa_sign_func	rsa_sign,
		rsa_key_len_func	rsa_key_len
	)

Set own certificate and external RSA private key and handling callbacks, such as the PKCS#11 wrappers or any other external private key handler.

(see the respective RSA functions in rsa.h for documentation of the callback parameters, with the only change being that the rsa_context * is a void * in the callbacks)

Note: own_cert should contain IN order from the bottom up your certificate chain. The top certificate (self-signed) can be omitted.

Parameters:

ssl	SSL context
own_cert	own public certificate chain
rsa_key	alternate implementation private RSA key
rsa_decrypt	alternate implementation of `rsa_pkcs1_decrypt()`
rsa_sign	alternate implementation of `rsa_pkcs1_sign()`
rsa_key_len	function returning length of RSA key in bytes

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

Definition at line 4012 of file ssl_tls.c.

int ssl_set_own_cert_rsa	(	ssl_context *	ssl,
		x509_crt *	own_cert,
		rsa_context *	rsa_key
	)

Set own certificate chain and private RSA key.

Note: own_cert should contain IN order from the bottom up your certificate chain. The top certificate (self-signed) can be omitted.

Parameters:

ssl	SSL context
own_cert	own public certificate chain
rsa_key	own private RSA key

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

Definition at line 3983 of file ssl_tls.c.

int ssl_set_psk	(	ssl_context *	ssl,
		const unsigned char *	psk,
		size_t	psk_len,
		const unsigned char *	psk_identity,
		size_t	psk_identity_len
	)

Set the Pre Shared Key (PSK) and the identity name connected to it.

Parameters:

ssl	SSL context
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 POLARSSL_ERR_SSL_MALLOC_FAILED

Definition at line 4043 of file ssl_tls.c.

void ssl_set_psk_cb	(	ssl_context *	ssl,
		int()(void , ssl_context , const unsigned char , size_t)	f_psk,
		void *	p_psk
	)

Set the PSK callback (server-side only) (Optional).

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

Parameters:

ssl	SSL context
f_psk	PSK identity function
p_psk	PSK identity parameter

Definition at line 4075 of file ssl_tls.c.

void ssl_set_renegotiation	(	ssl_context *	ssl,
		int	renegotiation
	)

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

Note: A server with support enabled is more vulnerable for a resource DoS by a malicious client. You should enable this on a client to enable server-initiated renegotiation.

Parameters:

ssl	SSL context
renegotiation	Enable or disable (SSL_RENEGOTIATION_ENABLED or SSL_RENEGOTIATION_DISABLED)

Definition at line 4283 of file ssl_tls.c.

void ssl_set_renegotiation_enforced	(	ssl_context *	ssl,
		int	max_records
	)

Enforce requested renegotiation.

(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 ssl_read(), as opposed to ssl_write() and 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 ssl_read().

Parameters:

ssl	SSL context
max_records	Use 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 4288 of file ssl_tls.c.

void ssl_set_renegotiation_period	(	ssl_context *	ssl,
		const unsigned char	period[8]
	)

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:

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

Definition at line 4293 of file ssl_tls.c.

void ssl_set_rng	(	ssl_context *	ssl,
		int()(void , unsigned char *, size_t)	f_rng,
		void *	p_rng
	)

Set the random number generator callback.

Parameters:

ssl	SSL context
f_rng	RNG function
p_rng	RNG parameter

Definition at line 3848 of file ssl_tls.c.

int ssl_set_session	(	ssl_context *	ssl,
		const ssl_session *	session
	)

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

Parameters:

ssl	SSL context
session	session context

Returns:: 0 if successful, POLARSSL_ERR_SSL_MALLOC_FAILED if memory allocation failed, POLARSSL_ERR_SSL_BAD_INPUT_DATA if used server-side or arguments are otherwise invalid

See also:: ssl_get_session()

Definition at line 3887 of file ssl_tls.c.

void ssl_set_session_cache	(	ssl_context *	ssl,
		int()(void , ssl_session *)	f_get_cache,
		void *	p_get_cache,
		int()(void , const ssl_session *)	f_set_cache,
		void *	p_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, 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 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 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:

ssl	SSL context
f_get_cache	session get callback
p_get_cache	session get parameter
f_set_cache	session set callback
p_set_cache	session set parameter

Definition at line 3875 of file ssl_tls.c.

void ssl_set_session_ticket_lifetime	(	ssl_context *	ssl,
		int	lifetime
	)

Set session ticket lifetime (server only) (Default: SSL_DEFAULT_TICKET_LIFETIME (86400 secs / 1 day))

Parameters:

ssl	SSL context
lifetime	session ticket lifetime

Definition at line 4319 of file ssl_tls.c.

int ssl_set_session_tickets	(	ssl_context *	ssl,
		int	use_tickets
	)

Enable / Disable session tickets (Default: SSL_SESSION_TICKETS_ENABLED on client, SSL_SESSION_TICKETS_DISABLED on server)

Note:: On server, ssl_set_rng() must be called before this function to allow generating the ticket encryption and authentication keys.

Parameters:

ssl	SSL context
use_tickets	Enable or disable (SSL_SESSION_TICKETS_ENABLED or SSL_SESSION_TICKETS_DISABLED)

Returns:: 0 if successful, or a specific error code (server only).

Definition at line 4301 of file ssl_tls.c.

void ssl_set_sni	(	ssl_context *	ssl,
		int()(void , 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, ssl_context *ssl, const unsigned char *hostname, size_t len). If a suitable certificate is found, the callback should set the certificate and key to use with ssl_set_own_cert() (and possibly adjust the CA chain as well) and return 0. The callback should return -1 to abort the handshake at this point.

Parameters:

ssl	SSL context
f_sni	verification function
p_sni	verification parameter

Definition at line 4159 of file ssl_tls.c.

int ssl_set_truncated_hmac	(	ssl_context *	ssl,
		int	truncate
	)

Activate negotiation of truncated HMAC (Default: SSL_TRUNC_HMAC_DISABLED on client, SSL_TRUNC_HMAC_ENABLED on server.)

Parameters:

ssl	SSL context
truncate	Enable or disable (SSL_TRUNC_HMAC_ENABLED or SSL_TRUNC_HMAC_DISABLED)

Returns:: Always 0.

Definition at line 4262 of file ssl_tls.c.

void ssl_set_verify	(	ssl_context *	ssl,
		int()(void , x509_crt , int, int )	f_vrfy,
		void *	p_vrfy
	)

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:

ssl	SSL context
f_vrfy	verification function
p_vrfy	verification parameter

Definition at line 3839 of file ssl_tls.c.

void ssl_transform_free ( ssl_transform * transform )

Free referenced items in an SSL transform context and clear memory.

Parameters:

transform SSL transform context

Definition at line 4913 of file ssl_tls.c.

int ssl_write	(	ssl_context *	ssl,
		const unsigned char *	buf,
		size_t	len
	)

Write exactly 'len' application data bytes.

Parameters:

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

Returns:: This function returns the number of bytes written, or a negative error code.

Note:: When this function returns POLARSSL_ERR_NET_WANT_WRITE, it must be called later with the *same* arguments, until it returns a positive value.; This function may write less than the number of bytes requested if len is greater than the maximum record length. For arbitrary-sized messages, it should be called in a loop.

Definition at line 4851 of file ssl_tls.c.

ssl.h File Reference

Functions

Detailed Description

Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

ssl.h File Reference

Functions

Detailed Description

Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Access Warning