mbed TLS library

Dependents:   HTTPClient-SSL WS_SERVER

Embed: (wiki syntax)

« Back to documentation index

ssl.h File Reference

ssl.h File Reference

SSL/TLS functions. More...

Go to the source code of this file.

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

Copyright (C) 2006-2014, ARM Limited, All Rights Reserved

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:
sslSSL 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:
sslSSL 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:
sslSSL 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:
sslSSL 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:
sslSSL 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_nameSSL 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_idSSL 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:
sslSSL 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:
sslSSL context
sessionsession 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:
sslSSL 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:
sslSSL 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:
sslSSL 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:
handshakeSSL 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:
sslSSL 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:
sslSSL 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:
sslSSL context
allow_legacyPrevent 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:
sslSSL context
bufbuffer that will hold the data
lenmaximum 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:
sslSSL 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:
sslSSL context
levelThe alert level of the message (SSL_ALERT_LEVEL_WARNING or SSL_ALERT_LEVEL_FATAL)
messageThe 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:
sessionSSL session

Definition at line 4992 of file ssl_tls.c.

void ssl_session_init ( ssl_session *  session )

Initialize SSL session structure.

Parameters:
sessionSSL 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:
sslSSL 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:
sslSSL context
protosNULL-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:
sslSSL context
arc4SSL_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:
sslSSL context
authmodecan 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:
sslSSL context
f_recvread callback
p_recvread parameter
f_sendwrite callback
p_sendwrite 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:
sslSSL context
ca_chaintrusted CA chain (meaning all fully trusted top-level CAs)
ca_crltrusted CA CRLs
peer_cnexpected 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:
sslSSL context
splitSSL_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:
sslSSL context
ciphersuites0-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:
sslSSL context
ciphersuites0-terminated list of allowed ciphersuites
majorMajor version number (only SSL_MAJOR_VERSION_3 supported)
minorMinor 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:
sslSSL context
curvesOrdered 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:
sslSSL context
f_dbgdebug function
p_dbgdebug 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:
sslSSL context
dhm_PDiffie-Hellman-Merkle modulus
dhm_GDiffie-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:
sslSSL context
dhm_ctxDiffie-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:
sslSSL context
etmSSL_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:
sslSSL context
endpointmust 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:
sslSSL context
emsSSL_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:
sslSSL context
fallbackSSL_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:
sslSSL context
hostnamethe 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:
sslSSL context
mfl_codeCode 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:
sslSSL context
majorMajor version number (only SSL_MAJOR_VERSION_3 supported)
minorMinor 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:
sslSSL context
majorMajor version number (only SSL_MAJOR_VERSION_3 supported)
minorMinor 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:
sslSSL context
own_certown public certificate chain
pk_keyown 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:
sslSSL context
own_certown public certificate chain
rsa_keyalternate implementation private RSA key
rsa_decryptalternate implementation of rsa_pkcs1_decrypt()
rsa_signalternate implementation of rsa_pkcs1_sign()
rsa_key_lenfunction 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:
sslSSL context
own_certown public certificate chain
rsa_keyown 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:
sslSSL context
pskpointer to the pre-shared key
psk_lenpre-shared key length
psk_identitypointer to the pre-shared key identity
psk_identity_lenidentity 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:
sslSSL context
f_pskPSK identity function
p_pskPSK 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:
sslSSL context
renegotiationEnable 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:
sslSSL context
max_recordsUse 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:
sslSSL context
periodThe 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:
sslSSL context
f_rngRNG function
p_rngRNG 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:
sslSSL context
sessionsession 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:
sslSSL context
f_get_cachesession get callback
p_get_cachesession get parameter
f_set_cachesession set callback
p_set_cachesession 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:
sslSSL context
lifetimesession 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:
sslSSL context
use_ticketsEnable 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:
sslSSL context
f_sniverification function
p_sniverification 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:
sslSSL context
truncateEnable 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:
sslSSL context
f_vrfyverification function
p_vrfyverification 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:
transformSSL 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:
sslSSL context
bufbuffer holding the data
lenhow 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.