idnits 2.17.1 draft-ietf-core-object-security-11.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 19, 2018) is 2220 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) == Missing Reference: 'MF00' is mentioned on line 2058, but not defined ** Obsolete normative reference: RFC 6347 (Obsoleted by RFC 9147) ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) ** Downref: Normative reference to an Experimental RFC: RFC 7390 ** Obsolete normative reference: RFC 8152 (Obsoleted by RFC 9052, RFC 9053) == Outdated reference: A later version (-15) exists of draft-ietf-6tisch-minimal-security-05 == Outdated reference: A later version (-46) exists of draft-ietf-ace-oauth-authz-10 == Outdated reference: A later version (-19) exists of draft-ietf-ace-oscore-profile-01 == Outdated reference: A later version (-08) exists of draft-ietf-cbor-cddl-02 == Outdated reference: A later version (-14) exists of draft-ietf-core-echo-request-tag-01 == Outdated reference: A later version (-21) exists of draft-ietf-core-oscore-groupcomm-01 == Outdated reference: A later version (-06) exists of draft-mattsson-core-coap-actuators-04 Summary: 6 errors (**), 0 flaws (~~), 9 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CoRE Working Group G. Selander 3 Internet-Draft J. Mattsson 4 Intended status: Standards Track F. Palombini 5 Expires: September 20, 2018 Ericsson AB 6 L. Seitz 7 RISE SICS 8 March 19, 2018 10 Object Security for Constrained RESTful Environments (OSCORE) 11 draft-ietf-core-object-security-11 13 Abstract 15 This document defines Object Security for Constrained RESTful 16 Environments (OSCORE), a method for application-layer protection of 17 the Constrained Application Protocol (CoAP), using CBOR Object 18 Signing and Encryption (COSE). OSCORE provides end-to-end protection 19 between endpoints communicating using CoAP or CoAP-mappable HTTP. 20 OSCORE is designed for constrained nodes and networks supporting a 21 range of proxy operations, including translation between different 22 transport protocols. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at https://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on September 20, 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 Options . . . . . . . . . . . . . . . . . . . . . . 13 67 4.2. CoAP Header Fields and Payload . . . . . . . . . . . . . 20 68 4.3. Signaling Messages . . . . . . . . . . . . . . . . . . . 21 69 5. The COSE Object . . . . . . . . . . . . . . . . . . . . . . . 22 70 5.1. Kid Context . . . . . . . . . . . . . . . . . . . . . . . 23 71 5.2. Nonce . . . . . . . . . . . . . . . . . . . . . . . . . . 24 72 5.3. Plaintext . . . . . . . . . . . . . . . . . . . . . . . . 24 73 5.4. Additional Authenticated Data . . . . . . . . . . . . . . 25 74 6. OSCORE Header Compression . . . . . . . . . . . . . . . . . . 26 75 6.1. Encoding of the Object-Security Value . . . . . . . . . . 26 76 6.2. Encoding of the OSCORE Payload . . . . . . . . . . . . . 28 77 6.3. Examples of Compressed COSE Objects . . . . . . . . . . . 28 78 7. Sequence Numbers, Replay, Message Binding, and Freshness . . 30 79 7.1. Message Binding . . . . . . . . . . . . . . . . . . . . . 30 80 7.2. AEAD Nonce Uniqueness . . . . . . . . . . . . . . . . . . 30 81 7.3. Freshness . . . . . . . . . . . . . . . . . . . . . . . . 31 82 7.4. Replay Protection . . . . . . . . . . . . . . . . . . . . 31 83 7.5. Losing Part of the Context State . . . . . . . . . . . . 32 84 8. Processing . . . . . . . . . . . . . . . . . . . . . . . . . 33 85 8.1. Protecting the Request . . . . . . . . . . . . . . . . . 33 86 8.2. Verifying the Request . . . . . . . . . . . . . . . . . . 34 87 8.3. Protecting the Response . . . . . . . . . . . . . . . . . 35 88 8.4. Verifying the Response . . . . . . . . . . . . . . . . . 36 89 9. Web Linking . . . . . . . . . . . . . . . . . . . . . . . . . 37 90 10. Proxy and HTTP Operations . . . . . . . . . . . . . . . . . . 37 91 10.1. CoAP-to-CoAP Forwarding Proxy . . . . . . . . . . . . . 38 92 10.2. HTTP Processing . . . . . . . . . . . . . . . . . . . . 38 93 10.3. HTTP-to-CoAP Translation Proxy . . . . . . . . . . . . . 40 94 10.4. CoAP-to-HTTP Translation Proxy . . . . . . . . . . . . . 41 95 11. Security Considerations . . . . . . . . . . . . . . . . . . . 43 96 11.1. End-to-end protection . . . . . . . . . . . . . . . . . 43 97 11.2. Security Context Establishment . . . . . . . . . . . . . 44 98 11.3. Replay Protection . . . . . . . . . . . . . . . . . . . 44 99 11.4. Cryptographic Considerations . . . . . . . . . . . . . . 44 100 11.5. Message Segmentation . . . . . . . . . . . . . . . . . . 45 101 11.6. Privacy Considerations . . . . . . . . . . . . . . . . . 45 102 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 45 103 12.1. COSE Header Parameters Registry . . . . . . . . . . . . 46 104 12.2. CoAP Option Numbers Registry . . . . . . . . . . . . . . 46 105 12.3. CoAP Signaling Option Numbers Registry . . . . . . . . . 46 106 12.4. Header Field Registrations . . . . . . . . . . . . . . . 46 107 12.5. Media Type Registrations . . . . . . . . . . . . . . . . 47 108 12.6. CoAP Content-Formats Registry . . . . . . . . . . . . . 49 109 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 49 110 13.1. Normative References . . . . . . . . . . . . . . . . . . 49 111 13.2. Informative References . . . . . . . . . . . . . . . . . 51 112 Appendix A. Scenario Examples . . . . . . . . . . . . . . . . . 52 113 A.1. Secure Access to Sensor . . . . . . . . . . . . . . . . . 52 114 A.2. Secure Subscribe to Sensor . . . . . . . . . . . . . . . 53 115 Appendix B. Deployment examples . . . . . . . . . . . . . . . . 55 116 B.1. Master Secret Used Once . . . . . . . . . . . . . . . . . 55 117 B.2. Master Secret Used Multiple Times . . . . . . . . . . . . 55 118 B.3. Client Aliveness . . . . . . . . . . . . . . . . . . . . 56 119 Appendix C. Test Vectors . . . . . . . . . . . . . . . . . . . . 57 120 C.1. Test Vector 1: Key Derivation with Master Salt . . . . . 57 121 C.2. Test Vector 2: Key Derivation without Master Salt . . . . 58 122 C.3. Test Vector 3: OSCORE Request, Client . . . . . . . . . . 59 123 C.4. Test Vector 4: OSCORE Request, Client . . . . . . . . . . 60 124 C.5. Test Vector 5: OSCORE Response, Server . . . . . . . . . 61 125 C.6. Test Vector 6: OSCORE Response with Partial IV, Server . 62 126 Appendix D. Overview of Security Properties . . . . . . . . . . 64 127 D.1. Supporting Proxy Operations . . . . . . . . . . . . . . . 64 128 D.2. Protected Message Fields . . . . . . . . . . . . . . . . 64 129 D.3. Uniqueness of (key, nonce) . . . . . . . . . . . . . . . 65 130 D.4. Unprotected Message Fields . . . . . . . . . . . . . . . 66 131 Appendix E. CDDL Summary . . . . . . . . . . . . . . . . . . . . 68 132 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 69 133 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 69 135 1. Introduction 137 The Constrained Application Protocol (CoAP) [RFC7252] is a web 138 transfer protocol, designed for constrained nodes and networks 139 [RFC7228], and may be mapped from HTTP [RFC8075]. CoAP specifies the 140 use of proxies for scalability and efficiency and references DTLS 141 [RFC6347] for security. CoAP-to-CoAP, HTTP-to-CoAP, and CoAP-to-HTTP 142 proxies require (D)TLS to be terminated at the proxy. The proxy 143 therefore not only has access to the data required for performing the 144 intended proxy functionality, but is also able to eavesdrop on, or 145 manipulate any part of, the message payload and metadata in transit 146 between the endpoints. The proxy can also inject, delete, or reorder 147 packets since they are no longer protected by (D)TLS. 149 This document defines the Object Security for Constrained RESTful 150 Environments (OSCORE) security protocol, protecting CoAP and CoAP- 151 mappable HTTP requests and responses end-to-end across intermediary 152 nodes such as CoAP forward proxies and cross-protocol translators 153 including HTTP-to-CoAP proxies [RFC8075]. In addition to the core 154 CoAP features defined in [RFC7252], OSCORE supports Observe 155 [RFC7641], Block-wise [RFC7959], No-Response [RFC7967], and PATCH and 156 FETCH [RFC8132]. An analysis of end-to-end security for CoAP 157 messages through some types of intermediary nodes is performed in 158 [I-D.hartke-core-e2e-security-reqs]. OSCORE essentially protects the 159 RESTful interactions; the request method, the requested resource, the 160 message payload, etc. (see Section 4). OSCORE protects neither the 161 CoAP Messaging Layer nor the CoAP Token which may change between the 162 endpoints, and those are therefore processed as defined in [RFC7252]. 163 Additionally, since the message formats for CoAP over unreliable 164 transport [RFC7252] and for CoAP over reliable transport [RFC8323] 165 differ only in terms of CoAP Messaging Layer, OSCORE can be applied 166 to both unreliable and reliable transports (see Figure 1). 168 +-----------------------------------+ 169 | Application | 170 +-----------------------------------+ 171 +-----------------------------------+ \ 172 | Requests / Responses / Signaling | | 173 |-----------------------------------| | 174 | OSCORE | | CoAP 175 |-----------------------------------| | 176 | Messaging Layer / Message Framing | | 177 +-----------------------------------+ / 178 +-----------------------------------+ 179 | UDP / TCP / ... | 180 +-----------------------------------+ 182 Figure 1: Abstract Layering of CoAP with OSCORE 184 OSCORE works in very constrained nodes and networks, thanks to its 185 small message size and the restricted code and memory requirements in 186 addition to what is required by CoAP. Examples of the use of OSCORE 187 are given in Appendix A. OSCORE does not depend on underlying 188 layers, and can be used anywhere where CoAP or HTTP can be used, 189 including non-IP transports (e.g., [I-D.bormann-6lo-coap-802-15-ie]). 190 OSCORE may be used together with (D)TLS over one or more hops in the 191 end-to-end path, e.g. with HTTPS in one hop and with plain CoAP in 192 another hop. 194 The use of OSCORE does not affect the URI scheme and OSCORE can 195 therefore be used with any URI scheme defined for CoAP or HTTP. The 196 application decides the conditions for which OSCORE is required. 198 OSCORE uses pre-shared keys which may have been established out-of- 199 band or with a key establishment protocol (see Section 3.2). The 200 technical solution builds on CBOR Object Signing and Encryption 201 (COSE) [RFC8152], providing end-to-end encryption, integrity, replay 202 protection, and secure binding of response to request. A compressed 203 version of COSE is used, as specified in Section 6. The use of 204 OSCORE is signaled with the new Object-Security CoAP option or HTTP 205 header field, defined in Section 2 and Section 10.3. The solution 206 transforms a CoAP/HTTP message into an "OSCORE message" before 207 sending, and vice versa after receiving. The OSCORE message is a 208 CoAP/HTTP message related to the original message in the following 209 way: the original CoAP/HTTP message is translated to CoAP (if not 210 already in CoAP) and protected in a COSE object. The encrypted 211 message fields of this COSE object are transported in the CoAP 212 payload/HTTP body of the OSCORE message, and the Object-Security 213 option/header field is included in the message. A sketch of an 214 OSCORE message exchange in the case of the original message being 215 CoAP is provided in Figure 2). 217 Client Server 218 | OSCORE request - POST example.com: | 219 | Header, Token, | 220 | Options: {Object-Security, ...}, | 221 | Payload: COSE ciphertext | 222 +--------------------------------------------->| 223 | | 224 |<---------------------------------------------+ 225 | OSCORE response - 2.04 (Changed): | 226 | Header, Token, | 227 | Options: {Object-Security, ...}, | 228 | Payload: COSE ciphertext | 229 | | 231 Figure 2: Sketch of CoAP with OSCORE 233 An implementation supporting this specification MAY implement only 234 the client part, MAY implement only the server part, or MAY implement 235 only one of the proxy parts. OSCORE is designed to protect as much 236 information as possible while still allowing proxy operations 237 (Section 10). It works with legacy CoAP-to-CoAP forward proxies 238 [RFC7252], but an OSCORE-aware proxy will be more efficient. HTTP- 239 to-CoAP proxies [RFC8075] and CoAP-to-HTTP proxies can also be used 240 with OSCORE, as specified in Section 10. 242 1.1. Terminology 244 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 245 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 246 "OPTIONAL" in this document are to be interpreted as described in BCP 247 14 [RFC2119] [RFC8174] when, and only when, they appear in all 248 capitals, as shown here. 250 Readers are expected to be familiar with the terms and concepts 251 described in CoAP [RFC7252], Observe [RFC7641], Block-wise [RFC7959], 252 COSE [RFC8152], CBOR [RFC7049], CDDL [I-D.ietf-cbor-cddl] as 253 summarized in Appendix E, and constrained environments [RFC7228]. 255 The term "hop" is used to denote a particular leg in the end-to-end 256 path. The concept "hop-by-hop" (as in "hop-by-hop encryption" or 257 "hop-by-hop fragmentation") opposed to "end-to-end", is used in this 258 document to indicate that the messages are processed accordingly in 259 the intermediaries, rather than just forwarded to the next node. 261 The term "stop processing" is used throughout the document to denote 262 that the message is not passed up to the CoAP Request/Response layer 263 (see Figure 1). 265 The terms Common/Sender/Recipient Context, Master Secret/Salt, Sender 266 ID/Key, Recipient ID/Key, and Common IV are defined in Section 3.1. 268 2. The CoAP Object-Security Option 270 The CoAP Object-Security option (see Figure 3, which extends Table 4 271 of [RFC7252]) indicates that the CoAP message is an OSCORE message 272 and that it contains a compressed COSE object (see Section 5 and 273 Section 6). The Object-Security option is critical, safe to forward, 274 part of the cache key, and not repeatable. 276 +-----+---+---+---+---+-----------------+--------+--------+---------+ 277 | No. | C | U | N | R | Name | Format | Length | Default | 278 +-----+---+---+---+---+-----------------+--------+--------+---------+ 279 | TBD | x | | | | Object-Security | (*) | 0-255 | (none) | 280 +-----+---+---+---+---+-----------------+--------+--------+---------+ 281 C = Critical, U = Unsafe, N = NoCacheKey, R = Repeatable 282 (*) See below. 284 Figure 3: The Object-Security Option 286 The Object-Security option includes the OSCORE flag bits (Section 6), 287 the Sender Sequence Number and the Sender ID when present 288 (Section 3). The detailed format and length is specified in 289 Section 6. If the OSCORE flag bits is all zero (0x00) the Option 290 value SHALL be empty (Option Length = 0). An endpoint receiving a 291 CoAP message without payload, that also contains an Object-Security 292 option SHALL treat it as malformed and reject it. 294 A successful response to a request with the Object-Security option 295 SHALL contain the Object-Security option. Whether error responses 296 contain the Object-Security option depends on the error type (see 297 Section 8). 299 A CoAP proxy SHOULD NOT cache a response to a request with an Object- 300 Security option, since the response is only applicable to the 301 original request (see Section 10.1). As the compressed COSE Object 302 is included in the cache key, messages with the Object-Security 303 option will never generate cache hits. For Max-Age processing, see 304 Section 4.1.3.1. 306 3. The Security Context 308 OSCORE requires that client and server establish a shared security 309 context used to process the COSE objects. OSCORE uses COSE with an 310 Authenticated Encryption with Additional Data (AEAD, [RFC5116]) 311 algorithm for protecting message data between a client and a server. 312 In this section, we define the security context and how it is derived 313 in client and server based on a shared secret and a key derivation 314 function (KDF). 316 3.1. Security Context Definition 318 The security context is the set of information elements necessary to 319 carry out the cryptographic operations in OSCORE. For each endpoint, 320 the security context is composed of a "Common Context", a "Sender 321 Context", and a "Recipient Context". 323 The endpoints protect messages to send using the Sender Context and 324 verify messages received using the Recipient Context, both contexts 325 being derived from the Common Context and other data. Clients and 326 servers need to be able to retrieve the correct security context to 327 use. 329 An endpoint uses its Sender ID (SID) to derive its Sender Context, 330 and the other endpoint uses the same ID, now called Recipient ID 331 (RID), to derive its Recipient Context. In communication between two 332 endpoints, the Sender Context of one endpoint matches the Recipient 333 Context of the other endpoint, and vice versa. Thus, the two 334 security contexts identified by the same IDs in the two endpoints are 335 not the same, but they are partly mirrored. Retrieval and use of the 336 security context are shown in Figure 4. 338 .-------------. .-------------. 339 | Common, | | Common, | 340 | Sender, | | Recipient, | 341 | Recipient | | Sender | 342 '-------------' '-------------' 343 Client Server 344 | | 345 Retrieve context for | OSCORE request: | 346 target resource | Token = Token1, | 347 Protect request with | kid = SID, ... | 348 Sender Context +---------------------->| Retrieve context with 349 | | RID = kid 350 | | Verify request with 351 | | Recipient Context 352 | OSCORE response: | Protect response with 353 | Token = Token1, ... | Sender Context 354 Retrieve context with |<----------------------+ 355 Token = Token1 | | 356 Verify request with | | 357 Recipient Context | | 359 Figure 4: Retrieval and use of the Security Context 361 The Common Context contains the following parameters: 363 o AEAD Algorithm. The COSE AEAD algorithm to use for encryption. 365 o Key Derivation Function. The HMAC based HKDF [RFC5869] used to 366 derive Sender Key, Recipient Key, and Common IV. 368 o Master Secret. Variable length, uniformly random byte string 369 containing the key used to derive traffic keys and IVs. 371 o Master Salt. Variable length byte string containing the salt used 372 to derive traffic keys and IVs. 374 o Common IV. Byte string derived from Master Secret and Master 375 Salt. Length is determined by the AEAD Algorithm. 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. 383 o Sender Key. Byte string containing the symmetric key to protect 384 messages to send. Derived from Common Context and Sender ID. 385 Length is determined by the AEAD Algorithm. 387 o Sender Sequence Number. Non-negative integer used by the sender 388 to protect requests and Observe notifications. Used as 'Partial 389 IV' [RFC8152] to generate unique nonces for the AEAD. Maximum 390 value is determined by the AEAD Algorithm. 392 The Recipient Context contains the following parameters: 394 o Recipient ID. Byte string used to identify the Recipient Context 395 and to assure unique AEAD nonces. Maximum length is determined by 396 the AEAD Algorithm. 398 o Recipient Key. Byte string containing the symmetric key to verify 399 messages received. Derived from Common Context and Recipient ID. 400 Length is determined by the AEAD Algorithm. 402 o Replay Window (Server only). The replay window to verify requests 403 received. 405 All parameters except Sender Sequence Number and Replay Window are 406 immutable once the security context is established. An endpoint may 407 free up memory by not storing the Common IV, Sender Key, and 408 Recipient Key, deriving them from the Master Key and Master Salt when 409 needed. Alternatively, an endpoint may free up memory by not storing 410 the Master Secret and Master Salt after the other parameters have 411 been derived. 413 Endpoints MAY operate as both client and server and use the same 414 security context for those roles. Independent of being client or 415 server, the endpoint protects messages to send using its Sender 416 Context, and verifies messages received using its Recipient Context. 417 The endpoints MUST NOT change the Sender/Recipient ID when changing 418 roles. In other words, changing the roles does not change the set of 419 keys to be used. 421 3.2. Establishment of Security Context Parameters 423 The parameters in the security context are derived from a small set 424 of input parameters. The following input parameters SHALL be pre- 425 established: 427 o Master Secret 429 o Sender ID 431 o Recipient ID 432 The following input parameters MAY be pre-established. In case any 433 of these parameters is not pre-established, the default value 434 indicated below is used: 436 o AEAD Algorithm 438 * Default is AES-CCM-16-64-128 (COSE algorithm encoding: 10) 440 o Master Salt 442 * Default is the empty string 444 o Key Derivation Function (KDF) 446 * Default is HKDF SHA-256 448 o Replay Window Type and Size 450 * Default is DTLS-type replay protection with a window size of 32 451 [RFC6347] 453 All input parameters need to be known to and agreed on by both 454 endpoints, but the replay window may be different in the two 455 endpoints. The way the input parameters are pre-established, is 456 application specific. The OSCORE profile of the ACE framework may be 457 used to establish the necessary input parameters 458 [I-D.ietf-ace-oscore-profile], or a key exchange protocol for 459 providing forward secrecy. Other examples of deploying OSCORE are 460 given in Appendix B. 462 3.2.1. Derivation of Sender Key, Recipient Key, and Common IV 464 The KDF MUST be one of the HMAC based HKDF [RFC5869] algorithms 465 defined in COSE. HKDF SHA-256 is mandatory to implement. The 466 security context parameters Sender Key, Recipient Key, and Common IV 467 SHALL be derived from the input parameters using the HKDF, which 468 consists of the composition of the HKDF-Extract and HKDF-Expand steps 469 [RFC5869]: 471 output parameter = HKDF(salt, IKM, info, L) 473 where: 475 o salt is the Master Salt as defined above 477 o IKM is the Master Secret as defined above 479 o info is a CBOR array consisting of: 481 info = [ 482 id : bstr, 483 alg_aead : int / tstr, 484 type : tstr, 485 L : uint 486 ] 488 where: 490 o id is the Sender ID or Recipient ID when deriving keys and the 491 empty string when deriving the Common IV. The encoding is 492 described in Section 5. 494 o alg_aead is the AEAD Algorithm, encoded as defined in [RFC8152]. 496 o type is "Key" or "IV". The label is an ASCII string, and does not 497 include a trailing NUL byte. 499 o L is the size of the key/IV for the AEAD algorithm used, in bytes. 501 For example, if the algorithm AES-CCM-16-64-128 (see Section 10.2 in 502 [RFC8152]) is used, the integer value for alg_aead is 10, the value 503 for L is 16 for keys and 13 for the Common IV. 505 3.2.2. Initial Sequence Numbers and Replay Window 507 The Sender Sequence Number is initialized to 0. The supported types 508 of replay protection and replay window length is application specific 509 and depends on how OSCORE is transported, see Section 7.4. The 510 default is DTLS-type replay protection with a window size of 32 511 initiated as described in Section 4.1.2.6 of [RFC6347]. 513 3.3. Requirements on the Security Context Parameters 515 As collisions may lead to the loss of both confidentiality and 516 integrity, Sender ID SHALL be unique in the set of all security 517 contexts using the same Master Secret and Master Salt. When a 518 trusted third party assigns identifiers (e.g., using 519 [I-D.ietf-ace-oauth-authz]) or by using a protocol that allows the 520 parties to negotiate locally unique identifiers in each endpoint, the 521 Sender IDs can be very short. The maximum length of Sender ID in 522 bytes equals the length of AEAD nonce minus 6. For AES-CCM-16-64-128 523 the maximum length of Sender ID is 7 bytes. 525 To simplify retrieval of the right Recipient Context, the Recipient 526 ID SHOULD be unique in the sets of all Recipient Contexts used by an 527 endpoint. If an endpoint has the same Recipient ID with different 528 Recipient Contexts, i.e. the Recipient Contexts are derived from 529 different keying material, then the endpoint may need to try multiple 530 times before finding the right security context associated to the 531 Recipient ID. The Client MAY provide a 'kid context' parameter 532 (Section 5.1) to help the Server find the right context. 534 While the triple (Master Secret, Master Salt, Sender ID) MUST be 535 unique, the same Master Salt MAY be used with several Master Secrets 536 and the same Master Secret MAY be used with several Master Salts. 538 4. Protected Message Fields 540 OSCORE transforms a CoAP message (which may have been generated from 541 an HTTP message) into an OSCORE message, and vice versa. OSCORE 542 protects as much of the original message as possible while still 543 allowing certain proxy operations (see Section 10). This section 544 defines how OSCORE protects the message fields and transfers them 545 end-to-end between client and server (in any direction). 547 The remainder of this section and later sections discuss the behavior 548 in terms of CoAP messages. If HTTP is used for a particular hop in 549 the end-to-end path, then this section applies to the conceptual CoAP 550 message that is mappable to/from the original HTTP message as 551 discussed in Section 10. That is, an HTTP message is conceptually 552 transformed to a CoAP message and then to an OSCORE message, and 553 similarly in the reverse direction. An actual implementation might 554 translate directly from HTTP to OSCORE without the intervening CoAP 555 representation. 557 Protection of Signaling messages (Section 5 of [RFC8323]) is 558 specified in Section 4.3. The other parts of this section target 559 Request/Response messages. 561 Message fields of the CoAP message may be protected end-to-end 562 between CoAP client and CoAP server in different ways: 564 o Class E: encrypted and integrity protected, 566 o Class I: integrity protected only, or 568 o Class U: unprotected. 570 The sending endpoint SHALL transfer Class E message fields in the 571 ciphertext of the COSE object in the OSCORE message. The sending 572 endpoint SHALL include Class I message fields in the Additional 573 Authenticated Data (AAD) of the AEAD algorithm, allowing the 574 receiving endpoint to detect if the value has changed in transfer. 575 Class U message fields SHALL NOT be protected in transfer. Class I 576 and Class U message field values are transferred in the header or 577 options part of the OSCORE message, which is visible to proxies. 579 Message fields not visible to proxies, i.e., transported in the 580 ciphertext of the COSE object, are called "Inner" (Class E). Message 581 fields transferred in the header or options part of the OSCORE 582 message, which is visible to proxies, are called "Outer" (Class I or 583 U). There are currently no Class I options defined. 585 An OSCORE message may contain both an Inner and an Outer instance of 586 a certain CoAP message field. Inner message fields are intended for 587 the receiving endpoint, whereas Outer message fields are used to 588 enable proxy operations. Inner and Outer message fields are 589 processed independently. 591 4.1. CoAP Options 593 A summary of how options are protected is shown in Figure 5. Note 594 that some options may have both Inner and Outer message fields which 595 are protected accordingly. The options which require special 596 processing are labelled with asterisks. 598 +-----+-----------------+---+---+ 599 | No. | Name | E | U | 600 +-----+-----------------+---+---+ 601 | 1 | If-Match | x | | 602 | 3 | Uri-Host | | x | 603 | 4 | ETag | x | | 604 | 5 | If-None-Match | x | | 605 | 6 | Observe | | * | 606 | 7 | Uri-Port | | x | 607 | 8 | Location-Path | x | | 608 | TBD | Object-Security | | * | 609 | 11 | Uri-Path | x | | 610 | 12 | Content-Format | x | | 611 | 14 | Max-Age | * | * | 612 | 15 | Uri-Query | x | | 613 | 17 | Accept | x | | 614 | 20 | Location-Query | x | | 615 | 23 | Block2 | * | * | 616 | 27 | Block1 | * | * | 617 | 28 | Size2 | * | * | 618 | 35 | Proxy-Uri | | * | 619 | 39 | Proxy-Scheme | | x | 620 | 60 | Size1 | * | * | 621 | 258 | No-Response | * | * | 622 +-----+-----------------+---+---+ 624 E = Encrypt and Integrity Protect (Inner) 625 U = Unprotected (Outer) 626 * = Special 628 Figure 5: Protection of CoAP Options 630 Options that are unknown or for which OSCORE processing is not 631 defined SHALL be processed as class E (and no special processing). 632 Specifications of new CoAP options SHOULD define how they are 633 processed with OSCORE. A new COAP option SHOULD be of class E unless 634 it requires proxy processing. 636 4.1.1. Inner Options 638 Inner option message fields (class E) are used to communicate 639 directly with the other endpoint. 641 The sending endpoint SHALL write the Inner option message fields 642 present in the original CoAP message into the plaintext of the COSE 643 object (Section 5.3), and then remove the Inner option message fields 644 from the OSCORE message. 646 The processing of Inner option message fields by the receiving 647 endpoint is specified in Section 8.2 and Section 8.4. 649 4.1.2. Outer Options 651 Outer option message fields (Class U or I) are used to support proxy 652 operations. 654 The sending endpoint SHALL include the Outer option message field 655 present in the original message in the options part of the OSCORE 656 message. All Outer option message fields, including Object-Security, 657 SHALL be encoded as described in Section 3.1 of [RFC7252], where the 658 delta is the difference to the previously included instance of Outer 659 option message field. 661 The processing of Outer options by the receiving endpoint is 662 specified in Section 8.2 and Section 8.4. 664 A procedure for integrity-protection-only of Class I option message 665 fields is specified in Section 5.4. Proxies MUST NOT change the 666 order of option's occurrences, for options repeatable and of class I. 668 Note: There are currently no Class I option message fields defined. 670 4.1.3. Special Options 672 Some options require special processing, marked with an asterisk '*' 673 in Figure 5; the processing is specified in this section. 675 4.1.3.1. Max-Age 677 An Inner Max-Age message field is used to indicate the maximum time a 678 response may be cached by the client (as defined in [RFC7252]), end- 679 to-end from the server to the client, taking into account that the 680 option is not accessible to proxies. The Inner Max-Age SHALL be 681 processed by OSCORE as specified in Section 4.1.1. 683 An Outer Max-Age message field is used to avoid unnecessary caching 684 of OSCORE error responses at OSCORE unaware intermediary nodes. A 685 server MAY set a Class U Max-Age message field with value zero to 686 OSCORE error responses, which are described in Section 7.4, 687 Section 8.2 and Section 8.4. Such message field is then processed 688 according to Section 4.1.2. 690 Successful OSCORE responses do not need to include an Outer Max-Age 691 option since the responses are non-cacheable by construction (see 692 Section 4.2). 694 4.1.3.2. The Block Options 696 Block-wise [RFC7959] is an optional feature. An implementation MAY 697 support [RFC7252] and the Object-Security option without supporting 698 block-wise transfers. The Block options (Block1, Block2, Size1, 699 Size2), when Inner message fields, provide secure message 700 segmentation such that each segment can be verified. The Block 701 options, when Outer message fields, enables hop-by-hop fragmentation 702 of the OSCORE message. Inner and Outer block processing may have 703 different performance properties depending on the underlying 704 transport. The end-to-end integrity of the message can be verified 705 both in case of Inner and Outer Block-wise transfers provided all 706 blocks are received. 708 4.1.3.2.1. Inner Block Options 710 The sending CoAP endpoint MAY fragment a CoAP message as defined in 711 [RFC7959] before the message is processed by OSCORE. In this case 712 the Block options SHALL be processed by OSCORE as Inner options 713 (Section 4.1.1). The receiving CoAP endpoint SHALL process the 714 OSCORE message according to Section 4.1.1 before processing Block- 715 wise as defined in [RFC7959]. 717 4.1.3.2.2. Outer Block Options 719 Proxies MAY fragment an OSCORE message using [RFC7959], by 720 introducing Block option message fields that are Outer 721 (Section 4.1.2) and not generated by the sending endpoint. Note that 722 the Outer Block options are neither encrypted nor integrity 723 protected. As a consequence, a proxy can maliciously inject block 724 fragments indefinitely, since the receiving endpoint needs to receive 725 the last block (see [RFC7959]) to be able to compose the OSCORE 726 message and verify its integrity. Therefore, applications supporting 727 OSCORE and [RFC7959] MUST specify a security policy defining a 728 maximum unfragmented message size (MAX_UNFRAGMENTED_SIZE) considering 729 the maximum size of message which can be handled by the endpoints. 730 Messages exceeding this size SHOULD be fragmented by the sending 731 endpoint using Inner Block options (Section 4.1.3.2.1). 733 An endpoint receiving an OSCORE message with an Outer Block option 734 SHALL first process this option according to [RFC7959], until all 735 blocks of the OSCORE message have been received, or the cumulated 736 message size of the blocks exceeds MAX_UNFRAGMENTED_SIZE. In the 737 former case, the processing of the OSCORE message continues as 738 defined in this document. In the latter case the message SHALL be 739 discarded. 741 Because of encryption of Uri-Path and Uri-Query, messages to the same 742 server may, from the point of view of a proxy, look like they also 743 target the same resource. A proxy SHOULD mitigate a potential mix-up 744 of blocks from concurrent requests to the same server, for example 745 using the Request-Tag processing specified in Section 3.3.2 of 746 [I-D.ietf-core-echo-request-tag]. 748 4.1.3.3. Proxy-Uri 750 Proxy-Uri, when present, is split by OSCORE into class U options and 751 class E options, which are processed accordingly. When Proxy-Uri is 752 used in the original CoAP message, Uri-* are not present [RFC7252]. 754 The sending endpoint SHALL first decompose the Proxy-Uri value of the 755 original CoAP message into the Proxy-Scheme, Uri-Host, Uri-Port, Uri- 756 Path, and Uri-Query options (if present) according to Section 6.4 of 757 [RFC7252]. 759 Uri-Path and Uri-Query are class E options and SHALL be protected and 760 processed as Inner options (Section 4.1.1). 762 The Proxy-Uri option of the OSCORE message SHALL be set to the 763 composition of Proxy-Scheme, Uri-Host, and Uri-Port options (if 764 present) as specified in Section 6.5 of [RFC7252], and processed as 765 an Outer option of Class U (Section 4.1.2). 767 Note that replacing the Proxy-Uri value with the Proxy-Scheme and 768 Uri-* options works by design for all CoAP URIs (see Section 6 of 769 [RFC7252]). OSCORE-aware HTTP servers should not use the userinfo 770 component of the HTTP URI (as defined in Section 3.2.1 of [RFC3986]), 771 so that this type of replacement is possible in the presence of CoAP- 772 to-HTTP proxies. In future documents specifying cross-protocol 773 proxying behavior using different URI structures, it is expected that 774 the authors will create Uri-* options that allow decomposing the 775 Proxy-Uri, and specify in which OSCORE class they belong. 777 An example of how Proxy-Uri is processed is given here. Assume that 778 the original CoAP message contains: 780 o Proxy-Uri = "coap://example.com/resource?q=1" 782 During OSCORE processing, Proxy-Uri is split into: 784 o Proxy-Scheme = "coap" 786 o Uri-Host = "example.com" 788 o Uri-Port = "5683" 789 o Uri-Path = "resource" 791 o Uri-Query = "q=1" 793 Uri-Path and Uri-Query follow the processing defined in 794 Section 4.1.1, and are thus encrypted and transported in the COSE 795 object. The remaining options are composed into the Proxy-Uri 796 included in the options part of the OSCORE message, which has value: 798 o Proxy-Uri = "coap://example.com" 800 See Sections 6.1 and 12.6 of [RFC7252] for more information. 802 4.1.3.4. Observe 804 Observe [RFC7641] is an optional feature. An implementation MAY 805 support [RFC7252] and the Object-Security option without supporting 806 [RFC7641]. The Observe option as used here targets the requirements 807 on forwarding of [I-D.hartke-core-e2e-security-reqs] (Section 2.2.1). 809 In order for an OSCORE-unaware proxy to support forwarding of Observe 810 messages [RFC7641], there SHALL be an Outer Observe option, i.e., 811 present in the options part of the OSCORE message. The processing of 812 the CoAP Code for Observe messages is described in Section 4.2. 814 To secure the order of notifications, the client SHALL maintain a 815 Notification Number for each Observation it registers. The 816 Notification Number is a non-negative integer containing the largest 817 Partial IV of the successfully received notifications for the 818 associated Observe registration (see Section 7.4). The Notification 819 Number is initialized to the Partial IV of the first successfully 820 received notification response to the registration request. In 821 contrast to [RFC7641], the received Partial IV MUST always be 822 compared with the Notification Number, which thus MUST NOT be 823 forgotten after 128 seconds. The client MAY ignore the Observe 824 option value. 826 If the verification fails, the client SHALL stop processing the 827 response. 829 The Observe option in the CoAP request may be legitimately removed by 830 a proxy. If the Observe option is removed from a CoAP request by a 831 proxy, then the server can still verify the request (as a non-Observe 832 request), and produce a non-Observe response. If the OSCORE client 833 receives a response to an Observe request without an Outer Observe 834 value, then it MUST verify the response as a non-Observe response. 835 If the OSCORE client receives a response to a non-Observe request 836 with an Outer Observe value, it stops processing the message, as 837 specified in Section 8.4. 839 Clients can re-register observations to ensure that the observation 840 is still active and establish freshness again ([RFC7641] 841 Section 3.3.1). When an OSCORE observation is refreshed, not only 842 the ETags, but also the partial IV (and thus the payload and Object- 843 Security option) change. The server uses the new request's Partial 844 IV as the 'request_piv' of new responses. 846 4.1.3.5. No-Response 848 No-Response is defined in [RFC7967]. Clients using No-Response MUST 849 set both an Inner (Class E) and an Outer (Class U) No-Response 850 option, with same value. 852 The Inner No-Response option is used to communicate to the server the 853 client's disinterest in certain classes of responses to a particular 854 request. The Inner No-Response SHALL be processed by OSCORE as 855 specified in Section 4.1.1. 857 The Outer No-Response option is used to support proxy functionality, 858 specifically to avoid error transmissions from proxies to clients, 859 and to avoid bandwidth reduction to servers by proxies applying 860 congestion control when not receiving responses. The Outer No- 861 Response option is processed according to Section 4.1.2. 863 In particular, step 8 of Section 8.4 is applied to No-Response. 865 Applications should consider that a proxy may remove the Outer No- 866 Response option from the request. Applications using No-Response can 867 specify policies to deal with cases where servers receive an Inner 868 No-Response option only, which may be the result of the request 869 having traversed a No-Response unaware proxy, and update the 870 processing in Section 8.4 accordingly. This avoids unnecessary error 871 responses to clients and bandwidth reductions to servers, due to No- 872 Response unaware proxies. 874 4.1.3.6. Object-Security 876 The Object-Security option is only defined to be present in OSCORE 877 messages, as an indication that OSCORE processing have been 878 performed. The content in the Object-Security option is neither 879 encrypted nor integrity protected as a whole but some part of the 880 content of this option is protected (see Section 5.4). "OSCORE 881 within OSCORE" is not supported: If OSCORE processing detects an 882 Object-Security option in the original CoAP message, then processing 883 SHALL be stopped. 885 4.2. CoAP Header Fields and Payload 887 A summary of how the CoAP header fields and payload are protected is 888 shown in Figure 6, including fields specific to CoAP over UDP and 889 CoAP over TCP (marked accordingly in the table). 891 +------------------+---+---+ 892 | Field | E | U | 893 +------------------+---+---+ 894 | Version (UDP) | | x | 895 | Type (UDP) | | x | 896 | Length (TCP) | | x | 897 | Token Length | | x | 898 | Code | x | | 899 | Message ID (UDP) | | x | 900 | Token | | x | 901 | Payload | x | | 902 +------------------+---+---+ 904 E = Encrypt and Integrity Protect (Inner) 905 U = Unprotected (Outer) 907 Figure 6: Protection of CoAP Header Fields and Payload 909 Most CoAP Header fields (i.e. the message fields in the fixed 4-byte 910 header) are required to be read and/or changed by CoAP proxies and 911 thus cannot in general be protected end-to-end between the endpoints. 912 As mentioned in Section 1, OSCORE protects the CoAP Request/Response 913 layer only, and not the Messaging Layer (Section 2 of [RFC7252]), so 914 fields such as Type and Message ID are not protected with OSCORE. 916 The CoAP Header field Code is protected by OSCORE. Code SHALL be 917 encrypted and integrity protected (Class E) to prevent an 918 intermediary from eavesdropping on or manipulating the Code (e.g., 919 changing from GET to DELETE). 921 The sending endpoint SHALL write the Code of the original CoAP 922 message into the plaintext of the COSE object (see Section 5.3). 923 After that, the Outer Code of the OSCORE message SHALL be set to 0.02 924 (POST) for requests without Observe option, to 0.05 (FETCH) for 925 requests with Observe option, and to 2.04 (Changed) for responses. 926 Using FETCH with Observe allows OSCORE to be compliant with the 927 Observe processing in OSCORE-unaware proxies. The choice of POST and 928 FETCH [RFC8132] allows all OSCORE messages to have payload. 930 The receiving endpoint SHALL discard the Code in the OSCORE message 931 and write the Code of the plaintext in the COSE object (Section 5.3) 932 into the decrypted CoAP message. 934 The other currently defined CoAP Header fields are Unprotected (Class 935 U). The sending endpoint SHALL write all other header fields of the 936 original message into the header of the OSCORE message. The 937 receiving endpoint SHALL write the header fields from the received 938 OSCORE message into the header of the decrypted CoAP message. 940 The CoAP Payload, if present in the original CoAP message, SHALL be 941 encrypted and integrity protected and is thus an Inner message field. 942 The sending endpoint writes the payload of the original CoAP message 943 into the plaintext (Section 5.3) input to the COSE object. The 944 receiving endpoint verifies and decrypts the COSE object, and 945 recreates the payload of the original CoAP message. 947 4.3. Signaling Messages 949 Signaling messages (CoAP Code 7.00-7.31) were introduced to exchange 950 information related to an underlying transport connection in the 951 specific case of CoAP over reliable transports [RFC8323]. 953 OSCORE MAY be used to protect Signaling if the endpoints for OSCORE 954 coincide with the endpoints for the signaling message. If OSCORE is 955 used to protect Signaling then: 957 o To comply with [RFC8323], an initial empty CSM message SHALL be 958 sent. The subsequent signaling message SHALL be protected. 960 o Signaling messages SHALL be protected as CoAP Request messages, 961 except in the case the Signaling message is a response to a 962 previous Signaling message, in which case it SHALL be protected as 963 a CoAP Response message. For example, 7.02 (Ping) is protected as 964 a CoAP Request and 7.03 (Pong) as a CoAP response. 966 o The Outer Code for Signaling messages SHALL be set to 0.02 (POST), 967 unless it is a response to a previous Signaling message, in which 968 case it SHALL be set to 2.04 (Changed). 970 o All Signaling options, except the Object-Security option, SHALL be 971 Inner (Class E). 973 NOTE: Option numbers for Signaling messages are specific to the CoAP 974 Code (see Section 5.2 of [RFC8323]). 976 If OSCORE is not used to protect Signaling, Signaling messages SHALL 977 be unaltered by OSCORE. 979 5. The COSE Object 981 This section defines how to use COSE [RFC8152] to wrap and protect 982 data in the original message. OSCORE uses the untagged COSE_Encrypt0 983 structure with an Authenticated Encryption with Additional Data 984 (AEAD) algorithm. The key lengths, IV length, nonce length, and 985 maximum Sender Sequence Number are algorithm dependent. 987 The AEAD algorithm AES-CCM-16-64-128 defined in Section 10.2 of 988 [RFC8152] is mandatory to implement. For AES-CCM-16-64-128 the 989 length of Sender Key and Recipient Key is 128 bits, the length of 990 nonce and Common IV is 13 bytes. The maximum Sender Sequence Number 991 is specified in Section 11. 993 As specified in [RFC5116], plaintext denotes the data that is to be 994 encrypted and integrity protected, and Additional Authenticated Data 995 (AAD) denotes the data that is to be integrity protected only. 997 The COSE Object SHALL be a COSE_Encrypt0 object with fields defined 998 as follows 1000 o The 'protected' field is empty. 1002 o The 'unprotected' field includes: 1004 * The 'Partial IV' parameter. The value is set to the Sender 1005 Sequence Number. All leading zeroes SHALL be removed when 1006 encoding the Partial IV, except in the case of value 0 which is 1007 encoded to the byte string 0x00. This parameter SHALL be 1008 present in requests. In case of Observe (Section 4.1.3.4) the 1009 Partial IV SHALL be present in responses, and otherwise the 1010 Partial IV will not typically be present in responses. (A non- 1011 Observe example where the Partial IV is included in a response 1012 is provided in Section 7.5.2.) 1014 * The 'kid' parameter. The value is set to the Sender ID. This 1015 parameter SHALL be present in requests and will not typically 1016 be present in responses. An example where the Sender ID is 1017 included in a response is the extension of OSCORE to group 1018 communication [I-D.ietf-core-oscore-groupcomm]. 1020 * Optionally, a 'kid context' parameter as defined in 1021 Section 5.1. This parameter MAY be present in requests and 1022 SHALL NOT be present in responses. 1024 o The 'ciphertext' field is computed from the secret key (Sender Key 1025 or Recipient Key), AEAD nonce (see Section 5.2), plaintext (see 1026 Section 5.3), and the Additional Authenticated Data (AAD) (see 1027 Section 5.4) following Section 5.2 of [RFC8152]. 1029 The encryption process is described in Section 5.3 of [RFC8152]. 1031 5.1. Kid Context 1033 For certain use cases, e.g. deployments where the same kid is used 1034 with multiple contexts, it is necessary or favorable for the sender 1035 to provide an additional identifier of the security material to use, 1036 in order for the receiver to retrieve or establish the correct key. 1037 The kid context parameter is used to provide such additional input. 1038 The kid context and kid are used to determine the security context, 1039 or to establish the necessary input parameters to derive the security 1040 context (see Section 3.2). The application defines how this is done. 1042 The kid context is implicitly integrity protected, as manipulation 1043 that leads to the wrong key (or no key) being retrieved which results 1044 in an error, as described in Section 8.2. 1046 A summary of the COSE header parameter kid context defined above can 1047 be found in Figure 7. 1049 Some examples of relevant uses of kid context are the following: 1051 o If the client has an identifier in some other namespace which can 1052 be used by the server to retrieve or establish the security 1053 context, then that identifier can be used as kid context. The kid 1054 context may be used as Master Salt (Section 3.1) for additional 1055 entropy of the security contexts (see for example Appendix B.2 or 1056 [I-D.ietf-6tisch-minimal-security]). 1058 o In case of a group communication scenario 1059 [I-D.ietf-core-oscore-groupcomm], if the server belongs to 1060 multiple groups, then a group identifier can be used as kid 1061 context to enable the server to find the right security context. 1063 +----------+--------+------------+----------------+-----------------+ 1064 | name | label | value type | value registry | description | 1065 +----------+--------+------------+----------------+-----------------+ 1066 | kid | kidctx | bstr | | Identifies the | 1067 | context | | | | kid context | 1068 +----------+--------+------------+----------------+-----------------+ 1070 Figure 7: Additional common header parameter for the COSE object 1072 5.2. Nonce 1074 The AEAD nonce is constructed in the following way (see Figure 8): 1076 1. left-padding the Partial IV (in network byte order) with zeroes 1077 to exactly 5 bytes, 1079 2. left-padding the (Sender) ID of the endpoint that generated the 1080 Partial IV (in network byte order) with zeroes to exactly nonce 1081 length - 6 bytes, 1083 3. concatenating the size of the ID (S) with the padded ID and the 1084 padded Partial IV, 1086 4. and then XORing with the Common IV. 1088 Note that in this specification only algorithms that use nonces equal 1089 or greater than 7 bytes are supported. The nonce construction with 1090 S, ID of PIV generator, and Partial IV together with endpoint unique 1091 IDs and encryption keys make it easy to verify that the nonces used 1092 with a specific key will be unique. 1094 When Observe is not used, the request and the response may use the 1095 same nonce. In this way, the Partial IV does not have to be sent in 1096 responses, which reduces the size. For processing instructions see 1097 Section 8. 1099 +---+-----------------------+--+--+--+--+--+ 1100 | S | ID of PIV generator | Partial IV |----+ 1101 +---+-----------------------+--+--+--+--+--+ | 1102 | 1103 +------------------------------------------+ | 1104 | Common IV |->(XOR) 1105 +------------------------------------------+ | 1106 | 1107 +------------------------------------------+ | 1108 | Nonce |<---+ 1109 +------------------------------------------+ 1111 Figure 8: AEAD Nonce Formation 1113 5.3. Plaintext 1115 The plaintext is formatted as a CoAP message without Header (see 1116 Figure 9) consisting of: 1118 o the Code of the original CoAP message as defined in Section 3 of 1119 [RFC7252]; and 1121 o all Inner option message fields (see Section 4.1.1) present in the 1122 original CoAP message (see Section 4.1). The options are encoded 1123 as described in Section 3.1 of [RFC7252], where the delta is the 1124 difference to the previously included instance of Class E option; 1125 and 1127 o the Payload of original CoAP message, if present, and in that case 1128 prefixed by the one-byte Payload Marker (0xFF). 1130 0 1 2 3 1131 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 1132 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1133 | Code | Class E options (if any) ... 1134 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1135 |1 1 1 1 1 1 1 1| Payload (if any) ... 1136 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1137 (only if there 1138 is payload) 1140 Figure 9: Plaintext 1142 NOTE: The plaintext contains all CoAP data that needs to be encrypted 1143 end-to-end between the endpoints. 1145 5.4. Additional Authenticated Data 1147 The external_aad SHALL be a CBOR array as defined below: 1149 external_aad = [ 1150 oscore_version : uint, 1151 algorithms : [ alg_aead : int / tstr ], 1152 request_kid : bstr, 1153 request_piv : bstr, 1154 options : bstr 1155 ] 1157 where: 1159 o oscore_version: contains the OSCORE version number. 1160 Implementations of this specification MUST set this field to 1. 1161 Other values are reserved for future versions. 1163 o algorithms: contains (for extensibility) an array of algorithms, 1164 according to this specification only containing alg_aead. 1166 o alg_aead: contains the AEAD Algorithm from the security context 1167 used for the exchange (see Section 3.1). 1169 o request_kid: contains the value of the 'kid' in the COSE object of 1170 the request (see Section 5). 1172 o request_piv: contains the value of the 'Partial IV' in the COSE 1173 object of the request (see Section 5). 1175 o options: contains the Class I options (see Section 4.1.2) present 1176 in the original CoAP message encoded as described in Section 3.1 1177 of [RFC7252], where the delta is the difference to the previously 1178 included instance of class I option. 1180 NOTE: The format of the external_aad is for simplicity the same for 1181 requests and responses, although some parameters, e.g. request_kid 1182 need not be integrity protected in the requests. 1184 6. OSCORE Header Compression 1186 The Concise Binary Object Representation (CBOR) [RFC7049] combines 1187 very small message sizes with extensibility. The CBOR Object Signing 1188 and Encryption (COSE) [RFC8152] uses CBOR to create compact encoding 1189 of signed and encrypted data. COSE is however constructed to support 1190 a large number of different stateless use cases, and is not fully 1191 optimized for use as a stateful security protocol, leading to a 1192 larger than necessary message expansion. In this section, we define 1193 a stateless header compression mechanism, simply removing redundant 1194 information from the COSE objects, which significantly reduces the 1195 per-packet overhead. The result of applying this mechanism to a COSE 1196 object is called the "compressed COSE object". 1198 The COSE_Encrypt0 object used in OSCORE is transported in the Object- 1199 Security option and in the Payload. The Payload contains the 1200 Ciphertext and the headers of the COSE object are compactly encoded 1201 as described in the next section. 1203 6.1. Encoding of the Object-Security Value 1205 The value of the Object-Security option SHALL contain the OSCORE flag 1206 bits, the Partial IV parameter, the kid context parameter (length and 1207 value), and the kid parameter as follows: 1209 0 1 2 3 4 5 6 7 <--------- n bytes -------------> 1210 +-+-+-+-+-+-+-+-+--------------------------------- 1211 |0 0 0|h|k| n | Partial IV (if any) ... 1212 +-+-+-+-+-+-+-+-+--------------------------------- 1214 <- 1 byte -> <------ s bytes -----> 1215 +------------+----------------------+------------------+ 1216 | s (if any) | kid context (if any) | kid (if any) ... | 1217 +------------+----------------------+------------------+ 1219 Figure 10: Object-Security Value 1221 o The first byte of flag bits encodes the following set of flags and 1222 the length of the Partial IV parameter: 1224 * The three least significant bits encode the Partial IV length 1225 n. If n = 0 then the Partial IV is not present in the 1226 compressed COSE object. The values n = 6 and n = 7 are 1227 reserved. 1229 * The fourth least significant bit is the kid flag, k: it is set 1230 to 1 if the kid is present in the compressed COSE object. 1232 * The fifth least significant bit is the kid context flag, h: it 1233 is set to 1 if the compressed COSE object contains a kid 1234 context (see Section 5.1). 1236 * The sixth to eighth least significant bits are reserved for 1237 future use. These bits SHALL be set to zero when not in use. 1238 According to this specification, if any of these bits are set 1239 to 1 the message is considered to be malformed and 1240 decompression fails as specified in item 3 of Section 8.2. 1242 o The following n bytes encode the value of the Partial IV, if the 1243 Partial IV is present (n > 0). 1245 o The following 1 byte encode the length of the kid context 1246 (Section 5.1) s, if the kid context flag is set (h = 1). 1248 o The following s bytes encode the kid context, if the kid context 1249 flag is set (h = 1). 1251 o The remaining bytes encode the value of the kid, if the kid is 1252 present (k = 1). 1254 Note that the kid MUST be the last field of the object-security 1255 value, even in case reserved bits are used and additional fields are 1256 added to it. 1258 The length of the Object-Security option thus depends on the presence 1259 and length of Partial IV, kid context, kid, as specified in this 1260 section, and on the presence and length of the other parameters, as 1261 defined in the separate documents. 1263 6.2. Encoding of the OSCORE Payload 1265 The payload of the OSCORE message SHALL encode the ciphertext of the 1266 COSE object. 1268 6.3. Examples of Compressed COSE Objects 1270 This section covers a list of OSCORE Header Compression examples for 1271 requests and responses. The examples assume the COSE_Encrypt0 object 1272 is set (which means the CoAP message and cryptographic material is 1273 known). Note that the full CoAP unprotected message, as well as the 1274 full security context, is not reported in the examples, but only the 1275 input necessary to the compression mechanism, i.e. the COSE_Encrypt0 1276 object. The output is the compressed COSE object as defined in 1277 Section 6, divided into two parts, since the object is transported in 1278 two CoAP fields: Object-Security option value and CoAP payload. 1280 6.3.1. Examples: Requests 1282 1. Request with ciphertext = 0xaea0155667924dff8a24e4cb35b9, kid = 1283 0x25 and Partial IV = 0x05 1285 Before compression (24 bytes): 1287 [ 1288 h'', 1289 { 4:h'25', 6:h'05' }, 1290 h'aea0155667924dff8a24e4cb35b9' 1291 ] 1293 After compression (17 bytes): 1295 Flag byte: 0b00001001 = 0x09 1297 Option Value: 09 05 25 (3 bytes) 1299 Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) 1301 2. Request with ciphertext = 0xaea0155667924dff8a24e4cb35b9, kid = 1302 empty string and Partial IV = 0x00 1304 Before compression (23 bytes): 1306 [ 1307 h'', 1308 { 4:h'', 6:h'00' }, 1309 h'aea0155667924dff8a24e4cb35b9' 1310 ] 1312 After compression (16 bytes): 1314 Flag byte: 0b00001001 = 0x09 1316 Option Value: 09 00 (2 bytes) 1318 Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) 1320 3. Request with ciphertext = 0xaea0155667924dff8a24e4cb35b9, kid = 1321 empty string, Partial IV = 0x05, and kid context = 0x44616c656b 1323 Before compression (30 bytes): 1325 [ 1326 h'', 1327 { 4:h'', 6:h'05', 8:h'44616c656b' }, 1328 h'aea0155667924dff8a24e4cb35b9' 1329 ] 1331 After compression (22 bytes): 1333 Flag byte: 0b00011001 = 0x19 1335 Option Value: 19 05 05 44 61 6c 65 6b (8 bytes) 1337 Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) 1339 6.3.2. Example: Response (without Observe) 1341 1. Response not including an Observe option, with ciphertext = 1342 0xaea0155667924dff8a24e4cb35b9 1344 Before compression (18 bytes): 1346 [ 1347 h'', 1348 {}, 1349 h'aea0155667924dff8a24e4cb35b9' 1350 ] 1352 After compression (14 bytes): 1354 Flag byte: 0b00000000 = 0x00 1356 Option Value: (0 bytes) 1358 Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) 1360 6.3.3. Example: Response (with Observe) 1362 1. Response including an Observe option, with ciphertext = 1363 0xaea0155667924dff8a24e4cb35b9 and Partial IV = 0x07 1365 Before compression (21 bytes): 1367 [ 1368 h'', 1369 { 6:h'07' }, 1370 h'aea0155667924dff8a24e4cb35b9' 1371 ] 1373 After compression (16 bytes): 1375 Flag byte: 0b00000001 = 0x01 1377 Option Value: 01 07 (2 bytes) 1379 Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) 1381 7. Sequence Numbers, Replay, Message Binding, and Freshness 1383 7.1. Message Binding 1385 In order to prevent response delay and mismatch attacks 1386 [I-D.mattsson-core-coap-actuators] from on-path attackers and 1387 compromised proxies, OSCORE binds responses to the requests by 1388 including the kid and Partial IV of the request in the AAD of the 1389 response. The server therefore needs to store the kid and Partial IV 1390 of the request until all responses have been sent. 1392 7.2. AEAD Nonce Uniqueness 1394 An AEAD nonce MUST NOT be used more than once per AEAD key. In order 1395 to assure unique nonces, each Sender Context contains a Sender 1396 Sequence Number used to protect requests, and - in case of Observe - 1397 responses. If messages are processed concurrently, the operation of 1398 reading and increasing the Sender Sequence Number MUST be atomic. 1400 The maximum Sender Sequence Number is algorithm dependent (see 1401 Section 11), and SHALL be less than 2^40. If the Sender Sequence 1402 Number exceeds the maximum, the endpoint MUST NOT process any more 1403 messages with the given Sender Context. The endpoint SHOULD acquire 1404 a new security context (and consequently inform the other endpoint) 1405 before this happens. The latter is out of scope of this document. 1407 7.3. Freshness 1409 For requests, OSCORE provides only the guarantee that the request is 1410 not older than the security context. For applications having 1411 stronger demands on request freshness (e.g., control of actuators), 1412 OSCORE needs to be augmented with mechanisms providing freshness, for 1413 example as specified in [I-D.ietf-core-echo-request-tag]. 1415 For responses, the message binding guarantees that a response is not 1416 older than its request. For responses without Observe, this gives 1417 strong absolute freshness. For responses with Observe, the absolute 1418 freshness gets weaker with time, and it is RECOMMENDED that the 1419 client regularly re-register the observation. 1421 For requests, and responses with Observe, OSCORE also provides 1422 relative freshness in the sense that the received Partial IV allows a 1423 recipient to determine the relative order of responses. 1425 7.4. Replay Protection 1427 In order to protect from replay of requests, the server's Recipient 1428 Context includes a Replay Window. A server SHALL verify that a 1429 Partial IV received in the COSE object has not been received before. 1430 If this verification fails the server SHALL stop processing the 1431 message, and MAY optionally respond with a 4.01 Unauthorized error 1432 message. Also, the server MAY set an Outer Max-Age option with value 1433 zero. The diagnostic payload MAY contain the "Replay detected" 1434 string. The size and type of the Replay Window depends on the use 1435 case and the protocol with which the OSCORE message is transported. 1436 In case of reliable and ordered transport from endpoint to endpoint, 1437 e.g. TCP, the server MAY just store the last received Partial IV and 1438 require that newly received Partial IVs equals the last received 1439 Partial IV + 1. However, in case of mixed reliable and unreliable 1440 transports and where messages may be lost, such a replay mechanism 1441 may be too restrictive and the default replay window be more suitable 1442 (see Section 3.2.2). 1444 Responses to non-Observe requests are protected against replay as 1445 they are cryptographically bound to the request. 1447 In the case of Observe, a client receiving a notification SHALL 1448 verify that the Partial IV of a received notification is greater than 1449 the Notification Number bound to that Observe registration. If the 1450 verification fails, the client SHALL stop processing the response. 1451 If the verification succeeds, the client SHALL overwrite the 1452 corresponding Notification Number with the received Partial IV. 1454 If messages are processed concurrently, the Partial IV needs to be 1455 validated a second time after decryption and before updating the 1456 replay protection data. The operation of validating the Partial IV 1457 and updating the replay protection data MUST be atomic. 1459 7.5. Losing Part of the Context State 1461 To prevent reuse of the AEAD nonce with the same key, or from 1462 accepting replayed messages, an endpoint needs to handle the 1463 situation of losing rapidly changing parts of the context, such as 1464 the request Token, Sender Sequence Number, Replay Window, and 1465 Notification Numbers. These are typically stored in RAM and 1466 therefore lost in the case of an unplanned reboot. 1468 After boot, an endpoint MAY reject to use pre-existing security 1469 contexts, and MAY establish a new security context with each endpoint 1470 it communicates with. However, establishing a fresh security context 1471 may have a non-negligible cost in terms of, e.g., power consumption. 1473 After boot, an endpoint MAY use a partly persistently stored security 1474 context, but then the endpoint MUST NOT reuse a previous Sender 1475 Sequence Number and MUST NOT accept previously accepted messages. 1476 Some ways to achieve this are described in the following sections. 1478 7.5.1. Sequence Number 1480 To prevent reuse of Sender Sequence Numbers, an endpoint MAY perform 1481 the following procedure during normal operations: 1483 o Each time the Sender Sequence Number is evenly divisible by K, 1484 where K is a positive integer, store the Sender Sequence Number in 1485 persistent memory. After boot, the endpoint initiates the Sender 1486 Sequence Number to the value stored in persistent memory + K - 1. 1487 Storing to persistent memory can be costly. The value K gives a 1488 trade-off between the number of storage operations and efficient 1489 use of Sender Sequence Numbers. 1491 7.5.2. Replay Window 1493 To prevent accepting replay of previously received requests, the 1494 server MAY perform the following procedure after boot: 1496 o For each stored security context, the first time after boot the 1497 server receives an OSCORE request, the server responds with the 1498 Echo option [I-D.ietf-core-echo-request-tag] to get a request with 1499 verifiable freshness. The server MUST use its Partial IV when 1500 generating the AEAD nonce and MUST include the Partial IV in the 1501 response. 1503 If the server using the Echo option can verify a second request as 1504 fresh, then the Partial IV of the second request is set as the lower 1505 limit of the replay window. 1507 7.5.3. Replay Protection of Observe Notifications 1509 To prevent accepting replay of previously received notification 1510 responses, the client MAY perform the following procedure after boot: 1512 o The client rejects notifications bound to the earlier 1513 registration, removes all Notification Numbers and re-registers 1514 using Observe. 1516 8. Processing 1518 This section describes the OSCORE message processing. 1520 8.1. Protecting the Request 1522 Given a CoAP request, the client SHALL perform the following steps to 1523 create an OSCORE request: 1525 1. Retrieve the Sender Context associated with the target resource. 1527 2. Compose the Additional Authenticated Data and the plaintext, as 1528 described in Section 5.4 and Section 5.3. 1530 3. Compute the AEAD nonce from the Sender ID, Common IV, and Partial 1531 IV (Sender Sequence Number in network byte order) as described in 1532 Section 5.2 and (in one atomic operation, see Section 7.2) 1533 increment the Sender Sequence Number by one. 1535 4. Encrypt the COSE object using the Sender Key. Compress the COSE 1536 Object as specified in Section 6. 1538 5. Format the OSCORE message according to Section 4. The Object- 1539 Security option is added (see Section 4.1.2). 1541 6. Store the association Token - Security Context, in order to be 1542 able to find the Recipient Context from the Token in the 1543 response. 1545 8.2. Verifying the Request 1547 A server receiving a request containing the Object-Security option 1548 SHALL perform the following steps: 1550 1. Process Outer Block options according to [RFC7959], until all 1551 blocks of the request have been received (see Section 4.1.3.2). 1553 2. Discard the message Code and all non-special Inner option 1554 message fields (marked with 'x' in column E of Figure 5) present 1555 in the received message. For example, an If-Match Outer option 1556 is discarded, but an Uri-Host Outer option is not discarded. 1558 3. Decompress the COSE Object (Section 6) and retrieve the 1559 Recipient Context associated with the Recipient ID in the 'kid' 1560 parameter. If either the decompression or the COSE message 1561 fails to decode, or the server fails to retrieve a Recipient 1562 Context with Recipient ID corresponding to the 'kid' parameter 1563 received, then the server SHALL stop processing the request. 1564 If: 1566 * either the decompression or the COSE message fails to decode, 1567 the server MAY respond with a 4.02 Bad Option error message. 1568 The server MAY set an Outer Max-Age option with value zero. 1569 The diagnostic payload SHOULD contain the string "Failed to 1570 decode COSE". 1572 * the server fails to retrieve a Recipient Context with 1573 Recipient ID corresponding to the 'kid' parameter received, 1574 the server MAY respond with a 4.01 Unauthorized error 1575 message. The server MAY set an Outer Max-Age option with 1576 value zero. The diagnostic payload SHOULD contain the string 1577 "Security context not found". 1579 4. Verify the 'Partial IV' parameter using the Replay Window, as 1580 described in Section 7.4. 1582 5. Compose the Additional Authenticated Data, as described in 1583 Section 5.4. 1585 6. Compute the AEAD nonce from the Recipient ID, Common IV, and the 1586 'Partial IV' parameter, received in the COSE Object. 1588 7. Decrypt the COSE object using the Recipient Key, as per 1589 [RFC8152] Section 5.3. (The decrypt operation includes the 1590 verification of the integrity.) 1591 * If decryption fails, the server MUST stop processing the 1592 request and MAY respond with a 4.00 Bad Request error 1593 message. The server MAY set an Outer Max-Age option with 1594 value zero. The diagnostic payload MAY contain the 1595 "Decryption failed" string. 1597 * If decryption succeeds, update the Replay Window, as 1598 described in Section 7. 1600 8. For each decrypted option, check if the option is also present 1601 as an Outer option: if it is, discard the Outer. For example: 1602 the message contains a Max-Age Inner and a Max-Age Outer option. 1603 The Outer Max-Age is discarded. 1605 9. Add decrypted code, options and payload to the decrypted 1606 request. The Object-Security option is removed. 1608 10. The decrypted CoAP request is processed according to [RFC7252]. 1610 8.3. Protecting the Response 1612 If a CoAP response is generated in response to an OSCORE request, the 1613 server SHALL perform the following steps to create an OSCORE 1614 response. Note that CoAP error responses derived from CoAP 1615 processing (point 10. in Section 8.2) are protected, as well as 1616 successful CoAP responses, while the OSCORE errors (point 3, 4, and 7 1617 in Section 8.2) do not follow the processing below, but are sent as 1618 simple CoAP responses, without OSCORE processing. 1620 1. Retrieve the Sender Context in the Security Context used to 1621 verify the request. 1623 2. Compose the Additional Authenticated Data and the plaintext, as 1624 described in Section 5.4 and Section 5.3. 1626 3. Compute the AEAD nonce 1628 * If Observe is used, compute the nonce from the Sender ID, 1629 Common IV, and Partial IV (Sender Sequence Number in network 1630 byte order). Then (in one atomic operation, see Section 7.2) 1631 increment the Sender Sequence Number by one. 1633 * If Observe is not used, either the nonce from the request is 1634 used or a new Partial IV is used (see bullet on 'Partial IV' 1635 in Section 5). 1637 4. Encrypt the COSE object using the Sender Key. Compress the COSE 1638 Object as specified in Section 6. If the AEAD nonce was 1639 constructed from a new Partial IV, this Partial IV MUST be 1640 included in the message. If the AEAD nonce from the request was 1641 used, the Partial IV MUST NOT be included in the message. 1643 5. Format the OSCORE message according to Section 4. The Object- 1644 Security option is added (see Section 4.1.2). 1646 8.4. Verifying the Response 1648 A client receiving a response containing the Object-Security option 1649 SHALL perform the following steps: 1651 1. Process Outer Block options according to [RFC7959], until all 1652 blocks of the OSCORE message have been received (see 1653 Section 4.1.3.2). 1655 2. Discard the message Code and all non-special Class E options 1656 from the message. For example, ETag Outer option is discarded, 1657 Max-Age Outer option is not discarded. 1659 3. Retrieve the Recipient Context associated with the Token. 1660 Decompress the COSE Object (Section 6). If either the 1661 decompression or the COSE message fails to decode, then go to 1662 11. 1664 4. For Observe notifications, verify the received 'Partial IV' 1665 parameter against the corresponding Notification Number as 1666 described in Section 7.4. If the client receives a notification 1667 for which no Observe request was sent, then go to 11. 1669 5. Compose the Additional Authenticated Data, as described in 1670 Section 5.4. 1672 6. Compute the AEAD nonce 1674 1. If the Observe option and the Partial IV are not present in 1675 the response, the nonce from the request is used. 1677 2. If the Observe option is present in the response, and the 1678 Partial IV is not present in the response, then go to 11. 1680 3. If the Partial IV is present in the response, compute the 1681 nonce from the Recipient ID, Common IV, and the 'Partial IV' 1682 parameter, received in the COSE Object. 1684 7. Decrypt the COSE object using the Recipient Key, as per 1685 [RFC8152] Section 5.3. (The decrypt operation includes the 1686 verification of the integrity.) 1687 * If decryption fails, then go to 11. 1689 * If decryption succeeds and Observe is used, update the 1690 corresponding Notification Number, as described in Section 7. 1692 8. For each decrypted option, check if the option is also present 1693 as an Outer option: if it is, discard the Outer. For example: 1694 the message contains a Max-Age Inner and a Max-Age Outer option. 1695 The Outer Max-Age is discarded. 1697 9. Add decrypted code, options and payload to the decrypted 1698 request. The Object-Security option is removed. 1700 10. The decrypted CoAP response is processed according to [RFC7252]. 1702 11. In case any of the previous erroneous conditions apply: the 1703 client SHALL stop processing the response. 1705 An error condition occurring while processing a response in an 1706 observation does not cancel the observation. A client MUST NOT react 1707 to failure in step 7 by re-registering the observation immediately. 1709 9. Web Linking 1711 The use of OSCORE MAY be indicated by a target attribute "osc" in a 1712 web link [RFC8288] to a resource. This attribute is a hint 1713 indicating that the destination of that link is to be accessed using 1714 OSCORE. Note that this is simply a hint, it does not include any 1715 security context material or any other information required to run 1716 OSCORE. 1718 A value MUST NOT be given for the "osc" attribute; any present value 1719 MUST be ignored by parsers. The "osc" attribute MUST NOT appear more 1720 than once in a given link-value; occurrences after the first MUST be 1721 ignored by parsers. 1723 10. Proxy and HTTP Operations 1725 RFC 7252 defines operations for a CoAP-to-CoAP proxy (see Section 5.7 1726 of [RFC7252]) and for proxying between CoAP and HTTP (Section 10 of 1727 [RFC7252]). A more detailed description of the HTTP-to-CoAP mapping 1728 is provided by [RFC8075]. This section describes the operations of 1729 OSCORE-aware proxies. 1731 10.1. CoAP-to-CoAP Forwarding Proxy 1733 OSCORE is designed to work with legacy CoAP-to-CoAP forward proxies 1734 [RFC7252], but OSCORE-aware proxies MAY provide certain 1735 simplifications as specified in this section. 1737 Security requirements for forwarding are presented in Section 2.2.1 1738 of [I-D.hartke-core-e2e-security-reqs]. OSCORE complies with the 1739 extended security requirements also addressing Block-wise [RFC7959] 1740 and CoAP-mappable HTTP. In particular caching is disabled since the 1741 CoAP response is only applicable to the original CoAP request. An 1742 OSCORE-aware proxy SHALL NOT cache a response to a request with an 1743 Object-Security option. As a consequence, the search for cache hits 1744 and CoAP freshness/Max-Age processing can be omitted. 1746 Proxy processing of the (Outer) Proxy-Uri option is as defined in 1747 [RFC7252]. 1749 Proxy processing of the (Outer) Block options is as defined in 1750 [RFC7959]. 1752 Proxy processing of the (Outer) Observe option is as defined in 1753 [RFC7641]. OSCORE-aware proxies MAY look at the Partial IV value 1754 instead of the Outer Observe option. 1756 10.2. HTTP Processing 1758 In order to use OSCORE over HTTP hops, a node needs to be able to map 1759 HTTP messages to CoAP messages (see [RFC8075]), and to apply OSCORE 1760 to CoAP messages (as defined in this document). 1762 For this purpose, this specification defines a new HTTP header field 1763 named CoAP-Object-Security, see Section 12.4. The CoAP-Object- 1764 Security header field is only used in POST requests and 200 (OK) 1765 responses, i.e. essentially using HTTP as a transport of an encrypted 1766 CoAP mappable message contained in the payload. 1768 The header field is neither appropriate to list in the Connection 1769 header field (see Section 6.1 of [RFC7230]), nor in a Vary response 1770 header field (see Section 7.1.4 of [RFC7231]), nor allowed in 1771 trailers (see Section 4.1 of [RFC7230]). 1773 [Ed. Note: Reconsider use of Vary] 1775 Intermediaries cannot insert, delete, or modify the field's value 1776 without being detected. The header field is not preserved across 1777 redirects. 1779 [Ed. Note: Reconsider support for redirects] 1781 Using the Augmented Backus-Naur Form (ABNF) notation of [RFC5234], 1782 including the following core ABNF syntax rules defined by that 1783 specification: ALPHA (letters) and DIGIT (decimal digits), the CoAP- 1784 Object-Security header field is as follows. 1786 base64-char = ALPHA / DIGIT / "_" / "-" 1788 CoAP-Object-Security = 2*base64-char 1790 A sending endpoint uses [RFC8075] to translate an HTTP message into a 1791 CoAP message. It then protects the message with OSCORE processing, 1792 and adds the Object-Security option (as defined in this document). 1793 Then, the endpoint maps the resulting CoAP message to an HTTP message 1794 that includes the HTTP header field CoAP-Object-Security, whose value 1795 is: 1797 o "" if the CoAP Object-Security option is empty, or 1799 o the value of the CoAP Object-Security option (Section 6.1) in 1800 base64url encoding (Section 5 of [RFC4648]) without padding (see 1801 [RFC7515] Appendix C for implementation notes for this encoding). 1803 Note that the value of the HTTP body is the CoAP payload, i.e. the 1804 OSCORE payload (Section 6.2). 1806 The HTTP header field Content-Type is set to 'application/oscore' 1807 (see Section 12.5). 1809 The resulting message is an OSCORE message that uses HTTP. 1811 A receiving endpoint uses [RFC8075] to translate an HTTP message into 1812 a CoAP message, with the following addition. The HTTP message 1813 includes the CoAP-Object-Security header field, which is mapped to 1814 the CoAP Object-Security option in the following way. The CoAP 1815 Object-Security option value is: 1817 o empty if the value of the HTTP CoAP-Object-Security header field 1818 is a single zero byte (0x00) represented by AA 1820 o the value of the HTTP CoAP-Object-Security header field decoded 1821 from base64url (Section 5 of [RFC4648]) without padding (see 1822 [RFC7515] Appendix C for implementation notes for this decoding). 1824 Note that the value of the CoAP payload is the HTTP body, i.e. the 1825 OSCORE payload (Section 6.2). 1827 The resulting message is an OSCORE message that uses CoAP. 1829 The endpoint can then verify the message according to the OSCORE 1830 processing and get a verified CoAP message. It can then translate 1831 the verified CoAP message into a verified HTTP message. 1833 10.3. HTTP-to-CoAP Translation Proxy 1835 Section 10.2 of [RFC7252] and [RFC8075] specify the behavior of an 1836 HTTP-to-CoAP proxy. As requested in Section 1 of [RFC8075], this 1837 section describes the HTTP mapping for the OSCORE protocol extension 1838 of CoAP. 1840 The presence of the Object-Security option, both in requests and 1841 responses, is expressed in an HTTP header field named CoAP-Object- 1842 Security in the mapped request or response. The value of the field 1843 is: 1845 o AA if the CoAP Object-Security option is empty, or 1847 o the value of the CoAP Object-Security option (Section 6.1) in 1848 base64url encoding (Section 5 of [RFC4648]) without padding (see 1849 [RFC7515] Appendix C for implementation notes for this encoding). 1851 The header field Content-Type 'application/oscore' (see Section 12.5) 1852 is used for OSCORE messages transported in HTTP. The CoAP Content- 1853 Format option is omitted for OSCORE messages transported in CoAP. 1855 The value of the body is the OSCORE payload (Section 6.2). 1857 Example: 1859 Mapping and notation here is based on "Simple Form" (Section 5.4.1.1 1860 of [RFC8075]). 1862 [HTTP request -- Before client object security processing] 1864 GET http://proxy.url/hc/?target_uri=coap://server.url/orders 1865 HTTP/1.1 1867 [HTTP request -- HTTP Client to Proxy] 1869 POST http://proxy.url/hc/?target_uri=coap://server.url/ HTTP/1.1 1870 Content-Type: application/oscore 1871 CoAP-Object-Security: CSU 1872 Body: 09 07 01 13 61 f7 0f d2 97 b1 [binary] 1874 [CoAP request -- Proxy to CoAP Server] 1876 POST coap://server.url/ 1877 Object-Security: 09 25 1878 Payload: 09 07 01 13 61 f7 0f d2 97 b1 [binary] 1880 [CoAP request -- After server object security processing] 1882 GET coap://server.url/orders 1884 [CoAP response -- Before server object security processing] 1886 2.05 Content 1887 Content-Format: 0 1888 Payload: Exterminate! Exterminate! 1890 [CoAP response -- CoAP Server to Proxy] 1892 2.04 Changed 1893 Object-Security: [empty] 1894 Payload: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] 1896 [HTTP response -- Proxy to HTTP Client] 1898 HTTP/1.1 200 OK 1899 Content-Type: application/oscore 1900 CoAP-Object-Security: "" 1901 Body: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] 1903 [HTTP response -- After client object security processing] 1905 HTTP/1.1 200 OK 1906 Content-Type: text/plain 1907 Body: Exterminate! Exterminate! 1909 Note that the HTTP Status Code 200 in the next-to-last message is the 1910 mapping of CoAP Code 2.04 (Changed), whereas the HTTP Status Code 200 1911 in the last message is the mapping of the CoAP Code 2.05 (Content), 1912 which was encrypted within the compressed COSE object carried in the 1913 Body of the HTTP response. 1915 10.4. CoAP-to-HTTP Translation Proxy 1917 Section 10.1 of [RFC7252] describes the behavior of a CoAP-to-HTTP 1918 proxy. RFC 8075 [RFC8075] does not cover this direction in any more 1919 detail and so an example instantiation of Section 10.1 of [RFC7252] 1920 is used below. 1922 Example: 1924 [CoAP request -- Before client object security processing] 1926 GET coap://proxy.url/ 1927 Proxy-Uri=http://server.url/orders 1929 [CoAP request -- CoAP Client to Proxy] 1931 POST coap://proxy.url/ 1932 Proxy-Uri=http://server.url/ 1933 Object-Security: 09 25 1934 Payload: 09 07 01 13 61 f7 0f d2 97 b1 [binary] 1936 [HTTP request -- Proxy to HTTP Server] 1938 POST http://server.url/ HTTP/1.1 1939 Content-Type: application/oscore 1940 CoAP-Object-Security: CSU 1941 Body: 09 07 01 13 61 f7 0f d2 97 b1 [binary] 1943 [HTTP request -- After server object security processing] 1945 GET http://server.url/orders HTTP/1.1 1947 [HTTP response -- Before server object security processing] 1949 HTTP/1.1 200 OK 1950 Content-Type: text/plain 1951 Body: Exterminate! Exterminate! 1953 [HTTP response -- HTTP Server to Proxy] 1955 HTTP/1.1 200 OK 1956 Content-Type: application/oscore 1957 CoAP-Object-Security: "" 1958 Body: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] 1960 [CoAP response - Proxy to CoAP Client] 1962 2.04 Changed 1963 Object-Security: [empty] 1964 Payload: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] 1966 [CoAP response -- After client object security processing] 1968 2.05 Content 1969 Content-Format: 0 1970 Payload: Exterminate! Exterminate! 1972 Note that the HTTP Code 2.04 (Changed) in the next-to-last message is 1973 the mapping of HTTP Status Code 200, whereas the CoAP Code 2.05 1974 (Content) in the last message is the value that was encrypted within 1975 the compressed COSE object carried in the Body of the HTTP response. 1977 11. Security Considerations 1979 11.1. End-to-end protection 1981 In scenarios with intermediary nodes such as proxies or gateways, 1982 transport layer security such as (D)TLS only protects data hop-by- 1983 hop. As a consequence, the intermediary nodes can read and modify 1984 information. The trust model where all intermediary nodes are 1985 considered trustworthy is problematic, not only from a privacy 1986 perspective, but also from a security perspective, as the 1987 intermediaries are free to delete resources on sensors and falsify 1988 commands to actuators (such as "unlock door", "start fire alarm", 1989 "raise bridge"). Even in the rare cases where all the owners of the 1990 intermediary nodes are fully trusted, attacks and data breaches make 1991 such an architecture brittle. 1993 (D)TLS protects hop-by-hop the entire message. OSCORE protects end- 1994 to-end all information that is not required for proxy operations (see 1995 Section 4). (D)TLS and OSCORE can be combined, thereby enabling end- 1996 to-end security of the message payload, in combination with hop-by- 1997 hop protection of the entire message, during transport between end- 1998 point and intermediary node. The CoAP messaging layer, including 1999 header fields such as Type and Message ID, as well as CoAP message 2000 fields Token and Token Length may be changed by a proxy and thus 2001 cannot be protected end-to-end. Error messages occurring during CoAP 2002 processing are protected end-to-end. Error messages occurring during 2003 OSCORE processing are not always possible to protect, e.g. if the 2004 receiving endpoint cannot locate the right security context. It may 2005 still be favorable to send an unprotected error message, e.g. to 2006 prevent extensive retransmissions, so unprotected error messages are 2007 allowed as specified. Similar to error messages, signaling messages 2008 are not always possible to protect as they may be intended for an 2009 intermediary. Hop-by-hop protection of signaling messages can be 2010 achieved with (D)TLS. Applications using unprotected error and 2011 signaling messages need to consider the threat that these messages 2012 may be spoofed. 2014 11.2. Security Context Establishment 2016 The use of COSE to protect messages as specified in this document 2017 requires an established security context. The method to establish 2018 the security context described in Section 3.2 is based on a common 2019 keying material in client and server, which may be obtained, e.g., by 2020 using the ACE framework [I-D.ietf-ace-oauth-authz]. An OSCORE 2021 profile of ACE is described in [I-D.ietf-ace-oscore-profile]. The 2022 key establishement procedure need to ensure same key is not installed 2023 twice, even in error situations. 2025 11.3. Replay Protection 2027 Most AEAD algorithms require a unique nonce for each message, for 2028 which the sender sequence numbers in the COSE message field 'Partial 2029 IV' is used. If the recipient accepts any sequence number larger 2030 than the one previously received, then the problem of sequence number 2031 synchronization is avoided. With reliable transport, it may be 2032 defined that only messages with sequence number which are equal to 2033 previous sequence number + 1 are accepted. The alternatives to 2034 sequence numbers have their issues: very constrained devices may not 2035 be able to support accurate time, or to generate and store large 2036 numbers of random nonces. The requirement to change key at counter 2037 wrap is a complication, but it also forces the user of this 2038 specification to think about implementing key renewal. 2040 11.4. Cryptographic Considerations 2042 The maximum sender sequence number is dependent on the AEAD 2043 algorithm. The maximum sender sequence number is 2^40 - 1, or any 2044 algorithm specific lower limit, after which a new security context 2045 must be generated. The mechanism to build the nonce (Section 5.2) 2046 assumes that the nonce is at least 56 bits, and the Partial IV is at 2047 most 40 bits. The mandatory-to-implement AEAD algorithm AES-CCM- 2048 16-64-128 is selected for compatibility with CCM*. 2050 The security level of a system with m Masters Keys of length k used 2051 together with Master Salts with entropy n is k + n - log2(m). 2052 Similarly, the security level of a system with m AEAD keys of length 2053 k used together with AEAD nonces of length n is k + n - log2(m). 2054 Security level here means that an attacker can recover one of the m 2055 keys with complexity 2^(k + n) / m. Protection against such attacks 2056 can be provided by increasing the size of the keys or the entropy of 2057 the Master Salt. The complexity of recovering a specific key is 2058 still 2^k (assuming the Master Salt/AEAD nonce is public) (see [MF00] 2059 for a overview). The Master Secret, Sender Key, and Recipient Key 2060 must be secret, the rest of the parameters may be public. The Master 2061 Secret must be uniformly random. 2063 11.5. Message Segmentation 2065 The Inner Block options enable the sender to split large messages 2066 into OSCORE-protected blocks such that the receiving endpoint can 2067 verify blocks before having received the complete message. The Outer 2068 Block options allow for arbitrary proxy fragmentation operations that 2069 cannot be verified by the endpoints, but can by policy be restricted 2070 in size since the Inner Block options allow for secure fragmentation 2071 of very large messages. A maximum message size (above which the 2072 sending endpoint fragments the message and the receiving endpoint 2073 discards the message, if complying to the policy) may be obtained as 2074 part of normal resource discovery. 2076 11.6. Privacy Considerations 2078 Privacy threats executed through intermediary nodes are considerably 2079 reduced by means of OSCORE. End-to-end integrity protection and 2080 encryption of the message payload and all options that are not used 2081 for proxy operations, provide mitigation against attacks on sensor 2082 and actuator communication, which may have a direct impact on the 2083 personal sphere. 2085 The unprotected options (Figure 5) may reveal privacy sensitive 2086 information. In particular Uri-Host SHOULD NOT contain privacy 2087 sensitive information. CoAP headers sent in plaintext allow, for 2088 example, matching of CON and ACK (CoAP Message Identifier), matching 2089 of request and responses (Token) and traffic analysis. OSCORE does 2090 not provide protection for HTTP header fields which are not CoAP- 2091 mappable. 2093 Unprotected error messages reveal information about the security 2094 state in the communication between the endpoints. Unprotected 2095 signalling messages reveal information about the reliable transport 2096 used on a leg of the path. Using the mechanisms described in 2097 Section 7.5 may reveal when a device goes through a reboot. This can 2098 be mitigated by the device storing the precise state of sender 2099 sequence number and replay window on a clean shutdown. 2101 The length of message fields can reveal information about the 2102 message. Applications may use a padding scheme to protect against 2103 traffic analysis. 2105 12. IANA Considerations 2107 Note to RFC Editor: Please replace all occurrences of "[[this 2108 document]]" with the RFC number of this specification. 2110 Note to IANA: Please note all occurrences of "TBD" in this 2111 specification should be assigned the same number. 2113 12.1. COSE Header Parameters Registry 2115 The 'kid context' parameter is added to the "COSE Header Parameters 2116 Registry": 2118 o Name: kid context 2120 o Label: TBD1 (Integer value between 1 and 255) 2122 o Value Type: bstr 2124 o Value Registry: 2126 o Description: kid context 2128 o Reference: Section 5.1 of this document 2130 12.2. CoAP Option Numbers Registry 2132 The Object-Security option is added to the CoAP Option Numbers 2133 registry: 2135 +--------+-----------------+-------------------+ 2136 | Number | Name | Reference | 2137 +--------+-----------------+-------------------+ 2138 | TBD | Object-Security | [[this document]] | 2139 +--------+-----------------+-------------------+ 2141 12.3. CoAP Signaling Option Numbers Registry 2143 The Object-Security option is added to the CoAP Signaling Option 2144 Numbers registry: 2146 +------------+--------+---------------------+-------------------+ 2147 | Applies to | Number | Name | Reference | 2148 +------------+--------+---------------------+-------------------+ 2149 | 7.xx (any) | TBD | Object-Security | [[this document]] | 2150 +------------+--------+---------------------+-------------------+ 2152 12.4. Header Field Registrations 2154 The HTTP header field CoAP-Object-Security is added to the Message 2155 Headers registry: 2157 +----------------------+----------+----------+-------------------+ 2158 | Header Field Name | Protocol | Status | Reference | 2159 +----------------------+----------+----------+-------------------+ 2160 | CoAP-Object-Security | http | standard | [[this document]] | 2161 +----------------------+----------+----------+-------------------+ 2163 12.5. Media Type Registrations 2165 This section registers the 'application/oscore' media type in the 2166 "Media Types" registry. 2167 These media types are used to indicate that the content is an OSCORE 2168 message. 2170 Type name: application 2172 Subtype name: oscore 2174 Required parameters: N/A 2176 Optional parameters: N/A 2178 Encoding considerations: binary 2180 Security considerations: See the Security Considerations section 2181 of [[This document]]. 2183 Interoperability considerations: N/A 2185 Published specification: [[This document]] 2187 Applications that use this media type: IoT applications sending 2188 security content over HTTP(S) transports. 2190 Fragment identifier considerations: N/A 2192 Additional information: 2194 * Deprecated alias names for this type: N/A 2196 * Magic number(s): N/A 2198 * File extension(s): N/A 2200 * Macintosh file type code(s): N/A 2202 Person & email address to contact for further information: 2203 iesg@ietf.org 2205 Intended usage: COMMON 2207 Restrictions on usage: N/A 2209 Author: Goeran Selander, goran.selander@ericsson.com 2211 Change Controller: IESG 2213 Provisional registration? No 2215 12.6. CoAP Content-Formats Registry 2217 TODO 2219 13. References 2221 13.1. Normative References 2223 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2224 Requirement Levels", BCP 14, RFC 2119, 2225 DOI 10.17487/RFC2119, March 1997, 2226 . 2228 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 2229 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 2230 . 2232 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 2233 Specifications: ABNF", STD 68, RFC 5234, 2234 DOI 10.17487/RFC5234, January 2008, 2235 . 2237 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 2238 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 2239 January 2012, . 2241 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 2242 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 2243 October 2013, . 2245 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 2246 Protocol (HTTP/1.1): Message Syntax and Routing", 2247 RFC 7230, DOI 10.17487/RFC7230, June 2014, 2248 . 2250 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 2251 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 2252 DOI 10.17487/RFC7231, June 2014, 2253 . 2255 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 2256 Application Protocol (CoAP)", RFC 7252, 2257 DOI 10.17487/RFC7252, June 2014, 2258 . 2260 [RFC7390] Rahman, A., Ed. and E. Dijk, Ed., "Group Communication for 2261 the Constrained Application Protocol (CoAP)", RFC 7390, 2262 DOI 10.17487/RFC7390, October 2014, 2263 . 2265 [RFC7641] Hartke, K., "Observing Resources in the Constrained 2266 Application Protocol (CoAP)", RFC 7641, 2267 DOI 10.17487/RFC7641, September 2015, 2268 . 2270 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 2271 the Constrained Application Protocol (CoAP)", RFC 7959, 2272 DOI 10.17487/RFC7959, August 2016, 2273 . 2275 [RFC8075] Castellani, A., Loreto, S., Rahman, A., Fossati, T., and 2276 E. Dijk, "Guidelines for Mapping Implementations: HTTP to 2277 the Constrained Application Protocol (CoAP)", RFC 8075, 2278 DOI 10.17487/RFC8075, February 2017, 2279 . 2281 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 2282 FETCH Methods for the Constrained Application Protocol 2283 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 2284 . 2286 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 2287 RFC 8152, DOI 10.17487/RFC8152, July 2017, 2288 . 2290 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2291 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2292 May 2017, . 2294 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 2295 DOI 10.17487/RFC8288, October 2017, 2296 . 2298 [RFC8323] Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 2299 Silverajan, B., and B. Raymor, Ed., "CoAP (Constrained 2300 Application Protocol) over TCP, TLS, and WebSockets", 2301 RFC 8323, DOI 10.17487/RFC8323, February 2018, 2302 . 2304 13.2. Informative References 2306 [I-D.bormann-6lo-coap-802-15-ie] 2307 Bormann, C., "Constrained Application Protocol (CoAP) over 2308 IEEE 802.15.4 Information Element for IETF", draft- 2309 bormann-6lo-coap-802-15-ie-00 (work in progress), April 2310 2016. 2312 [I-D.hartke-core-e2e-security-reqs] 2313 Selander, G., Palombini, F., and K. Hartke, "Requirements 2314 for CoAP End-To-End Security", draft-hartke-core-e2e- 2315 security-reqs-03 (work in progress), July 2017. 2317 [I-D.ietf-6tisch-minimal-security] 2318 Vucinic, M., Simon, J., Pister, K., and M. Richardson, 2319 "Minimal Security Framework for 6TiSCH", draft-ietf- 2320 6tisch-minimal-security-05 (work in progress), March 2018. 2322 [I-D.ietf-ace-oauth-authz] 2323 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 2324 H. Tschofenig, "Authentication and Authorization for 2325 Constrained Environments (ACE)", draft-ietf-ace-oauth- 2326 authz-10 (work in progress), February 2018. 2328 [I-D.ietf-ace-oscore-profile] 2329 Seitz, L., Palombini, F., Gunnarsson, M., and G. Selander, 2330 "OSCORE profile of the Authentication and Authorization 2331 for Constrained Environments Framework", draft-ietf-ace- 2332 oscore-profile-01 (work in progress), March 2018. 2334 [I-D.ietf-cbor-cddl] 2335 Birkholz, H., Vigano, C., and C. Bormann, "Concise data 2336 definition language (CDDL): a notational convention to 2337 express CBOR data structures", draft-ietf-cbor-cddl-02 2338 (work in progress), February 2018. 2340 [I-D.ietf-core-echo-request-tag] 2341 Amsuess, C., Mattsson, J., and G. Selander, "Echo and 2342 Request-Tag", draft-ietf-core-echo-request-tag-01 (work in 2343 progress), March 2018. 2345 [I-D.ietf-core-oscore-groupcomm] 2346 Tiloca, M., Selander, G., Palombini, F., and J. Park, 2347 "Secure group communication for CoAP", draft-ietf-core- 2348 oscore-groupcomm-01 (work in progress), March 2018. 2350 [I-D.mattsson-core-coap-actuators] 2351 Mattsson, J., Fornehed, J., Selander, G., Palombini, F., 2352 and C. Amsuess, "Controlling Actuators with CoAP", draft- 2353 mattsson-core-coap-actuators-04 (work in progress), March 2354 2018. 2356 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2357 Resource Identifier (URI): Generic Syntax", STD 66, 2358 RFC 3986, DOI 10.17487/RFC3986, January 2005, 2359 . 2361 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 2362 Encryption", RFC 5116, DOI 10.17487/RFC5116, January 2008, 2363 . 2365 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 2366 Key Derivation Function (HKDF)", RFC 5869, 2367 DOI 10.17487/RFC5869, May 2010, 2368 . 2370 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 2371 Constrained-Node Networks", RFC 7228, 2372 DOI 10.17487/RFC7228, May 2014, 2373 . 2375 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 2376 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 2377 2015, . 2379 [RFC7967] Bhattacharyya, A., Bandyopadhyay, S., Pal, A., and T. 2380 Bose, "Constrained Application Protocol (CoAP) Option for 2381 No Server Response", RFC 7967, DOI 10.17487/RFC7967, 2382 August 2016, . 2384 Appendix A. Scenario Examples 2386 This section gives examples of OSCORE, targeting scenarios in 2387 Section 2.2.1.1 of [I-D.hartke-core-e2e-security-reqs]. The message 2388 exchanges are made, based on the assumption that there is a security 2389 context established between client and server. For simplicity, these 2390 examples only indicate the content of the messages without going into 2391 detail of the (compressed) COSE message format. 2393 A.1. Secure Access to Sensor 2395 This example illustrates a client requesting the alarm status from a 2396 server. 2398 Client Proxy Server 2399 | | | 2400 +------>| | Code: 0.02 (POST) 2401 | POST | | Token: 0x8c 2402 | | | Object-Security: [kid:5f,Partial IV:42] 2403 | | | Payload: {Code:0.01, 2404 | | | Uri-Path:"alarm_status"} 2405 | | | 2406 | +------>| Code: 0.02 (POST) 2407 | | POST | Token: 0x7b 2408 | | | Object-Security: [kid:5f,Partial IV:42] 2409 | | | Payload: {Code:0.01, 2410 | | | Uri-Path:"alarm_status"} 2411 | | | 2412 | |<------+ Code: 2.04 (Changed) 2413 | | 2.04 | Token: 0x7b 2414 | | | Object-Security: - 2415 | | | Payload: {Code:2.05, "OFF"} 2416 | | | 2417 |<------+ | Code: 2.04 (Changed) 2418 | 2.04 | | Token: 0x8c 2419 | | | Object-Security: - 2420 | | | Payload: {Code:2.05, "OFF"} 2421 | | | 2423 Figure 11: Secure Access to Sensor. Square brackets [ ... ] indicate 2424 content of compressed COSE object. Curly brackets { ... } indicate 2425 encrypted data. 2427 The request/response Codes are encrypted by OSCORE and only dummy 2428 Codes (POST/Changed) are visible in the header of the OSCORE message. 2429 The option Uri-Path ("alarm_status") and payload ("OFF") are 2430 encrypted. 2432 The COSE header of the request contains an identifier (5f), 2433 indicating which security context was used to protect the message and 2434 a Partial IV (42). 2436 The server verifies the request as specified in Section 8.2. The 2437 client verifies the response as specified in Section 8.4. 2439 A.2. Secure Subscribe to Sensor 2441 This example illustrates a client requesting subscription to a blood 2442 sugar measurement resource (GET /glucose), first receiving the value 2443 220 mg/dl and then a second value 180 mg/dl. 2445 Client Proxy Server 2446 | | | 2447 +------>| | Code: 0.05 (FETCH) 2448 | FETCH | | Token: 0x83 2449 | | | Observe: 0 2450 | | | Object-Security: [kid:ca,Partial IV:15] 2451 | | | Payload: {Code:0.01, 2452 | | | Uri-Path:"glucose"} 2453 | | | 2454 | +------>| Code: 0.05 (FETCH) 2455 | | FETCH | Token: 0xbe 2456 | | | Observe: 0 2457 | | | Object-Security: [kid:ca,Partial IV:15] 2458 | | | Payload: {Code:0.01, 2459 | | | Uri-Path:"glucose"} 2460 | | | 2461 | |<------+ Code: 2.04 (Changed) 2462 | | 2.04 | Token: 0xbe 2463 | | | Observe: 7 2464 | | | Object-Security: [Partial IV:32] 2465 | | | Payload: {Code:2.05, 2466 | | | Content-Format:0, "220"} 2467 | | | 2468 |<------+ | Code: 2.04 (Changed) 2469 | 2.04 | | Token: 0x83 2470 | | | Observe: 7 2471 | | | Object-Security: [Partial IV:32] 2472 | | | Payload: {Code:2.05, 2473 | | | Content-Format:0, "220"} 2474 ... ... ... 2475 | | | 2476 | |<------+ Code: 2.04 (Changed) 2477 | | 2.04 | Token: 0xbe 2478 | | | Observe: 8 2479 | | | Object-Security: [Partial IV:36] 2480 | | | Payload: {Code:2.05, 2481 | | | Content-Format:0, "180"} 2482 | | | 2483 |<------+ | Code: 2.04 (Changed) 2484 | 2.04 | | Token: 0x83 2485 | | | Observe: 8 2486 | | | Object-Security: [Partial IV:36] 2487 | | | Payload: {Code:2.05, 2488 | | | Content-Format:0, "180"} 2489 | | | 2491 Figure 12: Secure Subscribe to Sensor. Square brackets [ ... ] 2492 indicate content of compressed COSE object header. Curly brackets { 2493 ... } indicate encrypted data. 2495 The request/response Codes are encrypted by OSCORE and only dummy 2496 Codes (FETCH/Changed) are visible in the header of the OSCORE 2497 message. The options Content-Format (0) and the payload ("220" and 2498 "180"), are encrypted. 2500 The COSE header of the request contains an identifier (ca), 2501 indicating the security context used to protect the message and a 2502 Partial IV (15). The COSE headers of the responses contains Partial 2503 IVs (32 and 36). 2505 The server verifies that the Partial IV has not been received before. 2506 The client verifies that the responses are bound to the request and 2507 that the Partial IVs are greater than any Partial IV previously 2508 received in a response bound to the request. 2510 Appendix B. Deployment examples 2512 OSCORE may be deployed in a variety of settings, a few examples are 2513 given in this section. 2515 B.1. Master Secret Used Once 2517 For settings where the Master Secret is only used during deployment, 2518 the uniqueness of AEAD nonce may be assured by persistent storage of 2519 the security context as described in this specification (see 2520 Section 7.5). For many IoT deployments, a 128 bit uniformly random 2521 Master Key is sufficient for encrypting all data exchanged with the 2522 IoT device throughout its lifetime. 2524 B.2. Master Secret Used Multiple Times 2526 In cases where the Master Secret needs to be used to derive multiple 2527 security contexts, e.g. due to recommissioning or where the security 2528 context is not persistently stored, a stochastically unique Master 2529 Salt prevents the reuse of AEAD nonce and key. The Master Salt may 2530 be transported between client and server in the kid context parameter 2531 (see Section 5.1) of the request. 2533 In this section we give an example of a procedure which may be 2534 implemented in client and server to establish the OSCORE security 2535 context based on pre-established input parameters (see Section 3.2) 2536 except for the Master Salt which is transported in kid context. 2538 1. In order to establish a security context with a server for the 2539 first time, or a new security context replacing an old security 2540 context, the client generates a (pseudo-)random uniformly 2541 distributed 64-bit Master Salt and derives the security context 2542 as specified in Section 3.2. The client protects a request with 2543 the new Sender Context and sends the message with kid context set 2544 to the Master Salt. 2546 2. The server, receiving an OSCORE request with a non-empty kid 2547 context derives the new security context using the received kid 2548 context as Master Salt. The server processes the request as 2549 specified in this document using the new Recipient Context. If 2550 the processing of the request completes without error, the server 2551 responds with an Echo option as specified in 2552 [I-D.ietf-core-echo-request-tag]. The response is protected with 2553 the new Sender Context. 2555 3. The client, receiving a response with an Echo option to a request 2556 which used a new security context, verifies the response using 2557 the new Recipient Context, and if valid repeats the request with 2558 the Echo option (see [I-D.ietf-core-echo-request-tag]) using the 2559 new Sender Context. Subsequent message exchanges (unless 2560 superseded) are processed using the new security context without 2561 including the Master Salt in the kid context. 2563 4. The server, receiving a request with a kid context and a valid 2564 Echo option (see [I-D.ietf-core-echo-request-tag]), repeats the 2565 processing described in step 2. If it completes without error, 2566 then the new security context is established, and the request is 2567 valid. If the server already had an old security context with 2568 this client that is now replaced by the new security context. 2570 If the server receives a request without kid context from a client 2571 with which no security context is established, then the server 2572 responds with a 4.01 Unauthorized error message with diagnostic 2573 payload containing the string "Security context not found". This 2574 could be the result of the server having lost its security context or 2575 that a new security context has not been successfully established, 2576 which may be a trigger for the client to run this procedure. 2578 B.3. Client Aliveness 2580 The use of a single OSCORE request and response enables the client to 2581 verify that the server's identity and aliveness through actual 2582 communications. While a verified OSCORE request enables the server 2583 to verify the identity of the entity who generated the message, it 2584 does not verify that the client is currently involved in the 2585 communication, since the message may be a delayed delivery of a 2586 previously generated request which now reaches the server. To verify 2587 the aliveness of the client the server may initiate an OSCORE 2588 protected message exchange with the client, e.g. by switching the 2589 roles of client and server as described in Section 3.1, or by using 2590 the Echo option in the response to a request from the client 2591 [I-D.ietf-core-echo-request-tag]. 2593 Appendix C. Test Vectors 2595 This appendix includes the test vectors for different examples of 2596 CoAP messages using OSCORE. 2598 C.1. Test Vector 1: Key Derivation with Master Salt 2600 Given a set of inputs, OSCORE defines how to set up the Security 2601 Context in both the client and the server. The default values are 2602 used for AEAD Algorithm and KDF. 2604 C.1.1. Client 2606 Inputs: 2608 o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes) 2610 o Master Salt: 0x9e7ca92223786340 (8 bytes) 2612 o Sender ID: 0x (0 byte) 2614 o Recipient ID: 0x01 (1 byte) 2616 From the previous parameters, 2618 o info (for Sender Key): 0x84400A634b657910 (8 bytes) 2620 o info (for Recipient Key): 0x8441010A634b657910 (9 bytes) 2622 o info (for Common IV): 0x84400a6249560d (7 bytes) 2624 Outputs: 2626 o Sender Key: 0x7230aab3b549d94c9224aacc744e93ab (16 bytes) 2628 o Recipient Key: 0xe534a26a64aa3982e988e31f1e401e65 (16 bytes) 2630 o Common IV: 0x01727733ab49ead385b18f7d91 (13 bytes) 2632 C.1.2. Server 2634 Inputs: 2636 o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes) 2637 o Master Salt: 0x9e7ca92223786340 (64 bytes) 2639 o Sender ID: 0x01 (1 byte) 2641 o Recipient ID: 0x (0 byte) 2643 From the previous parameters, 2645 o info (for Sender Key): 0x8441010A634b657910 (9 bytes) 2647 o info (for Recipient Key): 0x84400A634b657910 (8 bytes) 2649 o info (for Common IV): 0x84400a6249560d (7 bytes) 2651 Outputs: 2653 o Sender Key: 0xe534a26a64aa3982e988e31f1e401e65 (16 bytes) 2655 o Recipient Key: 0x7230aab3b549d94c9224aacc744e93ab (16 bytes) 2657 o Common IV: 0x01727733ab49ead385b18f7d91 (13 bytes) 2659 C.2. Test Vector 2: Key Derivation without Master Salt 2661 Given a set of inputs, OSCORE defines how to set up the Security 2662 Context in both the client and the server. The default values are 2663 used for AEAD Algorithm, KDF, and Master Salt. 2665 C.2.1. Client 2667 Inputs: 2669 o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes) 2671 o Sender ID: 0x00 (1 byte) 2673 o Recipient ID: 0x01 (1 byte) 2675 From the previous parameters, 2677 o info (for Sender Key): 0x8441000A634b657910 (9 bytes) 2679 o info (for Recipient Key): 0x8441010A634b657910 (9 bytes) 2681 o info (for Common IV): 0x84400a6249560d (7 bytes) 2683 Outputs: 2685 o Sender Key: 0xf8f3b887436285ed5a66f6026ac2cdc1 (16 bytes) 2687 o Recipient Key: 0xd904cb101f7341c3f4c56c300fa69941 (16 bytes) 2689 o Common IV: 0xd1a1949aa253278f34c528d2cc (13 bytes) 2691 C.2.2. Server 2693 Inputs: 2695 o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes) 2697 o Sender ID: 0x01 (1 byte) 2699 o Recipient ID: 0x00 (1 byte) 2701 From the previous parameters, 2703 o info (for Sender Key): 0x8441010A634b657910 (9 bytes) 2705 o info (for Recipient Key): 0x8441000A634b657910 (9 bytes) 2707 o info (for Common IV): 0x84400a6249560d (7 bytes) 2709 Outputs: 2711 o Sender Key: 0xd904cb101f7341c3f4c56c300fa69941 (16 bytes) 2713 o Recipient Key: 0xf8f3b887436285ed5a66f6026ac2cdc1 (16 bytes) 2715 o Common IV: 0xd1a1949aa253278f34c528d2cc (13 bytes) 2717 C.3. Test Vector 3: OSCORE Request, Client 2719 This section contains a test vector for a OSCORE protected CoAP GET 2720 request using the security context derived in Appendix C.1. The 2721 unprotected request only contains the Uri-Path option. 2723 Unprotected CoAP request: 2724 0x440149c60000f2a7396c6f63616c686f737483747631 (22 bytes) 2726 Common Context: 2728 o AEAD Algorithm: 10 (AES-CCM-16-64-128) 2730 o Key Derivation Function: HKDF SHA-256 2732 o Common IV: 0xd1a1949aa253278f34c528d2cc (13 bytes) 2733 Sender Context: 2735 o Sender ID: 0x00 (1 byte) 2737 o Sender Key: 0xf8f3b887436285ed5a66f6026ac2cdc1 (16 bytes) 2739 o Sender Sequence Number: 20 2741 The following COSE and cryptographic parameters are derived: 2743 o Partial IV: 0x14 (1 byte) 2745 o kid: 0x00 (1 byte) 2747 o external_aad: 0x8501810a4100411440 (9 bytes) 2749 o AAD: 0x8368456e63727970743040498501810a4100411440 (21 bytes) 2751 o plaintext: 0x01b3747631 (5 bytes) 2753 o encryption key: 0xf8f3b887436285ed5a66f6026ac2cdc1 (16 bytes) 2755 o nonce: 0xd0a1949aa253278f34c528d2d8 (13 bytes) 2757 From the previous parameter, the following is derived: 2759 o Object-Security value: 0x091400 (3 bytes) 2761 o ciphertext: 0x55b3710d47c611cd3924838a44 (13 bytes) 2763 From there: 2765 o Protected CoAP request (OSCORE message): 0x44026dd30000acc5396c6f6 2766 3616c686f7374d305091400ff55b3710d47c611cd3924838a44 (37 bytes) 2768 C.4. Test Vector 4: OSCORE Request, Client 2770 This section contains a test vector for a OSCORE protected CoAP GET 2771 request using the security context derived in Appendix C.2. The 2772 unprotected request only contains the Uri-Path option. 2774 Unprotected CoAP request: 2775 0x440149c60000f2a7396c6f63616c686f737483747631 (22 bytes) 2777 Common Context: 2779 o AEAD Algorithm: 10 (AES-CCM-16-64-128) 2780 o Key Derivation Function: HKDF SHA-256 2782 o Common IV: 0x01727733ab49ead385b18f7d91 (13 bytes) 2784 Sender Context: 2786 o Sender ID: 0x (0 bytes) 2788 o Sender Key: 0x7230aab3b549d94c9224aacc744e93ab (16 bytes) 2790 o Sender Sequence Number: 20 2792 The following COSE and cryptographic parameters are derived: 2794 o Partial IV: 0x14 (1 byte) 2796 o kid: 0x (0 byte) 2798 o external_aad: 0x8501810a40411440 (8 bytes) 2800 o AAD: 0x8368456e63727970743040488501810a40411440 (20 bytes) 2802 o plaintext: 0x01b3747631 (5 bytes) 2804 o encryption key: 0x7230aab3b549d94c9224aacc744e93ab (16 bytes) 2806 o nonce: 0x01727733ab49ead385b18f7d85 (13 bytes) 2808 From the previous parameter, the following is derived: 2810 o Object-Security value: 0x0914 (2 bytes) 2812 o ciphertext: 0x6be9214aad448260ff1be1f594 (13 bytes) 2814 From there: 2816 o Protected CoAP request (OSCORE message): 0x44023bfc000066ef396c6f6 2817 3616c686f7374d2050914ff6be9214aad448260ff1be1f594 (36 bytes) 2819 C.5. Test Vector 5: OSCORE Response, Server 2821 This section contains a test vector for a OSCORE protected 2.05 2822 Content response to the request in Appendix C.3. The unprotected 2823 response has payload "Hello World!" and no options. The protected 2824 response does not contain a kid nor a Partial IV. 2826 Unprotected CoAP response: 2827 0x644549c60000f2a7ff48656c6c6f20576f726c6421 (21 bytes) 2828 Common Context: 2830 o AEAD Algorithm: 10 (AES-CCM-16-64-128) 2832 o Key Derivation Function: HKDF SHA-256 2834 o Common IV: 0xd1a1949aa253278f34c528d2cc (13 bytes) 2836 Sender Context: 2838 o Sender ID: 0x01 (1 byte) 2840 o Sender Key: 0xd904cb101f7341c3f4c56c300fa69941 (16 bytes) 2842 o Sender Sequence Number: 0 2844 The following COSE and cryptographic parameters are derived: 2846 o external_aad: 0x8501810a4100411440 (9 bytes) 2848 o AAD: 0x8368456e63727970743040498501810a4100411440 (21 bytes) 2850 o plaintext: 0x45ff48656c6c6f20576f726c6421 (14 bytes) 2852 o encryption key: 0xd904cb101f7341c3f4c56c300fa69941 (16 bytes) 2854 o nonce: 0xd0a1949aa253278f34c528d2d8 (13 bytes) 2856 From the previous parameter, the following is derived: 2858 o Object-Security value: 0x (0 bytes) 2860 o ciphertext: e4e8c28c41c8f31ca56eec24f6c71d94eacbcdffdc6d (22 2861 bytes) 2863 From there: 2865 o Protected CoAP response (OSCORE message): 0x64446dd30000acc5d008ff 2866 e4e8c28c41c8f31ca56eec24f6c71d94eacbcdffdc6d (33 bytes) 2868 C.6. Test Vector 6: OSCORE Response with Partial IV, Server 2870 This section contains a test vector for a OSCORE protected 2.05 2871 Content response to the request in Appendix C.3. The unprotected 2872 response has payload "Hello World!" and no options. The protected 2873 response does not contain a kid, but contains a Partial IV. 2875 Unprotected CoAP response: 2876 0x644549c60000f2a7ff48656c6c6f20576f726c6421 (21 bytes) 2878 Common Context: 2880 o AEAD Algorithm: 10 (AES-CCM-16-64-128) 2882 o Key Derivation Function: HKDF SHA-256 2884 o Common IV: 0xd1a1949aa253278f34c528d2cc (13 bytes) 2886 Sender Context: 2888 o Sender ID: 0x01 (1 byte) 2890 o Sender Key: 0xd904cb101f7341c3f4c56c300fa69941 (16 bytes) 2892 o Sender Sequence Number: 0 2894 The following COSE and cryptographic parameters are derived: 2896 o Partial IV: 0x00 (1 byte) 2898 o external_aad: 0x8501810a4100411440 (9 bytes) 2900 o AAD: 0x8368456e63727970743040498501810a4100411440 (21 bytes) 2902 o plaintext: 0x45ff48656c6c6f20576f726c6421 (14 bytes) 2904 o encryption key: 0xd904cb101f7341c3f4c56c300fa69941 (16 bytes) 2906 o nonce: 0xd0a1949aa253278e34c528d2cc (13 bytes) 2908 From the previous parameter, the following is derived: 2910 o Object-Security value: 0x0100 (2 bytes) 2912 o ciphertext: 0xa7e3ca27f221f453c0ba68c350bf652ea096b328a1bf (22 2913 bytes) 2915 From there: 2917 o Protected CoAP response (OSCORE message): 0x64442b130000b29ed20801 2918 00ffa7e3ca27f221f453c0ba68c350bf652ea096b328a1bf (35 bytes) 2920 Appendix D. Overview of Security Properties 2922 D.1. Supporting Proxy Operations 2924 CoAP is designed to work with intermediaries reading and/or changing 2925 CoAP message fields and performing supporting operations in 2926 constrained environments, e.g. forwarding and cross-protocol 2927 translations. 2929 Securing CoAP on transport layer protects the entire message between 2930 the endpoints in which case CoAP proxy operations are not possible. 2931 In order to enable proxy operations, security on transport layer 2932 needs to be terminated at the proxy in which case the CoAP message in 2933 its entirety is unprotected in the proxy. 2935 Requirements for CoAP end-to-end security are specified in 2936 [I-D.hartke-core-e2e-security-reqs]. The client and server are 2937 assumed to trust each other, but proxies and gateways are only 2938 trusted to perform its intended operations. Forwarding is specified 2939 in Section 2.2.1 of [I-D.hartke-core-e2e-security-reqs]. HTTP-CoAP 2940 translation is specified in [RFC8075]. Intermediaries translating 2941 between different transport layers are intended to perform just that. 2943 By working at the CoAP layer, OSCORE enables different CoAP message 2944 fields to be protected differently, which allows message fields 2945 required for proxy operations to be available to the proxy while 2946 message fields intended for the other endpoint remain protected. In 2947 the remainder of this section we analyze how OSCORE protects the 2948 protected message fields and the consequences of message fields 2949 intended for proxy operation being unprotected. 2951 D.2. Protected Message Fields 2953 Protected message fields are included in the Plaintext (Section 5.3) 2954 and the Additional Authenticated Data (Section 5.4) of the 2955 COSE_Encrypt0 object using an AEAD algorithm. 2957 OSCORE depends on a pre-established strong Master Secret which can be 2958 used to derive keys, and a construction for making (key, nonce) pairs 2959 unique (Appendix D.3). Assuming this is true, and the keys are used 2960 for no more data than indicated in Section 7.2, OSCORE should provide 2961 the following guarantees: 2963 o Confidentiality: An attacker should not be able to determine the 2964 plaintext contents of a given OSCORE message or determine that 2965 different plaintexts are related (Section 5.3). 2967 o Integrity: An attacker should not be able to craft a new OSCORE 2968 message with protected message fields different from an existing 2969 OSCORE message which will be accepted by the receiver. 2971 o Request-response binding: An attacker should not be able to make a 2972 client match a response to the wrong request. 2974 o Non-replayability: An attacker should not be able to cause the 2975 receiver to accept a message which it has already accepted. 2977 Informally, OSCORE provides these properties by AEAD-protecting the 2978 plaintext with a strong key and uniqueness of (key, nonce) pairs. 2979 AEAD encryption [RFC5116] provides confidentiality and integrity for 2980 the data. Response-request binding is provided by including the kid 2981 and Partial IV of the request in the AAD of the response. Non- 2982 replayability of requests and notifications is provided by using 2983 unique (key, nonce) pairs and a replay protection mechanism 2984 (application dependent, see Section 7.4). 2986 OSCORE is susceptible to a variety of traffic analysis attacks based 2987 on observing the length and timing of encrypted packets. OSCORE does 2988 not provide any specific defenses against this form of attack but the 2989 application may use a padding mechanism to prevent an attacker from 2990 directly determine the length of the padding. However, information 2991 about padding may still be revealed by side-channel attacks observing 2992 differences in timing. 2994 D.3. Uniqueness of (key, nonce) 2996 In this section we show (key, nonce) pairs are not reused in the 2997 encryption of OSCORE messages. 2999 Fix a Security Context complying with the requirements Section 3.3) 3000 and an endpoint. Endpoints may alternate between Client and Server 3001 roles, but each endpoint encrypts with the Sender Key of its Sender 3002 Context. Sender Keys are (stochastically) unique since they are 3003 derived with HKDF from unique Sender IDs, so messages encrypted by 3004 different endpoints use different keys. It remains to prove that the 3005 nonces used by the fixed endpoint are unique. 3007 Since the Common IV is fixed, the nonces are determined by a Partial 3008 IV (PIV) and the Sender ID of the endpoint generating that Partial IV 3009 (ID_PIV), and are unique for different (ID_PIV, PIV) pairs 3010 (Section 5.2). 3012 For requests and notifications (GET Observe responses): 3014 o ID_PIV = Sender ID of the encrypting endpoint 3015 o PIV = current Partial IV of the encrypting endpoint 3017 Since the encrypting endpoint steps the Partial IV for each use, the 3018 nonces used in requests and notifications are all unique as long as 3019 the number of encrypted messages are kept within the required range 3020 (Section 7.2). 3022 For responses to requests: 3024 o ID_PIV = Sender ID of the endpoint generating the request 3026 o PIV = Partial IV of the request 3028 Since the request has been verified using the Recipient Context, 3029 ID_PIV is the Sender ID of another endpoint and is thus different 3030 from the Sender ID of the encrypting endpoint. Therefore the nonces 3031 used in responses are different compared to nonces in requests and 3032 notifications. Since the Partial IV of the request is verified for 3033 replay (Section 7.4), PIV is unique for responses and so are nonces 3034 used in responses. 3036 Note that the argument does not depend on if the nonce in the first 3037 response to GET Observe is generated as a notification or as a 3038 response to a request. In the former case the Partial IV of the 3039 encrypting endpoint is stepped. In the latter case, the nonce is in 3040 the the requesting endpoint's subset of nonces and would otherwise 3041 not be used by the encrypting endpoint. 3043 The argumentation also holds for group communication as specified in 3044 [RFC7390] although Observe is not used for that setting (see 3045 [I-D.ietf-core-oscore-groupcomm]). 3047 D.4. Unprotected Message Fields 3049 This section lists and discusses issues with unprotected CoAP message 3050 fields. 3052 D.4.1. CoAP Header Fields 3054 o Version 3056 The CoAP version will be in plaintext. A change of this parameter is 3057 potentially a denial of service attack. Currently there is only one 3058 CoAP version defined. Future versions of CoAP need to analyse 3059 attacks to OSCORE protected messages due to an adversary changing the 3060 CoAP version. 3062 o Token/Token Length 3063 The Token field is a client-local identifier for differentiating 3064 between concurrent requests. Change of Token is a denial of service 3065 attack, since the client may not be able to identify the request or 3066 verify integrity of the response, which depends on the request. 3068 o Type/Message ID 3070 These fields reveal information about the UDP transport binding. 3071 CoAP proxies are allowed to change Type and Message ID. These 3072 message fields are not present in CoAP over TCP, and does not impact 3073 the request/response message. A change of these fields is a denial 3074 of service attack similar to changing UDP header fields. 3076 o Length 3078 This field reveal information about the TCP transport binding. These 3079 message fields are not present in CoAP over UDP, and does not impact 3080 the request/response message. A change of Length is a denial of 3081 service attack similar to changing TCP header fields. 3083 D.4.2. CoAP Options 3085 o Max-Age 3087 The Outer Max-Age is used to avoid unnecessary caching of OSCORE 3088 error responses. Changing this value is a potential denial of 3089 service attack. 3091 o Proxy-Uri/Proxy-Scheme/Uri-Host/Uri-Port 3093 With OSCORE, the Proxy-Uri option does not contain the Uri-Path/Uri- 3094 Query parts of the URI. Proxy-Uri/Proxy-Scheme/Uri-Host/Uri-Port 3095 cannot be integrity protected since they are allowed to be changed by 3096 a forward proxy. 3098 o Observe 3100 The Outer Observe option is intended for an OSCORE-unaware proxy to 3101 support forwarding of Observe messages. Changing this option may 3102 lead to notifications not being forwarded. 3104 o Block1/Block2/Size1/Size2 3106 The Outer Block options enables fragmentation of OSCORE messages in 3107 addition to segmentation performed by the Inner Block options. 3108 Manipulating these options is a potential denial of service attack, 3109 e.g. injection of alleged Block fragments up to the 3110 MAX_UNFRAGMENTED_SIZE, at which the message will be dropped. 3112 o No-Response 3114 The Outer No-Response option is used to support proxy functionality, 3115 specifically to avoid error transmissions from proxies to clients, 3116 and to avoid bandwidth reduction to servers by proxies applying 3117 congestion control when not receiving responses. Changing this 3118 option is a potential denial of service attack. 3120 o Object-Security 3122 The Object-Security option contains information about the compressed 3123 COSE header. A change of this field may result in not being able to 3124 verify the OSCORE message. 3126 Appendix E. CDDL Summary 3128 Data structure definitions in the present specification employ the 3129 CDDL language for conciseness and precision. CDDL is defined in 3130 [I-D.ietf-cbor-cddl], which at the time of writing this appendix is 3131 in the process of completion. As the document is not yet available 3132 for a normative reference, the present appendix defines the small 3133 subset of CDDL that is being used in the present specification. 3135 Within the subset being used here, a CDDL rule is of the form "name = 3136 type", where "name" is the name given to the "type". A "type" can be 3137 one of: 3139 o a reference to another named type, by giving its name. The 3140 predefined named types used in the present specification are: 3141 "uint", an unsigned integer (as represented in CBOR by major type 3142 0); "int", an unsigned or negative integer (as represented in CBOR 3143 by major type 0 or 1); "bstr", a byte string (as represented in 3144 CBOR by major type 2); "tstr", a text string (as represented in 3145 CBOR by major type 3); 3147 o a choice between two types, by giving both types separated by a 3148 "/"; 3150 o an array type (as represented in CBOR by major type 4), where the 3151 sequence of elements of the array is described by giving a 3152 sequence of entries separated by commas ",", and this sequence is 3153 enclosed by square brackets "[" and "]". Arrays described by an 3154 array description contain elements that correspond one-to-one to 3155 the sequence of entries given. Each entry of an array description 3156 is of the form "name : type", where "name" is the name given to 3157 the entry and "type" is the type of the array element 3158 corresponding to this entry. 3160 Acknowledgments 3162 The following individuals provided input to this document: Christian 3163 Amsuess, Tobias Andersson, Carsten Bormann, Joakim Brorsson, Esko 3164 Dijk, Thomas Fossati, Martin Gunnarsson, Klaus Hartke, Jim Schaad, 3165 Peter van der Stok, Dave Thaler, Marco Tiloca, and Malisa Vucinic. 3167 Ludwig Seitz and Goeran Selander worked on this document as part of 3168 the CelticPlus project CyberWI, with funding from Vinnova. 3170 Authors' Addresses 3172 Goeran Selander 3173 Ericsson AB 3175 Email: goran.selander@ericsson.com 3177 John Mattsson 3178 Ericsson AB 3180 Email: john.mattsson@ericsson.com 3182 Francesca Palombini 3183 Ericsson AB 3185 Email: francesca.palombini@ericsson.com 3187 Ludwig Seitz 3188 RISE SICS 3190 Email: ludwig.seitz@ri.se