ssl_internal.h File Reference

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

Functions
void	mbedtls_ssl_handshake_free (mbedtls_ssl_context *ssl)
	Free referenced items in an SSL handshake context and clear memory.
int	mbedtls_ssl_read_record (mbedtls_ssl_context *ssl, unsigned update_hs_digest)
	Update record layer.
void	mbedtls_ssl_transform_free (mbedtls_ssl_transform *transform)
	Free referenced items in an SSL transform context and clear memory.

Detailed Description

Internal functions shared by the SSL modules.

Function Documentation

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_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_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