PolarSSL
Classes | Defines | Typedefs | Enumerations | Functions | Variables
polarssl/ssl.h File Reference
#include <time.h>
#include "polarssl/net.h"
#include "polarssl/dhm.h"
#include "polarssl/rsa.h"
#include "polarssl/md5.h"
#include "polarssl/sha1.h"
#include "polarssl/x509.h"

Go to the source code of this file.

Classes

struct  _ssl_session
struct  _ssl_context

Defines

#define POLARSSL_ERR_SSL_FEATURE_UNAVAILABLE   -0x1000
#define POLARSSL_ERR_SSL_BAD_INPUT_DATA   -0x1800
#define POLARSSL_ERR_SSL_INVALID_MAC   -0x2000
#define POLARSSL_ERR_SSL_INVALID_RECORD   -0x2800
#define POLARSSL_ERR_SSL_INVALID_MODULUS_SIZE   -0x3000
#define POLARSSL_ERR_SSL_UNKNOWN_CIPHER   -0x3800
#define POLARSSL_ERR_SSL_NO_CIPHER_CHOSEN   -0x4000
#define POLARSSL_ERR_SSL_NO_SESSION_FOUND   -0x4800
#define POLARSSL_ERR_SSL_NO_CLIENT_CERTIFICATE   -0x5000
#define POLARSSL_ERR_SSL_CERTIFICATE_TOO_LARGE   -0x5800
#define POLARSSL_ERR_SSL_CERTIFICATE_REQUIRED   -0x6000
#define POLARSSL_ERR_SSL_PRIVATE_KEY_REQUIRED   -0x6800
#define POLARSSL_ERR_SSL_CA_CHAIN_REQUIRED   -0x7000
#define POLARSSL_ERR_SSL_UNEXPECTED_MESSAGE   -0x7800
#define POLARSSL_ERR_SSL_FATAL_ALERT_MESSAGE   -0x8000
#define POLARSSL_ERR_SSL_PEER_VERIFY_FAILED   -0x8800
#define POLARSSL_ERR_SSL_PEER_CLOSE_NOTIFY   -0x9000
#define POLARSSL_ERR_SSL_BAD_HS_CLIENT_HELLO   -0x9800
#define POLARSSL_ERR_SSL_BAD_HS_SERVER_HELLO   -0xA000
#define POLARSSL_ERR_SSL_BAD_HS_CERTIFICATE   -0xA800
#define POLARSSL_ERR_SSL_BAD_HS_CERTIFICATE_REQUEST   -0xB000
#define POLARSSL_ERR_SSL_BAD_HS_SERVER_KEY_EXCHANGE   -0xB800
#define POLARSSL_ERR_SSL_BAD_HS_SERVER_HELLO_DONE   -0xC000
#define POLARSSL_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE   -0xC800
#define POLARSSL_ERR_SSL_BAD_HS_CERTIFICATE_VERIFY   -0xD000
#define POLARSSL_ERR_SSL_BAD_HS_CHANGE_CIPHER_SPEC   -0xD800
#define POLARSSL_ERR_SSL_BAD_HS_FINISHED   -0xE000
#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_IS_CLIENT   0
#define SSL_IS_SERVER   1
#define SSL_COMPRESS_NULL   0
#define SSL_VERIFY_NONE   0
#define SSL_VERIFY_OPTIONAL   1
#define SSL_VERIFY_REQUIRED   2
#define SSL_MAX_CONTENT_LEN   16384
#define SSL_BUFFER_LEN   (SSL_MAX_CONTENT_LEN + 512)
#define SSL_RSA_RC4_128_MD5   0x04
#define SSL_RSA_RC4_128_SHA   0x05
#define SSL_RSA_DES_168_SHA   0x0A
#define SSL_EDH_RSA_DES_168_SHA   0x16
#define SSL_RSA_AES_128_SHA   0x2F
#define SSL_EDH_RSA_AES_128_SHA   0x33
#define SSL_RSA_AES_256_SHA   0x35
#define SSL_EDH_RSA_AES_256_SHA   0x39
#define SSL_RSA_CAMELLIA_128_SHA   0x41
#define SSL_EDH_RSA_CAMELLIA_128_SHA   0x45
#define SSL_RSA_CAMELLIA_256_SHA   0x84
#define SSL_EDH_RSA_CAMELLIA_256_SHA   0x88
#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
#define SSL_ALERT_MSG_UNEXPECTED_MESSAGE   10
#define SSL_ALERT_MSG_BAD_RECORD_MAD   20
#define SSL_ALERT_MSG_DECRYPTION_FAILED   21
#define SSL_ALERT_MSG_RECORD_OVERFLOW   22
#define SSL_ALERT_MSG_DECOMPRESSION_FAILURE   30
#define SSL_ALERT_MSG_HANDSHAKE_FAILURE   40
#define SSL_ALERT_MSG_NO_CERT   41
#define SSL_ALERT_MSG_BAD_CERT   42
#define SSL_ALERT_MSG_UNSUPPORTED_CERT   43
#define SSL_ALERT_MSG_CERT_REVOKED   44
#define SSL_ALERT_MSG_CERT_EXPIRED   45
#define SSL_ALERT_MSG_CERT_UNKNOWN   46
#define SSL_ALERT_MSG_ILLEGAL_PARAMETER   47
#define SSL_ALERT_MSG_UNKNOWN_CA   48
#define SSL_ALERT_MSG_ACCESS_DENIED   49
#define SSL_ALERT_MSG_DECODE_ERROR   50
#define SSL_ALERT_MSG_DECRYPT_ERROR   51
#define SSL_ALERT_MSG_EXPORT_RESTRICTION   60
#define SSL_ALERT_MSG_PROTOCOL_VERSION   70
#define SSL_ALERT_MSG_INSUFFICIENT_SECURITY   71
#define SSL_ALERT_MSG_INTERNAL_ERROR   80
#define SSL_ALERT_MSG_USER_CANCELED   90
#define SSL_ALERT_MSG_NO_RENEGOTIATION   100
#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

Typedefs

typedef struct _ssl_session ssl_session
typedef struct _ssl_context ssl_context

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_OVER
}

Functions

int ssl_init (ssl_context *ssl)
 Initialize an SSL context.
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_rng (ssl_context *ssl, int(*f_rng)(void *), 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 *, int), void *p_recv, int(*f_send)(void *, unsigned char *, int), void *p_send)
 Set the underlying BIO read and write callbacks.
void ssl_set_scb (ssl_context *ssl, int(*s_get)(ssl_context *), int(*s_set)(ssl_context *))
 Set the session callbacks (server-side only)
void ssl_set_session (ssl_context *ssl, int resume, int timeout, ssl_session *session)
 Set the session resuming flag, timeout and data.
void ssl_set_ciphers (ssl_context *ssl, int *ciphers)
 Set the list of allowed ciphersuites.
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.
void ssl_set_own_cert (ssl_context *ssl, x509_cert *own_cert, rsa_context *rsa_key)
 Set own certificate and private key.
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)
int ssl_set_hostname (ssl_context *ssl, const char *hostname)
 Set hostname for ServerName TLS Extension.
int 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_cipher (const ssl_context *ssl)
 Return the name of the current cipher.
int ssl_handshake (ssl_context *ssl)
 Perform the SSL handshake.
int ssl_read (ssl_context *ssl, unsigned char *buf, int len)
 Read at most 'len' application data bytes.
int ssl_write (ssl_context *ssl, const unsigned char *buf, int len)
 Write exactly 'len' application data bytes.
int ssl_close_notify (ssl_context *ssl)
 Notify the peer that the connection is being closed.
void ssl_free (ssl_context *ssl)
 Free an SSL context.
int ssl_handshake_client (ssl_context *ssl)
int ssl_handshake_server (ssl_context *ssl)
int ssl_derive_keys (ssl_context *ssl)
void ssl_calc_verify (ssl_context *ssl, unsigned char hash[36])
int ssl_read_record (ssl_context *ssl)
int ssl_fetch_input (ssl_context *ssl, int 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)

Variables

int ssl_default_ciphers []

Detailed Description

Copyright (C) 2006-2010, 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.


Define Documentation

#define SSL_MINOR_VERSION_0   0

SSL v3.0

#define SSL_MINOR_VERSION_1   1

TLS v1.0

#define SSL_MINOR_VERSION_2   2

TLS v1.1


Function Documentation

int ssl_close_notify ( ssl_context ssl)

Notify the peer that the connection is being closed.

Parameters:
sslSSL context
void ssl_free ( ssl_context ssl)

Free an SSL context.

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

Return the name of the current cipher.

Parameters:
sslSSL context
Returns:
a string containing the cipher name
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
int ssl_handshake ( ssl_context ssl)

Perform the SSL handshake.

Parameters:
sslSSL context
Returns:
0 if successful, POLARSSL_ERR_NET_TRY_AGAIN, or a specific SSL error code.
int ssl_init ( ssl_context ssl)

Initialize an SSL context.

Parameters:
sslSSL context
Returns:
0 if successful, or 1 if memory allocation failed
int ssl_read ( ssl_context ssl,
unsigned char *  buf,
int  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, or a negative error code.
void ssl_set_authmode ( ssl_context ssl,
int  authmode 
)

Set the certificate verification mode.

Parameters:
sslSSL context
modecan 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.

void ssl_set_bio ( ssl_context ssl,
int(*)(void *, unsigned char *, int)  f_recv,
void *  p_recv,
int(*)(void *, unsigned char *, int)  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
ca_crltrusted CA CRLs
peer_cnexpected peer CommonName (or NULL)
Note:
TODO: add two more parameters: depth and crl
void ssl_set_ciphers ( ssl_context ssl,
int *  ciphers 
)

Set the list of allowed ciphersuites.

Parameters:
sslSSL context
ciphers0-terminated list of allowed ciphers
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)

Parameters:
sslSSL context
dhm_PDiffie-Hellman-Merkle modulus
dhm_GDiffie-Hellman-Merkle generator
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.

Parameters:
sslSSL context
hostnamethe server hostname
Returns:
0 if successful
void ssl_set_own_cert ( ssl_context ssl,
x509_cert own_cert,
rsa_context rsa_key 
)

Set own certificate and private key.

Parameters:
sslSSL context
own_certown public certificate
rsa_keyown private RSA key
void ssl_set_rng ( ssl_context ssl,
int(*)(void *)  f_rng,
void *  p_rng 
)

Set the random number generator callback.

Parameters:
sslSSL context
f_rngRNG function
p_rngRNG parameter
void ssl_set_scb ( ssl_context ssl,
int(*)(ssl_context *)  s_get,
int(*)(ssl_context *)  s_set 
)

Set the session callbacks (server-side only)

Parameters:
sslSSL context
s_getsession get callback
s_setsession set callback
void ssl_set_session ( ssl_context ssl,
int  resume,
int  timeout,
ssl_session session 
)

Set the session resuming flag, timeout and data.

Parameters:
sslSSL context
resumeif 0 (default), the session will not be resumed
timeoutsession timeout in seconds, or 0 (no timeout)
sessionsession context
int ssl_write ( ssl_context ssl,
const unsigned char *  buf,
int  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_TRY_AGAIN, it must be called later with the *same* arguments, until it returns a positive value.
 All Classes Files Functions Variables Defines