API functions for interfacing with OSCORE (RFC8613) More...

Collaboration diagram for OSCORE Support:

Typedefs
typedef int(*	coap_oscore_save_seq_num_t) (uint64_t sender_seq_num, void *param)
	Definition of the function used to save the current Sender Sequence Number.

Functions
COAP_API coap_session_t *	coap_new_client_session_oscore (coap_context_t ctx, const coap_address_t local_if, const coap_address_t server, coap_proto_t proto, coap_oscore_conf_t oscore_conf)
	Creates a new client session to the designated server, protecting the data using OSCORE.

COAP_API coap_session_t *	coap_new_client_session_oscore3 (coap_context_t ctx, const coap_address_t local_if, const coap_address_t server, coap_proto_t proto, coap_oscore_conf_t oscore_conf, void app_data, coap_app_data_free_callback_t callback, coap_str_const_t ws_host)
	Creates a new client session to the designated server, protecting the data using OSCORE, along with app_data information (as per coap_session_set_app_data2()) and optional WebSockets host (as per coap_ws_set_host_request()) to remove timing window call-back in startup instead of doing coap_new_client_session_oscore(); coap_session_set_app_data2(); or coap_new_client_session_oscore(); coap_ws_set_host_request();.

COAP_API coap_session_t *	coap_new_client_session_oscore_psk (coap_context_t ctx, const coap_address_t local_if, const coap_address_t server, coap_proto_t proto, coap_dtls_cpsk_t psk_data, coap_oscore_conf_t *oscore_conf)
	Creates a new client session to the designated server with PSK credentials as well as protecting the data using OSCORE.

COAP_API coap_session_t *	coap_new_client_session_oscore_psk3 (coap_context_t ctx, const coap_address_t local_if, const coap_address_t server, coap_proto_t proto, coap_dtls_cpsk_t psk_data, coap_oscore_conf_t oscore_conf, void app_data, coap_app_data_free_callback_t callback, coap_str_const_t *ws_host)
	Creates a new client session to the designated server, with PSK credentials protecting the data using OSCORE, along with app_data information (as per coap_session_set_app_data2()) and optional WebSockets host (as per coap_ws_set_host_request()) to remove timing window call-back in (D)TLS startup instead of doing coap_new_client_session_oscore_psk(); coap_session_set_app_data2(); or coap_new_client_session_oscore_psk(); coap_ws_set_host_request();.

COAP_API coap_session_t *	coap_new_client_session_oscore_pki (coap_context_t ctx, const coap_address_t local_if, const coap_address_t server, coap_proto_t proto, coap_dtls_pki_t pki_data, coap_oscore_conf_t *oscore_conf)
	Creates a new client session to the designated server with PKI credentials as well as protecting the data using OSCORE.

COAP_API coap_session_t *	coap_new_client_session_oscore_pki3 (coap_context_t ctx, const coap_address_t local_if, const coap_address_t server, coap_proto_t proto, coap_dtls_pki_t pki_data, coap_oscore_conf_t oscore_conf, void app_data, coap_app_data_free_callback_t callback, coap_str_const_t *ws_host)
	Creates a new client session to the designated server, with PKI credentials protecting the data using OSCORE, along with app_data information (as per coap_session_set_app_data2()) and optional WebSockets host (as per coap_ws_set_host_request()) to remove timing window call-back in (D)TLS startup instead of doing coap_new_client_session_oscore_pki(); coap_session_set_app_data2(); or coap_new_client_session_oscore_pki(); coap_ws_set_host_request();.

COAP_API int	coap_context_oscore_server (coap_context_t context, coap_oscore_conf_t oscore_conf)
	Set the context's default OSCORE configuration for a server.

coap_oscore_conf_t *	coap_new_oscore_conf (coap_str_const_t conf_mem, coap_oscore_save_seq_num_t save_seq_num_func, void *save_seq_num_func_param, uint64_t start_seq_num)
	Parse an OSCORE configuration (held in memory) and populate a OSCORE configuration structure.

int	coap_delete_oscore_conf (coap_oscore_conf_t *oscore_conf)
	Release all the information associated with the OSCORE configuration.

COAP_API int	coap_new_oscore_recipient (coap_context_t context, coap_bin_const_t recipient_id)
	Add in the specific Recipient ID into the OSCORE context (server only).

COAP_API int	coap_delete_oscore_recipient (coap_context_t context, coap_bin_const_t recipient_id)
	Release all the information associated for the specific Recipient ID (and hence and stop any further OSCORE protection for this Recipient).

Detailed Description

API functions for interfacing with OSCORE (RFC8613)

Typedef Documentation

◆ coap_oscore_save_seq_num_t

typedef int(* coap_oscore_save_seq_num_t) (uint64_t sender_seq_num, void *param)

Definition of the function used to save the current Sender Sequence Number.

Parameters

sender_seq_num	The Sender Sequence Number to save in non-volatile memory.
param	The save_seq_num_func_param provided to coap_new_oscore_context().

Returns: 1 if success, else 0 if a failure of some sort.

Definition at line 263 of file coap_oscore.h.

Function Documentation

◆ coap_context_oscore_server()

COAP_API int coap_context_oscore_server	(	coap_context_t *	context,
		coap_oscore_conf_t *	oscore_conf
	)

Set the context's default OSCORE configuration for a server.

Parameters

context	The current coap_context_t object.
oscore_conf	OSCORE configuration information. This structure is freed off by this call.

Returns: 1 if successful, else 0.

Definition at line 2338 of file coap_oscore.c.

◆ coap_delete_oscore_conf()

int coap_delete_oscore_conf ( coap_oscore_conf_t * oscore_conf )

Release all the information associated with the OSCORE configuration.

Parameters

oscore_conf The OSCORE configuration structure to release.

Returns: 1 Successfully removed, else 0 not found.

Definition at line 2358 of file coap_oscore.c.

◆ coap_delete_oscore_recipient()

COAP_API int coap_delete_oscore_recipient	(	coap_context_t *	context,
		coap_bin_const_t *	recipient_id
	)

Release all the information associated for the specific Recipient ID (and hence and stop any further OSCORE protection for this Recipient).

Note: This is only removed from the OSCORE context as first defined by coap_new_client_session_oscore*() or coap_context_oscore_server().

Parameters

context	The CoAP context holding the OSCORE recipient_id to.
recipient_id	The Recipient ID to remove.

Returns: 1 Successfully removed, else 0 not found.

Definition at line 2372 of file coap_oscore.c.

◆ coap_new_client_session_oscore()

COAP_API coap_session_t * coap_new_client_session_oscore	(	coap_context_t *	ctx,
		const coap_address_t *	local_if,
		const coap_address_t *	server,
		coap_proto_t	proto,
		coap_oscore_conf_t *	oscore_conf
	)

Creates a new client session to the designated server, protecting the data using OSCORE.

Deprecated:: Use coap_new_client_session_oscore3() instead.

Parameters

ctx	The CoAP context.
local_if	Address of local interface. It is recommended to use NULL to let the operating system choose a suitable local interface. If an address is specified, the port number should be zero, which means that a free port is automatically selected.
server	The server's address. If the port number is zero, the default port for the protocol will be used.
proto	CoAP Protocol.
oscore_conf	OSCORE configuration information. This structure is freed off by this call.

Returns: A new CoAP session or NULL if failed. Call coap_session_release() to free.

Definition at line 2292 of file coap_oscore.c.

◆ coap_new_client_session_oscore3()

COAP_API coap_session_t * coap_new_client_session_oscore3	(	coap_context_t *	ctx,
		const coap_address_t *	local_if,
		const coap_address_t *	server,
		coap_proto_t	proto,
		coap_oscore_conf_t *	oscore_conf,
		void *	app_data,
		coap_app_data_free_callback_t	callback,
		coap_str_const_t *	ws_host
	)

Creates a new client session to the designated server, protecting the data using OSCORE, along with app_data information (as per coap_session_set_app_data2()) and optional WebSockets host (as per coap_ws_set_host_request()) to remove timing window call-back in startup instead of doing coap_new_client_session_oscore(); coap_session_set_app_data2(); or coap_new_client_session_oscore(); coap_ws_set_host_request();.

Parameters

ctx	The CoAP context.
local_if	Address of local interface. It is recommended to use NULL to let the operating system choose a suitable local interface. If an address is specified, the port number should be zero, which means that a free port is automatically selected.
server	The server's address. If the port number is zero, the default port for the protocol will be used.
proto	CoAP Protocol.
oscore_conf	OSCORE configuration information. This structure is freed off by this call.
app_data	The pointer to the application data to store or NULL.
callback	The optional release call-back for app_data on session removal or NULL.
ws_host	If proto is COAP_PROTO_WS or COAP_PROTO_WSS, then set the Host parameter accordingly.

Returns: A new CoAP session or NULL if failed. Call coap_session_release() to free.

◆ coap_new_client_session_oscore_pki()

COAP_API coap_session_t * coap_new_client_session_oscore_pki	(	coap_context_t *	ctx,
		const coap_address_t *	local_if,
		const coap_address_t *	server,
		coap_proto_t	proto,
		coap_dtls_pki_t *	pki_data,
		coap_oscore_conf_t *	oscore_conf
	)

Creates a new client session to the designated server with PKI credentials as well as protecting the data using OSCORE.

Deprecated:: Use coap_new_client_session_oscore_pki3() instead.

Parameters

ctx	The CoAP context.
local_if	Address of local interface. It is recommended to use NULL to let the operating system choose a suitable local interface. If an address is specified, the port number should be zero, which means that a free port is automatically selected.
server	The server's address. If the port number is zero, the default port for the protocol will be used.
proto	CoAP Protocol.
pki_data	PKI parameters.
oscore_conf	OSCORE configuration information. This structure is freed off by this call.

Returns: A new CoAP session or NULL if failed. Call coap_session_release() to free.

Definition at line 2322 of file coap_oscore.c.

◆ coap_new_client_session_oscore_pki3()

COAP_API coap_session_t * coap_new_client_session_oscore_pki3	(	coap_context_t *	ctx,
		const coap_address_t *	local_if,
		const coap_address_t *	server,
		coap_proto_t	proto,
		coap_dtls_pki_t *	pki_data,
		coap_oscore_conf_t *	oscore_conf,
		void *	app_data,
		coap_app_data_free_callback_t	callback,
		coap_str_const_t *	ws_host
	)

Creates a new client session to the designated server, with PKI credentials protecting the data using OSCORE, along with app_data information (as per coap_session_set_app_data2()) and optional WebSockets host (as per coap_ws_set_host_request()) to remove timing window call-back in (D)TLS startup instead of doing coap_new_client_session_oscore_pki(); coap_session_set_app_data2(); or coap_new_client_session_oscore_pki(); coap_ws_set_host_request();.

Parameters

ctx	The CoAP context.
local_if	Address of local interface. It is recommended to use NULL to let the operating system choose a suitable local interface. If an address is specified, the port number should be zero, which means that a free port is automatically selected.
server	The server's address. If the port number is zero, the default port for the protocol will be used.
proto	CoAP Protocol.
pki_data	PKI parameters.
oscore_conf	OSCORE configuration information. This structure is freed off by this call.
app_data	The pointer to the application data to store or NULL.
callback	The optional release call-back for app_data on session removal or NULL.
ws_host	If proto is COAP_PROTO_WS or COAP_PROTO_WSS, then set the Host parameter accordingly.

Returns: A new CoAP session or NULL if failed. Call coap_session_release() to free.

◆ coap_new_client_session_oscore_psk()

COAP_API coap_session_t * coap_new_client_session_oscore_psk	(	coap_context_t *	ctx,
		const coap_address_t *	local_if,
		const coap_address_t *	server,
		coap_proto_t	proto,
		coap_dtls_cpsk_t *	psk_data,
		coap_oscore_conf_t *	oscore_conf
	)

Creates a new client session to the designated server with PSK credentials as well as protecting the data using OSCORE.

Deprecated:: Use coap_new_client_session_oscore_psk3() instead.

Parameters

ctx	The CoAP context.
local_if	Address of local interface. It is recommended to use NULL to let the operating system choose a suitable local interface. If an address is specified, the port number should be zero, which means that a free port is automatically selected.
server	The server's address. If the port number is zero, the default port for the protocol will be used.
proto	CoAP Protocol.
psk_data	PSK parameters.
oscore_conf	OSCORE configuration information. This structure is freed off by this call.

Returns: A new CoAP session or NULL if failed. Call coap_session_release() to free.

Definition at line 2306 of file coap_oscore.c.

◆ coap_new_client_session_oscore_psk3()

COAP_API coap_session_t * coap_new_client_session_oscore_psk3	(	coap_context_t *	ctx,
		const coap_address_t *	local_if,
		const coap_address_t *	server,
		coap_proto_t	proto,
		coap_dtls_cpsk_t *	psk_data,
		coap_oscore_conf_t *	oscore_conf,
		void *	app_data,
		coap_app_data_free_callback_t	callback,
		coap_str_const_t *	ws_host
	)

Creates a new client session to the designated server, with PSK credentials protecting the data using OSCORE, along with app_data information (as per coap_session_set_app_data2()) and optional WebSockets host (as per coap_ws_set_host_request()) to remove timing window call-back in (D)TLS startup instead of doing coap_new_client_session_oscore_psk(); coap_session_set_app_data2(); or coap_new_client_session_oscore_psk(); coap_ws_set_host_request();.

Parameters

ctx	The CoAP context.
local_if	Address of local interface. It is recommended to use NULL to let the operating system choose a suitable local interface. If an address is specified, the port number should be zero, which means that a free port is automatically selected.
server	The server's address. If the port number is zero, the default port for the protocol will be used.
proto	CoAP Protocol.
psk_data	PSK parameters.
oscore_conf	OSCORE configuration information. This structure is freed off by this call.
app_data	The pointer to the application data to store or NULL.
callback	The optional release call-back for app_data on session removal or NULL.
ws_host	If proto is COAP_PROTO_WS or COAP_PROTO_WSS, then set the Host parameter accordingly.

Returns: A new CoAP session or NULL if failed. Call coap_session_release() to free.

◆ coap_new_oscore_conf()

coap_oscore_conf_t * coap_new_oscore_conf	(	coap_str_const_t	conf_mem,
		coap_oscore_save_seq_num_t	save_seq_num_func,
		void *	save_seq_num_func_param,
		uint64_t	start_seq_num
	)

Parse an OSCORE configuration (held in memory) and populate a OSCORE configuration structure.

Parameters

conf_mem	The current configuration in memory.
save_seq_num_func	Function to call to save Sender Sequence Number in non-volatile memory, or NULL.
save_seq_num_func_param	Parameter to pass into save_seq_num_func() function.
start_seq_num	The Sender Sequence Number to start with following a reboot retrieved out of non-volatile menory or 0.

Returns: The new OSCORE configuration. NULL if failed. It needs to be freed off with coap_delete_oscore_conf() when no longer required, otherwise it is freed off when coap_free_context() is called.

Definition at line 2346 of file coap_oscore.c.

◆ coap_new_oscore_recipient()

COAP_API int coap_new_oscore_recipient	(	coap_context_t *	context,
		coap_bin_const_t *	recipient_id
	)

Add in the specific Recipient ID into the OSCORE context (server only).

Note: This is only added to the OSCORE context as first defined by coap_new_client_session_oscore*() or coap_context_oscore_server().

Parameters

context	The CoAP context to add the OSCORE recipient_id to.
recipient_id	The Recipient ID to add.

Returns: 1 Successfully added, else 0 there is an issue.

Definition at line 2364 of file coap_oscore.c.

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ coap_oscore_save_seq_num_t

Function Documentation

◆ coap_context_oscore_server()

◆ coap_delete_oscore_conf()

◆ coap_delete_oscore_recipient()

◆ coap_new_client_session_oscore()

◆ coap_new_client_session_oscore3()

◆ coap_new_client_session_oscore_pki()

◆ coap_new_client_session_oscore_pki3()

◆ coap_new_client_session_oscore_psk()

◆ coap_new_client_session_oscore_psk3()

◆ coap_new_oscore_conf()

◆ coap_new_oscore_recipient()