tls_mbedtls.h File Reference

#include <keel/tls.h>
#include <keel/allocator.h>

Include dependency graph for tls_mbedtls.h:

Go to the source code of this file.

Enumerations
enum	KlMtlsMode { KL_MTLS_NONE = 0 , KL_MTLS_OPTIONAL = 1 , KL_MTLS_REQUIRED = 2 }
	Client authentication mode for mTLS. More...

Functions
KlTlsCtx *	kl_tls_mbedtls_ctx_create (const char *cert_path, const char *key_path, const char *ca_path, int client_auth, KlAllocator *alloc)
	Create a server-side TLS context (certificates + keys).
KlTlsCtx *	kl_tls_mbedtls_client_ctx_create (const char *ca_path, KlAllocator *alloc)
	Create a client-side TLS context (for outbound connections).
KlTlsCtx *	kl_tls_mbedtls_client_ctx_create_from_buf (const unsigned char *ca_buf, size_t ca_len, KlAllocator *alloc)
	Create a TLS client context from an in-memory CA bundle.
void	kl_tls_mbedtls_ctx_destroy (KlTlsCtx *ctx)
	Destroy a TLS context.
KlTls *	kl_tls_mbedtls_create (KlTlsCtx *ctx, KlAllocator *alloc)
	Factory: create a per-connection KlTls session.
int	kl_tls_mbedtls_set_hostname (KlTls *tls, const char *hostname)
	Set the expected server hostname for SNI (client mode).

Enumeration Type Documentation

KlMtlsMode

enum KlMtlsMode

Client authentication mode for mTLS.

Enumerator
KL_MTLS_NONE	No client certificate requested
KL_MTLS_OPTIONAL	Request cert, allow unauthenticated
KL_MTLS_REQUIRED	Require valid client certificate

Function Documentation

kl_tls_mbedtls_ctx_create()

KlTlsCtx * kl_tls_mbedtls_ctx_create	(	const char *	cert_path,
		const char *	key_path,
		const char *	ca_path,
		int	client_auth,
		KlAllocator *	alloc
	)

Create a server-side TLS context (certificates + keys).

Parameters

cert_path	Path to PEM-encoded server certificate (chain).
key_path	Path to PEM-encoded server private key.
ca_path	Path to PEM-encoded CA cert for client verification (mTLS). NULL to disable client authentication.
client_auth	Client authentication mode (KlMtlsMode).
alloc	Allocator for context storage (borrowed — must outlive context).

Returns

Opaque context, or NULL on error.

kl_tls_mbedtls_client_ctx_create()

KlTlsCtx * kl_tls_mbedtls_client_ctx_create	(	const char *	ca_path,
		KlAllocator *	alloc
	)

Create a client-side TLS context (for outbound connections).

Parameters

ca_path	Path to PEM-encoded CA cert bundle for server verification. NULL skips certificate verification — requires explicit opt-in via –skip-ca-bundle flag. Production deployments should always provide a valid CA bundle path.
alloc	Allocator for context storage (borrowed — must outlive context).

Returns

Opaque context, or NULL on error.

kl_tls_mbedtls_client_ctx_create_from_buf()

KlTlsCtx * kl_tls_mbedtls_client_ctx_create_from_buf	(	const unsigned char *	ca_buf,
		size_t	ca_len,
		KlAllocator *	alloc
	)

Create a TLS client context from an in-memory CA bundle.

Same as kl_tls_mbedtls_client_ctx_create() but reads the CA bundle from a buffer instead of a file. Useful for embedded bundles where there is no filesystem path. The buffer must be PEM-encoded; binary DER is also accepted by mbedTLS (it auto-detects).

The buffer is parsed and copied internally; the caller may free it immediately after this call returns.

Parameters

ca_buf	PEM (or DER) CA bundle bytes. Must be non-NULL.
ca_len	Length in bytes. For PEM, must include the trailing NUL — mbedTLS requires PEM input to be NUL-terminated.
alloc	Allocator for context storage (borrowed — must outlive context).

Returns

Opaque context, or NULL on error.

kl_tls_mbedtls_ctx_destroy()

void kl_tls_mbedtls_ctx_destroy

(

KlTlsCtx *

ctx

)

Destroy a TLS context.

Safe to pass as ctx_destroy in KlTlsConfig.

kl_tls_mbedtls_create()

KlTls * kl_tls_mbedtls_create	(	KlTlsCtx *	ctx,
		KlAllocator *	alloc
	)

Factory: create a per-connection KlTls session.

Works for both server-side and client-side contexts. Pass as the factory field in KlTlsConfig.

Parameters

ctx	Shared context from kl_tls_mbedtls_ctx_create() or kl_tls_mbedtls_client_ctx_create().
alloc	Allocator for session resources.

Returns

New TLS session, or NULL on failure.

kl_tls_mbedtls_set_hostname()

int kl_tls_mbedtls_set_hostname	(	KlTls *	tls,
		const char *	hostname
	)

Set the expected server hostname for SNI (client mode).

Must be called after kl_tls_mbedtls_create() and before handshake().

Parameters

tls	TLS session from kl_tls_mbedtls_create().
hostname	Server hostname for SNI and certificate verification.

Returns

0 on success, -1 on error.