mbedtls library interface

Collaboration diagram for mbedtls library interface:

Data Structures
struct	tls_cfg_t
struct	tls_net_ctx_t
struct	tls_conn_t
struct	tls_pump_t

Macros
#define	TLS_RSA   1
	Set to 0 to slightly reduce ram and flash footprint if RSA is not needed (i.e. PSK-only)

Typedefs
typedef struct tls_cfg_t	tls_cfg_t
typedef struct tls_conn_t	tls_conn_t
typedef struct tls_pump_t	tls_pump_t

Functions
void	TlsPlatformInit (void)
int	TlsCfgInitRsa (tls_cfg_t *TlsCfg, int Role, const uint8_t *Cert, int CertLen, const uint8_t *Key, int KeyLen)
int	TlsCfgInitPsk (tls_cfg_t *TlsCfg, int Role, const uint8_t *Psk, int PskLen, const uint8_t *Identity, int IdentityLen)
void	TlsCfgFree (tls_cfg_t *TlsCfg)
int	TlsConnectionInit (tls_conn_t *TlsConn, tls_cfg_t *TlsCfg)
int	TlsPumpInit (tls_pump_t *TlsPump, tls_cfg_t *TlsCfg, const struct datapump_cfg_t *PumpCfg)
void	TlsPumpFree (tls_pump_t *TlsPump)
int	TlsHandshake (tls_conn_t *TlsConn, uint32_t Timeout)
void	TlsConnectionClose (tls_conn_t *TlsConn)
void	TlsConnectionFree (tls_conn_t *TlsConn)
int	TlsReceive (tls_conn_t *TlsConn, uint8_t *Buffer, size_t Length, uint32_t Timeout)
int	TlsSend (tls_conn_t *TlsConn, const uint8_t *Buffer, size_t Length, uint32_t Timeout)

Variables
const struct md_heap_t	TlsRxBufferHeap
	User-defined TLS Rx heap.
const struct md_heap_t	TlsTxBufferHeap
	User-defined TLS Tx heap.
const struct md_heap_t	TlsHeap
	User-defined TLS processing.

Detailed Description

Typedef Documentation

typedef struct tls_cfg_t tls_cfg_t

TLS instance (client or server) configuration.

typedef struct tls_conn_t tls_conn_t

TLS connection instance.

typedef struct tls_pump_t tls_pump_t

TLS datapump

Function Documentation

void TlsPlatformInit

(

void

)

Initializes TLS subsystem

int TlsCfgInitRsa	(	tls_cfg_t *	TlsCfg,
		int	Role,
		const uint8_t *	Cert,
		int	CertLen,
		const uint8_t *	Key,
		int	KeyLen
	)

Initializes a TLS instance configuration (RSA variant)

Parameters

TlsCfg	Pointer to an uninitialized TLS configuration
Role	MBEDTLS_SSL_IS_CLIENT or MBEDTLS_SSL_IS_SERVER
Cert	Pointer to an RSA sertificate
CertLen	RSA certificate length
Key	Pointer to an RSA private key
KeyLen	RSA private key length

Returns

0 if finished successfully, otherwise an mbedtls error code.

int TlsCfgInitPsk	(	tls_cfg_t *	TlsCfg,
		int	Role,
		const uint8_t *	Psk,
		int	PskLen,
		const uint8_t *	Identity,
		int	IdentityLen
	)

Initializes a TLS instance configuration (PSK variant)

Parameters

TlsCfg	Pointer to an uninitialized TLS configuration
Role	MBEDTLS_SSL_IS_CLIENT or MBEDTLS_SSL_IS_SERVER
Psk	Pointer to a PSK key
PskLen	PSK key length
Identity	Pointer to PSK identity
IdentityLen	PSK identity length

Returns

0 if finished successfully, otherwise an mbedtls error code.

void TlsCfgFree

(

tls_cfg_t *

TlsCfg

)

Free a previously allocated TLS instance configuration

Parameters

TlsCfg

Pointer to a previously allocated TLS configuration

int TlsConnectionInit	(	tls_conn_t *	TlsConn,
		tls_cfg_t *	TlsCfg
	)

Initializes a TLS connection

Parameters

TlsConn	Pointer to an uninitialized TLS connection instance
TlsCfg	Pointer to a TLS instance configuration

Returns

0 if finished successfully, otherwise an mbedtls error code.

int TlsPumpInit	(	tls_pump_t *	TlsPump,
		tls_cfg_t *	TlsCfg,
		const struct datapump_cfg_t *	PumpCfg
	)

Initializes a TLS connection and starts data pump tasks

Parameters

TlsPump	Pointer to an uninitialized TLS data pump instance
TlsCfg	Pointer to a TLS instance configuration
PumpCfg	Constant pointer to a data pump configuration

Returns

0 if finished successfully, otherwise an mbedtls error code.

void TlsPumpFree

(

tls_pump_t *

TlsPump

)

Deallocates resources, associated with datapump.

Parameters

TlsPump

Pointer to a data pump instance

int TlsHandshake	(	tls_conn_t *	TlsConn,
		uint32_t	Timeout
	)

Performes a TLS handshake.

The function uses sockets directly and thus must be called from a task.

Parameters

TlsConn	Pointer to a TLS connection instance
Timeout	Timeout (in system ticks)

Returns

0 if finished successfully, otherwise an mbedtls error code.

void TlsConnectionClose

(

tls_conn_t *

TlsConn

)

Terminates an ongoing TLS connection.

The function uses sockets directly and thus must be called from a task

Parameters

TlsConn

Pointer to a TLS connection instance

void TlsConnectionFree

(

tls_conn_t *

TlsConn

)

Deallocates resources, associated with a TlsConn.

Parameters

TlsConn

Pointer to a TLS connection instance

int TlsReceive	(	tls_conn_t *	TlsConn,
		uint8_t *	Buffer,
		size_t	Length,
		uint32_t	Timeout
	)

Receives data from a TLS connection.

The function uses sockets directly and thus must be called from a task. It has same semantic as a BSD socket recv() function and can return less bytes than it was requested.

Parameters

TlsConn	Pointer to a TLS connection instance
Buffer	A buffer to put data into
Length	Length of the buffer (max number of bytes to read)
Timeout	Timeout (in system ticks)

Returns

A positive value shows length of the data read, 0 indicates end-of-stream condition, and an (mbedtls) negative code indicates an error.

int TlsSend	(	tls_conn_t *	TlsConn,
		const uint8_t *	Buffer,
		size_t	Length,
		uint32_t	Timeout
	)

Sends data to a TLS connection.

The function uses sockets directly and thus must be called from a task. It has same semantic as a BSD socket send() function and can send less bytes than it was requested.

Parameters

TlsConn	Pointer to a TLS connection instance
Buffer	A buffer containing the data to send
Length	Length of the buffer (max number of bytes to send)
Timeout	Timeout (in system ticks)

Returns

A positive value shows length of the data sent, 0 indicates end-of-stream condition, and an (mbedtls) negative code indicates an error.