Helium
ssl_ctx.h
Go to the documentation of this file.
1 
26 #ifndef SSL_CTX_H
27 #define SSL_CTX_H
28 
29 #include "he_internal.h"
30 
44 
57 
70 
83 
93 
101 
122 
143 
151 
163  uint8_t major_version,
164  uint8_t minor_version);
165 
177  uint8_t major_version,
178  uint8_t minor_version);
187 bool he_ssl_ctx_is_supported_version(he_ssl_ctx_t *context, uint8_t major_version,
188  uint8_t minor_version);
189 
198 bool he_ssl_ctx_is_latest_version(he_ssl_ctx_t *context, uint8_t major_version,
199  uint8_t minor_version);
200 
201 // Setters and getters for the configuration
214 he_return_code_t he_ssl_ctx_set_server_dn(he_ssl_ctx_t *ctx, const char *distinguished_name);
215 
221 const char *he_ssl_ctx_get_server_dn(he_ssl_ctx_t *ctx);
222 
232 
241 
248 
261 he_return_code_t he_ssl_ctx_set_ca(he_ssl_ctx_t *ctx, uint8_t *cert_buffer, size_t length);
262 
269 
274  const char *server_key);
275 
280 
289  he_connection_type_t connection_type);
290 
299 
309 
322 
332 
345 
369 he_return_code_t he_conn_outside_data_received(he_conn_t *conn, uint8_t *buffer, size_t length);
370 
380 
389  he_network_config_ipv4_cb_t network_config_cb);
390 
400 
409 
416 
426 
435 
442 
449 
456 
463 
472 
481  he_pmtud_state_change_cb_t pmtud_state_change_cb);
482 
491 
504 
514 
520 
526 
535 
536 #ifndef HE_NO_PQC
537 
544 
545 #endif // HE_NO_PQC
546 
552 he_return_code_t he_ssl_ctx_set_max_frag_entries(he_ssl_ctx_t *ctx, size_t max_frag_entries);
553 
554 #endif // SSL_CTX_H
he_ssl_ctx_create
he_ssl_ctx_t * he_ssl_ctx_create(void)
Creates a Helium SSL context.
Definition: ssl_ctx.c:111
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.
Definition: ssl_ctx.c:583
he_ssl_ctx_set_server_cert_key_files
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.
Definition: ssl_ctx.c:501
he_inside_write_cb_t
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.
Definition: he.h:372
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.
Definition: ssl_ctx.c:616
he_internal.h
Core internal header file for libhelium.
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.
Definition: ssl_ctx.c:235
he_populate_network_config_ipv4_cb_t
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.
Definition: he.h:507
he_cleanup
he_return_code_t he_cleanup(void)
Cleans up all Helium global state.
Definition: ssl_ctx.c:44
he_state_change_cb_t
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.
Definition: he.h:358
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.
Definition: ssl_ctx.c:737
he_ssl_ctx_destroy
void he_ssl_ctx_destroy(he_ssl_ctx_t *ctx)
Releases all memory allocate by Helium for this context.
Definition: ssl_ctx.c:115
he_nudge_time_cb_t
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.
Definition: he.h:449
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.
Definition: ssl_ctx.c:590
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.
Definition: ssl_ctx.c:726
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.
Definition: ssl_ctx.c:152
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.
Definition: ssl_ctx.c:527
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.
Definition: ssl_ctx.c:625
he_return_code_t
enum he_return_code he_return_code_t
All possible return codes for helium.
he_init
he_return_code_t he_init(void)
Initialises Helium global state.
Definition: ssl_ctx.c:33
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.
Definition: ssl_ctx.c:706
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.
Definition: ssl_ctx.c:757
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.
Definition: ssl_ctx.c:551
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.
Definition: ssl_ctx.c:696
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.
Definition: ssl_ctx.c:677
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.
Definition: ssl_ctx.c:668
he_padding_type_t
enum he_padding_type he_padding_type_t
Helium supports numerous padding levels, from none to full. This enum defines which options can be ch...
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.
Definition: ssl_ctx.c:542
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 c...
Definition: ssl_ctx.c:746
he_server_config_cb_t
he_return_code_t(* he_server_config_cb_t)(he_conn_t *conn, uint8_t *buffer, size_t length, void *context)
The prototype for the server config callback function.
Definition: he.h:415
he_ssl_ctx_is_roaming_disabled
bool he_ssl_ctx_is_roaming_disabled(he_ssl_ctx_t *ctx)
Check if roaming has been disabled.
Definition: ssl_ctx.c:717
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.
Definition: ssl_ctx.c:574
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.
Definition: ssl_ctx.c:687
he_pmtud_time_cb_t
he_return_code_t(* he_pmtud_time_cb_t)(he_conn_t *conn, int timeout, void *context)
The prototype for the Path MTU Discovery (PMTUD) time callback function.
Definition: he.h:528
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.
Definition: ssl_ctx.c:439
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.
Definition: ssl_ctx.c:492
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.
Definition: ssl_ctx.c:376
he_auth_buf_cb_t
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.
Definition: he.h:493
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.
Definition: ssl_ctx.c:352
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.
Definition: ssl_ctx.c:87
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.
Definition: ssl_ctx.c:650
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.
Definition: ssl_ctx.c:409
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.
Definition: flow.c:299
he_auth_cb_t
bool(* he_auth_cb_t)(he_conn_t *conn, char const *username, char const *password, void *context)
The prototype for the authentication callback.
Definition: he.h:463
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.
Definition: ssl_ctx.c:632
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.
Definition: ssl_ctx.c:641
he_connection_type_t
enum he_connection_type he_connection_type_t
Helium can operate in datagram or stream modes. This enum defines these two modes.
he_auth_token_cb_t
bool(* he_auth_token_cb_t)(he_conn_t *conn, const uint8_t *token, size_t len, void *context)
The prototype for the authentication token callback.
Definition: he.h:478
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.
Definition: ssl_ctx.c:458
he_ssl_ctx
Definition: he_internal.h:92
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.
Definition: ssl_ctx.c:430
he_ssl_ctx_is_server_cert_key_set
bool he_ssl_ctx_is_server_cert_key_set(he_ssl_ctx_t *ctx)
Whether the server cert and keys have been set.
Definition: ssl_ctx.c:518
he_pmtud_state_change_cb_t
he_return_code_t(* he_pmtud_state_change_cb_t)(he_conn_t *conn, he_pmtud_state_t state, void *context)
The prototype for Lightway PMTUD state callback function.
Definition: he.h:546
he_ssl_ctx_stop
he_return_code_t he_ssl_ctx_stop(he_ssl_ctx_t *context)
Try to cleanly stop the SSL context.
Definition: ssl_ctx.c:311
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.
Definition: ssl_ctx.c:328
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...
Definition: ssl_ctx.c:600
he_outside_write_cb_t
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.
Definition: he.h:386
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.
Definition: ssl_ctx.c:467
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.
Definition: ssl_ctx.c:421
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.
Definition: ssl_ctx.c:558
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.
Definition: ssl_ctx.c:609
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.
Definition: ssl_ctx.c:67
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.
Definition: ssl_ctx.c:567
he_event_cb_t
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.
Definition: he.h:427
he_network_config_ipv4_cb_t
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.
Definition: he.h:399
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.
Definition: ssl_ctx.c:659
he_conn
Definition: he_internal.h:170
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.
Definition: ssl_ctx.c:448
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.
Definition: ssl_ctx.c:768