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

Collaboration diagram for OSCORE Support:

Typedefs
typedef coap_oscore_conf_t (	coap_oscore_find_handler_t) (const coap_session_t session, const coap_bin_const_t rcpkey_id, const coap_bin_const_t *ctxkey_id)
	Callback function type for overriding oscore_find_context().

typedef int(*	coap_oscore_update_seq_num_handler_t) (const coap_session_t session, const coap_bin_const_t rcpkey_id, const coap_bin_const_t *ctxkey_id, uint64_t receiver_seq_num, uint64_t seq_num_window)
	Callback function type for persisting the OSCORE receiver sequence number and anti-replay sliding window to an external storage.

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 void	coap_oscore_register_external_handlers (coap_context_t *context, coap_oscore_find_handler_t find_handler, coap_oscore_update_seq_num_handler_t update_seq_num_handler)
	Register external storage handlers for OSCORE session state.

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 stop any further OSCORE protection for this Recipient).

COAP_API int	coap_oscore_recipient_set_latest_seq (coap_oscore_conf_t oscore_conf, const coap_bin_const_t recipient_id, uint64_t last_seq, uint64_t seq_window)
	Set the latest sequence number and sliding window for the specified recipient id in the compiled configuration file.

Detailed Description

API functions for interfacing with OSCORE (RFC8613)

Typedef Documentation

◆ coap_oscore_find_handler_t

typedef coap_oscore_conf_t *(* coap_oscore_find_handler_t) (const coap_session_t *session, const coap_bin_const_t *rcpkey_id, const coap_bin_const_t *ctxkey_id)

Callback function type for overriding oscore_find_context().

If set via coap_oscore_register_external_handlers(), this function is called before the internal oscore_find_context() to locate the OSCORE recipient and security context for an incoming request.

The implementation of this function should be combined with coap_oscore_update_seq_num_handler_t if sequence counter management is required. Otherwise, libcoap will lose those values and replay protection will not work properly.

Parameters

session	The active CoAP session receiving the request from.
rcpkey_id	The Recipient Key ID (KID).
ctxkey_id	The ID Context to match or NULL.

Returns: The OSCORE config retrieved from the custom OSCORE storage or NULL if not found. Will fallback to libcoap internal credential storage lookup.

Definition at line 54 of file coap_oscore.h.

◆ 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 314 of file coap_oscore.h.

◆ coap_oscore_update_seq_num_handler_t

typedef int(* coap_oscore_update_seq_num_handler_t) (const coap_session_t *session, const coap_bin_const_t *rcpkey_id, const coap_bin_const_t *ctxkey_id, uint64_t receiver_seq_num, uint64_t seq_num_window)

Callback function type for persisting the OSCORE receiver sequence number and anti-replay sliding window to an external storage.

Called by the library whenever the Receiver Sequence Number or the anti-replay window is updated, giving the application the opportunity to store both values for external OSCORE credential management. Required to provide those values via the coap_oscore_find_handler_t callback, since the values will otherwise be lost.

Parameters

session	The active CoAP session receiving the request from.
rcpkey_id	The Recipient ID for which the sequence number and window applies.
ctxkey_id	The ID Context for which the sequence number and window applies.
receiver_seq_num	The receiver sequence number.
seq_num_window	The 64-bit anti-replay sliding window bitmask.

Returns: 1 if persisted successfully, else 0.

Definition at line 77 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 2960 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 released, else 0 if not valid.

Definition at line 2980 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 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 be removed.
recipient_id	The Recipient ID to remove.

Returns: 1 Successfully removed, else 0 not found.

Definition at line 2994 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 2850 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.

Definition at line 2864 of file coap_oscore.c.

◆ 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 2922 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.

Definition at line 2938 of file coap_oscore.c.

◆ 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 2884 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.

Definition at line 2900 of file coap_oscore.c.

◆ 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 2968 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. Ownership of memory moves into the function and will be freed off when the context is freed or if the function fails.

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

Definition at line 2986 of file coap_oscore.c.

◆ coap_oscore_recipient_set_latest_seq()

COAP_API int coap_oscore_recipient_set_latest_seq	(	coap_oscore_conf_t *	oscore_conf,
		const coap_bin_const_t *	recipient_id,
		uint64_t	last_seq,
		uint64_t	seq_window
	)

Set the latest sequence number and sliding window for the specified recipient id in the compiled configuration file.

Parameters

oscore_conf	The compiled configuration file.
recipient_id	The Recipient ID to update in `oscore_conf`.
last_seq	The sequence number to update the recipient id with.
seq_window	The sliding window to update the recipient id with.

Returns: 1 Successfully updated, else 0 recipient id not found.

◆ coap_oscore_register_external_handlers()

COAP_API void coap_oscore_register_external_handlers	(	coap_context_t *	context,
		coap_oscore_find_handler_t	find_handler,
		coap_oscore_update_seq_num_handler_t	update_seq_num_handler
	)

Register external storage handlers for OSCORE session state.

Allows providing a custom OSCORE credential storage for persistence and optimized for the needs of the application. Expands the built-in OSCORE context lookup and enables management of persistent OSCORE data (sequence numbers and Echo challenges) from within the application.

Parameters

context	The CoAP context to configure.
find_handler	Inject a customized OSCORE config-lookup function to return temporary oscore credentials managed by an external credential store (see coap_oscore_find_handler_t), or `NULL` to only use the built-in oscore_find_context().
update_seq_num_handler	Called whenever the Sender Sequence Number or anti-replay window changes. Use this to synchronize values with the external credential storage. `NULL` to disable. If find_handler is set, then it is recommended that update_seq_num_handler is set.

Definition at line 3002 of file coap_oscore.c.

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ coap_oscore_find_handler_t

◆ coap_oscore_save_seq_num_t

◆ coap_oscore_update_seq_num_handler_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()

◆ coap_oscore_recipient_set_latest_seq()

◆ coap_oscore_register_external_handlers()