idnits 2.17.1 draft-ietf-core-object-security-08.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 (January 22, 2018) is 2284 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 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-09 == 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-00 == 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 Summary: 3 errors (**), 0 flaws (~~), 7 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: July 26, 2018 Ericsson AB 6 L. Seitz 7 RISE SICS 8 January 22, 2018 10 Object Security for Constrained RESTful Environments (OSCORE) 11 draft-ietf-core-object-security-08 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 July 26, 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 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 . . . . . . . . . . . . . . . . . . 36 92 10.1. CoAP-to-CoAP Forwarding Proxy . . . . . . . . . . . . . 37 93 10.2. HTTP Processing . . . . . . . . . . . . . . . . . . . . 37 94 10.3. HTTP-to-CoAP Translation Proxy . . . . . . . . . . . . . 38 95 10.4. CoAP-to-HTTP Translation Proxy . . . . . . . . . . . . . 40 96 11. Security Considerations . . . . . . . . . . . . . . . . . . . 41 97 11.1. End-to-end protection . . . . . . . . . . . . . . . . . 41 98 11.2. Security Context Establishment . . . . . . . . . . . . . 42 99 11.3. Replay Protection . . . . . . . . . . . . . . . . . . . 42 100 11.4. Cryptographic Considerations . . . . . . . . . . . . . . 42 101 11.5. Message Fragmentation . . . . . . . . . . . . . . . . . 43 102 11.6. Privacy Considerations . . . . . . . . . . . . . . . . . 43 103 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 44 104 12.1. COSE Header Parameters Registry . . . . . . . . . . . . 44 105 12.2. CoAP Option Numbers Registry . . . . . . . . . . . . . . 44 106 12.3. CoAP Signaling Option Numbers Registry . . . . . . . . . 45 107 12.4. Header Field Registrations . . . . . . . . . . . . . . . 45 108 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 45 109 13.1. Normative References . . . . . . . . . . . . . . . . . . 45 110 13.2. Informative References . . . . . . . . . . . . . . . . . 46 111 Appendix A. Scenario examples . . . . . . . . . . . . . . . . . 48 112 A.1. Secure Access to Sensor . . . . . . . . . . . . . . . . . 48 113 A.2. Secure Subscribe to Sensor . . . . . . . . . . . . . . . 49 114 Appendix B. Deployment examples . . . . . . . . . . . . . . . . 51 115 B.1. Master Secret Used Once . . . . . . . . . . . . . . . . . 51 116 B.2. Master Secret Used Multiple Times . . . . . . . . . . . . 51 117 B.3. Client Aliveness . . . . . . . . . . . . . . . . . . . . 51 118 Appendix C. Test Vectors . . . . . . . . . . . . . . . . . . . . 52 119 C.1. Test Vector 1: Key Derivation with Master Salt . . . . . 52 120 C.2. Test Vector 2: Key Derivation without Master Salt . . . . 53 121 C.3. Test Vector 3: OSCORE Request, Client . . . . . . . . . . 54 122 C.4. Test Vector 4: OSCORE Request, Client . . . . . . . . . . 55 123 C.5. Test Vector 5: OSCORE Response, Server . . . . . . . . . 57 124 C.6. Test Vector 6: OSCORE Response with Partial IV, Server . 58 125 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 59 126 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 59 128 1. Introduction 130 The Constrained Application Protocol (CoAP) [RFC7252] is a web 131 application protocol, designed for constrained nodes and networks 132 [RFC7228], and may be mapped from HTTP [RFC8075]. CoAP specifies the 133 use of proxies for scalability and efficiency and references DTLS 134 ([RFC6347]) for security. CoAP and HTTP proxies require (D)TLS to be 135 terminated at the proxy. The proxy therefore not only has access to 136 the data required for performing the intended proxy functionality, 137 but is also able to eavesdrop on, or manipulate any part of the 138 message payload and metadata, in transit between the endpoints. The 139 proxy can also inject, delete, or reorder packets since they are no 140 longer protected by (D)TLS. 142 This document defines the Object Security for Constrained RESTful 143 Environments (OSCORE) security protocol, protecting CoAP and CoAP- 144 mappable HTTP requests and responses end-to-end across intermediary 145 nodes such as CoAP forward proxies and cross-protocol translators 146 including HTTP-to-CoAP proxies [RFC8075]. In addition to the core 147 CoAP features defined in [RFC7252], OSCORE supports Observe 148 [RFC7641], Blockwise [RFC7959], No-Response [RFC7967], and PATCH and 149 FETCH [RFC8132]. An analysis of end-to-end security for CoAP 150 messages through some types of intermediary nodes is performed in 151 [I-D.hartke-core-e2e-security-reqs]. OSCORE essentially protects the 152 RESTful interactions; the request method, the requested resource, the 153 message payload, etc. (see Section 4). OSCORE does neither protect 154 the CoAP Messaging Layer nor the CoAP Token which may change between 155 the endpoints, and those are therefore processed as defined in 156 [RFC7252]. Additionally, since the message formats for CoAP over 157 unreliable transport [RFC7252] and for CoAP over reliable transport 158 [I-D.ietf-core-coap-tcp-tls] differ only in terms of CoAP Messaging 159 Layer, OSCORE can be applied to both unreliable and reliable 160 transports (see Figure 1). 162 +-----------------------------------+ 163 | Application | 164 +-----------------------------------+ 165 +-----------------------------------+ \ 166 | Requests / Responses / Signaling | | 167 |-----------------------------------| | 168 | OSCORE | | CoAP 169 |-----------------------------------| | 170 | Messaging Layer / Message Framing | | 171 +-----------------------------------+ / 172 +-----------------------------------+ 173 | UDP / TCP / ... | 174 +-----------------------------------+ 176 Figure 1: Abstract Layering of CoAP with OSCORE 178 OSCORE works in very constrained nodes and networks, thanks to its 179 small message size and the restricted code and memory requirements in 180 addition to what is required by CoAP. Examples of the use of OSCORE 181 are given in Appendix A. OSCORE does not depend on underlying 182 layers, and can be used anywhere where CoAP or HTTP can be used, 183 including non-IP transports (e.g., [I-D.bormann-6lo-coap-802-15-ie]). 184 OSCORE may be used together with (D)TLS over one or more hops in the 185 end-to-end path, e.g. with HTTPs in one hop and with plain CoAP in 186 another hop. 188 An extension of OSCORE may also be used to protect group 189 communication for CoAP [I-D.tiloca-core-multicast-oscoap]. The use 190 of OSCORE does not affect the URI scheme and OSCORE can therefore be 191 used with any URI scheme defined for CoAP or HTTP. The application 192 decides the conditions for which OSCORE is required. 194 OSCORE uses pre-shared keys which may have been established out-of- 195 band or with a key establishment protocol (see Section 3.2). The 196 technical solution builds on CBOR Object Signing and Encryption 197 (COSE) [RFC8152], providing end-to-end encryption, integrity, replay 198 protection, and secure binding of response to request. A compressed 199 version of COSE is used, as specified in Section 6. The use of 200 OSCORE is signaled with the new Object-Security CoAP option or HTTP 201 header field, defined in Section 2 and Section 10.3. The solution 202 transforms a CoAP/HTTP message into an "OSCORE message" before 203 sending, and vice versa after receiving. The OSCORE message is a 204 CoAP/HTTP message related to the original message in the following 205 way: the original CoAP/HTTP message is translated to CoAP (if not 206 already in CoAP) and protected in a COSE object. The encrypted 207 message fields of this COSE object are transported in the CoAP 208 payload/HTTP body of the OSCORE message, and the Object-Security 209 option/header field is included in the message. A sketch of an 210 OSCORE message exchange in the case of the original message being 211 CoAP is provided in Figure 2). 213 Client Server 214 | OSCORE request - POST example.com: | 215 | Header, Token, | 216 | Options: {Object-Security, ...}, | 217 | Payload: COSE ciphertext | 218 +--------------------------------------------->| 219 | | 220 |<---------------------------------------------+ 221 | OSCORE response - 2.04 (Changed): | 222 | Header, Token, | 223 | Options: {Object-Security, ...}, | 224 | Payload: COSE ciphertext | 225 | | 227 Figure 2: Sketch of CoAP with OSCORE 229 An implementation supporting this specification MAY only implement 230 the client part, MAY only implement the server part, or MAY only 231 implement one of the proxy parts. OSCORE is designed to protect as 232 much information as possible while still allowing proxy operations 233 (Section 10). It works with legacy CoAP-to-CoAP forward proxies 234 [RFC7252], but an OSCORE-aware proxy will be more efficient. HTTP- 235 to-CoAP proxies [RFC8075] and CoAP-to-HTTP proxies can also be used 236 with OSCORE, as specified in Section 10. 238 1.1. Terminology 240 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 241 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 242 document are to be interpreted as described in [RFC2119]. These 243 words may also appear in this document in lowercase, absent their 244 normative meanings. 246 Readers are expected to be familiar with the terms and concepts 247 described in CoAP [RFC7252], Observe [RFC7641], Blockwise [RFC7959], 248 COSE [RFC8152], CBOR [RFC7049], CDDL [I-D.ietf-cbor-cddl], and 249 constrained environments [RFC7228]. 251 The term "hop" is used to denote a particular leg in the end-to-end 252 path. The concept "hop-by-hop" (as in "hop-by-hop encryption" or 253 "hop-by-hop fragmentation") opposed to "end-to-end", is used in this 254 document to indicate that the messages are processed accordingly in 255 the intermediaries, rather than just forwarded to the next node. 257 The term "stop processing" is used throughout the document to denote 258 that the message is not passed up to the CoAP Request/Response layer 259 (see Figure 1). 261 The terms Common/Sender/Recipient Context, Master Secret/Salt, Sender 262 ID/Key, Recipient ID/Key, and Common IV are defined in Section 3.1. 264 2. The CoAP Object-Security Option 266 The CoAP Object-Security option (see Figure 3) indicates that the 267 CoAP message is an OSCORE message and that it contains a compressed 268 COSE object (see Section 5 and Section 6). The Object-Security 269 option is critical, safe to forward, part of the cache key, and not 270 repeatable. 272 +-----+---+---+---+---+-----------------+--------+--------+---------+ 273 | No. | C | U | N | R | Name | Format | Length | Default | 274 +-----+---+---+---+---+-----------------+--------+--------+---------+ 275 | TBD | x | | | | Object-Security | (*) | 0-255 | (none) | 276 +-----+---+---+---+---+-----------------+--------+--------+---------+ 277 C = Critical, U = Unsafe, N = NoCacheKey, R = Repeatable 278 (*) See below. 280 Figure 3: The Object-Security Option 282 The Object-Security option includes the OSCORE flag bits (Section 6), 283 the Sender Sequence Number and the Sender ID when present 284 (Section 3). The detailed format and length is specified in 285 Section 6. If the OSCORE flag bits is all zero (0x00) the Option 286 value SHALL be empty (Option Length = 0). An endpoint receiving a 287 CoAP message without payload, that also contains an Object-Security 288 option SHALL treat it as malformed and reject it. 290 A successful response to a request with the Object-Security option 291 SHALL contain the Object-Security option. Whether error responses 292 contain the Object-Security option depends on the error type (see 293 Section 8). 295 A CoAP proxy SHOULD NOT cache a response to a request with an Object- 296 Security option, since the response is only applicable to the 297 original request (see Section 10.1). As the compressed COSE Object 298 is included in the cache key, messages with the Object-Security 299 option will never generate cache hits. For Max-Age processing (see 300 Section 4.2.3.1). 302 3. The Security Context 304 OSCORE requires that client and server establish a shared security 305 context used to process the COSE objects. OSCORE uses COSE with an 306 Authenticated Encryption with Additional Data (AEAD) algorithm for 307 protecting message data between a client and a server. In this 308 section, we define the security context and how it is derived in 309 client and server based on a shared secret and a key derivation 310 function (KDF). 312 3.1. Security Context Definition 314 The security context is the set of information elements necessary to 315 carry out the cryptographic operations in OSCORE. For each endpoint, 316 the security context is composed of a "Common Context", a "Sender 317 Context", and a "Recipient Context". 319 The endpoints protect messages to send using the Sender Context and 320 verify messages received using the Recipient Context, both contexts 321 being derived from the Common Context and other data. Clients and 322 servers need to be able to retrieve the correct security context to 323 use. 325 An endpoint uses its Sender ID (SID) to derive its Sender Context, 326 and the other endpoint uses the same ID, now called Recipient ID 327 (RID), to derive its Recipient Context. In communication between two 328 endpoints, the Sender Context of one endpoint matches the Recipient 329 Context of the other endpoint, and vice versa. Thus, the two 330 security contexts identified by the same IDs in the two endpoints are 331 not the same, but they are partly mirrored. Retrieval and use of the 332 security context are shown in Figure 4. 334 .-------------. .-------------. 335 | Common, | | Common, | 336 | Sender, | | Recipient, | 337 | Recipient | | Sender | 338 '-------------' '-------------' 339 Client Server 340 | | 341 Retrieve context for | OSCORE request: | 342 target resource | Token = Token1, | 343 Protect request with | kid = SID, ... | 344 Sender Context +---------------------->| Retrieve context with 345 | | RID = kid 346 | | Verify request with 347 | | Recipient Context 348 | OSCORE response: | Protect response with 349 | Token = Token1, ... | Sender Context 350 Retrieve context with |<----------------------+ 351 Token = Token1 | | 352 Verify request with | | 353 Recipient Context | | 355 Figure 4: Retrieval and use of the Security Context 357 The Common Context contains the following parameters: 359 o AEAD Algorithm. The COSE AEAD algorithm to use for encryption. 360 Its value is immutable once the security context is established. 362 o Key Derivation Function. The HMAC based HKDF [RFC5869] used to 363 derive Sender Key, Recipient Key, and Common IV. 365 o Master Secret. Variable length, uniformly random byte string 366 containing the key used to derive traffic keys and IVs. Its value 367 is immutable once the security context is established. 369 o Master Salt. Variable length byte string containing the salt used 370 to derive traffic keys and IVs. Its value is immutable once the 371 security context is established. 373 o Common IV. Byte string derived from Master Secret and Master 374 Salt. Length is determined by the AEAD Algorithm. Its value is 375 immutable once the security context is established. 377 The Sender Context contains the following parameters: 379 o Sender ID. Byte string used to identify the Sender Context and to 380 assure unique AEAD nonces. Maximum length is determined by the 381 AEAD Algorithm. Its value is immutable once the security context 382 is established. 384 o Sender Key. Byte string containing the symmetric key to protect 385 messages to send. Derived from Common Context and Sender ID. 386 Length is determined by the AEAD Algorithm. Its value is 387 immutable once the security context is established. 389 o Sender Sequence Number. Non-negative integer used by the sender 390 to protect requests and Observe notifications. Used as 'Partial 391 IV' [RFC8152] to generate unique nonces for the AEAD. Maximum 392 value is determined by the AEAD Algorithm. 394 The Recipient Context contains the following parameters: 396 o Recipient ID. Byte string used to identify the Recipient Context 397 and to assure unique AEAD nonces. Maximum length is determined by 398 the AEAD Algorithm. Its value is immutable once the security 399 context is established. 401 o Recipient Key. Byte string containing the symmetric key to verify 402 messages received. Derived from Common Context and Recipient ID. 403 Length is determined by the AEAD Algorithm. Its value is 404 immutable once the security context is established. 406 o Replay Window (Server only). The replay window to verify requests 407 received. 409 An endpoint may free up memory by not storing the Common IV, Sender 410 Key, and Recipient Key, deriving them from the Master Key and Master 411 Salt when needed. Alternatively, an endpoint may free up memory by 412 not storing the Master Secret and Master Salt after the other 413 parameters have been derived. 415 Endpoints MAY operate as both client and server and use the same 416 security context for those roles. Independent of being client or 417 server, the endpoint protects messages to send using its Sender 418 Context, and verifies messages received using its Recipient Context. 419 The endpoints MUST NOT change the Sender/Recipient ID when changing 420 roles. In other words, changing the roles does not change the set of 421 keys to be used. 423 3.2. Establishment of Security Context Parameters 425 The parameters in the security context are derived from a small set 426 of input parameters. The following input parameters SHALL be pre- 427 established: 429 o Master Secret 431 o Sender ID 433 o Recipient ID 435 The following input parameters MAY be pre-established. In case any 436 of these parameters is not pre-established, the default value 437 indicated below is used: 439 o AEAD Algorithm 441 * Default is AES-CCM-16-64-128 (COSE algorithm encoding: 10) 443 o Master Salt 445 * Default is the empty string 447 o Key Derivation Function (KDF) 449 * Default is HKDF SHA-256 451 o Replay Window Type and Size 453 * Default is DTLS-type replay protection with a window size of 32 454 ([RFC6347]) 456 All input parameters need to be known to and agreed on by both 457 endpoints, but the replay window may be different in the two 458 endpoints. How the input parameters are pre-established, is 459 application specific. The OSCORE profile of the ACE framework may be 460 used to establish the necessary input parameters 461 ([I-D.ietf-ace-oscore-profile]), or a key exchange protocol such as 462 the TLS/DTLS handshake ([I-D.mattsson-ace-tls-oscore]) providing 463 forward secrecy. Other examples of deploying OSCORE are given in 464 Appendix B. 466 3.2.1. Derivation of Sender Key, Recipient Key, and Common IV 468 The KDF MUST be one of the HMAC based HKDF [RFC5869] algorithms 469 defined in COSE. HKDF SHA-256 is mandatory to implement. The 470 security context parameters Sender Key, Recipient Key, and Common IV 471 SHALL be derived from the input parameters using the HKDF, which 472 consists of the composition of the HKDF-Extract and HKDF-Expand steps 473 ([RFC5869]): 475 output parameter = HKDF(salt, IKM, info, L) 477 where: 479 o salt is the Master Salt as defined above 481 o IKM is the Master Secret as defined above 483 o info is a CBOR array consisting of: 485 info = [ 486 id : bstr, 487 alg_aead : int / tstr, 488 type : tstr, 489 L : uint 490 ] 492 where: 494 o id is the Sender ID or Recipient ID when deriving keys and the 495 empty string when deriving the Common IV. The encoding is 496 described in Section 5. 498 o alg_aead is the AEAD Algorithm, encoded as defined in [RFC8152]. 500 o type is "Key" or "IV". The label is an ASCII string, and does not 501 include a trailing NUL byte. 503 o L is the size of the key/IV for the AEAD algorithm used, in bytes. 505 For example, if the algorithm AES-CCM-16-64-128 (see Section 10.2 in 506 [RFC8152]) is used, the integer value for alg_aead is 10, the value 507 for L is 16 for keys and 13 for the Common IV. 509 3.2.2. Initial Sequence Numbers and Replay Window 511 The Sender Sequence Number is initialized to 0. The supported types 512 of replay protection and replay window length is application specific 513 and depends on how OSCORE is transported, see Section 7.4. The 514 default is DTLS-type replay protection with a window size of 32 515 initiated as described in Section 4.1.2.6 of [RFC6347]. 517 3.3. Requirements on the Security Context Parameters 519 As collisions may lead to the loss of both confidentiality and 520 integrity, Sender ID SHALL be unique in the set of all security 521 contexts using the same Master Secret and Master Salt. When a 522 trusted third party assigns identifiers (e.g., using 523 [I-D.ietf-ace-oauth-authz]) or by using a protocol that allows the 524 parties to negotiate locally unique identifiers in each endpoint, the 525 Sender IDs can be very short. The maximum length of Sender ID in 526 bytes equals the length of AEAD nonce minus 6. For AES-CCM-16-64-128 527 the maximum length of Sender ID is 7 bytes. Sender IDs MAY be 528 uniformly random distributed byte strings if the probability of 529 collisions is negligible. 531 If Sender ID uniqueness cannot be guaranteed by construction, Sender 532 IDs MUST be long uniformly random distributed byte strings such that 533 the probability of collisions is negligible. 535 To enable retrieval of the right Recipient Context, the Recipient ID 536 SHOULD be unique in the sets of all Recipient Contexts used by an 537 endpoint. The Client MAY provide a 'kid context' parameter 538 (Section 5.1) to help the Server find the right context. 540 While the triple (Master Secret, Master Salt, Sender ID) MUST be 541 unique, the same Master Salt MAY be used with several Master Secrets 542 and the same Master Secret MAY be used with several Master Salts. 544 4. Protected Message Fields 546 OSCORE transforms a CoAP message (which may have been generated from 547 an HTTP message) into an OSCORE message, and vice versa. OSCORE 548 protects as much of the original message as possible while still 549 allowing certain proxy operations (see Section 10). This section 550 defines how OSCORE protects the message fields and transfers them 551 end-to-end between client and server (in any direction). 553 The remainder of this section and later sections discuss the behavior 554 in terms of CoAP messages. If HTTP is used for a particular hop in 555 the end-to-end path, then this section applies to the conceptual CoAP 556 message that is mappable to/from the original HTTP message as 557 discussed in Section 10. That is, an HTTP message is conceptually 558 transformed to a CoAP message and then to an OSCORE message, and 559 similarly in the reverse direction. An actual implementation might 560 translate directly from HTTP to OSCORE without the intervening CoAP 561 representation. 563 Protection of Signaling messages (Section 5 of 564 [I-D.ietf-core-coap-tcp-tls]) is specified in Section 4.4. The other 565 parts of this section target Request/Response messages. 567 Message fields of the CoAP message may be protected end-to-end 568 between CoAP client and CoAP server in different ways: 570 o Class E: encrypted and integrity protected, 572 o Class I: integrity protected only, or 573 o Class U: unprotected. 575 The sending endpoint SHALL transfer Class E message fields in the 576 ciphertext of the COSE object in the OSCORE message. The sending 577 endpoint SHALL include Class I message fields in the Additional 578 Authenticated Data (AAD) of the AEAD algorithm, allowing the 579 receiving endpoint to detect if the value has changed in transfer. 580 Class U message fields SHALL NOT be protected in transfer. Class I 581 and Class U message field values are transferred in the header or 582 options part of the OSCORE message, which is visible to proxies. 584 Message fields not visible to proxies, i.e., transported in the 585 ciphertext of the COSE object, are called "Inner" (Class E). Message 586 fields transferred in the header or options part of the OSCORE 587 message, which is visible to proxies, are called "Outer" (Class I or 588 U). There are currently no Class I options defined. 590 An OSCORE message may contain both an Inner and an Outer instance of 591 a certain CoAP message field. Inner message fields are intended for 592 the receiving endpoint, whereas Outer message fields are used to 593 support proxy operations. Inner and Outer message fields are 594 processed independently. 596 4.1. CoAP Payload 598 The CoAP Payload, if present in the original CoAP message, SHALL be 599 encrypted and integrity protected and is thus an Inner message field. 600 See Figure 5. 602 +------------------+---+---+ 603 | Field | E | U | 604 +------------------+---+---+ 605 | Payload | x | | 606 +------------------+---+---+ 608 E = Encrypt and Integrity Protect (Inner) 609 U = Unprotected (Outer) 611 Figure 5: Protection of CoAP Payload 613 The sending endpoint writes the payload of the original CoAP message 614 into the plaintext (Section 5.3) input to the COSE object. The 615 receiving endpoint verifies and decrypts the COSE object, and 616 recreates the payload of the original CoAP message. 618 4.2. CoAP Options 620 A summary of how options are protected is shown in Figure 6. Note 621 that some options may have both Inner and Outer message fields which 622 are protected accordingly. The options which require special 623 processing are labelled with asterisks. 625 +-----+-----------------+---+---+ 626 | No. | Name | E | U | 627 +-----+-----------------+---+---+ 628 | 1 | If-Match | x | | 629 | 3 | Uri-Host | | x | 630 | 4 | ETag | x | | 631 | 5 | If-None-Match | x | | 632 | 6 | Observe | | * | 633 | 7 | Uri-Port | | x | 634 | 8 | Location-Path | x | | 635 | TBD | Object-Security | | * | 636 | 11 | Uri-Path | x | | 637 | 12 | Content-Format | x | | 638 | 14 | Max-Age | * | * | 639 | 15 | Uri-Query | x | | 640 | 17 | Accept | x | | 641 | 20 | Location-Query | x | | 642 | 23 | Block2 | * | * | 643 | 27 | Block1 | * | * | 644 | 28 | Size2 | * | * | 645 | 35 | Proxy-Uri | | * | 646 | 39 | Proxy-Scheme | | x | 647 | 60 | Size1 | * | * | 648 | 258 | No-Response | * | * | 649 +-----+-----------------+---+---+ 651 E = Encrypt and Integrity Protect (Inner) 652 U = Unprotected (Outer) 653 * = Special 655 Figure 6: Protection of CoAP Options 657 Options that are unknown or for which OSCORE processing is not 658 defined SHALL be processed as class E (and no special processing). 659 Specifications of new CoAP options SHOULD define how they are 660 processed with OSCORE. A new COAP option SHOULD be of class E unless 661 it requires proxy processing. 663 4.2.1. Inner Options 665 Inner option message fields (class E) are used to communicate 666 directly with the other endpoint. 668 The sending endpoint SHALL write the Inner option message fields 669 present in the original CoAP message into the plaintext of the COSE 670 object (Section 5.3), and then remove the Inner option message fields 671 from the OSCORE message. 673 The processing of Inner option message fields by the receiving 674 endpoint is specified in Section 8.2 and Section 8.4. 676 4.2.2. Outer Options 678 Outer option message fields (Class U or I) are used to support proxy 679 operations. 681 The sending endpoint SHALL include the Outer option message field 682 present in the original message in the options part of the OSCORE 683 message. All Outer option message fields, including Object-Security, 684 SHALL be encoded as described in Section 3.1 of [RFC7252], where the 685 delta is the difference to the previously included Outer option 686 message field. 688 The processing of Outer options by the receiving endpoint is 689 specified in Section 8.2 and Section 8.4. 691 A procedure for integrity-protection-only of Class I option message 692 fields is specified in Section 5.4. New CoAP options which are 693 repeatable and of class I MUST specify that proxies MUST NOT change 694 the order of the option's occurrences. 696 Note: There are currently no Class I option message fields defined. 698 4.2.3. Special Options 700 Some options require special processing, marked with an asterisk '*' 701 in Figure 6; the processing is specified in this section. 703 4.2.3.1. Max-Age 705 An Inner Max-Age message field is used to indicate the maximum time a 706 response may be cached by the client (as defined in [RFC7252]), end- 707 to-end from the server to the client, taking into account that the 708 option is not accessible to proxies. The Inner Max-Age SHALL be 709 processed by OSCORE as specified in Section 4.2.1. 711 An Outer Max-Age message field is used to avoid unnecessary caching 712 of OSCORE error responses at OSCORE unaware intermediary nodes. A 713 server MAY set a Class U Max-Age message field with value zero to 714 OSCORE error responses described in Section 7.4, Section 8.2 and 715 Section 8.4, which is then processed according to Section 4.2.2. 717 Successful OSCORE responses do not need to include an Outer Max-Age 718 option since the responses are non-cacheable by construction (see 719 Section 4.3). 721 4.2.3.2. The Block Options 723 Blockwise [RFC7959] is an optional feature. An implementation MAY 724 support [RFC7252] and the Object-Security option without supporting 725 Blockwise. The Block options (Block1, Block2, Size1, Size2), when 726 Inner message fields, provide secure message fragmentation such that 727 each fragment can be verified. The Block options, when Outer message 728 fields, enables hop-by-hop fragmentation of the OSCORE message. 729 Inner and Outer block processing may have different performance 730 properties depending on the underlying transport. The end-to-end 731 integrity of the message can be verified both in case of Inner and 732 Outer Blockwise provided all blocks are received. 734 4.2.3.2.1. Inner Block Options 736 The sending CoAP endpoint MAY fragment a CoAP message as defined in 737 [RFC7959] before the message is processed by OSCORE. In this case 738 the Block options SHALL be processed by OSCORE as Inner options 739 (Section 4.2.1). The receiving CoAP endpoint SHALL process the 740 OSCORE message according to Section 4.2.1 before processing Blockwise 741 as defined in [RFC7959]. 743 For concurrent Blockwise operations the sending endpoint MUST ensure 744 that the receiving endpoint can distinguish between blocks from 745 different operations. One mechanism enabling this is specified in 746 [I-D.ietf-core-echo-request-tag]. 748 4.2.3.2.2. Outer Block Options 750 Proxies MAY fragment an OSCORE message using [RFC7959], by 751 introducing Block option message fields that are Outer 752 (Section 4.2.2) and not generated by the sending endpoint. Note that 753 the Outer Block options are neither encrypted nor integrity 754 protected. As a consequence, a proxy can maliciously inject block 755 fragments indefinitely, since the receiving endpoint needs to receive 756 the last block (see [RFC7959]) to be able to compose the OSCORE 757 message and verify its integrity. Therefore, applications supporting 758 OSCORE and [RFC7959] MUST specify a security policy defining a 759 maximum unfragmented message size (MAX_UNFRAGMENTED_SIZE) considering 760 the maximum size of message which can be handled by the endpoints. 761 Messages exceeding this size SHOULD be fragmented by the sending 762 endpoint using Inner Block options (Section 4.2.3.2.1). 764 An endpoint receiving an OSCORE message with an Outer Block option 765 SHALL first process this option according to [RFC7959], until all 766 blocks of the OSCORE message have been received, or the cumulated 767 message size of the blocks exceeds MAX_UNFRAGMENTED_SIZE. In the 768 former case, the processing of the OSCORE message continues as 769 defined in this document. In the latter case the message SHALL be 770 discarded. 772 Because of encryption of Uri-Path and Uri-Query, messages to the same 773 server may, from the point of view of a proxy, look like they also 774 target the same resource. A proxy SHOULD mitigate a potential mix-up 775 of blocks from concurrent requests to the same server, for example 776 using the Request-Tag processing specified in Section 3.3.2 of 777 [I-D.ietf-core-echo-request-tag]. 779 4.2.3.3. Proxy-Uri 781 Proxy-Uri, when present, is split by OSCORE into class U options and 782 class E options, which are processed accordingly. When Proxy-Uri is 783 used in the original CoAP message, Uri-* are not present [RFC7252]. 785 The sending endpoint SHALL first decompose the Proxy-Uri value of the 786 original CoAP message into the Proxy-Scheme, Uri-Host, Uri-Port, Uri- 787 Path, and Uri-Query options (if present) according to Section 6.4 of 788 [RFC7252]. 790 Uri-Path and Uri-Query are class E options and SHALL be protected and 791 processed as Inner options (Section 4.2.1). 793 The Proxy-Uri option of the OSCORE message SHALL be set to the 794 composition of Proxy-Scheme, Uri-Host, and Uri-Port options (if 795 present) as specified in Section 6.5 of [RFC7252], and processed as 796 an Outer option of Class U (Section 4.2.2). 798 Note that replacing the Proxy-Uri value with the Proxy-Scheme and 799 Uri-* options works by design for all CoAP URIs (see Section 6 of 800 [RFC7252]). OSCORE-aware HTTP servers should not use the userinfo 801 component of the HTTP URI (as defined in Section 3.2.1 of [RFC3986]), 802 so that this type of replacement is possible in the presence of CoAP- 803 to-HTTP proxies. In future documents specifying cross-protocol 804 proxying behavior using different URI structures, it is expected that 805 the authors will create Uri-* options that allow decomposing the 806 Proxy-Uri, and specify in which OSCORE class they belong. 808 An example of how Proxy-Uri is processed is given here. Assume that 809 the original CoAP message contains: 811 o Proxy-Uri = "coap://example.com/resource?q=1" 813 During OSCORE processing, Proxy-Uri is split into: 815 o Proxy-Scheme = "coap" 817 o Uri-Host = "example.com" 819 o Uri-Port = "5683" 821 o Uri-Path = "resource" 823 o Uri-Query = "q=1" 825 Uri-Path and Uri-Query follow the processing defined in 826 Section 4.2.1, and are thus encrypted and transported in the COSE 827 object. The remaining options are composed into the Proxy-Uri 828 included in the options part of the OSCORE message, which has value: 830 o Proxy-Uri = "coap://example.com" 832 See Sections 6.1 and 12.6 of [RFC7252] for more information. 834 4.2.3.4. Observe 836 Observe [RFC7641] is an optional feature. An implementation MAY 837 support [RFC7252] and the Object-Security option without supporting 838 [RFC7641]. The Observe option as used here targets the requirements 839 on forwarding of [I-D.hartke-core-e2e-security-reqs] (Section 2.2.1). 841 In order for an OSCORE-unaware proxy to support forwarding of Observe 842 messages ([RFC7641]), there SHALL be an Outer Observe option, i.e., 843 present in the options part of the OSCORE message. The processing of 844 the CoAP Code for Observe messages is described in Section 4.3. 846 To secure the order of notifications, the client SHALL maintain a 847 Notification Number for each Observation it registers. The 848 Notification Number is a non-negative integer containing the largest 849 Partial IV of the successfully received notifications for the 850 associated Observe registration (see Section 7.4). The Notification 851 Number is initialized to the Partial IV of the first successfully 852 received notification response to the registration request. In 853 contrast to [RFC7641], the received Partial IV MUST always be 854 compared with the Notification Number, which thus MUST NOT be 855 forgotten after 128 seconds. The client MAY ignore the Observe 856 option value. 858 If the verification fails, the client SHALL stop processing the 859 response. 861 The Observe option in the CoAP request may be legitimately removed by 862 a proxy. If the Observe option is removed from a CoAP request by a 863 proxy, then the server can still verify the request (as a non-Observe 864 request), and produce a non-Observe response. If the OSCORE client 865 receives a response to an Observe request without an Outer Observe 866 value, then it MUST verify the response as a non-Observe response. 867 If the OSCORE client receives a response to a non-Observe request 868 with an Outer Observe value, it stops processing the message, as 869 specified in Section 8.4. 871 Clients can re-register observations to ensure that the observation 872 is still active and establish freshness again ([RFC7641] 873 Section 3.3.1). When an OSCORE observation is refreshed, not only 874 the ETags, but also the partial IV (and thus the payload and Object- 875 Security option) change. The server uses the new request's Partial 876 IV as the 'request_piv' of new responses. 878 4.2.3.5. No-Response 880 No-Response is defined in [RFC7967]. Clients using No-Response MUST 881 set both an Inner (Class E) and an Outer (Class U) No-Response 882 option, with same value. 884 The Inner No-Response option is used to communicate to the server the 885 client's disinterest in certain classes of responses to a particular 886 request. The Inner No-Response SHALL be processed by OSCORE as 887 specified in Section 4.2.1. 889 The Outer No-Response option is used to support proxy functionality, 890 specifically to avoid error transmissions from proxies to clients, 891 and to avoid bandwidth reduction to servers by proxies applying 892 congestion control when not receiving responses. The Outer No- 893 Response option is processed according to Section 4.2.2. 895 In particular, step 8 of Section 8.4 is applied to No-Response. 897 Applications should consider that a proxy may remove the Outer No- 898 Response option from the request. Applications using No-Response can 899 specify policies to deal with cases where servers receive an Inner 900 No-Response option only, which may be the result of the request 901 having traversed a No-Response unaware proxy, and update the 902 processing in Section 8.4 accordingly. This avoids unnecessary error 903 responses to clients and bandwidth reductions to servers, due to No- 904 Response unaware proxies. 906 4.2.3.6. Object-Security 908 The Object-Security option is only defined to be present in OSCORE 909 messages, as an indication that OSCORE processing have been 910 performed. The content in the Object-Security option is neither 911 encrypted nor integrity protected as a whole but some part of the 912 content of this option is protected (see Section 5.4). "OSCORE 913 within OSCORE" is not supported: If OSCORE processing detects an 914 Object-Security option in the original CoAP message, then processing 915 SHALL be stopped. 917 4.3. CoAP Header 919 A summary of how the CoAP Header fields are protected is shown in 920 Figure 7, including fields specific to CoAP over UDP and CoAP over 921 TCP (marked accordingly in the table). 923 +------------------+---+---+ 924 | Field | E | U | 925 +------------------+---+---+ 926 | Version (UDP) | | x | 927 | Type (UDP) | | x | 928 | Length (TCP) | | x | 929 | Token Length | | x | 930 | Code | x | | 931 | Message ID (UDP) | | x | 932 | Token | | x | 933 +------------------+---+---+ 935 E = Encrypt and Integrity Protect (Inner) 936 U = Unprotected (Outer) 938 Figure 7: Protection of CoAP Header Fields 940 Most CoAP Header fields (i.e. the message fields in the fixed 4-byte 941 header) are required to be read and/or changed by CoAP proxies and 942 thus cannot in general be protected end-to-end between the endpoints. 943 As mentioned in Section 1, OSCORE protects the CoAP Request/Response 944 layer only, and not the Messaging Layer (Section 2 of [RFC7252]), so 945 fields such as Type and Message ID are not protected with OSCORE. 947 The CoAP Header field Code is protected by OSCORE. Code SHALL be 948 encrypted and integrity protected (Class E) to prevent an 949 intermediary from eavesdropping or manipulating the Code (e.g., 950 changing from GET to DELETE). 952 The sending endpoint SHALL write the Code of the original CoAP 953 message into the plaintext of the COSE object (see Section 5.3). 954 After that, the Outer Code of the OSCORE message SHALL be set to 0.02 955 (POST) for requests without Observe option, to 0.05 (FETCH) for 956 requests with Observe option, and to 2.04 (Changed) for responses. 957 Using FETCH with Observe allows OSCORE to be compliant with the 958 Observe processing in OSCORE-unaware proxies. The choice of POST and 959 FETCH ([RFC8132]) allows all OSCORE messages to have payload. 961 The receiving endpoint SHALL discard the Code in the OSCORE message 962 and write the Code of the plaintext in the COSE object (Section 5.3) 963 into the decrypted CoAP message. 965 The other CoAP Header fields are Unprotected (Class U). The sending 966 endpoint SHALL write all other header fields of the original message 967 into the header of the OSCORE message. The receiving endpoint SHALL 968 write the header fields from the received OSCORE message into the 969 header of the decrypted CoAP message. 971 4.4. Signaling Messages 973 Signaling messages (CoAP Code 7.00-7.31) were introduced to exchange 974 information related to an underlying transport connection in the 975 specific case of CoAP over reliable transports 976 ([I-D.ietf-core-coap-tcp-tls]). The use of OSCORE for protecting 977 Signaling is application dependent. 979 OSCORE MAY be used to protect Signaling if the endpoints for OSCORE 980 coincide with the endpoints for the connection. If OSCORE is used to 981 protect Signaling then: 983 o Signaling messages SHALL be protected as CoAP Request messages, 984 except in the case the Signaling message is a response to a 985 previous Signaling message, in which case it SHALL be protected as 986 a CoAP Response message. For example, 7.02 (Ping) is protected as 987 a CoAP Request and 7.03 (Pong) as a CoAP response. 989 o The Outer Code for Signaling messages SHALL be set to 0.02 (POST), 990 unless it is a response to a previous Signaling message, in which 991 case it SHALL be set to 2.04 (Changed). 993 o All Signaling options, except the Object-Security option, SHALL be 994 Inner (Class E). 996 NOTE: Option numbers for Signaling messages are specific to the CoAP 997 Code (see Section 5.2 of [I-D.ietf-core-coap-tcp-tls]). 999 If OSCORE is not used to protect Signaling, Signaling messages SHALL 1000 be unaltered by OSCORE. 1002 5. The COSE Object 1004 This section defines how to use COSE [RFC8152] to wrap and protect 1005 data in the original message. OSCORE uses the untagged COSE_Encrypt0 1006 structure with an Authenticated Encryption with Additional Data 1007 (AEAD) algorithm. The key lengths, IV length, nonce length, and 1008 maximum Sender Sequence Number are algorithm dependent. 1010 The AEAD algorithm AES-CCM-16-64-128 defined in Section 10.2 of 1011 [RFC8152] is mandatory to implement. For AES-CCM-16-64-128 the 1012 length of Sender Key and Recipient Key is 128 bits, the length of 1013 nonce and Common IV is 13 bytes. The maximum Sender Sequence Number 1014 is specified in Section 11. 1016 As specified in [RFC5116], plaintext denotes the data that is 1017 encrypted and integrity protected, and Additional Authenticated Data 1018 (AAD) denotes the data that is integrity protected only. 1020 The COSE Object SHALL be a COSE_Encrypt0 object with fields defined 1021 as follows 1023 o The 'protected' field is empty. 1025 o The 'unprotected' field includes: 1027 * The 'Partial IV' parameter. The value is set to the Sender 1028 Sequence Number. All leading zeroes SHALL be removed when 1029 encoding the Partial IV. The value 0 encodes to the byte 1030 string 0x00. This parameter SHALL be present in requests. In 1031 case of Observe (Section 4.2.3.4) the Partial IV SHALL be 1032 present in responses, and otherwise the Partial IV SHOULD NOT 1033 be present in responses. (A non-Observe example where the 1034 Partial IV is included in a response is provided in 1035 Section 7.5.2.) 1037 * The 'kid' parameter. The value is set to the Sender ID. This 1038 parameter SHALL be present in requests and SHOULD NOT be 1039 present in responses. An example where the Sender ID is 1040 included in a response is the extension of OSCORE to group 1041 communication [I-D.tiloca-core-multicast-oscoap]. 1043 * Optionally, a 'kid context' parameter as defined in 1044 Section 5.1. This parameter MAY be present in requests and 1045 SHALL NOT be present in responses. 1047 o The 'ciphertext' field is computed from the secret key (Sender Key 1048 or Recipient Key), AEAD nonce (see Section 5.2), plaintext (see 1049 Section 5.3), and the Additional Authenticated Data (AAD) (see 1050 Section 5.4) following Section 5.2 of [RFC8152]. 1052 The encryption process is described in Section 5.3 of [RFC8152]. 1054 5.1. Kid Context 1056 For certain use cases, e.g. deployments where the same 'kid' is used 1057 with multiple contexts, it is necessary or favorable for the sender 1058 to provide an additional identifier of the security material to use, 1059 in order for the receiver to retrieve or establish the correct key. 1060 The 'kid context' parameter is used to provide such additional input. 1061 The 'kid context' is implicitly integrity protected, as manipulation 1062 that leads to the wrong key (or no key) being retrieved which results 1063 in an error, as described in Section 8.2. 1065 A summary of the COSE header parameter 'kid context' defined above 1066 can be found in Figure 8. 1068 Some examples of relevant uses of kid context are the following: 1070 o If the client has an identifier in some other namespace which can 1071 be used by the server to retrieve or establish the security 1072 context, then that identifier can be used as kid context. The kid 1073 context may be used as Master Salt (Section 3.1) for additional 1074 entropy of the security contexts (see for example 1075 [I-D.ietf-6tisch-minimal-security]). 1077 o In case of a group communication scenario 1078 [I-D.tiloca-core-multicast-oscoap], if the server belongs to 1079 multiple groups, then a group identifier can be used as kid 1080 context to enable the server to find the right security context. 1082 +----------+--------+------------+----------------+-----------------+ 1083 | name | label | value type | value registry | description | 1084 +----------+--------+------------+----------------+-----------------+ 1085 | kid | kidctx | bstr | | Identifies the | 1086 | context | | | | kid context | 1087 +----------+--------+------------+----------------+-----------------+ 1089 Figure 8: Additional common header parameter for the COSE object 1091 5.2. Nonce 1093 The AEAD nonce is constructed in the following way (see Figure 9): 1095 1. left-padding the Partial IV (in network byte order) with zeroes 1096 to exactly 5 bytes, 1098 2. left-padding the (Sender) ID of the endpoint that generated the 1099 Partial IV (in network byte order) with zeroes to exactly nonce 1100 length - 6 bytes, 1102 3. concatenating the size of the ID (S) with the padded ID and the 1103 padded Partial IV, 1105 4. and then XORing with the Common IV. 1107 Note that in this specification only algorithms that use nonces equal 1108 or greater than 7 bytes are supported. The nonce construction with 1109 S, ID of PIV generator, and Partial IV together with endpoint unique 1110 IDs and encryption keys make it easy to verify that the nonces used 1111 with a specific key will be unique. 1113 When Observe is not used, the request and the response may use the 1114 same nonce. In this way, the Partial IV does not have to be sent in 1115 responses, which reduces the size. For processing instructions (see 1116 Section 8). 1118 +---+-----------------------+--+--+--+--+--+ 1119 | S | ID of PIV generator | Partial IV |----+ 1120 +---+-----------------------+--+--+--+--+--+ | 1121 | 1122 +------------------------------------------+ | 1123 | Common IV |->(XOR) 1124 +------------------------------------------+ | 1125 | 1126 +------------------------------------------+ | 1127 | Nonce |<---+ 1128 +------------------------------------------+ 1130 Figure 9: AEAD Nonce Formation 1132 5.3. Plaintext 1134 The plaintext is formatted as a CoAP message without Header (see 1135 Figure 10) consisting of: 1137 o the Code of the original CoAP message as defined in Section 3 of 1138 [RFC7252]; and 1140 o all Inner option message fields (see Section 4.2.1) present in the 1141 original CoAP message (see Section 4.2). The options are encoded 1142 as described in Section 3.1 of [RFC7252], where the delta is the 1143 difference to the previously included Class E option; and 1145 o the Payload of original CoAP message, if present, and in that case 1146 prefixed by the one-byte Payload Marker (0xFF). 1148 0 1 2 3 1149 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 1150 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1151 | Code | Class E options (if any) ... 1152 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1153 |1 1 1 1 1 1 1 1| Payload (if any) ... 1154 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1155 (only if there 1156 is payload) 1158 Figure 10: Plaintext 1160 NOTE: The plaintext contains all CoAP data that needs to be encrypted 1161 end-to-end between the endpoints. 1163 5.4. Additional Authenticated Data 1165 The external_aad SHALL be a CBOR array as defined below: 1167 external_aad = [ 1168 oscore_version : uint, 1169 [alg_aead : int / tstr], 1170 request_kid : bstr, 1171 request_piv : bstr, 1172 options : bstr 1173 ] 1175 where: 1177 o oscore_version: contains the OSCORE version number. 1178 Implementations of this specification MUST set this field to 1. 1179 Other values are reserved for future versions. 1181 o alg_aead: contains the AEAD Algorithm from the security context 1182 used for the exchange (see Section 3.1). 1184 o request_kid: contains the value of the 'kid' in the COSE object of 1185 the request (see Section 5). 1187 o request_piv: contains the value of the 'Partial IV' in the COSE 1188 object of the request (see Section 5). 1190 o options: contains the Class I options (see Section 4.2.2) present 1191 in the original CoAP message encoded as described in Section 3.1 1192 of [RFC7252], where the delta is the difference to the previously 1193 included class I option. 1195 NOTE: The format of the external_aad is for simplicity the same for 1196 requests and responses, although some parameters, e.g. request_kid 1197 need not be integrity protected in the requests. 1199 6. OSCORE Compression 1201 The Concise Binary Object Representation (CBOR) [RFC7049] combines 1202 very small message sizes with extensibility. The CBOR Object Signing 1203 and Encryption (COSE) [RFC8152] uses CBOR to create compact encoding 1204 of signed and encrypted data. COSE is however constructed to support 1205 a large number of different stateless use cases, and is not fully 1206 optimized for use as a stateful security protocol, leading to a 1207 larger than necessary message expansion. In this section, we define 1208 a stateless compression mechanism, simply removing redundant 1209 information from the COSE objects, which significantly reduces the 1210 per-packet overhead. The result of applying this mechanism to a COSE 1211 object is called the "compressed COSE object". 1213 6.1. Encoding of the Object-Security Value 1215 The value of the Object-Security option SHALL contain the OSCORE flag 1216 bits, the Partial IV parameter, the kid context parameter (length and 1217 value), and the kid parameter as follows: 1219 0 1 2 3 4 5 6 7 <--------- n bytes -------------> 1220 +-+-+-+-+-+-+-+-+--------------------------------- 1221 |0 0 0|h|k| n | Partial IV (if any) ... 1222 +-+-+-+-+-+-+-+-+--------------------------------- 1224 <- 1 byte -> <------ s bytes -----> 1225 +------------+----------------------+------------------+ 1226 | s (if any) | kid context (if any) | kid (if any) ... | 1227 +------------+----------------------+------------------+ 1229 Figure 11: Object-Security Value 1231 o The first byte of flag bits encodes the following set of flags and 1232 the length of the Partial IV parameter: 1234 * The three least significant bits encode the Partial IV length 1235 n. If n = 0 then the Partial IV is not present in the 1236 compressed COSE object. The values n = 6 and n = 7 are 1237 reserved. 1239 * The fourth least significant bit is the kid flag, k: it is set 1240 to 1 if the kid is present in the compressed COSE object. 1242 * The fifth least significant bit is the kid context flag, h: it 1243 is set to 1 if the compressed COSE object contains a kid 1244 context (see Section 5.1). 1246 * The sixth to eighth least significant bits are reserved for 1247 future use. These bits SHALL be set to zero when not in use. 1248 According to this specification, if any of these bits are set 1249 to 1 the message is considered to be malformed and 1250 decompression fails as specified in item 3 of Section 8.2. 1252 o The following n bytes encode the value of the Partial IV, if the 1253 Partial IV is present (n > 0). 1255 o The following 1 byte encode the length of the kid context 1256 (Section 5.1) s, if the kid context flag is set (h = 1). 1258 o The following s bytes encode the kid context, if the kid context 1259 flag is set (h = 1). 1261 o The remaining bytes encode the value of the kid, if the kid is 1262 present (k = 1). 1264 Note that the kid MUST be the last field of the object-security 1265 value, even in case reserved bits are used and additional fields are 1266 added to it. 1268 The length of the Object-Security option thus depends on the presence 1269 and length of Partial IV, kid context, kid, as specified in this 1270 section, and on the presence and length of the other parameters, as 1271 defined in the separate documents. 1273 6.2. Encoding of the OSCORE Payload 1275 The payload of the OSCORE message SHALL encode the ciphertext of the 1276 COSE object. 1278 6.3. Examples of Compressed COSE Objects 1280 6.3.1. Examples: Requests 1282 1. Request with kid = 25 and Partial IV = 5 1284 Before compression (24 bytes): 1286 [ 1287 h'', 1288 { 4:h'25', 6:h'05' }, 1289 h'aea0155667924dff8a24e4cb35b9' 1290 ] 1292 After compression (17 bytes): 1294 Flag byte: 0b00001001 = 0x09 1296 Option Value: 09 05 25 (3 bytes) 1298 Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) 1300 1. Request with kid = empty string and Partial IV = 0 1302 After compression (16 bytes): 1304 Flag byte: 0b00001001 = 0x09 1306 Option Value: 09 00 (2 bytes) 1308 Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) 1310 1. Request with kid = empty string, Partial IV = 5, and kid context 1311 = 0x44616c656b 1313 After compression (22 bytes): 1315 Flag byte: 0b00011001 = 0x19 1317 Option Value: 19 05 05 44 61 6c 65 6b (8 bytes) 1319 Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) 1321 6.3.2. Example: Response (without Observe) 1323 Before compression (18 bytes): 1325 [ 1326 h'', 1327 {}, 1328 h'aea0155667924dff8a24e4cb35b9' 1329 ] 1331 After compression (14 bytes): 1333 Flag byte: 0b00000000 = 0x00 1335 Option Value: (0 bytes) 1337 Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) 1339 6.3.3. Example: Response (with Observe) 1341 Before compression (21 bytes): 1343 [ 1344 h'', 1345 { 6:h'07' }, 1346 h'aea0155667924dff8a24e4cb35b9' 1347 ] 1349 After compression (16 bytes): 1351 Flag byte: 0b00000001 = 0x01 1353 Option Value: 01 07 (2 bytes) 1355 Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) 1357 7. Sequence Numbers, Replay, Message Binding, and Freshness 1359 7.1. Message Binding 1361 In order to prevent response delay and mismatch attacks 1362 [I-D.mattsson-core-coap-actuators] from on-path attackers and 1363 compromised proxies, OSCORE binds responses to the requests by 1364 including the kid and Partial IV of the request in the AAD of the 1365 response. The server therefore needs to store the kid and Partial IV 1366 of the request until all responses have been sent. 1368 7.2. AEAD Nonce Uniqueness 1370 An AEAD nonce MUST NOT be used more than once per AEAD key. In order 1371 to assure unique nonces, each Sender Context contains a Sender 1372 Sequence Number used to protect requests, and - in case of Observe - 1373 responses. If messages are processed concurrently, the operation of 1374 reading and increasing the Sender Sequence Number MUST be atomic. 1376 The maximum Sender Sequence Number is algorithm dependent (see 1377 Section 11), and no greater than 2^40 - 1. If the Sender Sequence 1378 Number exceeds the maximum, the endpoint MUST NOT process any more 1379 messages with the given Sender Context. The endpoint SHOULD acquire 1380 a new security context (and consequently inform the other endpoint) 1381 before this happens. The latter is out of scope of this document. 1383 7.3. Freshness 1385 For requests, OSCORE provides weak absolute freshness as the only 1386 guarantee is that the request is not older than the security context. 1387 For applications having stronger demands on request freshness (e.g., 1388 control of actuators), OSCORE needs to be augmented with mechanisms 1389 providing freshness, for example as specified in 1390 [I-D.ietf-core-echo-request-tag]. 1392 For responses, the message binding guarantees that a response is not 1393 older than its request. For responses without Observe, this gives 1394 strong absolute freshness. For responses with Observe, the absolute 1395 freshness gets weaker with time, and it is RECOMMENDED that the 1396 client regularly re-register the observation. 1398 For requests, and responses with Observe, OSCORE also provides 1399 relative freshness in the sense that the received Partial IV allows a 1400 recipient to determine the relative order of responses. 1402 7.4. Replay Protection 1404 In order to protect from replay of requests, the server's Recipient 1405 Context includes a Replay Window. A server SHALL verify that a 1406 Partial IV received in the COSE object has not been received before. 1407 If this verification fails the server SHALL stop processing the 1408 message, and MAY optionally respond with a 4.01 Unauthorized error 1409 message. Also, the server MAY set an Outer Max-Age option with value 1410 zero. The diagnostic payload MAY contain the "Replay protection 1411 failed" string. The size and type of the Replay Window depends on 1412 the use case and the protocol with which the OSCORE message is 1413 transported. In case of reliable and ordered transport from endpoint 1414 to endpoint, e.g. TCP, the server MAY just store the last received 1415 Partial IV and require that newly received Partial IVs equals the 1416 last received Partial IV + 1. However, in case of mixed reliable and 1417 unreliable transports and where messages may be lost, such a replay 1418 mechanism may be too restrictive and the default replay window be 1419 more suitable (see Section 3.2.2). 1421 Responses to non-Observe requests are protected against replay as 1422 they are cryptographically bound to the request. 1424 In the case of Observe, a client receiving a notification SHALL 1425 verify that the Partial IV of a received notification is greater than 1426 the Notification Number bound to that Observe registration. If the 1427 verification fails, the client SHALL stop processing the response. 1428 If the verification succeeds, the client SHALL overwrite the 1429 corresponding Notification Number with the received Partial IV. 1431 If messages are processed concurrently, the Partial IV needs to be 1432 validated a second time after decryption and before updating the 1433 replay protection data. The operation of validating the Partial IV 1434 and updating the replay protection data MUST be atomic. 1436 7.5. Losing Part of the Context State 1438 To prevent reuse of the AEAD nonce with the same key, or from 1439 accepting replayed messages, an endpoint needs to handle the 1440 situation of losing rapidly changing parts of the context, such as 1441 the request Token, Sender Sequence Number, Replay Window, and 1442 Notification Numbers. These are typically stored in RAM and 1443 therefore lost in the case of an unplanned reboot. 1445 After boot, an endpoint MAY reject to use existing security contexts 1446 from before it booted and MAY establish a new security context with 1447 each party it communicates. However, establishing a fresh security 1448 context may have a non-negligible cost in terms of, e.g., power 1449 consumption. 1451 After boot, an endpoint MAY use a partly persistently stored security 1452 context, but then the endpoint MUST NOT reuse a previous Sender 1453 Sequence Number and MUST NOT accept previously accepted messages. 1454 Some ways to achieve this is described below: 1456 7.5.1. Sequence Number 1458 To prevent reuse of Sender Sequence Numbers, an endpoint MAY perform 1459 the following procedure during normal operations: 1461 o Each time the Sender Sequence Number is evenly divisible by K, 1462 where K is a positive integer, store the Sender Sequence Number in 1463 persistent memory. After boot, the endpoint initiates the Sender 1464 Sequence Number to the value stored in persistent memory + K - 1. 1465 Storing to persistent memory can be costly. The value K gives a 1466 trade-off between the number of storage operations and efficient 1467 use of Sender Sequence Numbers. 1469 7.5.2. Replay Window 1471 To prevent accepting replay of previously received requests, the 1472 server MAY perform the following procedure after boot: 1474 o For each stored security context, the first time after boot the 1475 server receives an OSCORE request, the server responds with the 1476 Echo option [I-D.ietf-core-echo-request-tag] to get a request with 1477 verifiable freshness. The server MUST use its Partial IV when 1478 generating the AEAD nonce and MUST include the Partial IV in the 1479 response. 1481 If the server using the Echo option can verify a second request as 1482 fresh, then the Partial IV of the second request is set as the lower 1483 limit of the replay window. 1485 7.5.3. Replay Protection of Observe Notifications 1487 To prevent accepting replay of previously received notification 1488 responses, the client MAY perform the following procedure after boot: 1490 o The client rejects notifications bound to the earlier 1491 registration, removes all Notification Numbers and re-registers 1492 using Observe. 1494 8. Processing 1496 This section describes the OSCORE message processing. 1498 8.1. Protecting the Request 1500 Given a CoAP request, the client SHALL perform the following steps to 1501 create an OSCORE request: 1503 1. Retrieve the Sender Context associated with the target resource. 1505 2. Compose the Additional Authenticated Data and the plaintext, as 1506 described in Section 5.4 and Section 5.3. 1508 3. Compute the AEAD nonce from the Sender ID, Common IV, and Partial 1509 IV (Sender Sequence Number in network byte order) as described in 1510 Section 5.2 and (in one atomic operation, see Section 7.2) 1511 increment the Sender Sequence Number by one. 1513 4. Encrypt the COSE object using the Sender Key. Compress the COSE 1514 Object as specified in Section 6. 1516 5. Format the OSCORE message according to Section 4. The Object- 1517 Security option is added (see Section 4.2.2). 1519 6. Store the association Token - Security Context. The client SHALL 1520 be able to find the Recipient Context from the Token in the 1521 response. 1523 8.2. Verifying the Request 1525 A server receiving a request containing the Object-Security option 1526 SHALL perform the following steps: 1528 1. Process Outer Block options according to [RFC7959], until all 1529 blocks of the request have been received (see Section 4.2.3.2). 1531 2. Discard the message Code and all non-special Inner option 1532 message fields (marked with 'x' in column E of Figure 6) present 1533 in the received message. For example, an If-Match Outer option 1534 is discarded, but an Uri-Host Outer option is not discarded. 1536 3. Decompress the COSE Object (Section 6) and retrieve the 1537 Recipient Context associated with the Recipient ID in the 'kid' 1538 parameter. If either the decompression or the COSE message 1539 fails to decode, or the server fails to retrieve a Recipient 1540 Context with Recipient ID corresponding to the 'kid' parameter 1541 received, then the server SHALL stop processing the request. 1542 If: 1544 * either the decompression or the COSE message fails to decode, 1545 the server MAY respond with a 4.02 Bad Option error message. 1546 The server MAY set an Outer Max-Age option with value zero. 1547 The diagnostic payload SHOULD contain the string "Failed to 1548 decode COSE". 1550 * the server fails to retrieve a Recipient Context with 1551 Recipient ID corresponding to the 'kid' parameter received, 1552 the server MAY respond with a 4.01 Unauthorized error 1553 message. The server MAY set an Outer Max-Age option with 1554 value zero. The diagnostic payload SHOULD contain the string 1555 "Security context not found". 1557 4. Verify the 'Partial IV' parameter using the Replay Window, as 1558 described in Section 7.4. 1560 5. Compose the Additional Authenticated Data, as described in 1561 Section 5.4. 1563 6. Compute the AEAD nonce from the Recipient ID, Common IV, and the 1564 'Partial IV' parameter, received in the COSE Object. 1566 7. Decrypt the COSE object using the Recipient Key. 1568 * If decryption fails, the server MUST stop processing the 1569 request and MAY respond with a 4.00 Bad Request error 1570 message. The server MAY set an Outer Max-Age option with 1571 value zero. The diagnostic payload SHOULD contain the 1572 "Decryption failed" string. 1574 * If decryption succeeds, update the Replay Window, as 1575 described in Section 7. 1577 8. For each decrypted option, check if the option is also present 1578 as an Outer option: if it is, discard the Outer. For example: 1579 the message contains a Max-Age Inner and a Max-Age Outer option. 1580 The Outer Max-Age is discarded. 1582 9. Add decrypted code, options and payload to the decrypted 1583 request. The Object-Security option is removed. 1585 10. The decrypted CoAP request is processed according to [RFC7252] 1587 8.3. Protecting the Response 1589 If a CoAP response is generated in response to an OSCORE request, the 1590 server SHALL perform the following steps to create an OSCORE 1591 response. Note that CoAP error responses derived from CoAP 1592 processing (point 10. in Section 8.2) are protected, as well as 1593 successful CoAP responses, while the OSCORE errors (point 3, 4, and 7 1594 in Section 8.2) do not follow the processing below, but are sent as 1595 simple CoAP responses, without OSCORE processing. 1597 1. Retrieve the Sender Context in the Security Context used to 1598 verify the request. 1600 2. Compose the Additional Authenticated Data and the plaintext, as 1601 described in Section 5.4 and Section 5.3. 1603 3. Compute the AEAD nonce 1605 * If Observe is used, compute the nonce from the Sender ID, 1606 Common IV, and Partial IV (Sender Sequence Number in network 1607 byte order). Then (in one atomic operation, see Section 7.2) 1608 increment the Sender Sequence Number by one. 1610 * If Observe is not used, either the nonce from the request is 1611 used or a new Partial IV is used. 1613 4. Encrypt the COSE object using the Sender Key. Compress the COSE 1614 Object as specified in Section 6. If the AEAD nonce was 1615 constructed from a new Partial IV, this Partial IV MUST be 1616 included in the message. If the AEAD nonce from the request was 1617 used, the Partial IV MUST NOT be included in the message. 1619 5. Format the OSCORE message according to Section 4. The Object- 1620 Security option is added (see Section 4.2.2). 1622 8.4. Verifying the Response 1624 A client receiving a response containing the Object-Security option 1625 SHALL perform the following steps: 1627 1. Process Outer Block options according to [RFC7959], until all 1628 blocks of the OSCORE message have been received (see 1629 Section 4.2.3.2). 1631 2. Discard the message Code and all non-special Class E options 1632 from the message. For example, ETag Outer option is discarded, 1633 Max-Age Outer option is not discarded. 1635 3. Retrieve the Recipient Context associated with the Token. 1636 Decompress the COSE Object (Section 6). If either the 1637 decompression or the COSE message fails to decode, then go to 1638 11. 1640 4. For Observe notifications, verify the received 'Partial IV' 1641 parameter against the corresponding Notification Number as 1642 described in Section 7.4. If the client receives a notification 1643 for which no Observe request was sent, then go to 11. 1645 5. Compose the Additional Authenticated Data, as described in 1646 Section 5.4. 1648 6. Compute the AEAD nonce 1650 1. If the Observe option and the Partial IV are not present in 1651 the response, the nonce from the request is used. 1653 2. If the Observe option is present in the response, and the 1654 Partial IV is not present in the response, then go to 11. 1656 3. If the Partial IV is present in the response, compute the 1657 nonce from the Recipient ID, Common IV, and the 'Partial IV' 1658 parameter, received in the COSE Object. 1660 7. Decrypt the COSE object using the Recipient Key. 1662 * If decryption fails, then go to 11. 1664 * If decryption succeeds and Observe is used, update the 1665 corresponding Notification Number, as described in Section 7. 1667 8. For each decrypted option, check if the option is also present 1668 as an Outer option: if it is, discard the Outer. For example: 1669 the message contains a Max-Age Inner and a Max-Age Outer option. 1670 The Outer Max-Age is discarded. 1672 9. Add decrypted code, options and payload to the decrypted 1673 request. The Object-Security option is removed. 1675 10. The decrypted CoAP response is processed according to [RFC7252] 1677 11. (Optional) In case any of the previous erroneous conditions 1678 apply: the client SHALL stop processing the response. 1680 An error condition occurring while processing a response in an 1681 observation does not cancel the observation. A client MUST NOT react 1682 to failure in step 7 by re-registering the observation immediately. 1684 9. Web Linking 1686 The use of OSCORE MAY be indicated by a target attribute "osc" in a 1687 web link [RFC8288] to a resource. This attribute is a hint 1688 indicating that the destination of that link is to be accessed using 1689 OSCORE. Note that this is simply a hint, it does not include any 1690 security context material or any other information required to run 1691 OSCORE. 1693 A value MUST NOT be given for the "osc" attribute; any present value 1694 MUST be ignored by parsers. The "osc" attribute MUST NOT appear more 1695 than once in a given link-value; occurrences after the first MUST be 1696 ignored by parsers. 1698 10. Proxy and HTTP Operations 1700 RFC 7252 defines operations for a CoAP-to-CoAP proxy (see Section 5.7 1701 of [RFC7252]) and for proxying between CoAP and HTTP (Section 10 of 1702 [RFC7252]). A more detailed description of the HTTP-to-CoAP mapping 1703 is provided by [RFC8075]. This section describes the operations of 1704 OSCORE-aware proxies. 1706 10.1. CoAP-to-CoAP Forwarding Proxy 1708 OSCORE is designed to work with legacy CoAP-to-CoAP forward proxies 1709 [RFC7252], but OSCORE-aware proxies MAY provide certain 1710 simplifications as specified in this section. 1712 Security requirements for forwarding are presented in Section 2.2.1 1713 of [I-D.hartke-core-e2e-security-reqs]. OSCORE complies with the 1714 extended security requirements also addressing Blockwise ([RFC7959]) 1715 and CoAP-mappable HTTP. In particular caching is disabled since the 1716 CoAP response is only applicable to the original CoAP request. An 1717 OSCORE-aware proxy SHALL NOT cache a response to a request with an 1718 Object-Security option. As a consequence, the search for cache hits 1719 and CoAP freshness/Max-Age processing can be omitted. 1721 Proxy processing of the (Outer) Proxy-Uri option is as defined in 1722 [RFC7252]. 1724 Proxy processing of the (Outer) Block options is as defined in 1725 [RFC7959] and [I-D.ietf-core-echo-request-tag]. 1727 Proxy processing of the (Outer) Observe option is as defined in 1728 [RFC7641]. OSCORE-aware proxies MAY look at the Partial IV value 1729 instead of the Outer Observe option. 1731 10.2. HTTP Processing 1733 In order to use OSCORE with HTTP, an endpoint needs to be able to map 1734 HTTP messages to CoAP messages (see [RFC8075]), and to apply OSCORE 1735 to CoAP messages (as defined in this document). 1737 A sending endpoint uses [RFC8075] to translate an HTTP message into a 1738 CoAP message. It then protects the message with OSCORE processing, 1739 and add the Object-Security option (as defined in this document). 1740 Then, the endpoint maps the resulting CoAP message to an HTTP message 1741 that includes an HTTP header field named Object-Security, whose value 1742 is: 1744 o "" (empty string) if the CoAP Object-Security option is empty, or 1746 o the value of the CoAP Object-Security option (Section 6.1) in 1747 base64url encoding (Section 5 of [RFC4648]) without padding (see 1748 [RFC7515] Appendix C for implementation notes for this encoding). 1750 Note that the value of the HTTP body is the CoAP payload, i.e. the 1751 OSCORE payload (Section 6.2). 1753 The resulting message is an OSCORE message that uses HTTP. 1755 A receiving endpoint uses [RFC8075] to translate an HTTP message into 1756 a CoAP message, with the following addition. The HTTP message 1757 includes the Object-Security header field, which is mapped to the 1758 CoAP Object-Security option in the following way. The CoAP Object- 1759 Security option value is: 1761 o empty if the value of the HTTP Object-Security header field is "" 1762 (empty string) 1764 o the value of the HTTP Object-Security header field decoded from 1765 base64url (Section 5 of [RFC4648]) without padding (see [RFC7515] 1766 Appendix C for implementation notes for this decoding). 1768 Note that the value of the CoAP payload is the HTTP body, i.e. the 1769 OSCORE payload (Section 6.2). 1771 The resulting message is an OSCORE message that uses CoAP. 1773 The endpoint can then verify the message according to the OSCORE 1774 processing and get a verified CoAP message. It can then translate 1775 the verified CoAP message into a verified HTTP message. 1777 10.3. HTTP-to-CoAP Translation Proxy 1779 Section 10.2 of [RFC7252] and [RFC8075] specify the behavior of an 1780 HTTP-to-CoAP proxy. As requested in Section 1 of [RFC8075], this 1781 section describes the HTTP mapping for the OSCORE protocol extension 1782 of CoAP. 1784 The presence of the Object-Security option, both in requests and 1785 responses, is expressed in an HTTP header field named Object-Security 1786 in the mapped request or response. The value of the field is: 1788 o "" (empty string) if the CoAP Object-Security option is empty, or 1790 o the value of the CoAP Object-Security option (Section 6.1) in 1791 base64url encoding (Section 5 of [RFC4648]) without padding (see 1792 [RFC7515] Appendix C for implementation notes for this encoding). 1794 The value of the body is the OSCORE payload (Section 6.2). 1796 Example: 1798 Mapping and notation here is based on "Simple Form" (Section 5.4.1.1 1799 of [RFC8075]). 1801 [HTTP request -- Before client object security processing] 1803 GET http://proxy.url/hc/?target_uri=coap://server.url/orders HTTP/1.1 1805 [HTTP request -- HTTP Client to Proxy] 1807 POST http://proxy.url/hc/?target_uri=coap://server.url/ HTTP/1.1 1808 Object-Security: 09 25 1809 Body: 09 07 01 13 61 f7 0f d2 97 b1 [binary] 1811 [CoAP request -- Proxy to CoAP Server] 1813 POST coap://server.url/ 1814 Object-Security: 09 25 1815 Payload: 09 07 01 13 61 f7 0f d2 97 b1 [binary] 1817 [CoAP request -- After server object security processing] 1819 GET coap://server.url/orders 1821 [CoAP response -- Before server object security processing] 1823 2.05 Content 1824 Content-Format: 0 1825 Payload: Exterminate! Exterminate! 1827 [CoAP response -- CoAP Server to Proxy] 1829 2.04 Changed 1830 Object-Security: [empty] 1831 Payload: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] 1833 [HTTP response -- Proxy to HTTP Client] 1835 HTTP/1.1 200 OK 1836 Object-Security: "" (empty string) 1837 Body: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] 1839 [HTTP response -- After client object security processing] 1841 HTTP/1.1 200 OK 1842 Content-Type: text/plain 1843 Body: Exterminate! Exterminate! 1845 Note that the HTTP Status Code 200 in the next-to-last message is the 1846 mapping of CoAP Code 2.04 (Changed), whereas the HTTP Status Code 200 1847 in the last message is the mapping of the CoAP Code 2.05 (Content), 1848 which was encrypted within the compressed COSE object carried in the 1849 Body of the HTTP response. 1851 10.4. CoAP-to-HTTP Translation Proxy 1853 Section 10.1 of [RFC7252] describes the behavior of a CoAP-to-HTTP 1854 proxy. RFC 8075 [RFC8075] does not cover this direction in any more 1855 detail and so an example instantiation of Section 10.1 of [RFC7252] 1856 is used below. 1858 Example: 1860 [CoAP request -- Before client object security processing] 1862 GET coap://proxy.url/ 1863 Proxy-Uri=http://server.url/orders 1865 [CoAP request -- CoAP Client to Proxy] 1867 POST coap://proxy.url/ 1868 Proxy-Uri=http://server.url/ 1869 Object-Security: 09 25 1870 Payload: 09 07 01 13 61 f7 0f d2 97 b1 [binary] 1872 [HTTP request -- Proxy to HTTP Server] 1874 POST http://server.url/ HTTP/1.1 1875 Object-Security: 09 25 1876 Body: 09 07 01 13 61 f7 0f d2 97 b1 [binary] 1878 [HTTP request -- After server object security processing] 1880 GET http://server.url/orders HTTP/1.1 1882 [HTTP response -- Before server object security processing] 1884 HTTP/1.1 200 OK 1885 Content-Type: text/plain 1886 Body: Exterminate! Exterminate! 1888 [HTTP response -- HTTP Server to Proxy] 1890 HTTP/1.1 200 OK 1891 Object-Security: "" (empty string) 1892 Body: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] 1894 [CoAP response - Proxy to CoAP Client] 1896 2.04 Changed 1897 Object-Security: [empty] 1898 Payload: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] 1900 [CoAP response -- After client object security processing] 1902 2.05 Content 1903 Content-Format: 0 1904 Payload: Exterminate! Exterminate! 1906 Note that the HTTP Code 2.04 (Changed) in the next-to-last message is 1907 the mapping of HTTP Status Code 200, whereas the CoAP Code 2.05 1908 (Content) in the last message is the value that was encrypted within 1909 the compressed COSE object carried in the Body of the HTTP response. 1911 11. Security Considerations 1913 11.1. End-to-end protection 1915 In scenarios with intermediary nodes such as proxies or gateways, 1916 transport layer security such as (D)TLS only protects data hop-by- 1917 hop. As a consequence, the intermediary nodes can read and modify 1918 information. The trust model where all intermediary nodes are 1919 considered trustworthy is problematic, not only from a privacy 1920 perspective, but also from a security perspective, as the 1921 intermediaries are free to delete resources on sensors and falsify 1922 commands to actuators (such as "unlock door", "start fire alarm", 1923 "raise bridge"). Even in the rare cases, where all the owners of the 1924 intermediary nodes are fully trusted, attacks and data breaches make 1925 such an architecture brittle. 1927 (D)TLS protects hop-by-hop the entire message. OSCORE protects end- 1928 to-end all information that is not required for proxy operations (see 1929 Section 4). (D)TLS and OSCORE can be combined, thereby enabling end- 1930 to-end security of the message payload, in combination with hop-by- 1931 hop protection of the entire message, during transport between end- 1932 point and intermediary node. The CoAP messaging layer, including 1933 header fields such as Type and Message ID, as well as CoAP message 1934 fields Token and Token Length may be changed by a proxy and thus 1935 cannot be protected end-to-end. Error messages occurring during CoAP 1936 processing are protected end-to-end. Error messages occurring during 1937 OSCORE processing are not always possible to protect, e.g. if the 1938 receiving endpoint cannot locate the right security context. It may 1939 still be favorable to send an unprotected error message, e.g. to 1940 prevent extensive retransmissions, so unprotected error messages are 1941 allowed as specified. Similar to error messages, signaling messages 1942 are not always possible to protect as they may be intended for an 1943 intermediary. Hop-by-hop protection of signaling messages can be 1944 achieved with (D)TLS. Applications using unprotected error and 1945 signaling messages need to consider the threat that these messages 1946 may be spoofed. 1948 11.2. Security Context Establishment 1950 The use of COSE to protect messages as specified in this document 1951 requires an established security context. The method to establish 1952 the security context described in Section 3.2 is based on a common 1953 shared secret material in client and server, which may be obtained, 1954 e.g., by using the ACE framework [I-D.ietf-ace-oauth-authz]. An 1955 OSCORE profile of ACE is described in [I-D.ietf-ace-oscore-profile]. 1957 11.3. Replay Protection 1959 Most AEAD algorithms require a unique nonce for each message, for 1960 which the sender sequence numbers in the COSE message field 'Partial 1961 IV' is used. If the recipient accepts any sequence number larger 1962 than the one previously received, then the problem of sequence number 1963 synchronization is avoided. With reliable transport, it may be 1964 defined that only messages with sequence number which are equal to 1965 previous sequence number + 1 are accepted. The alternatives to 1966 sequence numbers have their issues: very constrained devices may not 1967 be able to support accurate time, or to generate and store large 1968 numbers of random nonces. The requirement to change key at counter 1969 wrap is a complication, but it also forces the user of this 1970 specification to think about implementing key renewal. 1972 11.4. Cryptographic Considerations 1974 The maximum sender sequence number is dependent on the AEAD 1975 algorithm. The maximum sender sequence number SHALL be 2^40 - 1, or 1976 any algorithm specific lower limit, after which a new security 1977 context must be generated. The mechanism to build the nonce 1978 (Section 5.2) assumes that the nonce is at least 56 bit-long, and the 1979 Partial IV is at most 40 bit-long. The mandatory-to-implement AEAD 1980 algorithm AES-CCM-16-64-128 is selected for compatibility with CCM*. 1982 The security level of a system with m Masters Keys of length k used 1983 together with Master Salts with entropy n is k + n - log2(m). 1984 Similarly, the security level of a system with m AEAD keys of length 1985 k used together with AEAD nonces of length n is k + n - log2(m). 1986 Security level here means that an attacker can recover one of the m 1987 keys with complexity 2^(k + n) / m. Protection against such attacks 1988 can be provided by increasing the size of the keys or the entropy of 1989 the Master Salt. The complexity of recovering a specific key is 1990 still 2^k (assuming the Master Salt/AEAD nonce is public). The 1991 Master Secret, Sender Key, and Recipient Key MUST be secret, the rest 1992 of the parameters MAY be public. The Master Secret MUST be uniformly 1993 random. 1995 11.5. Message Fragmentation 1997 The Inner Block options enable the sender to split large messages 1998 into OSCORE-protected blocks such that the receiving endpoint can 1999 verify blocks before having received the complete message. The Outer 2000 Block options allow for arbitrary proxy fragmentation operations that 2001 cannot be verified by the endpoints, but can by policy be restricted 2002 in size since the Inner Block options allow for secure fragmentation 2003 of very large messages. A maximum message size (above which the 2004 sending endpoint fragments the message and the receiving endpoint 2005 discards the message, if complying to the policy) may be obtained as 2006 part of normal resource discovery. 2008 11.6. Privacy Considerations 2010 Privacy threats executed through intermediary nodes are considerably 2011 reduced by means of OSCORE. End-to-end integrity protection and 2012 encryption of the message payload and all options that are not used 2013 for proxy operations, provide mitigation against attacks on sensor 2014 and actuator communication, which may have a direct impact on the 2015 personal sphere. 2017 The unprotected options (Figure 6) may reveal privacy sensitive 2018 information. In particular Uri-Host SHOULD NOT contain privacy 2019 sensitive information. CoAP headers sent in plaintext allow, for 2020 example, matching of CON and ACK (CoAP Message Identifier), matching 2021 of request and responses (Token) and traffic analysis. 2023 Unprotected error messages reveal information about the security 2024 state in the communication between the endpoints. Unprotected 2025 signalling messages reveal information about the reliable transport 2026 used on a leg of the path. Using the mechanisms described in 2027 Section 7.5 may reveal when a device goes through a reboot. This can 2028 be mitigated by the device storing the precise state of sender 2029 sequence number and replay window on a clean shutdown. 2031 The length of message fields can reveal information about the 2032 message. Applications may use a padding scheme to protect against 2033 traffic analysis. As an example, the strings "YES" and "NO" even if 2034 encrypted can be distinguished from each other as there is no padding 2035 supplied by the current set of encryption algorithms. Some 2036 information can be determined even from looking at boundary 2037 conditions. An example of this would be returning an integer between 2038 0 and 100 where lengths of 1, 2 and 3 will provide information about 2039 where in the range things are. Three different methods to deal with 2040 this are: 1) ensure that all messages are the same length. For 2041 example, using 0 and 1 instead of "yes" and "no". 2) Use a character 2042 which is not part of the responses to pad to a fixed length. For 2043 example, pad with a space to three characters. 3) Use the PKCS #7 2044 style padding scheme where m bytes are appended each having the value 2045 of m. For example, appending a 0 to "YES" and two 1's to "NO". This 2046 style of padding means that all values need to be padded. Similar 2047 arguments apply to other message fields such as resource names. 2049 12. IANA Considerations 2051 Note to RFC Editor: Please replace all occurrences of "[[this 2052 document]]" with the RFC number of this specification. 2054 Note to IANA: Please note all occurrences of "TBD" in this 2055 specification should be assigned the same number. 2057 12.1. COSE Header Parameters Registry 2059 The 'kid context' parameter is added to the "COSE Header Parameters 2060 Registry": 2062 o Name: kid context 2064 o Label: kidctx 2066 o Value Type: bstr 2068 o Value Registry: 2070 o Description: kid context 2072 o Reference: Section 5.1 of this document 2074 12.2. CoAP Option Numbers Registry 2076 The Object-Security option is added to the CoAP Option Numbers 2077 registry: 2079 +--------+-----------------+-------------------+ 2080 | Number | Name | Reference | 2081 +--------+-----------------+-------------------+ 2082 | TBD | Object-Security | [[this document]] | 2083 +--------+-----------------+-------------------+ 2085 12.3. CoAP Signaling Option Numbers Registry 2087 The Object-Security option is added to the CoAP Signaling Option 2088 Numbers registry: 2090 +------------+--------+---------------------+-------------------+ 2091 | Applies to | Number | Name | Reference | 2092 +------------+--------+---------------------+-------------------+ 2093 | 7.xx | TBD | Object-Security | [[this document]] | 2094 +------------+--------+---------------------+-------------------+ 2096 12.4. Header Field Registrations 2098 The HTTP header field Object-Security is added to the Message Headers 2099 registry: 2101 +-------------------+----------+----------+-------------------+ 2102 | Header Field Name | Protocol | Status | Reference | 2103 +-------------------+----------+----------+-------------------+ 2104 | Object-Security | http | standard | [[this document]] | 2105 +-------------------+----------+----------+-------------------+ 2107 13. References 2109 13.1. Normative References 2111 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2112 Requirement Levels", BCP 14, RFC 2119, 2113 DOI 10.17487/RFC2119, March 1997, 2114 . 2116 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 2117 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 2118 . 2120 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 2121 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 2122 January 2012, . 2124 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 2125 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 2126 October 2013, . 2128 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 2129 Application Protocol (CoAP)", RFC 7252, 2130 DOI 10.17487/RFC7252, June 2014, 2131 . 2133 [RFC7641] Hartke, K., "Observing Resources in the Constrained 2134 Application Protocol (CoAP)", RFC 7641, 2135 DOI 10.17487/RFC7641, September 2015, 2136 . 2138 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 2139 the Constrained Application Protocol (CoAP)", RFC 7959, 2140 DOI 10.17487/RFC7959, August 2016, 2141 . 2143 [RFC8075] Castellani, A., Loreto, S., Rahman, A., Fossati, T., and 2144 E. Dijk, "Guidelines for Mapping Implementations: HTTP to 2145 the Constrained Application Protocol (CoAP)", RFC 8075, 2146 DOI 10.17487/RFC8075, February 2017, 2147 . 2149 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 2150 FETCH Methods for the Constrained Application Protocol 2151 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 2152 . 2154 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 2155 RFC 8152, DOI 10.17487/RFC8152, July 2017, 2156 . 2158 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 2159 DOI 10.17487/RFC8288, October 2017, 2160 . 2162 13.2. Informative References 2164 [I-D.bormann-6lo-coap-802-15-ie] 2165 Bormann, C., "Constrained Application Protocol (CoAP) over 2166 IEEE 802.15.4 Information Element for IETF", draft- 2167 bormann-6lo-coap-802-15-ie-00 (work in progress), April 2168 2016. 2170 [I-D.hartke-core-e2e-security-reqs] 2171 Selander, G., Palombini, F., and K. Hartke, "Requirements 2172 for CoAP End-To-End Security", draft-hartke-core-e2e- 2173 security-reqs-03 (work in progress), July 2017. 2175 [I-D.ietf-6tisch-minimal-security] 2176 Vucinic, M., Simon, J., Pister, K., and M. Richardson, 2177 "Minimal Security Framework for 6TiSCH", draft-ietf- 2178 6tisch-minimal-security-04 (work in progress), October 2179 2017. 2181 [I-D.ietf-ace-oauth-authz] 2182 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 2183 H. Tschofenig, "Authentication and Authorization for 2184 Constrained Environments (ACE)", draft-ietf-ace-oauth- 2185 authz-09 (work in progress), November 2017. 2187 [I-D.ietf-ace-oscore-profile] 2188 Seitz, L., Palombini, F., and M. Gunnarsson, "OSCORE 2189 profile of the Authentication and Authorization for 2190 Constrained Environments Framework", draft-ietf-ace- 2191 oscore-profile-00 (work in progress), December 2017. 2193 [I-D.ietf-cbor-cddl] 2194 Birkholz, H., Vigano, C., and C. Bormann, "Concise data 2195 definition language (CDDL): a notational convention to 2196 express CBOR data structures", draft-ietf-cbor-cddl-00 2197 (work in progress), July 2017. 2199 [I-D.ietf-core-coap-tcp-tls] 2200 Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 2201 Silverajan, B., and B. Raymor, "CoAP (Constrained 2202 Application Protocol) over TCP, TLS, and WebSockets", 2203 draft-ietf-core-coap-tcp-tls-11 (work in progress), 2204 December 2017. 2206 [I-D.ietf-core-echo-request-tag] 2207 Amsuess, C., Mattsson, J., and G. Selander, "Echo and 2208 Request-Tag", draft-ietf-core-echo-request-tag-00 (work in 2209 progress), October 2017. 2211 [I-D.mattsson-ace-tls-oscore] 2212 Mattsson, J., "Using Transport Layer Security (TLS) to 2213 Secure OSCORE", draft-mattsson-ace-tls-oscore-00 (work in 2214 progress), October 2017. 2216 [I-D.mattsson-core-coap-actuators] 2217 Mattsson, J., Fornehed, J., Selander, G., Palombini, F., 2218 and C. Amsuess, "Controlling Actuators with CoAP", draft- 2219 mattsson-core-coap-actuators-03 (work in progress), 2220 October 2017. 2222 [I-D.tiloca-core-multicast-oscoap] 2223 Tiloca, M., Selander, G., Palombini, F., and J. Park, 2224 "Secure group communication for CoAP", draft-tiloca-core- 2225 multicast-oscoap-04 (work in progress), October 2017. 2227 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2228 Resource Identifier (URI): Generic Syntax", STD 66, 2229 RFC 3986, DOI 10.17487/RFC3986, January 2005, 2230 . 2232 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 2233 Encryption", RFC 5116, DOI 10.17487/RFC5116, January 2008, 2234 . 2236 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 2237 Key Derivation Function (HKDF)", RFC 5869, 2238 DOI 10.17487/RFC5869, May 2010, 2239 . 2241 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 2242 Constrained-Node Networks", RFC 7228, 2243 DOI 10.17487/RFC7228, May 2014, 2244 . 2246 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 2247 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 2248 2015, . 2250 [RFC7967] Bhattacharyya, A., Bandyopadhyay, S., Pal, A., and T. 2251 Bose, "Constrained Application Protocol (CoAP) Option for 2252 No Server Response", RFC 7967, DOI 10.17487/RFC7967, 2253 August 2016, . 2255 Appendix A. Scenario examples 2257 This section gives examples of OSCORE, targeting scenarios in 2258 Section 2.2.1.1 of [I-D.hartke-core-e2e-security-reqs]. The message 2259 exchanges are made, based on the assumption that there is a security 2260 context established between client and server. For simplicity, these 2261 examples only indicate the content of the messages without going into 2262 detail of the (compressed) COSE message format. 2264 A.1. Secure Access to Sensor 2266 This example illustrates a client requesting the alarm status from a 2267 server. 2269 Client Proxy Server 2270 | | | 2271 +------>| | Code: 0.02 (POST) 2272 | POST | | Token: 0x8c 2273 | | | Object-Security: [kid:5f,Partial IV:42] 2274 | | | Payload: {Code:0.01, 2275 | | | Uri-Path:"alarm_status"} 2276 | | | 2277 | +------>| Code: 0.02 (POST) 2278 | | POST | Token: 0x7b 2279 | | | Object-Security: [kid:5f,Partial IV:42] 2280 | | | Payload: {Code:0.01, 2281 | | | Uri-Path:"alarm_status"} 2282 | | | 2283 | |<------+ Code: 2.04 (Changed) 2284 | | 2.04 | Token: 0x7b 2285 | | | Object-Security: - 2286 | | | Payload: {Code:2.05, "OFF"} 2287 | | | 2288 |<------+ | Code: 2.04 (Changed) 2289 | 2.04 | | Token: 0x8c 2290 | | | Object-Security: - 2291 | | | Payload: {Code:2.05, "OFF"} 2292 | | | 2294 Figure 12: Secure Access to Sensor. Square brackets [ ... ] indicate 2295 content of compressed COSE object. Curly brackets { ... } indicate 2296 encrypted data. 2298 The request/response Codes are encrypted by OSCORE and only dummy 2299 Codes (POST/Changed) are visible in the header of the OSCORE message. 2300 The option Uri-Path ("alarm_status") and payload ("OFF") are 2301 encrypted. 2303 The COSE header of the request contains an identifier (5f), 2304 indicating which security context was used to protect the message and 2305 a Partial IV (42). 2307 The server verifies that the Partial IV has not been received before. 2308 The client verifies that the response is bound to the request. 2310 A.2. Secure Subscribe to Sensor 2312 This example illustrates a client requesting subscription to a blood 2313 sugar measurement resource (GET /glucose), first receiving the value 2314 220 mg/dl and then a second value 180 mg/dl. 2316 Client Proxy Server 2317 | | | 2318 +------>| | Code: 0.05 (FETCH) 2319 | FETCH | | Token: 0x83 2320 | | | Observe: 0 2321 | | | Object-Security: [kid:ca,Partial IV:15] 2322 | | | Payload: {Code:0.01, 2323 | | | Uri-Path:"glucose"} 2324 | | | 2325 | +------>| Code: 0.05 (FETCH) 2326 | | FETCH | Token: 0xbe 2327 | | | Observe: 0 2328 | | | Object-Security: [kid:ca,Partial IV:15] 2329 | | | Payload: {Code:0.01, 2330 | | | Uri-Path:"glucose"} 2331 | | | 2332 | |<------+ Code: 2.04 (Changed) 2333 | | 2.04 | Token: 0xbe 2334 | | | Observe: 7 2335 | | | Object-Security: [Partial IV:32] 2336 | | | Payload: {Code:2.05, 2337 | | | Content-Format:0, "220"} 2338 | | | 2339 |<------+ | Code: 2.04 (Changed) 2340 | 2.04 | | Token: 0x83 2341 | | | Observe: 7 2342 | | | Object-Security: [Partial IV:32] 2343 | | | Payload: {Code:2.05, 2344 | | | Content-Format:0, "220"} 2345 ... ... ... 2346 | | | 2347 | |<------+ Code: 2.04 (Changed) 2348 | | 2.04 | Token: 0xbe 2349 | | | Observe: 8 2350 | | | Object-Security: [Partial IV:36] 2351 | | | Payload: {Code:2.05, 2352 | | | Content-Format:0, "180"} 2353 | | | 2354 |<------+ | Code: 2.04 (Changed) 2355 | 2.04 | | Token: 0x83 2356 | | | Observe: 8 2357 | | | Object-Security: [Partial IV:36] 2358 | | | Payload: {Code:2.05, 2359 | | | Content-Format:0, "180"} 2360 | | | 2362 Figure 13: Secure Subscribe to Sensor. Square brackets [ ... ] 2363 indicate content of compressed COSE object header. Curly brackets { 2364 ... } indicate encrypted data. 2366 The request/response Codes are encrypted by OSCORE and only dummy 2367 Codes (FETCH/Changed) are visible in the header of the OSCORE 2368 message. The options Content-Format (0) and the payload ("220" and 2369 "180"), are encrypted. 2371 The COSE header of the request contains an identifier (ca), 2372 indicating the security context used to protect the message and a 2373 Partial IV (15). The COSE headers of the responses contains Partial 2374 IVs (32 and 36). 2376 The server verifies that the Partial IV has not been received before. 2377 The client verifies that the responses are bound to the request and 2378 that the Partial IVs are greater than any Partial IV previously 2379 received in a response bound to the request. 2381 Appendix B. Deployment examples 2383 OSCORE may be deployed in a variety of settings, a few examples are 2384 given in this section. 2386 B.1. Master Secret Used Once 2388 For settings where the Master Secret is only used during deployment, 2389 the uniqueness of AEAD nonce may be assured by persistent storage of 2390 the security context as described in this specification (see 2391 Section 7.5). For many IoT deployments, a 128 bit uniformly random 2392 Master Key is sufficient for encrypting all data exchanged with the 2393 IoT device throughout its lifetime. 2395 B.2. Master Secret Used Multiple Times 2397 In cases where the Master Secret is used to derive security context 2398 multiple times, e.g. during recommissioning or where the security 2399 context is not persistently stored, the reuse of AEAD nonce may be 2400 prevented by providing a sufficiently long uniformly random byte 2401 string as Master Salt, such that the probability of Master Salt re- 2402 use is negligible. The Master Salt may be transported in the Kid 2403 Context parameter of the request (see Section 5.1) 2405 B.3. Client Aliveness 2407 The use of a single OSCORE request and response enables the client to 2408 verify that the server's identity and aliveness through actual 2409 communications. While a verified OSCORE request enables the server 2410 to verify the identity of the entity who generated the message, it 2411 does not verify that the client is currently involved in the 2412 communication, since the message may be a delayed delivery of a 2413 previously generated request which now reaches the server. To verify 2414 the aliveness of the client the server may initiate an OSCORE 2415 protected message exchange with the client, e.g. by switching the 2416 roles of client and server as described in Section 3.1, or by using 2417 the Echo option in the response to a request from the client 2418 [I-D.ietf-core-echo-request-tag]. 2420 Appendix C. Test Vectors 2422 This appendix includes the test vectors for different examples of 2423 CoAP messages using OSCORE. 2425 C.1. Test Vector 1: Key Derivation with Master Salt 2427 Given a set of inputs, OSCORE defines how to set up the Security 2428 Context in both the client and the server. The default values are 2429 used for AEAD Algorithm and KDF. 2431 C.1.1. Client 2433 Inputs: 2435 o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes) 2437 o Master Salt: 0x9e7ca92223786340 (8 bytes) 2439 o Sender ID: 0x (0 byte) 2441 o Recipient ID: 0x01 (1 byte) 2443 From the previous parameters, 2445 o info (for Sender Key): 0x84400A634b657910 (8 bytes) 2447 o info (for Recipient Key): 0x8441010A634b657910 (9 bytes) 2449 o info (for Common IV): 0x84400a6249560d (7 bytes) 2451 Outputs: 2453 o Sender Key: 0x7230aab3b549d94c9224aacc744e93ab (16 bytes) 2455 o Recipient Key: 0xe534a26a64aa3982e988e31f1e401e65 (16 bytes) 2457 o Common IV: 0x01727733ab49ead385b18f7d91 (13 bytes) 2459 C.1.2. Server 2461 Inputs: 2463 o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes) 2465 o Master Salt: 0x9e7ca92223786340 (64 bytes) 2467 o Sender ID: 0x01 (1 byte) 2469 o Recipient ID: 0x (0 byte) 2471 From the previous parameters, 2473 o info (for Sender Key): 0x8441010A634b657910 (9 bytes) 2475 o info (for Recipient Key): 0x84400A634b657910 (8 bytes) 2477 o info (for Common IV): 0x84400a6249560d (7 bytes) 2479 Outputs: 2481 o Sender Key: 0xe534a26a64aa3982e988e31f1e401e65 (16 bytes) 2483 o Recipient Key: 0x7230aab3b549d94c9224aacc744e93ab (16 bytes) 2485 o Common IV: 0x01727733ab49ead385b18f7d91 (13 bytes) 2487 C.2. Test Vector 2: Key Derivation without Master Salt 2489 Given a set of inputs, OSCORE defines how to set up the Security 2490 Context in both the client and the server. The default values are 2491 used for AEAD Algorithm, KDF, and Master Salt. 2493 C.2.1. Client 2495 Inputs: 2497 o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes) 2499 o Sender ID: 0x00 (1 byte) 2501 o Recipient ID: 0x01 (1 byte) 2503 From the previous parameters, 2505 o info (for Sender Key): 0x8441000A634b657910 (9 bytes) 2506 o info (for Recipient Key): 0x8441010A634b657910 (9 bytes) 2508 o info (for Common IV): 0x84400a6249560d (7 bytes) 2510 Outputs: 2512 o Sender Key: 0xf8f3b887436285ed5a66f6026ac2cdc1 (16 bytes) 2514 o Recipient Key: 0xd904cb101f7341c3f4c56c300fa69941 (16 bytes) 2516 o Common IV: 0xd1a1949aa253278f34c528d2cc (13 bytes) 2518 C.2.2. Server 2520 Inputs: 2522 o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes) 2524 o Sender ID: 0x01 (1 byte) 2526 o Recipient ID: 0x00 (1 byte) 2528 From the previous parameters, 2530 o info (for Sender Key): 0x8441010A634b657910 (9 bytes) 2532 o info (for Recipient Key): 0x8441000A634b657910 (9 bytes) 2534 o info (for Common IV): 0x84400a6249560d (7 bytes) 2536 Outputs: 2538 o Sender Key: 0xd904cb101f7341c3f4c56c300fa69941 (16 bytes) 2540 o Recipient Key: 0xf8f3b887436285ed5a66f6026ac2cdc1 (16 bytes) 2542 o Common IV: 0xd1a1949aa253278f34c528d2cc (13 bytes) 2544 C.3. Test Vector 3: OSCORE Request, Client 2546 This section contains a test vector for a OSCORE protected CoAP GET 2547 request using the security context derived in Appendix C.1. The 2548 unprotected request only contains the Uri-Path option. 2550 Unprotected CoAP request: 2551 0x440149c60000f2a7396c6f63616c686f737483747631 (22 bytes) 2553 Common Context: 2555 o AEAD Algorithm: 10 (AES-CCM-16-64-128) 2557 o Key Derivation Function: HKDF SHA-256 2559 o Common IV: 0xd1a1949aa253278f34c528d2cc (13 bytes) 2561 Sender Context: 2563 o Sender ID: 0x00 (1 byte) 2565 o Sender Key: 0xf8f3b887436285ed5a66f6026ac2cdc1 (16 bytes) 2567 o Sender Sequence Number: 20 2569 The following COSE and cryptographic parameters are derived: 2571 o Partial IV: 0x14 (1 byte) 2573 o kid: 0x00 (1 byte) 2575 o external_aad: 0x8501810a4100411440 (9 bytes) 2577 o AAD: 0x8368456e63727970743040498501810a4100411440 (21 bytes) 2579 o plaintext: 0x01b3747631 (5 bytes) 2581 o encryption key: 0xf8f3b887436285ed5a66f6026ac2cdc1 (16 bytes) 2583 o nonce: 0xd0a1949aa253278f34c528d2d8 (13 bytes) 2585 From the previous parameter, the following is derived: 2587 o Object-Security value: 0x091400 (3 bytes) 2589 o ciphertext: 0x55b3710d47c611cd3924838a44 (13 bytes) 2591 From there: 2593 o Protected CoAP request (OSCORE message): 0x44026dd30000acc5396c6f6 2594 3616c686f7374d305091400ff55b3710d47c611cd3924838a44 (37 bytes) 2596 C.4. Test Vector 4: OSCORE Request, Client 2598 This section contains a test vector for a OSCORE protected CoAP GET 2599 request using the security context derived in Appendix C.2. The 2600 unprotected request only contains the Uri-Path option. 2602 Unprotected CoAP request: 2603 0x440149c60000f2a7396c6f63616c686f737483747631 (22 bytes) 2605 Common Context: 2607 o AEAD Algorithm: 10 (AES-CCM-16-64-128) 2609 o Key Derivation Function: HKDF SHA-256 2611 o Common IV: 0x01727733ab49ead385b18f7d91 (13 bytes) 2613 Sender Context: 2615 o Sender ID: 0x (0 bytes) 2617 o Sender Key: 0x7230aab3b549d94c9224aacc744e93ab (16 bytes) 2619 o Sender Sequence Number: 20 2621 The following COSE and cryptographic parameters are derived: 2623 o Partial IV: 0x14 (1 byte) 2625 o kid: 0x (0 byte) 2627 o external_aad: 0x8501810a40411440 (8 bytes) 2629 o AAD: 0x8368456e63727970743040488501810a40411440 (20 bytes) 2631 o plaintext: 0x01b3747631 (5 bytes) 2633 o encryption key: 0x7230aab3b549d94c9224aacc744e93ab (16 bytes) 2635 o nonce: 0x01727733ab49ead385b18f7d85 (13 bytes) 2637 From the previous parameter, the following is derived: 2639 o Object-Security value: 0x0914 (2 bytes) 2641 o ciphertext: 0x6be9214aad448260ff1be1f594 (13 bytes) 2643 From there: 2645 o Protected CoAP request (OSCORE message): 0x44023bfc000066ef396c6f6 2646 3616c686f7374d2050914ff6be9214aad448260ff1be1f594 (36 bytes) 2648 C.5. Test Vector 5: OSCORE Response, Server 2650 This section contains a test vector for a OSCORE protected 2.05 2651 Content response to the request in Appendix C.3. The unprotected 2652 response has payload "Hello World!" and no options. The protected 2653 response does not contain a kid nor a Partial IV. 2655 Unprotected CoAP response: 2656 0x644549c60000f2a7ff48656c6c6f20576f726c6421 (21 bytes) 2658 Common Context: 2660 o AEAD Algorithm: 10 (AES-CCM-16-64-128) 2662 o Key Derivation Function: HKDF SHA-256 2664 o Common IV: 0xd1a1949aa253278f34c528d2cc (13 bytes) 2666 Sender Context: 2668 o Sender ID: 0x01 (1 byte) 2670 o Sender Key: 0xd904cb101f7341c3f4c56c300fa69941 (16 bytes) 2672 o Sender Sequence Number: 0 2674 The following COSE and cryptographic parameters are derived: 2676 o external_aad: 0x8501810a4100411440 (9 bytes) 2678 o AAD: 0x8368456e63727970743040498501810a4100411440 (21 bytes) 2680 o plaintext: 0x45ff48656c6c6f20576f726c6421 (14 bytes) 2682 o encryption key: 0xd904cb101f7341c3f4c56c300fa69941 (16 bytes) 2684 o nonce: 0xd0a1949aa253278f34c528d2d8 (13 bytes) 2686 From the previous parameter, the following is derived: 2688 o Object-Security value: 0x (0 bytes) 2690 o ciphertext: e4e8c28c41c8f31ca56eec24f6c71d94eacbcdffdc6d (22 2691 bytes) 2693 From there: 2695 o Protected CoAP response (OSCORE message): 0x64446dd30000acc5d008ff 2696 e4e8c28c41c8f31ca56eec24f6c71d94eacbcdffdc6d (33 bytes) 2698 C.6. Test Vector 6: OSCORE Response with Partial IV, Server 2700 This section contains a test vector for a OSCORE protected 2.05 2701 Content response to the request in Appendix C.3. The unprotected 2702 response has payload "Hello World!" and no options. The protected 2703 response does not contain a kid, but contains a Partial IV. 2705 Unprotected CoAP response: 2706 0x644549c60000f2a7ff48656c6c6f20576f726c6421 (21 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) 2716 Sender Context: 2718 o Sender ID: 0x01 (1 byte) 2720 o Sender Key: 0xd904cb101f7341c3f4c56c300fa69941 (16 bytes) 2722 o Sender Sequence Number: 0 2724 The following COSE and cryptographic parameters are derived: 2726 o Partial IV: 0x00 (1 byte) 2728 o external_aad: 0x8501810a4100411440 (9 bytes) 2730 o AAD: 0x8368456e63727970743040498501810a4100411440 (21 bytes) 2732 o plaintext: 0x45ff48656c6c6f20576f726c6421 (14 bytes) 2734 o encryption key: 0xd904cb101f7341c3f4c56c300fa69941 (16 bytes) 2736 o nonce: 0xd0a1949aa253278e34c528d2cc (13 bytes) 2738 From the previous parameter, the following is derived: 2740 o Object-Security value: 0x0100 (2 bytes) 2741 o ciphertext: 0xa7e3ca27f221f453c0ba68c350bf652ea096b328a1bf (22 2742 bytes) 2744 From there: 2746 o Protected CoAP response (OSCORE message): 0x64442b130000b29ed20801 2747 00ffa7e3ca27f221f453c0ba68c350bf652ea096b328a1bf (35 bytes) 2749 Acknowledgments 2751 The following individuals provided input to this document: Christian 2752 Amsuess, Tobias Andersson, Carsten Bormann, Joakim Brorsson, Esko 2753 Dijk, Thomas Fossati, Martin Gunnarsson, Klaus Hartke, Jim Schaad, 2754 Peter van der Stok, Dave Thaler, Marco Tiloca, and Malisa Vucinic. 2756 Ludwig Seitz and Goeran Selander worked on this document as part of 2757 the CelticPlus project CyberWI, with funding from Vinnova. 2759 Authors' Addresses 2761 Goeran Selander 2762 Ericsson AB 2764 Email: goran.selander@ericsson.com 2766 John Mattsson 2767 Ericsson AB 2769 Email: john.mattsson@ericsson.com 2771 Francesca Palombini 2772 Ericsson AB 2774 Email: francesca.palombini@ericsson.com 2776 Ludwig Seitz 2777 RISE SICS 2779 Email: ludwig.seitz@ri.se