Functions for managing the connection. More...

#include <he.h>

Include dependency graph for conn.h:

Macros
#define	HE_WOLF_TIMEOUT_MULTIPLIER 100

#define	HE_WOLF_RENEGOTIATION_TIMEOUT_MULTIPLIER 1000

Functions
he_conn_t *	he_conn_create (void)
	Creates a Helium connection struct. More...

void	he_conn_destroy (he_conn_t *conn)
	Releases all memory allocate by Helium for this connection. More...

he_return_code_t	he_conn_is_valid_client (he_ssl_ctx_t ssl_ctx, he_conn_t conn)
	Checks whether the client conn has the basic values to allow Helium to connect. More...

he_return_code_t	he_conn_is_valid_server (he_ssl_ctx_t ssl_ctx, he_conn_t conn)
	Checks whether the client conn has the basic values to allow Helium to connect. More...

int	he_conn_set_username (he_conn_t conn, const char username)
	Set the username to authenticate with. More...

const char *	he_conn_get_username (const he_conn_t *conn)
	Get the username that Helium will authenticate with, previously set by he_conn_set_username. More...

bool	he_conn_is_username_set (const he_conn_t *conn)
	Check if the password has been set. More...

he_return_code_t	he_conn_set_password (he_conn_t conn, const char password)
	Sets the password Helium should use to authenticate with. More...

bool	he_conn_is_password_set (const he_conn_t *conn)
	Check if the password has been set. More...

he_return_code_t	he_conn_set_auth_buffer (he_conn_t conn, uint8_t auth_type, uint8_t buffer, uint16_t length)
	Sets the opaque buffer Helium should use to authenticate with. More...

bool	he_conn_is_auth_buffer_set (const he_conn_t *conn)
	Check if the auth buffer has been set. More...

int	he_conn_set_outside_mtu (he_conn_t *conn, int mtu)
	Set the MTU for the outside transport mechanism. Usually this will be the MTU of the devices Internet connection. More...

int	he_conn_get_outside_mtu (he_conn_t *conn)
	Get the MTU value for the outside transport mechanism. *. More...

bool	he_conn_is_outside_mtu_set (he_conn_t *conn)
	Check if the outside MTU has been set. More...

he_return_code_t	he_conn_set_context (he_conn_t conn, void data)
	Store a pointer in the context that will be made available in all Helium callbacks. More...

void *	he_conn_get_context (he_conn_t *conn)
	Retrieve the pointer to the user supplied context. More...

he_return_code_t	he_internal_conn_configure (he_conn_t conn, he_ssl_ctx_t ctx)

he_return_code_t	he_conn_client_connect (he_conn_t conn, he_ssl_ctx_t ssl_ctx, he_plugin_chain_t inside_plugins, he_plugin_chain_t outside_plugins)
	Tries to establish a connection with a Helium server. More...

he_return_code_t	he_conn_server_connect (he_conn_t conn, he_ssl_ctx_t ssl_ctx, he_plugin_chain_t inside_plugins, he_plugin_chain_t outside_plugins)
	Tries to establish a connection with a Helium client. More...

he_return_code_t	he_conn_disconnect (he_conn_t *conn)
	Try to cleanly disconnect from the remote Helium instance (client or server). More...

void	he_internal_disconnect_and_shutdown (he_conn_t *conn)

void	he_internal_change_conn_state (he_conn_t *conn, he_conn_state_t state)

he_return_code_t	he_internal_send_message (he_conn_t conn, uint8_t message, uint16_t length)
	Sends a message over the secured tunnel. More...

he_return_code_t	he_internal_send_goodbye (he_conn_t *conn)

he_return_code_t	he_internal_send_auth (he_conn_t *conn)

he_return_code_t	he_conn_send_keepalive (he_conn_t *conn)
	Tell Helium to send a keepalive message. This can be used to avoid NAT timing out. More...

he_return_code_t	he_conn_schedule_renegotiation (he_conn_t *conn)
	Tell Helium to schedule a renegotiation. More...

he_return_code_t	he_internal_renegotiate_ssl (he_conn_t *conn)

void	he_internal_update_timeout (he_conn_t *conn)
	Updates the timeout for a connectionand triggers the timeout callback if set. More...

int	he_conn_get_nudge_time (he_conn_t *conn)
	Returns the number of miliseconds that host application should wait before nudging Helium. More...

he_return_code_t	he_conn_nudge (he_conn_t *conn)
	Nudges Helium. More...

he_conn_state_t	he_conn_get_state (he_conn_t *conn)
	Returns the state that the conn is currently in. More...

uint64_t	he_conn_get_session_id (he_conn_t *conn)
	Returns the session ID for this connection.

he_return_code_t	he_conn_set_session_id (he_conn_t *conn, uint64_t session_id)
	Sets the session ID for this connection.

uint64_t	he_conn_get_pending_session_id (he_conn_t *conn)
	Returns the pending session ID for this connection, if there is one. More...

bool	he_conn_is_error_fatal (he_conn_t *conn, he_return_code_t error_msg)
	Returns true if a given error (a return from libhelium where he_return_code_t != HE_SUCCESS) is obviously fatal and should terminate the connection. More...

he_return_code_t	he_conn_rotate_session_id (he_conn_t conn, uint64_t new_session_id)
	Rotate the session ID for this connection. More...

bool	he_conn_supports_renegotiation (he_conn_t *conn)
	Whether this particular connection supports renegoation. More...

void	he_internal_generate_event (he_conn_t *conn, he_conn_event_t event)

he_return_code_t	he_conn_set_protocol_version (he_conn_t *conn, uint8_t major_version, uint8_t minor_version)
	On the server, sets the major/minor version number for this connection. More...

size_t	he_internal_calculate_data_packet_length (he_conn_t *conn, size_t length)

he_return_code_t	he_internal_generate_session_id (he_conn_t conn, uint64_t session_id_out)
	Generate a random session ID. More...

Detailed Description

Functions for managing the connection.

Function Documentation

he_return_code_t he_conn_client_connect	(	he_conn_t *	conn,
		he_ssl_ctx_t *	ssl_ctx,
		he_plugin_chain_t *	inside_plugins,
		he_plugin_chain_t *	outside_plugins
	)

Tries to establish a connection with a Helium server.

Parameters

conn	A pointer to a valid Helium connection
conn	A pointer to a valid connection conn
ssl_ctx	A pointer to valid and started SSL context
ctx_conn	A pointer to a valid SSL context connection
outside_plugins	A pointer to a valid plugin chain

Returns: HE_ERR_NULL_POINTER One or more required pointers are NULL; HE_ERR_CONF_USERNAME_NOT_SET The username has not been set; HE_ERR_CONF_PASSWORD_NOT_SET The password has not been set; HE_ERR_CONF_MTU_NOT_SET The external MTU has not been set; HE_ERR_INIT_FAILED Helium was unable to initialise itself; HE_ERR_SSL_CERT Generic failure in the SSL engine; HE_ERR_CONNECT_FAILED There was an I/O issue trying to connect to the server.; HE_SUCCESS Helium is in the process of connecting

Note: This function triggers the initialisation and initial connection to a Helium server. However it is asynchronous, Helium is not connected when this function returns, merely that the connection is in progress. Use event and state change callbacks to determine the actual state of Helium

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_conn_client_connect again without changing the connection is unlikely to succeed.

he_conn_t* he_conn_create ( void )

Creates a Helium connection struct.

Returns: he_conn_t* Returns a pointer to a valid Helium connection

Note: This function allocates memory

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

void he_conn_destroy ( he_conn_t * conn )

Releases all memory allocate by Helium for this connection.

Parameters

conn	A pointer to a valid Helium connection

It will first remove all of the callbacks which means no Helium callbacks will be triggered after calling this function. It is thus an error to call any Helium functions on this connection after it has been destroyed.

he_return_code_t he_conn_disconnect ( he_conn_t * conn )

Try to cleanly disconnect from the remote Helium instance (client or server).

Returns: HE_ERR_NEVER_CONNECTED The connection has never been connected and so cannot be disconnected. It is safe to destroy the connection state here.; HE_ERR_INVALID_CONN_STATE This function should only be used when Helium is in the online state. It is safe to destroy the connection in other states.; HE_SUCCESS The disconnect process has started

Note: Like he_conn_client_connect, this is an asynchronous process. Watch state changes to determine when Helium has actually disconnected; This function is not yet well described and is likely to change

void* he_conn_get_context ( he_conn_t * conn )

Retrieve the pointer to the user supplied context.

Parameters

conn	A pointer to a valid HE context

Returns: void* The void pointer that was set previously or NULL if none was set

int he_conn_get_nudge_time ( he_conn_t * conn )

Returns the number of miliseconds that host application should wait before nudging Helium.

Parameters

conn	A pointer to a valid connection

Returns: The number of miliseconds to wait before nudging again

Warning: This value is updated after Helium completes a read cycle. It should be called directly after those functions

int he_conn_get_outside_mtu ( he_conn_t * conn )

Get the MTU value for the outside transport mechanism. *.

Parameters

conn	A pointer to a valid connection. @ return int The MTU value in bytes.

uint64_t he_conn_get_pending_session_id ( he_conn_t * conn )

Returns the pending session ID for this connection, if there is one.

Parameters

conn	A pointer to a valid connection

Returns: 0 If there is no pending session

Note: On a conn connection this function will always return 0; there are no pending conn session IDs

he_conn_state_t he_conn_get_state ( he_conn_t * conn )

Returns the state that the conn is currently in.

Parameters

conn	A pointer to a valid connection

Returns: he_conn_state_t The state the connection is in

See also: he_set_state_change_cb; he_conn_state_t

const char* he_conn_get_username ( const he_conn_t * conn )

Get the username that Helium will authenticate with, previously set by he_conn_set_username.

Parameters

conn	A pointer to a valid connection

Returns: const char* A pointer to the username

bool he_conn_is_auth_buffer_set ( const he_conn_t * conn )

Check if the auth buffer has been set.

Parameters

conn	A pointer to a valid connection

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

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

bool he_conn_is_error_fatal	(	he_conn_t *	conn,
		he_return_code_t	error_msg
	)

Returns true if a given error (a return from libhelium where he_return_code_t != HE_SUCCESS) is obviously fatal and should terminate the connection.

It is not required to call this function – users are welcome to capture their errors, close connections and reconnect even if this function returns false.

bool he_conn_is_outside_mtu_set ( he_conn_t * conn )

Check if the outside MTU has been set.

Parameters

conn	A pointer to a valid connection

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

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

bool he_conn_is_password_set ( const he_conn_t * conn )

Check if the password has been set.

Parameters

conn	A pointer to a valid connection

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

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

bool he_conn_is_username_set ( const he_conn_t * conn )

Check if the password has been set.

Parameters

conn	A pointer to a valid connection

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

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

he_return_code_t he_conn_is_valid_client	(	he_ssl_ctx_t *	ssl_ctx,
		he_conn_t *	conn
	)

Checks whether the client conn has the basic values to allow Helium to connect.

Parameters

ssl_ctx	A pointer to a valid SSL context
conn	A pointer to a valid connection conn

Returns: HE_ERR_NULL_POINTER The conn pointer supplied is NULL; HE_ERR_CONF_USERNAME_NOT_SET The username has not been set; HE_ERR_CONF_PASSWORD_NOT_SET The password has not been set; HE_ERR_CONF_MTU_NOT_SET The external MTU has not been set; HE_ERR_INCORRECT_PROTOCOL_VERSION The protocol version has been set; HE_SUCCESS The basic configuration options have been set

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

he_return_code_t he_conn_is_valid_server	(	he_ssl_ctx_t *	ssl_ctx,
		he_conn_t *	conn
	)

Checks whether the client conn has the basic values to allow Helium to connect.

Parameters

ssl_ctx	A pointer to a valid SSL context
conn	A pointer to a valid connection conn

Returns: HE_ERR_NULL_POINTER The conn pointer supplied is NULL; HE_ERR_CONF_MTU_NOT_SET The external MTU has not been set; HE_ERR_INCORRECT_PROTOCOL_VERSION The protocol version has been set to an unsupported version; HE_SUCCESS The basic configuration options have been set

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

he_return_code_t he_conn_nudge ( he_conn_t * conn )

Nudges Helium.

Parameters

conn	A pointer to a valid connection

Returns: HE_SUCCESS The nudge was successful; HE_CONNECTION_TIMED_OUT Nudge timed out

he_return_code_t he_conn_rotate_session_id	(	he_conn_t *	conn,
		uint64_t *	new_session_id
	)

Rotate the session ID for this connection.

After calling this function, the value returned by he_conn_get_session_id will NOT be updated. The value returned by he_conn_get_pending_session_id is guaranteed to be the same as the value pointed to by new_session_id if that parameter is not null.

After the event "HE_EVENT_PENDING_SESSION_ACKNOWLEDGED" fires, he_conn_get_pending_session_id will return 0, and the value for he_conn_get_session_id will be the same as the session ID generated by this call.

Parameters

	conn	A pointer to a valid connection
[out]	A	uint64_t pointer; if not null the value will be updated with the new session ID

Returns: HE_ERR_INVALID_CONN_STATE If this connection has not been started, or is a client connection, or there is already a pending session rotation; HE_ERR_RNG_FAILURE if we were unable to generate a random number; HE_SUCCESS Session ID rotation begun

he_return_code_t he_conn_schedule_renegotiation ( he_conn_t * conn )

Tell Helium to schedule a renegotiation.

Parameters

conn	A pointer to a valid connection

Returns: HE_SUCCESS A renegotiation is scheduled.

Note that this schedules a key rotation or D/TLS renegotiation on the next time we process data on this connection; calling this function provides no time-based guarantees, only that when we see this connection again we will renegotiate.

he_return_code_t he_conn_send_keepalive ( he_conn_t * conn )

Tell Helium to send a keepalive message. This can be used to avoid NAT timing out.

Parameters

conn	A pointer to a valid connection

Returns: HE_SUCCESS Keep alive was sent

This is used to send a heartbeat message to a Helium server and get a reply. Its prmary use is to ensure that the connection doesn't time out due to NAT traversal. This feature is not mandatory, but as Helium cannot by itself know when to send these, it is up to the host application to call this function at the required intervals.

he_return_code_t he_conn_server_connect	(	he_conn_t *	conn,
		he_ssl_ctx_t *	ssl_ctx,
		he_plugin_chain_t *	inside_plugins,
		he_plugin_chain_t *	outside_plugins
	)

Tries to establish a connection with a Helium client.

Parameters

conn	A pointer to a valid Helium connection
ssl_ctx	A pointer to valid and started SSL context
ctx_conn	A pointer to a valid SSL context connection
plugins	A pointer to a valid plugin chain

Returns: HE_ERR_NULL_POINTER One or more required pointers are NULL; HE_ERR_INIT_FAILED Helium was unable to initialise itself; HE_ERR_SSL_CERT Generic failure in the SSL engine; HE_ERR_CONNECT_FAILED There was an I/O issue trying to connect to the server.; HE_SUCCESS Helium is in the process of connecting

Note: This function triggers the initialisation and initial connection to a Helium client. However it is asynchronous, Helium is not connected when this function returns, merely that the connection is in progress. Use event and state change callbacks to determine the actual state of Helium

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_conn_client_connect again without changing the connection is unlikely to succeed.

he_return_code_t he_conn_set_auth_buffer	(	he_conn_t *	conn,
		uint8_t	auth_type,
		uint8_t *	buffer,
		uint16_t	length
	)

Sets the opaque buffer Helium should use to authenticate with.

Parameters

conn	A pointer to a valid connection
auth_type	the authentication type to pass to the server
buffer	A pointer to the authentication buffer to use
length	The length of the buffer

Returns: HE_SUCCESS the auth buffer has been set; HE_ERR_STRING_TOO_LONG if length is greater than the maximum buffer size

he_return_code_t he_conn_set_context	(	he_conn_t *	conn,
		void *	data
	)

Store a pointer in the context that will be made available in all Helium callbacks.

Parameters

conn	A valid connection
data	A pointer to a user provided data structure

Helium will interact with the host application primarily through the use of callback functions. To avoid the need for global variables, a pointer to some data structure can be set on the context. This context will be passed in all function callbacks as void pointer.

int he_conn_set_outside_mtu	(	he_conn_t *	conn,
		int	mtu
	)

Set the MTU for the outside transport mechanism. Usually this will be the MTU of the devices Internet connection.

Parameters

conn	A pointer to a valid connection
mtu	The MTU of the outside transport mechanism in bytes

Returns: HE_SUCCESS The MTU value was set

Note: A default value is not set as although Ethernet is almost always 1500, mobile devices have a wide range of options

Setting the MTU will update the MSS clamp size to an optimal value for the new MTU.

he_return_code_t he_conn_set_password	(	he_conn_t *	conn,
		const char *	password
	)

Sets the password Helium should use to authenticate with.

Parameters

conn	A pointer to a valid connection
password	A pointer to the password

Returns: HE_SUCCESS The password has been set; HE_ERR_STRING_TOO_LONG Password is too long; HE_ERR_EMPTY_STRING String is empty

Note: There is no he_conn_get_password or equivalent for security reasons

he_return_code_t he_conn_set_protocol_version	(	he_conn_t *	conn,
		uint8_t	major_version,
		uint8_t	minor_version
	)

On the server, sets the major/minor version number for this connection.

Parameters

conn	A pointer to a valid server connection
major_version
minor_version

Returns: HE_SUCCESS if the major/minor version was set successfully

Note: It will result in an invalid state if the protocol version is set on a connection that is later used as a client connection

int he_conn_set_username	(	he_conn_t *	conn,
		const char *	username
	)

Set the username to authenticate with.

Parameters

conn	A pointer to a valid conn
username	A pointer to the username

Returns: HE_SUCCESS Username has been set; HE_ERR_STRING_TOO_LONG Username is too long; HE_ERR_EMPTY_STRING String is empty

bool he_conn_supports_renegotiation ( he_conn_t * conn )

Whether this particular connection supports renegoation.

Only pre-Dec 2020 clients won't support this.

he_return_code_t he_internal_generate_session_id	(	he_conn_t *	conn,
		uint64_t *	session_id_out
	)

Generate a random session ID.

Parameters

	context	A pointer to a valid SSL server context
[out]	session_id_out	A pointer to a uint64_t, where we will write the session ID

Returns: HE_ERR_RNG_FAILURE An error occurred generating the session ID; HE_SUCCESS Random value generated correctly

he_return_code_t he_internal_send_message	(	he_conn_t *	conn,
		uint8_t *	message,
		uint16_t	length
	)

Sends a message over the secured tunnel.

Parameters

conn	A pointer to a valid connection
message	A pointer to the raw message to be sent
length	The length of the message

Returns: he_conn_return_code_t HE_SUCCESS

void he_internal_update_timeout ( he_conn_t * conn )

Updates the timeout for a connectionand triggers the timeout callback if set.

Parameters

conn	A pointer to a valid connection

Macros

Functions

Detailed Description

Function Documentation