PolarSSL is now part of ARM Official announcement and rebranded as mbed TLS.

API Documentation (Doxygen generated)

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

ssl_internal.h File Reference

Internal functions shared by the SSL modules. More...

#include "ssl.h"
#include "cipher.h"
#include "md5.h"
#include "sha1.h"
#include "sha256.h"
#include "sha512.h"
Include dependency graph for ssl_internal.h:

Go to the source code of this file.

Data Structures

struct  mbedtls_ssl_sig_hash_set_t
 
struct  mbedtls_ssl_handshake_params
 
struct  mbedtls_ssl_transform
 
struct  mbedtls_ssl_key_cert
 
struct  mbedtls_ssl_flight_item
 

Macros

#define MBEDTLS_SSL_MIN_MAJOR_VERSION   MBEDTLS_SSL_MAJOR_VERSION_3
 
#define MBEDTLS_SSL_MIN_MINOR_VERSION   MBEDTLS_SSL_MINOR_VERSION_1
 
#define MBEDTLS_SSL_MIN_VALID_MINOR_VERSION   MBEDTLS_SSL_MINOR_VERSION_1
 
#define MBEDTLS_SSL_MIN_VALID_MAJOR_VERSION   MBEDTLS_SSL_MAJOR_VERSION_3
 
#define MBEDTLS_SSL_MAX_MAJOR_VERSION   MBEDTLS_SSL_MAJOR_VERSION_3
 
#define MBEDTLS_SSL_MAX_MINOR_VERSION   MBEDTLS_SSL_MINOR_VERSION_3
 
#define MBEDTLS_SSL_INITIAL_HANDSHAKE   0
 
#define MBEDTLS_SSL_RENEGOTIATION_IN_PROGRESS   1 /* In progress */
 
#define MBEDTLS_SSL_RENEGOTIATION_DONE   2 /* Done or aborted */
 
#define MBEDTLS_SSL_RENEGOTIATION_PENDING   3 /* Requested (server only) */
 
#define MBEDTLS_SSL_RETRANS_PREPARING   0
 
#define MBEDTLS_SSL_RETRANS_SENDING   1
 
#define MBEDTLS_SSL_RETRANS_WAITING   2
 
#define MBEDTLS_SSL_RETRANS_FINISHED   3
 
#define MBEDTLS_SSL_COMPRESSION_ADD   0
 
#define MBEDTLS_SSL_MAC_ADD   48 /* SHA-384 used for HMAC */
 
#define MBEDTLS_SSL_PADDING_ADD   256
 
#define MBEDTLS_SSL_PAYLOAD_OVERHEAD
 
#define MBEDTLS_SSL_IN_PAYLOAD_LEN
 
#define MBEDTLS_SSL_OUT_PAYLOAD_LEN
 
#define MBEDTLS_SSL_MAX_BUFFERED_HS   4
 
#define MBEDTLS_TLS_EXT_ADV_CONTENT_LEN
 
#define MBEDTLS_SSL_HEADER_LEN   13
 
#define MBEDTLS_SSL_IN_BUFFER_LEN   ( ( MBEDTLS_SSL_HEADER_LEN ) + ( MBEDTLS_SSL_IN_PAYLOAD_LEN ) )
 
#define MBEDTLS_SSL_OUT_BUFFER_LEN   ( ( MBEDTLS_SSL_HEADER_LEN ) + ( MBEDTLS_SSL_OUT_PAYLOAD_LEN ) )
 
#define MBEDTLS_TLS_EXT_SUPPORTED_POINT_FORMATS_PRESENT   (1 << 0)
 
#define MBEDTLS_TLS_EXT_ECJPAKE_KKPP_OK   (1 << 1)
 

Typedefs

typedef struct
mbedtls_ssl_hs_buffer 
mbedtls_ssl_hs_buffer
 

Functions

mbedtls_md_type_t mbedtls_ssl_sig_hash_set_find (mbedtls_ssl_sig_hash_set_t *set, mbedtls_pk_type_t sig_alg)
 
void mbedtls_ssl_sig_hash_set_add (mbedtls_ssl_sig_hash_set_t *set, mbedtls_pk_type_t sig_alg, mbedtls_md_type_t md_alg)
 
void mbedtls_ssl_sig_hash_set_const_hash (mbedtls_ssl_sig_hash_set_t *set, mbedtls_md_type_t md_alg)
 
static void mbedtls_ssl_sig_hash_set_init (mbedtls_ssl_sig_hash_set_t *set)
 
void mbedtls_ssl_transform_free (mbedtls_ssl_transform *transform)
 Free referenced items in an SSL transform context and clear memory. More...
 
void mbedtls_ssl_handshake_free (mbedtls_ssl_context *ssl)
 Free referenced items in an SSL handshake context and clear memory. More...
 
int mbedtls_ssl_handshake_client_step (mbedtls_ssl_context *ssl)
 
int mbedtls_ssl_handshake_server_step (mbedtls_ssl_context *ssl)
 
void mbedtls_ssl_handshake_wrapup (mbedtls_ssl_context *ssl)
 
int mbedtls_ssl_send_fatal_handshake_failure (mbedtls_ssl_context *ssl)
 
void mbedtls_ssl_reset_checksum (mbedtls_ssl_context *ssl)
 
int mbedtls_ssl_derive_keys (mbedtls_ssl_context *ssl)
 
int mbedtls_ssl_handle_message_type (mbedtls_ssl_context *ssl)
 
int mbedtls_ssl_prepare_handshake_record (mbedtls_ssl_context *ssl)
 
void mbedtls_ssl_update_handshake_status (mbedtls_ssl_context *ssl)
 
int mbedtls_ssl_read_record (mbedtls_ssl_context *ssl, unsigned update_hs_digest)
 Update record layer. More...
 
int mbedtls_ssl_fetch_input (mbedtls_ssl_context *ssl, size_t nb_want)
 
int mbedtls_ssl_write_handshake_msg (mbedtls_ssl_context *ssl)
 
int mbedtls_ssl_write_record (mbedtls_ssl_context *ssl, uint8_t force_flush)
 
int mbedtls_ssl_flush_output (mbedtls_ssl_context *ssl)
 
int mbedtls_ssl_parse_certificate (mbedtls_ssl_context *ssl)
 
int mbedtls_ssl_write_certificate (mbedtls_ssl_context *ssl)
 
int mbedtls_ssl_parse_change_cipher_spec (mbedtls_ssl_context *ssl)
 
int mbedtls_ssl_write_change_cipher_spec (mbedtls_ssl_context *ssl)
 
int mbedtls_ssl_parse_finished (mbedtls_ssl_context *ssl)
 
int mbedtls_ssl_write_finished (mbedtls_ssl_context *ssl)
 
void mbedtls_ssl_optimize_checksum (mbedtls_ssl_context *ssl, const mbedtls_ssl_ciphersuite_t *ciphersuite_info)
 
int mbedtls_ssl_psk_derive_premaster (mbedtls_ssl_context *ssl, mbedtls_key_exchange_type_t key_ex)
 
unsigned char mbedtls_ssl_sig_from_pk (mbedtls_pk_context *pk)
 
unsigned char mbedtls_ssl_sig_from_pk_alg (mbedtls_pk_type_t type)
 
mbedtls_pk_type_t mbedtls_ssl_pk_alg_from_sig (unsigned char sig)
 
mbedtls_md_type_t mbedtls_ssl_md_alg_from_hash (unsigned char hash)
 
unsigned char mbedtls_ssl_hash_from_md_alg (int md)
 
int mbedtls_ssl_set_calc_verify_md (mbedtls_ssl_context *ssl, int md)
 
int mbedtls_ssl_check_curve (const mbedtls_ssl_context *ssl, mbedtls_ecp_group_id grp_id)
 
int mbedtls_ssl_check_sig_hash (const mbedtls_ssl_context *ssl, mbedtls_md_type_t md)
 
static mbedtls_pk_contextmbedtls_ssl_own_key (mbedtls_ssl_context *ssl)
 
static mbedtls_x509_crtmbedtls_ssl_own_cert (mbedtls_ssl_context *ssl)
 
int mbedtls_ssl_check_cert_usage (const mbedtls_x509_crt *cert, const mbedtls_ssl_ciphersuite_t *ciphersuite, int cert_endpoint, uint32_t *flags)
 
void mbedtls_ssl_write_version (int major, int minor, int transport, unsigned char ver[2])
 
void mbedtls_ssl_read_version (int *major, int *minor, int transport, const unsigned char ver[2])
 
static size_t mbedtls_ssl_hdr_len (const mbedtls_ssl_context *ssl)
 
static size_t mbedtls_ssl_hs_hdr_len (const mbedtls_ssl_context *ssl)
 
void mbedtls_ssl_send_flight_completed (mbedtls_ssl_context *ssl)
 
void mbedtls_ssl_recv_flight_completed (mbedtls_ssl_context *ssl)
 
int mbedtls_ssl_resend (mbedtls_ssl_context *ssl)
 
int mbedtls_ssl_flight_transmit (mbedtls_ssl_context *ssl)
 
int mbedtls_ssl_dtls_replay_check (mbedtls_ssl_context *ssl)
 
void mbedtls_ssl_dtls_replay_update (mbedtls_ssl_context *ssl)
 
static int mbedtls_ssl_safer_memcmp (const void *a, const void *b, size_t n)
 
int mbedtls_ssl_get_key_exchange_md_ssl_tls (mbedtls_ssl_context *ssl, unsigned char *output, unsigned char *data, size_t data_len)
 
int mbedtls_ssl_get_key_exchange_md_tls1_2 (mbedtls_ssl_context *ssl, unsigned char *hash, size_t *hashlen, unsigned char *data, size_t data_len, mbedtls_md_type_t md_alg)
 

Detailed Description

Internal functions shared by the SSL modules.

Definition in file ssl_internal.h.

Macro Definition Documentation

#define MBEDTLS_SSL_COMPRESSION_ADD   0

Definition at line 123 of file ssl_internal.h.

#define MBEDTLS_SSL_HEADER_LEN   13

Definition at line 200 of file ssl_internal.h.

#define MBEDTLS_SSL_IN_BUFFER_LEN   ( ( MBEDTLS_SSL_HEADER_LEN ) + ( MBEDTLS_SSL_IN_PAYLOAD_LEN ) )

Definition at line 202 of file ssl_internal.h.

#define MBEDTLS_SSL_IN_PAYLOAD_LEN
Value:
#define MBEDTLS_SSL_PAYLOAD_OVERHEAD
Definition: ssl_internal.h:146
#define MBEDTLS_SSL_IN_CONTENT_LEN
Maximum incoming fragment length in bytes.
Definition: ssl.h:239

Definition at line 152 of file ssl_internal.h.

#define MBEDTLS_SSL_INITIAL_HANDSHAKE   0

Definition at line 96 of file ssl_internal.h.

#define MBEDTLS_SSL_MAC_ADD   48 /* SHA-384 used for HMAC */

Definition at line 129 of file ssl_internal.h.

#define MBEDTLS_SSL_MAX_BUFFERED_HS   4

Definition at line 159 of file ssl_internal.h.

#define MBEDTLS_SSL_MAX_MAJOR_VERSION   MBEDTLS_SSL_MAJOR_VERSION_3

Definition at line 78 of file ssl_internal.h.

#define MBEDTLS_SSL_MAX_MINOR_VERSION   MBEDTLS_SSL_MINOR_VERSION_3

Definition at line 81 of file ssl_internal.h.

#define MBEDTLS_SSL_MIN_MAJOR_VERSION   MBEDTLS_SSL_MAJOR_VERSION_3

Definition at line 56 of file ssl_internal.h.

#define MBEDTLS_SSL_MIN_MINOR_VERSION   MBEDTLS_SSL_MINOR_VERSION_1

Definition at line 62 of file ssl_internal.h.

#define MBEDTLS_SSL_MIN_VALID_MAJOR_VERSION   MBEDTLS_SSL_MAJOR_VERSION_3

Definition at line 75 of file ssl_internal.h.

#define MBEDTLS_SSL_MIN_VALID_MINOR_VERSION   MBEDTLS_SSL_MINOR_VERSION_1

Definition at line 74 of file ssl_internal.h.

#define MBEDTLS_SSL_OUT_BUFFER_LEN   ( ( MBEDTLS_SSL_HEADER_LEN ) + ( MBEDTLS_SSL_OUT_PAYLOAD_LEN ) )

Definition at line 205 of file ssl_internal.h.

#define MBEDTLS_SSL_OUT_PAYLOAD_LEN
Value:
#define MBEDTLS_SSL_PAYLOAD_OVERHEAD
Definition: ssl_internal.h:146
#define MBEDTLS_SSL_OUT_CONTENT_LEN
Maximum outgoing fragment length in bytes.
Definition: ssl.h:243

Definition at line 155 of file ssl_internal.h.

#define MBEDTLS_SSL_PADDING_ADD   256

Definition at line 141 of file ssl_internal.h.

#define MBEDTLS_SSL_PAYLOAD_OVERHEAD
Value:
)
#define MBEDTLS_SSL_COMPRESSION_ADD
Definition: ssl_internal.h:123
#define MBEDTLS_MAX_IV_LENGTH
Maximum length of any IV, in Bytes.
Definition: cipher.h:221
#define MBEDTLS_SSL_MAC_ADD
Definition: ssl_internal.h:129
#define MBEDTLS_SSL_PADDING_ADD
Definition: ssl_internal.h:141

Definition at line 146 of file ssl_internal.h.

#define MBEDTLS_SSL_RENEGOTIATION_DONE   2 /* Done or aborted */

Definition at line 98 of file ssl_internal.h.

#define MBEDTLS_SSL_RENEGOTIATION_IN_PROGRESS   1 /* In progress */

Definition at line 97 of file ssl_internal.h.

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

Definition at line 99 of file ssl_internal.h.

#define MBEDTLS_SSL_RETRANS_FINISHED   3

Definition at line 112 of file ssl_internal.h.

#define MBEDTLS_SSL_RETRANS_PREPARING   0

Definition at line 109 of file ssl_internal.h.

#define MBEDTLS_SSL_RETRANS_SENDING   1

Definition at line 110 of file ssl_internal.h.

#define MBEDTLS_SSL_RETRANS_WAITING   2

Definition at line 111 of file ssl_internal.h.

#define MBEDTLS_TLS_EXT_ADV_CONTENT_LEN
Value:
( \
)
#define MBEDTLS_SSL_OUT_CONTENT_LEN
Maximum outgoing fragment length in bytes.
Definition: ssl.h:243
#define MBEDTLS_SSL_IN_CONTENT_LEN
Maximum incoming fragment length in bytes.
Definition: ssl.h:239

Definition at line 165 of file ssl_internal.h.

#define MBEDTLS_TLS_EXT_ECJPAKE_KKPP_OK   (1 << 1)

Definition at line 223 of file ssl_internal.h.

#define MBEDTLS_TLS_EXT_SUPPORTED_POINT_FORMATS_PRESENT   (1 << 0)

Definition at line 222 of file ssl_internal.h.

Typedef Documentation

Definition at line 397 of file ssl_internal.h.

Function Documentation

int mbedtls_ssl_check_cert_usage ( const mbedtls_x509_crt cert,
const mbedtls_ssl_ciphersuite_t ciphersuite,
int  cert_endpoint,
uint32_t *  flags 
)
int mbedtls_ssl_check_curve ( const mbedtls_ssl_context ssl,
mbedtls_ecp_group_id  grp_id 
)
int mbedtls_ssl_check_sig_hash ( const mbedtls_ssl_context ssl,
mbedtls_md_type_t  md 
)
int mbedtls_ssl_derive_keys ( mbedtls_ssl_context ssl)
int mbedtls_ssl_dtls_replay_check ( mbedtls_ssl_context ssl)
void mbedtls_ssl_dtls_replay_update ( mbedtls_ssl_context ssl)
int mbedtls_ssl_fetch_input ( mbedtls_ssl_context ssl,
size_t  nb_want 
)
int mbedtls_ssl_flight_transmit ( mbedtls_ssl_context ssl)
int mbedtls_ssl_flush_output ( mbedtls_ssl_context ssl)
int mbedtls_ssl_get_key_exchange_md_ssl_tls ( mbedtls_ssl_context ssl,
unsigned char *  output,
unsigned char *  data,
size_t  data_len 
)
int mbedtls_ssl_get_key_exchange_md_tls1_2 ( mbedtls_ssl_context ssl,
unsigned char *  hash,
size_t *  hashlen,
unsigned char *  data,
size_t  data_len,
mbedtls_md_type_t  md_alg 
)
int mbedtls_ssl_handle_message_type ( mbedtls_ssl_context ssl)
int mbedtls_ssl_handshake_client_step ( mbedtls_ssl_context ssl)
void mbedtls_ssl_handshake_free ( mbedtls_ssl_context ssl)

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

Parameters
sslSSL context
int mbedtls_ssl_handshake_server_step ( mbedtls_ssl_context ssl)
void mbedtls_ssl_handshake_wrapup ( mbedtls_ssl_context ssl)
unsigned char mbedtls_ssl_hash_from_md_alg ( int  md)
static size_t mbedtls_ssl_hdr_len ( const mbedtls_ssl_context ssl)
inlinestatic
static size_t mbedtls_ssl_hs_hdr_len ( const mbedtls_ssl_context ssl)
inlinestatic
mbedtls_md_type_t mbedtls_ssl_md_alg_from_hash ( unsigned char  hash)
void mbedtls_ssl_optimize_checksum ( mbedtls_ssl_context ssl,
const mbedtls_ssl_ciphersuite_t ciphersuite_info 
)
int mbedtls_ssl_parse_certificate ( mbedtls_ssl_context ssl)
int mbedtls_ssl_parse_change_cipher_spec ( mbedtls_ssl_context ssl)
int mbedtls_ssl_parse_finished ( mbedtls_ssl_context ssl)
mbedtls_pk_type_t mbedtls_ssl_pk_alg_from_sig ( unsigned char  sig)
int mbedtls_ssl_prepare_handshake_record ( mbedtls_ssl_context ssl)
int mbedtls_ssl_psk_derive_premaster ( mbedtls_ssl_context ssl,
mbedtls_key_exchange_type_t  key_ex 
)
int mbedtls_ssl_read_record ( mbedtls_ssl_context ssl,
unsigned  update_hs_digest 
)

Update record layer.

This function roughly separates the implementation of the logic of (D)TLS from the implementation of the secure transport.

Parameters
sslThe SSL context to use.
update_hs_digestThis indicates if the handshake digest should be automatically updated in case a handshake message is found.
Returns
0 or non-zero error code.
Note
A clarification on what is called 'record layer' here is in order, as many sensible definitions are possible:

The record layer takes as input an untrusted underlying transport (stream or datagram) and transforms it into a serially multiplexed, secure transport, which conceptually provides the following:

(1) Three datagram based, content-agnostic transports for handshake, alert and CCS messages. (2) One stream- or datagram-based transport for application data. (3) Functionality for changing the underlying transform securing the contents.

The interface to this functionality is given as follows:

a Updating [Currently implemented by mbedtls_ssl_read_record]

Check if and on which of the four 'ports' data is pending: Nothing, a controlling datagram of type (1), or application data (2). In any case data is present, internal buffers provide access to the data for the user to process it. Consumption of type (1) datagrams is done automatically on the next update, invalidating that the internal buffers for previous datagrams, while consumption of application data (2) is user-controlled.

b Reading of application data [Currently manual adaption of ssl->in_offt pointer]

As mentioned in the last paragraph, consumption of data is different from the automatic consumption of control datagrams (1) because application data is treated as a stream.

c Tracking availability of application data [Currently manually through decreasing ssl->in_msglen]

For efficiency and to retain datagram semantics for application data in case of DTLS, the record layer provides functionality for checking how much application data is still available in the internal buffer.

d Changing the transformation securing the communication.

Given an opaque implementation of the record layer in the above sense, it should be possible to implement the logic of (D)TLS on top of it without the need to know anything about the record layer's internals. This is done e.g. in all the handshake handling functions, and in the application data reading function mbedtls_ssl_read.

Note
The above tries to give a conceptual picture of the record layer, but the current implementation deviates from it in some places. For example, our implementation of the update functionality through mbedtls_ssl_read_record discards datagrams depending on the current state, which wouldn't fall under the record layer's responsibility following the above definition.
void mbedtls_ssl_read_version ( int *  major,
int *  minor,
int  transport,
const unsigned char  ver[2] 
)
void mbedtls_ssl_recv_flight_completed ( mbedtls_ssl_context ssl)
int mbedtls_ssl_resend ( mbedtls_ssl_context ssl)
void mbedtls_ssl_reset_checksum ( mbedtls_ssl_context ssl)
static int mbedtls_ssl_safer_memcmp ( const void *  a,
const void *  b,
size_t  n 
)
inlinestatic

Definition at line 717 of file ssl_internal.h.

int mbedtls_ssl_send_fatal_handshake_failure ( mbedtls_ssl_context ssl)
void mbedtls_ssl_send_flight_completed ( mbedtls_ssl_context ssl)
int mbedtls_ssl_set_calc_verify_md ( mbedtls_ssl_context ssl,
int  md 
)
unsigned char mbedtls_ssl_sig_from_pk ( mbedtls_pk_context pk)
unsigned char mbedtls_ssl_sig_from_pk_alg ( mbedtls_pk_type_t  type)
void mbedtls_ssl_sig_hash_set_add ( mbedtls_ssl_sig_hash_set_t set,
mbedtls_pk_type_t  sig_alg,
mbedtls_md_type_t  md_alg 
)
void mbedtls_ssl_sig_hash_set_const_hash ( mbedtls_ssl_sig_hash_set_t set,
mbedtls_md_type_t  md_alg 
)
mbedtls_md_type_t mbedtls_ssl_sig_hash_set_find ( mbedtls_ssl_sig_hash_set_t set,
mbedtls_pk_type_t  sig_alg 
)
static void mbedtls_ssl_sig_hash_set_init ( mbedtls_ssl_sig_hash_set_t set)
inlinestatic

Definition at line 480 of file ssl_internal.h.

References MBEDTLS_MD_NONE, and mbedtls_ssl_sig_hash_set_const_hash().

void mbedtls_ssl_transform_free ( mbedtls_ssl_transform transform)

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

Parameters
transformSSL transform context
void mbedtls_ssl_update_handshake_status ( mbedtls_ssl_context ssl)
int mbedtls_ssl_write_certificate ( mbedtls_ssl_context ssl)
int mbedtls_ssl_write_change_cipher_spec ( mbedtls_ssl_context ssl)
int mbedtls_ssl_write_finished ( mbedtls_ssl_context ssl)
int mbedtls_ssl_write_handshake_msg ( mbedtls_ssl_context ssl)
int mbedtls_ssl_write_record ( mbedtls_ssl_context ssl,
uint8_t  force_flush 
)
void mbedtls_ssl_write_version ( int  major,
int  minor,
int  transport,
unsigned char  ver[2] 
)