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.
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)
	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)
	Set own certificate and alternate non-PolarSSL 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)
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 (Client only) (Default: SSL_TRUNC_HMAC_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.
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_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_read_record (ssl_context *ssl)
int	ssl_fetch_input (ssl_context *ssl, size_t nb_want)

Detailed Description

SSL/TLS functions.

This file is part of PolarSSL (http://www.polarssl.org) Lead Maintainer: Paul Bakker <polarssl_maintainer at polarssl.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 4511 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 1914 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 4631 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 4006 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 4092 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 4102 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 1624 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 1612 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 4133 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 4142 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, or a combination of: BADCERT_EXPIRED BADCERT_REVOKED BADCERT_CN_MISMATCH BADCERT_NOT_TRUSTED

Definition at line 4097 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 4110 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 4178 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 4575 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 4158 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 3438 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 4064 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 1552 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	how many bytes must be read

Returns:: This function returns the number of bytes read, 0 for EOF, or a negative error code.

Definition at line 4308 of file ssl_tls.c.

int ssl_read_record ( ssl_context * ssl )

Subtract from error code as ssl->in_msg[1] is 7-bit positive error identifier.

Definition at line 2074 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 4261 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 2363 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 4611 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 3521 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 3982 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 3647 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 3678 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 3769 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)

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

Parameters:

ssl	SSL context
ciphersuites	0-terminated list of allowed ciphersuites

Definition at line 3718 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 3726 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 3941 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 3670 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 3898 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 3917 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 3637 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 3948 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:: O if successful or POLARSSL_ERR_SSL_BAD_INPUT_DATA

Definition at line 4033 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 4012 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.

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 4022 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 3777 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 alternate non-PolarSSL 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.

Warning:: This backwards-compatibility function is deprecated! Please use pk_init_ctx_rsa_alt() and ssl_set_own_cert() instead.

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

Warning:: This backwards-compatibility function is deprecated! Please use ssl_set_own_cert() instead.

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 3792 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 3851 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 3887 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 4059 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 3662 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 3698 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.

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 3688 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 4083 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:: O if successful, or a specific error code (server only).

Definition at line 4070 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 3971 of file ssl_tls.c.

int ssl_set_truncated_hmac	(	ssl_context *	ssl,
		int	truncate
	)

Activate negotiation of truncated HMAC (Client only) (Default: SSL_TRUNC_HMAC_ENABLED)

Parameters:

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

Returns:: O if successful, POLARSSL_ERR_SSL_BAD_INPUT_DATA if used server-side

Definition at line 4048 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 3653 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 4538 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.

Definition at line 4447 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