PolarSSL v1.2.12
Data Structures | Macros | Typedefs | Enumerations | Functions | Variables
ssl.h File Reference

SSL/TLS functions. More...

#include <time.h>
#include "net.h"
#include "rsa.h"
#include "md5.h"
#include "sha1.h"
#include "sha2.h"
#include "sha4.h"
#include "x509.h"
#include "config.h"
#include "dhm.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_context
 

Macros

#define POLARSSL_ERR_SSL_FEATURE_UNAVAILABLE   -0x7080
 The requested feature is not available. More...
 
#define POLARSSL_ERR_SSL_BAD_INPUT_DATA   -0x7100
 Bad input parameters to function. More...
 
#define POLARSSL_ERR_SSL_INVALID_MAC   -0x7180
 Verification of the message MAC failed. More...
 
#define POLARSSL_ERR_SSL_INVALID_RECORD   -0x7200
 An invalid SSL record was received. More...
 
#define POLARSSL_ERR_SSL_CONN_EOF   -0x7280
 The connection indicated an EOF. More...
 
#define POLARSSL_ERR_SSL_UNKNOWN_CIPHER   -0x7300
 An unknown cipher was received. More...
 
#define POLARSSL_ERR_SSL_NO_CIPHER_CHOSEN   -0x7380
 The server has no ciphersuites in common with the client. More...
 
#define POLARSSL_ERR_SSL_NO_RNG   -0x7400
 No RNG was provided to the SSL module. More...
 
#define POLARSSL_ERR_SSL_NO_CLIENT_CERTIFICATE   -0x7480
 No client certification received from the client, but required by the authentication mode. More...
 
#define POLARSSL_ERR_SSL_CERTIFICATE_TOO_LARGE   -0x7500
 Our own certificate(s) is/are too large to send in an SSL message. More...
 
#define POLARSSL_ERR_SSL_CERTIFICATE_REQUIRED   -0x7580
 The own certificate is not set, but needed by the server. More...
 
#define POLARSSL_ERR_SSL_PRIVATE_KEY_REQUIRED   -0x7600
 The own private key is not set, but needed. More...
 
#define POLARSSL_ERR_SSL_CA_CHAIN_REQUIRED   -0x7680
 No CA Chain is set, but required to operate. More...
 
#define POLARSSL_ERR_SSL_UNEXPECTED_MESSAGE   -0x7700
 An unexpected message was received from our peer. More...
 
#define POLARSSL_ERR_SSL_FATAL_ALERT_MESSAGE   -0x7780
 A fatal alert message was received from our peer. More...
 
#define POLARSSL_ERR_SSL_PEER_VERIFY_FAILED   -0x7800
 Verification of our peer failed. More...
 
#define POLARSSL_ERR_SSL_PEER_CLOSE_NOTIFY   -0x7880
 The peer notified us that the connection is going to be closed. More...
 
#define POLARSSL_ERR_SSL_BAD_HS_CLIENT_HELLO   -0x7900
 Processing of the ClientHello handshake message failed. More...
 
#define POLARSSL_ERR_SSL_BAD_HS_SERVER_HELLO   -0x7980
 Processing of the ServerHello handshake message failed. More...
 
#define POLARSSL_ERR_SSL_BAD_HS_CERTIFICATE   -0x7A00
 Processing of the Certificate handshake message failed. More...
 
#define POLARSSL_ERR_SSL_BAD_HS_CERTIFICATE_REQUEST   -0x7A80
 Processing of the CertificateRequest handshake message failed. More...
 
#define POLARSSL_ERR_SSL_BAD_HS_SERVER_KEY_EXCHANGE   -0x7B00
 Processing of the ServerKeyExchange handshake message failed. More...
 
#define POLARSSL_ERR_SSL_BAD_HS_SERVER_HELLO_DONE   -0x7B80
 Processing of the ServerHelloDone handshake message failed. More...
 
#define POLARSSL_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE   -0x7C00
 Processing of the ClientKeyExchange handshake message failed. More...
 
#define POLARSSL_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE_DHM_RP   -0x7C80
 Processing of the ClientKeyExchange handshake message failed in DHM Read Public. More...
 
#define POLARSSL_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE_DHM_CS   -0x7D00
 Processing of the ClientKeyExchange handshake message failed in DHM Calculate Secret. More...
 
#define POLARSSL_ERR_SSL_BAD_HS_CERTIFICATE_VERIFY   -0x7D80
 Processing of the CertificateVerify handshake message failed. More...
 
#define POLARSSL_ERR_SSL_BAD_HS_CHANGE_CIPHER_SPEC   -0x7E00
 Processing of the ChangeCipherSpec handshake message failed. More...
 
#define POLARSSL_ERR_SSL_BAD_HS_FINISHED   -0x7E80
 Processing of the Finished handshake message failed. More...
 
#define POLARSSL_ERR_SSL_MALLOC_FAILED   -0x7F00
 Memory allocation failed. More...
 
#define POLARSSL_ERR_SSL_HW_ACCEL_FAILED   -0x7F80
 Hardware acceleration function returned with error. More...
 
#define POLARSSL_ERR_SSL_HW_ACCEL_FALLTHROUGH   -0x6F80
 Hardware acceleration function skipped / left alone data. More...
 
#define POLARSSL_ERR_SSL_COMPRESSION_FAILED   -0x6F00
 Processing of the compression / decompression failed. More...
 
#define POLARSSL_ERR_SSL_BAD_HS_PROTOCOL_VERSION   -0x6E80
 Handshake protocol not within min/max boundaries. More...
 
#define POLARSSL_ERR_SSL_COUNTER_WRAPPING   -0x6B80
 A counter would wrap (eg, too many messages exchanged). More...
 
#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_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
 
#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_MAX_CONTENT_LEN   16384
 Size of the input / output buffer. More...
 
#define SSL_COMPRESSION_ADD   0
 
#define SSL_BUFFER_LEN   (SSL_MAX_CONTENT_LEN + SSL_COMPRESSION_ADD + 512)
 
#define TLS_RSA_WITH_NULL_MD5   0x01
 Weak! More...
 
#define TLS_RSA_WITH_NULL_SHA   0x02
 Weak! More...
 
#define TLS_RSA_WITH_NULL_SHA256   0x3B
 Weak! More...
 
#define TLS_RSA_WITH_DES_CBC_SHA   0x09
 Weak! Not in TLS 1.2. More...
 
#define TLS_DHE_RSA_WITH_DES_CBC_SHA   0x15
 Weak! Not in TLS 1.2. More...
 
#define TLS_RSA_WITH_RC4_128_MD5   0x04
 
#define TLS_RSA_WITH_RC4_128_SHA   0x05
 
#define TLS_RSA_WITH_3DES_EDE_CBC_SHA   0x0A
 
#define TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA   0x16
 
#define TLS_RSA_WITH_AES_128_CBC_SHA   0x2F
 
#define TLS_DHE_RSA_WITH_AES_128_CBC_SHA   0x33
 
#define TLS_RSA_WITH_AES_256_CBC_SHA   0x35
 
#define TLS_DHE_RSA_WITH_AES_256_CBC_SHA   0x39
 
#define TLS_RSA_WITH_AES_128_CBC_SHA256   0x3C
 TLS 1.2. More...
 
#define TLS_RSA_WITH_AES_256_CBC_SHA256   0x3D
 TLS 1.2. More...
 
#define TLS_DHE_RSA_WITH_AES_128_CBC_SHA256   0x67
 TLS 1.2. More...
 
#define TLS_DHE_RSA_WITH_AES_256_CBC_SHA256   0x6B
 TLS 1.2. More...
 
#define TLS_RSA_WITH_CAMELLIA_128_CBC_SHA   0x41
 
#define TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA   0x45
 
#define TLS_RSA_WITH_CAMELLIA_256_CBC_SHA   0x84
 
#define TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA   0x88
 
#define TLS_RSA_WITH_CAMELLIA_128_CBC_SHA256   0xBA
 TLS 1.2. More...
 
#define TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA256   0xBE
 TLS 1.2. More...
 
#define TLS_RSA_WITH_CAMELLIA_256_CBC_SHA256   0xC0
 TLS 1.2. More...
 
#define TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA256   0xC4
 TLS 1.2. More...
 
#define TLS_RSA_WITH_AES_128_GCM_SHA256   0x9C
 
#define TLS_RSA_WITH_AES_256_GCM_SHA384   0x9D
 
#define TLS_DHE_RSA_WITH_AES_128_GCM_SHA256   0x9E
 
#define TLS_DHE_RSA_WITH_AES_256_GCM_SHA384   0x9F
 
#define SSL_EMPTY_RENEGOTIATION_INFO   0xFF
 renegotiation info ext More...
 
#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_RSA   1
 
#define SSL_CERT_TYPE_RSA_SIGN   1
 
#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_HS_HELLO_REQUEST   0
 
#define SSL_HS_CLIENT_HELLO   1
 
#define SSL_HS_SERVER_HELLO   2
 
#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_SIG_ALG   13
 
#define TLS_EXT_RENEGOTIATION_INFO   0xFF01
 

Typedefs

typedef int(* rsa_decrypt_func )(void *ctx, int(*f_rng)(void *, unsigned char *, size_t), void *p_rng, 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, int hash_id, 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
 

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
}
 

Functions

static const int * ssl_list_ciphersuites (void)
 Returns the list of ciphersuites supported by the SSL/TLS module. More...
 
const char * ssl_get_ciphersuite_name (const int ciphersuite_id)
 Return the name of the ciphersuite associated with the given ID. More...
 
int ssl_get_ciphersuite_id (const char *ciphersuite_name)
 Return the ID of the ciphersuite associated with the given name. More...
 
int ssl_init (ssl_context *ssl)
 Initialize an SSL context. More...
 
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. More...
 
void ssl_set_endpoint (ssl_context *ssl, int endpoint)
 Set the current endpoint type. More...
 
void ssl_set_authmode (ssl_context *ssl, int authmode)
 Set the certificate verification mode. More...
 
void ssl_set_verify (ssl_context *ssl, int(*f_vrfy)(void *, x509_cert *, int, int *), void *p_vrfy)
 Set the verification callback (Optional). More...
 
void ssl_set_rng (ssl_context *ssl, int(*f_rng)(void *, unsigned char *, size_t), void *p_rng)
 Set the random number generator callback. More...
 
void ssl_set_dbg (ssl_context *ssl, void(*f_dbg)(void *, int, const char *), void *p_dbg)
 Set the debug callback. More...
 
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. More...
 
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. More...
 
void 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. More...
 
void ssl_set_ciphersuites (ssl_context *ssl, const int *ciphersuites)
 Set the list of allowed ciphersuites (Default: ssl_default_ciphersuites) (Overrides all version specific lists) More...
 
void ssl_set_ciphersuites_for_version (ssl_context *ssl, const int *ciphersuites, int major, int minor)
 Set the list of allowed ciphersuites for a specific version of the protocol. More...
 
void ssl_set_ca_chain (ssl_context *ssl, x509_cert *ca_chain, x509_crl *ca_crl, const char *peer_cn)
 Set the data required to verify peer certificate. More...
 
void ssl_set_own_cert (ssl_context *ssl, x509_cert *own_cert, rsa_context *rsa_key)
 Set own certificate chain and private key. More...
 
void ssl_set_own_cert_alt (ssl_context *ssl, x509_cert *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 private key and handling callbacks, such as the PKCS#11 wrappers or any other external private key handler. More...
 
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]) More...
 
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) More...
 
int ssl_set_hostname (ssl_context *ssl, const char *hostname)
 Set hostname for ServerName TLS extension (client-side only) More...
 
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). More...
 
void ssl_set_max_version (ssl_context *ssl, int major, int minor)
 Set the maximum supported version sent from the client side. More...
 
void ssl_set_min_version (ssl_context *ssl, int major, int minor)
 Set the minimum accepted SSL/TLS protocol version (Default: SSL_MAJOR_VERSION_3, SSL_MINOR_VERSION_0) More...
 
void ssl_set_renegotiation (ssl_context *ssl, int renegotiation)
 Enable / Disable renegotiation support for connection when initiated by peer (Default: SSL_RENEGOTIATION_DISABLED) More...
 
void ssl_legacy_renegotiation (ssl_context *ssl, int allow_legacy)
 Prevent or allow legacy renegotiation. More...
 
size_t ssl_get_bytes_avail (const ssl_context *ssl)
 Return the number of data bytes available to read. More...
 
int ssl_get_verify_result (const ssl_context *ssl)
 Return the result of the certificate verification. More...
 
const char * ssl_get_ciphersuite (const ssl_context *ssl)
 Return the name of the current ciphersuite. More...
 
const char * ssl_get_version (const ssl_context *ssl)
 Return the current SSL version (SSLv3/TLSv1/etc) More...
 
const x509_certssl_get_peer_cert (const ssl_context *ssl)
 Return the peer certificate from the current connection. More...
 
int ssl_handshake (ssl_context *ssl)
 Perform the SSL handshake. More...
 
int ssl_handshake_step (ssl_context *ssl)
 Perform a single step of the SSL handshake. More...
 
int ssl_renegotiate (ssl_context *ssl)
 Perform an SSL renegotiation on the running connection. More...
 
int ssl_read (ssl_context *ssl, unsigned char *buf, size_t len)
 Read at most 'len' application data bytes. More...
 
int ssl_write (ssl_context *ssl, const unsigned char *buf, size_t len)
 Write exactly 'len' application data bytes. More...
 
int ssl_send_alert_message (ssl_context *ssl, unsigned char level, unsigned char message)
 Send an alert message. More...
 
int ssl_close_notify (ssl_context *ssl)
 Notify the peer that the connection is being closed. More...
 
void ssl_free (ssl_context *ssl)
 Free referenced items in an SSL context and clear memory. More...
 
void ssl_session_free (ssl_session *session)
 Free referenced items in an SSL session including the peer certificate and clear memory. More...
 
void ssl_transform_free (ssl_transform *transform)
 Free referenced items in an SSL transform context and clear memory. More...
 
void ssl_handshake_free (ssl_handshake_params *handshake)
 Free referenced items in an SSL handshake context and clear memory. More...
 
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, int ciphersuite)
 
int ssl_get_ciphersuite_min_version (const int ciphersuite_id)
 
static int safer_memcmp (const void *a, const void *b, size_t n)
 

Variables

const int ssl_default_ciphersuites []
 

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

#define POLARSSL_ERR_SSL_BAD_HS_CERTIFICATE_REQUEST   -0x7A80

Processing of the CertificateRequest handshake message failed.

Definition at line 80 of file ssl.h.

#define POLARSSL_ERR_SSL_BAD_HS_CERTIFICATE_VERIFY   -0x7D80

Processing of the CertificateVerify handshake message failed.

Definition at line 86 of file ssl.h.

#define POLARSSL_ERR_SSL_BAD_HS_CHANGE_CIPHER_SPEC   -0x7E00

Processing of the ChangeCipherSpec handshake message failed.

Definition at line 87 of file ssl.h.

#define POLARSSL_ERR_SSL_BAD_HS_CLIENT_HELLO   -0x7900

Processing of the ClientHello handshake message failed.

Definition at line 77 of file ssl.h.

#define POLARSSL_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE   -0x7C00

Processing of the ClientKeyExchange handshake message failed.

Definition at line 83 of file ssl.h.

#define POLARSSL_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE_DHM_CS   -0x7D00

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

Definition at line 85 of file ssl.h.

#define POLARSSL_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE_DHM_RP   -0x7C80

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

Definition at line 84 of file ssl.h.

#define POLARSSL_ERR_SSL_BAD_HS_FINISHED   -0x7E80

Processing of the Finished handshake message failed.

Definition at line 88 of file ssl.h.

#define POLARSSL_ERR_SSL_BAD_HS_PROTOCOL_VERSION   -0x6E80

Handshake protocol not within min/max boundaries.

Definition at line 93 of file ssl.h.

#define POLARSSL_ERR_SSL_BAD_HS_SERVER_HELLO   -0x7980

Processing of the ServerHello handshake message failed.

Definition at line 78 of file ssl.h.

#define POLARSSL_ERR_SSL_BAD_HS_SERVER_HELLO_DONE   -0x7B80

Processing of the ServerHelloDone handshake message failed.

Definition at line 82 of file ssl.h.

#define POLARSSL_ERR_SSL_BAD_HS_SERVER_KEY_EXCHANGE   -0x7B00

Processing of the ServerKeyExchange handshake message failed.

Definition at line 81 of file ssl.h.

#define POLARSSL_ERR_SSL_BAD_INPUT_DATA   -0x7100

Bad input parameters to function.

Definition at line 61 of file ssl.h.

#define POLARSSL_ERR_SSL_CA_CHAIN_REQUIRED   -0x7680

No CA Chain is set, but required to operate.

Definition at line 72 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 70 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 69 of file ssl.h.

#define POLARSSL_ERR_SSL_COMPRESSION_FAILED   -0x6F00

Processing of the compression / decompression failed.

Definition at line 92 of file ssl.h.

#define POLARSSL_ERR_SSL_CONN_EOF   -0x7280

The connection indicated an EOF.

Definition at line 64 of file ssl.h.

#define POLARSSL_ERR_SSL_COUNTER_WRAPPING   -0x6B80

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

Definition at line 94 of file ssl.h.

#define POLARSSL_ERR_SSL_FATAL_ALERT_MESSAGE   -0x7780

A fatal alert message was received from our peer.

Definition at line 74 of file ssl.h.

#define POLARSSL_ERR_SSL_FEATURE_UNAVAILABLE   -0x7080

The requested feature is not available.

Definition at line 60 of file ssl.h.

#define POLARSSL_ERR_SSL_HW_ACCEL_FAILED   -0x7F80

Hardware acceleration function returned with error.

Definition at line 90 of file ssl.h.

#define POLARSSL_ERR_SSL_HW_ACCEL_FALLTHROUGH   -0x6F80

Hardware acceleration function skipped / left alone data.

Definition at line 91 of file ssl.h.

#define POLARSSL_ERR_SSL_INVALID_MAC   -0x7180

Verification of the message MAC failed.

Definition at line 62 of file ssl.h.

#define POLARSSL_ERR_SSL_INVALID_RECORD   -0x7200

An invalid SSL record was received.

Definition at line 63 of file ssl.h.

#define POLARSSL_ERR_SSL_MALLOC_FAILED   -0x7F00

Memory allocation failed.

Definition at line 89 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 66 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 68 of file ssl.h.

#define POLARSSL_ERR_SSL_NO_RNG   -0x7400

No RNG was provided to the SSL module.

Definition at line 67 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 76 of file ssl.h.

#define POLARSSL_ERR_SSL_PEER_VERIFY_FAILED   -0x7800

Verification of our peer failed.

Definition at line 75 of file ssl.h.

#define POLARSSL_ERR_SSL_PRIVATE_KEY_REQUIRED   -0x7600

The own private key is not set, but needed.

Definition at line 71 of file ssl.h.

#define POLARSSL_ERR_SSL_UNEXPECTED_MESSAGE   -0x7700

An unexpected message was received from our peer.

Definition at line 73 of file ssl.h.

#define POLARSSL_ERR_SSL_UNKNOWN_CIPHER   -0x7300

An unknown cipher was received.

Definition at line 65 of file ssl.h.

#define SSL_ALERT_LEVEL_FATAL   2

Definition at line 219 of file ssl.h.

#define SSL_ALERT_LEVEL_WARNING   1

Definition at line 218 of file ssl.h.

#define SSL_ALERT_MSG_ACCESS_DENIED   49 /* 0x31 */

Definition at line 236 of file ssl.h.

#define SSL_ALERT_MSG_BAD_CERT   42 /* 0x2A */

Definition at line 229 of file ssl.h.

#define SSL_ALERT_MSG_BAD_RECORD_MAC   20 /* 0x14 */

Definition at line 223 of file ssl.h.

#define SSL_ALERT_MSG_CERT_EXPIRED   45 /* 0x2D */

Definition at line 232 of file ssl.h.

#define SSL_ALERT_MSG_CERT_REVOKED   44 /* 0x2C */

Definition at line 231 of file ssl.h.

#define SSL_ALERT_MSG_CERT_UNKNOWN   46 /* 0x2E */

Definition at line 233 of file ssl.h.

#define SSL_ALERT_MSG_CLOSE_NOTIFY   0 /* 0x00 */

Definition at line 221 of file ssl.h.

#define SSL_ALERT_MSG_DECODE_ERROR   50 /* 0x32 */

Definition at line 237 of file ssl.h.

#define SSL_ALERT_MSG_DECOMPRESSION_FAILURE   30 /* 0x1E */

Definition at line 226 of file ssl.h.

#define SSL_ALERT_MSG_DECRYPT_ERROR   51 /* 0x33 */

Definition at line 238 of file ssl.h.

#define SSL_ALERT_MSG_DECRYPTION_FAILED   21 /* 0x15 */

Definition at line 224 of file ssl.h.

#define SSL_ALERT_MSG_EXPORT_RESTRICTION   60 /* 0x3C */

Definition at line 239 of file ssl.h.

#define SSL_ALERT_MSG_HANDSHAKE_FAILURE   40 /* 0x28 */

Definition at line 227 of file ssl.h.

#define SSL_ALERT_MSG_ILLEGAL_PARAMETER   47 /* 0x2F */

Definition at line 234 of file ssl.h.

#define SSL_ALERT_MSG_INSUFFICIENT_SECURITY   71 /* 0x47 */

Definition at line 241 of file ssl.h.

#define SSL_ALERT_MSG_INTERNAL_ERROR   80 /* 0x50 */

Definition at line 242 of file ssl.h.

#define SSL_ALERT_MSG_NO_CERT   41 /* 0x29 */

Definition at line 228 of file ssl.h.

#define SSL_ALERT_MSG_NO_RENEGOTIATION   100 /* 0x64 */

Definition at line 244 of file ssl.h.

#define SSL_ALERT_MSG_PROTOCOL_VERSION   70 /* 0x46 */

Definition at line 240 of file ssl.h.

#define SSL_ALERT_MSG_RECORD_OVERFLOW   22 /* 0x16 */

Definition at line 225 of file ssl.h.

#define SSL_ALERT_MSG_UNEXPECTED_MESSAGE   10 /* 0x0A */

Definition at line 222 of file ssl.h.

#define SSL_ALERT_MSG_UNKNOWN_CA   48 /* 0x30 */

Definition at line 235 of file ssl.h.

#define SSL_ALERT_MSG_UNRECOGNIZED_NAME   112 /* 0x70 */

Definition at line 246 of file ssl.h.

#define SSL_ALERT_MSG_UNSUPPORTED_CERT   43 /* 0x2B */

Definition at line 230 of file ssl.h.

#define SSL_ALERT_MSG_UNSUPPORTED_EXT   110 /* 0x6E */

Definition at line 245 of file ssl.h.

#define SSL_ALERT_MSG_USER_CANCELED   90 /* 0x5A */

Definition at line 243 of file ssl.h.

#define SSL_BUFFER_LEN   (SSL_MAX_CONTENT_LEN + SSL_COMPRESSION_ADD + 512)

Definition at line 150 of file ssl.h.

#define SSL_CERT_TYPE_RSA_SIGN   1

Definition at line 208 of file ssl.h.

#define SSL_COMPRESS_DEFLATE   1

Definition at line 108 of file ssl.h.

#define SSL_COMPRESS_NULL   0

Definition at line 107 of file ssl.h.

#define SSL_COMPRESSION_ADD   0

Definition at line 147 of file ssl.h.

#define SSL_EMPTY_RENEGOTIATION_INFO   0xFF

renegotiation info ext

Definition at line 190 of file ssl.h.

#define SSL_HASH_MD5   1

Definition at line 196 of file ssl.h.

#define SSL_HASH_NONE   0

Definition at line 195 of file ssl.h.

#define SSL_HASH_SHA1   2

Definition at line 197 of file ssl.h.

#define SSL_HASH_SHA224   3

Definition at line 198 of file ssl.h.

#define SSL_HASH_SHA256   4

Definition at line 199 of file ssl.h.

#define SSL_HASH_SHA384   5

Definition at line 200 of file ssl.h.

#define SSL_HASH_SHA512   6

Definition at line 201 of file ssl.h.

#define SSL_HS_CERTIFICATE   11

Definition at line 251 of file ssl.h.

#define SSL_HS_CERTIFICATE_REQUEST   13

Definition at line 253 of file ssl.h.

#define SSL_HS_CERTIFICATE_VERIFY   15

Definition at line 255 of file ssl.h.

#define SSL_HS_CLIENT_HELLO   1

Definition at line 249 of file ssl.h.

#define SSL_HS_CLIENT_KEY_EXCHANGE   16

Definition at line 256 of file ssl.h.

#define SSL_HS_FINISHED   20

Definition at line 257 of file ssl.h.

#define SSL_HS_HELLO_REQUEST   0

Definition at line 248 of file ssl.h.

#define SSL_HS_SERVER_HELLO   2

Definition at line 250 of file ssl.h.

#define SSL_HS_SERVER_HELLO_DONE   14

Definition at line 254 of file ssl.h.

#define SSL_HS_SERVER_KEY_EXCHANGE   12

Definition at line 252 of file ssl.h.

#define SSL_INITIAL_HANDSHAKE   0

Definition at line 114 of file ssl.h.

#define SSL_IS_CLIENT   0

Definition at line 105 of file ssl.h.

#define SSL_IS_SERVER   1

Definition at line 106 of file ssl.h.

#define SSL_LEGACY_ALLOW_RENEGOTIATION   1

Definition at line 124 of file ssl.h.

#define SSL_LEGACY_BREAK_HANDSHAKE   2

Definition at line 125 of file ssl.h.

#define SSL_LEGACY_NO_RENEGOTIATION   0

Definition at line 123 of file ssl.h.

#define SSL_LEGACY_RENEGOTIATION   0

Definition at line 117 of file ssl.h.

#define SSL_MAJOR_VERSION_3   3

Definition at line 99 of file ssl.h.

#define SSL_MAX_CONTENT_LEN   16384

Size of the input / output buffer.

Definition at line 135 of file ssl.h.

#define SSL_MINOR_VERSION_0   0

SSL v3.0

Definition at line 100 of file ssl.h.

#define SSL_MINOR_VERSION_1   1

TLS v1.0

Definition at line 101 of file ssl.h.

#define SSL_MINOR_VERSION_2   2

TLS v1.1

Definition at line 102 of file ssl.h.

#define SSL_MINOR_VERSION_3   3

TLS v1.2

Definition at line 103 of file ssl.h.

#define SSL_MSG_ALERT   21

Definition at line 214 of file ssl.h.

#define SSL_MSG_APPLICATION_DATA   23

Definition at line 216 of file ssl.h.

#define SSL_MSG_CHANGE_CIPHER_SPEC   20

Definition at line 213 of file ssl.h.

#define SSL_MSG_HANDSHAKE   22

Definition at line 215 of file ssl.h.

#define SSL_RENEGOTIATION   1

Definition at line 115 of file ssl.h.

#define SSL_RENEGOTIATION_DISABLED   0

Definition at line 120 of file ssl.h.

#define SSL_RENEGOTIATION_ENABLED   1

Definition at line 121 of file ssl.h.

#define SSL_SECURE_RENEGOTIATION   1

Definition at line 118 of file ssl.h.

#define SSL_SIG_RSA   1

Definition at line 203 of file ssl.h.

#define SSL_VERIFY_NONE   0

Definition at line 110 of file ssl.h.

#define SSL_VERIFY_OPTIONAL   1

Definition at line 111 of file ssl.h.

#define SSL_VERIFY_REQUIRED   2

Definition at line 112 of file ssl.h.

#define TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA   0x16

Definition at line 165 of file ssl.h.

#define TLS_DHE_RSA_WITH_AES_128_CBC_SHA   0x33

Definition at line 168 of file ssl.h.

#define TLS_DHE_RSA_WITH_AES_128_CBC_SHA256   0x67

TLS 1.2.

Definition at line 173 of file ssl.h.

#define TLS_DHE_RSA_WITH_AES_128_GCM_SHA256   0x9E

Definition at line 187 of file ssl.h.

#define TLS_DHE_RSA_WITH_AES_256_CBC_SHA   0x39

Definition at line 170 of file ssl.h.

#define TLS_DHE_RSA_WITH_AES_256_CBC_SHA256   0x6B

TLS 1.2.

Definition at line 174 of file ssl.h.

#define TLS_DHE_RSA_WITH_AES_256_GCM_SHA384   0x9F

Definition at line 188 of file ssl.h.

#define TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA   0x45

Definition at line 177 of file ssl.h.

#define TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA256   0xBE

TLS 1.2.

Definition at line 181 of file ssl.h.

#define TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA   0x88

Definition at line 179 of file ssl.h.

#define TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA256   0xC4

TLS 1.2.

Definition at line 183 of file ssl.h.

#define TLS_DHE_RSA_WITH_DES_CBC_SHA   0x15

Weak! Not in TLS 1.2.

Definition at line 159 of file ssl.h.

#define TLS_EXT_RENEGOTIATION_INFO   0xFF01

Definition at line 267 of file ssl.h.

#define TLS_EXT_SERVERNAME   0

Definition at line 262 of file ssl.h.

#define TLS_EXT_SERVERNAME_HOSTNAME   0

Definition at line 263 of file ssl.h.

#define TLS_EXT_SIG_ALG   13

Definition at line 265 of file ssl.h.

#define TLS_RSA_WITH_3DES_EDE_CBC_SHA   0x0A

Definition at line 164 of file ssl.h.

#define TLS_RSA_WITH_AES_128_CBC_SHA   0x2F

Definition at line 167 of file ssl.h.

#define TLS_RSA_WITH_AES_128_CBC_SHA256   0x3C

TLS 1.2.

Definition at line 171 of file ssl.h.

#define TLS_RSA_WITH_AES_128_GCM_SHA256   0x9C

Definition at line 185 of file ssl.h.

#define TLS_RSA_WITH_AES_256_CBC_SHA   0x35

Definition at line 169 of file ssl.h.

#define TLS_RSA_WITH_AES_256_CBC_SHA256   0x3D

TLS 1.2.

Definition at line 172 of file ssl.h.

#define TLS_RSA_WITH_AES_256_GCM_SHA384   0x9D

Definition at line 186 of file ssl.h.

#define TLS_RSA_WITH_CAMELLIA_128_CBC_SHA   0x41

Definition at line 176 of file ssl.h.

#define TLS_RSA_WITH_CAMELLIA_128_CBC_SHA256   0xBA

TLS 1.2.

Definition at line 180 of file ssl.h.

#define TLS_RSA_WITH_CAMELLIA_256_CBC_SHA   0x84

Definition at line 178 of file ssl.h.

#define TLS_RSA_WITH_CAMELLIA_256_CBC_SHA256   0xC0

TLS 1.2.

Definition at line 182 of file ssl.h.

#define TLS_RSA_WITH_DES_CBC_SHA   0x09

Weak! Not in TLS 1.2.

Definition at line 158 of file ssl.h.

#define TLS_RSA_WITH_NULL_MD5   0x01

Weak!

Definition at line 155 of file ssl.h.

#define TLS_RSA_WITH_NULL_SHA   0x02

Weak!

Definition at line 156 of file ssl.h.

#define TLS_RSA_WITH_NULL_SHA256   0x3B

Weak!

Definition at line 157 of file ssl.h.

#define TLS_RSA_WITH_RC4_128_MD5   0x04

Definition at line 161 of file ssl.h.

#define TLS_RSA_WITH_RC4_128_SHA   0x05

Definition at line 162 of file ssl.h.

Typedef Documentation

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

Definition at line 274 of file ssl.h.

typedef size_t(* rsa_key_len_func)(void *ctx)

Definition at line 283 of file ssl.h.

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

Definition at line 279 of file ssl.h.

typedef struct _ssl_context ssl_context

Definition at line 311 of file ssl.h.

Definition at line 313 of file ssl.h.

typedef struct _ssl_session ssl_session

Definition at line 310 of file ssl.h.

typedef struct _ssl_transform ssl_transform

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

Definition at line 288 of file ssl.h.

Function Documentation

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

Definition at line 1147 of file ssl.h.

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
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
int ssl_get_ciphersuite_min_version ( const int  ciphersuite_id)
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_cert* 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_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.

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)
static const int* ssl_list_ciphersuites ( void  )
inlinestatic

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

References ssl_default_ciphersuites.

void ssl_optimize_checksum ( ssl_context ssl,
int  ciphersuite 
)
int ssl_parse_certificate ( ssl_context ssl)
int ssl_parse_change_cipher_spec ( ssl_context ssl)
int ssl_parse_finished ( ssl_context ssl)
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)

Perform an SSL renegotiation on the running connection.

Parameters
sslSSL context
Returns
0 if succesful, 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
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_cert 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 (Default: ssl_default_ciphersuites) (Overrides all version specific lists)

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 for a specific version of the protocol.

(Default: ssl_default_ciphersuites) (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
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
void ssl_set_max_version ( ssl_context ssl,
int  major,
int  minor 
)

Set the maximum supported version sent from the client side.

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_MAJOR_VERSION_3, SSL_MINOR_VERSION_0)

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_own_cert ( ssl_context ssl,
x509_cert own_cert,
rsa_context rsa_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.

Parameters
sslSSL context
own_certown public certificate chain
rsa_keyown private RSA key
void ssl_set_own_cert_alt ( ssl_context ssl,
x509_cert 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 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_decrypt_funcalternate implementation of rsa_pkcs1_decrypt()
rsa_sign_funcalternate implementation of rsa_pkcs1_sign()
rsa_key_len_funcfunction returning length of RSA key in bytes
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
void 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.

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 when storing the session for use in this function.

Parameters
sslSSL context
sessionsession context
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_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
void ssl_set_verify ( ssl_context ssl,
int(*)(void *, x509_cert *, 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
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)

Variable Documentation

const int ssl_default_ciphersuites[]

Referenced by ssl_list_ciphersuites().