TLS

Portable TLS layer using mbedTLS. More...

Data Structures
struct	ove_tls_config_t
	TLS session configuration. More...

Functions
int	ove_tls_init (ove_tls_t *tls, ove_tls_storage_t *storage)
	Initialise a TLS session from caller-supplied storage.
void	ove_tls_deinit (ove_tls_t tls)
	De-initialise a TLS session (frees internal resources, not storage).
int	ove_tls_handshake (ove_tls_t tls, ove_socket_t sock, const ove_tls_config_t *cfg)
	Perform the TLS handshake over an established socket.
int	ove_tls_send (ove_tls_t tls, const void *data, size_t len, size_t *sent)
	Send data over an encrypted TLS session.
int	ove_tls_recv (ove_tls_t tls, void *buf, size_t len, size_t *received)
	Receive data from an encrypted TLS session.
void	ove_tls_close (ove_tls_t tls)
	Shut down the TLS session (sends close_notify).
int	ove_tls_create (ove_tls_t *tls)
	Heap-allocate and initialise a TLS session.
void	ove_tls_destroy (ove_tls_t tls)
	Destroy a heap-allocated TLS session.

Detailed Description

Portable TLS layer using mbedTLS.

Provides encrypted socket communication. The TLS layer wraps mbedTLS and delegates I/O to the oveRTOS socket API, making it portable across all backends.

Note

Requires CONFIG_OVE_NET_TLS (implies CONFIG_OVE_NET). When disabled every function is replaced by a no-op stub that returns OVE_ERR_NOT_SUPPORTED.

Function Documentation

ove_tls_init()

int ove_tls_init	(	ove_tls_t *	tls,
		ove_tls_storage_t *	storage
	)

Initialise a TLS session from caller-supplied storage.

Parameters

[out]	tls	Handle written on success.
[in]	storage	Caller-allocated storage.

Returns

OVE_OK on success, negative error code on failure.

ove_tls_deinit()

void ove_tls_deinit

(

ove_tls_t

tls

)

De-initialise a TLS session (frees internal resources, not storage).

Parameters

[in]

tls

Handle returned by ove_tls_init().

ove_tls_handshake()

int ove_tls_handshake	(	ove_tls_t	tls,
		ove_socket_t	sock,
		const ove_tls_config_t *	cfg
	)

Perform the TLS handshake over an established socket.

Parameters

[in]	tls	TLS handle.
[in]	sock	Connected socket to wrap.
[in]	cfg	TLS configuration (certs, hostname).

Returns

OVE_OK on success, negative error code on failure.

ove_tls_send()

int ove_tls_send	(	ove_tls_t	tls,
		const void *	data,
		size_t	len,
		size_t *	sent
	)

Send data over an encrypted TLS session.

Parameters

[in]	tls	TLS handle (after successful handshake).
[in]	data	Pointer to data to send.
[in]	len	Number of bytes to send.
[out]	sent	Number of bytes actually sent (may be NULL).

Returns

OVE_OK on success, negative error code on failure.

ove_tls_recv()

int ove_tls_recv	(	ove_tls_t	tls,
		void *	buf,
		size_t	len,
		size_t *	received
	)

Receive data from an encrypted TLS session.

Parameters

[in]	tls	TLS handle (after successful handshake).
[out]	buf	Buffer to receive into.
[in]	len	Buffer size in bytes.
[out]	received	Number of bytes received (may be NULL).

Returns

OVE_OK on success, OVE_ERR_NET_CLOSED if peer closed.

ove_tls_close()

void ove_tls_close

(

ove_tls_t

tls

)

Shut down the TLS session (sends close_notify).

The underlying socket is NOT closed — caller must close it separately.

Parameters

[in]

tls

TLS handle.

ove_tls_create()

int ove_tls_create

(

ove_tls_t *

tls

)

Heap-allocate and initialise a TLS session.

Parameters

[out]

tls

Handle written on success.

Returns

OVE_OK on success, negative error code on failure.

ove_tls_destroy()

void ove_tls_destroy

(

ove_tls_t

tls

)

Destroy a heap-allocated TLS session.

Parameters

[in]

tls

Handle returned by ove_tls_create().