ssl_ctx.h File Reference

Functions for managing the SSL context. More...

#include <he.h>

Include dependency graph for ssl_ctx.h:

Go to the source code of this file.

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 contxt. 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_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_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...
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...

Detailed Description

Functions for managing the SSL context.

Function Documentation

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.

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

See also

he_init()

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_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_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.

Call this first before any other Helium function!

See also

he_cleanup()

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

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_padding_type_t he_ssl_ctx_get_padding_type

(

he_ssl_ctx_t *

ctx

)

Returns the current padding mode.

Returns

he_padding_type_t

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

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

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

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

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.

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

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

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.

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.

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.

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.

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.

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.

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

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_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_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_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

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

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_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_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_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.

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.

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

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.

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.

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

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_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

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_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.

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_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_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 ctxure 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_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 ctxure 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_return_code_t he_ssl_ctx_stop

(

he_ssl_ctx_t *

context

)

Try to cleanly stop the SSL contxt.

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