API Documentation (Doxygen generated)

These pages are generated with doxygen directly from the source code!

ssl.h File Reference

SSL/TLS functions. More...

#include "config.h"
#include "net.h"
#include "bignum.h"
#include "ssl_ciphersuites.h"
#include "md5.h"
#include "sha1.h"
#include "sha256.h"
#include "sha512.h"
#include "aes.h"
#include "x509_crt.h"
#include "x509_crl.h"
#include "dhm.h"
#include "ecdh.h"
#include <time.h>
Include dependency graph for ssl.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  _ssl_session
struct  _ssl_transform
struct  _ssl_handshake_params
struct  _ssl_ticket_keys
struct  _ssl_key_cert
struct  _ssl_context

Macros

#define POLARSSL_KEY_EXCHANGE__SOME__PSK_ENABLED
#define POLARSSL_KEY_EXCHANGE__SOME__ECDHE_ENABLED
#define POLARSSL_ERR_SSL_FEATURE_UNAVAILABLE   -0x7080
 The requested feature is not available.
#define POLARSSL_ERR_SSL_BAD_INPUT_DATA   -0x7100
 Bad input parameters to function.
#define POLARSSL_ERR_SSL_INVALID_MAC   -0x7180
 Verification of the message MAC failed.
#define POLARSSL_ERR_SSL_INVALID_RECORD   -0x7200
 An invalid SSL record was received.
#define POLARSSL_ERR_SSL_CONN_EOF   -0x7280
 The connection indicated an EOF.
#define POLARSSL_ERR_SSL_UNKNOWN_CIPHER   -0x7300
 An unknown cipher was received.
#define POLARSSL_ERR_SSL_NO_CIPHER_CHOSEN   -0x7380
 The server has no ciphersuites in common with the client.
#define POLARSSL_ERR_SSL_NO_RNG   -0x7400
 No RNG was provided to the SSL module.
#define POLARSSL_ERR_SSL_NO_CLIENT_CERTIFICATE   -0x7480
 No client certification received from the client, but required by the authentication mode.
#define POLARSSL_ERR_SSL_CERTIFICATE_TOO_LARGE   -0x7500
 Our own certificate(s) is/are too large to send in an SSL message.
#define POLARSSL_ERR_SSL_CERTIFICATE_REQUIRED   -0x7580
 The own certificate is not set, but needed by the server.
#define POLARSSL_ERR_SSL_PRIVATE_KEY_REQUIRED   -0x7600
 The own private key or pre-shared key is not set, but needed.
#define POLARSSL_ERR_SSL_CA_CHAIN_REQUIRED   -0x7680
 No CA Chain is set, but required to operate.
#define POLARSSL_ERR_SSL_UNEXPECTED_MESSAGE   -0x7700
 An unexpected message was received from our peer.
#define POLARSSL_ERR_SSL_FATAL_ALERT_MESSAGE   -0x7780
 A fatal alert message was received from our peer.
#define POLARSSL_ERR_SSL_PEER_VERIFY_FAILED   -0x7800
 Verification of our peer failed.
#define POLARSSL_ERR_SSL_PEER_CLOSE_NOTIFY   -0x7880
 The peer notified us that the connection is going to be closed.
#define POLARSSL_ERR_SSL_BAD_HS_CLIENT_HELLO   -0x7900
 Processing of the ClientHello handshake message failed.
#define POLARSSL_ERR_SSL_BAD_HS_SERVER_HELLO   -0x7980
 Processing of the ServerHello handshake message failed.
#define POLARSSL_ERR_SSL_BAD_HS_CERTIFICATE   -0x7A00
 Processing of the Certificate handshake message failed.
#define POLARSSL_ERR_SSL_BAD_HS_CERTIFICATE_REQUEST   -0x7A80
 Processing of the CertificateRequest handshake message failed.
#define POLARSSL_ERR_SSL_BAD_HS_SERVER_KEY_EXCHANGE   -0x7B00
 Processing of the ServerKeyExchange handshake message failed.
#define POLARSSL_ERR_SSL_BAD_HS_SERVER_HELLO_DONE   -0x7B80
 Processing of the ServerHelloDone handshake message failed.
#define POLARSSL_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE   -0x7C00
 Processing of the ClientKeyExchange handshake message failed.
#define POLARSSL_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE_RP   -0x7C80
 Processing of the ClientKeyExchange handshake message failed in DHM / ECDH Read Public.
#define POLARSSL_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE_CS   -0x7D00
 Processing of the ClientKeyExchange handshake message failed in DHM / ECDH Calculate Secret.
#define POLARSSL_ERR_SSL_BAD_HS_CERTIFICATE_VERIFY   -0x7D80
 Processing of the CertificateVerify handshake message failed.
#define POLARSSL_ERR_SSL_BAD_HS_CHANGE_CIPHER_SPEC   -0x7E00
 Processing of the ChangeCipherSpec handshake message failed.
#define POLARSSL_ERR_SSL_BAD_HS_FINISHED   -0x7E80
 Processing of the Finished handshake message failed.
#define POLARSSL_ERR_SSL_MALLOC_FAILED   -0x7F00
 Memory allocation failed.
#define POLARSSL_ERR_SSL_HW_ACCEL_FAILED   -0x7F80
 Hardware acceleration function returned with error.
#define POLARSSL_ERR_SSL_HW_ACCEL_FALLTHROUGH   -0x6F80
 Hardware acceleration function skipped / left alone data.
#define POLARSSL_ERR_SSL_COMPRESSION_FAILED   -0x6F00
 Processing of the compression / decompression failed.
#define POLARSSL_ERR_SSL_BAD_HS_PROTOCOL_VERSION   -0x6E80
 Handshake protocol not within min/max boundaries.
#define POLARSSL_ERR_SSL_BAD_HS_NEW_SESSION_TICKET   -0x6E00
 Processing of the NewSessionTicket handshake message failed.
#define POLARSSL_ERR_SSL_SESSION_TICKET_EXPIRED   -0x6D80
 Session ticket has expired.
#define POLARSSL_ERR_SSL_PK_TYPE_MISMATCH   -0x6D00
 Public key type mismatch (eg, asked for RSA key exchange and presented EC key)
#define POLARSSL_ERR_SSL_UNKNOWN_IDENTITY   -0x6C80
 Unknown identity received (eg, PSK identity)
#define POLARSSL_ERR_SSL_INTERNAL_ERROR   -0x6C00
 Internal error (eg, unexpected failure in lower-level module)
#define POLARSSL_ERR_SSL_COUNTER_WRAPPING   -0x6B80
 A counter would wrap (eg, too many messages exchanged).
#define SSL_MAJOR_VERSION_3   3
#define SSL_MINOR_VERSION_0   0
#define SSL_MINOR_VERSION_1   1
#define SSL_MINOR_VERSION_2   2
#define SSL_MINOR_VERSION_3   3
#define SSL_MIN_MAJOR_VERSION   SSL_MAJOR_VERSION_3
#define SSL_MIN_MINOR_VERSION   SSL_MINOR_VERSION_0
#define SSL_MAX_MAJOR_VERSION   SSL_MAJOR_VERSION_3
#define SSL_MAX_MINOR_VERSION   SSL_MINOR_VERSION_3
#define SSL_MAX_FRAG_LEN_NONE   0
#define SSL_MAX_FRAG_LEN_512   1
#define SSL_MAX_FRAG_LEN_1024   2
#define SSL_MAX_FRAG_LEN_2048   3
#define SSL_MAX_FRAG_LEN_4096   4
#define SSL_MAX_FRAG_LEN_INVALID   5
#define SSL_IS_CLIENT   0
#define SSL_IS_SERVER   1
#define SSL_COMPRESS_NULL   0
#define SSL_COMPRESS_DEFLATE   1
#define SSL_VERIFY_NONE   0
#define SSL_VERIFY_OPTIONAL   1
#define SSL_VERIFY_REQUIRED   2
#define SSL_INITIAL_HANDSHAKE   0
#define SSL_RENEGOTIATION   1 /* In progress */
#define SSL_RENEGOTIATION_DONE   2 /* Done */
#define SSL_RENEGOTIATION_PENDING   3 /* Requested (server only) */
#define SSL_LEGACY_RENEGOTIATION   0
#define SSL_SECURE_RENEGOTIATION   1
#define SSL_RENEGOTIATION_DISABLED   0
#define SSL_RENEGOTIATION_ENABLED   1
#define SSL_LEGACY_NO_RENEGOTIATION   0
#define SSL_LEGACY_ALLOW_RENEGOTIATION   1
#define SSL_LEGACY_BREAK_HANDSHAKE   2
#define SSL_TRUNC_HMAC_DISABLED   0
#define SSL_TRUNC_HMAC_ENABLED   1
#define SSL_TRUNCATED_HMAC_LEN   10 /* 80 bits, rfc 6066 section 7 */
#define SSL_SESSION_TICKETS_DISABLED   0
#define SSL_SESSION_TICKETS_ENABLED   1
#define SSL_DEFAULT_TICKET_LIFETIME   86400
 Lifetime of session tickets (if enabled)
#define SSL_MAX_CONTENT_LEN   16384
 Size of the input / output buffer.
#define SSL_COMPRESSION_ADD   0
#define SSL_BUFFER_LEN   (SSL_MAX_CONTENT_LEN + SSL_COMPRESSION_ADD + 301)
#define SSL_EMPTY_RENEGOTIATION_INFO   0xFF
 renegotiation info ext
#define SSL_HASH_NONE   0
#define SSL_HASH_MD5   1
#define SSL_HASH_SHA1   2
#define SSL_HASH_SHA224   3
#define SSL_HASH_SHA256   4
#define SSL_HASH_SHA384   5
#define SSL_HASH_SHA512   6
#define SSL_SIG_ANON   0
#define SSL_SIG_RSA   1
#define SSL_SIG_ECDSA   3
#define SSL_CERT_TYPE_RSA_SIGN   1
#define SSL_CERT_TYPE_ECDSA_SIGN   64
#define SSL_MSG_CHANGE_CIPHER_SPEC   20
#define SSL_MSG_ALERT   21
#define SSL_MSG_HANDSHAKE   22
#define SSL_MSG_APPLICATION_DATA   23
#define SSL_ALERT_LEVEL_WARNING   1
#define SSL_ALERT_LEVEL_FATAL   2
#define SSL_ALERT_MSG_CLOSE_NOTIFY   0 /* 0x00 */
#define SSL_ALERT_MSG_UNEXPECTED_MESSAGE   10 /* 0x0A */
#define SSL_ALERT_MSG_BAD_RECORD_MAC   20 /* 0x14 */
#define SSL_ALERT_MSG_DECRYPTION_FAILED   21 /* 0x15 */
#define SSL_ALERT_MSG_RECORD_OVERFLOW   22 /* 0x16 */
#define SSL_ALERT_MSG_DECOMPRESSION_FAILURE   30 /* 0x1E */
#define SSL_ALERT_MSG_HANDSHAKE_FAILURE   40 /* 0x28 */
#define SSL_ALERT_MSG_NO_CERT   41 /* 0x29 */
#define SSL_ALERT_MSG_BAD_CERT   42 /* 0x2A */
#define SSL_ALERT_MSG_UNSUPPORTED_CERT   43 /* 0x2B */
#define SSL_ALERT_MSG_CERT_REVOKED   44 /* 0x2C */
#define SSL_ALERT_MSG_CERT_EXPIRED   45 /* 0x2D */
#define SSL_ALERT_MSG_CERT_UNKNOWN   46 /* 0x2E */
#define SSL_ALERT_MSG_ILLEGAL_PARAMETER   47 /* 0x2F */
#define SSL_ALERT_MSG_UNKNOWN_CA   48 /* 0x30 */
#define SSL_ALERT_MSG_ACCESS_DENIED   49 /* 0x31 */
#define SSL_ALERT_MSG_DECODE_ERROR   50 /* 0x32 */
#define SSL_ALERT_MSG_DECRYPT_ERROR   51 /* 0x33 */
#define SSL_ALERT_MSG_EXPORT_RESTRICTION   60 /* 0x3C */
#define SSL_ALERT_MSG_PROTOCOL_VERSION   70 /* 0x46 */
#define SSL_ALERT_MSG_INSUFFICIENT_SECURITY   71 /* 0x47 */
#define SSL_ALERT_MSG_INTERNAL_ERROR   80 /* 0x50 */
#define SSL_ALERT_MSG_USER_CANCELED   90 /* 0x5A */
#define SSL_ALERT_MSG_NO_RENEGOTIATION   100 /* 0x64 */
#define SSL_ALERT_MSG_UNSUPPORTED_EXT   110 /* 0x6E */
#define SSL_ALERT_MSG_UNRECOGNIZED_NAME   112 /* 0x70 */
#define SSL_ALERT_MSG_UNKNOWN_PSK_IDENTITY   115 /* 0x73 */
#define SSL_ALERT_MSG_NO_APPLICATION_PROTOCOL   120 /* 0x78 */
#define SSL_HS_HELLO_REQUEST   0
#define SSL_HS_CLIENT_HELLO   1
#define SSL_HS_SERVER_HELLO   2
#define SSL_HS_NEW_SESSION_TICKET   4
#define SSL_HS_CERTIFICATE   11
#define SSL_HS_SERVER_KEY_EXCHANGE   12
#define SSL_HS_CERTIFICATE_REQUEST   13
#define SSL_HS_SERVER_HELLO_DONE   14
#define SSL_HS_CERTIFICATE_VERIFY   15
#define SSL_HS_CLIENT_KEY_EXCHANGE   16
#define SSL_HS_FINISHED   20
#define TLS_EXT_SERVERNAME   0
#define TLS_EXT_SERVERNAME_HOSTNAME   0
#define TLS_EXT_MAX_FRAGMENT_LENGTH   1
#define TLS_EXT_TRUNCATED_HMAC   4
#define TLS_EXT_SUPPORTED_ELLIPTIC_CURVES   10
#define TLS_EXT_SUPPORTED_POINT_FORMATS   11
#define TLS_EXT_SIG_ALG   13
#define TLS_EXT_ALPN   16
#define TLS_EXT_SESSION_TICKET   35
#define TLS_EXT_RENEGOTIATION_INFO   0xFF01
#define TLS_EXT_SUPPORTED_POINT_FORMATS_PRESENT   (1 << 0)
#define POLARSSL_PREMASTER_SIZE   POLARSSL_MPI_MAX_SIZE

Typedefs

typedef int(* rsa_decrypt_func )(void *ctx, int mode, size_t *olen, const unsigned char *input, unsigned char *output, size_t output_max_len)
typedef int(* rsa_sign_func )(void *ctx, int(*f_rng)(void *, unsigned char *, size_t), void *p_rng, int mode, md_type_t md_alg, unsigned int hashlen, const unsigned char *hash, unsigned char *sig)
typedef size_t(* rsa_key_len_func )(void *ctx)
typedef struct _ssl_session ssl_session
typedef struct _ssl_context ssl_context
typedef struct _ssl_transform ssl_transform
typedef struct
_ssl_handshake_params 
ssl_handshake_params
typedef struct _ssl_ticket_keys ssl_ticket_keys
typedef struct _ssl_key_cert ssl_key_cert

Enumerations

enum  ssl_states {
  SSL_HELLO_REQUEST, SSL_CLIENT_HELLO, SSL_SERVER_HELLO, SSL_SERVER_CERTIFICATE,
  SSL_SERVER_KEY_EXCHANGE, SSL_CERTIFICATE_REQUEST, SSL_SERVER_HELLO_DONE, SSL_CLIENT_CERTIFICATE,
  SSL_CLIENT_KEY_EXCHANGE, SSL_CERTIFICATE_VERIFY, SSL_CLIENT_CHANGE_CIPHER_SPEC, SSL_CLIENT_FINISHED,
  SSL_SERVER_CHANGE_CIPHER_SPEC, SSL_SERVER_FINISHED, SSL_FLUSH_BUFFERS, SSL_HANDSHAKE_WRAPUP,
  SSL_HANDSHAKE_OVER, SSL_SERVER_NEW_SESSION_TICKET
}

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)
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_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_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_handshake_client_step (ssl_context *ssl)
int ssl_handshake_server_step (ssl_context *ssl)
void ssl_handshake_wrapup (ssl_context *ssl)
int ssl_send_fatal_handshake_failure (ssl_context *ssl)
int ssl_derive_keys (ssl_context *ssl)
int ssl_read_record (ssl_context *ssl)
int ssl_fetch_input (ssl_context *ssl, size_t nb_want)
int ssl_write_record (ssl_context *ssl)
int ssl_flush_output (ssl_context *ssl)
int ssl_parse_certificate (ssl_context *ssl)
int ssl_write_certificate (ssl_context *ssl)
int ssl_parse_change_cipher_spec (ssl_context *ssl)
int ssl_write_change_cipher_spec (ssl_context *ssl)
int ssl_parse_finished (ssl_context *ssl)
int ssl_write_finished (ssl_context *ssl)
void ssl_optimize_checksum (ssl_context *ssl, const ssl_ciphersuite_t *ciphersuite_info)
int ssl_psk_derive_premaster (ssl_context *ssl, key_exchange_type_t key_ex)
unsigned char ssl_sig_from_pk (pk_context *pk)
pk_type_t ssl_pk_alg_from_sig (unsigned char sig)
md_type_t ssl_md_alg_from_hash (unsigned char hash)
static pk_contextssl_own_key (ssl_context *ssl)
static x509_crtssl_own_cert (ssl_context *ssl)
int ssl_check_cert_usage (const x509_crt *cert, const ssl_ciphersuite_t *ciphersuite, int cert_endpoint)
static int safer_memcmp (const void *a, const void *b, size_t n)

Detailed Description

SSL/TLS functions.

Copyright (C) 2006-2013, Brainspark B.V.

This file is part of PolarSSL (http://www.polarssl.org) Lead Maintainer: Paul Bakker <polarssl_maintainer at polarssl.org>

All rights reserved.

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.

Macro Definition Documentation

#define POLARSSL_ERR_SSL_BAD_HS_CERTIFICATE   -0x7A00

Processing of the Certificate handshake message failed.

Definition at line 122 of file ssl.h.

#define POLARSSL_ERR_SSL_BAD_HS_CERTIFICATE_REQUEST   -0x7A80

Processing of the CertificateRequest handshake message failed.

Definition at line 123 of file ssl.h.

#define POLARSSL_ERR_SSL_BAD_HS_CERTIFICATE_VERIFY   -0x7D80

Processing of the CertificateVerify handshake message failed.

Definition at line 129 of file ssl.h.

#define POLARSSL_ERR_SSL_BAD_HS_CHANGE_CIPHER_SPEC   -0x7E00

Processing of the ChangeCipherSpec handshake message failed.

Definition at line 130 of file ssl.h.

#define POLARSSL_ERR_SSL_BAD_HS_CLIENT_HELLO   -0x7900

Processing of the ClientHello handshake message failed.

Definition at line 120 of file ssl.h.

#define POLARSSL_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE   -0x7C00

Processing of the ClientKeyExchange handshake message failed.

Definition at line 126 of file ssl.h.

#define POLARSSL_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE_CS   -0x7D00

Processing of the ClientKeyExchange handshake message failed in DHM / ECDH Calculate Secret.

Definition at line 128 of file ssl.h.

#define POLARSSL_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE_RP   -0x7C80

Processing of the ClientKeyExchange handshake message failed in DHM / ECDH Read Public.

Definition at line 127 of file ssl.h.

#define POLARSSL_ERR_SSL_BAD_HS_FINISHED   -0x7E80

Processing of the Finished handshake message failed.

Definition at line 131 of file ssl.h.

#define POLARSSL_ERR_SSL_BAD_HS_NEW_SESSION_TICKET   -0x6E00

Processing of the NewSessionTicket handshake message failed.

Definition at line 137 of file ssl.h.

#define POLARSSL_ERR_SSL_BAD_HS_PROTOCOL_VERSION   -0x6E80

Handshake protocol not within min/max boundaries.

Definition at line 136 of file ssl.h.

#define POLARSSL_ERR_SSL_BAD_HS_SERVER_HELLO   -0x7980

Processing of the ServerHello handshake message failed.

Definition at line 121 of file ssl.h.

#define POLARSSL_ERR_SSL_BAD_HS_SERVER_HELLO_DONE   -0x7B80

Processing of the ServerHelloDone handshake message failed.

Definition at line 125 of file ssl.h.

#define POLARSSL_ERR_SSL_BAD_HS_SERVER_KEY_EXCHANGE   -0x7B00

Processing of the ServerKeyExchange handshake message failed.

Definition at line 124 of file ssl.h.

#define POLARSSL_ERR_SSL_BAD_INPUT_DATA   -0x7100

Bad input parameters to function.

Definition at line 104 of file ssl.h.

#define POLARSSL_ERR_SSL_CA_CHAIN_REQUIRED   -0x7680

No CA Chain is set, but required to operate.

Definition at line 115 of file ssl.h.

#define POLARSSL_ERR_SSL_CERTIFICATE_REQUIRED   -0x7580

The own certificate is not set, but needed by the server.

Definition at line 113 of file ssl.h.

#define POLARSSL_ERR_SSL_CERTIFICATE_TOO_LARGE   -0x7500

Our own certificate(s) is/are too large to send in an SSL message.

Definition at line 112 of file ssl.h.

#define POLARSSL_ERR_SSL_COMPRESSION_FAILED   -0x6F00

Processing of the compression / decompression failed.

Definition at line 135 of file ssl.h.

#define POLARSSL_ERR_SSL_CONN_EOF   -0x7280

The connection indicated an EOF.

Definition at line 107 of file ssl.h.

#define POLARSSL_ERR_SSL_COUNTER_WRAPPING   -0x6B80

A counter would wrap (eg, too many messages exchanged).

Definition at line 142 of file ssl.h.

#define POLARSSL_ERR_SSL_FATAL_ALERT_MESSAGE   -0x7780

A fatal alert message was received from our peer.

Definition at line 117 of file ssl.h.

#define POLARSSL_ERR_SSL_FEATURE_UNAVAILABLE   -0x7080

The requested feature is not available.

Definition at line 103 of file ssl.h.

#define POLARSSL_ERR_SSL_HW_ACCEL_FAILED   -0x7F80

Hardware acceleration function returned with error.

Definition at line 133 of file ssl.h.

#define POLARSSL_ERR_SSL_HW_ACCEL_FALLTHROUGH   -0x6F80

Hardware acceleration function skipped / left alone data.

Definition at line 134 of file ssl.h.

#define POLARSSL_ERR_SSL_INTERNAL_ERROR   -0x6C00

Internal error (eg, unexpected failure in lower-level module)

Definition at line 141 of file ssl.h.

#define POLARSSL_ERR_SSL_INVALID_MAC   -0x7180

Verification of the message MAC failed.

Definition at line 105 of file ssl.h.

#define POLARSSL_ERR_SSL_INVALID_RECORD   -0x7200

An invalid SSL record was received.

Definition at line 106 of file ssl.h.

#define POLARSSL_ERR_SSL_MALLOC_FAILED   -0x7F00

Memory allocation failed.

Definition at line 132 of file ssl.h.

#define POLARSSL_ERR_SSL_NO_CIPHER_CHOSEN   -0x7380

The server has no ciphersuites in common with the client.

Definition at line 109 of file ssl.h.

#define POLARSSL_ERR_SSL_NO_CLIENT_CERTIFICATE   -0x7480

No client certification received from the client, but required by the authentication mode.

Definition at line 111 of file ssl.h.

#define POLARSSL_ERR_SSL_NO_RNG   -0x7400

No RNG was provided to the SSL module.

Definition at line 110 of file ssl.h.

#define POLARSSL_ERR_SSL_PEER_CLOSE_NOTIFY   -0x7880

The peer notified us that the connection is going to be closed.

Definition at line 119 of file ssl.h.

#define POLARSSL_ERR_SSL_PEER_VERIFY_FAILED   -0x7800

Verification of our peer failed.

Definition at line 118 of file ssl.h.

#define POLARSSL_ERR_SSL_PK_TYPE_MISMATCH   -0x6D00

Public key type mismatch (eg, asked for RSA key exchange and presented EC key)

Definition at line 139 of file ssl.h.

#define POLARSSL_ERR_SSL_PRIVATE_KEY_REQUIRED   -0x7600

The own private key or pre-shared key is not set, but needed.

Definition at line 114 of file ssl.h.

#define POLARSSL_ERR_SSL_SESSION_TICKET_EXPIRED   -0x6D80

Session ticket has expired.

Definition at line 138 of file ssl.h.

#define POLARSSL_ERR_SSL_UNEXPECTED_MESSAGE   -0x7700

An unexpected message was received from our peer.

Definition at line 116 of file ssl.h.

#define POLARSSL_ERR_SSL_UNKNOWN_CIPHER   -0x7300

An unknown cipher was received.

Definition at line 108 of file ssl.h.

#define POLARSSL_ERR_SSL_UNKNOWN_IDENTITY   -0x6C80

Unknown identity received (eg, PSK identity)

Definition at line 140 of file ssl.h.

#define POLARSSL_KEY_EXCHANGE__SOME__ECDHE_ENABLED

Definition at line 89 of file ssl.h.

#define POLARSSL_KEY_EXCHANGE__SOME__PSK_ENABLED

Definition at line 83 of file ssl.h.

#define POLARSSL_PREMASTER_SIZE   POLARSSL_MPI_MAX_SIZE

Definition at line 371 of file ssl.h.

#define SSL_ALERT_LEVEL_FATAL   2

Definition at line 294 of file ssl.h.

#define SSL_ALERT_LEVEL_WARNING   1

Definition at line 293 of file ssl.h.

#define SSL_ALERT_MSG_ACCESS_DENIED   49 /* 0x31 */

Definition at line 311 of file ssl.h.

#define SSL_ALERT_MSG_BAD_CERT   42 /* 0x2A */

Definition at line 304 of file ssl.h.

#define SSL_ALERT_MSG_BAD_RECORD_MAC   20 /* 0x14 */

Definition at line 298 of file ssl.h.

#define SSL_ALERT_MSG_CERT_EXPIRED   45 /* 0x2D */

Definition at line 307 of file ssl.h.

#define SSL_ALERT_MSG_CERT_REVOKED   44 /* 0x2C */

Definition at line 306 of file ssl.h.

#define SSL_ALERT_MSG_CERT_UNKNOWN   46 /* 0x2E */

Definition at line 308 of file ssl.h.

#define SSL_ALERT_MSG_CLOSE_NOTIFY   0 /* 0x00 */

Definition at line 296 of file ssl.h.

#define SSL_ALERT_MSG_DECODE_ERROR   50 /* 0x32 */

Definition at line 312 of file ssl.h.

#define SSL_ALERT_MSG_DECOMPRESSION_FAILURE   30 /* 0x1E */

Definition at line 301 of file ssl.h.

#define SSL_ALERT_MSG_DECRYPT_ERROR   51 /* 0x33 */

Definition at line 313 of file ssl.h.

#define SSL_ALERT_MSG_DECRYPTION_FAILED   21 /* 0x15 */

Definition at line 299 of file ssl.h.

#define SSL_ALERT_MSG_EXPORT_RESTRICTION   60 /* 0x3C */

Definition at line 314 of file ssl.h.

#define SSL_ALERT_MSG_HANDSHAKE_FAILURE   40 /* 0x28 */

Definition at line 302 of file ssl.h.

#define SSL_ALERT_MSG_ILLEGAL_PARAMETER   47 /* 0x2F */

Definition at line 309 of file ssl.h.

#define SSL_ALERT_MSG_INSUFFICIENT_SECURITY   71 /* 0x47 */

Definition at line 316 of file ssl.h.

#define SSL_ALERT_MSG_INTERNAL_ERROR   80 /* 0x50 */

Definition at line 317 of file ssl.h.

#define SSL_ALERT_MSG_NO_APPLICATION_PROTOCOL   120 /* 0x78 */

Definition at line 323 of file ssl.h.

#define SSL_ALERT_MSG_NO_CERT   41 /* 0x29 */

Definition at line 303 of file ssl.h.

#define SSL_ALERT_MSG_NO_RENEGOTIATION   100 /* 0x64 */

Definition at line 319 of file ssl.h.

#define SSL_ALERT_MSG_PROTOCOL_VERSION   70 /* 0x46 */

Definition at line 315 of file ssl.h.

#define SSL_ALERT_MSG_RECORD_OVERFLOW   22 /* 0x16 */

Definition at line 300 of file ssl.h.

#define SSL_ALERT_MSG_UNEXPECTED_MESSAGE   10 /* 0x0A */

Definition at line 297 of file ssl.h.

#define SSL_ALERT_MSG_UNKNOWN_CA   48 /* 0x30 */

Definition at line 310 of file ssl.h.

#define SSL_ALERT_MSG_UNKNOWN_PSK_IDENTITY   115 /* 0x73 */

Definition at line 322 of file ssl.h.

#define SSL_ALERT_MSG_UNRECOGNIZED_NAME   112 /* 0x70 */

Definition at line 321 of file ssl.h.

#define SSL_ALERT_MSG_UNSUPPORTED_CERT   43 /* 0x2B */

Definition at line 305 of file ssl.h.

#define SSL_ALERT_MSG_UNSUPPORTED_EXT   110 /* 0x6E */

Definition at line 320 of file ssl.h.

#define SSL_ALERT_MSG_USER_CANCELED   90 /* 0x5A */

Definition at line 318 of file ssl.h.

#define SSL_BUFFER_LEN   (SSL_MAX_CONTENT_LEN + SSL_COMPRESSION_ADD + 301)

Definition at line 258 of file ssl.h.

#define SSL_CERT_TYPE_ECDSA_SIGN   64

Definition at line 283 of file ssl.h.

#define SSL_CERT_TYPE_RSA_SIGN   1

Definition at line 282 of file ssl.h.

#define SSL_COMPRESS_DEFLATE   1

Definition at line 203 of file ssl.h.

#define SSL_COMPRESS_NULL   0

Definition at line 202 of file ssl.h.

#define SSL_COMPRESSION_ADD   0

Definition at line 255 of file ssl.h.

#define SSL_DEFAULT_TICKET_LIFETIME   86400

Lifetime of session tickets (if enabled)

Definition at line 232 of file ssl.h.

#define SSL_EMPTY_RENEGOTIATION_INFO   0xFF

renegotiation info ext

Definition at line 260 of file ssl.h.

#define SSL_HASH_MD5   1

Definition at line 267 of file ssl.h.

#define SSL_HASH_NONE   0

Definition at line 266 of file ssl.h.

#define SSL_HASH_SHA1   2

Definition at line 268 of file ssl.h.

#define SSL_HASH_SHA224   3

Definition at line 269 of file ssl.h.

#define SSL_HASH_SHA256   4

Definition at line 270 of file ssl.h.

#define SSL_HASH_SHA384   5

Definition at line 271 of file ssl.h.

#define SSL_HASH_SHA512   6

Definition at line 272 of file ssl.h.

#define SSL_HS_CERTIFICATE   11

Definition at line 329 of file ssl.h.

#define SSL_HS_CERTIFICATE_REQUEST   13

Definition at line 331 of file ssl.h.

#define SSL_HS_CERTIFICATE_VERIFY   15

Definition at line 333 of file ssl.h.

#define SSL_HS_CLIENT_HELLO   1

Definition at line 326 of file ssl.h.

#define SSL_HS_CLIENT_KEY_EXCHANGE   16

Definition at line 334 of file ssl.h.

#define SSL_HS_FINISHED   20

Definition at line 335 of file ssl.h.

#define SSL_HS_HELLO_REQUEST   0

Definition at line 325 of file ssl.h.

#define SSL_HS_NEW_SESSION_TICKET   4

Definition at line 328 of file ssl.h.

#define SSL_HS_SERVER_HELLO   2

Definition at line 327 of file ssl.h.

#define SSL_HS_SERVER_HELLO_DONE   14

Definition at line 332 of file ssl.h.

#define SSL_HS_SERVER_KEY_EXCHANGE   12

Definition at line 330 of file ssl.h.

#define SSL_INITIAL_HANDSHAKE   0

Definition at line 209 of file ssl.h.

#define SSL_IS_CLIENT   0

Definition at line 200 of file ssl.h.

#define SSL_IS_SERVER   1

Definition at line 201 of file ssl.h.

#define SSL_LEGACY_ALLOW_RENEGOTIATION   1

Definition at line 221 of file ssl.h.

#define SSL_LEGACY_BREAK_HANDSHAKE   2

Definition at line 222 of file ssl.h.

#define SSL_LEGACY_NO_RENEGOTIATION   0

Definition at line 220 of file ssl.h.

#define SSL_LEGACY_RENEGOTIATION   0

Definition at line 214 of file ssl.h.

#define SSL_MAJOR_VERSION_3   3

Definition at line 147 of file ssl.h.

#define SSL_MAX_CONTENT_LEN   16384

Size of the input / output buffer.

Definition at line 243 of file ssl.h.

#define SSL_MAX_FRAG_LEN_1024   2

MaxFragmentLength 2^10

Definition at line 195 of file ssl.h.

#define SSL_MAX_FRAG_LEN_2048   3

MaxFragmentLength 2^11

Definition at line 196 of file ssl.h.

#define SSL_MAX_FRAG_LEN_4096   4

MaxFragmentLength 2^12

Definition at line 197 of file ssl.h.

#define SSL_MAX_FRAG_LEN_512   1

MaxFragmentLength 2^9

Definition at line 194 of file ssl.h.

#define SSL_MAX_FRAG_LEN_INVALID   5

first invalid value

Definition at line 198 of file ssl.h.

#define SSL_MAX_FRAG_LEN_NONE   0

don't use this extension

Definition at line 193 of file ssl.h.

#define SSL_MAX_MAJOR_VERSION   SSL_MAJOR_VERSION_3

Definition at line 173 of file ssl.h.

#define SSL_MAX_MINOR_VERSION   SSL_MINOR_VERSION_3

Definition at line 176 of file ssl.h.

#define SSL_MIN_MAJOR_VERSION   SSL_MAJOR_VERSION_3

Definition at line 154 of file ssl.h.

#define SSL_MIN_MINOR_VERSION   SSL_MINOR_VERSION_0

Definition at line 157 of file ssl.h.

#define SSL_MINOR_VERSION_0   0

SSL v3.0

Definition at line 148 of file ssl.h.

#define SSL_MINOR_VERSION_1   1

TLS v1.0

Definition at line 149 of file ssl.h.

#define SSL_MINOR_VERSION_2   2

TLS v1.1

Definition at line 150 of file ssl.h.

#define SSL_MINOR_VERSION_3   3

TLS v1.2

Definition at line 151 of file ssl.h.

#define SSL_MSG_ALERT   21

Definition at line 289 of file ssl.h.

#define SSL_MSG_APPLICATION_DATA   23

Definition at line 291 of file ssl.h.

#define SSL_MSG_CHANGE_CIPHER_SPEC   20

Definition at line 288 of file ssl.h.

#define SSL_MSG_HANDSHAKE   22

Definition at line 290 of file ssl.h.

#define SSL_RENEGOTIATION   1 /* In progress */

Definition at line 210 of file ssl.h.

#define SSL_RENEGOTIATION_DISABLED   0

Definition at line 217 of file ssl.h.

#define SSL_RENEGOTIATION_DONE   2 /* Done */

Definition at line 211 of file ssl.h.

#define SSL_RENEGOTIATION_ENABLED   1

Definition at line 218 of file ssl.h.

#define SSL_RENEGOTIATION_PENDING   3 /* Requested (server only) */

Definition at line 212 of file ssl.h.

#define SSL_SECURE_RENEGOTIATION   1

Definition at line 215 of file ssl.h.

#define SSL_SESSION_TICKETS_DISABLED   0

Definition at line 228 of file ssl.h.

#define SSL_SESSION_TICKETS_ENABLED   1

Definition at line 229 of file ssl.h.

#define SSL_SIG_ANON   0

Definition at line 274 of file ssl.h.

#define SSL_SIG_ECDSA   3

Definition at line 276 of file ssl.h.

#define SSL_SIG_RSA   1

Definition at line 275 of file ssl.h.

#define SSL_TRUNC_HMAC_DISABLED   0

Definition at line 224 of file ssl.h.

#define SSL_TRUNC_HMAC_ENABLED   1

Definition at line 225 of file ssl.h.

#define SSL_TRUNCATED_HMAC_LEN   10 /* 80 bits, rfc 6066 section 7 */

Definition at line 226 of file ssl.h.

#define SSL_VERIFY_NONE   0

Definition at line 205 of file ssl.h.

#define SSL_VERIFY_OPTIONAL   1

Definition at line 206 of file ssl.h.

#define SSL_VERIFY_REQUIRED   2

Definition at line 207 of file ssl.h.

#define TLS_EXT_ALPN   16

Definition at line 352 of file ssl.h.

#define TLS_EXT_MAX_FRAGMENT_LENGTH   1

Definition at line 343 of file ssl.h.

#define TLS_EXT_RENEGOTIATION_INFO   0xFF01

Definition at line 356 of file ssl.h.

#define TLS_EXT_SERVERNAME   0

Definition at line 340 of file ssl.h.

#define TLS_EXT_SERVERNAME_HOSTNAME   0

Definition at line 341 of file ssl.h.

#define TLS_EXT_SESSION_TICKET   35

Definition at line 354 of file ssl.h.

#define TLS_EXT_SIG_ALG   13

Definition at line 350 of file ssl.h.

#define TLS_EXT_SUPPORTED_ELLIPTIC_CURVES   10

Definition at line 347 of file ssl.h.

#define TLS_EXT_SUPPORTED_POINT_FORMATS   11

Definition at line 348 of file ssl.h.

#define TLS_EXT_SUPPORTED_POINT_FORMATS_PRESENT   (1 << 0)

Definition at line 363 of file ssl.h.

#define TLS_EXT_TRUNCATED_HMAC   4

Definition at line 345 of file ssl.h.

Typedef Documentation

typedef int(* rsa_decrypt_func)(void *ctx, int mode, size_t *olen, const unsigned char *input, unsigned char *output, size_t output_max_len)

Definition at line 382 of file ssl.h.

typedef size_t(* rsa_key_len_func)(void *ctx)

Definition at line 389 of file ssl.h.

typedef int(* rsa_sign_func)(void *ctx, int(*f_rng)(void *, unsigned char *, size_t), void *p_rng, int mode, md_type_t md_alg, unsigned int hashlen, const unsigned char *hash, unsigned char *sig)

Definition at line 385 of file ssl.h.

typedef struct _ssl_context ssl_context

Definition at line 418 of file ssl.h.

Definition at line 420 of file ssl.h.

typedef struct _ssl_key_cert ssl_key_cert

Definition at line 425 of file ssl.h.

typedef struct _ssl_session ssl_session

Definition at line 417 of file ssl.h.

Definition at line 422 of file ssl.h.

typedef struct _ssl_transform ssl_transform

Definition at line 419 of file ssl.h.

Enumeration Type Documentation

enum ssl_states
Enumerator:
SSL_HELLO_REQUEST 
SSL_CLIENT_HELLO 
SSL_SERVER_HELLO 
SSL_SERVER_CERTIFICATE 
SSL_SERVER_KEY_EXCHANGE 
SSL_CERTIFICATE_REQUEST 
SSL_SERVER_HELLO_DONE 
SSL_CLIENT_CERTIFICATE 
SSL_CLIENT_KEY_EXCHANGE 
SSL_CERTIFICATE_VERIFY 
SSL_CLIENT_CHANGE_CIPHER_SPEC 
SSL_CLIENT_FINISHED 
SSL_SERVER_CHANGE_CIPHER_SPEC 
SSL_SERVER_FINISHED 
SSL_FLUSH_BUFFERS 
SSL_HANDSHAKE_WRAPUP 
SSL_HANDSHAKE_OVER 
SSL_SERVER_NEW_SESSION_TICKET 

Definition at line 394 of file ssl.h.

Function Documentation

static int safer_memcmp ( const void *  a,
const void *  b,
size_t  n 
)
inlinestatic

Definition at line 1676 of file ssl.h.

int ssl_check_cert_usage ( const x509_crt cert,
const ssl_ciphersuite_t ciphersuite,
int  cert_endpoint 
)
int ssl_close_notify ( ssl_context ssl)

Notify the peer that the connection is being closed.

Parameters
sslSSL context
int ssl_derive_keys ( ssl_context ssl)
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.
int ssl_flush_output ( ssl_context ssl)
void ssl_free ( ssl_context ssl)

Free referenced items in an SSL context and clear memory.

Parameters
sslSSL context
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.
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
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
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
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
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
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()
int ssl_get_verify_result ( const ssl_context ssl)

Return the result of the certificate verification.

Parameters
sslSSL context
Returns
0 if successful, or a combination of: BADCERT_EXPIRED BADCERT_REVOKED BADCERT_CN_MISMATCH BADCERT_NOT_TRUSTED
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
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.
int ssl_handshake_client_step ( ssl_context ssl)
void ssl_handshake_free ( ssl_handshake_params handshake)

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

Parameters
handshakeSSL handshake context
int ssl_handshake_server_step ( ssl_context ssl)
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.
void ssl_handshake_wrapup ( ssl_context ssl)
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
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)
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.
md_type_t ssl_md_alg_from_hash ( unsigned char  hash)
void ssl_optimize_checksum ( ssl_context ssl,
const ssl_ciphersuite_t ciphersuite_info 
)
static x509_crt* ssl_own_cert ( ssl_context ssl)
inlinestatic
static pk_context* ssl_own_key ( ssl_context ssl)
inlinestatic
int ssl_parse_certificate ( ssl_context ssl)
int ssl_parse_change_cipher_spec ( ssl_context ssl)
int ssl_parse_finished ( ssl_context ssl)
pk_type_t ssl_pk_alg_from_sig ( unsigned char  sig)
int ssl_psk_derive_premaster ( ssl_context ssl,
key_exchange_type_t  key_ex 
)
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
lenhow many bytes must be read
Returns
This function returns the number of bytes read, 0 for EOF, or a negative error code.
int ssl_read_record ( ssl_context ssl)
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.
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.
int ssl_send_fatal_handshake_failure ( ssl_context ssl)
void ssl_session_free ( ssl_session session)

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

Parameters
sessionSSL session
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
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.
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.
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
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)
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
sslSSL context
ciphersuites0-terminated list of allowed ciphersuites
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)
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
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
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
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.
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
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
O if successful or POLARSSL_ERR_SSL_BAD_INPUT_DATA
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)
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
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)
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
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
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.
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
sslSSL context
own_certown public certificate chain
rsa_keyown private RSA key
Returns
0 on success, or a specific error code.
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
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
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)
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
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()
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
sslSSL context
f_get_cachesession get callback
p_get_cachesession get parameter
f_set_cachesession set callback
p_set_cachesession set parameter
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
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
O if successful, or a specific error code (server only).
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
int ssl_set_truncated_hmac ( ssl_context ssl,
int  truncate 
)

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

Parameters
sslSSL context
truncateEnable 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
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 \c x509parse_verify()
Parameters
sslSSL context
f_vrfyverification function
p_vrfyverification parameter
unsigned char ssl_sig_from_pk ( pk_context pk)
void ssl_transform_free ( ssl_transform transform)

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

Parameters
transformSSL transform context
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.
int ssl_write_certificate ( ssl_context ssl)
int ssl_write_change_cipher_spec ( ssl_context ssl)
int ssl_write_finished ( ssl_context ssl)
int ssl_write_record ( ssl_context ssl)