Typedefs
typedef struct M_tls_clientctx	M_tls_clientctx_t

typedef struct M_tls_serverctx	M_tls_serverctx_t

Enumerations
enum	M_tls_protocols_t { M_TLS_PROTOCOL_INVALID = -1 , M_TLS_PROTOCOL_TLSv1_0 = 1 << 0 , M_TLS_PROTOCOL_TLSv1_1 = 1 << 1 , M_TLS_PROTOCOL_TLSv1_2 = 1 << 2 , M_TLS_PROTOCOL_TLSv1_3 = 1 << 3 , M_TLS_PROTOCOL_DEFAULT = (M_TLS_PROTOCOL_TLSv1_0 \| M_TLS_PROTOCOL_TLSv1_1 \| M_TLS_PROTOCOL_TLSv1_2 \| M_TLS_PROTOCOL_TLSv1_3) }

enum	M_tls_verify_level_t { M_TLS_VERIFY_NONE = 0 , M_TLS_VERIFY_CERT_ONLY = 1 , M_TLS_VERIFY_CERT_FUZZY = 2 , M_TLS_VERIFY_FULL = 3 }

enum	M_tls_init_t { M_TLS_INIT_NORMAL = 1 , M_TLS_INIT_EXTERNAL = 2 }

Functions
void	M_tls_init (M_tls_init_t type)

M_tls_clientctx_t *	M_tls_clientctx_create (void)

M_bool	M_tls_clientctx_upref (M_tls_clientctx_t *ctx)

void	M_tls_clientctx_destroy (M_tls_clientctx_t *ctx)

M_bool	M_tls_clientctx_set_protocols (M_tls_clientctx_t *ctx, int protocols)

M_bool	M_tls_clientctx_set_ciphers (M_tls_clientctx_t ctx, const char ciphers)

M_bool	M_tls_clientctx_set_cert (M_tls_clientctx_t ctx, const unsigned char key, size_t key_len, const unsigned char crt, size_t crt_len, const unsigned char intermediate, size_t intermediate_len)

M_bool	M_tls_clientctx_set_cert_files (M_tls_clientctx_t ctx, const char keypath, const char crtpath, const char intermediatepath)

M_bool	M_tls_clientctx_set_default_trust (M_tls_clientctx_t *ctx)

M_bool	M_tls_clientctx_set_trust_ca (M_tls_clientctx_t ctx, const unsigned char ca, size_t len)

M_bool	M_tls_clientctx_set_trust_ca_file (M_tls_clientctx_t ctx, const char path)

M_bool	M_tls_clientctx_set_trust_ca_dir (M_tls_clientctx_t ctx, const char path)

M_bool	M_tls_clientctx_set_trust_cert (M_tls_clientctx_t ctx, const unsigned char crt, size_t len)

M_bool	M_tls_clientctx_set_trust_cert_file (M_tls_clientctx_t ctx, const char path)

M_bool	M_tls_clientctx_set_verify_level (M_tls_clientctx_t *ctx, M_tls_verify_level_t level)

M_bool	M_tls_clientctx_set_session_resumption (M_tls_clientctx_t *ctx, M_bool enable)

char *	M_tls_clientctx_get_cipherlist (M_tls_clientctx_t *ctx)

M_bool	M_tls_clientctx_set_applications (M_tls_clientctx_t ctx, M_list_str_t applications)

M_bool	M_tls_clientctx_set_negotiation_timeout_ms (M_tls_clientctx_t *ctx, M_uint64 timeout_ms)

M_io_error_t	M_io_tls_client_add (M_io_t io, M_tls_clientctx_t ctx, const char hostname, size_t layer_id)

M_tls_serverctx_t *	M_tls_serverctx_create (const unsigned char key, size_t key_len, const unsigned char crt, size_t crt_len, const unsigned char *intermediate, size_t intermediate_len)

M_tls_serverctx_t *	M_tls_serverctx_create_from_files (const char keypath, const char crtpath, const char *intermediatepath)

M_bool	M_tls_serverctx_upref (M_tls_serverctx_t *ctx)

void	M_tls_serverctx_destroy (M_tls_serverctx_t *ctx)

M_bool	M_tls_serverctx_SNI_ctx_add (M_tls_serverctx_t ctx, M_tls_serverctx_t child)

size_t	M_tls_serverctx_SNI_count (M_tls_serverctx_t *ctx)

M_tls_serverctx_t *	M_tls_serverctx_SNI_lookup (M_tls_serverctx_t ctx, const char hostname)

M_tls_serverctx_t *	M_tls_serverctx_SNI_at (M_tls_serverctx_t *ctx, size_t idx)

char *	M_tls_serverctx_get_cert (M_tls_serverctx_t *ctx)

M_bool	M_tls_serverctx_set_protocols (M_tls_serverctx_t *ctx, int protocols)

M_bool	M_tls_serverctx_set_ciphers (M_tls_serverctx_t ctx, const char ciphers)

M_bool	M_tls_serverctx_set_server_preference (M_tls_serverctx_t *ctx, M_bool tf)

M_bool	M_tls_serverctx_set_trust_ca (M_tls_serverctx_t ctx, const unsigned char ca, size_t len)

M_bool	M_tls_serverctx_set_trust_ca_file (M_tls_serverctx_t ctx, const char path)

M_bool	M_tls_serverctx_set_trust_ca_dir (M_tls_serverctx_t ctx, const char path)

M_bool	M_tls_serverctx_set_trust_cert (M_tls_serverctx_t ctx, const unsigned char crt, size_t len)

M_bool	M_tls_serverctx_set_trust_cert_file (M_tls_serverctx_t ctx, const char path)

M_bool	M_tls_serverctx_add_trust_crl (M_tls_serverctx_t ctx, const unsigned char crl, size_t len)

M_bool	M_tls_serverctx_add_trust_crl_file (M_tls_serverctx_t ctx, const char path)

M_bool	M_tls_serverctx_set_dhparam (M_tls_serverctx_t ctx, const unsigned char dhparam, size_t dhparam_len)

M_bool	M_tls_serverctx_set_dhparam_file (M_tls_serverctx_t ctx, const char dhparam_path)

M_bool	M_tls_serverctx_set_session_resumption (M_tls_serverctx_t *ctx, M_bool enable)

char *	M_tls_serverctx_get_cipherlist (M_tls_serverctx_t *ctx)

M_bool	M_tls_serverctx_set_applications (M_tls_serverctx_t ctx, M_list_str_t applications)

M_bool	M_tls_serverctx_set_negotiation_timeout_ms (M_tls_serverctx_t *ctx, M_uint64 timeout_ms)

M_io_error_t	M_io_tls_server_add (M_io_t io, M_tls_serverctx_t ctx, size_t *layer_id)

const char *	M_tls_server_get_hostname (M_io_t *io, size_t id)

M_tls_protocols_t	M_tls_get_protocol (M_io_t *io, size_t id)

M_bool	M_tls_get_sessionreused (M_io_t *io, size_t id)

const char *	M_tls_get_cipher (M_io_t *io, size_t id)

char *	M_tls_get_application (M_io_t *io, size_t id)

char *	M_tls_get_peer_cert (M_io_t *io, size_t id)

M_uint64	M_tls_get_negotiation_time_ms (M_io_t *io, size_t id)

const char *	M_tls_protocols_to_str (M_tls_protocols_t protocol)

M_tls_protocols_t	M_tls_protocols_from_str (const char *protocols_str)

Detailed Description

TLS functions

Typedef Documentation

◆ M_tls_clientctx_t

typedef struct M_tls_clientctx M_tls_clientctx_t

◆ M_tls_serverctx_t

typedef struct M_tls_serverctx M_tls_serverctx_t

Enumeration Type Documentation

◆ M_tls_protocols_t

enum M_tls_protocols_t

Supported TLS protocols.

Enumerator
M_TLS_PROTOCOL_INVALID	Invalid protocol.
M_TLS_PROTOCOL_TLSv1_0
M_TLS_PROTOCOL_TLSv1_1
M_TLS_PROTOCOL_TLSv1_2
M_TLS_PROTOCOL_TLSv1_3
M_TLS_PROTOCOL_DEFAULT	While not a define passing 0 to a function that takes a protocol will be treated as default.

◆ M_tls_verify_level_t

enum M_tls_verify_level_t

Certificate verification level.

Used by client connections to control how they decide to trust the certificate presented by the server.

Enumerator
M_TLS_VERIFY_NONE	Do not verify the certificate or hostname.
M_TLS_VERIFY_CERT_ONLY	Only verify the certificate. The domain name is not checked.
M_TLS_VERIFY_CERT_FUZZY	Verify the certificate and that the base domain name matches. Use this for servers that don't properly have a wild card cert but still use a sub domain.
M_TLS_VERIFY_FULL	Default. Verify the certificate and full domain name matches

◆ M_tls_init_t

enum M_tls_init_t

How the TLS stack was/is initialized.

The TLS system uses OpenSSL as its back ends. It has global initialization and can only be initialized once. Inform the TLS system if it has already been initialized.

Enumerator
M_TLS_INIT_NORMAL	Fully initialize the TLS (OpenSSL stack)
M_TLS_INIT_EXTERNAL	TLS initialization is handled externally (use with caution)

Function Documentation

◆ M_tls_init()

void M_tls_init ( M_tls_init_t type )

Initialize the TLS library.

If a TLS function is used without calling this function it will be auto initialized using the NORMAL type.

Parameters

[in] type Type of initialization.

◆ M_tls_clientctx_create()

M_tls_clientctx_t * M_tls_clientctx_create ( void )

Create a client TLS context.

Returns: Client context.

◆ M_tls_clientctx_upref()

M_bool M_tls_clientctx_upref ( M_tls_clientctx_t * ctx )

Increment reference counters.

Intended for APIs that might take ownership. Can only be Dereferenced via M_tls_clientctx_destroy()

Parameters

[in] ctx Client context.

◆ M_tls_clientctx_destroy()

void M_tls_clientctx_destroy ( M_tls_clientctx_t * ctx )

Destroy a client context.

Client CTXs use reference counters, and will delay destruction until after last consumer is destroyed.

Parameters

[in] ctx Client context.

◆ M_tls_clientctx_set_protocols()

M_bool M_tls_clientctx_set_protocols	(	M_tls_clientctx_t *	ctx,
		int	protocols
	)

Set the TLS protocols that the context should use.

Parameters

[in]	ctx	Client context.
[in]	protocols	M_tls_protocols_t bitmap of TLS protocols that should be supported. Protocols are treated as min and max. For example if TLSv1.0 and TLSv1.2 are enabled, then TLSv1.1 will be enabled even if not explicitly set.

Returns: M_TRUE on success, otherwise M_FALSE on error.

◆ M_tls_clientctx_set_ciphers()

M_bool M_tls_clientctx_set_ciphers	(	M_tls_clientctx_t *	ctx,
		const char *	ciphers
	)

Set the ciphers that the context should support.

A default list of secure ciphers is used if it is not explicitly changed by this function.

Parameters

[in]	ctx	Client context.
[in]	ciphers	OpenSSL cipher string.

See also: M_tls_clientctx_get_cipherlist

◆ M_tls_clientctx_set_cert()

M_bool M_tls_clientctx_set_cert	(	M_tls_clientctx_t *	ctx,
		const unsigned char *	key,
		size_t	key_len,
		const unsigned char *	crt,
		size_t	crt_len,
		const unsigned char *	intermediate,
		size_t	intermediate_len
	)

◆ M_tls_clientctx_set_cert_files()

M_bool M_tls_clientctx_set_cert_files	(	M_tls_clientctx_t *	ctx,
		const char *	keypath,
		const char *	crtpath,
		const char *	intermediatepath
	)

◆ M_tls_clientctx_set_default_trust()

M_bool M_tls_clientctx_set_default_trust ( M_tls_clientctx_t * ctx )

Load the OS CA trust list for validating the certificate presented by the server.

This will not clear existing CAs that were already loaded.

Parameters

[in] ctx Client context.

Returns: M_TRUE on success, otherwise M_FALSE on error.

◆ M_tls_clientctx_set_trust_ca()

M_bool M_tls_clientctx_set_trust_ca	(	M_tls_clientctx_t *	ctx,
		const unsigned char *	ca,
		size_t	len
	)

Load a CA certificate for validating the certificate presented by the server.

This will not clear existing CAs that were already loaded.

Parameters

[in]	ctx	Client context.
[in]	ca	CA data.
[in]	len	CA length.

Returns: M_TRUE on success, otherwise M_FALSE on error.

◆ M_tls_clientctx_set_trust_ca_file()

M_bool M_tls_clientctx_set_trust_ca_file	(	M_tls_clientctx_t *	ctx,
		const char *	path
	)

Load a CA certificate from a file for validating the certificate presented by the server.

This will not clear existing CAs that were already loaded.

Parameters

[in]	ctx	Client context.
[in]	path

Returns: M_TRUE on success, otherwise M_FALSE on error.

◆ M_tls_clientctx_set_trust_ca_dir()

M_bool M_tls_clientctx_set_trust_ca_dir	(	M_tls_clientctx_t *	ctx,
		const char *	path
	)

Load CA certificates found in a directory for validating the certificate presented by the server.

Files must be PEM encoded and use the ".pem" extension.

This will not clear existing CAs that were already loaded.

Parameters

[in]	ctx	Client context.
[in]	path	Path to CA file.

Returns: M_TRUE on success, otherwise M_FALSE on error.

See also: M_tls_clientctx_set_trust_ca

◆ M_tls_clientctx_set_trust_cert()

M_bool M_tls_clientctx_set_trust_cert	(	M_tls_clientctx_t *	ctx,
		const unsigned char *	crt,
		size_t	len
	)

Load a certificate for validation of the certificate presented by the server.

This is for loading intermediate certificate used as part of the trust chain.

This will not clear existing certificates that were already loaded.

Parameters

[in]	ctx	Client context.
[in]	crt	Certificate.
[in]	len	Certificate length.

Returns: M_TRUE on success, otherwise M_FALSE on error.

◆ M_tls_clientctx_set_trust_cert_file()

M_bool M_tls_clientctx_set_trust_cert_file	(	M_tls_clientctx_t *	ctx,
		const char *	path
	)

Load a certificate from a file for validation of the certificate presented by the server.

This is for loading intermediate certificate used as part of the trust chain.

This will not clear existing certificates that were already loaded.

Parameters

[in]	ctx	Client context.
[in]	path	Path to certificate file.

Returns: M_TRUE on success, otherwise M_FALSE on error.

See also: M_tls_clientctx_set_trust_cert

◆ M_tls_clientctx_set_verify_level()

M_bool M_tls_clientctx_set_verify_level	(	M_tls_clientctx_t *	ctx,
		M_tls_verify_level_t	level
	)

◆ M_tls_clientctx_set_session_resumption()

M_bool M_tls_clientctx_set_session_resumption	(	M_tls_clientctx_t *	ctx,
		M_bool	enable
	)

Enable or disable session resumption.

Session resumption is enabled by default.

Parameters

[in]	ctx	Client context.
[in]	enable	M_TRUE to enable. M_FALSE to disable.

Returns: M_TRUE on success, otherwise M_FALSE on error.

◆ M_tls_clientctx_get_cipherlist()

char * M_tls_clientctx_get_cipherlist ( M_tls_clientctx_t * ctx )

Retrieves a colon separated list of ciphers that are enabled.

Parameters

[in] ctx Client context.

Returns: String.

◆ M_tls_clientctx_set_applications()

M_bool M_tls_clientctx_set_applications	(	M_tls_clientctx_t *	ctx,
		M_list_str_t *	applications
	)

Set ALPN supported applications.

Parameters

[in]	ctx	Client context.
[in]	applications	List of supported applications.

Returns: M_TRUE on success, otherwise M_FALSE on error.

◆ M_tls_clientctx_set_negotiation_timeout_ms()

M_bool M_tls_clientctx_set_negotiation_timeout_ms	(	M_tls_clientctx_t *	ctx,
		M_uint64	timeout_ms
	)

Set the negotiation timeout.

How long the client should wait to establish a connection.

Parameters

[in]	ctx	Client context.
[in]	timeout_ms	Time in milliseconds.

Returns: M_TRUE on success, otherwise M_FALSE on error.

◆ M_io_tls_client_add()

M_io_error_t M_io_tls_client_add	(	M_io_t *	io,
		M_tls_clientctx_t *	ctx,
		const char *	hostname,
		size_t *	layer_id
	)

Wrap existing IO channel with TLS.

Parameters

[in]	io	io object.
[in]	ctx	Client context.
[in]	hostname	Hostname is optional if wrapping an outbound network connection where it can be retrieved from the lower layer
[out]	layer_id	Layer id this is added at.

Returns: Result.

◆ M_tls_serverctx_create()

M_tls_serverctx_t * M_tls_serverctx_create	(	const unsigned char *	key,
		size_t	key_len,
		const unsigned char *	crt,
		size_t	crt_len,
		const unsigned char *	intermediate,
		size_t	intermediate_len
	)

Create a server TLS context.

Parameters

[in]	key	Private key associated with certificate.
[in]	key_len	Length of private key.
[in]	crt	Certificate.
[in]	crt_len	Length of certificate.
[in]	intermediate	Intermediate certificate chain. Can be NULL.
[in]	intermediate_len	Length of intermediate certificate chain.

Returns: Server context.

◆ M_tls_serverctx_create_from_files()

M_tls_serverctx_t * M_tls_serverctx_create_from_files	(	const char *	keypath,
		const char *	crtpath,
		const char *	intermediatepath
	)

Create a server TLS context from files.

Parameters

[in]	keypath	Path to key file.
[in]	crtpath	Path to certificate file.
[in]	intermediatepath	Path to intermediate certificate file. Can be NULL.

Returns: Server context.

◆ M_tls_serverctx_upref()

M_bool M_tls_serverctx_upref ( M_tls_serverctx_t * ctx )

Increment reference counters.

Intended for APIs that might take ownership. Can only be Dereferenced via M_tls_serverctx_destroy()

Parameters

[in] ctx Server context.

Returns: M_TRUE on success, otherwise M_FALSE on error.

◆ M_tls_serverctx_destroy()

void M_tls_serverctx_destroy ( M_tls_serverctx_t * ctx )

Destroy a server context.

Server CTXs use reference counters, and will delay destruction until after last consumer is destroyed.

Parameters

[in] ctx Server context.

◆ M_tls_serverctx_SNI_ctx_add()

M_bool M_tls_serverctx_SNI_ctx_add	(	M_tls_serverctx_t *	ctx,
		M_tls_serverctx_t *	child
	)

Add a sub context under this one to allow multiple certificates to be used with SNI.

For SNI support, if a certificate does not list a subject alt name, a server context needs to be created for each certificate. The certificate to be used as the default when the client does not support SNI will be the parent context. All of the additional contexts are added to this one.

This is not necessary if a certificate lists all expected host names as subject alt names.

Parameters

[in]	ctx	Server context.
[in]	child	Child server context.

Returns: M_TRUE on success, otherwise M_FALSE on error.

◆ M_tls_serverctx_SNI_count()

size_t M_tls_serverctx_SNI_count ( M_tls_serverctx_t * ctx )

Number of child contexts associated with this server context used for SNI.

Parameters

[in] ctx Server context.

Returns: Count.

See also: M_tls_serverctx_SNI_at

◆ M_tls_serverctx_SNI_lookup()

M_tls_serverctx_t * M_tls_serverctx_SNI_lookup	(	M_tls_serverctx_t *	ctx,
		const char *	hostname
	)

Get a child SNI context from a context based on host name.

Parameters

[in]	ctx	Server context.
[in]	hostname	Host name to look for.

Returns: Server context on success, otherwise NULL if not found.

◆ M_tls_serverctx_SNI_at()

M_tls_serverctx_t * M_tls_serverctx_SNI_at	(	M_tls_serverctx_t *	ctx,
		size_t	idx
	)

Get a child SNI context from a context at a given index.

Parameters

[in]	ctx	Server context.
[in]	idx	Index.

Returns: Server context on success, otherwise NULL on error.

See also: M_tls_serverctx_SNI_count

◆ M_tls_serverctx_get_cert()

char * M_tls_serverctx_get_cert ( M_tls_serverctx_t * ctx )

◆ M_tls_serverctx_set_protocols()

M_bool M_tls_serverctx_set_protocols	(	M_tls_serverctx_t *	ctx,
		int	protocols
	)

Set the TLS protocols that the context should use.

Parameters

[in]	ctx	Server context.
[in]	protocols	M_tls_protocols_t bitmap of TLS protocols that should be supported. Protocols are treated as min and max. For example if TLSv1.0 and TLSv1.2 are enabled, then TLSv1.1 will be enabled even if not explicitly set.

Returns: M_TRUE on success, otherwise M_FALSE on error.

◆ M_tls_serverctx_set_ciphers()

M_bool M_tls_serverctx_set_ciphers	(	M_tls_serverctx_t *	ctx,
		const char *	ciphers
	)

Set the ciphers that the context should support.

A default list of secure ciphers is used if it is not explicitly changed by this function.

Parameters

[in]	ctx	Server context.
[in]	ciphers	OpenSSL cipher string.

See also: M_tls_clientctx_get_cipherlist

◆ M_tls_serverctx_set_server_preference()

M_bool M_tls_serverctx_set_server_preference	(	M_tls_serverctx_t *	ctx,
		M_bool	tf
	)

Set the server to prefer its own cipher order rather than the client.

By default, the client cipher order is preferred, this is recommended as a client may be a mobile device where a cipher like TLS_CHACHA20_POLY1305_SHA256 is more efficient than TLS_AES_256_GCM_SHA384 and will provide a better customer experience. However a desktop client may prefer TLS_AES_256_GCM_SHA384 as it supports AES-NI instruction helpers or similar. Since the server is often more powerful than the client, it is better suited to the additional compute.

Assuming the server is configured to only allow strong ciphers, there should be no security risk in allowing the client to decide the most efficient.

Parameters

[in]	ctx	Server context.
[in]	tf	M_TRUE to enable server preference, M_FALSE to disable.

See also: M_tls_clientctx_get_cipherlist

◆ M_tls_serverctx_set_trust_ca()

M_bool M_tls_serverctx_set_trust_ca	(	M_tls_serverctx_t *	ctx,
		const unsigned char *	ca,
		size_t	len
	)

Load a CA certificate for validating the certificate presented by the client.

If set the client will be required to present a certificate.

This will not clear existing CAs that were already loaded.

Parameters

[in]	ctx	Server context.
[in]	ca	CA data.
[in]	len	CA length.

Returns: M_TRUE on success, otherwise M_FALSE on error.

◆ M_tls_serverctx_set_trust_ca_file()

M_bool M_tls_serverctx_set_trust_ca_file	(	M_tls_serverctx_t *	ctx,
		const char *	path
	)

Load a CA certificate from a file for validating the certificate presented by the client.

This will not clear existing CAs that were already loaded.

Parameters

[in]	ctx	Server context.
[in]	path	Path to CA file.

Returns: M_TRUE on success, otherwise M_FALSE on error.

See also: M_tls_serverctx_set_trust_ca

◆ M_tls_serverctx_set_trust_ca_dir()

M_bool M_tls_serverctx_set_trust_ca_dir	(	M_tls_serverctx_t *	ctx,
		const char *	path
	)

Load a certificate for validation of the certificate presented by the client.

This is for loading intermediate certificate used as part of the trust chain.

This will not clear existing certificates that were already loaded.

Parameters

[in]	ctx	Server context.
[in]	path	Path to CA directory.

Returns: M_TRUE on success, otherwise M_FALSE on error.

See also: M_tls_serverctx_set_trust_ca

◆ M_tls_serverctx_set_trust_cert()

M_bool M_tls_serverctx_set_trust_cert	(	M_tls_serverctx_t *	ctx,
		const unsigned char *	crt,
		size_t	len
	)

Load a certificate for validation of the certificate presented by the client.

This is for loading intermediate certificate used as part of the trust chain.

This will not clear existing certificates that were already loaded.

Parameters

[in]	ctx	Server context.
[in]	crt	Certificate.
[in]	len	Certificate length.

Returns: M_TRUE on success, otherwise M_FALSE on error.

◆ M_tls_serverctx_set_trust_cert_file()

M_bool M_tls_serverctx_set_trust_cert_file	(	M_tls_serverctx_t *	ctx,
		const char *	path
	)

Load a certificate from a file for validation of the certificate presented by the client.

This is for loading intermediate certificate used as part of the trust chain.

This will not clear existing certificates that were already loaded.

Parameters

[in]	ctx	Server context.
[in]	path	Path to certificate file.

Returns: M_TRUE on success, otherwise M_FALSE on error.

See also: M_tls_serverctx_set_trust_cert

◆ M_tls_serverctx_add_trust_crl()

M_bool M_tls_serverctx_add_trust_crl	(	M_tls_serverctx_t *	ctx,
		const unsigned char *	crl,
		size_t	len
	)

Load a certificate revocation list to validate the certificate presented by the client.

This will not clear existing revocations already loaded.

Parameters

[in]	ctx	Server context.
[in]	crl	CRL.
[in]	len	CRL Length.

Returns: M_TRUE on success, otherwise M_FALSE on error.

◆ M_tls_serverctx_add_trust_crl_file()

M_bool M_tls_serverctx_add_trust_crl_file	(	M_tls_serverctx_t *	ctx,
		const char *	path
	)

Load a certificate revocation from a file list to validate the certificate presented by the client.

This will not clear existing revocations already loaded.

Parameters

[in]	ctx	Server context.
[in]	path	Path to certificate revocation list file.

Returns: M_TRUE on success, otherwise M_FALSE on error.

See also: M_tls_serverctx_set_trust_cert_file

◆ M_tls_serverctx_set_dhparam()

M_bool M_tls_serverctx_set_dhparam	(	M_tls_serverctx_t *	ctx,
		const unsigned char *	dhparam,
		size_t	dhparam_len
	)

Set the dhparam for the context.

If not set, uses internal 2236 dhparam. DHparam data must be PEM-encoded.

Parameters

[in]	ctx	Server context.
[in]	dhparam	DHparam data. If dhparam is NULL, disables the use of DHE negotiation.
[in]	dhparam_len	Length of data.

Returns: M_TRUE on success, otherwise M_FALSE on error.

◆ M_tls_serverctx_set_dhparam_file()

M_bool M_tls_serverctx_set_dhparam_file	(	M_tls_serverctx_t *	ctx,
		const char *	dhparam_path
	)

Set the dhparam for the context from a file.

If not set, uses internal 2236 dhparam. DHparam data must be PEM-encoded.

Parameters

[in]	ctx	Server context.
[in]	dhparam_path	Path to DHparam data.

Returns: M_TRUE on success, otherwise M_FALSE on error.

See also: M_tls_serverctx_set_dhparam

◆ M_tls_serverctx_set_session_resumption()

M_bool M_tls_serverctx_set_session_resumption	(	M_tls_serverctx_t *	ctx,
		M_bool	enable
	)

Enable or disable session resumption.

Session resumption is enabled by default.

Parameters

[in]	ctx	Server context.
[in]	enable	M_TRUE to enable. M_FALSE to disable.

Returns: M_TRUE on success, otherwise M_FALSE on error.

◆ M_tls_serverctx_get_cipherlist()

char * M_tls_serverctx_get_cipherlist ( M_tls_serverctx_t * ctx )

Retrieves a colon separated list of ciphers that are enabled.

Parameters

[in] ctx Server context.

Returns: String.

◆ M_tls_serverctx_set_applications()

M_bool M_tls_serverctx_set_applications	(	M_tls_serverctx_t *	ctx,
		M_list_str_t *	applications
	)

Set ALPN supported applications.

Parameters

[in]	ctx	Server context.
[in]	applications	List of supported applications.

Returns: M_TRUE on success, otherwise M_FALSE on error.

◆ M_tls_serverctx_set_negotiation_timeout_ms()

M_bool M_tls_serverctx_set_negotiation_timeout_ms	(	M_tls_serverctx_t *	ctx,
		M_uint64	timeout_ms
	)

Set the negotiation timeout.

How long the server should wait to establish a connection.

Parameters

[in]	ctx	Server context.
[in]	timeout_ms	Time in milliseconds.

Returns: M_TRUE on success, otherwise M_FALSE on error.

◆ M_io_tls_server_add()

M_io_error_t M_io_tls_server_add	(	M_io_t *	io,
		M_tls_serverctx_t *	ctx,
		size_t *	layer_id
	)

Wrap existing IO channel with TLS.

Parameters

[in]	io	io object.
[in]	ctx	Server context.
[out]	layer_id	Layer id this is added at.

Returns: Result.

◆ M_tls_server_get_hostname()

const char * M_tls_server_get_hostname	(	M_io_t *	io,
		size_t	id
	)

Get the host name the connected client requested.

Parameters

[in]	io	io object.
[in]	id	Layer id.

Returns: String.

◆ M_tls_get_protocol()

M_tls_protocols_t M_tls_get_protocol	(	M_io_t *	io,
		size_t	id
	)

Get the protocol the connection was establish with.

Parameters

[in]	io	io object.
[in]	id	Layer id.

Returns: Protocol.

◆ M_tls_get_sessionreused()

M_bool M_tls_get_sessionreused	(	M_io_t *	io,
		size_t	id
	)

Was the session for this connection reused from a previous connection?

Parameters

[in]	io	io object.
[in]	id	Layer id.

Returns: M_TRUE if reused, otherwise M_FALSE.

◆ M_tls_get_cipher()

const char * M_tls_get_cipher	(	M_io_t *	io,
		size_t	id
	)

Get the cipher negotiated.

Parameters

[in]	io	io object.
[in]	id	Layer id.

Returns: String.

◆ M_tls_get_application()

char * M_tls_get_application	(	M_io_t *	io,
		size_t	id
	)

Get the application negotiated.

Parameters

[in]	io	io object.
[in]	id	Layer id.

Returns: NULL if there is no ALPN support or on error, or will return the application.

◆ M_tls_get_peer_cert()

char * M_tls_get_peer_cert	(	M_io_t *	io,
		size_t	id
	)

Get the certificate presented by the other end.

Parameters

[in]	io	io object.
[in]	id	Layer id.

Returns: X509 PEM encoded certificate.

◆ M_tls_get_negotiation_time_ms()

M_uint64 M_tls_get_negotiation_time_ms	(	M_io_t *	io,
		size_t	id
	)

How long negotiated took.

Parameters

[in]	io	io object.
[in]	id	Layer id.

Returns: Negotiation time (success or fail) in ms

◆ M_tls_protocols_to_str()

const char * M_tls_protocols_to_str ( M_tls_protocols_t protocol )

Convert a protocol to string.

Only single protocol should be specified. If multiple are provided it is undefined which will be returned. Used primarily for logging to print what protocol a connection is using.

Parameters

[in] protocol

Returns: String.

◆ M_tls_protocols_from_str()

M_tls_protocols_t M_tls_protocols_from_str ( const char * protocols_str )

Convert a string to protocols bitmap

The value for this field is a space separated list of protocols. Valid protocols are: tlsv1, tlsv1.0, tlsv1.1, tlsv1.2, tlsv1.3.

Entry tlsv1 implies all tls 1.y protocols.

If the protocol is appended with a plus (+) sign, then it means that protocol version or higher, for instance, "tlsv1.1+" implies "tlsv1.1 tlsv1.2 tlsv1.3"

Protocols are treated as min and max. Enabling protocols with version gaps will result in the gaps being enabled. E.g. specifying "tlsv1.0 tlsv1.2" will enable tlsv1.0, tlsv1.1, and tlsv1.2.

Unknown entries will be ignored. Protocols that are not supported by the backend will be removed from the list of returned protocols.

Parameters

[in] protocols_str String of protocols

Returns: Protocol bitmap. M_TLS_PROTOCOL_INVALID on error.

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ M_tls_clientctx_t

◆ M_tls_serverctx_t

Enumeration Type Documentation

◆ M_tls_protocols_t

◆ M_tls_verify_level_t

◆ M_tls_init_t

Function Documentation

◆ M_tls_init()

◆ M_tls_clientctx_create()

◆ M_tls_clientctx_upref()

◆ M_tls_clientctx_destroy()

◆ M_tls_clientctx_set_protocols()

◆ M_tls_clientctx_set_ciphers()

◆ M_tls_clientctx_set_cert()

◆ M_tls_clientctx_set_cert_files()

◆ M_tls_clientctx_set_default_trust()

◆ M_tls_clientctx_set_trust_ca()

◆ M_tls_clientctx_set_trust_ca_file()

◆ M_tls_clientctx_set_trust_ca_dir()

◆ M_tls_clientctx_set_trust_cert()

◆ M_tls_clientctx_set_trust_cert_file()

◆ M_tls_clientctx_set_verify_level()

◆ M_tls_clientctx_set_session_resumption()

◆ M_tls_clientctx_get_cipherlist()

◆ M_tls_clientctx_set_applications()

◆ M_tls_clientctx_set_negotiation_timeout_ms()

◆ M_io_tls_client_add()

◆ M_tls_serverctx_create()

◆ M_tls_serverctx_create_from_files()

◆ M_tls_serverctx_upref()

◆ M_tls_serverctx_destroy()

◆ M_tls_serverctx_SNI_ctx_add()

◆ M_tls_serverctx_SNI_count()

◆ M_tls_serverctx_SNI_lookup()

◆ M_tls_serverctx_SNI_at()

◆ M_tls_serverctx_get_cert()

◆ M_tls_serverctx_set_protocols()

◆ M_tls_serverctx_set_ciphers()

◆ M_tls_serverctx_set_server_preference()

◆ M_tls_serverctx_set_trust_ca()

◆ M_tls_serverctx_set_trust_ca_file()

◆ M_tls_serverctx_set_trust_ca_dir()

◆ M_tls_serverctx_set_trust_cert()

◆ M_tls_serverctx_set_trust_cert_file()

◆ M_tls_serverctx_add_trust_crl()

◆ M_tls_serverctx_add_trust_crl_file()

◆ M_tls_serverctx_set_dhparam()

◆ M_tls_serverctx_set_dhparam_file()

◆ M_tls_serverctx_set_session_resumption()

◆ M_tls_serverctx_get_cipherlist()

◆ M_tls_serverctx_set_applications()

◆ M_tls_serverctx_set_negotiation_timeout_ms()

◆ M_io_tls_server_add()

◆ M_tls_server_get_hostname()

◆ M_tls_get_protocol()

◆ M_tls_get_sessionreused()

◆ M_tls_get_cipher()

◆ M_tls_get_application()

◆ M_tls_get_peer_cert()

◆ M_tls_get_negotiation_time_ms()

◆ M_tls_protocols_to_str()

◆ M_tls_protocols_from_str()