1// -*- mode:doc; -*- 2// vim: set syntax=asciidoc tw=0 3 4coap-oscore-conf(5) 5=================== 6:doctype: manpage 7:man source: coap-oscore-conf 8:man version: @PACKAGE_VERSION@ 9:man manual: Coap OSCORE configuration file format 10 11NAME 12----- 13coap-oscore-conf 14- CoAP OSCORE configuration file format 15 16DESCRIPTION 17----------- 18The OSCORE configuration file is read in when using the _*-E* oscore_conf_file_ 19option for the *coap-client*(5) or *coap-server*(5) executables. This then 20allows a client or server to use OSCORE to protect the CoAP information 21between endpoints (https://rfc-editor.org/rfc/rfc8613[RFC8613]). 22 23It is also read in and parsed by *coap_new_oscore_conf*(3). 24 25This configuration file can be a configuration held in memory, the formatting 26of the memory region is same as that for a file as if the file was mapped 27into memory. The *coap_new_oscore_conf*(3) function uses the memory 28version of the file. 29 30The configuration file comprises of a set of keywords, the value of the 31keyword encoding type and the keyword value, one per line, comma separated. 32 33keyword,encoding,value 34 35The keywords are case sensitive. If a line starts with a *#*, then it is 36treated as a comment line and so is ignored. Empty lines are also valid 37and ignored. 38 39The possible encodings are: 40 41*ascii* :: 42 The value is encoded as a binary representation of the ascii string. This 43 string can optionally be enclosed in _"_. 44 45*bool* :: 46 The textual string is either true or false and is subsequently encoded as 47 an integer number. 48 49*hex* :: 50 The value is encoded as a binary representation of the hex string. This 51 string can optionally be enclosed in _"_. 52 53*integer* :: 54 The value is encoded as an integer number. 55 56*text* :: 57 The string value is mapped and then encoded as an integer number. This 58 string can optionally be enclosed in _"_. A subset of the Names from 59 https://www.iana.org/assignments/cose/cose.xhtml#algorithms or 60 https://www.iana.org/assignments/cose/cose.xhtml#elliptic-curves are 61 supported. 62 63The valid keywords are: 64 65*master_secret* :: 66 (*hex* or *ascii*) (*Required*) (No default) + 67 "https://rfc-editor.org/rfc/rfc8613#section-3.1[RFC8613 Section 3.1. 68 Security Context Definition]". 69 Master Secret. Variable length. Must be the same for both client and 70 server. 71 72*master_salt* :: 73 (*hex* or *ascii*) (*Optional*) (No default) + 74 "https://rfc-editor.org/rfc/rfc8613#section-3.1[RFC8613 Section 3.1. 75 Security Context Definition]". 76 Master Salt. Variable length. Must be the same for both client and 77 server. 78 79*id_context* :: 80 (*hex* or *ascii*) (*Optional*) (No default) + 81 "https://rfc-editor.org/rfc/rfc8613#section-3.1[RFC8613 Section 3.1. 82 Security Context Definition]". 83 ID Context. Variable length. Must be the same for both client and 84 server. 85 86*sender_id* :: 87 (*hex* or *ascii*) (*Required*) (No default) + 88 "https://rfc-editor.org/rfc/rfc8613#section-3.1[RFC8613 Section 3.1. 89 Security Context Definition]". 90 Sender ID. This is the local application ID. 91 Maximum length is determined by the AEAD Algorithm (typically 7 bytes). 92 93*recipient_id* :: 94 (*hex* or *ascii*) (*Required* for client, else *Optional*) (No default) + 95 "https://rfc-editor.org/rfc/rfc8613#section-3.1[RFC8613 Section 3.1. 96 Security Context Definition]". 97 Recipient ID. This is the remote peer application ID. 98 Maximum length is determined by the AEAD Algorithm (typically 7 bytes). 99 For servers, there can be zero or more (unique) recipient_ids. 100 Additional recipient_ids can be added programmatically to the OSCORE 101 configuration - see *coap_new_oscore_recipient*(3). 102 For clients, there should only be one recipient_id (only the first is used). 103 104*replay_window* :: 105 (*integer*) (*Optional*) (Default is 32) + 106 "https://rfc-editor.org/rfc/rfc8613#section-3.1[RFC8613 Section 3.1. 107 Security Context Definition]". 108 Recipient Replay Window (Server Only). Supported values are 1 - 63. 109 110*aead_alg* :: 111 (*integer* or *text*) (*Optional*) (Default is 10 or "AES-CCM-16-64-128") + 112 "https://rfc-editor.org/rfc/rfc8613#section-3.1[RFC8613 Section 3.1. 113 Security Context Definition]". 114 AEAD Algorithm. Only the mandatory and a small subset of the algorithms 115 are supported depending on the TLS library. 116 117*hkdf_alg* :: 118 (*integer* or *text*) (*Optional*) (Default is -10 or "direct+HKDF-SHA-256") + 119 "https://rfc-editor.org/rfc/rfc8613#section-3.1[RFC8613 Section 3.1. 120 Security Context Definition]". 121 HDKF Algorithm. Only the mandatory and a small subset of the algorithms 122 are supported depending on the TLS library. 123 124*rfc8613_b_1_2* :: 125 (*bool*) (*Optional*) (Default is true) + 126 "https://rfc-editor.org/rfc/rfc8613#appendix-B.1.2[RFC8613 Appendix B.1.2. 127 Replay Window]". 128 Enable server rebooting Replay Window. 129 130*rfc8613_b_2* :: 131 (*bool*) (*Optional*) (Default is false) + 132 "https://rfc-editor.org/rfc/rfc8613#appendix-B.2[RFC8613 Appendix B.2. 133 Security Context Derived Multiple Times]". 134 Enable Security Context protocol. 135 136*ssn_freq* :: 137 (*integer*) (*Optional*) (Default is 1) + 138 "https://rfc-editor.org/rfc/rfc8613#appendix-B.1.1[RFC8613 Appendix B.1.1. 139 Sender Sequence Number]". 140 Sender Sequence Number frequency non-volatile storage update rate. Has 141 to be a positive number. 142 143Diagnostic testing options 144 145*break_sender_key* :: 146 (*bool*) (*Optional*) (Default is false) + 147 Enable random breaking of the derived sender key. 148 149*break_recipient_key* :: 150 (*bool*) (*Optional*) (Default is false) + 151 Enable random breaking of the derived recipient key. 152 153EXAMPLE SERVER OSCORE CONFIGURATION FILE 154---------------------------------------- 155 156[source, c] 157---- 158 159# Master Secret (same for both client and server) 160master_secret,hex,"0102030405060708090a0b0c0d0e0f10" 161 162# Master Salt (same for both client and server) 163master_salt,hex,"9e7ca92223786340" 164 165# Sender ID 166sender_id,ascii,"server" 167 168# Recipient ID 169recipient_id,ascii,"client" 170 171# Replay Window (usually 32) 172replay_window,integer,32 173 174# AEAD COSE Cipher Algorithm (usually 10) 175aead_alg,integer,10 176 177# HKDF COSE Algorithm (usually -10) 178hkdf_alg,integer,-10 179 180---- 181 182EXAMPLE CLIENT OSCORE CONFIGURATION FILE 183---------------------------------------- 184 185[source, c] 186---- 187 188# Master Secret (same for both client and server) 189master_secret,hex,"0102030405060708090a0b0c0d0e0f10" 190 191# Master Salt (same for both client and server) 192master_salt,hex,"9e7ca92223786340" 193 194# Sender ID (This is the client who is the Sender) 195sender_id,ascii,"client" 196 197# Recipient ID (It is the server that is remote) 198recipient_id,ascii,"server" 199 200# Replay Window (usually 32) 201replay_window,integer,32 202 203# AEAD COSE Cipher Algorithm (usually 10) 204aead_alg,integer,10 205 206# HKDF COSE Algorithm (usually -10) 207hkdf_alg,integer,-10 208 209---- 210 211SEE ALSO 212-------- 213 214*coap-client*(5), *coap-server*(5) and *coap_new_oscore_conf*(3) 215 216FURTHER INFORMATION 217------------------- 218See 219 220"https://tools.ietf.org/html/rfc8613[RFC8613: Object Security for Constrained RESTful Environments (OSCORE)]" 221 222for further information. 223 224BUGS 225----- 226Please report bugs on the mailing list for libcoap: 227libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at 228https://github.com/obgm/libcoap/issues 229 230AUTHORS 231------- 232The libcoap project <libcoap-developers@lists.sourceforge.net> 233