idnits 2.17.1 draft-ietf-core-object-security-09.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 05, 2018) is 2243 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 6347 (Obsoleted by RFC 9147) ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 8152 (Obsoleted by RFC 9052, RFC 9053) == Outdated reference: A later version (-15) exists of draft-ietf-6tisch-minimal-security-04 == Outdated reference: A later version (-46) exists of draft-ietf-ace-oauth-authz-10 == Outdated reference: A later version (-19) exists of draft-ietf-ace-oscore-profile-00 == Outdated reference: A later version (-08) exists of draft-ietf-cbor-cddl-02 == Outdated reference: A later version (-14) exists of draft-ietf-core-echo-request-tag-00 == Outdated reference: A later version (-06) exists of draft-mattsson-core-coap-actuators-03 == Outdated reference: A later version (-14) exists of draft-selander-ace-cose-ecdhe-07 Summary: 5 errors (**), 0 flaws (~~), 8 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CoRE Working Group G. Selander 3 Internet-Draft J. Mattsson 4 Intended status: Standards Track F. Palombini 5 Expires: September 6, 2018 Ericsson AB 6 L. Seitz 7 RISE SICS 8 March 05, 2018 10 Object Security for Constrained RESTful Environments (OSCORE) 11 draft-ietf-core-object-security-09 13 Abstract 15 This document defines Object Security for Constrained RESTful 16 Environments (OSCORE), a method for application-layer protection of 17 the Constrained Application Protocol (CoAP), using CBOR Object 18 Signing and Encryption (COSE). OSCORE provides end-to-end protection 19 between endpoints communicating using CoAP or CoAP-mappable HTTP. 20 OSCORE is designed for constrained nodes and networks supporting a 21 range of proxy operations, including translation between different 22 transport protocols. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at https://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on September 6, 2018. 41 Copyright Notice 43 Copyright (c) 2018 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (https://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 59 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 60 2. The CoAP Object-Security Option . . . . . . . . . . . . . . . 6 61 3. The Security Context . . . . . . . . . . . . . . . . . . . . 7 62 3.1. Security Context Definition . . . . . . . . . . . . . . . 7 63 3.2. Establishment of Security Context Parameters . . . . . . 9 64 3.3. Requirements on the Security Context Parameters . . . . . 11 65 4. Protected Message Fields . . . . . . . . . . . . . . . . . . 12 66 4.1. CoAP Payload . . . . . . . . . . . . . . . . . . . . . . 13 67 4.2. CoAP Options . . . . . . . . . . . . . . . . . . . . . . 14 68 4.3. CoAP Header . . . . . . . . . . . . . . . . . . . . . . . 20 69 4.4. Signaling Messages . . . . . . . . . . . . . . . . . . . 21 70 5. The COSE Object . . . . . . . . . . . . . . . . . . . . . . . 22 71 5.1. Kid Context . . . . . . . . . . . . . . . . . . . . . . . 23 72 5.2. Nonce . . . . . . . . . . . . . . . . . . . . . . . . . . 24 73 5.3. Plaintext . . . . . . . . . . . . . . . . . . . . . . . . 24 74 5.4. Additional Authenticated Data . . . . . . . . . . . . . . 25 75 6. OSCORE Header Compression . . . . . . . . . . . . . . . . . . 26 76 6.1. Encoding of the Object-Security Value . . . . . . . . . . 26 77 6.2. Encoding of the OSCORE Payload . . . . . . . . . . . . . 27 78 6.3. Examples of Compressed COSE Objects . . . . . . . . . . . 28 79 7. Sequence Numbers, Replay, Message Binding, and Freshness . . 29 80 7.1. Message Binding . . . . . . . . . . . . . . . . . . . . . 29 81 7.2. AEAD Nonce Uniqueness . . . . . . . . . . . . . . . . . . 29 82 7.3. Freshness . . . . . . . . . . . . . . . . . . . . . . . . 30 83 7.4. Replay Protection . . . . . . . . . . . . . . . . . . . . 30 84 7.5. Losing Part of the Context State . . . . . . . . . . . . 31 85 8. Processing . . . . . . . . . . . . . . . . . . . . . . . . . 32 86 8.1. Protecting the Request . . . . . . . . . . . . . . . . . 32 87 8.2. Verifying the Request . . . . . . . . . . . . . . . . . . 33 88 8.3. Protecting the Response . . . . . . . . . . . . . . . . . 34 89 8.4. Verifying the Response . . . . . . . . . . . . . . . . . 35 90 9. Web Linking . . . . . . . . . . . . . . . . . . . . . . . . . 36 91 10. Proxy and HTTP Operations . . . . . . . . . . . . . . . . . . 37 92 10.1. CoAP-to-CoAP Forwarding Proxy . . . . . . . . . . . . . 37 93 10.2. HTTP Processing . . . . . . . . . . . . . . . . . . . . 37 94 10.3. HTTP-to-CoAP Translation Proxy . . . . . . . . . . . . . 39 95 10.4. CoAP-to-HTTP Translation Proxy . . . . . . . . . . . . . 40 96 11. Security Considerations . . . . . . . . . . . . . . . . . . . 42 97 11.1. End-to-end protection . . . . . . . . . . . . . . . . . 42 98 11.2. Security Context Establishment . . . . . . . . . . . . . 42 99 11.3. Replay Protection . . . . . . . . . . . . . . . . . . . 43 100 11.4. Cryptographic Considerations . . . . . . . . . . . . . . 43 101 11.5. Message Fragmentation . . . . . . . . . . . . . . . . . 43 102 11.6. Privacy Considerations . . . . . . . . . . . . . . . . . 44 103 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 45 104 12.1. COSE Header Parameters Registry . . . . . . . . . . . . 45 105 12.2. CoAP Option Numbers Registry . . . . . . . . . . . . . . 45 106 12.3. CoAP Signaling Option Numbers Registry . . . . . . . . . 45 107 12.4. Header Field Registrations . . . . . . . . . . . . . . . 46 108 12.5. Media Type Registrations . . . . . . . . . . . . . . . . 46 109 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 48 110 13.1. Normative References . . . . . . . . . . . . . . . . . . 48 111 13.2. Informative References . . . . . . . . . . . . . . . . . 49 112 Appendix A. Scenario examples . . . . . . . . . . . . . . . . . 51 113 A.1. Secure Access to Sensor . . . . . . . . . . . . . . . . . 51 114 A.2. Secure Subscribe to Sensor . . . . . . . . . . . . . . . 52 115 Appendix B. Deployment examples . . . . . . . . . . . . . . . . 54 116 B.1. Master Secret Used Once . . . . . . . . . . . . . . . . . 54 117 B.2. Master Secret Used Multiple Times . . . . . . . . . . . . 54 118 B.3. Client Aliveness . . . . . . . . . . . . . . . . . . . . 55 119 Appendix C. Test Vectors . . . . . . . . . . . . . . . . . . . . 56 120 C.1. Test Vector 1: Key Derivation with Master Salt . . . . . 56 121 C.2. Test Vector 2: Key Derivation without Master Salt . . . . 57 122 C.3. Test Vector 3: OSCORE Request, Client . . . . . . . . . . 58 123 C.4. Test Vector 4: OSCORE Request, Client . . . . . . . . . . 59 124 C.5. Test Vector 5: OSCORE Response, Server . . . . . . . . . 60 125 C.6. Test Vector 6: OSCORE Response with Partial IV, Server . 61 126 Appendix D. CDDL Summary . . . . . . . . . . . . . . . . . . . . 63 127 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 63 128 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 64 130 1. Introduction 132 The Constrained Application Protocol (CoAP) [RFC7252] is a web 133 application protocol, designed for constrained nodes and networks 134 [RFC7228], and may be mapped from HTTP [RFC8075]. CoAP specifies the 135 use of proxies for scalability and efficiency and references DTLS 136 ([RFC6347]) for security. CoAP and HTTP proxies require (D)TLS to be 137 terminated at the proxy. The proxy therefore not only has access to 138 the data required for performing the intended proxy functionality, 139 but is also able to eavesdrop on, or manipulate any part of the 140 message payload and metadata, in transit between the endpoints. The 141 proxy can also inject, delete, or reorder packets since they are no 142 longer protected by (D)TLS. 144 This document defines the Object Security for Constrained RESTful 145 Environments (OSCORE) security protocol, protecting CoAP and CoAP- 146 mappable HTTP requests and responses end-to-end across intermediary 147 nodes such as CoAP forward proxies and cross-protocol translators 148 including HTTP-to-CoAP proxies [RFC8075]. In addition to the core 149 CoAP features defined in [RFC7252], OSCORE supports Observe 150 [RFC7641], Blockwise [RFC7959], No-Response [RFC7967], and PATCH and 151 FETCH [RFC8132]. An analysis of end-to-end security for CoAP 152 messages through some types of intermediary nodes is performed in 153 [I-D.hartke-core-e2e-security-reqs]. OSCORE essentially protects the 154 RESTful interactions; the request method, the requested resource, the 155 message payload, etc. (see Section 4). OSCORE does neither protect 156 the CoAP Messaging Layer nor the CoAP Token which may change between 157 the endpoints, and those are therefore processed as defined in 158 [RFC7252]. Additionally, since the message formats for CoAP over 159 unreliable transport [RFC7252] and for CoAP over reliable transport 160 [RFC8323] differ only in terms of CoAP Messaging Layer, OSCORE can be 161 applied to both unreliable and reliable transports (see Figure 1). 163 +-----------------------------------+ 164 | Application | 165 +-----------------------------------+ 166 +-----------------------------------+ \ 167 | Requests / Responses / Signaling | | 168 |-----------------------------------| | 169 | OSCORE | | CoAP 170 |-----------------------------------| | 171 | Messaging Layer / Message Framing | | 172 +-----------------------------------+ / 173 +-----------------------------------+ 174 | UDP / TCP / ... | 175 +-----------------------------------+ 177 Figure 1: Abstract Layering of CoAP with OSCORE 179 OSCORE works in very constrained nodes and networks, thanks to its 180 small message size and the restricted code and memory requirements in 181 addition to what is required by CoAP. Examples of the use of OSCORE 182 are given in Appendix A. OSCORE does not depend on underlying 183 layers, and can be used anywhere where CoAP or HTTP can be used, 184 including non-IP transports (e.g., [I-D.bormann-6lo-coap-802-15-ie]). 185 OSCORE may be used together with (D)TLS over one or more hops in the 186 end-to-end path, e.g. with HTTPs in one hop and with plain CoAP in 187 another hop. 189 An extension of OSCORE may also be used to protect group 190 communication for CoAP [I-D.tiloca-core-multicast-oscoap]. The use 191 of OSCORE does not affect the URI scheme and OSCORE can therefore be 192 used with any URI scheme defined for CoAP or HTTP. The application 193 decides the conditions for which OSCORE is required. 195 OSCORE uses pre-shared keys which may have been established out-of- 196 band or with a key establishment protocol (see Section 3.2). The 197 technical solution builds on CBOR Object Signing and Encryption 198 (COSE) [RFC8152], providing end-to-end encryption, integrity, replay 199 protection, and secure binding of response to request. A compressed 200 version of COSE is used, as specified in Section 6. The use of 201 OSCORE is signaled with the new Object-Security CoAP option or HTTP 202 header field, defined in Section 2 and Section 10.3. The solution 203 transforms a CoAP/HTTP message into an "OSCORE message" before 204 sending, and vice versa after receiving. The OSCORE message is a 205 CoAP/HTTP message related to the original message in the following 206 way: the original CoAP/HTTP message is translated to CoAP (if not 207 already in CoAP) and protected in a COSE object. The encrypted 208 message fields of this COSE object are transported in the CoAP 209 payload/HTTP body of the OSCORE message, and the Object-Security 210 option/header field is included in the message. A sketch of an 211 OSCORE message exchange in the case of the original message being 212 CoAP is provided in Figure 2). 214 Client Server 215 | OSCORE request - POST example.com: | 216 | Header, Token, | 217 | Options: {Object-Security, ...}, | 218 | Payload: COSE ciphertext | 219 +--------------------------------------------->| 220 | | 221 |<---------------------------------------------+ 222 | OSCORE response - 2.04 (Changed): | 223 | Header, Token, | 224 | Options: {Object-Security, ...}, | 225 | Payload: COSE ciphertext | 226 | | 228 Figure 2: Sketch of CoAP with OSCORE 230 An implementation supporting this specification MAY only implement 231 the client part, MAY only implement the server part, or MAY only 232 implement one of the proxy parts. OSCORE is designed to protect as 233 much information as possible while still allowing proxy operations 234 (Section 10). It works with legacy CoAP-to-CoAP forward proxies 235 [RFC7252], but an OSCORE-aware proxy will be more efficient. HTTP- 236 to-CoAP proxies [RFC8075] and CoAP-to-HTTP proxies can also be used 237 with OSCORE, as specified in Section 10. 239 1.1. Terminology 241 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 242 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 243 document are to be interpreted as described in [RFC2119]. These 244 words may also appear in this document in lowercase, absent their 245 normative meanings. 247 Readers are expected to be familiar with the terms and concepts 248 described in CoAP [RFC7252], Observe [RFC7641], Blockwise [RFC7959], 249 COSE [RFC8152], CBOR [RFC7049], CDDL [I-D.ietf-cbor-cddl] as 250 summarized in Appendix D, and constrained environments [RFC7228]. 252 The term "hop" is used to denote a particular leg in the end-to-end 253 path. The concept "hop-by-hop" (as in "hop-by-hop encryption" or 254 "hop-by-hop fragmentation") opposed to "end-to-end", is used in this 255 document to indicate that the messages are processed accordingly in 256 the intermediaries, rather than just forwarded to the next node. 258 The term "stop processing" is used throughout the document to denote 259 that the message is not passed up to the CoAP Request/Response layer 260 (see Figure 1). 262 The terms Common/Sender/Recipient Context, Master Secret/Salt, Sender 263 ID/Key, Recipient ID/Key, and Common IV are defined in Section 3.1. 265 2. The CoAP Object-Security Option 267 The CoAP Object-Security option (see Figure 3) indicates that the 268 CoAP message is an OSCORE message and that it contains a compressed 269 COSE object (see Section 5 and Section 6). The Object-Security 270 option is critical, safe to forward, part of the cache key, and not 271 repeatable. 273 +-----+---+---+---+---+-----------------+--------+--------+---------+ 274 | No. | C | U | N | R | Name | Format | Length | Default | 275 +-----+---+---+---+---+-----------------+--------+--------+---------+ 276 | TBD | x | | | | Object-Security | (*) | 0-255 | (none) | 277 +-----+---+---+---+---+-----------------+--------+--------+---------+ 278 C = Critical, U = Unsafe, N = NoCacheKey, R = Repeatable 279 (*) See below. 281 Figure 3: The Object-Security Option 283 The Object-Security option includes the OSCORE flag bits (Section 6), 284 the Sender Sequence Number and the Sender ID when present 285 (Section 3). The detailed format and length is specified in 286 Section 6. If the OSCORE flag bits is all zero (0x00) the Option 287 value SHALL be empty (Option Length = 0). An endpoint receiving a 288 CoAP message without payload, that also contains an Object-Security 289 option SHALL treat it as malformed and reject it. 291 A successful response to a request with the Object-Security option 292 SHALL contain the Object-Security option. Whether error responses 293 contain the Object-Security option depends on the error type (see 294 Section 8). 296 A CoAP proxy SHOULD NOT cache a response to a request with an Object- 297 Security option, since the response is only applicable to the 298 original request (see Section 10.1). As the compressed COSE Object 299 is included in the cache key, messages with the Object-Security 300 option will never generate cache hits. For Max-Age processing (see 301 Section 4.2.3.1). 303 3. The Security Context 305 OSCORE requires that client and server establish a shared security 306 context used to process the COSE objects. OSCORE uses COSE with an 307 Authenticated Encryption with Additional Data (AEAD, [RFC5116]) 308 algorithm for protecting message data between a client and a server. 309 In this section, we define the security context and how it is derived 310 in client and server based on a shared secret and a key derivation 311 function (KDF). 313 3.1. Security Context Definition 315 The security context is the set of information elements necessary to 316 carry out the cryptographic operations in OSCORE. For each endpoint, 317 the security context is composed of a "Common Context", a "Sender 318 Context", and a "Recipient Context". 320 The endpoints protect messages to send using the Sender Context and 321 verify messages received using the Recipient Context, both contexts 322 being derived from the Common Context and other data. Clients and 323 servers need to be able to retrieve the correct security context to 324 use. 326 An endpoint uses its Sender ID (SID) to derive its Sender Context, 327 and the other endpoint uses the same ID, now called Recipient ID 328 (RID), to derive its Recipient Context. In communication between two 329 endpoints, the Sender Context of one endpoint matches the Recipient 330 Context of the other endpoint, and vice versa. Thus, the two 331 security contexts identified by the same IDs in the two endpoints are 332 not the same, but they are partly mirrored. Retrieval and use of the 333 security context are shown in Figure 4. 335 .-------------. .-------------. 336 | Common, | | Common, | 337 | Sender, | | Recipient, | 338 | Recipient | | Sender | 339 '-------------' '-------------' 340 Client Server 341 | | 342 Retrieve context for | OSCORE request: | 343 target resource | Token = Token1, | 344 Protect request with | kid = SID, ... | 345 Sender Context +---------------------->| Retrieve context with 346 | | RID = kid 347 | | Verify request with 348 | | Recipient Context 349 | OSCORE response: | Protect response with 350 | Token = Token1, ... | Sender Context 351 Retrieve context with |<----------------------+ 352 Token = Token1 | | 353 Verify request with | | 354 Recipient Context | | 356 Figure 4: Retrieval and use of the Security Context 358 The Common Context contains the following parameters: 360 o AEAD Algorithm. The COSE AEAD algorithm to use for encryption. 361 Its value is immutable once the security context is established. 363 o Key Derivation Function. The HMAC based HKDF [RFC5869] used to 364 derive Sender Key, Recipient Key, and Common IV. 366 o Master Secret. Variable length, uniformly random byte string 367 containing the key used to derive traffic keys and IVs. Its value 368 is immutable once the security context is established. 370 o Master Salt. Variable length byte string containing the salt used 371 to derive traffic keys and IVs. Its value is immutable once the 372 security context is established. 374 o Common IV. Byte string derived from Master Secret and Master 375 Salt. Length is determined by the AEAD Algorithm. Its value is 376 immutable once the security context is established. 378 The Sender Context contains the following parameters: 380 o Sender ID. Byte string used to identify the Sender Context and to 381 assure unique AEAD nonces. Maximum length is determined by the 382 AEAD Algorithm. Its value is immutable once the security context 383 is established. 385 o Sender Key. Byte string containing the symmetric key to protect 386 messages to send. Derived from Common Context and Sender ID. 387 Length is determined by the AEAD Algorithm. Its value is 388 immutable once the security context is established. 390 o Sender Sequence Number. Non-negative integer used by the sender 391 to protect requests and Observe notifications. Used as 'Partial 392 IV' [RFC8152] to generate unique nonces for the AEAD. Maximum 393 value is determined by the AEAD Algorithm. 395 The Recipient Context contains the following parameters: 397 o Recipient ID. Byte string used to identify the Recipient Context 398 and to assure unique AEAD nonces. Maximum length is determined by 399 the AEAD Algorithm. Its value is immutable once the security 400 context is established. 402 o Recipient Key. Byte string containing the symmetric key to verify 403 messages received. Derived from Common Context and Recipient ID. 404 Length is determined by the AEAD Algorithm. Its value is 405 immutable once the security context is established. 407 o Replay Window (Server only). The replay window to verify requests 408 received. 410 An endpoint may free up memory by not storing the Common IV, Sender 411 Key, and Recipient Key, deriving them from the Master Key and Master 412 Salt when needed. Alternatively, an endpoint may free up memory by 413 not storing the Master Secret and Master Salt after the other 414 parameters have been derived. 416 Endpoints MAY operate as both client and server and use the same 417 security context for those roles. Independent of being client or 418 server, the endpoint protects messages to send using its Sender 419 Context, and verifies messages received using its Recipient Context. 420 The endpoints MUST NOT change the Sender/Recipient ID when changing 421 roles. In other words, changing the roles does not change the set of 422 keys to be used. 424 3.2. Establishment of Security Context Parameters 426 The parameters in the security context are derived from a small set 427 of input parameters. The following input parameters SHALL be pre- 428 established: 430 o Master Secret 432 o Sender ID 434 o Recipient ID 436 The following input parameters MAY be pre-established. In case any 437 of these parameters is not pre-established, the default value 438 indicated below is used: 440 o AEAD Algorithm 442 * Default is AES-CCM-16-64-128 (COSE algorithm encoding: 10) 444 o Master Salt 446 * Default is the empty string 448 o Key Derivation Function (KDF) 450 * Default is HKDF SHA-256 452 o Replay Window Type and Size 454 * Default is DTLS-type replay protection with a window size of 32 455 ([RFC6347]) 457 All input parameters need to be known to and agreed on by both 458 endpoints, but the replay window may be different in the two 459 endpoints. How the input parameters are pre-established, is 460 application specific. The OSCORE profile of the ACE framework may be 461 used to establish the necessary input parameters 462 ([I-D.ietf-ace-oscore-profile]), or a key exchange protocol such as 463 the TLS/DTLS handshake ([I-D.mattsson-ace-tls-oscore]) or EDHOC 464 ([I-D.selander-ace-cose-ecdhe]) providing forward secrecy. Other 465 examples of deploying OSCORE are given in Appendix B. 467 3.2.1. Derivation of Sender Key, Recipient Key, and Common IV 469 The KDF MUST be one of the HMAC based HKDF [RFC5869] algorithms 470 defined in COSE. HKDF SHA-256 is mandatory to implement. The 471 security context parameters Sender Key, Recipient Key, and Common IV 472 SHALL be derived from the input parameters using the HKDF, which 473 consists of the composition of the HKDF-Extract and HKDF-Expand steps 474 ([RFC5869]): 476 output parameter = HKDF(salt, IKM, info, L) 478 where: 480 o salt is the Master Salt as defined above 482 o IKM is the Master Secret as defined above 484 o info is a CBOR array consisting of: 486 info = [ 487 id : bstr, 488 alg_aead : int / tstr, 489 type : tstr, 490 L : uint 491 ] 493 where: 495 o id is the Sender ID or Recipient ID when deriving keys and the 496 empty string when deriving the Common IV. The encoding is 497 described in Section 5. 499 o alg_aead is the AEAD Algorithm, encoded as defined in [RFC8152]. 501 o type is "Key" or "IV". The label is an ASCII string, and does not 502 include a trailing NUL byte. 504 o L is the size of the key/IV for the AEAD algorithm used, in bytes. 506 For example, if the algorithm AES-CCM-16-64-128 (see Section 10.2 in 507 [RFC8152]) is used, the integer value for alg_aead is 10, the value 508 for L is 16 for keys and 13 for the Common IV. 510 3.2.2. Initial Sequence Numbers and Replay Window 512 The Sender Sequence Number is initialized to 0. The supported types 513 of replay protection and replay window length is application specific 514 and depends on how OSCORE is transported, see Section 7.4. The 515 default is DTLS-type replay protection with a window size of 32 516 initiated as described in Section 4.1.2.6 of [RFC6347]. 518 3.3. Requirements on the Security Context Parameters 520 As collisions may lead to the loss of both confidentiality and 521 integrity, Sender ID SHALL be unique in the set of all security 522 contexts using the same Master Secret and Master Salt. When a 523 trusted third party assigns identifiers (e.g., using 524 [I-D.ietf-ace-oauth-authz]) or by using a protocol that allows the 525 parties to negotiate locally unique identifiers in each endpoint, the 526 Sender IDs can be very short. The maximum length of Sender ID in 527 bytes equals the length of AEAD nonce minus 6. For AES-CCM-16-64-128 528 the maximum length of Sender ID is 7 bytes. Sender IDs MAY be 529 uniformly random distributed byte strings if the probability of 530 collisions is negligible. 532 If Sender ID uniqueness cannot be guaranteed by construction, Sender 533 IDs MUST be long uniformly random distributed byte strings such that 534 the probability of collisions is negligible. 536 To simplify retrieval of the right Recipient Context, the Recipient 537 ID SHOULD be unique in the sets of all Recipient Contexts used by an 538 endpoint. If an endpoint has the same Recipient ID with different 539 Recipient Contexts, i.e. the Recipient Contexts are derived from 540 different keying material, then the endpoint may need to try multiple 541 times before finding the right security context associated to the 542 Recipient ID. The Client MAY provide a 'kid context' parameter 543 (Section 5.1) to help the Server find the right context. 545 While the triple (Master Secret, Master Salt, Sender ID) MUST be 546 unique, the same Master Salt MAY be used with several Master Secrets 547 and the same Master Secret MAY be used with several Master Salts. 549 4. Protected Message Fields 551 OSCORE transforms a CoAP message (which may have been generated from 552 an HTTP message) into an OSCORE message, and vice versa. OSCORE 553 protects as much of the original message as possible while still 554 allowing certain proxy operations (see Section 10). This section 555 defines how OSCORE protects the message fields and transfers them 556 end-to-end between client and server (in any direction). 558 The remainder of this section and later sections discuss the behavior 559 in terms of CoAP messages. If HTTP is used for a particular hop in 560 the end-to-end path, then this section applies to the conceptual CoAP 561 message that is mappable to/from the original HTTP message as 562 discussed in Section 10. That is, an HTTP message is conceptually 563 transformed to a CoAP message and then to an OSCORE message, and 564 similarly in the reverse direction. An actual implementation might 565 translate directly from HTTP to OSCORE without the intervening CoAP 566 representation. 568 Protection of Signaling messages (Section 5 of [RFC8323]) is 569 specified in Section 4.4. The other parts of this section target 570 Request/Response messages. 572 Message fields of the CoAP message may be protected end-to-end 573 between CoAP client and CoAP server in different ways: 575 o Class E: encrypted and integrity protected, 577 o Class I: integrity protected only, or 579 o Class U: unprotected. 581 The sending endpoint SHALL transfer Class E message fields in the 582 ciphertext of the COSE object in the OSCORE message. The sending 583 endpoint SHALL include Class I message fields in the Additional 584 Authenticated Data (AAD) of the AEAD algorithm, allowing the 585 receiving endpoint to detect if the value has changed in transfer. 586 Class U message fields SHALL NOT be protected in transfer. Class I 587 and Class U message field values are transferred in the header or 588 options part of the OSCORE message, which is visible to proxies. 590 Message fields not visible to proxies, i.e., transported in the 591 ciphertext of the COSE object, are called "Inner" (Class E). Message 592 fields transferred in the header or options part of the OSCORE 593 message, which is visible to proxies, are called "Outer" (Class I or 594 U). There are currently no Class I options defined. 596 An OSCORE message may contain both an Inner and an Outer instance of 597 a certain CoAP message field. Inner message fields are intended for 598 the receiving endpoint, whereas Outer message fields are used to 599 support proxy operations. Inner and Outer message fields are 600 processed independently. 602 4.1. CoAP Payload 604 The CoAP Payload, if present in the original CoAP message, SHALL be 605 encrypted and integrity protected and is thus an Inner message field. 606 See Figure 5. 608 +------------------+---+---+ 609 | Field | E | U | 610 +------------------+---+---+ 611 | Payload | x | | 612 +------------------+---+---+ 614 E = Encrypt and Integrity Protect (Inner) 615 U = Unprotected (Outer) 617 Figure 5: Protection of CoAP Payload 619 The sending endpoint writes the payload of the original CoAP message 620 into the plaintext (Section 5.3) input to the COSE object. The 621 receiving endpoint verifies and decrypts the COSE object, and 622 recreates the payload of the original CoAP message. 624 4.2. CoAP Options 626 A summary of how options are protected is shown in Figure 6. Note 627 that some options may have both Inner and Outer message fields which 628 are protected accordingly. The options which require special 629 processing are labelled with asterisks. 631 +-----+-----------------+---+---+ 632 | No. | Name | E | U | 633 +-----+-----------------+---+---+ 634 | 1 | If-Match | x | | 635 | 3 | Uri-Host | | x | 636 | 4 | ETag | x | | 637 | 5 | If-None-Match | x | | 638 | 6 | Observe | | * | 639 | 7 | Uri-Port | | x | 640 | 8 | Location-Path | x | | 641 | TBD | Object-Security | | * | 642 | 11 | Uri-Path | x | | 643 | 12 | Content-Format | x | | 644 | 14 | Max-Age | * | * | 645 | 15 | Uri-Query | x | | 646 | 17 | Accept | x | | 647 | 20 | Location-Query | x | | 648 | 23 | Block2 | * | * | 649 | 27 | Block1 | * | * | 650 | 28 | Size2 | * | * | 651 | 35 | Proxy-Uri | | * | 652 | 39 | Proxy-Scheme | | x | 653 | 60 | Size1 | * | * | 654 | 258 | No-Response | * | * | 655 +-----+-----------------+---+---+ 657 E = Encrypt and Integrity Protect (Inner) 658 U = Unprotected (Outer) 659 * = Special 661 Figure 6: Protection of CoAP Options 663 Options that are unknown or for which OSCORE processing is not 664 defined SHALL be processed as class E (and no special processing). 665 Specifications of new CoAP options SHOULD define how they are 666 processed with OSCORE. A new COAP option SHOULD be of class E unless 667 it requires proxy processing. 669 4.2.1. Inner Options 671 Inner option message fields (class E) are used to communicate 672 directly with the other endpoint. 674 The sending endpoint SHALL write the Inner option message fields 675 present in the original CoAP message into the plaintext of the COSE 676 object (Section 5.3), and then remove the Inner option message fields 677 from the OSCORE message. 679 The processing of Inner option message fields by the receiving 680 endpoint is specified in Section 8.2 and Section 8.4. 682 4.2.2. Outer Options 684 Outer option message fields (Class U or I) are used to support proxy 685 operations. 687 The sending endpoint SHALL include the Outer option message field 688 present in the original message in the options part of the OSCORE 689 message. All Outer option message fields, including Object-Security, 690 SHALL be encoded as described in Section 3.1 of [RFC7252], where the 691 delta is the difference to the previously included Outer option 692 message field. 694 The processing of Outer options by the receiving endpoint is 695 specified in Section 8.2 and Section 8.4. 697 A procedure for integrity-protection-only of Class I option message 698 fields is specified in Section 5.4. New CoAP options which are 699 repeatable and of class I MUST specify that proxies MUST NOT change 700 the order of the option's occurrences. 702 Note: There are currently no Class I option message fields defined. 704 4.2.3. Special Options 706 Some options require special processing, marked with an asterisk '*' 707 in Figure 6; the processing is specified in this section. 709 4.2.3.1. Max-Age 711 An Inner Max-Age message field is used to indicate the maximum time a 712 response may be cached by the client (as defined in [RFC7252]), end- 713 to-end from the server to the client, taking into account that the 714 option is not accessible to proxies. The Inner Max-Age SHALL be 715 processed by OSCORE as specified in Section 4.2.1. 717 An Outer Max-Age message field is used to avoid unnecessary caching 718 of OSCORE error responses at OSCORE unaware intermediary nodes. A 719 server MAY set a Class U Max-Age message field with value zero to 720 OSCORE error responses described in Section 7.4, Section 8.2 and 721 Section 8.4, which is then processed according to Section 4.2.2. 723 Successful OSCORE responses do not need to include an Outer Max-Age 724 option since the responses are non-cacheable by construction (see 725 Section 4.3). 727 4.2.3.2. The Block Options 729 Blockwise [RFC7959] is an optional feature. An implementation MAY 730 support [RFC7252] and the Object-Security option without supporting 731 Blockwise. The Block options (Block1, Block2, Size1, Size2), when 732 Inner message fields, provide secure message fragmentation such that 733 each fragment can be verified. The Block options, when Outer message 734 fields, enables hop-by-hop fragmentation of the OSCORE message. 735 Inner and Outer block processing may have different performance 736 properties depending on the underlying transport. The end-to-end 737 integrity of the message can be verified both in case of Inner and 738 Outer Blockwise provided all blocks are received. 740 4.2.3.2.1. Inner Block Options 742 The sending CoAP endpoint MAY fragment a CoAP message as defined in 743 [RFC7959] before the message is processed by OSCORE. In this case 744 the Block options SHALL be processed by OSCORE as Inner options 745 (Section 4.2.1). The receiving CoAP endpoint SHALL process the 746 OSCORE message according to Section 4.2.1 before processing Blockwise 747 as defined in [RFC7959]. 749 For concurrent Blockwise operations the sending endpoint MUST ensure 750 that the receiving endpoint can distinguish between blocks from 751 different operations. One mechanism enabling this is specified in 752 [I-D.ietf-core-echo-request-tag]. 754 4.2.3.2.2. Outer Block Options 756 Proxies MAY fragment an OSCORE message using [RFC7959], by 757 introducing Block option message fields that are Outer 758 (Section 4.2.2) and not generated by the sending endpoint. Note that 759 the Outer Block options are neither encrypted nor integrity 760 protected. As a consequence, a proxy can maliciously inject block 761 fragments indefinitely, since the receiving endpoint needs to receive 762 the last block (see [RFC7959]) to be able to compose the OSCORE 763 message and verify its integrity. Therefore, applications supporting 764 OSCORE and [RFC7959] MUST specify a security policy defining a 765 maximum unfragmented message size (MAX_UNFRAGMENTED_SIZE) considering 766 the maximum size of message which can be handled by the endpoints. 767 Messages exceeding this size SHOULD be fragmented by the sending 768 endpoint using Inner Block options (Section 4.2.3.2.1). 770 An endpoint receiving an OSCORE message with an Outer Block option 771 SHALL first process this option according to [RFC7959], until all 772 blocks of the OSCORE message have been received, or the cumulated 773 message size of the blocks exceeds MAX_UNFRAGMENTED_SIZE. In the 774 former case, the processing of the OSCORE message continues as 775 defined in this document. In the latter case the message SHALL be 776 discarded. 778 Because of encryption of Uri-Path and Uri-Query, messages to the same 779 server may, from the point of view of a proxy, look like they also 780 target the same resource. A proxy SHOULD mitigate a potential mix-up 781 of blocks from concurrent requests to the same server, for example 782 using the Request-Tag processing specified in Section 3.3.2 of 783 [I-D.ietf-core-echo-request-tag]. 785 4.2.3.3. Proxy-Uri 787 Proxy-Uri, when present, is split by OSCORE into class U options and 788 class E options, which are processed accordingly. When Proxy-Uri is 789 used in the original CoAP message, Uri-* are not present [RFC7252]. 791 The sending endpoint SHALL first decompose the Proxy-Uri value of the 792 original CoAP message into the Proxy-Scheme, Uri-Host, Uri-Port, Uri- 793 Path, and Uri-Query options (if present) according to Section 6.4 of 794 [RFC7252]. 796 Uri-Path and Uri-Query are class E options and SHALL be protected and 797 processed as Inner options (Section 4.2.1). 799 The Proxy-Uri option of the OSCORE message SHALL be set to the 800 composition of Proxy-Scheme, Uri-Host, and Uri-Port options (if 801 present) as specified in Section 6.5 of [RFC7252], and processed as 802 an Outer option of Class U (Section 4.2.2). 804 Note that replacing the Proxy-Uri value with the Proxy-Scheme and 805 Uri-* options works by design for all CoAP URIs (see Section 6 of 806 [RFC7252]). OSCORE-aware HTTP servers should not use the userinfo 807 component of the HTTP URI (as defined in Section 3.2.1 of [RFC3986]), 808 so that this type of replacement is possible in the presence of CoAP- 809 to-HTTP proxies. In future documents specifying cross-protocol 810 proxying behavior using different URI structures, it is expected that 811 the authors will create Uri-* options that allow decomposing the 812 Proxy-Uri, and specify in which OSCORE class they belong. 814 An example of how Proxy-Uri is processed is given here. Assume that 815 the original CoAP message contains: 817 o Proxy-Uri = "coap://example.com/resource?q=1" 819 During OSCORE processing, Proxy-Uri is split into: 821 o Proxy-Scheme = "coap" 823 o Uri-Host = "example.com" 825 o Uri-Port = "5683" 827 o Uri-Path = "resource" 829 o Uri-Query = "q=1" 831 Uri-Path and Uri-Query follow the processing defined in 832 Section 4.2.1, and are thus encrypted and transported in the COSE 833 object. The remaining options are composed into the Proxy-Uri 834 included in the options part of the OSCORE message, which has value: 836 o Proxy-Uri = "coap://example.com" 838 See Sections 6.1 and 12.6 of [RFC7252] for more information. 840 4.2.3.4. Observe 842 Observe [RFC7641] is an optional feature. An implementation MAY 843 support [RFC7252] and the Object-Security option without supporting 844 [RFC7641]. The Observe option as used here targets the requirements 845 on forwarding of [I-D.hartke-core-e2e-security-reqs] (Section 2.2.1). 847 In order for an OSCORE-unaware proxy to support forwarding of Observe 848 messages ([RFC7641]), there SHALL be an Outer Observe option, i.e., 849 present in the options part of the OSCORE message. The processing of 850 the CoAP Code for Observe messages is described in Section 4.3. 852 To secure the order of notifications, the client SHALL maintain a 853 Notification Number for each Observation it registers. The 854 Notification Number is a non-negative integer containing the largest 855 Partial IV of the successfully received notifications for the 856 associated Observe registration (see Section 7.4). The Notification 857 Number is initialized to the Partial IV of the first successfully 858 received notification response to the registration request. In 859 contrast to [RFC7641], the received Partial IV MUST always be 860 compared with the Notification Number, which thus MUST NOT be 861 forgotten after 128 seconds. The client MAY ignore the Observe 862 option value. 864 If the verification fails, the client SHALL stop processing the 865 response. 867 The Observe option in the CoAP request may be legitimately removed by 868 a proxy. If the Observe option is removed from a CoAP request by a 869 proxy, then the server can still verify the request (as a non-Observe 870 request), and produce a non-Observe response. If the OSCORE client 871 receives a response to an Observe request without an Outer Observe 872 value, then it MUST verify the response as a non-Observe response. 873 If the OSCORE client receives a response to a non-Observe request 874 with an Outer Observe value, it stops processing the message, as 875 specified in Section 8.4. 877 Clients can re-register observations to ensure that the observation 878 is still active and establish freshness again ([RFC7641] 879 Section 3.3.1). When an OSCORE observation is refreshed, not only 880 the ETags, but also the partial IV (and thus the payload and Object- 881 Security option) change. The server uses the new request's Partial 882 IV as the 'request_piv' of new responses. 884 4.2.3.5. No-Response 886 No-Response is defined in [RFC7967]. Clients using No-Response MUST 887 set both an Inner (Class E) and an Outer (Class U) No-Response 888 option, with same value. 890 The Inner No-Response option is used to communicate to the server the 891 client's disinterest in certain classes of responses to a particular 892 request. The Inner No-Response SHALL be processed by OSCORE as 893 specified in Section 4.2.1. 895 The Outer No-Response option is used to support proxy functionality, 896 specifically to avoid error transmissions from proxies to clients, 897 and to avoid bandwidth reduction to servers by proxies applying 898 congestion control when not receiving responses. The Outer No- 899 Response option is processed according to Section 4.2.2. 901 In particular, step 8 of Section 8.4 is applied to No-Response. 903 Applications should consider that a proxy may remove the Outer No- 904 Response option from the request. Applications using No-Response can 905 specify policies to deal with cases where servers receive an Inner 906 No-Response option only, which may be the result of the request 907 having traversed a No-Response unaware proxy, and update the 908 processing in Section 8.4 accordingly. This avoids unnecessary error 909 responses to clients and bandwidth reductions to servers, due to No- 910 Response unaware proxies. 912 4.2.3.6. Object-Security 914 The Object-Security option is only defined to be present in OSCORE 915 messages, as an indication that OSCORE processing have been 916 performed. The content in the Object-Security option is neither 917 encrypted nor integrity protected as a whole but some part of the 918 content of this option is protected (see Section 5.4). "OSCORE 919 within OSCORE" is not supported: If OSCORE processing detects an 920 Object-Security option in the original CoAP message, then processing 921 SHALL be stopped. 923 4.3. CoAP Header 925 A summary of how the CoAP Header fields are protected is shown in 926 Figure 7, including fields specific to CoAP over UDP and CoAP over 927 TCP (marked accordingly in the table). 929 +------------------+---+---+ 930 | Field | E | U | 931 +------------------+---+---+ 932 | Version (UDP) | | x | 933 | Type (UDP) | | x | 934 | Length (TCP) | | x | 935 | Token Length | | x | 936 | Code | x | | 937 | Message ID (UDP) | | x | 938 | Token | | x | 939 +------------------+---+---+ 941 E = Encrypt and Integrity Protect (Inner) 942 U = Unprotected (Outer) 944 Figure 7: Protection of CoAP Header Fields 946 Most CoAP Header fields (i.e. the message fields in the fixed 4-byte 947 header) are required to be read and/or changed by CoAP proxies and 948 thus cannot in general be protected end-to-end between the endpoints. 949 As mentioned in Section 1, OSCORE protects the CoAP Request/Response 950 layer only, and not the Messaging Layer (Section 2 of [RFC7252]), so 951 fields such as Type and Message ID are not protected with OSCORE. 953 The CoAP Header field Code is protected by OSCORE. Code SHALL be 954 encrypted and integrity protected (Class E) to prevent an 955 intermediary from eavesdropping or manipulating the Code (e.g., 956 changing from GET to DELETE). 958 The sending endpoint SHALL write the Code of the original CoAP 959 message into the plaintext of the COSE object (see Section 5.3). 960 After that, the Outer Code of the OSCORE message SHALL be set to 0.02 961 (POST) for requests without Observe option, to 0.05 (FETCH) for 962 requests with Observe option, and to 2.04 (Changed) for responses. 963 Using FETCH with Observe allows OSCORE to be compliant with the 964 Observe processing in OSCORE-unaware proxies. The choice of POST and 965 FETCH ([RFC8132]) allows all OSCORE messages to have payload. 967 The receiving endpoint SHALL discard the Code in the OSCORE message 968 and write the Code of the plaintext in the COSE object (Section 5.3) 969 into the decrypted CoAP message. 971 The other CoAP Header fields are Unprotected (Class U). The sending 972 endpoint SHALL write all other header fields of the original message 973 into the header of the OSCORE message. The receiving endpoint SHALL 974 write the header fields from the received OSCORE message into the 975 header of the decrypted CoAP message. 977 4.4. Signaling Messages 979 Signaling messages (CoAP Code 7.00-7.31) were introduced to exchange 980 information related to an underlying transport connection in the 981 specific case of CoAP over reliable transports ([RFC8323]). The use 982 of OSCORE for protecting Signaling is application dependent. 984 OSCORE MAY be used to protect Signaling if the endpoints for OSCORE 985 coincide with the endpoints for the connection. If OSCORE is used to 986 protect Signaling then: 988 o Signaling messages SHALL be protected as CoAP Request messages, 989 except in the case the Signaling message is a response to a 990 previous Signaling message, in which case it SHALL be protected as 991 a CoAP Response message. For example, 7.02 (Ping) is protected as 992 a CoAP Request and 7.03 (Pong) as a CoAP response. 994 o The Outer Code for Signaling messages SHALL be set to 0.02 (POST), 995 unless it is a response to a previous Signaling message, in which 996 case it SHALL be set to 2.04 (Changed). 998 o All Signaling options, except the Object-Security option, SHALL be 999 Inner (Class E). 1001 NOTE: Option numbers for Signaling messages are specific to the CoAP 1002 Code (see Section 5.2 of [RFC8323]). 1004 If OSCORE is not used to protect Signaling, Signaling messages SHALL 1005 be unaltered by OSCORE. 1007 5. The COSE Object 1009 This section defines how to use COSE [RFC8152] to wrap and protect 1010 data in the original message. OSCORE uses the untagged COSE_Encrypt0 1011 structure with an Authenticated Encryption with Additional Data 1012 (AEAD) algorithm. The key lengths, IV length, nonce length, and 1013 maximum Sender Sequence Number are algorithm dependent. 1015 The AEAD algorithm AES-CCM-16-64-128 defined in Section 10.2 of 1016 [RFC8152] is mandatory to implement. For AES-CCM-16-64-128 the 1017 length of Sender Key and Recipient Key is 128 bits, the length of 1018 nonce and Common IV is 13 bytes. The maximum Sender Sequence Number 1019 is specified in Section 11. 1021 As specified in [RFC5116], plaintext denotes the data that is 1022 encrypted and integrity protected, and Additional Authenticated Data 1023 (AAD) denotes the data that is integrity protected only. 1025 The COSE Object SHALL be a COSE_Encrypt0 object with fields defined 1026 as follows 1028 o The 'protected' field is empty. 1030 o The 'unprotected' field includes: 1032 * The 'Partial IV' parameter. The value is set to the Sender 1033 Sequence Number. All leading zeroes SHALL be removed when 1034 encoding the Partial IV. The value 0 encodes to the byte 1035 string 0x00. This parameter SHALL be present in requests. In 1036 case of Observe (Section 4.2.3.4) the Partial IV SHALL be 1037 present in responses, and otherwise the Partial IV SHOULD NOT 1038 be present in responses. (A non-Observe example where the 1039 Partial IV is included in a response is provided in 1040 Section 7.5.2.) 1042 * The 'kid' parameter. The value is set to the Sender ID. This 1043 parameter SHALL be present in requests and SHOULD NOT be 1044 present in responses. An example where the Sender ID is 1045 included in a response is the extension of OSCORE to group 1046 communication [I-D.tiloca-core-multicast-oscoap]. 1048 * Optionally, a 'kid context' parameter as defined in 1049 Section 5.1. This parameter MAY be present in requests and 1050 SHALL NOT be present in responses. 1052 o The 'ciphertext' field is computed from the secret key (Sender Key 1053 or Recipient Key), AEAD nonce (see Section 5.2), plaintext (see 1054 Section 5.3), and the Additional Authenticated Data (AAD) (see 1055 Section 5.4) following Section 5.2 of [RFC8152]. 1057 The encryption process is described in Section 5.3 of [RFC8152]. 1059 5.1. Kid Context 1061 For certain use cases, e.g. deployments where the same kid is used 1062 with multiple contexts, it is necessary or favorable for the sender 1063 to provide an additional identifier of the security material to use, 1064 in order for the receiver to retrieve or establish the correct key. 1065 The kid context parameter is used to provide such additional input. 1066 The kid context and kid are used to determine the security context, 1067 or to establish the necessary input parameters to derive the security 1068 context (see Section 3.2). The application defines how this is done. 1070 The kid context is implicitly integrity protected, as manipulation 1071 that leads to the wrong key (or no key) being retrieved which results 1072 in an error, as described in Section 8.2. 1074 A summary of the COSE header parameter kid context defined above can 1075 be found in Figure 8. 1077 Some examples of relevant uses of kid context are the following: 1079 o If the client has an identifier in some other namespace which can 1080 be used by the server to retrieve or establish the security 1081 context, then that identifier can be used as kid context. The kid 1082 context may be used as Master Salt (Section 3.1) for additional 1083 entropy of the security contexts (see for example Appendix B.2 or 1084 [I-D.ietf-6tisch-minimal-security]). 1086 o In case of a group communication scenario 1087 [I-D.tiloca-core-multicast-oscoap], if the server belongs to 1088 multiple groups, then a group identifier can be used as kid 1089 context to enable the server to find the right security context. 1091 +----------+--------+------------+----------------+-----------------+ 1092 | name | label | value type | value registry | description | 1093 +----------+--------+------------+----------------+-----------------+ 1094 | kid | kidctx | bstr | | Identifies the | 1095 | context | | | | kid context | 1096 +----------+--------+------------+----------------+-----------------+ 1098 Figure 8: Additional common header parameter for the COSE object 1100 5.2. Nonce 1102 The AEAD nonce is constructed in the following way (see Figure 9): 1104 1. left-padding the Partial IV (in network byte order) with zeroes 1105 to exactly 5 bytes, 1107 2. left-padding the (Sender) ID of the endpoint that generated the 1108 Partial IV (in network byte order) with zeroes to exactly nonce 1109 length - 6 bytes, 1111 3. concatenating the size of the ID (S) with the padded ID and the 1112 padded Partial IV, 1114 4. and then XORing with the Common IV. 1116 Note that in this specification only algorithms that use nonces equal 1117 or greater than 7 bytes are supported. The nonce construction with 1118 S, ID of PIV generator, and Partial IV together with endpoint unique 1119 IDs and encryption keys make it easy to verify that the nonces used 1120 with a specific key will be unique. 1122 When Observe is not used, the request and the response may use the 1123 same nonce. In this way, the Partial IV does not have to be sent in 1124 responses, which reduces the size. For processing instructions (see 1125 Section 8). 1127 +---+-----------------------+--+--+--+--+--+ 1128 | S | ID of PIV generator | Partial IV |----+ 1129 +---+-----------------------+--+--+--+--+--+ | 1130 | 1131 +------------------------------------------+ | 1132 | Common IV |->(XOR) 1133 +------------------------------------------+ | 1134 | 1135 +------------------------------------------+ | 1136 | Nonce |<---+ 1137 +------------------------------------------+ 1139 Figure 9: AEAD Nonce Formation 1141 5.3. Plaintext 1143 The plaintext is formatted as a CoAP message without Header (see 1144 Figure 10) consisting of: 1146 o the Code of the original CoAP message as defined in Section 3 of 1147 [RFC7252]; and 1149 o all Inner option message fields (see Section 4.2.1) present in the 1150 original CoAP message (see Section 4.2). The options are encoded 1151 as described in Section 3.1 of [RFC7252], where the delta is the 1152 difference to the previously included Class E option; and 1154 o the Payload of original CoAP message, if present, and in that case 1155 prefixed by the one-byte Payload Marker (0xFF). 1157 0 1 2 3 1158 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1159 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1160 | Code | Class E options (if any) ... 1161 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1162 |1 1 1 1 1 1 1 1| Payload (if any) ... 1163 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1164 (only if there 1165 is payload) 1167 Figure 10: Plaintext 1169 NOTE: The plaintext contains all CoAP data that needs to be encrypted 1170 end-to-end between the endpoints. 1172 5.4. Additional Authenticated Data 1174 The external_aad SHALL be a CBOR array as defined below: 1176 external_aad = [ 1177 oscore_version : uint, 1178 algorithms : [ alg_aead : int / tstr ], 1179 request_kid : bstr, 1180 request_piv : bstr, 1181 options : bstr 1182 ] 1184 where: 1186 o oscore_version: contains the OSCORE version number. 1187 Implementations of this specification MUST set this field to 1. 1188 Other values are reserved for future versions. 1190 o alg_aead: contains the AEAD Algorithm from the security context 1191 used for the exchange (see Section 3.1). 1193 o request_kid: contains the value of the 'kid' in the COSE object of 1194 the request (see Section 5). 1196 o request_piv: contains the value of the 'Partial IV' in the COSE 1197 object of the request (see Section 5). 1199 o options: contains the Class I options (see Section 4.2.2) present 1200 in the original CoAP message encoded as described in Section 3.1 1201 of [RFC7252], where the delta is the difference to the previously 1202 included class I option. 1204 NOTE: The format of the external_aad is for simplicity the same for 1205 requests and responses, although some parameters, e.g. request_kid 1206 need not be integrity protected in the requests. 1208 6. OSCORE Header Compression 1210 The Concise Binary Object Representation (CBOR) [RFC7049] combines 1211 very small message sizes with extensibility. The CBOR Object Signing 1212 and Encryption (COSE) [RFC8152] uses CBOR to create compact encoding 1213 of signed and encrypted data. COSE is however constructed to support 1214 a large number of different stateless use cases, and is not fully 1215 optimized for use as a stateful security protocol, leading to a 1216 larger than necessary message expansion. In this section, we define 1217 a stateless header compression mechanism, simply removing redundant 1218 information from the COSE objects, which significantly reduces the 1219 per-packet overhead. The result of applying this mechanism to a COSE 1220 object is called the "compressed COSE object". 1222 The COSE_Encrypt0 object used in OSCORE is transported in the Object- 1223 Security option and in the Payload. The Payload contains the 1224 Ciphertext and the headers of the COSE object are compactly encoded 1225 as described in the next section. 1227 6.1. Encoding of the Object-Security Value 1229 The value of the Object-Security option SHALL contain the OSCORE flag 1230 bits, the Partial IV parameter, the kid context parameter (length and 1231 value), and the kid parameter as follows: 1233 0 1 2 3 4 5 6 7 <--------- n bytes -------------> 1234 +-+-+-+-+-+-+-+-+--------------------------------- 1235 |0 0 0|h|k| n | Partial IV (if any) ... 1236 +-+-+-+-+-+-+-+-+--------------------------------- 1238 <- 1 byte -> <------ s bytes -----> 1239 +------------+----------------------+------------------+ 1240 | s (if any) | kid context (if any) | kid (if any) ... | 1241 +------------+----------------------+------------------+ 1243 Figure 11: Object-Security Value 1245 o The first byte of flag bits encodes the following set of flags and 1246 the length of the Partial IV parameter: 1248 * The three least significant bits encode the Partial IV length 1249 n. If n = 0 then the Partial IV is not present in the 1250 compressed COSE object. The values n = 6 and n = 7 are 1251 reserved. 1253 * The fourth least significant bit is the kid flag, k: it is set 1254 to 1 if the kid is present in the compressed COSE object. 1256 * The fifth least significant bit is the kid context flag, h: it 1257 is set to 1 if the compressed COSE object contains a kid 1258 context (see Section 5.1). 1260 * The sixth to eighth least significant bits are reserved for 1261 future use. These bits SHALL be set to zero when not in use. 1262 According to this specification, if any of these bits are set 1263 to 1 the message is considered to be malformed and 1264 decompression fails as specified in item 3 of Section 8.2. 1266 o The following n bytes encode the value of the Partial IV, if the 1267 Partial IV is present (n > 0). 1269 o The following 1 byte encode the length of the kid context 1270 (Section 5.1) s, if the kid context flag is set (h = 1). 1272 o The following s bytes encode the kid context, if the kid context 1273 flag is set (h = 1). 1275 o The remaining bytes encode the value of the kid, if the kid is 1276 present (k = 1). 1278 Note that the kid MUST be the last field of the object-security 1279 value, even in case reserved bits are used and additional fields are 1280 added to it. 1282 The length of the Object-Security option thus depends on the presence 1283 and length of Partial IV, kid context, kid, as specified in this 1284 section, and on the presence and length of the other parameters, as 1285 defined in the separate documents. 1287 6.2. Encoding of the OSCORE Payload 1289 The payload of the OSCORE message SHALL encode the ciphertext of the 1290 COSE object. 1292 6.3. Examples of Compressed COSE Objects 1294 6.3.1. Examples: Requests 1296 1. Request with kid = 25 and Partial IV = 5 1298 Before compression (24 bytes): 1300 [ 1301 h'', 1302 { 4:h'25', 6:h'05' }, 1303 h'aea0155667924dff8a24e4cb35b9' 1304 ] 1306 After compression (17 bytes): 1308 Flag byte: 0b00001001 = 0x09 1310 Option Value: 09 05 25 (3 bytes) 1312 Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) 1314 1. Request with kid = empty string and Partial IV = 0 1316 After compression (16 bytes): 1318 Flag byte: 0b00001001 = 0x09 1320 Option Value: 09 00 (2 bytes) 1322 Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) 1324 1. Request with kid = empty string, Partial IV = 5, and kid context 1325 = 0x44616c656b 1327 After compression (22 bytes): 1329 Flag byte: 0b00011001 = 0x19 1331 Option Value: 19 05 05 44 61 6c 65 6b (8 bytes) 1333 Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) 1335 6.3.2. Example: Response (without Observe) 1337 Before compression (18 bytes): 1339 [ 1340 h'', 1341 {}, 1342 h'aea0155667924dff8a24e4cb35b9' 1343 ] 1345 After compression (14 bytes): 1347 Flag byte: 0b00000000 = 0x00 1349 Option Value: (0 bytes) 1351 Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) 1353 6.3.3. Example: Response (with Observe) 1355 Before compression (21 bytes): 1357 [ 1358 h'', 1359 { 6:h'07' }, 1360 h'aea0155667924dff8a24e4cb35b9' 1361 ] 1363 After compression (16 bytes): 1365 Flag byte: 0b00000001 = 0x01 1367 Option Value: 01 07 (2 bytes) 1369 Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) 1371 7. Sequence Numbers, Replay, Message Binding, and Freshness 1373 7.1. Message Binding 1375 In order to prevent response delay and mismatch attacks 1376 [I-D.mattsson-core-coap-actuators] from on-path attackers and 1377 compromised proxies, OSCORE binds responses to the requests by 1378 including the kid and Partial IV of the request in the AAD of the 1379 response. The server therefore needs to store the kid and Partial IV 1380 of the request until all responses have been sent. 1382 7.2. AEAD Nonce Uniqueness 1384 An AEAD nonce MUST NOT be used more than once per AEAD key. In order 1385 to assure unique nonces, each Sender Context contains a Sender 1386 Sequence Number used to protect requests, and - in case of Observe - 1387 responses. If messages are processed concurrently, the operation of 1388 reading and increasing the Sender Sequence Number MUST be atomic. 1390 The maximum Sender Sequence Number is algorithm dependent (see 1391 Section 11), and no greater than 2^40 - 1. If the Sender Sequence 1392 Number exceeds the maximum, the endpoint MUST NOT process any more 1393 messages with the given Sender Context. The endpoint SHOULD acquire 1394 a new security context (and consequently inform the other endpoint) 1395 before this happens. The latter is out of scope of this document. 1397 7.3. Freshness 1399 For requests, OSCORE provides weak absolute freshness as the only 1400 guarantee is that the request is not older than the security context. 1401 For applications having stronger demands on request freshness (e.g., 1402 control of actuators), OSCORE needs to be augmented with mechanisms 1403 providing freshness, for example as specified in 1404 [I-D.ietf-core-echo-request-tag]. 1406 For responses, the message binding guarantees that a response is not 1407 older than its request. For responses without Observe, this gives 1408 strong absolute freshness. For responses with Observe, the absolute 1409 freshness gets weaker with time, and it is RECOMMENDED that the 1410 client regularly re-register the observation. 1412 For requests, and responses with Observe, OSCORE also provides 1413 relative freshness in the sense that the received Partial IV allows a 1414 recipient to determine the relative order of responses. 1416 7.4. Replay Protection 1418 In order to protect from replay of requests, the server's Recipient 1419 Context includes a Replay Window. A server SHALL verify that a 1420 Partial IV received in the COSE object has not been received before. 1421 If this verification fails the server SHALL stop processing the 1422 message, and MAY optionally respond with a 4.01 Unauthorized error 1423 message. Also, the server MAY set an Outer Max-Age option with value 1424 zero. The diagnostic payload MAY contain the "Replay protection 1425 failed" string. The size and type of the Replay Window depends on 1426 the use case and the protocol with which the OSCORE message is 1427 transported. In case of reliable and ordered transport from endpoint 1428 to endpoint, e.g. TCP, the server MAY just store the last received 1429 Partial IV and require that newly received Partial IVs equals the 1430 last received Partial IV + 1. However, in case of mixed reliable and 1431 unreliable transports and where messages may be lost, such a replay 1432 mechanism may be too restrictive and the default replay window be 1433 more suitable (see Section 3.2.2). 1435 Responses to non-Observe requests are protected against replay as 1436 they are cryptographically bound to the request. 1438 In the case of Observe, a client receiving a notification SHALL 1439 verify that the Partial IV of a received notification is greater than 1440 the Notification Number bound to that Observe registration. If the 1441 verification fails, the client SHALL stop processing the response. 1442 If the verification succeeds, the client SHALL overwrite the 1443 corresponding Notification Number with the received Partial IV. 1445 If messages are processed concurrently, the Partial IV needs to be 1446 validated a second time after decryption and before updating the 1447 replay protection data. The operation of validating the Partial IV 1448 and updating the replay protection data MUST be atomic. 1450 7.5. Losing Part of the Context State 1452 To prevent reuse of the AEAD nonce with the same key, or from 1453 accepting replayed messages, an endpoint needs to handle the 1454 situation of losing rapidly changing parts of the context, such as 1455 the request Token, Sender Sequence Number, Replay Window, and 1456 Notification Numbers. These are typically stored in RAM and 1457 therefore lost in the case of an unplanned reboot. 1459 After boot, an endpoint MAY reject to use existing security contexts 1460 from before it booted and MAY establish a new security context with 1461 each party it communicates. However, establishing a fresh security 1462 context may have a non-negligible cost in terms of, e.g., power 1463 consumption. 1465 After boot, an endpoint MAY use a partly persistently stored security 1466 context, but then the endpoint MUST NOT reuse a previous Sender 1467 Sequence Number and MUST NOT accept previously accepted messages. 1468 Some ways to achieve this is described below: 1470 7.5.1. Sequence Number 1472 To prevent reuse of Sender Sequence Numbers, an endpoint MAY perform 1473 the following procedure during normal operations: 1475 o Each time the Sender Sequence Number is evenly divisible by K, 1476 where K is a positive integer, store the Sender Sequence Number in 1477 persistent memory. After boot, the endpoint initiates the Sender 1478 Sequence Number to the value stored in persistent memory + K - 1. 1479 Storing to persistent memory can be costly. The value K gives a 1480 trade-off between the number of storage operations and efficient 1481 use of Sender Sequence Numbers. 1483 7.5.2. Replay Window 1485 To prevent accepting replay of previously received requests, the 1486 server MAY perform the following procedure after boot: 1488 o For each stored security context, the first time after boot the 1489 server receives an OSCORE request, the server responds with the 1490 Echo option [I-D.ietf-core-echo-request-tag] to get a request with 1491 verifiable freshness. The server MUST use its Partial IV when 1492 generating the AEAD nonce and MUST include the Partial IV in the 1493 response. 1495 If the server using the Echo option can verify a second request as 1496 fresh, then the Partial IV of the second request is set as the lower 1497 limit of the replay window. 1499 7.5.3. Replay Protection of Observe Notifications 1501 To prevent accepting replay of previously received notification 1502 responses, the client MAY perform the following procedure after boot: 1504 o The client rejects notifications bound to the earlier 1505 registration, removes all Notification Numbers and re-registers 1506 using Observe. 1508 8. Processing 1510 This section describes the OSCORE message processing. 1512 8.1. Protecting the Request 1514 Given a CoAP request, the client SHALL perform the following steps to 1515 create an OSCORE request: 1517 1. Retrieve the Sender Context associated with the target resource. 1519 2. Compose the Additional Authenticated Data and the plaintext, as 1520 described in Section 5.4 and Section 5.3. 1522 3. Compute the AEAD nonce from the Sender ID, Common IV, and Partial 1523 IV (Sender Sequence Number in network byte order) as described in 1524 Section 5.2 and (in one atomic operation, see Section 7.2) 1525 increment the Sender Sequence Number by one. 1527 4. Encrypt the COSE object using the Sender Key. Compress the COSE 1528 Object as specified in Section 6. 1530 5. Format the OSCORE message according to Section 4. The Object- 1531 Security option is added (see Section 4.2.2). 1533 6. Store the association Token - Security Context. The client SHALL 1534 be able to find the Recipient Context from the Token in the 1535 response. 1537 8.2. Verifying the Request 1539 A server receiving a request containing the Object-Security option 1540 SHALL perform the following steps: 1542 1. Process Outer Block options according to [RFC7959], until all 1543 blocks of the request have been received (see Section 4.2.3.2). 1545 2. Discard the message Code and all non-special Inner option 1546 message fields (marked with 'x' in column E of Figure 6) present 1547 in the received message. For example, an If-Match Outer option 1548 is discarded, but an Uri-Host Outer option is not discarded. 1550 3. Decompress the COSE Object (Section 6) and retrieve the 1551 Recipient Context associated with the Recipient ID in the 'kid' 1552 parameter. If either the decompression or the COSE message 1553 fails to decode, or the server fails to retrieve a Recipient 1554 Context with Recipient ID corresponding to the 'kid' parameter 1555 received, then the server SHALL stop processing the request. 1556 If: 1558 * either the decompression or the COSE message fails to decode, 1559 the server MAY respond with a 4.02 Bad Option error message. 1560 The server MAY set an Outer Max-Age option with value zero. 1561 The diagnostic payload SHOULD contain the string "Failed to 1562 decode COSE". 1564 * the server fails to retrieve a Recipient Context with 1565 Recipient ID corresponding to the 'kid' parameter received, 1566 the server MAY respond with a 4.01 Unauthorized error 1567 message. The server MAY set an Outer Max-Age option with 1568 value zero. The diagnostic payload SHOULD contain the string 1569 "Security context not found". 1571 4. Verify the 'Partial IV' parameter using the Replay Window, as 1572 described in Section 7.4. 1574 5. Compose the Additional Authenticated Data, as described in 1575 Section 5.4. 1577 6. Compute the AEAD nonce from the Recipient ID, Common IV, and the 1578 'Partial IV' parameter, received in the COSE Object. 1580 7. Decrypt the COSE object using the Recipient Key, as per 1581 [RFC8152] Section 5.3. (The decrypt operation includes the 1582 verification of the integrity.) 1584 * If decryption fails, the server MUST stop processing the 1585 request and MAY respond with a 4.00 Bad Request error 1586 message. The server MAY set an Outer Max-Age option with 1587 value zero. The diagnostic payload SHOULD contain the 1588 "Decryption failed" string. 1590 * If decryption succeeds, update the Replay Window, as 1591 described in Section 7. 1593 8. For each decrypted option, check if the option is also present 1594 as an Outer option: if it is, discard the Outer. For example: 1595 the message contains a Max-Age Inner and a Max-Age Outer option. 1596 The Outer Max-Age is discarded. 1598 9. Add decrypted code, options and payload to the decrypted 1599 request. The Object-Security option is removed. 1601 10. The decrypted CoAP request is processed according to [RFC7252] 1603 8.3. Protecting the Response 1605 If a CoAP response is generated in response to an OSCORE request, the 1606 server SHALL perform the following steps to create an OSCORE 1607 response. Note that CoAP error responses derived from CoAP 1608 processing (point 10. in Section 8.2) are protected, as well as 1609 successful CoAP responses, while the OSCORE errors (point 3, 4, and 7 1610 in Section 8.2) do not follow the processing below, but are sent as 1611 simple CoAP responses, without OSCORE processing. 1613 1. Retrieve the Sender Context in the Security Context used to 1614 verify the request. 1616 2. Compose the Additional Authenticated Data and the plaintext, as 1617 described in Section 5.4 and Section 5.3. 1619 3. Compute the AEAD nonce 1621 * If Observe is used, compute the nonce from the Sender ID, 1622 Common IV, and Partial IV (Sender Sequence Number in network 1623 byte order). Then (in one atomic operation, see Section 7.2) 1624 increment the Sender Sequence Number by one. 1626 * If Observe is not used, either the nonce from the request is 1627 used or a new Partial IV is used (see bullet on 'Partial IV' 1628 in Section 5). 1630 4. Encrypt the COSE object using the Sender Key. Compress the COSE 1631 Object as specified in Section 6. If the AEAD nonce was 1632 constructed from a new Partial IV, this Partial IV MUST be 1633 included in the message. If the AEAD nonce from the request was 1634 used, the Partial IV MUST NOT be included in the message. 1636 5. Format the OSCORE message according to Section 4. The Object- 1637 Security option is added (see Section 4.2.2). 1639 8.4. Verifying the Response 1641 A client receiving a response containing the Object-Security option 1642 SHALL perform the following steps: 1644 1. Process Outer Block options according to [RFC7959], until all 1645 blocks of the OSCORE message have been received (see 1646 Section 4.2.3.2). 1648 2. Discard the message Code and all non-special Class E options 1649 from the message. For example, ETag Outer option is discarded, 1650 Max-Age Outer option is not discarded. 1652 3. Retrieve the Recipient Context associated with the Token. 1653 Decompress the COSE Object (Section 6). If either the 1654 decompression or the COSE message fails to decode, then go to 1655 11. 1657 4. For Observe notifications, verify the received 'Partial IV' 1658 parameter against the corresponding Notification Number as 1659 described in Section 7.4. If the client receives a notification 1660 for which no Observe request was sent, then go to 11. 1662 5. Compose the Additional Authenticated Data, as described in 1663 Section 5.4. 1665 6. Compute the AEAD nonce 1667 1. If the Observe option and the Partial IV are not present in 1668 the response, the nonce from the request is used. 1670 2. If the Observe option is present in the response, and the 1671 Partial IV is not present in the response, then go to 11. 1673 3. If the Partial IV is present in the response, compute the 1674 nonce from the Recipient ID, Common IV, and the 'Partial IV' 1675 parameter, received in the COSE Object. 1677 7. Decrypt the COSE object using the Recipient Key, as per 1678 [RFC8152] Section 5.3. (The decrypt operation includes the 1679 verification of the integrity.) 1681 * If decryption fails, then go to 11. 1683 * If decryption succeeds and Observe is used, update the 1684 corresponding Notification Number, as described in Section 7. 1686 8. For each decrypted option, check if the option is also present 1687 as an Outer option: if it is, discard the Outer. For example: 1688 the message contains a Max-Age Inner and a Max-Age Outer option. 1689 The Outer Max-Age is discarded. 1691 9. Add decrypted code, options and payload to the decrypted 1692 request. The Object-Security option is removed. 1694 10. The decrypted CoAP response is processed according to [RFC7252] 1696 11. (Optional) In case any of the previous erroneous conditions 1697 apply: the client SHALL stop processing the response. 1699 An error condition occurring while processing a response in an 1700 observation does not cancel the observation. A client MUST NOT react 1701 to failure in step 7 by re-registering the observation immediately. 1703 9. Web Linking 1705 The use of OSCORE MAY be indicated by a target attribute "osc" in a 1706 web link [RFC8288] to a resource. This attribute is a hint 1707 indicating that the destination of that link is to be accessed using 1708 OSCORE. Note that this is simply a hint, it does not include any 1709 security context material or any other information required to run 1710 OSCORE. 1712 A value MUST NOT be given for the "osc" attribute; any present value 1713 MUST be ignored by parsers. The "osc" attribute MUST NOT appear more 1714 than once in a given link-value; occurrences after the first MUST be 1715 ignored by parsers. 1717 10. Proxy and HTTP Operations 1719 RFC 7252 defines operations for a CoAP-to-CoAP proxy (see Section 5.7 1720 of [RFC7252]) and for proxying between CoAP and HTTP (Section 10 of 1721 [RFC7252]). A more detailed description of the HTTP-to-CoAP mapping 1722 is provided by [RFC8075]. This section describes the operations of 1723 OSCORE-aware proxies. 1725 10.1. CoAP-to-CoAP Forwarding Proxy 1727 OSCORE is designed to work with legacy CoAP-to-CoAP forward proxies 1728 [RFC7252], but OSCORE-aware proxies MAY provide certain 1729 simplifications as specified in this section. 1731 Security requirements for forwarding are presented in Section 2.2.1 1732 of [I-D.hartke-core-e2e-security-reqs]. OSCORE complies with the 1733 extended security requirements also addressing Blockwise ([RFC7959]) 1734 and CoAP-mappable HTTP. In particular caching is disabled since the 1735 CoAP response is only applicable to the original CoAP request. An 1736 OSCORE-aware proxy SHALL NOT cache a response to a request with an 1737 Object-Security option. As a consequence, the search for cache hits 1738 and CoAP freshness/Max-Age processing can be omitted. 1740 Proxy processing of the (Outer) Proxy-Uri option is as defined in 1741 [RFC7252]. 1743 Proxy processing of the (Outer) Block options is as defined in 1744 [RFC7959]. 1746 Proxy processing of the (Outer) Observe option is as defined in 1747 [RFC7641]. OSCORE-aware proxies MAY look at the Partial IV value 1748 instead of the Outer Observe option. 1750 10.2. HTTP Processing 1752 In order to use OSCORE with HTTP, an endpoint needs to be able to map 1753 HTTP messages to CoAP messages (see [RFC8075]), and to apply OSCORE 1754 to CoAP messages (as defined in this document). 1756 For this purpose, this specification defines a new HTTP header field 1757 named CoAP-Object-Security, see Section 12.4. The CoAP-Object- 1758 Security header field is only used in POST requests and 200 (OK) 1759 responses. All field semantics is given within the CoAP-Object- 1760 Security header field. The header field is neither appropriate to 1761 list in the Connection header field (see Section 6.1 of [RFC7230]), 1762 nor in a Vary response header field (see Section 7.1.4 of [RFC7231]), 1763 nor allowed in trailers (see Section 4.1 of [RFC7230]). 1765 Intermediaries are not allowed to insert, delete, or modify the 1766 field's value. The header field is not preserved across redirects. 1768 A sending endpoint uses [RFC8075] to translate an HTTP message into a 1769 CoAP message. It then protects the message with OSCORE processing, 1770 and add the Object-Security option (as defined in this document). 1771 Then, the endpoint maps the resulting CoAP message to an HTTP message 1772 that includes the HTTP header field CoAP-Object-Security, whose value 1773 is: 1775 o "" (empty string) if the CoAP Object-Security option is empty, or 1777 o the value of the CoAP Object-Security option (Section 6.1) in 1778 base64url encoding (Section 5 of [RFC4648]) without padding (see 1779 [RFC7515] Appendix C for implementation notes for this encoding). 1781 Note that the value of the HTTP body is the CoAP payload, i.e. the 1782 OSCORE payload (Section 6.2). 1784 The HTTP header field Content-Type is set to 'application/oscore' 1785 (see Section 12.5). 1787 The resulting message is an OSCORE message that uses HTTP. 1789 A receiving endpoint uses [RFC8075] to translate an HTTP message into 1790 a CoAP message, with the following addition. The HTTP message 1791 includes the CoAP-Object-Security header field, which is mapped to 1792 the CoAP Object-Security option in the following way. The CoAP 1793 Object-Security option value is: 1795 o empty if the value of the HTTP CoAP-Object-Security header field 1796 is "" (empty string) 1798 o the value of the HTTP CoAP-Object-Security header field decoded 1799 from base64url (Section 5 of [RFC4648]) without padding (see 1800 [RFC7515] Appendix C for implementation notes for this decoding). 1802 Note that the value of the CoAP payload is the HTTP body, i.e. the 1803 OSCORE payload (Section 6.2). 1805 The resulting message is an OSCORE message that uses CoAP. 1807 The endpoint can then verify the message according to the OSCORE 1808 processing and get a verified CoAP message. It can then translate 1809 the verified CoAP message into a verified HTTP message. 1811 10.3. HTTP-to-CoAP Translation Proxy 1813 Section 10.2 of [RFC7252] and [RFC8075] specify the behavior of an 1814 HTTP-to-CoAP proxy. As requested in Section 1 of [RFC8075], this 1815 section describes the HTTP mapping for the OSCORE protocol extension 1816 of CoAP. 1818 The presence of the Object-Security option, both in requests and 1819 responses, is expressed in an HTTP header field named CoAP-Object- 1820 Security in the mapped request or response. The value of the field 1821 is: 1823 o "" (empty string) if the CoAP Object-Security option is empty, or 1825 o the value of the CoAP Object-Security option (Section 6.1) in 1826 base64url encoding (Section 5 of [RFC4648]) without padding (see 1827 [RFC7515] Appendix C for implementation notes for this encoding). 1829 The header field Content-Type 'application/oscore' (see Section 12.5) 1830 is used for OSCORE messages transported in HTTP. The CoAP Content- 1831 Format option is omitted for OSCORE messages transported in CoAP. 1833 The value of the body is the OSCORE payload (Section 6.2). 1835 Example: 1837 Mapping and notation here is based on "Simple Form" (Section 5.4.1.1 1838 of [RFC8075]). 1840 [HTTP request -- Before client object security processing] 1842 GET http://proxy.url/hc/?target_uri=coap://server.url/orders HTTP/1.1 1844 [HTTP request -- HTTP Client to Proxy] 1846 POST http://proxy.url/hc/?target_uri=coap://server.url/ HTTP/1.1 1847 Content-Type: application/oscore 1848 CoAP-Object-Security: 09 25 1849 Body: 09 07 01 13 61 f7 0f d2 97 b1 [binary] 1851 [CoAP request -- Proxy to CoAP Server] 1853 POST coap://server.url/ 1854 Object-Security: 09 25 1855 Payload: 09 07 01 13 61 f7 0f d2 97 b1 [binary] 1857 [CoAP request -- After server object security processing] 1859 GET coap://server.url/orders 1861 [CoAP response -- Before server object security processing] 1863 2.05 Content 1864 Content-Format: 0 1865 Payload: Exterminate! Exterminate! 1867 [CoAP response -- CoAP Server to Proxy] 1869 2.04 Changed 1870 Object-Security: [empty] 1871 Payload: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] 1873 [HTTP response -- Proxy to HTTP Client] 1875 HTTP/1.1 200 OK 1876 Content-Type: application/oscore 1877 CoAP-Object-Security: "" (empty string) 1878 Body: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] 1880 [HTTP response -- After client object security processing] 1882 HTTP/1.1 200 OK 1883 Content-Type: text/plain 1884 Body: Exterminate! Exterminate! 1886 Note that the HTTP Status Code 200 in the next-to-last message is the 1887 mapping of CoAP Code 2.04 (Changed), whereas the HTTP Status Code 200 1888 in the last message is the mapping of the CoAP Code 2.05 (Content), 1889 which was encrypted within the compressed COSE object carried in the 1890 Body of the HTTP response. 1892 10.4. CoAP-to-HTTP Translation Proxy 1894 Section 10.1 of [RFC7252] describes the behavior of a CoAP-to-HTTP 1895 proxy. RFC 8075 [RFC8075] does not cover this direction in any more 1896 detail and so an example instantiation of Section 10.1 of [RFC7252] 1897 is used below. 1899 Example: 1901 [CoAP request -- Before client object security processing] 1903 GET coap://proxy.url/ 1904 Proxy-Uri=http://server.url/orders 1906 [CoAP request -- CoAP Client to Proxy] 1908 POST coap://proxy.url/ 1909 Proxy-Uri=http://server.url/ 1910 Object-Security: 09 25 1911 Payload: 09 07 01 13 61 f7 0f d2 97 b1 [binary] 1913 [HTTP request -- Proxy to HTTP Server] 1915 POST http://server.url/ HTTP/1.1 1916 Content-Type: application/oscore 1917 CoAP-Object-Security: 09 25 1918 Body: 09 07 01 13 61 f7 0f d2 97 b1 [binary] 1920 [HTTP request -- After server object security processing] 1922 GET http://server.url/orders HTTP/1.1 1924 [HTTP response -- Before server object security processing] 1926 HTTP/1.1 200 OK 1927 Content-Type: text/plain 1928 Body: Exterminate! Exterminate! 1930 [HTTP response -- HTTP Server to Proxy] 1932 HTTP/1.1 200 OK 1933 Content-Type: application/oscore 1934 CoAP-Object-Security: "" (empty string) 1935 Body: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] 1937 [CoAP response - Proxy to CoAP Client] 1939 2.04 Changed 1940 Object-Security: [empty] 1941 Payload: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] 1943 [CoAP response -- After client object security processing] 1945 2.05 Content 1946 Content-Format: 0 1947 Payload: Exterminate! Exterminate! 1949 Note that the HTTP Code 2.04 (Changed) in the next-to-last message is 1950 the mapping of HTTP Status Code 200, whereas the CoAP Code 2.05 1951 (Content) in the last message is the value that was encrypted within 1952 the compressed COSE object carried in the Body of the HTTP response. 1954 11. Security Considerations 1956 11.1. End-to-end protection 1958 In scenarios with intermediary nodes such as proxies or gateways, 1959 transport layer security such as (D)TLS only protects data hop-by- 1960 hop. As a consequence, the intermediary nodes can read and modify 1961 information. The trust model where all intermediary nodes are 1962 considered trustworthy is problematic, not only from a privacy 1963 perspective, but also from a security perspective, as the 1964 intermediaries are free to delete resources on sensors and falsify 1965 commands to actuators (such as "unlock door", "start fire alarm", 1966 "raise bridge"). Even in the rare cases, where all the owners of the 1967 intermediary nodes are fully trusted, attacks and data breaches make 1968 such an architecture brittle. 1970 (D)TLS protects hop-by-hop the entire message. OSCORE protects end- 1971 to-end all information that is not required for proxy operations (see 1972 Section 4). (D)TLS and OSCORE can be combined, thereby enabling end- 1973 to-end security of the message payload, in combination with hop-by- 1974 hop protection of the entire message, during transport between end- 1975 point and intermediary node. The CoAP messaging layer, including 1976 header fields such as Type and Message ID, as well as CoAP message 1977 fields Token and Token Length may be changed by a proxy and thus 1978 cannot be protected end-to-end. Error messages occurring during CoAP 1979 processing are protected end-to-end. Error messages occurring during 1980 OSCORE processing are not always possible to protect, e.g. if the 1981 receiving endpoint cannot locate the right security context. It may 1982 still be favorable to send an unprotected error message, e.g. to 1983 prevent extensive retransmissions, so unprotected error messages are 1984 allowed as specified. Similar to error messages, signaling messages 1985 are not always possible to protect as they may be intended for an 1986 intermediary. Hop-by-hop protection of signaling messages can be 1987 achieved with (D)TLS. Applications using unprotected error and 1988 signaling messages need to consider the threat that these messages 1989 may be spoofed. 1991 11.2. Security Context Establishment 1993 The use of COSE to protect messages as specified in this document 1994 requires an established security context. The method to establish 1995 the security context described in Section 3.2 is based on a common 1996 shared secret material in client and server, which may be obtained, 1997 e.g., by using the ACE framework [I-D.ietf-ace-oauth-authz]. An 1998 OSCORE profile of ACE is described in [I-D.ietf-ace-oscore-profile]. 2000 11.3. Replay Protection 2002 Most AEAD algorithms require a unique nonce for each message, for 2003 which the sender sequence numbers in the COSE message field 'Partial 2004 IV' is used. If the recipient accepts any sequence number larger 2005 than the one previously received, then the problem of sequence number 2006 synchronization is avoided. With reliable transport, it may be 2007 defined that only messages with sequence number which are equal to 2008 previous sequence number + 1 are accepted. The alternatives to 2009 sequence numbers have their issues: very constrained devices may not 2010 be able to support accurate time, or to generate and store large 2011 numbers of random nonces. The requirement to change key at counter 2012 wrap is a complication, but it also forces the user of this 2013 specification to think about implementing key renewal. 2015 11.4. Cryptographic Considerations 2017 The maximum sender sequence number is dependent on the AEAD 2018 algorithm. The maximum sender sequence number SHALL be 2^40 - 1, or 2019 any algorithm specific lower limit, after which a new security 2020 context must be generated. The mechanism to build the nonce 2021 (Section 5.2) assumes that the nonce is at least 56 bit-long, and the 2022 Partial IV is at most 40 bit-long. The mandatory-to-implement AEAD 2023 algorithm AES-CCM-16-64-128 is selected for compatibility with CCM*. 2025 The security level of a system with m Masters Keys of length k used 2026 together with Master Salts with entropy n is k + n - log2(m). 2027 Similarly, the security level of a system with m AEAD keys of length 2028 k used together with AEAD nonces of length n is k + n - log2(m). 2029 Security level here means that an attacker can recover one of the m 2030 keys with complexity 2^(k + n) / m. Protection against such attacks 2031 can be provided by increasing the size of the keys or the entropy of 2032 the Master Salt. The complexity of recovering a specific key is 2033 still 2^k (assuming the Master Salt/AEAD nonce is public). The 2034 Master Secret, Sender Key, and Recipient Key MUST be secret, the rest 2035 of the parameters MAY be public. The Master Secret MUST be uniformly 2036 random. 2038 11.5. Message Fragmentation 2040 The Inner Block options enable the sender to split large messages 2041 into OSCORE-protected blocks such that the receiving endpoint can 2042 verify blocks before having received the complete message. The Outer 2043 Block options allow for arbitrary proxy fragmentation operations that 2044 cannot be verified by the endpoints, but can by policy be restricted 2045 in size since the Inner Block options allow for secure fragmentation 2046 of very large messages. A maximum message size (above which the 2047 sending endpoint fragments the message and the receiving endpoint 2048 discards the message, if complying to the policy) may be obtained as 2049 part of normal resource discovery. 2051 11.6. Privacy Considerations 2053 Privacy threats executed through intermediary nodes are considerably 2054 reduced by means of OSCORE. End-to-end integrity protection and 2055 encryption of the message payload and all options that are not used 2056 for proxy operations, provide mitigation against attacks on sensor 2057 and actuator communication, which may have a direct impact on the 2058 personal sphere. 2060 The unprotected options (Figure 6) may reveal privacy sensitive 2061 information. In particular Uri-Host SHOULD NOT contain privacy 2062 sensitive information. CoAP headers sent in plaintext allow, for 2063 example, matching of CON and ACK (CoAP Message Identifier), matching 2064 of request and responses (Token) and traffic analysis. OSCORE does 2065 not provide protection for HTTP header fields which are not CoAP- 2066 mappable. 2068 Unprotected error messages reveal information about the security 2069 state in the communication between the endpoints. Unprotected 2070 signalling messages reveal information about the reliable transport 2071 used on a leg of the path. Using the mechanisms described in 2072 Section 7.5 may reveal when a device goes through a reboot. This can 2073 be mitigated by the device storing the precise state of sender 2074 sequence number and replay window on a clean shutdown. 2076 The length of message fields can reveal information about the 2077 message. Applications may use a padding scheme to protect against 2078 traffic analysis. As an example, the strings "YES" and "NO" even if 2079 encrypted can be distinguished from each other as there is no padding 2080 supplied by the current set of encryption algorithms. Some 2081 information can be determined even from looking at boundary 2082 conditions. An example of this would be returning an integer between 2083 0 and 100 where lengths of 1, 2 and 3 will provide information about 2084 where in the range things are. Three different methods to deal with 2085 this are: 1) ensure that all messages are the same length. For 2086 example, using 0 and 1 instead of "yes" and "no". 2) Use a character 2087 which is not part of the responses to pad to a fixed length. For 2088 example, pad with a space to three characters. 3) Use the PKCS #7 2089 style padding scheme where m bytes are appended each having the value 2090 of m. For example, appending a 0 to "YES" and two 1's to "NO". This 2091 style of padding means that all values need to be padded. Similar 2092 arguments apply to other message fields such as resource names. 2094 12. IANA Considerations 2096 Note to RFC Editor: Please replace all occurrences of "[[this 2097 document]]" with the RFC number of this specification. 2099 Note to IANA: Please note all occurrences of "TBD" in this 2100 specification should be assigned the same number. 2102 12.1. COSE Header Parameters Registry 2104 The 'kid context' parameter is added to the "COSE Header Parameters 2105 Registry": 2107 o Name: kid context 2109 o Label: kidctx 2111 o Value Type: bstr 2113 o Value Registry: 2115 o Description: kid context 2117 o Reference: Section 5.1 of this document 2119 12.2. CoAP Option Numbers Registry 2121 The Object-Security option is added to the CoAP Option Numbers 2122 registry: 2124 +--------+-----------------+-------------------+ 2125 | Number | Name | Reference | 2126 +--------+-----------------+-------------------+ 2127 | TBD | Object-Security | [[this document]] | 2128 +--------+-----------------+-------------------+ 2130 12.3. CoAP Signaling Option Numbers Registry 2132 The Object-Security option is added to the CoAP Signaling Option 2133 Numbers registry: 2135 +------------+--------+---------------------+-------------------+ 2136 | Applies to | Number | Name | Reference | 2137 +------------+--------+---------------------+-------------------+ 2138 | 7.xx | TBD | Object-Security | [[this document]] | 2139 +------------+--------+---------------------+-------------------+ 2141 12.4. Header Field Registrations 2143 The HTTP header field CoAP-Object-Security is added to the Message 2144 Headers registry: 2146 +----------------------+----------+----------+-------------------+ 2147 | Header Field Name | Protocol | Status | Reference | 2148 +----------------------+----------+----------+-------------------+ 2149 | CoAP-Object-Security | http | standard | [[this document]] | 2150 +----------------------+----------+----------+-------------------+ 2152 12.5. Media Type Registrations 2154 This section registers the 'application/oscore' media type in the 2155 "Media Types" registry. 2156 These media types are used to indicate that the content is an OSCORE 2157 message. 2159 Type name: application 2161 Subtype name: oscore 2163 Required parameters: N/A 2165 Optional parameters: N/A 2167 Encoding considerations: binary 2169 Security considerations: See the Security Considerations section 2170 of [[This document]]. 2172 Interoperability considerations: N/A 2174 Published specification: [[This document]] 2176 Applications that use this media type: IoT applications sending 2177 security content over HTTP(S) transports. 2179 Fragment identifier considerations: N/A 2181 Additional information: 2183 * Deprecated alias names for this type: N/A 2185 * Magic number(s): N/A 2187 * File extension(s): N/A 2189 * Macintosh file type code(s): N/A 2191 Person & email address to contact for further information: 2192 iesg@ietf.org 2194 Intended usage: COMMON 2196 Restrictions on usage: N/A 2198 Author: Goeran Selander, goran.selander@ericsson.com 2200 Change Controller: IESG 2202 Provisional registration? No 2204 13. References 2206 13.1. Normative References 2208 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2209 Requirement Levels", BCP 14, RFC 2119, 2210 DOI 10.17487/RFC2119, March 1997, 2211 . 2213 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 2214 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 2215 . 2217 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 2218 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 2219 January 2012, . 2221 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 2222 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 2223 October 2013, . 2225 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 2226 Protocol (HTTP/1.1): Message Syntax and Routing", 2227 RFC 7230, DOI 10.17487/RFC7230, June 2014, 2228 . 2230 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 2231 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 2232 DOI 10.17487/RFC7231, June 2014, 2233 . 2235 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 2236 Application Protocol (CoAP)", RFC 7252, 2237 DOI 10.17487/RFC7252, June 2014, 2238 . 2240 [RFC7641] Hartke, K., "Observing Resources in the Constrained 2241 Application Protocol (CoAP)", RFC 7641, 2242 DOI 10.17487/RFC7641, September 2015, 2243 . 2245 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 2246 the Constrained Application Protocol (CoAP)", RFC 7959, 2247 DOI 10.17487/RFC7959, August 2016, 2248 . 2250 [RFC8075] Castellani, A., Loreto, S., Rahman, A., Fossati, T., and 2251 E. Dijk, "Guidelines for Mapping Implementations: HTTP to 2252 the Constrained Application Protocol (CoAP)", RFC 8075, 2253 DOI 10.17487/RFC8075, February 2017, 2254 . 2256 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 2257 FETCH Methods for the Constrained Application Protocol 2258 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 2259 . 2261 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 2262 RFC 8152, DOI 10.17487/RFC8152, July 2017, 2263 . 2265 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 2266 DOI 10.17487/RFC8288, October 2017, 2267 . 2269 [RFC8323] Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 2270 Silverajan, B., and B. Raymor, Ed., "CoAP (Constrained 2271 Application Protocol) over TCP, TLS, and WebSockets", 2272 RFC 8323, DOI 10.17487/RFC8323, February 2018, 2273 . 2275 13.2. Informative References 2277 [I-D.bormann-6lo-coap-802-15-ie] 2278 Bormann, C., "Constrained Application Protocol (CoAP) over 2279 IEEE 802.15.4 Information Element for IETF", draft- 2280 bormann-6lo-coap-802-15-ie-00 (work in progress), April 2281 2016. 2283 [I-D.hartke-core-e2e-security-reqs] 2284 Selander, G., Palombini, F., and K. Hartke, "Requirements 2285 for CoAP End-To-End Security", draft-hartke-core-e2e- 2286 security-reqs-03 (work in progress), July 2017. 2288 [I-D.ietf-6tisch-minimal-security] 2289 Vucinic, M., Simon, J., Pister, K., and M. Richardson, 2290 "Minimal Security Framework for 6TiSCH", draft-ietf- 2291 6tisch-minimal-security-04 (work in progress), October 2292 2017. 2294 [I-D.ietf-ace-oauth-authz] 2295 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 2296 H. Tschofenig, "Authentication and Authorization for 2297 Constrained Environments (ACE)", draft-ietf-ace-oauth- 2298 authz-10 (work in progress), February 2018. 2300 [I-D.ietf-ace-oscore-profile] 2301 Seitz, L., Palombini, F., and M. Gunnarsson, "OSCORE 2302 profile of the Authentication and Authorization for 2303 Constrained Environments Framework", draft-ietf-ace- 2304 oscore-profile-00 (work in progress), December 2017. 2306 [I-D.ietf-cbor-cddl] 2307 Birkholz, H., Vigano, C., and C. Bormann, "Concise data 2308 definition language (CDDL): a notational convention to 2309 express CBOR data structures", draft-ietf-cbor-cddl-02 2310 (work in progress), February 2018. 2312 [I-D.ietf-core-echo-request-tag] 2313 Amsuess, C., Mattsson, J., and G. Selander, "Echo and 2314 Request-Tag", draft-ietf-core-echo-request-tag-00 (work in 2315 progress), October 2017. 2317 [I-D.mattsson-ace-tls-oscore] 2318 Mattsson, J., "Using Transport Layer Security (TLS) to 2319 Secure OSCORE", draft-mattsson-ace-tls-oscore-00 (work in 2320 progress), October 2017. 2322 [I-D.mattsson-core-coap-actuators] 2323 Mattsson, J., Fornehed, J., Selander, G., Palombini, F., 2324 and C. Amsuess, "Controlling Actuators with CoAP", draft- 2325 mattsson-core-coap-actuators-03 (work in progress), 2326 October 2017. 2328 [I-D.selander-ace-cose-ecdhe] 2329 Selander, G., Mattsson, J., and F. Palombini, "Ephemeral 2330 Diffie-Hellman Over COSE (EDHOC)", draft-selander-ace- 2331 cose-ecdhe-07 (work in progress), July 2017. 2333 [I-D.tiloca-core-multicast-oscoap] 2334 Tiloca, M., Selander, G., Palombini, F., and J. Park, 2335 "Secure group communication for CoAP", draft-tiloca-core- 2336 multicast-oscoap-04 (work in progress), October 2017. 2338 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2339 Resource Identifier (URI): Generic Syntax", STD 66, 2340 RFC 3986, DOI 10.17487/RFC3986, January 2005, 2341 . 2343 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 2344 Encryption", RFC 5116, DOI 10.17487/RFC5116, January 2008, 2345 . 2347 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 2348 Key Derivation Function (HKDF)", RFC 5869, 2349 DOI 10.17487/RFC5869, May 2010, 2350 . 2352 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 2353 Constrained-Node Networks", RFC 7228, 2354 DOI 10.17487/RFC7228, May 2014, 2355 . 2357 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 2358 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 2359 2015, . 2361 [RFC7967] Bhattacharyya, A., Bandyopadhyay, S., Pal, A., and T. 2362 Bose, "Constrained Application Protocol (CoAP) Option for 2363 No Server Response", RFC 7967, DOI 10.17487/RFC7967, 2364 August 2016, . 2366 Appendix A. Scenario examples 2368 This section gives examples of OSCORE, targeting scenarios in 2369 Section 2.2.1.1 of [I-D.hartke-core-e2e-security-reqs]. The message 2370 exchanges are made, based on the assumption that there is a security 2371 context established between client and server. For simplicity, these 2372 examples only indicate the content of the messages without going into 2373 detail of the (compressed) COSE message format. 2375 A.1. Secure Access to Sensor 2377 This example illustrates a client requesting the alarm status from a 2378 server. 2380 Client Proxy Server 2381 | | | 2382 +------>| | Code: 0.02 (POST) 2383 | POST | | Token: 0x8c 2384 | | | Object-Security: [kid:5f,Partial IV:42] 2385 | | | Payload: {Code:0.01, 2386 | | | Uri-Path:"alarm_status"} 2387 | | | 2388 | +------>| Code: 0.02 (POST) 2389 | | POST | Token: 0x7b 2390 | | | Object-Security: [kid:5f,Partial IV:42] 2391 | | | Payload: {Code:0.01, 2392 | | | Uri-Path:"alarm_status"} 2393 | | | 2394 | |<------+ Code: 2.04 (Changed) 2395 | | 2.04 | Token: 0x7b 2396 | | | Object-Security: - 2397 | | | Payload: {Code:2.05, "OFF"} 2398 | | | 2399 |<------+ | Code: 2.04 (Changed) 2400 | 2.04 | | Token: 0x8c 2401 | | | Object-Security: - 2402 | | | Payload: {Code:2.05, "OFF"} 2403 | | | 2405 Figure 12: Secure Access to Sensor. Square brackets [ ... ] indicate 2406 content of compressed COSE object. Curly brackets { ... } indicate 2407 encrypted data. 2409 The request/response Codes are encrypted by OSCORE and only dummy 2410 Codes (POST/Changed) are visible in the header of the OSCORE message. 2411 The option Uri-Path ("alarm_status") and payload ("OFF") are 2412 encrypted. 2414 The COSE header of the request contains an identifier (5f), 2415 indicating which security context was used to protect the message and 2416 a Partial IV (42). 2418 The server verifies that the Partial IV has not been received before. 2419 The client verifies that the response is bound to the request. 2421 A.2. Secure Subscribe to Sensor 2423 This example illustrates a client requesting subscription to a blood 2424 sugar measurement resource (GET /glucose), first receiving the value 2425 220 mg/dl and then a second value 180 mg/dl. 2427 Client Proxy Server 2428 | | | 2429 +------>| | Code: 0.05 (FETCH) 2430 | FETCH | | Token: 0x83 2431 | | | Observe: 0 2432 | | | Object-Security: [kid:ca,Partial IV:15] 2433 | | | Payload: {Code:0.01, 2434 | | | Uri-Path:"glucose"} 2435 | | | 2436 | +------>| Code: 0.05 (FETCH) 2437 | | FETCH | Token: 0xbe 2438 | | | Observe: 0 2439 | | | Object-Security: [kid:ca,Partial IV:15] 2440 | | | Payload: {Code:0.01, 2441 | | | Uri-Path:"glucose"} 2442 | | | 2443 | |<------+ Code: 2.04 (Changed) 2444 | | 2.04 | Token: 0xbe 2445 | | | Observe: 7 2446 | | | Object-Security: [Partial IV:32] 2447 | | | Payload: {Code:2.05, 2448 | | | Content-Format:0, "220"} 2449 | | | 2450 |<------+ | Code: 2.04 (Changed) 2451 | 2.04 | | Token: 0x83 2452 | | | Observe: 7 2453 | | | Object-Security: [Partial IV:32] 2454 | | | Payload: {Code:2.05, 2455 | | | Content-Format:0, "220"} 2456 ... ... ... 2457 | | | 2458 | |<------+ Code: 2.04 (Changed) 2459 | | 2.04 | Token: 0xbe 2460 | | | Observe: 8 2461 | | | Object-Security: [Partial IV:36] 2462 | | | Payload: {Code:2.05, 2463 | | | Content-Format:0, "180"} 2464 | | | 2465 |<------+ | Code: 2.04 (Changed) 2466 | 2.04 | | Token: 0x83 2467 | | | Observe: 8 2468 | | | Object-Security: [Partial IV:36] 2469 | | | Payload: {Code:2.05, 2470 | | | Content-Format:0, "180"} 2471 | | | 2473 Figure 13: Secure Subscribe to Sensor. Square brackets [ ... ] 2474 indicate content of compressed COSE object header. Curly brackets { 2475 ... } indicate encrypted data. 2477 The request/response Codes are encrypted by OSCORE and only dummy 2478 Codes (FETCH/Changed) are visible in the header of the OSCORE 2479 message. The options Content-Format (0) and the payload ("220" and 2480 "180"), are encrypted. 2482 The COSE header of the request contains an identifier (ca), 2483 indicating the security context used to protect the message and a 2484 Partial IV (15). The COSE headers of the responses contains Partial 2485 IVs (32 and 36). 2487 The server verifies that the Partial IV has not been received before. 2488 The client verifies that the responses are bound to the request and 2489 that the Partial IVs are greater than any Partial IV previously 2490 received in a response bound to the request. 2492 Appendix B. Deployment examples 2494 OSCORE may be deployed in a variety of settings, a few examples are 2495 given in this section. 2497 B.1. Master Secret Used Once 2499 For settings where the Master Secret is only used during deployment, 2500 the uniqueness of AEAD nonce may be assured by persistent storage of 2501 the security context as described in this specification (see 2502 Section 7.5). For many IoT deployments, a 128 bit uniformly random 2503 Master Key is sufficient for encrypting all data exchanged with the 2504 IoT device throughout its lifetime. 2506 B.2. Master Secret Used Multiple Times 2508 In cases where the Master Secret needs to be used to derive multiple 2509 security contexts, e.g. due to recommissioning or where the security 2510 context is not persistently stored, a stochastically unique Master 2511 Salt prevents the reuse of AEAD nonce and key. The Master Salt may 2512 be transported between client and server in the kid context parameter 2513 (see Section 5.1) of the request. 2515 In this section we give an example of a procedure which may be 2516 implemented in client and server to establish the OSCORE security 2517 context based on pre-established input parameters (see Section 3.2) 2518 except for the Master Salt which is transported in kid context. 2520 1. In order to establish a security context with a server for the 2521 first time, or a new security context replacing an old security 2522 context, the client generates a (pseudo-)random uniformly 2523 distributed 64-bit Master Salt and derives the security context 2524 as specified in Section 3.2. The client protects a request with 2525 the new Sender Context and sends the message with kid context set 2526 to the Master Salt. 2528 2. The server, receiving an OSCORE request with a non-empty kid 2529 context derives the new security context using the received kid 2530 context as Master Salt. The server processes the request as 2531 specified in this document using the new Recipient Context. If 2532 the processing of the request completes without error, the server 2533 responds with an Echo option as specified in 2534 [I-D.ietf-core-echo-request-tag]. The response is protected with 2535 the new Sender Context. 2537 3. The client, receiving a response with an Echo option to a request 2538 which used a new security context, verifies the response using 2539 the new Recipient Context, and if valid repeats the request with 2540 the Echo option (see [I-D.ietf-core-echo-request-tag]) using the 2541 new Sender Context. Subsequent message exchanges (unless 2542 superseded) are processed using the new security context without 2543 including the Master Salt in the kid context. 2545 4. The server, receiving a request with a kid context and a valid 2546 Echo option (see [I-D.ietf-core-echo-request-tag]), repeats the 2547 processing described in step 2. If it completes without error, 2548 then the new security context is established, and the request is 2549 valid. If the server already had an old security context with 2550 this client that is now replaced by the new security context. 2552 If the server receives a request without kid context from a client 2553 with which no security context is established, then the server 2554 responds with a 4.01 Unauthorized error message with diagnostic 2555 payload containing the string "Security context not found". This 2556 could be the result of the server having lost its security context or 2557 that a new security context has not been successfully established, 2558 which may be a trigger for the client to run this procedure. 2560 B.3. Client Aliveness 2562 The use of a single OSCORE request and response enables the client to 2563 verify that the server's identity and aliveness through actual 2564 communications. While a verified OSCORE request enables the server 2565 to verify the identity of the entity who generated the message, it 2566 does not verify that the client is currently involved in the 2567 communication, since the message may be a delayed delivery of a 2568 previously generated request which now reaches the server. To verify 2569 the aliveness of the client the server may initiate an OSCORE 2570 protected message exchange with the client, e.g. by switching the 2571 roles of client and server as described in Section 3.1, or by using 2572 the Echo option in the response to a request from the client 2573 [I-D.ietf-core-echo-request-tag]. 2575 Appendix C. Test Vectors 2577 This appendix includes the test vectors for different examples of 2578 CoAP messages using OSCORE. 2580 C.1. Test Vector 1: Key Derivation with Master Salt 2582 Given a set of inputs, OSCORE defines how to set up the Security 2583 Context in both the client and the server. The default values are 2584 used for AEAD Algorithm and KDF. 2586 C.1.1. Client 2588 Inputs: 2590 o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes) 2592 o Master Salt: 0x9e7ca92223786340 (8 bytes) 2594 o Sender ID: 0x (0 byte) 2596 o Recipient ID: 0x01 (1 byte) 2598 From the previous parameters, 2600 o info (for Sender Key): 0x84400A634b657910 (8 bytes) 2602 o info (for Recipient Key): 0x8441010A634b657910 (9 bytes) 2604 o info (for Common IV): 0x84400a6249560d (7 bytes) 2606 Outputs: 2608 o Sender Key: 0x7230aab3b549d94c9224aacc744e93ab (16 bytes) 2610 o Recipient Key: 0xe534a26a64aa3982e988e31f1e401e65 (16 bytes) 2612 o Common IV: 0x01727733ab49ead385b18f7d91 (13 bytes) 2614 C.1.2. Server 2616 Inputs: 2618 o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes) 2619 o Master Salt: 0x9e7ca92223786340 (64 bytes) 2621 o Sender ID: 0x01 (1 byte) 2623 o Recipient ID: 0x (0 byte) 2625 From the previous parameters, 2627 o info (for Sender Key): 0x8441010A634b657910 (9 bytes) 2629 o info (for Recipient Key): 0x84400A634b657910 (8 bytes) 2631 o info (for Common IV): 0x84400a6249560d (7 bytes) 2633 Outputs: 2635 o Sender Key: 0xe534a26a64aa3982e988e31f1e401e65 (16 bytes) 2637 o Recipient Key: 0x7230aab3b549d94c9224aacc744e93ab (16 bytes) 2639 o Common IV: 0x01727733ab49ead385b18f7d91 (13 bytes) 2641 C.2. Test Vector 2: Key Derivation without Master Salt 2643 Given a set of inputs, OSCORE defines how to set up the Security 2644 Context in both the client and the server. The default values are 2645 used for AEAD Algorithm, KDF, and Master Salt. 2647 C.2.1. Client 2649 Inputs: 2651 o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes) 2653 o Sender ID: 0x00 (1 byte) 2655 o Recipient ID: 0x01 (1 byte) 2657 From the previous parameters, 2659 o info (for Sender Key): 0x8441000A634b657910 (9 bytes) 2661 o info (for Recipient Key): 0x8441010A634b657910 (9 bytes) 2663 o info (for Common IV): 0x84400a6249560d (7 bytes) 2665 Outputs: 2667 o Sender Key: 0xf8f3b887436285ed5a66f6026ac2cdc1 (16 bytes) 2669 o Recipient Key: 0xd904cb101f7341c3f4c56c300fa69941 (16 bytes) 2671 o Common IV: 0xd1a1949aa253278f34c528d2cc (13 bytes) 2673 C.2.2. Server 2675 Inputs: 2677 o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes) 2679 o Sender ID: 0x01 (1 byte) 2681 o Recipient ID: 0x00 (1 byte) 2683 From the previous parameters, 2685 o info (for Sender Key): 0x8441010A634b657910 (9 bytes) 2687 o info (for Recipient Key): 0x8441000A634b657910 (9 bytes) 2689 o info (for Common IV): 0x84400a6249560d (7 bytes) 2691 Outputs: 2693 o Sender Key: 0xd904cb101f7341c3f4c56c300fa69941 (16 bytes) 2695 o Recipient Key: 0xf8f3b887436285ed5a66f6026ac2cdc1 (16 bytes) 2697 o Common IV: 0xd1a1949aa253278f34c528d2cc (13 bytes) 2699 C.3. Test Vector 3: OSCORE Request, Client 2701 This section contains a test vector for a OSCORE protected CoAP GET 2702 request using the security context derived in Appendix C.1. The 2703 unprotected request only contains the Uri-Path option. 2705 Unprotected CoAP request: 2706 0x440149c60000f2a7396c6f63616c686f737483747631 (22 bytes) 2708 Common Context: 2710 o AEAD Algorithm: 10 (AES-CCM-16-64-128) 2712 o Key Derivation Function: HKDF SHA-256 2714 o Common IV: 0xd1a1949aa253278f34c528d2cc (13 bytes) 2715 Sender Context: 2717 o Sender ID: 0x00 (1 byte) 2719 o Sender Key: 0xf8f3b887436285ed5a66f6026ac2cdc1 (16 bytes) 2721 o Sender Sequence Number: 20 2723 The following COSE and cryptographic parameters are derived: 2725 o Partial IV: 0x14 (1 byte) 2727 o kid: 0x00 (1 byte) 2729 o external_aad: 0x8501810a4100411440 (9 bytes) 2731 o AAD: 0x8368456e63727970743040498501810a4100411440 (21 bytes) 2733 o plaintext: 0x01b3747631 (5 bytes) 2735 o encryption key: 0xf8f3b887436285ed5a66f6026ac2cdc1 (16 bytes) 2737 o nonce: 0xd0a1949aa253278f34c528d2d8 (13 bytes) 2739 From the previous parameter, the following is derived: 2741 o Object-Security value: 0x091400 (3 bytes) 2743 o ciphertext: 0x55b3710d47c611cd3924838a44 (13 bytes) 2745 From there: 2747 o Protected CoAP request (OSCORE message): 0x44026dd30000acc5396c6f6 2748 3616c686f7374d305091400ff55b3710d47c611cd3924838a44 (37 bytes) 2750 C.4. Test Vector 4: OSCORE Request, Client 2752 This section contains a test vector for a OSCORE protected CoAP GET 2753 request using the security context derived in Appendix C.2. The 2754 unprotected request only contains the Uri-Path option. 2756 Unprotected CoAP request: 2757 0x440149c60000f2a7396c6f63616c686f737483747631 (22 bytes) 2759 Common Context: 2761 o AEAD Algorithm: 10 (AES-CCM-16-64-128) 2762 o Key Derivation Function: HKDF SHA-256 2764 o Common IV: 0x01727733ab49ead385b18f7d91 (13 bytes) 2766 Sender Context: 2768 o Sender ID: 0x (0 bytes) 2770 o Sender Key: 0x7230aab3b549d94c9224aacc744e93ab (16 bytes) 2772 o Sender Sequence Number: 20 2774 The following COSE and cryptographic parameters are derived: 2776 o Partial IV: 0x14 (1 byte) 2778 o kid: 0x (0 byte) 2780 o external_aad: 0x8501810a40411440 (8 bytes) 2782 o AAD: 0x8368456e63727970743040488501810a40411440 (20 bytes) 2784 o plaintext: 0x01b3747631 (5 bytes) 2786 o encryption key: 0x7230aab3b549d94c9224aacc744e93ab (16 bytes) 2788 o nonce: 0x01727733ab49ead385b18f7d85 (13 bytes) 2790 From the previous parameter, the following is derived: 2792 o Object-Security value: 0x0914 (2 bytes) 2794 o ciphertext: 0x6be9214aad448260ff1be1f594 (13 bytes) 2796 From there: 2798 o Protected CoAP request (OSCORE message): 0x44023bfc000066ef396c6f6 2799 3616c686f7374d2050914ff6be9214aad448260ff1be1f594 (36 bytes) 2801 C.5. Test Vector 5: OSCORE Response, Server 2803 This section contains a test vector for a OSCORE protected 2.05 2804 Content response to the request in Appendix C.3. The unprotected 2805 response has payload "Hello World!" and no options. The protected 2806 response does not contain a kid nor a Partial IV. 2808 Unprotected CoAP response: 2809 0x644549c60000f2a7ff48656c6c6f20576f726c6421 (21 bytes) 2810 Common Context: 2812 o AEAD Algorithm: 10 (AES-CCM-16-64-128) 2814 o Key Derivation Function: HKDF SHA-256 2816 o Common IV: 0xd1a1949aa253278f34c528d2cc (13 bytes) 2818 Sender Context: 2820 o Sender ID: 0x01 (1 byte) 2822 o Sender Key: 0xd904cb101f7341c3f4c56c300fa69941 (16 bytes) 2824 o Sender Sequence Number: 0 2826 The following COSE and cryptographic parameters are derived: 2828 o external_aad: 0x8501810a4100411440 (9 bytes) 2830 o AAD: 0x8368456e63727970743040498501810a4100411440 (21 bytes) 2832 o plaintext: 0x45ff48656c6c6f20576f726c6421 (14 bytes) 2834 o encryption key: 0xd904cb101f7341c3f4c56c300fa69941 (16 bytes) 2836 o nonce: 0xd0a1949aa253278f34c528d2d8 (13 bytes) 2838 From the previous parameter, the following is derived: 2840 o Object-Security value: 0x (0 bytes) 2842 o ciphertext: e4e8c28c41c8f31ca56eec24f6c71d94eacbcdffdc6d (22 2843 bytes) 2845 From there: 2847 o Protected CoAP response (OSCORE message): 0x64446dd30000acc5d008ff 2848 e4e8c28c41c8f31ca56eec24f6c71d94eacbcdffdc6d (33 bytes) 2850 C.6. Test Vector 6: OSCORE Response with Partial IV, Server 2852 This section contains a test vector for a OSCORE protected 2.05 2853 Content response to the request in Appendix C.3. The unprotected 2854 response has payload "Hello World!" and no options. The protected 2855 response does not contain a kid, but contains a Partial IV. 2857 Unprotected CoAP response: 2858 0x644549c60000f2a7ff48656c6c6f20576f726c6421 (21 bytes) 2860 Common Context: 2862 o AEAD Algorithm: 10 (AES-CCM-16-64-128) 2864 o Key Derivation Function: HKDF SHA-256 2866 o Common IV: 0xd1a1949aa253278f34c528d2cc (13 bytes) 2868 Sender Context: 2870 o Sender ID: 0x01 (1 byte) 2872 o Sender Key: 0xd904cb101f7341c3f4c56c300fa69941 (16 bytes) 2874 o Sender Sequence Number: 0 2876 The following COSE and cryptographic parameters are derived: 2878 o Partial IV: 0x00 (1 byte) 2880 o external_aad: 0x8501810a4100411440 (9 bytes) 2882 o AAD: 0x8368456e63727970743040498501810a4100411440 (21 bytes) 2884 o plaintext: 0x45ff48656c6c6f20576f726c6421 (14 bytes) 2886 o encryption key: 0xd904cb101f7341c3f4c56c300fa69941 (16 bytes) 2888 o nonce: 0xd0a1949aa253278e34c528d2cc (13 bytes) 2890 From the previous parameter, the following is derived: 2892 o Object-Security value: 0x0100 (2 bytes) 2894 o ciphertext: 0xa7e3ca27f221f453c0ba68c350bf652ea096b328a1bf (22 2895 bytes) 2897 From there: 2899 o Protected CoAP response (OSCORE message): 0x64442b130000b29ed20801 2900 00ffa7e3ca27f221f453c0ba68c350bf652ea096b328a1bf (35 bytes) 2902 Appendix D. CDDL Summary 2904 Data structure definitions in the present specification employ the 2905 CDDL language for conciseness and precision. CDDL is defined in 2906 [I-D.ietf-cbor-cddl], which at the time of writing this appendix is 2907 in the process of completion. As the document is not yet available 2908 for a normative reference, the present appendix defines the small 2909 subset of CDDL that is being used in the present specification. 2911 Within the subset being used here, a CDDL rule is of the form "name = 2912 type", where "name" is the name given to the "type". A "type" can be 2913 one of: 2915 o a reference to another named type, by giving its name. The 2916 predefined named types used in the present specification are: 2917 "uint", an unsigned integer (as represented in CBOR by major type 2918 0); "int", an unsigned or negative integer (as represented in CBOR 2919 by major type 0 or 1); "bstr", a byte string (as represented in 2920 CBOR by major type 2); "tstr", a text string (as represented in 2921 CBOR by major type 3); 2923 o a choice between two types, by giving both types separated by a 2924 "/"; 2926 o an array type (as represented in CBOR by major type 4), where the 2927 sequence of elements of the array is described by giving a 2928 sequence of entries separated by commas ",", and this sequence is 2929 enclosed by square brackets "[" and "]". Arrays described by an 2930 array description contain elements that correspond one-to-one to 2931 the sequence of entries given. Each entry of an array description 2932 is of the form "name : type", where "name" is the name given to 2933 the entry and "type" is the type of the array element 2934 corresponding to this entry. 2936 Acknowledgments 2938 The following individuals provided input to this document: Christian 2939 Amsuess, Tobias Andersson, Carsten Bormann, Joakim Brorsson, Esko 2940 Dijk, Thomas Fossati, Martin Gunnarsson, Klaus Hartke, Jim Schaad, 2941 Peter van der Stok, Dave Thaler, Marco Tiloca, and Malisa Vucinic. 2943 Ludwig Seitz and Goeran Selander worked on this document as part of 2944 the CelticPlus project CyberWI, with funding from Vinnova. 2946 Authors' Addresses 2948 Goeran Selander 2949 Ericsson AB 2951 Email: goran.selander@ericsson.com 2953 John Mattsson 2954 Ericsson AB 2956 Email: john.mattsson@ericsson.com 2958 Francesca Palombini 2959 Ericsson AB 2961 Email: francesca.palombini@ericsson.com 2963 Ludwig Seitz 2964 RISE SICS 2966 Email: ludwig.seitz@ri.se