mbed TLS  Version 2.17.0
SSL/TLS Library for the Embedded Space
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
ssl_internal.h File Reference

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
 
struct  mbedtls_ssl_handshake_params.buffering
 
struct  mbedtls_ssl_hs_buffer.buffering.hs
 
struct  mbedtls_ssl_handshake_params.buffering.future_record
 

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)
 
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)
 
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])
 
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)
 
int mbedtls_ssl_session_copy (mbedtls_ssl_session *dst, const mbedtls_ssl_session *src)
 
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)
 

Description

Internal functions shared by the SSL modules.


Data Structure Documentation

struct mbedtls_ssl_sig_hash_set_t
Data Fields
mbedtls_md_type_t ecdsa
mbedtls_md_type_t rsa
struct mbedtls_ssl_transform
Data Fields
mbedtls_cipher_context_t cipher_ctx_dec

decryption context

mbedtls_cipher_context_t cipher_ctx_enc

encryption context

const mbedtls_ssl_ciphersuite_t * ciphersuite_info

Chosen cipersuite_info

size_t fixed_ivlen

Fixed part of IV (AEAD)

unsigned char iv_dec[16]

IV (decryption)

unsigned char iv_enc[16]

IV (encryption)

size_t ivlen

IV length

unsigned int keylen

symmetric key length (bytes)

size_t maclen

MAC length

mbedtls_md_context_t md_ctx_dec

MAC (decryption)

mbedtls_md_context_t md_ctx_enc

MAC (encryption)

size_t minlen

min. ciphertext length

struct mbedtls_ssl_key_cert
Data Fields
mbedtls_x509_crt * cert

cert

mbedtls_pk_context * key

private key

mbedtls_ssl_key_cert * next

next key/cert pair

struct mbedtls_ssl_flight_item
Data Fields
size_t len

length of p

mbedtls_ssl_flight_item * next

next handshake message(s)

unsigned char * p

message, including handshake headers

unsigned char type

type of the message: handshake or CCS

struct mbedtls_ssl_handshake_params.buffering
Data Fields
buffering future_record
buffering hs[MBEDTLS_SSL_MAX_BUFFERED_HS]
uint8_t seen_ccs

Indicates if a CCS message has been seen in the current flight.

size_t total_bytes_buffered

Cumulative size of heap allocated buffers used for message buffering.

struct mbedtls_ssl_handshake_params::mbedtls_ssl_hs_buffer.buffering.hs
Data Fields
unsigned char * data
size_t data_len
unsigned is_complete: 1
unsigned is_fragmented: 1
unsigned is_valid: 1
struct mbedtls_ssl_handshake_params.buffering.future_record
Data Fields
unsigned char * data
unsigned epoch
size_t len

Function Documentation

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_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_transform_free ( mbedtls_ssl_transform transform)

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

Parameters
transformSSL transform context