ssl_internal.h File Reference

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

#include "mbedtls/config.h"
#include "mbedtls/ssl.h"
#include "mbedtls/cipher.h"

Go to the source code of this file.

Data Structures
struct	mbedtls_ssl_key_set
	The data structure holding the cryptographic material (key and IV) used for record protection in TLS 1.3. More...
struct	mbedtls_ssl_handshake_params
struct	mbedtls_ssl_transform
struct	mbedtls_record

Macros
#define	MBEDTLS_SSL_CHK_BUF_PTR(cur, end, need)
	This macro checks if the remaining size in a buffer is greater or equal than a needed space. More...

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_read_record (mbedtls_ssl_context *ssl, unsigned update_hs_digest)
	Update record layer. More...

Detailed Description

Internal functions shared by the SSL modules.

Definition in file ssl_internal.h.

Macro Definition Documentation

MBEDTLS_SSL_CHK_BUF_PTR

#define MBEDTLS_SSL_CHK_BUF_PTR	(		cur,
			end,
			need
	)

Value:

    do {                                                                 \
        if( mbedtls_ssl_chk_buf_ptr( ( cur ), ( end ), ( need ) ) != 0 ) \
        {                                                                \
            return( MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL );                  \
        }                                                                \
    } while( 0 )

This macro checks if the remaining size in a buffer is greater or equal than a needed space.

If it is not the case, it returns an SSL_BUFFER_TOO_SMALL error.

Parameters

cur	Pointer to the current position in the buffer.
end	Pointer to one past the end of the buffer.
need	Needed space in bytes.

Definition at line 347 of file ssl_internal.h.

Function Documentation

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