Provided by: libcoap3t64_4.3.4-1.1build4_amd64 
NAME
coap_oscore, coap_oscore_is_supported, coap_new_oscore_conf, coap_delete_oscore_conf,
coap_new_oscore_recipient, coap_delete_oscore_recipient, coap_new_client_session_oscore,
coap_new_client_session_oscore_pki, coap_new_client_session_oscore_psk, coap_context_oscore_server - Work
with CoAP OSCORE
SYNOPSIS
#include <coap3/coap.h>
int coap_oscore_is_supported(void);
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);
int coap_delete_oscore_conf(coap_oscore_conf_t *oscore_conf);
int coap_new_oscore_recipient(coap_context_t *context, coap_bin_const_t *recipient_id);
int coap_delete_oscore_recipient(coap_context_t *context, coap_bin_const_t *recipient_id);
coap_session_t *coap_new_client_session_oscore(coap_context_t *context, const coap_address_t *local_if,
const coap_address_t *server, coap_proto_t proto, coap_oscore_conf_t *oscore_conf);
coap_session_t *coap_new_client_session_oscore_psk(coap_context_t *context, 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);
coap_session_t *coap_new_client_session_oscore_pki(coap_context_t *context, 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);
int coap_context_oscore_server(coap_context_t *context, coap_oscore_conf_t *oscore_conf);
For specific (D)TLS library support, link with -lcoap-3-notls, -lcoap-3-gnutls, -lcoap-3-openssl,
-lcoap-3-mbedtls or -lcoap-3-tinydtls. Otherwise, link with -lcoap-3 to get the default (D)TLS library
support.
DESCRIPTION
This describes libcoap’s support for using OSCORE as defined in RFC8613.
OSCORE provides end-to-end protection between endpoints communicating using CoAP. (D)TLS can only protect
HOP by HOP traffic which allows proxies to manipulate information.
CALLBACK HANDLER
Callback Type: coap_oscore_save_seq_num_t
The coap_oscore_save_seq_num_t method handler function prototype is defined as:
typedef int (*coap_oscore_save_seq_num_t)(uint64_t sender_seq_num, void *param);
and returns 0 on failure, 1 on succes.
FUNCTIONS
Function: coap_oscore_is_supported()
The coap_oscore_is_supported() function returns 1 if OSCORE is supported, otherwise 0.
Function: coap_new_oscore_conf()
The coap_new_oscore_conf() function is used to build a new OSCORE configuration. It parses the provided
OSCORE configuration in conf_mem. The format of the keywords, encoding types and values is documented in
coap-oscore-conf(5). It also sets an optional function save_seq_num_func (which gets
save_seq_num_func_param passed in) that is called to store the next Sender Sequence Number (SSN) in
non-volatile storage. The latest next SSN from non-volatile storage (or 0) is then put in start_seq_num.
SSN are used so that anti-replay mechanisms do not kick in following application restarts. The rate of
calling save_seq_num_func can be controlled by the ssn_freq parameter as defined in coap-oscore-conf(5).
This OSCORE configuration is then used in the client and server OSCORE version of the setup functions.
If the server is proxy enabled and the new incoming session is OSCORE encoded with the Outer CoAP
ProxyScheme and Host options set, then the libcoap logic will determine whether the server is the final
endpoint of the session, or whether the proxy will be forwarding the session off to another server, based
on how coap_resource_proxy_uri_init(3) configured the proxy logic. If the session is going to forwarded,
then the OSCORE protection will not be removed.
If coap_context_oscore_server() is not called and the proxy logic (if set) indicates the session will get
forwarded, then the OSCORE protection is untouched, otherwise the session will get dropped with an
unknown critical option error response.
Function: coap_new_oscore_recipient()
The coap_new_oscore_recipient() is used to add a new recipient_id to the OSCORE information associated
with context. The new recipient_id should be unique and this function should only be used for server
based applications as the client will only ever use the first defined recipient_id. It is assumed that
coap_context_oscore_server() has already been called to update context with the appropriate OSCORE
information.
Function: coap_delete_oscore_recipient()
The coap_delete_oscore_recipient() is used to remove the recipient_id from the OSCORE information
associated with context. OSCORE Traffic continuing to use recipient_id will then fail.
Function: coap_delete_oscore_conf()
The coap_delete_oscore_conf() function is used to free off the coap_oscore_conf_t structure oscore_conf
as returned by coap_new_oscore_conf(). Normally this function never needs to be called as oscore_conf is
freed off by the call the client or server setup functions.
Function: coap_new_client_session_oscore()
The coap_new_client_session_oscore() is basically the same as coap_new_client_session(3), but has an
additional parameter oscore_conf that is created by coap_new_oscore_conf(). This function creates a
client endpoint for a specific context and initiates a new client session to the specified server using
the CoAP protocol proto and OSCORE protected by the oscore_conf definition (which is freed off by this
call). If the port is set to 0 in server, then the default CoAP port is used. Normally local_if would be
set to NULL, but by specifying local_if the source of the network session can be bound to a specific IP
address or port. The session will initially have a reference count of 1.
Function: coap_new_client_session_oscore_psk()
The coap_new_client_session_oscore_psk() is basically the same as coap_new_client_session_psk2(3), but
has an additional parameter oscore_conf that is created by coap_new_oscore_conf(). This function, for a
specific context, is used to configure the TLS context using the setup_data variables as defined in the
coap_dtls_cpsk_t structure in the newly created endpoint session - see coap_encryption(3), as well as
OSCORE protected by the oscore_conf definition (which is freed off by this call). The connection is to
the specified server using the CoAP protocol proto. If the port is set to 0 in server, then the default
CoAP port is used. Normally local_if would be set to NULL, but by specifying local_if the source of the
network session can be bound to a specific IP address or port. The session will initially have a
reference count of 1.
Function: coap_new_client_session_oscore_pki()
The coap_new_client_session_oscore_pki() is basically the same as coap_new_client_session_pki(3), but has
an additional parameter oscore_conf that is created by coap_new_oscore_conf(). This function, for a
specific context, is used to configure the TLS context using the setup_data variables as defined in the
coap_dtls_pki_t structure in the newly created endpoint session - see coap_encryption(3), as well as
OSCORE protected by the oscore_conf definition (which is freed off by this call). The connection is to
the specified server using the CoAP protocol proto. If the port is set to 0 in server, then the default
CoAP port is used. Normally local_if would be set to NULL, but by specifying local_if the source of the
network session can be bound to a specific IP address or port. The session will initially have a
reference count of 1.
Function: coap_context_oscore_server()
The coap_context_oscore_server() function is used to enable the server to support OSCORE incoming
sessions. It updates context with the OSCORE configure oscore_conf (which is freed off by this call).
RETURN VALUES
coap_new_client_session_oscore(), coap_new_client_session_oscore_psk() and
coap_new_client_session_oscore_pki() return a newly created client session or NULL if there is a malloc
or parameter failure.
coap_new_oscore_conf() returns a coap_oscore_conf_t or NULL on failure.
coap_oscore_is_supported(), coap_context_oscore_server(), coap_delete_oscore_conf(),
coap_new_oscore_recipient() and coap_delete_oscore_recipient() return 0 on failure, 1 on success.
EXAMPLES
Client Setup
#include <coap3/coap.h>
#include <netinet/in.h>
#include <stdio.h>
static uint8_t oscore_config[] =
"master_secret,hex,\"0102030405060708090a0b0c0d0e0f10\"\n"
"master_salt,hex,\"9e7ca92223786340\"\n"
"server_id,ascii,\"client\"\n"
"recipient_id,ascii,\"server\"\n"
"replay_window,integer,30\n"
"aead_alg,integer,10\n"
"hkdf_alg,integer,-10\n"
;
static FILE *oscore_seq_num_fp = NULL;
/* Not a particularly safe place to keep next Sender Sequence Number ... */
static const char* oscore_seq_save_file = "/tmp/client.seq";
static int
oscore_save_seq_num(uint64_t sender_seq_num, void *param COAP_UNUSED) {
if (oscore_seq_num_fp) {
rewind(oscore_seq_num_fp);
fprintf(oscore_seq_num_fp, "%lu\n", sender_seq_num);
fflush(oscore_seq_num_fp);
}
return 1;
}
static coap_session_t *
setup_client_session (struct in_addr ip_address) {
coap_session_t *session;
coap_address_t server;
/* See coap_context(3) */
coap_context_t *context = coap_new_context(NULL);
if (!context)
return NULL;
/* See coap_block(3) */
coap_context_set_block_mode(context,
COAP_BLOCK_USE_LIBCOAP | COAP_BLOCK_SINGLE_BODY);
coap_address_init(&server);
server.addr.sa.sa_family = AF_INET;
server.addr.sin.sin_addr = ip_address;
server.addr.sin.sin_port = htons (5683);
if (coap_oscore_is_supported()) {
coap_str_const_t config = { sizeof (oscore_config), oscore_config };
uint64_t start_seq_num = 0;
coap_oscore_conf_t *oscore_conf;
if (oscore_seq_save_file) {
oscore_seq_num_fp = fopen(oscore_seq_save_file, "r+");
if (oscore_seq_num_fp == NULL) {
/* Try creating it */
oscore_seq_num_fp = fopen(oscore_seq_save_file, "w+");
if (oscore_seq_num_fp == NULL) {
coap_log_err("OSCORE save restart info file error: %s\n",
oscore_seq_save_file);
return NULL;
}
}
fscanf(oscore_seq_num_fp, "%ju", &start_seq_num);
}
oscore_conf = coap_new_oscore_conf(config, oscore_save_seq_num,
NULL, start_seq_num);
if (!oscore_conf) {
coap_free_context(context);
return NULL;
}
session = coap_new_client_session_oscore(context, NULL, &server,
COAP_PROTO_UDP, oscore_conf);
} else {
session = coap_new_client_session(context, NULL, &server, COAP_PROTO_UDP);
}
if (!session) {
coap_free_context(context);
return NULL;
}
/* The context is in session->context */
return session;
}
Server Setup
#include <coap3/coap.h>
#include <stdio.h>
static uint8_t oscore_config[] =
"master_secret,hex,\"0102030405060708090a0b0c0d0e0f10\"\n"
"master_salt,hex,\"9e7ca92223786340\"\n"
"sender_id,ascii,\"server\"\n"
"recipient_id,ascii,\"client\"\n"
"replay_window,integer,30\n"
"aead_alg,integer,10\n"
"hkdf_alg,integer,-10\n"
;
static FILE *oscore_seq_num_fp = NULL;
/* Not a particularly safe place to keep next Sender Sequence Number ... */
static const char* oscore_seq_save_file = "/tmp/server.seq";
static int
oscore_save_seq_num(uint64_t sender_seq_num, void *param COAP_UNUSED) {
if (oscore_seq_num_fp) {
rewind(oscore_seq_num_fp);
fprintf(oscore_seq_num_fp, "%lu\n", sender_seq_num);
fflush(oscore_seq_num_fp);
}
return 1;
}
static int
setup_context (void) {
/* See coap_context(3) */
coap_context_t *context = coap_new_context(NULL);
if (!context)
return 0;
/* See coap_block(3) */
coap_context_set_block_mode(context,
COAP_BLOCK_USE_LIBCOAP | COAP_BLOCK_SINGLE_BODY);
if (coap_oscore_is_supported()) {
coap_str_const_t config = { sizeof (oscore_config), oscore_config };
uint64_t start_seq_num = 0;
coap_oscore_conf_t *oscore_conf;
if (oscore_seq_save_file) {
oscore_seq_num_fp = fopen(oscore_seq_save_file, "r+");
if (oscore_seq_num_fp == NULL) {
/* Try creating it */
oscore_seq_num_fp = fopen(oscore_seq_save_file, "w+");
if (oscore_seq_num_fp == NULL) {
coap_log_err("OSCORE save restart info file error: %s\n",
oscore_seq_save_file);
return 0;
}
}
fscanf(oscore_seq_num_fp, "%ju", &start_seq_num);
}
oscore_conf = coap_new_oscore_conf(config, oscore_save_seq_num,
NULL, start_seq_num);
if (!oscore_conf) {
coap_free_context(context);
return 0;
}
coap_context_oscore_server(context, oscore_conf);
}
return 1;
}
SEE ALSO
coap_endpoint_client(3), coap_endpoint_server(3) and coap-oscore-conf(5)
FURTHER INFORMATION
See
"RFC7252: The Constrained Application Protocol (CoAP)"
"RFC8613: Object Security for Constrained RESTful Environments (OSCORE)"
for further information.
BUGS
Please report bugs on the mailing list for libcoap: libcoap-developers@lists.sourceforge.net or raise an
issue on GitHub at https://github.com/obgm/libcoap/issues
AUTHORS
The libcoap project <libcoap-developers@lists.sourceforge.net>