ra8_tls.h File Reference

Tiny TLS facade over the vendored Mbed TLS 4.x stack. More...

#include <stddef.h>
#include <stdint.h>
#include "ra8_err.h"

Include dependency graph for ra8_tls.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	ra8_tls_session_cfg

Typedefs
typedef int(*	ra8_tls_bio_send_fn) (void *ctx, const uint8_t *buf, size_t len)
	BIO send callback signature (write ciphertext to transport).
typedef int(*	ra8_tls_bio_recv_fn) (void *ctx, uint8_t *buf, size_t len)
	BIO receive callback signature (read ciphertext from transport).
typedef struct ra8_tls_session_cfg	ra8_tls_session_cfg_t
typedef struct ra8_tls_session_handle *	ra8_tls_session_t
	Opaque TLS session handle (typed pointer into the static pool).

Enumerations
enum	ra8_tls_limits_t : uint8_t {   k_ra8_tls_max_sessions = 4U ,   k_ra8_tls_cipher_name_cap = 48U }
	Static-pool sizing constants for the TLS facade. More...
enum	ra8_tls_net_const_t : uint16_t {   k_ra8_tls_ipv4_hdr_bytes = 20U ,   k_ra8_tls_tcp_hdr_bytes = 20U ,   k_ra8_tls_mtu_min = 128U ,   k_ra8_tls_mss_min = 64U }
	Transport-sizing constants used by ra8_tls_mss_clamp. More...
enum	ra8_tls_verify_mode_t : uint8_t {   k_ra8_tls_verify_default = 0U ,   k_ra8_tls_verify_none = 1U ,   k_ra8_tls_verify_optional = 2U ,   k_ra8_tls_verify_required = 3U }
	Peer-certificate verification policy for a session. More...

Functions
ra8_err_t	ra8_tls_global_init (void)
	One-shot facade initialisation.
ra8_err_t	ra8_tls_global_deinit (void)
	Symmetric tear-down for ra8_tls_global_init.
ra8_err_t	ra8_tls_session_open (ra8_tls_session_t *out_session, const ra8_tls_session_cfg_t *cfg)
	Allocate a TLS session from the static pool.
ra8_err_t	ra8_tls_session_close (ra8_tls_session_t session)
	Release a TLS session back to the pool.
ra8_err_t	ra8_tls_handshake (ra8_tls_session_t session)
	Iterative TLS handshake driver.
ra8_err_t	ra8_tls_send (ra8_tls_session_t session, const uint8_t *buf, size_t len, size_t *out_sent)
	Encrypt and send application data.
ra8_err_t	ra8_tls_recv (ra8_tls_session_t session, uint8_t *buf, size_t len, size_t *out_received)
	Decrypt and receive application data.
ra8_err_t	ra8_tls_get_cipher_suite (ra8_tls_session_t session, uint16_t *out_id, char *out_name, size_t name_cap)
	Report the negotiated cipher suite for a session.
ra8_err_t	ra8_tls_get_verify_result (ra8_tls_session_t session, uint32_t *out_flags)
	Report the peer-certificate verification result for a session.
ra8_err_t	ra8_tls_mss_clamp (uint16_t mtu, uint16_t *out_mss)
	Compute the TCP MSS that keeps a segment inside one MTU frame.

Detailed Description

Tiny TLS facade over the vendored Mbed TLS 4.x stack.

Tag

[Ring 4 / PAL] {World: NS}

ra8_tls is a thin, project-shaped wrapper around the third-party Mbed TLS 4.x + TF-PSA-Crypto 1.x library that ships under libs/third_party/mbedtls and libs/third_party/tf-psa-crypto. The goal is twofold:

1. Hide the Mbed TLS spelling (mbedtls_ssl_context, mbedtls_ssl_config, mbedtls_ctr_drbg_context, ...) behind a small ra8_tls_* API that returns ra8_err_t like the rest of the firmware. Higher-level apps (HTTPS client, MQTT/TLS, OTA firmware fetch) call into this facade instead of pulling a direct Mbed TLS dependency into their translation units.
2. Enforce NASA Power of 10 Rule 3 (no dynamic memory after init): sessions are handed out from a fixed-size static pool of mbedtls_ssl_context + mbedtls_ssl_config blocks, so a misbehaving consumer cannot fragment the heap or run the allocator past its budget.

Layering

*   +---------------------------+ ra8_tls_handshake
*   | App (HTTPS / MQTT / OTA)  | ra8_tls_send / ra8_tls_recv
*   +-------------+-------------+
*                 |
*                 v
*   +---------------------------+ ra8_tls (this header)
*   | Mbed TLS 4.x + TF-PSA     |
*   +-------------+-------------+
*                 |
*                 v
*   +---------------------------+ user-supplied BIO callbacks
*   | Transport (NetX Duo)      |
*   +---------------------------+
* 

The transport is bound through the BIO callbacks on ra8_tls_session_cfg_t – the facade itself does not know about NetX Duo. The NetX Duo adapter lives in a follow-up library.

Threading

One global init brings the PSA crypto layer online. The session-scoped APIs are not internally synchronised: callers that dispatch the same session from multiple threads must serialise the calls themselves (typical embedded usage opens a session from one task and never shares it).

Memory model

• k_ra8_tls_max_sessions mbedtls_ssl_context blocks live in .bss inside ra8_tls.c. ra8_tls_session_open hands out indices from a small bitmap; ra8_tls_session_close clears the bit and runs mbedtls_ssl_free on the slot.
• The opaque ra8_tls_session_t is a typed pointer to an internal struct that lives inside the same static pool, so callers cannot construct one out of thin air; the only legal source is ra8_tls_session_open.

Copyright

Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Definition in file ra8_tls.h.

Typedef Documentation

ra8_tls_bio_recv_fn

typedef int(* ra8_tls_bio_recv_fn) (void *ctx, uint8_t *buf, size_t len)

BIO receive callback signature (read ciphertext from transport).

Mirrors the Mbed TLS mbedtls_ssl_recv_t contract: returns the number of bytes consumed, 0 on EOF, or a negative Mbed TLS error code (MBEDTLS_ERR_SSL_WANT_READ for non-blocking would-block).

Parameters

[in,out]	ctx	Opaque user pointer registered through ra8_tls_session_cfg_t::bio_ctx.
[out]	buf	Buffer to fill with up to len bytes.
[in]	len	Capacity of buf in bytes.

Returns

Bytes read, 0 on EOF, or a negative Mbed TLS error code.

Since

0.1.0

Definition at line 203 of file ra8_tls.h.

ra8_tls_bio_send_fn

typedef int(* ra8_tls_bio_send_fn) (void *ctx, const uint8_t *buf, size_t len)

BIO send callback signature (write ciphertext to transport).

Mirrors the Mbed TLS mbedtls_ssl_send_t contract: returns the number of bytes accepted by the transport, or a negative Mbed TLS error code on failure (MBEDTLS_ERR_SSL_WANT_WRITE for non-blocking would-block).

Parameters

[in,out]	ctx	Opaque user pointer registered through ra8_tls_session_cfg_t::bio_ctx.
[in]	buf	Buffer holding len bytes of ciphertext.
[in]	len	Length of buf in bytes.

Returns

Bytes written, or a negative Mbed TLS error code.

Since

0.1.0

Definition at line 184 of file ra8_tls.h.

ra8_tls_session_cfg_t

typedef struct ra8_tls_session_cfg ra8_tls_session_cfg_t

ra8_tls_session_t

typedef struct ra8_tls_session_handle* ra8_tls_session_t

Opaque TLS session handle (typed pointer into the static pool).

NULL is a sentinel for "uninitialized handle". The only legal way to obtain a non-NULL value is ra8_tls_session_open; passing any other pointer to ra8_tls_session_close and friends is undefined behaviour from the caller's perspective and yields k_ra8_err_invalid_arg from this facade.

Since

0.1.0

Definition at line 277 of file ra8_tls.h.

Enumeration Type Documentation

ra8_tls_limits_t

enum ra8_tls_limits_t : uint8_t

Static-pool sizing constants for the TLS facade.

These bounds are chosen to fit four concurrent TLS sessions on the RA8D2 SRAM budget while leaving headroom for ThreadX stacks and NetX Duo packet pools. Increasing the count requires re-sizing s_session_pool in ra8_tls.c.

Invariant

k_ra8_tls_max_sessions fits in a uint8_t.

Enumerator
k_ra8_tls_max_sessions	Maximum simultaneous TLS sessions handed out by the pool. NASA Power of 10 Rule 3 cap: any further open returns k_ra8_err_no_mem.
k_ra8_tls_cipher_name_cap	Capacity (bytes) a caller must reserve for a cipher-suite name. ra8_tls_get_cipher_suite never writes more than this many bytes (including the terminating NUL) into the caller buffer; the longest IANA suite string plus NUL fits comfortably.

Definition at line 101 of file ra8_tls.h.

ra8_tls_net_const_t

enum ra8_tls_net_const_t : uint16_t

Transport-sizing constants used by ra8_tls_mss_clamp.

The RA8D2 ESWM has a documented large-frame egress defect (issue #21): frames over roughly half a KiB corrupt on the wire, so the whole networking stack is pinned to a 128-byte MTU. A TLS client that dials over TCP must therefore clamp its TCP Maximum Segment Size (MSS) so every segment – TLS record bytes included – fits inside one 128-byte MTU frame after the fixed IPv4 + TCP header overhead. These constants express that arithmetic without a bare literal.

Invariant

k_ra8_tls_ipv4_hdr_bytes + k_ra8_tls_tcp_hdr_bytes is strictly less than k_ra8_tls_mtu_min so a positive MSS always exists at the floor.

Enumerator
k_ra8_tls_ipv4_hdr_bytes	IPv4 header with no options.
k_ra8_tls_tcp_hdr_bytes	TCP header with no options.
k_ra8_tls_mtu_min	#21 pinned MTU floor (bytes).
k_ra8_tls_mss_min	Smallest MSS worth clamping to.

Definition at line 134 of file ra8_tls.h.

ra8_tls_verify_mode_t

enum ra8_tls_verify_mode_t : uint8_t

Peer-certificate verification policy for a session.

Maps onto the Mbed TLS MBEDTLS_SSL_VERIFY_* authentication modes. The zero value is a safe default (behaves as required) so a zero-initialised ra8_tls_session_cfg_t never silently disables verification.

Invariant

k_ra8_tls_verify_default is treated identically to k_ra8_tls_verify_required by the facade.

Enumerator
k_ra8_tls_verify_default	Facade default – same as required.
k_ra8_tls_verify_none	Do not verify the peer certificate.
k_ra8_tls_verify_optional	Verify but do not abort on failure.
k_ra8_tls_verify_required	Verify and abort the handshake on fail.

Definition at line 154 of file ra8_tls.h.

Function Documentation

ra8_tls_get_cipher_suite()

ra8_err_t ra8_tls_get_cipher_suite	(	ra8_tls_session_t	session,
		uint16_t *	out_id,
		char *	out_name,
		size_t	name_cap )

Report the negotiated cipher suite for a session.

After a successful ra8_tls_handshake this returns the IANA cipher-suite name (e.g. TLS-ECDHE-RSA-WITH-AES-128-GCM-SHA256) and its 16-bit IANA identifier so an application can log exactly what was negotiated. In RA8_OFF_TARGET (host unit-test build) the handshake is a loopback drain rather than a real negotiation, so a deterministic sentinel is reported: out_name becomes "off-target-loopback" and *out_id becomes 0. The output name is always NUL-terminated and never exceeds name_cap bytes.

Parameters

[in]	session	Open session handle in the application-data state.
[out]	out_id	Receives the 16-bit IANA cipher-suite id (0 when unknown / fake).
[out]	out_name	Receives the NUL-terminated cipher-suite name. Truncated to fit when the real name is longer.
[in]	name_cap	Capacity of out_name in bytes; must be >= 1.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Cipher reported into the outputs.
k_ra8_err_invalid_arg	Any pointer NULL, name_cap zero, or session invalid.
k_ra8_err_not_initialized	Module not initialized.

Precondition

session has completed its handshake.

out_id and out_name are non-NULL and name_cap >= 1.

Postcondition

On k_ra8_ok out_name is NUL-terminated.

On any error *out_id == 0 and out_name[0] == '\0' when the buffers are writable.

Note

Not thread-safe unless documented otherwise.

See also

ra8_tls_get_verify_result()

Since

0.1.0

Definition at line 600 of file ra8_tls.c.

References internal_copy_cstr(), internal_handle_valid(), k_ra8_err_invalid_arg, k_ra8_err_not_initialized, k_ra8_ok, s_initialized, and ra8_tls_session_handle::ssl.

Referenced by demo_report().

ra8_tls_get_verify_result()

ra8_err_t ra8_tls_get_verify_result	(	ra8_tls_session_t	session,
		uint32_t *	out_flags )

Report the peer-certificate verification result for a session.

Wraps mbedtls_ssl_get_verify_result: 0 means the peer chain satisfied the configured verify_mode; any non-zero value is the OR of MBEDTLS_X509_BADCERT_* / MBEDTLS_X509_BADCRL_* flags. In RA8_OFF_TARGET the loopback path reports 0 (verified).

Parameters

[in]	session	Open session handle in the application-data state.
[out]	out_flags	Receives the verification bit set (0 == OK).

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Result written to *out_flags.
k_ra8_err_invalid_arg	out_flags NULL or session invalid.
k_ra8_err_not_initialized	Module not initialized.

Precondition

session has completed its handshake.

out_flags is non-NULL.

Postcondition

On k_ra8_ok *out_flags holds the verification bit set.

On any error *out_flags == 0 when the pointer is writable.

Note

Not thread-safe unless documented otherwise.

See also

ra8_tls_get_cipher_suite()

Since

0.1.0

Definition at line 631 of file ra8_tls.c.

References internal_handle_valid(), k_ra8_err_invalid_arg, k_ra8_err_not_initialized, k_ra8_ok, s_initialized, and ra8_tls_session_handle::ssl.

Referenced by demo_report().

ra8_tls_global_deinit()

ra8_err_t ra8_tls_global_deinit

(

void

)

Symmetric tear-down for ra8_tls_global_init.

Frees every still-open session, wipes the CTR_DRBG state, and marks the module uninitialized so a subsequent ra8_tls_global_init succeeds again.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Facade torn down.
k_ra8_err_not_initialized	ra8_tls_global_init was never called.

Precondition

None (safe to call before any session open).

Module was previously initialized.

Postcondition

Pool is empty and module is not initialized.

All mbedtls_* contexts freed.

Note

Not re-entrant.

See also

ra8_tls_global_init()

Since

0.1.0

Definition at line 249 of file ra8_tls.c.

References internal_pool_reset(), k_ra8_err_not_initialized, k_ra8_ok, and s_initialized.

Referenced by demo_run_tls().

ra8_tls_global_init()

ra8_err_t ra8_tls_global_init

(

void

)

One-shot facade initialisation.

Brings the PSA crypto layer online and marks the session pool empty. Mbed TLS 4.x sources randomness from PSA (psa_generate_random) rather than a facade-owned CTR_DRBG, so the actual entropy is drawn lazily on the first random call through the application-supplied mbedtls_psa_external_get_random hook (the RSIP TRNG on hardware). Safe to call exactly once per boot; subsequent calls without a matching ra8_tls_global_deinit return k_ra8_err_exists.

Algorithm:

1. If already initialized, return k_ra8_err_exists.
2. Reset the session pool so close-without-open paths are well-defined.
3. Call psa_crypto_init (skipped in off-target mode).
4. Mark the module initialized.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Facade ready.
k_ra8_err_exists	Already initialized this boot.
k_ra8_err_hw_error	psa_crypto_init failed.

Precondition

Mbed TLS has been built into the firmware image (RA8_USE_MBEDTLS=ON) OR RA8_OFF_TARGET is defined for the host unit-test build.

On hardware, the RSIP TRNG that backs the PSA external-RNG hook is reachable before the first handshake (skipped in off-target mode).

Postcondition

Module is in the initialized state on success.

Session pool is fully reset (no slot held).

Note

Not re-entrant. Call from the boot path before any TLS session is opened.

Warning

Per-session trust anchors passed through ra8_tls_session_cfg_t::ca_pem are referenced, not copied; their storage must outlive the session.

Example:

ra8_err_t err = ra8_tls_global_init();
RA8_RETURN_ON_ERROR(err, "ra8_tls", "global_init failed");

See also

ra8_tls_global_deinit()

Since

0.1.0

Definition at line 222 of file ra8_tls.c.

References internal_pool_reset(), k_ra8_err_exists, k_ra8_err_hw_error, k_ra8_ok, ra8_log_error, ra8_log_info, ra8_log_warn, s_initialized, and s_ra8_tls_tag.

Referenced by demo_run_tls().

ra8_tls_handshake()

ra8_err_t ra8_tls_handshake

(

ra8_tls_session_t

session

)

Iterative TLS handshake driver.

Wraps mbedtls_ssl_handshake and translates its return value into an ra8_err_t. Returns k_ra8_err_would_block while the underlying BIO is non-blocking and waiting for I/O so the caller can loop without consuming the entire transport-level event budget.

In RA8_OFF_TARGET (host unit-test build) the call short- circuits to k_ra8_ok after a single BIO drain so the loopback test path can complete without a real cryptographic handshake.

Parameters

[in,out]

session

Open session handle.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Handshake complete.
k_ra8_err_invalid_arg	session invalid.
k_ra8_err_not_initialized	Module not initialized.
k_ra8_err_would_block	BIO is non-blocking; retry later.
k_ra8_err_comm_error	Mbed TLS reported a fatal handshake failure (cert / protocol / decode).

Precondition

session is open.

BIO callbacks have been bound (done by ra8_tls_session_open).

Postcondition

On k_ra8_ok the session is in the application-data state.

On any non-would-block error the session must be closed.

See also

ra8_tls_send()

ra8_tls_recv()

Since

0.1.0

Note

Not thread-safe unless documented otherwise.

Definition at line 479 of file ra8_tls.c.

References ra8_tls_session_handle::cfg, internal_handle_valid(), k_ra8_err_comm_error, k_ra8_err_invalid_arg, k_ra8_err_not_initialized, k_ra8_err_would_block, k_ra8_ok, k_tls_content_handshake, ra8_log_error, s_initialized, s_ra8_tls_tag, and ra8_tls_session_handle::ssl.

Referenced by demo_handshake().

ra8_tls_mss_clamp()

ra8_err_t ra8_tls_mss_clamp	(	uint16_t	mtu,
		uint16_t *	out_mss )

Compute the TCP MSS that keeps a segment inside one MTU frame.

Pure arithmetic helper for TLS-over-TCP clients on the #21-pinned 128-byte MTU link: subtracts the fixed IPv4 + TCP header overhead from mtu to yield the largest TCP payload (Maximum Segment Size) that still fits one Ethernet frame the ESWM egress transmits cleanly. The result is what a caller feeds to the transport (e.g. an Mbed TLS maximum-fragment-length hint or a NetX Duo socket MSS) so the TLS record layer never asks the MAC to send an over-length frame.

Parameters

[in]	mtu	Link MTU in bytes (payload, excluding the 14-byte Ethernet header); must be >= k_ra8_tls_mtu_min.
[out]	out_mss	Receives the clamped MSS (mtu - IPv4 - TCP) in bytes.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	MSS written to *out_mss.
k_ra8_err_invalid_arg	out_mss NULL, or mtu too small to leave at least k_ra8_tls_mss_min bytes.

Precondition

out_mss is non-NULL.

mtu leaves room for a >= k_ra8_tls_mss_min byte segment.

Postcondition

On k_ra8_ok *out_mss is in [k_ra8_tls_mss_min, mtu).

On any error *out_mss == 0 when the pointer is writable.

Note

Pure function; safe from any context.

Example:

uint16_t mss = 0U;
if (ra8_tls_mss_clamp(k_ra8_tls_mtu_min, &mss) == k_ra8_ok) {
  // mss == 88 for the 128-byte MTU: 128 - 20 (IP) - 20 (TCP)
}

Since

0.1.0

Definition at line 651 of file ra8_tls.c.

References k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_tls_ipv4_hdr_bytes, k_ra8_tls_mss_min, and k_ra8_tls_tcp_hdr_bytes.

Referenced by demo_run_tls().

ra8_tls_recv()

ra8_err_t ra8_tls_recv	(	ra8_tls_session_t	session,
		uint8_t *	buf,
		size_t	len,
		size_t *	out_received )

Decrypt and receive application data.

Wraps mbedtls_ssl_read. *out_received == 0 together with k_ra8_ok denotes a clean peer close-notify; k_ra8_err_would_block means the underlying transport had no data ready.

Parameters

[in,out]	session	Open session handle in the application-data state.
[out]	buf	Plaintext output buffer.
[in]	len	Capacity of buf in bytes.
[out]	out_received	Bytes decrypted into buf.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Decrypted *out_received bytes (0 on clean close).
k_ra8_err_invalid_arg	Any pointer NULL or session invalid.
k_ra8_err_not_initialized	Module not initialized.
k_ra8_err_would_block	No ciphertext available yet.
k_ra8_err_comm_error	Fatal TLS-layer error.

Precondition

session has completed its handshake.

buf is non-NULL when len > 0.

Postcondition

*out_received <= len.

On any error *out_received == 0.

See also

ra8_tls_send()

Since

0.1.0

Note

Not thread-safe unless documented otherwise.

Definition at line 557 of file ra8_tls.c.

References ra8_tls_session_handle::cfg, internal_handle_valid(), k_ra8_err_comm_error, k_ra8_err_invalid_arg, k_ra8_err_not_initialized, k_ra8_err_would_block, k_ra8_ok, s_initialized, and ra8_tls_session_handle::ssl.

Referenced by demo_exchange().

ra8_tls_send()

ra8_err_t ra8_tls_send	(	ra8_tls_session_t	session,
		const uint8_t *	buf,
		size_t	len,
		size_t *	out_sent )

Encrypt and send application data.

Wraps mbedtls_ssl_write. Returns the number of bytes accepted by the TLS layer through out_sent; partial writes are reported back to the caller so they can advance their buffer pointer.

Parameters

[in,out]	session	Open session handle in the application-data state.
[in]	buf	Plaintext input buffer.
[in]	len	Number of bytes to send (0 is a no-op).
[out]	out_sent	Bytes consumed by the TLS layer (always <= len).

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Wrote *out_sent bytes.
k_ra8_err_invalid_arg	Any pointer NULL or session invalid.
k_ra8_err_not_initialized	Module not initialized.
k_ra8_err_would_block	Non-blocking BIO returned WANT_WRITE.
k_ra8_err_comm_error	Fatal TLS-layer error.

Precondition

session has completed its handshake.

buf is non-NULL when len > 0.

Postcondition

On k_ra8_ok *out_sent <= len.

On any error *out_sent == 0.

See also

ra8_tls_recv()

Since

0.1.0

Note

Not thread-safe unless documented otherwise.

Definition at line 517 of file ra8_tls.c.

References ra8_tls_session_handle::cfg, internal_handle_valid(), k_ra8_err_comm_error, k_ra8_err_invalid_arg, k_ra8_err_not_initialized, k_ra8_err_would_block, k_ra8_ok, s_initialized, and ra8_tls_session_handle::ssl.

Referenced by demo_exchange().

ra8_tls_session_close()

ra8_err_t ra8_tls_session_close

(

ra8_tls_session_t

session

)

Release a TLS session back to the pool.

Validates that session actually points into the pool, runs mbedtls_ssl_free / mbedtls_ssl_config_free on the slot, and clears the in-use bit. Safe to call on any open session, even one that has not completed its handshake.

Parameters

[in,out]

session

Handle previously returned by ra8_tls_session_open.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Slot released.
k_ra8_err_invalid_arg	session is NULL or does not point into the pool.
k_ra8_err_not_initialized	ra8_tls_global_init was never called.

Precondition

session was returned by ra8_tls_session_open.

Module is initialized.

Postcondition

Slot is free and may be re-issued.

No further use of session is permitted (use-after-free is caller's bug).

See also

ra8_tls_session_open()

Since

0.1.0

Note

Not thread-safe unless documented otherwise.

Definition at line 461 of file ra8_tls.c.

References ra8_tls_session_handle::ca, ra8_tls_session_handle::config, internal_handle_valid(), k_ra8_err_invalid_arg, k_ra8_err_not_initialized, k_ra8_ok, memset(), s_initialized, and ra8_tls_session_handle::ssl.

Referenced by demo_run_tls().

ra8_tls_session_open()

ra8_err_t ra8_tls_session_open	(	ra8_tls_session_t *	out_session,
		const ra8_tls_session_cfg_t *	cfg )

Allocate a TLS session from the static pool.

Searches the in-use bitmap for a free slot, copies cfg into the slot, runs mbedtls_ssl_setup / mbedtls_ssl_set_bio and returns the typed pointer through out_session.

Parameters

[out]	out_session	Receives the new opaque handle on success. Set to NULL on any non-success return.
[in]	cfg	Session configuration; both BIO callbacks must be non-NULL. The struct itself is copied; the caller may free it on return.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Session allocated and ready for handshake.
k_ra8_err_invalid_arg	out_session or cfg is NULL, or one of the BIO callbacks is NULL.
k_ra8_err_not_initialized	ra8_tls_global_init was never called.
k_ra8_err_no_mem	Pool exhausted (more than k_ra8_tls_max_sessions open).

Precondition

ra8_tls_global_init returned k_ra8_ok previously.

cfg->bio_send and cfg->bio_recv are non-NULL.

Postcondition

On k_ra8_ok, *out_session is non-NULL and survives until a matching ra8_tls_session_close.

On any error, *out_session is set to NULL.

Note

Not thread-safe; caller must serialise allocation against concurrent close.

See also

ra8_tls_session_close()

ra8_tls_handshake()

Since

0.1.0

Definition at line 432 of file ra8_tls.c.

References ra8_tls_session_handle::cfg, ra8_tls_session_handle::in_use, internal_pool_acquire(), internal_session_mbedtls_setup(), internal_session_validate_args(), k_ra8_err_no_mem, k_ra8_ok, ra8_log_warn, and s_ra8_tls_tag.

Referenced by demo_run_tls().