1COAP-OSCORE-CONF(5) Coap OSCORE configuration file COAP-OSCORE-CONF(5)
2
6 coap-oscore-conf - CoAP OSCORE configuration file format
7
9 The OSCORE configuration file is read in when using the *-E*
10 oscore_conf_file option for the coap-client(5) or coap-server(5)
11 executables. This then allows a client or server to use OSCORE to
12 protect the CoAP information between endpoints (RFC8613).
13 It is also read in and parsed by coap_new_oscore_conf(3).
15 This configuration file can be a configuration held in memory, the
17 formatting of the memory region is same as that for a file as if the
18 file was mapped into memory. The coap_new_oscore_conf(3) function uses
19 the memory version of the file.
20 The configuration file comprises of a set of keywords, the value of the
22 keyword encoding type and the keyword value, one per line, comma
23 separated.
24 keyword,encoding,value
26 The keywords are case sensitive. If a line starts with a #, then it is
28 treated as a comment line and so is ignored. Empty lines are also valid
29 and ignored.
30 The possible encodings are:
32 ascii
34 The value is encoded as a binary representation of the ascii
35 string. This string can optionally be enclosed in ".
36 bool
38 The textual string is either true or false and is subsequently
39 encoded as an integer number.
40 hex
42 The value is encoded as a binary representation of the hex string.
43 This string can optionally be enclosed in ".
44 integer
46 The value is encoded as an integer number.
47 text
49 The string value is mapped and then encoded as an integer number.
50 This string can optionally be enclosed in ". A subset of the Names
51 from https://www.iana.org/assignments/cose/cose.xhtml#algorithms or
52 https://www.iana.org/assignments/cose/cose.xhtml#elliptic-curves
53 are supported.
54 The valid keywords are:
56 master_secret
58 (hex or ascii) (Required) (No default)
59 "RFC8613 Section 3.1. Security Context Definition". Master Secret.
61 Variable length. Must be the same for both client and server.
62 master_salt
64 (hex or ascii) (Optional) (No default)
65 "RFC8613 Section 3.1. Security Context Definition". Master Salt.
67 Variable length. Must be the same for both client and server.
68 id_context
70 (hex or ascii) (Optional) (No default)
71 "RFC8613 Section 3.1. Security Context Definition". ID Context.
73 Variable length. Must be the same for both client and server.
74 sender_id
76 (hex or ascii) (Required) (No default)
77 "RFC8613 Section 3.1. Security Context Definition". Sender ID. This
79 is the local application ID. Maximum length is determined by the
80 AEAD Algorithm (typically 7 bytes).
81 recipient_id
83 (hex or ascii) (Required for client, else Optional) (No default)
84 "RFC8613 Section 3.1. Security Context Definition". Recipient ID.
86 This is the remote peer application ID. Maximum length is
87 determined by the AEAD Algorithm (typically 7 bytes). For servers,
88 there can be zero or more (unique) recipient_ids. Additional
89 recipient_ids can be added programmatically to the OSCORE
90 configuration - see coap_new_oscore_recipient(3). For clients,
91 there should only be one recipient_id (only the first is used).
92 replay_window
94 (integer) (Optional) (Default is 32)
95 "RFC8613 Section 3.1. Security Context Definition". Recipient
97 Replay Window (Server Only). Supported values are 1 - 63.
98 aead_alg
100 (integer or text) (Optional) (Default is 10 or "AES-CCM-16-64-128")
101 "RFC8613 Section 3.1. Security Context Definition". AEAD Algorithm.
103 Only the mandatory and a small subset of the algorithms are
104 supported depending on the TLS library.
105 hkdf_alg
107 (integer or text) (Optional) (Default is -10 or
108 "direct+HKDF-SHA-256")
109 "RFC8613 Section 3.1. Security Context Definition". HDKF Algorithm.
111 Only the mandatory and a small subset of the algorithms are
112 supported depending on the TLS library.
113 rfc8613_b_1_2
115 (bool) (Optional) (Default is true)
116 "RFC8613 Appendix B.1.2. Replay Window". Enable server rebooting
118 Replay Window.
119 rfc8613_b_2
121 (bool) (Optional) (Default is false)
122 "RFC8613 Appendix B.2. Security Context Derived Multiple Times".
124 Enable Security Context protocol.
125 ssn_freq
127 (integer) (Optional) (Default is 1)
128 "RFC8613 Appendix B.1.1. Sender Sequence Number". Sender Sequence
130 Number frequency non-volatile storage update rate. Has to be a
131 positive number.
132 Diagnostic testing options
134 break_sender_key
136 (bool) (Optional) (Default is false)
137 Enable random breaking of the derived sender key.
139 break_recipient_key
141 (bool) (Optional) (Default is false)
142 Enable random breaking of the derived recipient key.
144
146 # Master Secret (same for both client and server)
147 master_secret,hex,"0102030405060708090a0b0c0d0e0f10"
148 # Master Salt (same for both client and server)
150 master_salt,hex,"9e7ca92223786340"
151 # Sender ID
153 sender_id,ascii,"server"
154 # Recipient ID
156 recipient_id,ascii,"client"
157 # Replay Window (usually 32)
159 replay_window,integer,32
160 # AEAD COSE Cipher Algorithm (usually 10)
162 aead_alg,integer,10
163 # HKDF COSE Algorithm (usually -10)
165 hkdf_alg,integer,-10
166
168 # Master Secret (same for both client and server)
169 master_secret,hex,"0102030405060708090a0b0c0d0e0f10"
170 # Master Salt (same for both client and server)
172 master_salt,hex,"9e7ca92223786340"
173 # Sender ID (This is the client who is the Sender)
175 sender_id,ascii,"client"
176 # Recipient ID (It is the server that is remote)
178 recipient_id,ascii,"server"
179 # Replay Window (usually 32)
181 replay_window,integer,32
182 # AEAD COSE Cipher Algorithm (usually 10)
184 aead_alg,integer,10
185 # HKDF COSE Algorithm (usually -10)
187 hkdf_alg,integer,-10
188
190 coap-client(5), coap-server(5) and coap_new_oscore_conf(3)
191
193 See
194 "RFC8613: Object Security for Constrained RESTful Environments
196 (OSCORE)"
197 for further information.
199
201 Please report bugs on the mailing list for libcoap:
202 libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at
203 https://github.com/obgm/libcoap/issues
204
206 The libcoap project <libcoap-developers@lists.sourceforge.net>
207coap-oscore-conf 4.3.4 10/09/2023 COAP-OSCORE-CONF(5)