'\" t
.\" Title: coap-oscore-conf
.\" Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot
.\" Date: 04/07/2024
.\" Manual: Coap OSCORE configuration file format
.\" Source: coap-oscore-conf 4.3.4
.\" Language: English
.\"
.TH "COAP\-OSCORE\-CONF" "5" "04/07/2024" "coap\-oscore\-conf 4\&.3\&.4" "Coap OSCORE configuration file"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
coap-oscore-conf \- CoAP OSCORE configuration file format
.SH "DESCRIPTION"
.sp
The OSCORE configuration file is read in when using the \fI*\-E* oscore_conf_file\fR option for the \fBcoap\-client\fR(5) or \fBcoap\-server\fR(5) executables\&. This then allows a client or server to use OSCORE to protect the CoAP information between endpoints (RFC8613)\&.
.sp
It is also read in and parsed by \fBcoap_new_oscore_conf\fR(3)\&.
.sp
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 \fBcoap_new_oscore_conf\fR(3) function uses the memory version of the file\&.
.sp
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\&.
.sp
keyword,encoding,value
.sp
The keywords are case sensitive\&. If a line starts with a \fB#\fR, then it is treated as a comment line and so is ignored\&. Empty lines are also valid and ignored\&.
.sp
The possible encodings are:
.PP
\fBascii\fR
.RS 4
The value is encoded as a binary representation of the ascii string\&. This string can optionally be enclosed in
\fI"\fR\&.
.RE
.PP
\fBbool\fR
.RS 4
The textual string is either true or false and is subsequently encoded as an integer number\&.
.RE
.PP
\fBhex\fR
.RS 4
The value is encoded as a binary representation of the hex string\&. This string can optionally be enclosed in
\fI"\fR\&.
.RE
.PP
\fBinteger\fR
.RS 4
The value is encoded as an integer number\&.
.RE
.PP
\fBtext\fR
.RS 4
The string value is mapped and then encoded as an integer number\&. This string can optionally be enclosed in
\fI"\fR\&. 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\&.
.RE
.sp
The valid keywords are:
.PP
\fBmaster_secret\fR
.RS 4
(\fBhex\fR
or
\fBascii\fR) (\fBRequired\fR) (No default)
"RFC8613 Section 3\&.1\&. Security Context Definition"\&. Master Secret\&. Variable length\&. Must be the same for both client and server\&.
.RE
.PP
\fBmaster_salt\fR
.RS 4
(\fBhex\fR
or
\fBascii\fR) (\fBOptional\fR) (No default)
"RFC8613 Section 3\&.1\&. Security Context Definition"\&. Master Salt\&. Variable length\&. Must be the same for both client and server\&.
.RE
.PP
\fBid_context\fR
.RS 4
(\fBhex\fR
or
\fBascii\fR) (\fBOptional\fR) (No default)
"RFC8613 Section 3\&.1\&. Security Context Definition"\&. ID Context\&. Variable length\&. Must be the same for both client and server\&.
.RE
.PP
\fBsender_id\fR
.RS 4
(\fBhex\fR
or
\fBascii\fR) (\fBRequired\fR) (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)\&.
.RE
.PP
\fBrecipient_id\fR
.RS 4
(\fBhex\fR
or
\fBascii\fR) (\fBRequired\fR
for client, else
\fBOptional\fR) (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
\fBcoap_new_oscore_recipient\fR(3)\&. For clients, there should only be one recipient_id (only the first is used)\&.
.RE
.PP
\fBreplay_window\fR
.RS 4
(\fBinteger\fR) (\fBOptional\fR) (Default is 32)
"RFC8613 Section 3\&.1\&. Security Context Definition"\&. Recipient Replay Window (Server Only)\&. Supported values are 1 \- 63\&.
.RE
.PP
\fBaead_alg\fR
.RS 4
(\fBinteger\fR
or
\fBtext\fR) (\fBOptional\fR) (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\&.
.RE
.PP
\fBhkdf_alg\fR
.RS 4
(\fBinteger\fR
or
\fBtext\fR) (\fBOptional\fR) (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\&.
.RE
.PP
\fBrfc8613_b_1_2\fR
.RS 4
(\fBbool\fR) (\fBOptional\fR) (Default is true)
"RFC8613 Appendix B\&.1\&.2\&. Replay Window"\&. Enable server rebooting Replay Window\&.
.RE
.PP
\fBrfc8613_b_2\fR
.RS 4
(\fBbool\fR) (\fBOptional\fR) (Default is false)
"RFC8613 Appendix B\&.2\&. Security Context Derived Multiple Times"\&. Enable Security Context protocol\&.
.RE
.PP
\fBssn_freq\fR
.RS 4
(\fBinteger\fR) (\fBOptional\fR) (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\&.
.RE
.sp
Diagnostic testing options
.PP
\fBbreak_sender_key\fR
.RS 4
(\fBbool\fR) (\fBOptional\fR) (Default is false)
Enable random breaking of the derived sender key\&.
.RE
.PP
\fBbreak_recipient_key\fR
.RS 4
(\fBbool\fR) (\fBOptional\fR) (Default is false)
Enable random breaking of the derived recipient key\&.
.RE
.SH "EXAMPLE SERVER OSCORE CONFIGURATION FILE"
.sp
.if n \{\
.RS 4
.\}
.nf
# 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
.fi
.if n \{\
.RE
.\}
.SH "EXAMPLE CLIENT OSCORE CONFIGURATION FILE"
.sp
.if n \{\
.RS 4
.\}
.nf
# 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
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
.sp
\fBcoap\-client\fR(5), \fBcoap\-server\fR(5) and \fBcoap_new_oscore_conf\fR(3)
.SH "FURTHER INFORMATION"
.sp
See
.sp
"RFC8613: Object Security for Constrained RESTful Environments (OSCORE)"
.sp
for further information\&.
.SH "BUGS"
.sp
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
.SH "AUTHORS"
.sp
The libcoap project