libcoap 4.3.3
OSCORE Support

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. More...
 

Functions

int coap_oscore_is_supported (void)
 Check whether OSCORE is available. More...
 
coap_session_tcoap_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. More...
 
coap_session_tcoap_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. More...
 
coap_session_tcoap_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. More...
 
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. More...
 
coap_oscore_conf_tcoap_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. More...
 
int coap_delete_oscore_conf (coap_oscore_conf_t *oscore_conf)
 Release all the information associated with the OSCORE configuration. More...
 
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). More...
 
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). More...
 

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_numThe Sender Sequence Number to save in non-volatile memory.
paramThe 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 137 of file coap_oscore.h.

Function Documentation

◆ coap_context_oscore_server()

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
contextThe current coap_context_t object.
oscore_confOSCORE configuration information. This structure is freed off by this call.
Returns
1 if successful, else 0.

Definition at line 2155 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_confThe OSCORE configuration structure to release.
Returns
1 Successfully removed, else 0 not found.

Definition at line 2175 of file coap_oscore.c.

◆ coap_delete_oscore_recipient()

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
contextThe CoAP context holding the OSCORE recipient_id to.
recipient_idThe Recipient ID to remove.
Returns
1 Successfully removed, else 0 not found.

Definition at line 2189 of file coap_oscore.c.

◆ coap_new_client_session_oscore()

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.

Parameters
ctxThe CoAP context.
local_ifAddress 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.
serverThe server's address. If the port number is zero, the default port for the protocol will be used.
protoCoAP Protocol.
oscore_confOSCORE 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 2109 of file coap_oscore.c.

◆ coap_new_client_session_oscore_pki()

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.

Parameters
ctxThe CoAP context.
local_ifAddress 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.
serverThe server's address. If the port number is zero, the default port for the protocol will be used.
protoCoAP Protocol.
pki_dataPKI parameters.
oscore_confOSCORE 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 2139 of file coap_oscore.c.

◆ coap_new_client_session_oscore_psk()

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.

Parameters
ctxThe CoAP context.
local_ifAddress 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.
serverThe server's address. If the port number is zero, the default port for the protocol will be used.
protoCoAP Protocol.
psk_dataPSK parameters.
oscore_confOSCORE 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 2123 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_memThe current configuration in memory.
save_seq_num_funcFunction to call to save Sender Sequence Number in non-volatile memory, or NULL.
save_seq_num_func_paramParameter to pass into save_seq_num_func() function.
start_seq_numThe 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 2163 of file coap_oscore.c.

◆ coap_new_oscore_recipient()

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
contextThe CoAP context to add the OSCORE recipient_id to.
recipient_idThe Recipient ID to add.
Returns
1 Successfully added, else 0 there is an issue.

Definition at line 2181 of file coap_oscore.c.

◆ coap_oscore_is_supported()

int coap_oscore_is_supported ( void  )

Check whether OSCORE is available.

Returns
1 if support for OSCORE is enabled, or 0 otherwise.

Definition at line 2104 of file coap_oscore.c.

+ Here is the caller graph for this function: