Functions for managing the SSL context. More...

#include "he_internal.h"

Include dependency graph for ssl_ctx.h:

Functions
he_return_code_t	he_init (void)
	Initialises Helium global state. More...

he_return_code_t	he_cleanup (void)
	Cleans up all Helium global state. More...

he_return_code_t	he_ssl_ctx_is_valid_client (he_ssl_ctx_t *ctx)
	Checks whether the client context has the basic configuration to allow Helium to connect. More...

he_return_code_t	he_ssl_ctx_is_valid_server (he_ssl_ctx_t *ctx)
	Checks whether the server context has the basic configuration to allow Helium to connect. More...

he_ssl_ctx_t *	he_ssl_ctx_create (void)
	Creates a Helium SSL context. More...

void	he_ssl_ctx_destroy (he_ssl_ctx_t *ctx)
	Releases all memory allocate by Helium for this context. More...

he_return_code_t	he_ssl_ctx_start (he_ssl_ctx_t *context)
	Sets up all internal state so that client connections can be created. More...

he_return_code_t	he_ssl_ctx_start_server (he_ssl_ctx_t *context)
	Sets up all internal state so that server connections can be created. More...

he_return_code_t	he_ssl_ctx_stop (he_ssl_ctx_t *context)
	Try to cleanly stop the SSL context. More...

he_return_code_t	he_ssl_ctx_set_minimum_supported_version (he_ssl_ctx_t *context, uint8_t major_version, uint8_t minor_version)
	Set the minimum supported wire protocol version by this SSL context. More...

he_return_code_t	he_ssl_ctx_set_maximum_supported_version (he_ssl_ctx_t *context, uint8_t major_version, uint8_t minor_version)
	Set the maximum supported wire protocol version by this SSL context. More...

bool	he_ssl_ctx_is_supported_version (he_ssl_ctx_t *context, uint8_t major_version, uint8_t minor_version)
	Validate whether a major/minor version is supported by this SSL context. More...

bool	he_ssl_ctx_is_latest_version (he_ssl_ctx_t *context, uint8_t major_version, uint8_t minor_version)
	Validate whether the major/minor version is the latest. More...

he_return_code_t	he_ssl_ctx_set_server_dn (he_ssl_ctx_t ctx, const char distinguished_name)
	Set the expected Distinguished Name (DN) of the server. More...

const char *	he_ssl_ctx_get_server_dn (he_ssl_ctx_t *ctx)
	Get the Distinguished Name that Helium will use to verify the server's certificate. More...

bool	he_ssl_ctx_is_server_dn_set (he_ssl_ctx_t *ctx)
	Check if the server DN has been set. More...

he_return_code_t	he_ssl_ctx_set_use_chacha20 (he_ssl_ctx_t *ctx, bool use)
	Tell Helium to use CHACHA20 and Poly1305 instead of AES and SHA based encryption and authentication. More...

bool	he_ssl_ctx_get_use_chacha20 (he_ssl_ctx_t *ctx)
	Returns whether CHACHA20 is enabled or not. More...

he_return_code_t	he_ssl_ctx_set_ca (he_ssl_ctx_t ctx, uint8_t cert_buffer, size_t length)
	Set the location and size of the CA certificate chain. More...

bool	he_ssl_ctx_is_ca_set (he_ssl_ctx_t *ctx)
	Check if the CA has been set. More...

he_return_code_t	he_ssl_ctx_set_server_cert_key_files (he_ssl_ctx_t ctx, const char server_cert, const char *server_key)
	Set the server cert and keys.

bool	he_ssl_ctx_is_server_cert_key_set (he_ssl_ctx_t *ctx)
	Whether the server cert and keys have been set.

he_return_code_t	he_ssl_ctx_set_connection_type (he_ssl_ctx_t *ctx, he_connection_type_t connection_type)
	Set the connection type. More...

void	he_ssl_ctx_set_state_change_cb (he_ssl_ctx_t *ctx, he_state_change_cb_t state_change_cb)
	Sets the function that should be called on Helium state changes. More...

bool	he_ssl_ctx_is_state_change_cb_set (he_ssl_ctx_t *ctx)
	Check if the state change callback has been set. More...

void	he_ssl_ctx_set_inside_write_cb (he_ssl_ctx_t *ctx, he_inside_write_cb_t inside_write_cb)
	Sets the function that will be called when Helium needs to do an inside write. More...

bool	he_ssl_ctx_is_inside_write_cb_set (he_ssl_ctx_t *ctx)
	Check if the inside write callback has been set. More...

void	he_ssl_ctx_set_outside_write_cb (he_ssl_ctx_t *ctx, he_outside_write_cb_t outside_write_cb)
	Sets the function that will be called when Helium needs to do an outside write. More...

he_return_code_t	he_conn_outside_data_received (he_conn_t conn, uint8_t buffer, size_t length)
	Called when the host application needs to deliver outside data to be processed by Helium. More...

bool	he_ssl_ctx_is_outside_write_cb_set (he_ssl_ctx_t *ctx)
	Check if the outside write callback has been set. More...

void	he_ssl_ctx_set_network_config_ipv4_cb (he_ssl_ctx_t *ctx, he_network_config_ipv4_cb_t network_config_cb)
	Sets the function that will be called when Helium needs to pass network ctx to the host application. More...

bool	he_ssl_ctx_is_network_config_ipv4_cb_set (he_ssl_ctx_t *ctx)
	Check if the network ctx callback has been set. More...

void	he_ssl_ctx_set_server_config_cb (he_ssl_ctx_t *ctx, he_server_config_cb_t server_config_cb)
	Sets the function that will be called when Helium needs to pass server config to the host application. More...

void	he_ssl_ctx_set_nudge_time_cb (he_ssl_ctx_t *ctx, he_nudge_time_cb_t nudge_time_cb)
	Sets the function that will be called when Helium needs to update the nudge time. More...

bool	he_ssl_ctx_is_nudge_time_cb_set (he_ssl_ctx_t *ctx)
	Check if the nudge time callback has been set. More...

void	he_ssl_ctx_set_event_cb (he_ssl_ctx_t *ctx, he_event_cb_t event_cb)
	Sets the function that will be called when Helium needs to pass an event to the host application. More...

void	he_ssl_ctx_set_auth_cb (he_ssl_ctx_t *ctx, he_auth_cb_t auth_cb)
	Sets the function that will be called when Helium needs to authenticate a user. More...

void	he_ssl_ctx_set_auth_token_cb (he_ssl_ctx_t *ctx, he_auth_token_cb_t auth_token_cb)
	Sets the function that will be called when Helium needs to authenticate a user. More...

void	he_ssl_ctx_set_auth_buf_cb (he_ssl_ctx_t *ctx, he_auth_buf_cb_t auth_buf_cb)
	Sets the function that will be called when Helium needs to authenticate a user. More...

bool	he_ssl_ctx_is_auth_cb_set (he_ssl_ctx_t *ctx)
	Check if at least one auth callback has been set. More...

void	he_ssl_ctx_set_populate_network_config_ipv4_cb (he_ssl_ctx_t *ctx, he_populate_network_config_ipv4_cb_t pop_network_cb)
	Sets the function that will be called when Helium needs to provide network ctx to a client. More...

void	he_ssl_ctx_set_pmtud_state_change_cb (he_ssl_ctx_t *ctx, he_pmtud_state_change_cb_t pmtud_state_change_cb)
	Sets the function that will be called when Lightway PMTUD changes state. More...

void	he_ssl_ctx_set_pmtud_time_cb (he_ssl_ctx_t *ctx, he_pmtud_time_cb_t pmtud_time_cb)
	Sets the function that will be called when Lightway PMTUD needs to start the timer. More...

he_return_code_t	he_ssl_ctx_set_disable_roaming (he_ssl_ctx_t *ctx)
	Disables session roaming and removes the session ID from the packet header. More...

bool	he_ssl_ctx_is_roaming_disabled (he_ssl_ctx_t *ctx)
	Check if roaming has been disabled. More...

he_return_code_t	he_ssl_ctx_set_padding_type (he_ssl_ctx_t *ctx, he_padding_type_t padding_type)
	Sets the padding mode and hence the level of padding (if any) to be used. More...

he_padding_type_t	he_ssl_ctx_get_padding_type (he_ssl_ctx_t *ctx)
	Returns the current padding mode. More...

he_return_code_t	he_ssl_ctx_set_aggressive_mode (he_ssl_ctx_t *ctx)
	Sets the client to aggressive mode, where it will send each message three times to help improve the chances of a faster connection and greater throughput despite packet drops in D/TLS mode. More...

he_return_code_t	he_ssl_ctx_set_use_pqc (he_ssl_ctx_t *ctx, bool enabled)
	Sets the client to use PQC Keyshares. More...

he_return_code_t	he_ssl_ctx_set_max_frag_entries (he_ssl_ctx_t *ctx, size_t max_frag_entries)
	Sets the maximum number of entries the connection can use for reassembling fragments. More...

Detailed Description

Functions for managing the SSL context.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

Function Documentation

◆ he_cleanup()

he_return_code_t he_cleanup ( void )

Cleans up all Helium global state.

Returns: HE_SUCCESS clean up successful; HE_INIT_FAILED Couldn't clean up global state

This cleans up any global state that Helium used.

@caution Do not call any Helium function after calling this apart from he_init()

See also: he_init()

◆ he_conn_outside_data_received()

he_return_code_t he_conn_outside_data_received	(	he_conn_t *	conn,
		uint8_t *	buffer,
		size_t	length
	)

Called when the host application needs to deliver outside data to be processed by Helium.

Parameters

conn	A valid Helium connection
buffer	A pointer to the packet data
length	The length of the packet

Returns: HE_ERR_NULL_POINTER The pointer provided is a NULL pointer; HE_ERR_PACKET_TOO_SMALL The packet is too small to be a valid Helium packet; HE_ERR_NOT_HE_PACKET The packet is not a Helium packet (it does not have the Helium header); HE_ERR_SSL_ERROR Something went wrong decrypting the packet - this is a FATAL error for the connection; HE_ERR_SERVER_DN_MISMATCH The name in the server's cert did not match local configuration; HE_ERR_CANNOT_VERIFY_SERVER_CERT The server certificate couldn't be verified using the configured CA Cert; HE_ERR_SERVER_GOODBYE The server sent a goodbye message and the client should disconnect and try to connect a different server; HE_SUCCESS The packet was processed normally.

Note: These error codes may change before final release as new issues come to light.; If the conn has registered plugins, they may arbitrarily change the packet data, but are restricted here to not exceeding the provided length. Users who wish to have more control over this should not register plugins upon connection, but instead call the plugin API explicitly prior to invoking this function.

Parameters

conn	A valid Helium connection
buffer	A pointer to the packet data
length	The length of the packet

Returns: HE_ERR_NULL_POINTER The pointer provided is a NULL pointer; HE_ERR_PACKET_TOO_SMALL The packet is too small to be a valid Helium packet; HE_ERR_NOT_HE_PACKET The packet is not a Helium packet (it does not have the Helium header); HE_ERR_SSL_ERROR Something went wrong decrypting the packet - this is a FATAL error for the connection; HE_ERR_SERVER_DN_MISMATCH The name in the server's cert did not match local configuration; HE_ERR_CANNOT_VERIFY_SERVER_CERT The server certificate couldn't be verified using the configured CA Cert; HE_SUCCESS The packet was processed normally.

Note: These error codes may change before final release as new issues come to light.; If the conn has registered plugins, they may arbitrarily change the packet data, but are restricted here to not exceeding the provided length. Users who wish to have more control over this should not register plugins upon connection, but instead call the plugin API explicitly prior to invoking this function.

Streaming Stuff

◆ he_init()

he_return_code_t he_init ( void )

Initialises Helium global state.

Returns: HE_SUCCESS Initialisation successful; HE_INIT_FAILED Fatal error - couldn't initialise global state

Helium doesn't itself use global state at present, however the underlying crypto library does. To keep things clean so that Helium can be totally cleaned out of a process, init and cleanup functions were added.

@caution Call this first before any other Helium function!

See also: he_cleanup()

◆ he_ssl_ctx_create()

he_ssl_ctx_t* he_ssl_ctx_create ( void )

Creates a Helium SSL context.

Returns: he_ssl_ctx_t* Returns a pointer to a valid Helium context ctx

Note: This function allocates memory

This function must be called to create the initial Helium SSL context for use with other functions

◆ he_ssl_ctx_destroy()

void he_ssl_ctx_destroy ( he_ssl_ctx_t * ctx )

Releases all memory allocate by Helium for this context.

Parameters

ctx	A pointer to a valid SSL context

Note: Make sure all connections created from this context are destroyed before calling this function; once this function is called their behaviour is undefined.

◆ he_ssl_ctx_get_padding_type()

he_padding_type_t he_ssl_ctx_get_padding_type ( he_ssl_ctx_t * ctx )

Returns the current padding mode.

Returns: he_padding_type_t

◆ he_ssl_ctx_get_server_dn()

const char* he_ssl_ctx_get_server_dn ( he_ssl_ctx_t * ctx )

Get the Distinguished Name that Helium will use to verify the server's certificate.

Parameters

ctx	A pointer to a valid SSL context

Returns: const char* A pointer to the distinguished name

◆ he_ssl_ctx_get_use_chacha20()

bool he_ssl_ctx_get_use_chacha20 ( he_ssl_ctx_t * ctx )

Returns whether CHACHA20 is enabled or not.

Parameters

ctx	A pointer to a valid SSL context

Returns: bool Whether CHACHA20 is enabled or not

◆ he_ssl_ctx_is_auth_cb_set()

bool he_ssl_ctx_is_auth_cb_set ( he_ssl_ctx_t * ctx )

Check if at least one auth callback has been set.

Parameters

ctx	A pointer to a valid SSL context

Returns: bool Returns true or false depending on whether it has been set

◆ he_ssl_ctx_is_ca_set()

bool he_ssl_ctx_is_ca_set ( he_ssl_ctx_t * ctx )

Check if the CA has been set.

Parameters

ctx	A pointer to a valid SSL context

Returns: Returns true if the CA has been set, false otherwise

◆ he_ssl_ctx_is_inside_write_cb_set()

bool he_ssl_ctx_is_inside_write_cb_set ( he_ssl_ctx_t * ctx )

Check if the inside write callback has been set.

Parameters

ctx	A pointer to a valid SSL context

Returns: bool Returns true or false depending on whether it has been set

It is anticipated that this feature will be used for implementing UIs that don't maintain their own configuration state.

◆ he_ssl_ctx_is_latest_version()

bool he_ssl_ctx_is_latest_version	(	he_ssl_ctx_t *	context,
		uint8_t	major_version,
		uint8_t	minor_version
	)

Validate whether the major/minor version is the latest.

Parameters

context	A pointer to a valid SSL context
major_version	The major version to test
minor_version	The minor version to test

Returns: true if this major/minor version is the latest supported by this context

Note: There's no need for clients to use this function, they will always use the maximum

◆ he_ssl_ctx_is_network_config_ipv4_cb_set()

bool he_ssl_ctx_is_network_config_ipv4_cb_set ( he_ssl_ctx_t * ctx )

Check if the network ctx callback has been set.

Parameters

ctx	A pointer to a valid SSL context

Returns: bool Returns true or false depending on whether it has been set

It is anticipated that this feature will be used for implementing UIs that don't maintain their own configuration state.

◆ he_ssl_ctx_is_nudge_time_cb_set()

bool he_ssl_ctx_is_nudge_time_cb_set ( he_ssl_ctx_t * ctx )

Check if the nudge time callback has been set.

Parameters

ctx	A pointer to a valid SSL context

Returns: bool Returns true or false depending on whether it has been set

It is anticipated that this feature will be used for implementing UIs that don't maintain their own configuration state.

◆ he_ssl_ctx_is_outside_write_cb_set()

bool he_ssl_ctx_is_outside_write_cb_set ( he_ssl_ctx_t * ctx )

Check if the outside write callback has been set.

Parameters

ctx	A pointer to a valid SSL context

Returns: bool Returns true or false depending on whether it has been set

It is anticipated that this feature will be used for implementing UIs that don't maintain their own configuration state.

◆ he_ssl_ctx_is_roaming_disabled()

bool he_ssl_ctx_is_roaming_disabled ( he_ssl_ctx_t * ctx )

Check if roaming has been disabled.

Parameters

ctx	A pointer to a valid SSL context

Returns: bool Returns true or false depending on whether it has been set

It is anticipated that this feature will be used for implementing UIs that don't maintain their own configuration state.

◆ he_ssl_ctx_is_server_dn_set()

bool he_ssl_ctx_is_server_dn_set ( he_ssl_ctx_t * ctx )

Check if the server DN has been set.

Parameters

ctx	A pointer to a valid SSL context

Returns: bool Returns true or false depending on whether it has been set

It is anticipated that this feature will be used for implementing UIs that don't maintain their own configuration state.

◆ he_ssl_ctx_is_state_change_cb_set()

bool he_ssl_ctx_is_state_change_cb_set ( he_ssl_ctx_t * ctx )

Check if the state change callback has been set.

Parameters

ctx	A pointer to a valid SSL context

Returns: bool Returns true or false depending on whether it has been set

It is anticipated that this feature will be used for implementing UIs that don't maintain their own configuration state.

◆ he_ssl_ctx_is_supported_version()

bool he_ssl_ctx_is_supported_version	(	he_ssl_ctx_t *	context,
		uint8_t	major_version,
		uint8_t	minor_version
	)

Validate whether a major/minor version is supported by this SSL context.

Parameters

context	A pointer to a valid SSL context
major_version	The major version to test
minor_version	The minor version to test

Returns: true if this SSL context supports this major/minor version, false otherwise

Note: There's no need for clients to use this function, they will always use the maximum

◆ he_ssl_ctx_is_valid_client()

he_return_code_t he_ssl_ctx_is_valid_client ( he_ssl_ctx_t * ctx )

Checks whether the client context has the basic configuration to allow Helium to connect.

Parameters

ctx	A pointer to a valid SSL context configuration

Returns: HE_ERR_NULL_POINTER The ctx pointer supplied is NULL; HE_ERR_CONF_CA_NOT_SET The CA has not been set; HE_ERR_CONF_OUTSIDE_WRITE_CB_NOT_SET The outside write callback has not been set; HE_SUCCESS The basic configuration options have been set

Note: These return codes are similar to he_ssl_ctx_start because that function will call this function before attempting to connect.

◆ he_ssl_ctx_is_valid_server()

he_return_code_t he_ssl_ctx_is_valid_server ( he_ssl_ctx_t * ctx )

Checks whether the server context has the basic configuration to allow Helium to connect.

Parameters

ctx	A pointer to a valid SSL context configuration

Returns: HE_ERR_NULL_POINTER The ctx pointer supplied is NULL; HE_ERR_CONF_CA_NOT_SET The CA has not been set; HE_ERR_CONF_OUTSIDE_WRITE_CB_NOT_SET The outside write callback has not been set; HE_SUCCESS The basic configuration options have been set

Note: These return codes are similar to he_ssl_ctx_start_server because that function will call this function before attempting to connect.

◆ he_ssl_ctx_set_aggressive_mode()

he_return_code_t he_ssl_ctx_set_aggressive_mode ( he_ssl_ctx_t * ctx )

Sets the client to aggressive mode, where it will send each message three times to help improve the chances of a faster connection and greater throughput despite packet drops in D/TLS mode.

Returns: HE_SUCCESS Aggressive mode is enabled

◆ he_ssl_ctx_set_auth_buf_cb()

void he_ssl_ctx_set_auth_buf_cb	(	he_ssl_ctx_t *	ctx,
		he_auth_buf_cb_t	auth_buf_cb
	)

Sets the function that will be called when Helium needs to authenticate a user.

Parameters

ctx	A pointer to a valid SSL context
auth_buf_cb	The function to be called when Helium needs to authenticate a user

◆ he_ssl_ctx_set_auth_cb()

void he_ssl_ctx_set_auth_cb	(	he_ssl_ctx_t *	ctx,
		he_auth_cb_t	auth_cb
	)

Sets the function that will be called when Helium needs to authenticate a user.

Parameters

ctx	A pointer to a valid SSL context
auth_cb	The function to be called when Helium needs to authenticate a user

◆ he_ssl_ctx_set_auth_token_cb()

void he_ssl_ctx_set_auth_token_cb	(	he_ssl_ctx_t *	ctx,
		he_auth_token_cb_t	auth_token_cb
	)

Sets the function that will be called when Helium needs to authenticate a user.

Parameters

ctx	A pointer to a valid SSL context
auth_token_cb	The function to be called when Helium needs to authenticate a user

◆ he_ssl_ctx_set_ca()

he_return_code_t he_ssl_ctx_set_ca	(	he_ssl_ctx_t *	ctx,
		uint8_t *	cert_buffer,
		size_t	length
	)

Set the location and size of the CA certificate chain.

Parameters

ctx	A pointer to a valid SSL context
cert_buffer	A pointer to the location of the CA certificate chain in memory
length	The total size of the CA certificate chain

Returns: HE_SUCCESS CA has been set; HE_ERR_NULL_POINTER supplied cert_buffer was NULL; HE_ERR_ZERO_SIZE supplied length was 0

Note: The certificate chain should be in PEM format. Concatenated certificates (like you'd find in a .pem file) are supported.

◆ he_ssl_ctx_set_connection_type()

he_return_code_t he_ssl_ctx_set_connection_type	(	he_ssl_ctx_t *	ctx,
		he_connection_type_t	connection_type
	)

Set the connection type.

Parameters

ctx	A pointer to a valid SSL context
connection_type	A valid member of the he_connection_type_t ENUM

Returns: HE_SUCCESS Connection type has been set; HE_ERR_INVALID_CONNECTION_TYPE If an unknown connection type is passed

◆ he_ssl_ctx_set_disable_roaming()

he_return_code_t he_ssl_ctx_set_disable_roaming ( he_ssl_ctx_t * ctx )

Disables session roaming and removes the session ID from the packet header.

Returns: HE_SUCCESS This function removes the session ID from the external packet header so that an observer cannot follow the session across Internet connections. However Helium also will not be able to follow the connection and will trigger a session reject when a client changes source IP or port.

@caution This will hide the session ID but if the client's source port changes (such as a NAT timeout), the connection will be reset and reestablished.

◆ he_ssl_ctx_set_event_cb()

void he_ssl_ctx_set_event_cb	(	he_ssl_ctx_t *	ctx,
		he_event_cb_t	event_cb
	)

Sets the function that will be called when Helium needs to pass an event to the host application.

Parameters

ctx	A pointer to a valid SSL context
event_cb	The function to be called when Helium needs to pass an event to the host application

◆ he_ssl_ctx_set_inside_write_cb()

void he_ssl_ctx_set_inside_write_cb	(	he_ssl_ctx_t *	ctx,
		he_inside_write_cb_t	inside_write_cb
	)

Sets the function that will be called when Helium needs to do an inside write.

Parameters

ctx	A pointer to a valid SSL context
inside_write_cb	The function to be called when Helium needs to do an inside write

Helium is platform agnostic and as such does not handle its own I/O. This allows the developer to hook up Helium using the most appropriate methods for their platform.

Inside writes are triggered when decrypted packets need to be passed to the host operating system. On Linux, the inside write would usually be to a tun device.

◆ he_ssl_ctx_set_max_frag_entries()

he_return_code_t he_ssl_ctx_set_max_frag_entries	(	he_ssl_ctx_t *	ctx,
		size_t	max_frag_entries
	)

Sets the maximum number of entries the connection can use for reassembling fragments.

Parameters

max_frag_entries Max number of entries for fragment assembly.

Returns: HE_SUCCESS if the value is set successfully.

◆ he_ssl_ctx_set_maximum_supported_version()

he_return_code_t he_ssl_ctx_set_maximum_supported_version	(	he_ssl_ctx_t *	context,
		uint8_t	major_version,
		uint8_t	minor_version
	)

Set the maximum supported wire protocol version by this SSL context.

Parameters

context	A pointer to a valid SSL context
major_version	The major version of the maximum supported protocol version
minor_version	The minor version of the maximum supported protocol version

Returns: HE_SUCCESS if the support version is set successfully; HE_ERR_NULL_POINTER if the given SSL context is NULL; HE_ERR_INCORRECT_PROTOCOL_VERSION if the new version is not valid

Note: This function is for server-side only

◆ he_ssl_ctx_set_minimum_supported_version()

he_return_code_t he_ssl_ctx_set_minimum_supported_version	(	he_ssl_ctx_t *	context,
		uint8_t	major_version,
		uint8_t	minor_version
	)

Set the minimum supported wire protocol version by this SSL context.

Parameters

context	A pointer to a valid SSL context
major_version	The major version of the minimum supported protocol version
minor_version	The minor version of the minimum supported protocol version

Returns: HE_SUCCESS if the support version is set successfully; HE_ERR_NULL_POINTER if the given SSL context is NULL; HE_ERR_INCORRECT_PROTOCOL_VERSION if the new version is not valid

Note: This function is for server-side only.

◆ he_ssl_ctx_set_network_config_ipv4_cb()

void he_ssl_ctx_set_network_config_ipv4_cb	(	he_ssl_ctx_t *	ctx,
		he_network_config_ipv4_cb_t	network_config_cb
	)

Sets the function that will be called when Helium needs to pass network ctx to the host application.

Parameters

ctx	A pointer to a valid SSL context
network_config_cb	The function to be called when Helium needs to pass network ctx to the host application.

◆ he_ssl_ctx_set_nudge_time_cb()

void he_ssl_ctx_set_nudge_time_cb	(	he_ssl_ctx_t *	ctx,
		he_nudge_time_cb_t	nudge_time_cb
	)

Sets the function that will be called when Helium needs to update the nudge time.

Parameters

ctx	A pointer to a valid SSL context
nudge_time_cb	The function to be called when Helium needs to update the nudge time

◆ he_ssl_ctx_set_outside_write_cb()

void he_ssl_ctx_set_outside_write_cb	(	he_ssl_ctx_t *	ctx,
		he_outside_write_cb_t	outside_write_cb
	)

Sets the function that will be called when Helium needs to do an outside write.

Parameters

ctx	A pointer to a valid SSL context
outside_write_cb	The function to be called when Helium needs to do an outside write

Helium is platform agnostic and as such does not handle its own I/O. This allows the developer to hook up Helium using the most appropriate methods for their platform.

Outside writes are triggered when encrypted packets need to be sent to the Helium server. On Linux this would usually be a UDP socket.

◆ he_ssl_ctx_set_padding_type()

he_return_code_t he_ssl_ctx_set_padding_type	(	he_ssl_ctx_t *	ctx,
		he_padding_type_t	padding_type
	)

Sets the padding mode and hence the level of padding (if any) to be used.

Returns: HE_SUCCESS

◆ he_ssl_ctx_set_pmtud_state_change_cb()

void he_ssl_ctx_set_pmtud_state_change_cb	(	he_ssl_ctx_t *	ctx,
		he_pmtud_state_change_cb_t	pmtud_state_change_cb
	)

Sets the function that will be called when Lightway PMTUD changes state.

Parameters

ctx	A pointer to a valid SSL context
pmtud_state_change_cb	The function to be called when Lightway PMTUD changes state

Note: This callback function is optional if the implementation never intends to use the PMTUD feature.

◆ he_ssl_ctx_set_pmtud_time_cb()

void he_ssl_ctx_set_pmtud_time_cb	(	he_ssl_ctx_t *	ctx,
		he_pmtud_time_cb_t	pmtud_time_cb
	)

Sets the function that will be called when Lightway PMTUD needs to start the timer.

Parameters

ctx	A pointer to a valid SSL context
pmtud_time_cb	The function to be called when Lightway PMTUD needs to start the timer

Note: This callback function is optional if the implementation never intends to use the PMTUD feature.

◆ he_ssl_ctx_set_populate_network_config_ipv4_cb()

void he_ssl_ctx_set_populate_network_config_ipv4_cb	(	he_ssl_ctx_t *	ctx,
		he_populate_network_config_ipv4_cb_t	pop_network_cb
	)

Sets the function that will be called when Helium needs to provide network ctx to a client.

Parameters

ctx	A pointer to a valid SSL context
pop_network_cb	The function to be called when Helium needs network ctx

◆ he_ssl_ctx_set_server_config_cb()

void he_ssl_ctx_set_server_config_cb	(	he_ssl_ctx_t *	ctx,
		he_server_config_cb_t	server_config_cb
	)

Sets the function that will be called when Helium needs to pass server config to the host application.

Parameters

ctx	A pointer to a valid SSL context
server_config_cb	The function to be called when Helium needs to pass server config to the host application.

◆ he_ssl_ctx_set_server_dn()

he_return_code_t he_ssl_ctx_set_server_dn	(	he_ssl_ctx_t *	ctx,
		const char *	distinguished_name
	)

Set the expected Distinguished Name (DN) of the server.

Parameters

ctx	A pointer to a valid SSL context
distinguished_name	A pointer to the distinguished name

Returns: HE_SUCCESS The DN has been set; HE_ERR_SSL_ERROR Generic failure - DN couldn't be set

Note: This must be set before calling he_ssl_ctx_start[_server]

If this option is set, Helium will verify the DN name of the server's certificate to provide additional security. However, even without this set, Helium will still validate the certificate chain.

◆ he_ssl_ctx_set_state_change_cb()

void he_ssl_ctx_set_state_change_cb	(	he_ssl_ctx_t *	ctx,
		he_state_change_cb_t	state_change_cb
	)

Sets the function that should be called on Helium state changes.

Parameters

ctx	A pointer to a valid SSL context
state_change_cb	The function to be called when Helium changes state

Whenever Helium changes state internally, the supplied function will be called.

◆ he_ssl_ctx_set_use_chacha20()

he_return_code_t he_ssl_ctx_set_use_chacha20	(	he_ssl_ctx_t *	ctx,
		bool	use
	)

Tell Helium to use CHACHA20 and Poly1305 instead of AES and SHA based encryption and authentication.

Parameters

ctx	A pointer to a valid SSL context
use	A boolean to indicate whether chacha20 should be used

Returns: HE_SUCCESS The use of CHACHA20 has been set successfully

◆ he_ssl_ctx_set_use_pqc()

he_return_code_t he_ssl_ctx_set_use_pqc	(	he_ssl_ctx_t *	ctx,
		bool	enabled
	)

Sets the client to use PQC Keyshares.

Returns: HE_SUCCESS PQC Keyshares are enabled

◆ he_ssl_ctx_start()

he_return_code_t he_ssl_ctx_start ( he_ssl_ctx_t * context )

Sets up all internal state so that client connections can be created.

Parameters

context A pointer to a valid SSL context

Returns: HE_ERR_NULL_POINTER The ctx pointer supplied is NULL; HE_ERR_CONF_CA_NOT_SET The CA has not been set; HE_ERR_CONF_OUTSIDE_WRITE_CB_NOT_SET The outside write callback has not been set; HE_ERR_INIT_FAILED Helium was unable to initialise itself; HE_ERR_SSL_BAD_FILETYPE The SSL certificate was not provided in PEM format; HE_ERR_SSL_BAD_FILE The SSL certificate is corrupt or damaged; HE_ERR_SSL_OUT_OF_MEMORY The crypto engine ran out of memory; HE_ERR_SSL_ASN_INPUT The certificate does not comply to ASN formatting; HE_ERR_SSL_BUFFER Ran out of memory trying to allocate buffers for the SSL layer; HE_ERR_SSL_CERT Generic failure in the SSL engine; HE_SUCCESS Helium is in the process of connecting

This function has a lot of return codes as it is where Helium tries to apply and configure the crypto engine. All of the return codes except for HE_SUCCESS are effectively fatal errors. Trying to call he_ssl_ctx_start_ again without changing the configuration is unlikely to succeed.

◆ he_ssl_ctx_start_server()

he_return_code_t he_ssl_ctx_start_server ( he_ssl_ctx_t * context )

Sets up all internal state so that server connections can be created.

Parameters

context A pointer to a valid SSL context

Returns: HE_ERR_NULL_POINTER The ctx pointer supplied is NULL; HE_ERR_CONF_CA_NOT_SET The CA has not been set; HE_ERR_CONF_OUTSIDE_WRITE_CB_NOT_SET The outside write callback has not been set; HE_ERR_INIT_FAILED Helium was unable to initialise itself; HE_ERR_SSL_BAD_FILETYPE The SSL certificate was not provided in PEM format; HE_ERR_SSL_BAD_FILE The SSL certificate is corrupt or damaged; HE_ERR_SSL_OUT_OF_MEMORY The crypto engine ran out of memory; HE_ERR_SSL_ASN_INPUT The certificate does not comply to ASN formatting; HE_ERR_SSL_BUFFER Ran out of memory trying to allocate buffers for the SSL layer; HE_ERR_SSL_CERT Generic failure in the SSL engine; HE_SUCCESS Helium is in the process of connecting

This function has a lot of return codes as it is where Helium tries to apply and configure the crypto engine. All of the return codes except for HE_SUCCESS are effectively fatal errors. Trying to call he_ssl_ctx_start_ again without changing the configuration is unlikely to succeed.

◆ he_ssl_ctx_stop()

he_return_code_t he_ssl_ctx_stop ( he_ssl_ctx_t * context )

Try to cleanly stop the SSL context.

Parameters

context A pointer to a valid SSL context (client or server)

Returns: HE_SUCCESS The disconnect process has started

Note: This function is not yet well described and is likely to change