Helium
|
Core internal header file for libhelium. More...
#include <stdbool.h>
#include <stdint.h>
#include "he_plugin.h"
#include <wolfssl/options.h>
#include <wolfssl/ssl.h>
#include <wolfssl/wolfcrypt/settings.h>
#include <wolfssl/wolfcrypt/random.h>
Go to the source code of this file.
Data Structures | |
struct | he_client |
Data structure to hold all the state needed as a Helium client. More... | |
struct | he_packet_buffer |
struct | he_version_info |
struct | he_ssl_ctx |
struct | he_conn |
struct | he_plugin_chain |
struct | he_network_config_ipv4 |
struct | he_wire_hdr |
The wire header format It is strongly discouraged to interact with this header structure, however, it is provided for specific use cases (such as a server rejecting a session, where by definition we don't have a connection object). More... | |
struct | he_msg_hdr |
struct | he_msg_ping |
struct | he_msg_pong |
struct | he_msg_auth_hdr |
struct | he_msg_auth |
struct | he_msg_auth_buf |
struct | he_msg_config_ipv4 |
struct | he_msg_data |
struct | he_deprecated_msg_13 |
struct | he_msg_auth_response |
struct | he_msg_session_request |
struct | he_msg_session_response |
struct | he_msg_goodbye |
struct | he_msg_extension |
Macros | |
#define | HE_MAX_WIRE_MTU 1500 |
#define | HE_MAX_MTU 1350 |
#define | HE_MAX_MTU_STR "1350" |
#define | HE_WIRE_MINIMUM_PROTOCOL_MAJOR_VERSION 1 |
#define | HE_WIRE_MINIMUM_PROTOCOL_MINOR_VERSION 0 |
#define | HE_WIRE_MAXIMUM_PROTOCOL_MAJOR_VERSION 1 |
#define | HE_WIRE_MAXIMUM_PROTOCOL_MINOR_VERSION 1 |
#define | HE_CONFIG_TEXT_FIELD_LENGTH 50 |
Helpful deprecation macro. More... | |
#define | HE_MAX_IPV4_STRING_LENGTH 24 |
Maximum size of an IPV4 String. | |
#define | HE_AUTH_STATUS_SUCCESS 0 |
#define | HE_AUTH_STATUS_FAILURE 1 |
#define | HE_EXT_TYPE_REQUEST 1 |
#define | HE_EXT_TYPE_RESPONSE 2 |
#define | HE_EXT_ID_BLOCK_DNS_OVER_TLS 1 |
#define | HE_EXT_PAYLOAD_TYPE_MSGPACK 1 |
#define | HE_EXT_PAYLOAD_TYPE_BINARY 2 |
#define | HE_EXT_PAYLOAD_TYPE_INT16 3 |
#define | HE_WOLF_MAX_HEADER_SIZE 37 |
#define | HE_IPV4_HEADER_SIZE 20 |
#define | HE_TCP_HEADER_SIZE 20 |
#define | HE_UDP_HEADER_SIZE 8 |
#define | HE_HEADER_SAFE_GAP 28 |
#define | HE_MSS_OVERHEAD (HE_IPV4_HEADER_SIZE + HE_UDP_HEADER_SIZE) |
Typedefs | |
typedef enum he_return_code | he_return_code_t |
All possible return codes for helium. | |
typedef enum he_conn_state | he_conn_state_t |
Status codes for a Helium connection. | |
typedef enum he_conn_event | he_conn_event_t |
typedef enum he_padding_type | he_padding_type_t |
Helium supports numerous padding levels, from none to full. This enum defines which options can be chosen. | |
typedef enum he_connection_type | he_connection_type_t |
Helium can operate in datagram or stream modes. This enum defines these two modes. | |
typedef struct he_ssl_ctx | he_ssl_ctx_t |
typedef struct he_conn | he_conn_t |
typedef struct he_plugin_chain | he_plugin_chain_t |
typedef struct he_network_config_ipv4 | he_network_config_ipv4_t |
typedef struct he_client | he_client_t |
Data structure to hold all the state needed as a Helium client. | |
typedef void *(* | he_malloc_t) (size_t size) |
typedef void *(* | he_calloc_t) (size_t nmemb, size_t size) |
typedef void *(* | he_realloc_t) (void *ptr, size_t size) |
typedef void(* | he_free_t) (void *ptr) |
typedef he_return_code_t(* | he_state_change_cb_t) (he_conn_t *conn, he_conn_state_t new_state, void *context) |
The prototype for the state callback function. More... | |
typedef he_return_code_t(* | he_inside_write_cb_t) (he_conn_t *conn, uint8_t *packet, size_t length, void *context) |
The prototype for the inside write callback function. More... | |
typedef he_return_code_t(* | he_outside_write_cb_t) (he_conn_t *conn, uint8_t *packet, size_t length, void *context) |
The prototype for the outside write callback function. More... | |
typedef he_return_code_t(* | he_network_config_ipv4_cb_t) (he_conn_t *conn, he_network_config_ipv4_t *config, void *context) |
The prototype for the network config callback function. More... | |
typedef he_return_code_t(* | he_event_cb_t) (he_conn_t *conn, he_conn_event_t event, void *context) |
The prototype for the event callback function. More... | |
typedef he_return_code_t(* | he_nudge_time_cb_t) (he_conn_t *conn, int timeout, void *context) |
The prototype for the nudge time callback function. More... | |
typedef bool(* | he_auth_cb_t) (he_conn_t *conn, char const *username, char const *password, void *context) |
The prototype for the authentication callback. More... | |
typedef bool(* | he_auth_buf_cb_t) (he_conn_t *conn, uint8_t auth_type, uint8_t *buffer, uint16_t length, void *context) |
The prototype for the authentication buffer callback. More... | |
typedef he_return_code_t(* | he_populate_network_config_ipv4_cb_t) (he_conn_t *conn, he_network_config_ipv4_t *config, void *context) |
The prototype for the population of the network config. More... | |
typedef struct he_packet_buffer | he_packet_buffer_t |
typedef struct he_version_info | he_version_info_t |
typedef enum msg_ids | msg_ids_t |
typedef enum he_auth_type | he_auth_type_t |
typedef struct he_wire_hdr | he_wire_hdr_t |
The wire header format It is strongly discouraged to interact with this header structure, however, it is provided for specific use cases (such as a server rejecting a session, where by definition we don't have a connection object). | |
typedef struct he_msg_hdr | he_msg_hdr_t |
typedef struct he_msg_ping | he_msg_ping_t |
typedef struct he_msg_pong | he_msg_pong_t |
typedef struct he_msg_auth_hdr | he_msg_auth_hdr_t |
typedef struct he_msg_auth | he_msg_auth_t |
typedef struct he_msg_auth_buf | he_msg_auth_buf_t |
typedef struct he_msg_config_ipv4 | he_msg_config_ipv4_t |
typedef struct he_msg_data | he_msg_data_t |
typedef struct he_deprecated_msg_13 | he_deprecated_msg_13_t |
typedef struct he_msg_auth_response | he_msg_auth_response_t |
typedef struct he_msg_session_request | he_msg_session_request_t |
typedef struct he_msg_session_response | he_msg_session_response_t |
typedef struct he_msg_goodbye | he_msg_goodbye_t |
typedef struct he_msg_extension | he_msg_extension_t |
Core internal header file for libhelium.
This file includes common type definitions and useful constants for ensuring consistency across the code files for libhelium. It should be included by every header file.
Parts of this file are included in the public header, but other parts are considered "internal" implementation details.
#define HE_CONFIG_TEXT_FIELD_LENGTH 50 |
Helpful deprecation macro.
Begin Public SectionMaximum size of a text based config option.
#define HE_MAX_WIRE_MTU 1500 |
Set sizes
#define HE_WIRE_MINIMUM_PROTOCOL_MAJOR_VERSION 1 |
Set Maximum and Minimum Minor Versions
#define HE_WOLF_MAX_HEADER_SIZE 37 |
End Public Section
typedef bool(* he_auth_buf_cb_t) (he_conn_t *conn, uint8_t auth_type, uint8_t *buffer, uint16_t length, void *context) |
The prototype for the authentication buffer callback.
conn | A pointer to the connection that triggered this callback |
auth_type | the authentication type |
buffer | An opaque buffer object |
length | The length of the buffer parameter |
context | A pointer to the user defined context |
The host is expected to interpret this buffer and return whether it considers this connection authenticated.
typedef bool(* he_auth_cb_t) (he_conn_t *conn, char const *username, char const *password, void *context) |
The prototype for the authentication callback.
conn | A pointer to the connection that triggered this callback |
username | A pointer to the username |
password | A pointer to the password |
context | A pointer to the user defined context |
The host is expected to return whether this username and password is valid for the connection. Note that username and password are not guaranteed to be null terminated, but will be less than or equal in length to HE_CONFIG_TEXT_FIELD_LENGTH
typedef he_return_code_t(* he_event_cb_t) (he_conn_t *conn, he_conn_event_t event, void *context) |
The prototype for the event callback function.
conn | A pointer to the connection that triggered this callback |
event | The event to trigger |
context | A pointer to the user defined context |
Whenever Helium generates an event, this function will be called.
typedef he_return_code_t(* he_inside_write_cb_t) (he_conn_t *conn, uint8_t *packet, size_t length, void *context) |
The prototype for the inside write callback function.
conn | A pointer to the connection that triggered this callback |
packet | A pointer to the packet data |
length | The length of the entire packet in bytes |
context | A pointer to the user defined context |
Whenever Helium needs to do an inside write this function will be called. On Linux this would usually be writing decrypted packets to a tun device.
typedef struct he_msg_hdr he_msg_hdr_t |
End Public Section
typedef he_return_code_t(* he_network_config_ipv4_cb_t) (he_conn_t *conn, he_network_config_ipv4_t *config, void *context) |
The prototype for the network config callback function.
conn | A pointer to the connection that triggered this callback |
config | The network config data such as local IP, peer IP, DNS IP and MTU |
context | A pointer to the user defined context |
When network configuration data is sent to Helium from the server, this callback will be triggered to allow to host application to configure its network accordingly.
typedef struct he_network_config_ipv4 he_network_config_ipv4_t |
Begin Public Section
typedef he_return_code_t(* he_nudge_time_cb_t) (he_conn_t *conn, int timeout, void *context) |
The prototype for the nudge time callback function.
conn | A pointer to the connection that triggered this callback |
timeout | The number of milliseconds to wait before nudging Helium |
context | A pointer to the user defined context |
Helium uses D/TLS which needs to be able to resend certain messages if they are not received in time. As Helium does not have its own threads or timers, it is up to the host application to tell Helium when a certain amount of time has passed. Because D/TLS implements exponential back off, the amount of waiting time can change after every read.
To avoid the host application having to remember to ask Helium after every read with he_conn_get_nudge_time(), the host application can register this callback instead.
typedef he_return_code_t(* he_outside_write_cb_t) (he_conn_t *conn, uint8_t *packet, size_t length, void *context) |
The prototype for the outside write callback function.
conn | A pointer to the connection that triggered this callback |
packet | A pointer to the packet data |
length | The length of the entire packet in bytes |
context | A pointer to the user defined context |
Whenever Helium needs to do an outside write this function will be called. On Linux this would usually be writing to a UDP socket to send encrypted data over the Internet.
typedef struct he_packet_buffer he_packet_buffer_t |
End Public Section
typedef he_return_code_t(* he_populate_network_config_ipv4_cb_t) (he_conn_t *conn, he_network_config_ipv4_t *config, void *context) |
The prototype for the population of the network config.
conn | A pointer to the connection that triggered this callback | |
[out] | config | A valid pointer to a network_config_ipv4_t, to be populated by the host |
context | A pointer to the user defined context |
The host is expected to populate the provided he_network_config_ipv4_t* object with the correct values so that the client can successfully connect.
typedef he_return_code_t(* he_state_change_cb_t) (he_conn_t *conn, he_conn_state_t new_state, void *context) |
The prototype for the state callback function.
conn | A pointer to the connection that triggered this callback |
new_state | The state that the context has just entered |
context | A pointer to the user defined context |
Whenever Helium changes state, this function will be called.
enum he_conn_event |
enum he_conn_state |
Status codes for a Helium connection.
enum he_connection_type |
enum he_padding_type |
Helium supports numerous padding levels, from none to full. This enum defines which options can be chosen.
enum he_return_code |
All possible return codes for helium.
enum msg_ids |