COAP-OSCORE-CONF(5)

📦
version 4.3.5 · 9 versions
, in ubuntu stonking

💖 coap-oscore-conf(5) — the CoAP OSCORE configuration file format, explained by your fave ✨

Okay bestie, so this is the manual page for coap-oscore-conf — the config file format for OSCORE, and honestly it's giving "small file, big responsibilities" energy 💅. Let's get into it.

🌸 NAME 🌸

coap-oscore-conf — the CoAP OSCORE configuration file format. That's it, that's the name, no cap.

✨ DESCRIPTION ✨

So here's the tea: this OSCORE config file gets read in when you use the -E oscore_conf_file option with the coap-client(5) or coap-server(5) executables. And what does that do? It lets a client or server use OSCORE to protect the CoAP information between endpoints — that's RFC8613, bestie, look it up 🦋.

It's also read in and parsed by coap_new_oscore_conf(3). Two ways in, same file, iconic.

Here's a lil detail that matters: this configuration file can be a configuration held in memory, and the formatting of that memory region is the same as that for a file — literally as if the file was mapped into memory. The coap_new_oscore_conf(3) function uses the memory version of the file. So same vibes, different delivery method 💫.

The file itself is a set of keywords: you've got the keyword, the value of the keyword's encoding type, and the keyword value. One per line, comma separated. Like this 👇

keyword,encoding,value

Keywords are case sensitive — do not play with the casing, fr. If a line starts with a #, it's treated as a comment line and gets ignored. Empty lines are also valid and ignored. So you can absolutely sprinkle comments everywhere, main character energy 🌈.

🎀 The possible encodings (iykyk) 🎀

  • 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 it's 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 (aka the whole menu) 🔥

  • 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. Same secret, both sides, no exceptions 💜
  • 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). So like, don't go stacking recipient_ids as a client, she's a one-recipient_id kind of client 🙈
  • 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. So like… it depends on your TLS library, babe 🫶
  • 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. (Yes, the original says "HDKF" there — we keep it exactly as written, I don't make the rules 💀)
  • 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. Positive. Number. Do not test me ⭐

💀 Diagnostic testing options 💀

These are for testing, bestie — not your everyday config 🧚

  • 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 🦋

Like, here's a whole server config you can straight-up copy:

# 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 🌸

And here's the client one — notice the sender/recipient IDs are swapped, that's the whole point babe 💅

# 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 🌈

Go give these a read, they're literally faves: 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. That's the source of truth, go drink your water and read it 💖

🙈 BUGS 🙈

Found a bug? Please raise an issue on GitHub at https://github.com/obgm/libcoap/issues to report any bugs. And if you've got a fix? Please raise a Pull Request at https://github.com/obgm/libcoap/pulls for any fixes. Community slay 🫶

💜 AUTHORS 💜

The libcoap project <libcoap-developers@lists.sourceforge.net>

K that's the whole page, you ate it 💅✨

Sign-off vibes: this beauty is coap-oscore-conf 4.3.5, dated 08/24/2026 — and it's the COAP-OSCORE-CONF(5) page, go forth and OSCORE responsibly 🎀💖🌟

📦 where this page comes from