--- name: "coap-oscore-conf" section: "5" platform: "linux" package: "libcoap3-bin" version: "4.3.4-1.1+deb13u3" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/coap-oscore-conf" --- # coap-oscore-conf(5) CoAP OSCORE configuration file format ## 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)](/coap-client/5.md) or [**coap-server**(5)](/coap-server/5.md) 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)](/coap_new_oscore_conf/3.md). 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)](/coap_new_oscore_conf/3.md) 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)](/coap_new_oscore_recipient/3.md). 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-client/5.md), [**coap-server**(5)](/coap-server/5.md) and [**coap\_new\_oscore\_conf**(3)](/coap_new_oscore_conf/3.md) ## 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 \