Provided by: libcoap3-bin_4.3.4-1.1build4_amd64 
NAME
coap-oscore-conf - CoAP OSCORE configuration file format
DESCRIPTION
The OSCORE configuration file is read in when using the *-E* oscore_conf_file option for
the coap-client(5) or coap-server(5) executables. This then allows a client or server to
use OSCORE to protect the CoAP information between endpoints (RFC8613).
It is also read in and parsed by coap_new_oscore_conf(3).
This configuration file can be a configuration held in memory, the formatting of the
memory region is same as that for a file as if the file was mapped into memory. The
coap_new_oscore_conf(3) function uses the memory version of the file.
The configuration file comprises of a set of keywords, the value of the keyword encoding
type and the keyword value, one per line, comma separated.
keyword,encoding,value
The keywords are case sensitive. If a line starts with a #, then it is treated as a
comment line and so is ignored. Empty lines are also valid and ignored.
The possible encodings are:
ascii
The value is encoded as a binary representation of the ascii string. This string can
optionally be enclosed in ".
bool
The textual string is either true or false and is subsequently encoded as an integer
number.
hex
The value is encoded as a binary representation of the hex string. This string can
optionally be enclosed in ".
integer
The value is encoded as an integer number.
text
The string value is mapped and then encoded as an integer number. This string can
optionally be enclosed in ". A subset of the Names from
https://www.iana.org/assignments/cose/cose.xhtml#algorithms or
https://www.iana.org/assignments/cose/cose.xhtml#elliptic-curves are supported.
The valid keywords are:
master_secret
(hex or ascii) (Required) (No default)
"RFC8613 Section 3.1. Security Context Definition". Master Secret. Variable length.
Must be the same for both client and server.
master_salt
(hex or ascii) (Optional) (No default)
"RFC8613 Section 3.1. Security Context Definition". Master Salt. Variable length. Must
be the same for both client and server.
id_context
(hex or ascii) (Optional) (No default)
"RFC8613 Section 3.1. Security Context Definition". ID Context. Variable length. Must
be the same for both client and server.
sender_id
(hex or ascii) (Required) (No default)
"RFC8613 Section 3.1. Security Context Definition". Sender ID. This is the local
application ID. Maximum length is determined by the AEAD Algorithm (typically 7
bytes).
recipient_id
(hex or ascii) (Required for client, else Optional) (No default)
"RFC8613 Section 3.1. Security Context Definition". Recipient ID. This is the remote
peer application ID. Maximum length is determined by the AEAD Algorithm (typically 7
bytes). For servers, there can be zero or more (unique) recipient_ids. Additional
recipient_ids can be added programmatically to the OSCORE configuration - see
coap_new_oscore_recipient(3). For clients, there should only be one recipient_id (only
the first is used).
replay_window
(integer) (Optional) (Default is 32)
"RFC8613 Section 3.1. Security Context Definition". Recipient Replay Window (Server
Only). Supported values are 1 - 63.
aead_alg
(integer or text) (Optional) (Default is 10 or "AES-CCM-16-64-128")
"RFC8613 Section 3.1. Security Context Definition". AEAD Algorithm. Only the mandatory
and a small subset of the algorithms are supported depending on the TLS library.
hkdf_alg
(integer or text) (Optional) (Default is -10 or "direct+HKDF-SHA-256")
"RFC8613 Section 3.1. Security Context Definition". HDKF Algorithm. Only the mandatory
and a small subset of the algorithms are supported depending on the TLS library.
rfc8613_b_1_2
(bool) (Optional) (Default is true)
"RFC8613 Appendix B.1.2. Replay Window". Enable server rebooting Replay Window.
rfc8613_b_2
(bool) (Optional) (Default is false)
"RFC8613 Appendix B.2. Security Context Derived Multiple Times". Enable Security
Context protocol.
ssn_freq
(integer) (Optional) (Default is 1)
"RFC8613 Appendix B.1.1. Sender Sequence Number". Sender Sequence Number frequency
non-volatile storage update rate. Has to be a positive number.
Diagnostic testing options
break_sender_key
(bool) (Optional) (Default is false)
Enable random breaking of the derived sender key.
break_recipient_key
(bool) (Optional) (Default is false)
Enable random breaking of the derived recipient key.
EXAMPLE SERVER OSCORE CONFIGURATION FILE
# Master Secret (same for both client and server)
master_secret,hex,"0102030405060708090a0b0c0d0e0f10"
# Master Salt (same for both client and server)
master_salt,hex,"9e7ca92223786340"
# Sender ID
sender_id,ascii,"server"
# Recipient ID
recipient_id,ascii,"client"
# Replay Window (usually 32)
replay_window,integer,32
# AEAD COSE Cipher Algorithm (usually 10)
aead_alg,integer,10
# HKDF COSE Algorithm (usually -10)
hkdf_alg,integer,-10
EXAMPLE CLIENT OSCORE CONFIGURATION FILE
# Master Secret (same for both client and server)
master_secret,hex,"0102030405060708090a0b0c0d0e0f10"
# Master Salt (same for both client and server)
master_salt,hex,"9e7ca92223786340"
# Sender ID (This is the client who is the Sender)
sender_id,ascii,"client"
# Recipient ID (It is the server that is remote)
recipient_id,ascii,"server"
# Replay Window (usually 32)
replay_window,integer,32
# AEAD COSE Cipher Algorithm (usually 10)
aead_alg,integer,10
# HKDF COSE Algorithm (usually -10)
hkdf_alg,integer,-10
SEE ALSO
coap-client(5), coap-server(5) and coap_new_oscore_conf(3)
FURTHER INFORMATION
See
"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>