ssl_internal.h File Reference

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

#include "ssl.h"
#include "cipher.h"
#include "sha256.h"

Include dependency graph for ssl_internal.h:

Go to the source code of this file.

Classes
struct	mbedtls_ssl_handshake_params
struct	mbedtls_ssl_transform

Macros
#define	MBEDTLS_SSL_MIN_MAJOR_VERSION   MBEDTLS_SSL_MAJOR_VERSION_3
#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_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   16
#define	MBEDTLS_SSL_PADDING_ADD   0
#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
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)
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)
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])

Detailed Description

Internal functions shared by the SSL modules.

Macro Definition Documentation

MBEDTLS_SSL_COMPRESSION_ADD

#define MBEDTLS_SSL_COMPRESSION_ADD   0

MBEDTLS_SSL_HEADER_LEN

#define MBEDTLS_SSL_HEADER_LEN   13

MBEDTLS_SSL_IN_BUFFER_LEN

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

MBEDTLS_SSL_IN_PAYLOAD_LEN

#define MBEDTLS_SSL_IN_PAYLOAD_LEN

Value:

( MBEDTLS_SSL_PAYLOAD_OVERHEAD + \
                                     ( MBEDTLS_SSL_IN_CONTENT_LEN ) )

MBEDTLS_SSL_INITIAL_HANDSHAKE

#define MBEDTLS_SSL_INITIAL_HANDSHAKE   0

MBEDTLS_SSL_MAC_ADD

#define MBEDTLS_SSL_MAC_ADD   16

MBEDTLS_SSL_MAX_BUFFERED_HS

#define MBEDTLS_SSL_MAX_BUFFERED_HS   4

MBEDTLS_SSL_MAX_MAJOR_VERSION

#define MBEDTLS_SSL_MAX_MAJOR_VERSION   MBEDTLS_SSL_MAJOR_VERSION_3

MBEDTLS_SSL_MIN_MAJOR_VERSION

#define MBEDTLS_SSL_MIN_MAJOR_VERSION   MBEDTLS_SSL_MAJOR_VERSION_3

MBEDTLS_SSL_MIN_VALID_MAJOR_VERSION

#define MBEDTLS_SSL_MIN_VALID_MAJOR_VERSION   MBEDTLS_SSL_MAJOR_VERSION_3

MBEDTLS_SSL_MIN_VALID_MINOR_VERSION

#define MBEDTLS_SSL_MIN_VALID_MINOR_VERSION   MBEDTLS_SSL_MINOR_VERSION_1

MBEDTLS_SSL_OUT_BUFFER_LEN

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

MBEDTLS_SSL_OUT_PAYLOAD_LEN

#define MBEDTLS_SSL_OUT_PAYLOAD_LEN

Value:

( MBEDTLS_SSL_PAYLOAD_OVERHEAD + \
                                      ( MBEDTLS_SSL_OUT_CONTENT_LEN ) )

MBEDTLS_SSL_PADDING_ADD

#define MBEDTLS_SSL_PADDING_ADD   0

MBEDTLS_SSL_PAYLOAD_OVERHEAD

#define MBEDTLS_SSL_PAYLOAD_OVERHEAD

Value:

( MBEDTLS_SSL_COMPRESSION_ADD +    \
                                       MBEDTLS_MAX_IV_LENGTH +          \
                                       MBEDTLS_SSL_MAC_ADD +            \
                                       MBEDTLS_SSL_PADDING_ADD          \
                                       )

MBEDTLS_SSL_RENEGOTIATION_DONE

#define MBEDTLS_SSL_RENEGOTIATION_DONE   2 /* Done or aborted */

MBEDTLS_SSL_RENEGOTIATION_IN_PROGRESS

#define MBEDTLS_SSL_RENEGOTIATION_IN_PROGRESS   1 /* In progress */

MBEDTLS_SSL_RENEGOTIATION_PENDING

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

MBEDTLS_SSL_RETRANS_FINISHED

#define MBEDTLS_SSL_RETRANS_FINISHED   3

MBEDTLS_SSL_RETRANS_PREPARING

#define MBEDTLS_SSL_RETRANS_PREPARING   0

MBEDTLS_SSL_RETRANS_SENDING

#define MBEDTLS_SSL_RETRANS_SENDING   1

MBEDTLS_SSL_RETRANS_WAITING

#define MBEDTLS_SSL_RETRANS_WAITING   2

MBEDTLS_TLS_EXT_ADV_CONTENT_LEN

#define MBEDTLS_TLS_EXT_ADV_CONTENT_LEN

Value:

(                            \
        (MBEDTLS_SSL_IN_CONTENT_LEN > MBEDTLS_SSL_OUT_CONTENT_LEN)   \
        ? ( MBEDTLS_SSL_OUT_CONTENT_LEN )                            \
        : ( MBEDTLS_SSL_IN_CONTENT_LEN )                             \
        )

MBEDTLS_TLS_EXT_ECJPAKE_KKPP_OK

#define MBEDTLS_TLS_EXT_ECJPAKE_KKPP_OK   (1 << 1)

MBEDTLS_TLS_EXT_SUPPORTED_POINT_FORMATS_PRESENT

#define MBEDTLS_TLS_EXT_SUPPORTED_POINT_FORMATS_PRESENT   (1 << 0)

Typedef Documentation

mbedtls_ssl_hs_buffer

typedef struct mbedtls_ssl_hs_buffer mbedtls_ssl_hs_buffer

Function Documentation

mbedtls_ssl_derive_keys()

int mbedtls_ssl_derive_keys

(

mbedtls_ssl_context *

ssl

)

mbedtls_ssl_fetch_input()

int mbedtls_ssl_fetch_input	(	mbedtls_ssl_context *	ssl,
		size_t	nb_want
	)

mbedtls_ssl_flush_output()

int mbedtls_ssl_flush_output

(

mbedtls_ssl_context *

ssl

)

mbedtls_ssl_handle_message_type()

int mbedtls_ssl_handle_message_type

(

mbedtls_ssl_context *

ssl

)

mbedtls_ssl_handshake_client_step()

int mbedtls_ssl_handshake_client_step

(

mbedtls_ssl_context *

ssl

)

mbedtls_ssl_handshake_free()

void mbedtls_ssl_handshake_free

(

mbedtls_ssl_context *

ssl

)

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

Parameters

ssl	SSL context

mbedtls_ssl_handshake_server_step()

int mbedtls_ssl_handshake_server_step

(

mbedtls_ssl_context *

ssl

)

mbedtls_ssl_handshake_wrapup()

void mbedtls_ssl_handshake_wrapup

(

mbedtls_ssl_context *

ssl

)

mbedtls_ssl_hash_from_md_alg()

unsigned char mbedtls_ssl_hash_from_md_alg

(

int

md

)

mbedtls_ssl_md_alg_from_hash()

mbedtls_md_type_t mbedtls_ssl_md_alg_from_hash

(

unsigned char

hash

)

mbedtls_ssl_optimize_checksum()

void mbedtls_ssl_optimize_checksum	(	mbedtls_ssl_context *	ssl,
		const mbedtls_ssl_ciphersuite_t *	ciphersuite_info
	)

mbedtls_ssl_parse_certificate()

int mbedtls_ssl_parse_certificate

(

mbedtls_ssl_context *

ssl

)

mbedtls_ssl_parse_change_cipher_spec()

int mbedtls_ssl_parse_change_cipher_spec

(

mbedtls_ssl_context *

ssl

)

mbedtls_ssl_parse_finished()

int mbedtls_ssl_parse_finished

(

mbedtls_ssl_context *

ssl

)

mbedtls_ssl_prepare_handshake_record()

int mbedtls_ssl_prepare_handshake_record

(

mbedtls_ssl_context *

ssl

)

mbedtls_ssl_read_record()

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

ssl	The SSL context to use.
update_hs_digest	This 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.

mbedtls_ssl_read_version()

void mbedtls_ssl_read_version	(	int *	major,
		int *	minor,
		int	transport,
		const unsigned char	ver[2]
	)

mbedtls_ssl_reset_checksum()

void mbedtls_ssl_reset_checksum

(

mbedtls_ssl_context *

ssl

)

mbedtls_ssl_send_fatal_handshake_failure()

int mbedtls_ssl_send_fatal_handshake_failure

(

mbedtls_ssl_context *

ssl

)

mbedtls_ssl_set_calc_verify_md()

int mbedtls_ssl_set_calc_verify_md	(	mbedtls_ssl_context *	ssl,
		int	md
	)

mbedtls_ssl_transform_free()

void mbedtls_ssl_transform_free

(

mbedtls_ssl_transform *

transform

)

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

Parameters

transform

SSL transform context

mbedtls_ssl_update_handshake_status()

void mbedtls_ssl_update_handshake_status

(

mbedtls_ssl_context *

ssl

)

mbedtls_ssl_write_certificate()

int mbedtls_ssl_write_certificate

(

mbedtls_ssl_context *

ssl

)

mbedtls_ssl_write_change_cipher_spec()

int mbedtls_ssl_write_change_cipher_spec

(

mbedtls_ssl_context *

ssl

)

mbedtls_ssl_write_finished()

int mbedtls_ssl_write_finished

(

mbedtls_ssl_context *

ssl

)

mbedtls_ssl_write_handshake_msg()

int mbedtls_ssl_write_handshake_msg

(

mbedtls_ssl_context *

ssl

)

mbedtls_ssl_write_record()

int mbedtls_ssl_write_record	(	mbedtls_ssl_context *	ssl,
		uint8_t	force_flush
	)

mbedtls_ssl_write_version()

void mbedtls_ssl_write_version	(	int	major,
		int	minor,
		int	transport,
		unsigned char	ver[2]
	)