idnits 2.17.1 draft-ietf-core-object-security-10.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 14, 2018) is 2233 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 6347 (Obsoleted by RFC 9147) ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 8152 (Obsoleted by RFC 9052, RFC 9053) == Outdated reference: A later version (-15) exists of draft-ietf-6tisch-minimal-security-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-00 == Outdated reference: A later version (-08) exists of draft-ietf-cbor-cddl-02 == Outdated reference: A later version (-14) exists of draft-ietf-core-echo-request-tag-00 == Outdated reference: A later version (-21) exists of draft-ietf-core-oscore-groupcomm-01 == Outdated reference: A later version (-06) exists of draft-mattsson-core-coap-actuators-04 == Outdated reference: A later version (-14) exists of draft-selander-ace-cose-ecdhe-07 Summary: 5 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 15, 2018 Ericsson AB 6 L. Seitz 7 RISE SICS 8 March 14, 2018 10 Object Security for Constrained RESTful Environments (OSCORE) 11 draft-ietf-core-object-security-10 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 http://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 15, 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 (http://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 . . . . . . . . . . . . . . . . . . . . . . . 21 70 5.1. Kid Context . . . . . . . . . . . . . . . . . . . . . . . 23 71 5.2. Nonce . . . . . . . . . . . . . . . . . . . . . . . . . . 23 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 . . . . . . . . . . . . . 27 77 6.3. Examples of Compressed COSE Objects . . . . . . . . . . . 28 78 7. Sequence Numbers, Replay, Message Binding, and Freshness . . 29 79 7.1. Message Binding . . . . . . . . . . . . . . . . . . . . . 29 80 7.2. AEAD Nonce Uniqueness . . . . . . . . . . . . . . . . . . 29 81 7.3. Freshness . . . . . . . . . . . . . . . . . . . . . . . . 30 82 7.4. Replay Protection . . . . . . . . . . . . . . . . . . . . 30 83 7.5. Losing Part of the Context State . . . . . . . . . . . . 31 84 8. Processing . . . . . . . . . . . . . . . . . . . . . . . . . 32 85 8.1. Protecting the Request . . . . . . . . . . . . . . . . . 32 86 8.2. Verifying the Request . . . . . . . . . . . . . . . . . . 33 87 8.3. Protecting the Response . . . . . . . . . . . . . . . . . 34 88 8.4. Verifying the Response . . . . . . . . . . . . . . . . . 35 89 9. Web Linking . . . . . . . . . . . . . . . . . . . . . . . . . 36 90 10. Proxy and HTTP Operations . . . . . . . . . . . . . . . . . . 37 91 10.1. CoAP-to-CoAP Forwarding Proxy . . . . . . . . . . . . . 37 92 10.2. HTTP Processing . . . . . . . . . . . . . . . . . . . . 37 93 10.3. HTTP-to-CoAP Translation Proxy . . . . . . . . . . . . . 39 94 10.4. CoAP-to-HTTP Translation Proxy . . . . . . . . . . . . . 40 95 11. Security Considerations . . . . . . . . . . . . . . . . . . . 42 96 11.1. End-to-end protection . . . . . . . . . . . . . . . . . 42 97 11.2. Security Context Establishment . . . . . . . . . . . . . 43 98 11.3. Replay Protection . . . . . . . . . . . . . . . . . . . 43 99 11.4. Cryptographic Considerations . . . . . . . . . . . . . . 43 100 11.5. Message Fragmentation . . . . . . . . . . . . . . . . . 44 101 11.6. Privacy Considerations . . . . . . . . . . . . . . . . . 44 102 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 45 103 12.1. COSE Header Parameters Registry . . . . . . . . . . . . 45 104 12.2. CoAP Option Numbers Registry . . . . . . . . . . . . . . 45 105 12.3. CoAP Signaling Option Numbers Registry . . . . . . . . . 46 106 12.4. Header Field Registrations . . . . . . . . . . . . . . . 46 107 12.5. Media Type Registrations . . . . . . . . . . . . . . . . 46 108 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 48 109 13.1. Normative References . . . . . . . . . . . . . . . . . . 48 110 13.2. Informative References . . . . . . . . . . . . . . . . . 49 111 Appendix A. Scenario Examples . . . . . . . . . . . . . . . . . 51 112 A.1. Secure Access to Sensor . . . . . . . . . . . . . . . . . 51 113 A.2. Secure Subscribe to Sensor . . . . . . . . . . . . . . . 52 114 Appendix B. Deployment examples . . . . . . . . . . . . . . . . 54 115 B.1. Master Secret Used Once . . . . . . . . . . . . . . . . . 54 116 B.2. Master Secret Used Multiple Times . . . . . . . . . . . . 54 117 B.3. Client Aliveness . . . . . . . . . . . . . . . . . . . . 55 118 Appendix C. Test Vectors . . . . . . . . . . . . . . . . . . . . 56 119 C.1. Test Vector 1: Key Derivation with Master Salt . . . . . 56 120 C.2. Test Vector 2: Key Derivation without Master Salt . . . . 57 121 C.3. Test Vector 3: OSCORE Request, Client . . . . . . . . . . 58 122 C.4. Test Vector 4: OSCORE Request, Client . . . . . . . . . . 59 123 C.5. Test Vector 5: OSCORE Response, Server . . . . . . . . . 60 124 C.6. Test Vector 6: OSCORE Response with Partial IV, Server . 61 125 Appendix D. Security properties . . . . . . . . . . . . . . . . 63 126 Appendix E. CDDL Summary . . . . . . . . . . . . . . . . . . . . 63 127 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 63 128 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 64 130 1. Introduction 132 The Constrained Application Protocol (CoAP) [RFC7252] is a web 133 application protocol, designed for constrained nodes and networks 134 [RFC7228], and may be mapped from HTTP [RFC8075]. CoAP specifies the 135 use of proxies for scalability and efficiency and references DTLS 136 ([RFC6347]) for security. CoAP-to-CoAP, HTTP-to-CoAP, and CoAP-to- 137 HTTP proxies require (D)TLS to be terminated at the proxy. The proxy 138 therefore not only has access to the data required for performing the 139 intended proxy functionality, but is also able to eavesdrop on, or 140 manipulate any part of, the message payload and metadata in transit 141 between the endpoints. The proxy can also inject, delete, or reorder 142 packets since they are no longer protected by (D)TLS. 144 This document defines the Object Security for Constrained RESTful 145 Environments (OSCORE) security protocol, protecting CoAP and CoAP- 146 mappable HTTP requests and responses end-to-end across intermediary 147 nodes such as CoAP forward proxies and cross-protocol translators 148 including HTTP-to-CoAP proxies [RFC8075]. In addition to the core 149 CoAP features defined in [RFC7252], OSCORE supports Observe 150 [RFC7641], Blockwise [RFC7959], No-Response [RFC7967], and PATCH and 151 FETCH [RFC8132]. An analysis of end-to-end security for CoAP 152 messages through some types of intermediary nodes is performed in 153 [I-D.hartke-core-e2e-security-reqs]. OSCORE essentially protects the 154 RESTful interactions; the request method, the requested resource, the 155 message payload, etc. (see Section 4). OSCORE protects neither the 156 CoAP Messaging Layer nor the CoAP Token which may change between the 157 endpoints, and those are therefore processed as defined in [RFC7252]. 158 Additionally, since the message formats for CoAP over unreliable 159 transport [RFC7252] and for CoAP over reliable transport [RFC8323] 160 differ only in terms of CoAP Messaging Layer, OSCORE can be applied 161 to both unreliable and reliable transports (see Figure 1). 163 +-----------------------------------+ 164 | Application | 165 +-----------------------------------+ 166 +-----------------------------------+ \ 167 | Requests / Responses / Signaling | | 168 |-----------------------------------| | 169 | OSCORE | | CoAP 170 |-----------------------------------| | 171 | Messaging Layer / Message Framing | | 172 +-----------------------------------+ / 173 +-----------------------------------+ 174 | UDP / TCP / ... | 175 +-----------------------------------+ 177 Figure 1: Abstract Layering of CoAP with OSCORE 179 OSCORE works in very constrained nodes and networks, thanks to its 180 small message size and the restricted code and memory requirements in 181 addition to what is required by CoAP. Examples of the use of OSCORE 182 are given in Appendix A. OSCORE does not depend on underlying 183 layers, and can be used anywhere where CoAP or HTTP can be used, 184 including non-IP transports (e.g., [I-D.bormann-6lo-coap-802-15-ie]). 185 OSCORE may be used together with (D)TLS over one or more hops in the 186 end-to-end path, e.g. with HTTPs in one hop and with plain CoAP in 187 another hop. 189 The use of OSCORE does not affect the URI scheme and OSCORE can 190 therefore be used with any URI scheme defined for CoAP or HTTP. The 191 application decides the conditions for which OSCORE is required. 193 OSCORE uses pre-shared keys which may have been established out-of- 194 band or with a key establishment protocol (see Section 3.2). The 195 technical solution builds on CBOR Object Signing and Encryption 196 (COSE) [RFC8152], providing end-to-end encryption, integrity, replay 197 protection, and secure binding of response to request. A compressed 198 version of COSE is used, as specified in Section 6. The use of 199 OSCORE is signaled with the new Object-Security CoAP option or HTTP 200 header field, defined in Section 2 and Section 10.3. The solution 201 transforms a CoAP/HTTP message into an "OSCORE message" before 202 sending, and vice versa after receiving. The OSCORE message is a 203 CoAP/HTTP message related to the original message in the following 204 way: the original CoAP/HTTP message is translated to CoAP (if not 205 already in CoAP) and protected in a COSE object. The encrypted 206 message fields of this COSE object are transported in the CoAP 207 payload/HTTP body of the OSCORE message, and the Object-Security 208 option/header field is included in the message. A sketch of an 209 OSCORE message exchange in the case of the original message being 210 CoAP is provided in Figure 2). 212 Client Server 213 | OSCORE request - POST example.com: | 214 | Header, Token, | 215 | Options: {Object-Security, ...}, | 216 | Payload: COSE ciphertext | 217 +--------------------------------------------->| 218 | | 219 |<---------------------------------------------+ 220 | OSCORE response - 2.04 (Changed): | 221 | Header, Token, | 222 | Options: {Object-Security, ...}, | 223 | Payload: COSE ciphertext | 224 | | 226 Figure 2: Sketch of CoAP with OSCORE 228 An implementation supporting this specification MAY implement only 229 the client part, MAY implement only the server part, or MAY implement 230 only one of the proxy parts. OSCORE is designed to protect as much 231 information as possible while still allowing proxy operations 232 (Section 10). It works with legacy CoAP-to-CoAP forward proxies 233 [RFC7252], but an OSCORE-aware proxy will be more efficient. HTTP- 234 to-CoAP proxies [RFC8075] and CoAP-to-HTTP proxies can also be used 235 with OSCORE, as specified in Section 10. 237 1.1. Terminology 239 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 240 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 241 "OPTIONAL" in this document are to be interpreted as described in BCP 242 14 [RFC2119] [RFC8174] when, and only when, they appear in all 243 capitals, as shown here. 245 Readers are expected to be familiar with the terms and concepts 246 described in CoAP [RFC7252], Observe [RFC7641], Blockwise [RFC7959], 247 COSE [RFC8152], CBOR [RFC7049], CDDL [I-D.ietf-cbor-cddl] as 248 summarized in Appendix E, and constrained environments [RFC7228]. 250 The term "hop" is used to denote a particular leg in the end-to-end 251 path. The concept "hop-by-hop" (as in "hop-by-hop encryption" or 252 "hop-by-hop fragmentation") opposed to "end-to-end", is used in this 253 document to indicate that the messages are processed accordingly in 254 the intermediaries, rather than just forwarded to the next node. 256 The term "stop processing" is used throughout the document to denote 257 that the message is not passed up to the CoAP Request/Response layer 258 (see Figure 1). 260 The terms Common/Sender/Recipient Context, Master Secret/Salt, Sender 261 ID/Key, Recipient ID/Key, and Common IV are defined in Section 3.1. 263 2. The CoAP Object-Security Option 265 The CoAP Object-Security option (see Figure 3, which extends Table 4 266 of [RFC7252]) indicates that the CoAP message is an OSCORE message 267 and that it contains a compressed COSE object (see Section 5 and 268 Section 6). The Object-Security option is critical, safe to forward, 269 part of the cache key, and not repeatable. 271 +-----+---+---+---+---+-----------------+--------+--------+---------+ 272 | No. | C | U | N | R | Name | Format | Length | Default | 273 +-----+---+---+---+---+-----------------+--------+--------+---------+ 274 | TBD | x | | | | Object-Security | (*) | 0-255 | (none) | 275 +-----+---+---+---+---+-----------------+--------+--------+---------+ 276 C = Critical, U = Unsafe, N = NoCacheKey, R = Repeatable 277 (*) See below. 279 Figure 3: The Object-Security Option 281 The Object-Security option includes the OSCORE flag bits (Section 6), 282 the Sender Sequence Number and the Sender ID when present 283 (Section 3). The detailed format and length is specified in 284 Section 6. If the OSCORE flag bits is all zero (0x00) the Option 285 value SHALL be empty (Option Length = 0). An endpoint receiving a 286 CoAP message without payload, that also contains an Object-Security 287 option SHALL treat it as malformed and reject it. 289 A successful response to a request with the Object-Security option 290 SHALL contain the Object-Security option. Whether error responses 291 contain the Object-Security option depends on the error type (see 292 Section 8). 294 A CoAP proxy SHOULD NOT cache a response to a request with an Object- 295 Security option, since the response is only applicable to the 296 original request (see Section 10.1). As the compressed COSE Object 297 is included in the cache key, messages with the Object-Security 298 option will never generate cache hits. For Max-Age processing (see 299 Section 4.1.3.1). 301 3. The Security Context 303 OSCORE requires that client and server establish a shared security 304 context used to process the COSE objects. OSCORE uses COSE with an 305 Authenticated Encryption with Additional Data (AEAD, [RFC5116]) 306 algorithm for protecting message data between a client and a server. 307 In this section, we define the security context and how it is derived 308 in client and server based on a shared secret and a key derivation 309 function (KDF). 311 3.1. Security Context Definition 313 The security context is the set of information elements necessary to 314 carry out the cryptographic operations in OSCORE. For each endpoint, 315 the security context is composed of a "Common Context", a "Sender 316 Context", and a "Recipient Context". 318 The endpoints protect messages to send using the Sender Context and 319 verify messages received using the Recipient Context, both contexts 320 being derived from the Common Context and other data. Clients and 321 servers need to be able to retrieve the correct security context to 322 use. 324 An endpoint uses its Sender ID (SID) to derive its Sender Context, 325 and the other endpoint uses the same ID, now called Recipient ID 326 (RID), to derive its Recipient Context. In communication between two 327 endpoints, the Sender Context of one endpoint matches the Recipient 328 Context of the other endpoint, and vice versa. Thus, the two 329 security contexts identified by the same IDs in the two endpoints are 330 not the same, but they are partly mirrored. Retrieval and use of the 331 security context are shown in Figure 4. 333 .-------------. .-------------. 334 | Common, | | Common, | 335 | Sender, | | Recipient, | 336 | Recipient | | Sender | 337 '-------------' '-------------' 338 Client Server 339 | | 340 Retrieve context for | OSCORE request: | 341 target resource | Token = Token1, | 342 Protect request with | kid = SID, ... | 343 Sender Context +---------------------->| Retrieve context with 344 | | RID = kid 345 | | Verify request with 346 | | Recipient Context 347 | OSCORE response: | Protect response with 348 | Token = Token1, ... | Sender Context 349 Retrieve context with |<----------------------+ 350 Token = Token1 | | 351 Verify request with | | 352 Recipient Context | | 354 Figure 4: Retrieval and use of the Security Context 356 The Common Context contains the following parameters: 358 o AEAD Algorithm. The COSE AEAD algorithm to use for encryption. 360 o Key Derivation Function. The HMAC based HKDF [RFC5869] used to 361 derive Sender Key, Recipient Key, and Common IV. 363 o Master Secret. Variable length, uniformly random byte string 364 containing the key used to derive traffic keys and IVs. 366 o Master Salt. Variable length byte string containing the salt used 367 to derive traffic keys and IVs. 369 o Common IV. Byte string derived from Master Secret and Master 370 Salt. Length is determined by the AEAD Algorithm. 372 The Sender Context contains the following parameters: 374 o Sender ID. Byte string used to identify the Sender Context and to 375 assure unique AEAD nonces. Maximum length is determined by the 376 AEAD Algorithm. 378 o Sender Key. Byte string containing the symmetric key to protect 379 messages to send. Derived from Common Context and Sender ID. 380 Length is determined by the AEAD Algorithm. 382 o Sender Sequence Number. Non-negative integer used by the sender 383 to protect requests and Observe notifications. Used as 'Partial 384 IV' [RFC8152] to generate unique nonces for the AEAD. Maximum 385 value is determined by the AEAD Algorithm. 387 The Recipient Context contains the following parameters: 389 o Recipient ID. Byte string used to identify the Recipient Context 390 and to assure unique AEAD nonces. Maximum length is determined by 391 the AEAD Algorithm. 393 o Recipient Key. Byte string containing the symmetric key to verify 394 messages received. Derived from Common Context and Recipient ID. 395 Length is determined by the AEAD Algorithm. 397 o Replay Window (Server only). The replay window to verify requests 398 received. 400 All parameters except Sender Sequence Number and Replay Window are 401 immutable once the security context is established. An endpoint may 402 free up memory by not storing the Common IV, Sender Key, and 403 Recipient Key, deriving them from the Master Key and Master Salt when 404 needed. Alternatively, an endpoint may free up memory by not storing 405 the Master Secret and Master Salt after the other parameters have 406 been derived. 408 Endpoints MAY operate as both client and server and use the same 409 security context for those roles. Independent of being client or 410 server, the endpoint protects messages to send using its Sender 411 Context, and verifies messages received using its Recipient Context. 412 The endpoints MUST NOT change the Sender/Recipient ID when changing 413 roles. In other words, changing the roles does not change the set of 414 keys to be used. 416 3.2. Establishment of Security Context Parameters 418 The parameters in the security context are derived from a small set 419 of input parameters. The following input parameters SHALL be pre- 420 established: 422 o Master Secret 424 o Sender ID 426 o Recipient ID 427 The following input parameters MAY be pre-established. In case any 428 of these parameters is not pre-established, the default value 429 indicated below is used: 431 o AEAD Algorithm 433 * Default is AES-CCM-16-64-128 (COSE algorithm encoding: 10) 435 o Master Salt 437 * Default is the empty string 439 o Key Derivation Function (KDF) 441 * Default is HKDF SHA-256 443 o Replay Window Type and Size 445 * Default is DTLS-type replay protection with a window size of 32 446 ([RFC6347]) 448 All input parameters need to be known to and agreed on by both 449 endpoints, but the replay window may be different in the two 450 endpoints. How the input parameters are pre-established, is 451 application specific. The OSCORE profile of the ACE framework may be 452 used to establish the necessary input parameters 453 ([I-D.ietf-ace-oscore-profile]), or a key exchange protocol such as 454 the TLS/DTLS handshake ([I-D.mattsson-ace-tls-oscore]) or EDHOC 455 ([I-D.selander-ace-cose-ecdhe]) providing forward secrecy. Other 456 examples of deploying OSCORE are given in Appendix B. 458 3.2.1. Derivation of Sender Key, Recipient Key, and Common IV 460 The KDF MUST be one of the HMAC based HKDF [RFC5869] algorithms 461 defined in COSE. HKDF SHA-256 is mandatory to implement. The 462 security context parameters Sender Key, Recipient Key, and Common IV 463 SHALL be derived from the input parameters using the HKDF, which 464 consists of the composition of the HKDF-Extract and HKDF-Expand steps 465 ([RFC5869]): 467 output parameter = HKDF(salt, IKM, info, L) 469 where: 471 o salt is the Master Salt as defined above 473 o IKM is the Master Secret as defined above 474 o info is a CBOR array consisting of: 476 info = [ 477 id : bstr, 478 alg_aead : int / tstr, 479 type : tstr, 480 L : uint 481 ] 483 where: 485 o id is the Sender ID or Recipient ID when deriving keys and the 486 empty string when deriving the Common IV. The encoding is 487 described in Section 5. 489 o alg_aead is the AEAD Algorithm, encoded as defined in [RFC8152]. 491 o type is "Key" or "IV". The label is an ASCII string, and does not 492 include a trailing NUL byte. 494 o L is the size of the key/IV for the AEAD algorithm used, in bytes. 496 For example, if the algorithm AES-CCM-16-64-128 (see Section 10.2 in 497 [RFC8152]) is used, the integer value for alg_aead is 10, the value 498 for L is 16 for keys and 13 for the Common IV. 500 3.2.2. Initial Sequence Numbers and Replay Window 502 The Sender Sequence Number is initialized to 0. The supported types 503 of replay protection and replay window length is application specific 504 and depends on how OSCORE is transported, see Section 7.4. The 505 default is DTLS-type replay protection with a window size of 32 506 initiated as described in Section 4.1.2.6 of [RFC6347]. 508 3.3. Requirements on the Security Context Parameters 510 As collisions may lead to the loss of both confidentiality and 511 integrity, Sender ID SHALL be unique in the set of all security 512 contexts using the same Master Secret and Master Salt. When a 513 trusted third party assigns identifiers (e.g., using 514 [I-D.ietf-ace-oauth-authz]) or by using a protocol that allows the 515 parties to negotiate locally unique identifiers in each endpoint, the 516 Sender IDs can be very short. The maximum length of Sender ID in 517 bytes equals the length of AEAD nonce minus 6. For AES-CCM-16-64-128 518 the maximum length of Sender ID is 7 bytes. Sender IDs MAY be 519 uniformly random distributed byte strings if the probability of 520 collisions is negligible. 522 If Sender ID uniqueness cannot be guaranteed by construction, Sender 523 IDs MUST be long uniformly random distributed byte strings such that 524 the probability of collisions is negligible. 526 To simplify retrieval of the right Recipient Context, the Recipient 527 ID SHOULD be unique in the sets of all Recipient Contexts used by an 528 endpoint. If an endpoint has the same Recipient ID with different 529 Recipient Contexts, i.e. the Recipient Contexts are derived from 530 different keying material, then the endpoint may need to try multiple 531 times before finding the right security context associated to the 532 Recipient ID. The Client MAY provide a 'kid context' parameter 533 (Section 5.1) to help the Server find the right context. 535 While the triple (Master Secret, Master Salt, Sender ID) MUST be 536 unique, the same Master Salt MAY be used with several Master Secrets 537 and the same Master Secret MAY be used with several Master Salts. 539 4. Protected Message Fields 541 OSCORE transforms a CoAP message (which may have been generated from 542 an HTTP message) into an OSCORE message, and vice versa. OSCORE 543 protects as much of the original message as possible while still 544 allowing certain proxy operations (see Section 10). This section 545 defines how OSCORE protects the message fields and transfers them 546 end-to-end between client and server (in any direction). 548 The remainder of this section and later sections discuss the behavior 549 in terms of CoAP messages. If HTTP is used for a particular hop in 550 the end-to-end path, then this section applies to the conceptual CoAP 551 message that is mappable to/from the original HTTP message as 552 discussed in Section 10. That is, an HTTP message is conceptually 553 transformed to a CoAP message and then to an OSCORE message, and 554 similarly in the reverse direction. An actual implementation might 555 translate directly from HTTP to OSCORE without the intervening CoAP 556 representation. 558 Protection of Signaling messages (Section 5 of [RFC8323]) is 559 specified in Section 4.3. The other parts of this section target 560 Request/Response messages. 562 Message fields of the CoAP message may be protected end-to-end 563 between CoAP client and CoAP server in different ways: 565 o Class E: encrypted and integrity protected, 567 o Class I: integrity protected only, or 569 o Class U: unprotected. 571 The sending endpoint SHALL transfer Class E message fields in the 572 ciphertext of the COSE object in the OSCORE message. The sending 573 endpoint SHALL include Class I message fields in the Additional 574 Authenticated Data (AAD) of the AEAD algorithm, allowing the 575 receiving endpoint to detect if the value has changed in transfer. 576 Class U message fields SHALL NOT be protected in transfer. Class I 577 and Class U message field values are transferred in the header or 578 options part of the OSCORE message, which is visible to proxies. 580 Message fields not visible to proxies, i.e., transported in the 581 ciphertext of the COSE object, are called "Inner" (Class E). Message 582 fields transferred in the header or options part of the OSCORE 583 message, which is visible to proxies, are called "Outer" (Class I or 584 U). There are currently no Class I options defined. 586 An OSCORE message may contain both an Inner and an Outer instance of 587 a certain CoAP message field. Inner message fields are intended for 588 the receiving endpoint, whereas Outer message fields are used to 589 support proxy operations. Inner and Outer message fields are 590 processed independently. 592 4.1. CoAP Options 594 A summary of how options are protected is shown in Figure 5. Note 595 that some options may have both Inner and Outer message fields which 596 are protected accordingly. The options which require special 597 processing are labelled with asterisks. 599 +-----+-----------------+---+---+ 600 | No. | Name | E | U | 601 +-----+-----------------+---+---+ 602 | 1 | If-Match | x | | 603 | 3 | Uri-Host | | x | 604 | 4 | ETag | x | | 605 | 5 | If-None-Match | x | | 606 | 6 | Observe | | * | 607 | 7 | Uri-Port | | x | 608 | 8 | Location-Path | x | | 609 | TBD | Object-Security | | * | 610 | 11 | Uri-Path | x | | 611 | 12 | Content-Format | x | | 612 | 14 | Max-Age | * | * | 613 | 15 | Uri-Query | x | | 614 | 17 | Accept | x | | 615 | 20 | Location-Query | x | | 616 | 23 | Block2 | * | * | 617 | 27 | Block1 | * | * | 618 | 28 | Size2 | * | * | 619 | 35 | Proxy-Uri | | * | 620 | 39 | Proxy-Scheme | | x | 621 | 60 | Size1 | * | * | 622 | 258 | No-Response | * | * | 623 +-----+-----------------+---+---+ 625 E = Encrypt and Integrity Protect (Inner) 626 U = Unprotected (Outer) 627 * = Special 629 Figure 5: Protection of CoAP Options 631 Options that are unknown or for which OSCORE processing is not 632 defined SHALL be processed as class E (and no special processing). 633 Specifications of new CoAP options SHOULD define how they are 634 processed with OSCORE. A new COAP option SHOULD be of class E unless 635 it requires proxy processing. 637 4.1.1. Inner Options 639 Inner option message fields (class E) are used to communicate 640 directly with the other endpoint. 642 The sending endpoint SHALL write the Inner option message fields 643 present in the original CoAP message into the plaintext of the COSE 644 object (Section 5.3), and then remove the Inner option message fields 645 from the OSCORE message. 647 The processing of Inner option message fields by the receiving 648 endpoint is specified in Section 8.2 and Section 8.4. 650 4.1.2. Outer Options 652 Outer option message fields (Class U or I) are used to support proxy 653 operations. 655 The sending endpoint SHALL include the Outer option message field 656 present in the original message in the options part of the OSCORE 657 message. All Outer option message fields, including Object-Security, 658 SHALL be encoded as described in Section 3.1 of [RFC7252], where the 659 delta is the difference to the previously included instance of Outer 660 option message field. 662 The processing of Outer options by the receiving endpoint is 663 specified in Section 8.2 and Section 8.4. 665 A procedure for integrity-protection-only of Class I option message 666 fields is specified in Section 5.4. Proxies MUST NOT change the 667 order of option's occurrences, for options repeatable and of class I. 669 Note: There are currently no Class I option message fields defined. 671 4.1.3. Special Options 673 Some options require special processing, marked with an asterisk '*' 674 in Figure 5; the processing is specified in this section. 676 4.1.3.1. Max-Age 678 An Inner Max-Age message field is used to indicate the maximum time a 679 response may be cached by the client (as defined in [RFC7252]), end- 680 to-end from the server to the client, taking into account that the 681 option is not accessible to proxies. The Inner Max-Age SHALL be 682 processed by OSCORE as specified in Section 4.1.1. 684 An Outer Max-Age message field is used to avoid unnecessary caching 685 of OSCORE error responses at OSCORE unaware intermediary nodes. A 686 server MAY set a Class U Max-Age message field with value zero to 687 OSCORE error responses, which are described in Section 7.4, 688 Section 8.2 and Section 8.4. Such message field is then processed 689 according to Section 4.1.2. 691 Successful OSCORE responses do not need to include an Outer Max-Age 692 option since the responses are non-cacheable by construction (see 693 Section 4.2). 695 4.1.3.2. The Block Options 697 Blockwise [RFC7959] is an optional feature. An implementation MAY 698 support [RFC7252] and the Object-Security option without supporting 699 Blockwise. The Block options (Block1, Block2, Size1, Size2), when 700 Inner message fields, provide secure message fragmentation such that 701 each fragment can be verified. The Block options, when Outer message 702 fields, enables hop-by-hop fragmentation of the OSCORE message. 703 Inner and Outer block processing may have different performance 704 properties depending on the underlying transport. The end-to-end 705 integrity of the message can be verified both in case of Inner and 706 Outer Blockwise provided all 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 Blockwise 715 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" 790 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 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]). The use 952 of OSCORE for protecting Signaling is application dependent. 954 OSCORE MAY be used to protect Signaling if the endpoints for OSCORE 955 coincide with the endpoints for the connection. If OSCORE is used to 956 protect Signaling then: 958 o Signaling messages SHALL be protected as CoAP Request messages, 959 except in the case the Signaling message is a response to a 960 previous Signaling message, in which case it SHALL be protected as 961 a CoAP Response message. For example, 7.02 (Ping) is protected as 962 a CoAP Request and 7.03 (Pong) as a CoAP response. 964 o The Outer Code for Signaling messages SHALL be set to 0.02 (POST), 965 unless it is a response to a previous Signaling message, in which 966 case it SHALL be set to 2.04 (Changed). 968 o All Signaling options, except the Object-Security option, SHALL be 969 Inner (Class E). 971 NOTE: Option numbers for Signaling messages are specific to the CoAP 972 Code (see Section 5.2 of [RFC8323]). 974 If OSCORE is not used to protect Signaling, Signaling messages SHALL 975 be unaltered by OSCORE. 977 5. The COSE Object 979 This section defines how to use COSE [RFC8152] to wrap and protect 980 data in the original message. OSCORE uses the untagged COSE_Encrypt0 981 structure with an Authenticated Encryption with Additional Data 982 (AEAD) algorithm. The key lengths, IV length, nonce length, and 983 maximum Sender Sequence Number are algorithm dependent. 985 The AEAD algorithm AES-CCM-16-64-128 defined in Section 10.2 of 986 [RFC8152] is mandatory to implement. For AES-CCM-16-64-128 the 987 length of Sender Key and Recipient Key is 128 bits, the length of 988 nonce and Common IV is 13 bytes. The maximum Sender Sequence Number 989 is specified in Section 11. 991 As specified in [RFC5116], plaintext denotes the data that is to be 992 encrypted and integrity protected, and Additional Authenticated Data 993 (AAD) denotes the data that is to be integrity protected only. 995 The COSE Object SHALL be a COSE_Encrypt0 object with fields defined 996 as follows 998 o The 'protected' field is empty. 1000 o The 'unprotected' field includes: 1002 * The 'Partial IV' parameter. The value is set to the Sender 1003 Sequence Number. All leading zeroes SHALL be removed when 1004 encoding the Partial IV. The value 0 encodes to the byte 1005 string 0x00. This parameter SHALL be present in requests. In 1006 case of Observe (Section 4.1.3.4) the Partial IV SHALL be 1007 present in responses, and otherwise the Partial IV will not 1008 typically be present in responses. (A non-Observe example 1009 where the Partial IV is included in a response is provided in 1010 Section 7.5.2.) 1012 * The 'kid' parameter. The value is set to the Sender ID. This 1013 parameter SHALL be present in requests and will not typically 1014 be present in responses. An example where the Sender ID is 1015 included in a response is the extension of OSCORE to group 1016 communication [I-D.ietf-core-oscore-groupcomm]. 1018 * Optionally, a 'kid context' parameter as defined in 1019 Section 5.1. This parameter MAY be present in requests and 1020 SHALL NOT be present in responses. 1022 o The 'ciphertext' field is computed from the secret key (Sender Key 1023 or Recipient Key), AEAD nonce (see Section 5.2), plaintext (see 1024 Section 5.3), and the Additional Authenticated Data (AAD) (see 1025 Section 5.4) following Section 5.2 of [RFC8152]. 1027 The encryption process is described in Section 5.3 of [RFC8152]. 1029 5.1. Kid Context 1031 For certain use cases, e.g. deployments where the same kid is used 1032 with multiple contexts, it is necessary or favorable for the sender 1033 to provide an additional identifier of the security material to use, 1034 in order for the receiver to retrieve or establish the correct key. 1035 The kid context parameter is used to provide such additional input. 1036 The kid context and kid are used to determine the security context, 1037 or to establish the necessary input parameters to derive the security 1038 context (see Section 3.2). The application defines how this is done. 1040 The kid context is implicitly integrity protected, as manipulation 1041 that leads to the wrong key (or no key) being retrieved which results 1042 in an error, as described in Section 8.2. 1044 A summary of the COSE header parameter kid context defined above can 1045 be found in Figure 7. 1047 Some examples of relevant uses of kid context are the following: 1049 o If the client has an identifier in some other namespace which can 1050 be used by the server to retrieve or establish the security 1051 context, then that identifier can be used as kid context. The kid 1052 context may be used as Master Salt (Section 3.1) for additional 1053 entropy of the security contexts (see for example Appendix B.2 or 1054 [I-D.ietf-6tisch-minimal-security]). 1056 o In case of a group communication scenario 1057 [I-D.ietf-core-oscore-groupcomm], if the server belongs to 1058 multiple groups, then a group identifier can be used as kid 1059 context to enable the server to find the right security context. 1061 +----------+--------+------------+----------------+-----------------+ 1062 | name | label | value type | value registry | description | 1063 +----------+--------+------------+----------------+-----------------+ 1064 | kid | kidctx | bstr | | Identifies the | 1065 | context | | | | kid context | 1066 +----------+--------+------------+----------------+-----------------+ 1068 Figure 7: Additional common header parameter for the COSE object 1070 5.2. Nonce 1072 The AEAD nonce is constructed in the following way (see Figure 8): 1074 1. left-padding the Partial IV (in network byte order) with zeroes 1075 to exactly 5 bytes, 1077 2. left-padding the (Sender) ID of the endpoint that generated the 1078 Partial IV (in network byte order) with zeroes to exactly nonce 1079 length - 6 bytes, 1081 3. concatenating the size of the ID (S) with the padded ID and the 1082 padded Partial IV, 1084 4. and then XORing with the Common IV. 1086 Note that in this specification only algorithms that use nonces equal 1087 or greater than 7 bytes are supported. The nonce construction with 1088 S, ID of PIV generator, and Partial IV together with endpoint unique 1089 IDs and encryption keys make it easy to verify that the nonces used 1090 with a specific key will be unique. 1092 When Observe is not used, the request and the response may use the 1093 same nonce. In this way, the Partial IV does not have to be sent in 1094 responses, which reduces the size. For processing instructions see 1095 Section 8. 1097 +---+-----------------------+--+--+--+--+--+ 1098 | S | ID of PIV generator | Partial IV |----+ 1099 +---+-----------------------+--+--+--+--+--+ | 1100 | 1101 +------------------------------------------+ | 1102 | Common IV |->(XOR) 1103 +------------------------------------------+ | 1104 | 1105 +------------------------------------------+ | 1106 | Nonce |<---+ 1107 +------------------------------------------+ 1109 Figure 8: AEAD Nonce Formation 1111 5.3. Plaintext 1113 The plaintext is formatted as a CoAP message without Header (see 1114 Figure 9) consisting of: 1116 o the Code of the original CoAP message as defined in Section 3 of 1117 [RFC7252]; and 1119 o all Inner option message fields (see Section 4.1.1) present in the 1120 original CoAP message (see Section 4.1). The options are encoded 1121 as described in Section 3.1 of [RFC7252], where the delta is the 1122 difference to the previously included instance of Class E option; 1123 and 1125 o the Payload of original CoAP message, if present, and in that case 1126 prefixed by the one-byte Payload Marker (0xFF). 1128 0 1 2 3 1129 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 1130 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1131 | Code | Class E options (if any) ... 1132 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1133 |1 1 1 1 1 1 1 1| Payload (if any) ... 1134 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1135 (only if there 1136 is payload) 1138 Figure 9: Plaintext 1140 NOTE: The plaintext contains all CoAP data that needs to be encrypted 1141 end-to-end between the endpoints. 1143 5.4. Additional Authenticated Data 1145 The external_aad SHALL be a CBOR array as defined below: 1147 external_aad = [ 1148 oscore_version : uint, 1149 algorithms : [ alg_aead : int / tstr ], 1150 request_kid : bstr, 1151 request_piv : bstr, 1152 options : bstr 1153 ] 1155 where: 1157 o oscore_version: contains the OSCORE version number. 1158 Implementations of this specification MUST set this field to 1. 1159 Other values are reserved for future versions. 1161 o alg_aead: contains the AEAD Algorithm from the security context 1162 used for the exchange (see Section 3.1). 1164 o request_kid: contains the value of the 'kid' in the COSE object of 1165 the request (see Section 5). 1167 o request_piv: contains the value of the 'Partial IV' in the COSE 1168 object of the request (see Section 5). 1170 o options: contains the Class I options (see Section 4.1.2) present 1171 in the original CoAP message encoded as described in Section 3.1 1172 of [RFC7252], where the delta is the difference to the previously 1173 included instance of class I option. 1175 NOTE: The format of the external_aad is for simplicity the same for 1176 requests and responses, although some parameters, e.g. request_kid 1177 need not be integrity protected in the requests. 1179 6. OSCORE Header Compression 1181 The Concise Binary Object Representation (CBOR) [RFC7049] combines 1182 very small message sizes with extensibility. The CBOR Object Signing 1183 and Encryption (COSE) [RFC8152] uses CBOR to create compact encoding 1184 of signed and encrypted data. COSE is however constructed to support 1185 a large number of different stateless use cases, and is not fully 1186 optimized for use as a stateful security protocol, leading to a 1187 larger than necessary message expansion. In this section, we define 1188 a stateless header compression mechanism, simply removing redundant 1189 information from the COSE objects, which significantly reduces the 1190 per-packet overhead. The result of applying this mechanism to a COSE 1191 object is called the "compressed COSE object". 1193 The COSE_Encrypt0 object used in OSCORE is transported in the Object- 1194 Security option and in the Payload. The Payload contains the 1195 Ciphertext and the headers of the COSE object are compactly encoded 1196 as described in the next section. 1198 6.1. Encoding of the Object-Security Value 1200 The value of the Object-Security option SHALL contain the OSCORE flag 1201 bits, the Partial IV parameter, the kid context parameter (length and 1202 value), and the kid parameter as follows: 1204 0 1 2 3 4 5 6 7 <--------- n bytes -------------> 1205 +-+-+-+-+-+-+-+-+--------------------------------- 1206 |0 0 0|h|k| n | Partial IV (if any) ... 1207 +-+-+-+-+-+-+-+-+--------------------------------- 1209 <- 1 byte -> <------ s bytes -----> 1210 +------------+----------------------+------------------+ 1211 | s (if any) | kid context (if any) | kid (if any) ... | 1212 +------------+----------------------+------------------+ 1214 Figure 10: Object-Security Value 1216 o The first byte of flag bits encodes the following set of flags and 1217 the length of the Partial IV parameter: 1219 * The three least significant bits encode the Partial IV length 1220 n. If n = 0 then the Partial IV is not present in the 1221 compressed COSE object. The values n = 6 and n = 7 are 1222 reserved. 1224 * The fourth least significant bit is the kid flag, k: it is set 1225 to 1 if the kid is present in the compressed COSE object. 1227 * The fifth least significant bit is the kid context flag, h: it 1228 is set to 1 if the compressed COSE object contains a kid 1229 context (see Section 5.1). 1231 * The sixth to eighth least significant bits are reserved for 1232 future use. These bits SHALL be set to zero when not in use. 1233 According to this specification, if any of these bits are set 1234 to 1 the message is considered to be malformed and 1235 decompression fails as specified in item 3 of Section 8.2. 1237 o The following n bytes encode the value of the Partial IV, if the 1238 Partial IV is present (n > 0). 1240 o The following 1 byte encode the length of the kid context 1241 (Section 5.1) s, if the kid context flag is set (h = 1). 1243 o The following s bytes encode the kid context, if the kid context 1244 flag is set (h = 1). 1246 o The remaining bytes encode the value of the kid, if the kid is 1247 present (k = 1). 1249 Note that the kid MUST be the last field of the object-security 1250 value, even in case reserved bits are used and additional fields are 1251 added to it. 1253 The length of the Object-Security option thus depends on the presence 1254 and length of Partial IV, kid context, kid, as specified in this 1255 section, and on the presence and length of the other parameters, as 1256 defined in the separate documents. 1258 6.2. Encoding of the OSCORE Payload 1260 The payload of the OSCORE message SHALL encode the ciphertext of the 1261 COSE object. 1263 6.3. Examples of Compressed COSE Objects 1265 6.3.1. Examples: Requests 1267 1. Request with kid = 0x25 and Partial IV = 0x05 1269 Before compression (24 bytes): 1271 [ 1272 h'', 1273 { 4:h'25', 6:h'05' }, 1274 h'aea0155667924dff8a24e4cb35b9' 1275 ] 1277 After compression (17 bytes): 1279 Flag byte: 0b00001001 = 0x09 1281 Option Value: 09 05 25 (3 bytes) 1283 Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) 1285 2. Request with kid = empty string and Partial IV = 0x00 1287 After compression (16 bytes): 1289 Flag byte: 0b00001001 = 0x09 1291 Option Value: 09 00 (2 bytes) 1293 Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) 1295 3. Request with kid = empty string, Partial IV = 0x05, and kid 1296 context = 0x44616c656b 1298 After compression (22 bytes): 1300 Flag byte: 0b00011001 = 0x19 1302 Option Value: 19 05 05 44 61 6c 65 6b (8 bytes) 1304 Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) 1306 6.3.2. Example: Response (without Observe) 1308 Before compression (18 bytes): 1310 [ 1311 h'', 1312 {}, 1313 h'aea0155667924dff8a24e4cb35b9' 1314 ] 1316 After compression (14 bytes): 1318 Flag byte: 0b00000000 = 0x00 1320 Option Value: (0 bytes) 1322 Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) 1324 6.3.3. Example: Response (with Observe) 1326 Before compression (21 bytes): 1328 [ 1329 h'', 1330 { 6:h'07' }, 1331 h'aea0155667924dff8a24e4cb35b9' 1332 ] 1334 After compression (16 bytes): 1336 Flag byte: 0b00000001 = 0x01 1338 Option Value: 01 07 (2 bytes) 1340 Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) 1342 7. Sequence Numbers, Replay, Message Binding, and Freshness 1344 7.1. Message Binding 1346 In order to prevent response delay and mismatch attacks 1347 [I-D.mattsson-core-coap-actuators] from on-path attackers and 1348 compromised proxies, OSCORE binds responses to the requests by 1349 including the kid and Partial IV of the request in the AAD of the 1350 response. The server therefore needs to store the kid and Partial IV 1351 of the request until all responses have been sent. 1353 7.2. AEAD Nonce Uniqueness 1355 An AEAD nonce MUST NOT be used more than once per AEAD key. In order 1356 to assure unique nonces, each Sender Context contains a Sender 1357 Sequence Number used to protect requests, and - in case of Observe - 1358 responses. If messages are processed concurrently, the operation of 1359 reading and increasing the Sender Sequence Number MUST be atomic. 1361 The maximum Sender Sequence Number is algorithm dependent (see 1362 Section 11), and no greater than 2^40 - 1. If the Sender Sequence 1363 Number exceeds the maximum, the endpoint MUST NOT process any more 1364 messages with the given Sender Context. The endpoint SHOULD acquire 1365 a new security context (and consequently inform the other endpoint) 1366 before this happens. The latter is out of scope of this document. 1368 7.3. Freshness 1370 For requests, OSCORE provides only the guarantee that the request is 1371 not older than the security context. For applications having 1372 stronger demands on request freshness (e.g., control of actuators), 1373 OSCORE needs to be augmented with mechanisms providing freshness, for 1374 example as specified in [I-D.ietf-core-echo-request-tag]. 1376 For responses, the message binding guarantees that a response is not 1377 older than its request. For responses without Observe, this gives 1378 strong absolute freshness. For responses with Observe, the absolute 1379 freshness gets weaker with time, and it is RECOMMENDED that the 1380 client regularly re-register the observation. 1382 For requests, and responses with Observe, OSCORE also provides 1383 relative freshness in the sense that the received Partial IV allows a 1384 recipient to determine the relative order of responses. 1386 7.4. Replay Protection 1388 In order to protect from replay of requests, the server's Recipient 1389 Context includes a Replay Window. A server SHALL verify that a 1390 Partial IV received in the COSE object has not been received before. 1391 If this verification fails the server SHALL stop processing the 1392 message, and MAY optionally respond with a 4.01 Unauthorized error 1393 message. Also, the server MAY set an Outer Max-Age option with value 1394 zero. The diagnostic payload MAY contain the "Replay protection 1395 failed" string. The size and type of the Replay Window depends on 1396 the use case and the protocol with which the OSCORE message is 1397 transported. In case of reliable and ordered transport from endpoint 1398 to endpoint, e.g. TCP, the server MAY just store the last received 1399 Partial IV and require that newly received Partial IVs equals the 1400 last received Partial IV + 1. However, in case of mixed reliable and 1401 unreliable transports and where messages may be lost, such a replay 1402 mechanism may be too restrictive and the default replay window be 1403 more suitable (see Section 3.2.2). 1405 Responses to non-Observe requests are protected against replay as 1406 they are cryptographically bound to the request. 1408 In the case of Observe, a client receiving a notification SHALL 1409 verify that the Partial IV of a received notification is greater than 1410 the Notification Number bound to that Observe registration. If the 1411 verification fails, the client SHALL stop processing the response. 1412 If the verification succeeds, the client SHALL overwrite the 1413 corresponding Notification Number with the received Partial IV. 1415 If messages are processed concurrently, the Partial IV needs to be 1416 validated a second time after decryption and before updating the 1417 replay protection data. The operation of validating the Partial IV 1418 and updating the replay protection data MUST be atomic. 1420 7.5. Losing Part of the Context State 1422 To prevent reuse of the AEAD nonce with the same key, or from 1423 accepting replayed messages, an endpoint needs to handle the 1424 situation of losing rapidly changing parts of the context, such as 1425 the request Token, Sender Sequence Number, Replay Window, and 1426 Notification Numbers. These are typically stored in RAM and 1427 therefore lost in the case of an unplanned reboot. 1429 After boot, an endpoint MAY reject to use pre-existing security 1430 contexts, and MAY establish a new security context with each endpoint 1431 it communicates with. However, establishing a fresh security context 1432 may have a non-negligible cost in terms of, e.g., power consumption. 1434 After boot, an endpoint MAY use a partly persistently stored security 1435 context, but then the endpoint MUST NOT reuse a previous Sender 1436 Sequence Number and MUST NOT accept previously accepted messages. 1437 Some ways to achieve this are described in the following sections. 1439 7.5.1. Sequence Number 1441 To prevent reuse of Sender Sequence Numbers, an endpoint MAY perform 1442 the following procedure during normal operations: 1444 o Each time the Sender Sequence Number is evenly divisible by K, 1445 where K is a positive integer, store the Sender Sequence Number in 1446 persistent memory. After boot, the endpoint initiates the Sender 1447 Sequence Number to the value stored in persistent memory + K - 1. 1448 Storing to persistent memory can be costly. The value K gives a 1449 trade-off between the number of storage operations and efficient 1450 use of Sender Sequence Numbers. 1452 7.5.2. Replay Window 1454 To prevent accepting replay of previously received requests, the 1455 server MAY perform the following procedure after boot: 1457 o For each stored security context, the first time after boot the 1458 server receives an OSCORE request, the server responds with the 1459 Echo option [I-D.ietf-core-echo-request-tag] to get a request with 1460 verifiable freshness. The server MUST use its Partial IV when 1461 generating the AEAD nonce and MUST include the Partial IV in the 1462 response. 1464 If the server using the Echo option can verify a second request as 1465 fresh, then the Partial IV of the second request is set as the lower 1466 limit of the replay window. 1468 7.5.3. Replay Protection of Observe Notifications 1470 To prevent accepting replay of previously received notification 1471 responses, the client MAY perform the following procedure after boot: 1473 o The client rejects notifications bound to the earlier 1474 registration, removes all Notification Numbers and re-registers 1475 using Observe. 1477 8. Processing 1479 This section describes the OSCORE message processing. 1481 8.1. Protecting the Request 1483 Given a CoAP request, the client SHALL perform the following steps to 1484 create an OSCORE request: 1486 1. Retrieve the Sender Context associated with the target resource. 1488 2. Compose the Additional Authenticated Data and the plaintext, as 1489 described in Section 5.4 and Section 5.3. 1491 3. Compute the AEAD nonce from the Sender ID, Common IV, and Partial 1492 IV (Sender Sequence Number in network byte order) as described in 1493 Section 5.2 and (in one atomic operation, see Section 7.2) 1494 increment the Sender Sequence Number by one. 1496 4. Encrypt the COSE object using the Sender Key. Compress the COSE 1497 Object as specified in Section 6. 1499 5. Format the OSCORE message according to Section 4. The Object- 1500 Security option is added (see Section 4.1.2). 1502 6. Store the association Token - Security Context, in order to be 1503 able to find the Recipient Context from the Token in the 1504 response. 1506 8.2. Verifying the Request 1508 A server receiving a request containing the Object-Security option 1509 SHALL perform the following steps: 1511 1. Process Outer Block options according to [RFC7959], until all 1512 blocks of the request have been received (see Section 4.1.3.2). 1514 2. Discard the message Code and all non-special Inner option 1515 message fields (marked with 'x' in column E of Figure 5) present 1516 in the received message. For example, an If-Match Outer option 1517 is discarded, but an Uri-Host Outer option is not discarded. 1519 3. Decompress the COSE Object (Section 6) and retrieve the 1520 Recipient Context associated with the Recipient ID in the 'kid' 1521 parameter. If either the decompression or the COSE message 1522 fails to decode, or the server fails to retrieve a Recipient 1523 Context with Recipient ID corresponding to the 'kid' parameter 1524 received, then the server SHALL stop processing the request. 1525 If: 1527 * either the decompression or the COSE message fails to decode, 1528 the server MAY respond with a 4.02 Bad Option error message. 1529 The server MAY set an Outer Max-Age option with value zero. 1530 The diagnostic payload SHOULD contain the string "Failed to 1531 decode COSE". 1533 * the server fails to retrieve a Recipient Context with 1534 Recipient ID corresponding to the 'kid' parameter received, 1535 the server MAY respond with a 4.01 Unauthorized error 1536 message. The server MAY set an Outer Max-Age option with 1537 value zero. The diagnostic payload SHOULD contain the string 1538 "Security context not found". 1540 4. Verify the 'Partial IV' parameter using the Replay Window, as 1541 described in Section 7.4. 1543 5. Compose the Additional Authenticated Data, as described in 1544 Section 5.4. 1546 6. Compute the AEAD nonce from the Recipient ID, Common IV, and the 1547 'Partial IV' parameter, received in the COSE Object. 1549 7. Decrypt the COSE object using the Recipient Key, as per 1550 [RFC8152] Section 5.3. (The decrypt operation includes the 1551 verification of the integrity.) 1553 * If decryption fails, the server MUST stop processing the 1554 request and MAY respond with a 4.00 Bad Request error 1555 message. The server MAY set an Outer Max-Age option with 1556 value zero. The diagnostic payload SHOULD contain the 1557 "Decryption failed" string. 1559 * If decryption succeeds, update the Replay Window, as 1560 described in Section 7. 1562 8. For each decrypted option, check if the option is also present 1563 as an Outer option: if it is, discard the Outer. For example: 1564 the message contains a Max-Age Inner and a Max-Age Outer option. 1565 The Outer Max-Age is discarded. 1567 9. Add decrypted code, options and payload to the decrypted 1568 request. The Object-Security option is removed. 1570 10. The decrypted CoAP request is processed according to [RFC7252] 1572 8.3. Protecting the Response 1574 If a CoAP response is generated in response to an OSCORE request, the 1575 server SHALL perform the following steps to create an OSCORE 1576 response. Note that CoAP error responses derived from CoAP 1577 processing (point 10. in Section 8.2) are protected, as well as 1578 successful CoAP responses, while the OSCORE errors (point 3, 4, and 7 1579 in Section 8.2) do not follow the processing below, but are sent as 1580 simple CoAP responses, without OSCORE processing. 1582 1. Retrieve the Sender Context in the Security Context used to 1583 verify the request. 1585 2. Compose the Additional Authenticated Data and the plaintext, as 1586 described in Section 5.4 and Section 5.3. 1588 3. Compute the AEAD nonce 1590 * If Observe is used, compute the nonce from the Sender ID, 1591 Common IV, and Partial IV (Sender Sequence Number in network 1592 byte order). Then (in one atomic operation, see Section 7.2) 1593 increment the Sender Sequence Number by one. 1595 * If Observe is not used, either the nonce from the request is 1596 used or a new Partial IV is used (see bullet on 'Partial IV' 1597 in Section 5). 1599 4. Encrypt the COSE object using the Sender Key. Compress the COSE 1600 Object as specified in Section 6. If the AEAD nonce was 1601 constructed from a new Partial IV, this Partial IV MUST be 1602 included in the message. If the AEAD nonce from the request was 1603 used, the Partial IV MUST NOT be included in the message. 1605 5. Format the OSCORE message according to Section 4. The Object- 1606 Security option is added (see Section 4.1.2). 1608 8.4. Verifying the Response 1610 A client receiving a response containing the Object-Security option 1611 SHALL perform the following steps: 1613 1. Process Outer Block options according to [RFC7959], until all 1614 blocks of the OSCORE message have been received (see 1615 Section 4.1.3.2). 1617 2. Discard the message Code and all non-special Class E options 1618 from the message. For example, ETag Outer option is discarded, 1619 Max-Age Outer option is not discarded. 1621 3. Retrieve the Recipient Context associated with the Token. 1622 Decompress the COSE Object (Section 6). If either the 1623 decompression or the COSE message fails to decode, then go to 1624 11. 1626 4. For Observe notifications, verify the received 'Partial IV' 1627 parameter against the corresponding Notification Number as 1628 described in Section 7.4. If the client receives a notification 1629 for which no Observe request was sent, then go to 11. 1631 5. Compose the Additional Authenticated Data, as described in 1632 Section 5.4. 1634 6. Compute the AEAD nonce 1636 1. If the Observe option and the Partial IV are not present in 1637 the response, the nonce from the request is used. 1639 2. If the Observe option is present in the response, and the 1640 Partial IV is not present in the response, then go to 11. 1642 3. If the Partial IV is present in the response, compute the 1643 nonce from the Recipient ID, Common IV, and the 'Partial IV' 1644 parameter, received in the COSE Object. 1646 7. Decrypt the COSE object using the Recipient Key, as per 1647 [RFC8152] Section 5.3. (The decrypt operation includes the 1648 verification of the integrity.) 1650 * If decryption fails, then go to 11. 1652 * If decryption succeeds and Observe is used, update the 1653 corresponding Notification Number, as described in Section 7. 1655 8. For each decrypted option, check if the option is also present 1656 as an Outer option: if it is, discard the Outer. For example: 1657 the message contains a Max-Age Inner and a Max-Age Outer option. 1658 The Outer Max-Age is discarded. 1660 9. Add decrypted code, options and payload to the decrypted 1661 request. The Object-Security option is removed. 1663 10. The decrypted CoAP response is processed according to [RFC7252] 1665 11. (Optional) In case any of the previous erroneous conditions 1666 apply: the client SHALL stop processing the response. 1668 An error condition occurring while processing a response in an 1669 observation does not cancel the observation. A client MUST NOT react 1670 to failure in step 7 by re-registering the observation immediately. 1672 9. Web Linking 1674 The use of OSCORE MAY be indicated by a target attribute "osc" in a 1675 web link [RFC8288] to a resource. This attribute is a hint 1676 indicating that the destination of that link is to be accessed using 1677 OSCORE. Note that this is simply a hint, it does not include any 1678 security context material or any other information required to run 1679 OSCORE. 1681 A value MUST NOT be given for the "osc" attribute; any present value 1682 MUST be ignored by parsers. The "osc" attribute MUST NOT appear more 1683 than once in a given link-value; occurrences after the first MUST be 1684 ignored by parsers. 1686 10. Proxy and HTTP Operations 1688 RFC 7252 defines operations for a CoAP-to-CoAP proxy (see Section 5.7 1689 of [RFC7252]) and for proxying between CoAP and HTTP (Section 10 of 1690 [RFC7252]). A more detailed description of the HTTP-to-CoAP mapping 1691 is provided by [RFC8075]. This section describes the operations of 1692 OSCORE-aware proxies. 1694 10.1. CoAP-to-CoAP Forwarding Proxy 1696 OSCORE is designed to work with legacy CoAP-to-CoAP forward proxies 1697 [RFC7252], but OSCORE-aware proxies MAY provide certain 1698 simplifications as specified in this section. 1700 Security requirements for forwarding are presented in Section 2.2.1 1701 of [I-D.hartke-core-e2e-security-reqs]. OSCORE complies with the 1702 extended security requirements also addressing Blockwise ([RFC7959]) 1703 and CoAP-mappable HTTP. In particular caching is disabled since the 1704 CoAP response is only applicable to the original CoAP request. An 1705 OSCORE-aware proxy SHALL NOT cache a response to a request with an 1706 Object-Security option. As a consequence, the search for cache hits 1707 and CoAP freshness/Max-Age processing can be omitted. 1709 Proxy processing of the (Outer) Proxy-Uri option is as defined in 1710 [RFC7252]. 1712 Proxy processing of the (Outer) Block options is as defined in 1713 [RFC7959]. 1715 Proxy processing of the (Outer) Observe option is as defined in 1716 [RFC7641]. OSCORE-aware proxies MAY look at the Partial IV value 1717 instead of the Outer Observe option. 1719 10.2. HTTP Processing 1721 OSCORE was initially designed to work between CoAP endpoints only, 1722 but the interest in use cases with one endpoint being an HTTP 1723 endpoint has driven the extension specified here. OSCORE is intended 1724 to be used with at least one endpoint being a CoAP endpoint. 1726 In order to use OSCORE with HTTP, an endpoint needs to be able to map 1727 HTTP messages to CoAP messages (see [RFC8075]), and to apply OSCORE 1728 to CoAP messages (as defined in this document). 1730 For this purpose, this specification defines a new HTTP header field 1731 named CoAP-Object-Security, see Section 12.4. The CoAP-Object- 1732 Security header field is only used in POST requests and 200 (OK) 1733 responses. All field semantics is given within the CoAP-Object- 1734 Security header field. The header field is neither appropriate to 1735 list in the Connection header field (see Section 6.1 of [RFC7230]), 1736 nor in a Vary response header field (see Section 7.1.4 of [RFC7231]), 1737 nor allowed in trailers (see Section 4.1 of [RFC7230]). 1738 Intermediaries are not allowed to insert, delete, or modify the 1739 field's value. The header field is not preserved across redirects. 1741 A sending endpoint uses [RFC8075] to translate an HTTP message into a 1742 CoAP message. It then protects the message with OSCORE processing, 1743 and add the Object-Security option (as defined in this document). 1744 Then, the endpoint maps the resulting CoAP message to an HTTP message 1745 that includes the HTTP header field CoAP-Object-Security, whose value 1746 is: 1748 o "" if the CoAP Object-Security option is empty, or 1750 o the value of the CoAP Object-Security option (Section 6.1) in 1751 base64url encoding (Section 5 of [RFC4648]) without padding (see 1752 [RFC7515] Appendix C for implementation notes for this encoding). 1754 Note that the value of the HTTP body is the CoAP payload, i.e. the 1755 OSCORE payload (Section 6.2). 1757 The HTTP header field Content-Type is set to 'application/oscore' 1758 (see Section 12.5). 1760 The resulting message is an OSCORE message that uses HTTP. 1762 A receiving endpoint uses [RFC8075] to translate an HTTP message into 1763 a CoAP message, with the following addition. The HTTP message 1764 includes the CoAP-Object-Security header field, which is mapped to 1765 the CoAP Object-Security option in the following way. The CoAP 1766 Object-Security option value is: 1768 o empty if the value of the HTTP CoAP-Object-Security header field 1769 is "" 1771 o the value of the HTTP CoAP-Object-Security header field decoded 1772 from base64url (Section 5 of [RFC4648]) without padding (see 1773 [RFC7515] Appendix C for implementation notes for this decoding). 1775 Note that the value of the CoAP payload is the HTTP body, i.e. the 1776 OSCORE payload (Section 6.2). 1778 The resulting message is an OSCORE message that uses CoAP. 1780 The endpoint can then verify the message according to the OSCORE 1781 processing and get a verified CoAP message. It can then translate 1782 the verified CoAP message into a verified HTTP message. 1784 10.3. HTTP-to-CoAP Translation Proxy 1786 Section 10.2 of [RFC7252] and [RFC8075] specify the behavior of an 1787 HTTP-to-CoAP proxy. As requested in Section 1 of [RFC8075], this 1788 section describes the HTTP mapping for the OSCORE protocol extension 1789 of CoAP. 1791 The presence of the Object-Security option, both in requests and 1792 responses, is expressed in an HTTP header field named CoAP-Object- 1793 Security in the mapped request or response. The value of the field 1794 is: 1796 o "" if the CoAP Object-Security option is empty, or 1798 o the value of the CoAP Object-Security option (Section 6.1) in 1799 base64url encoding (Section 5 of [RFC4648]) without padding (see 1800 [RFC7515] Appendix C for implementation notes for this encoding). 1802 The header field Content-Type 'application/oscore' (see Section 12.5) 1803 is used for OSCORE messages transported in HTTP. The CoAP Content- 1804 Format option is omitted for OSCORE messages transported in CoAP. 1806 The value of the body is the OSCORE payload (Section 6.2). 1808 Example: 1810 Mapping and notation here is based on "Simple Form" (Section 5.4.1.1 1811 of [RFC8075]). 1813 [HTTP request -- Before client object security processing] 1815 GET http://proxy.url/hc/?target_uri=coap://server.url/orders 1816 HTTP/1.1 1818 [HTTP request -- HTTP Client to Proxy] 1820 POST http://proxy.url/hc/?target_uri=coap://server.url/ HTTP/1.1 1821 Content-Type: application/oscore 1822 CoAP-Object-Security: CSU 1823 Body: 09 07 01 13 61 f7 0f d2 97 b1 [binary] 1825 [CoAP request -- Proxy to CoAP Server] 1827 POST coap://server.url/ 1828 Object-Security: 09 25 1829 Payload: 09 07 01 13 61 f7 0f d2 97 b1 [binary] 1831 [CoAP request -- After server object security processing] 1833 GET coap://server.url/orders 1835 [CoAP response -- Before server object security processing] 1837 2.05 Content 1838 Content-Format: 0 1839 Payload: Exterminate! Exterminate! 1841 [CoAP response -- CoAP Server to Proxy] 1843 2.04 Changed 1844 Object-Security: [empty] 1845 Payload: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] 1847 [HTTP response -- Proxy to HTTP Client] 1849 HTTP/1.1 200 OK 1850 Content-Type: application/oscore 1851 CoAP-Object-Security: "" 1852 Body: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] 1854 [HTTP response -- After client object security processing] 1856 HTTP/1.1 200 OK 1857 Content-Type: text/plain 1858 Body: Exterminate! Exterminate! 1860 Note that the HTTP Status Code 200 in the next-to-last message is the 1861 mapping of CoAP Code 2.04 (Changed), whereas the HTTP Status Code 200 1862 in the last message is the mapping of the CoAP Code 2.05 (Content), 1863 which was encrypted within the compressed COSE object carried in the 1864 Body of the HTTP response. 1866 10.4. CoAP-to-HTTP Translation Proxy 1868 Section 10.1 of [RFC7252] describes the behavior of a CoAP-to-HTTP 1869 proxy. RFC 8075 [RFC8075] does not cover this direction in any more 1870 detail and so an example instantiation of Section 10.1 of [RFC7252] 1871 is used below. 1873 Example: 1875 [CoAP request -- Before client object security processing] 1877 GET coap://proxy.url/ 1878 Proxy-Uri=http://server.url/orders 1880 [CoAP request -- CoAP Client to Proxy] 1882 POST coap://proxy.url/ 1883 Proxy-Uri=http://server.url/ 1884 Object-Security: 09 25 1885 Payload: 09 07 01 13 61 f7 0f d2 97 b1 [binary] 1887 [HTTP request -- Proxy to HTTP Server] 1889 POST http://server.url/ HTTP/1.1 1890 Content-Type: application/oscore 1891 CoAP-Object-Security: CSU 1892 Body: 09 07 01 13 61 f7 0f d2 97 b1 [binary] 1894 [HTTP request -- After server object security processing] 1896 GET http://server.url/orders HTTP/1.1 1898 [HTTP response -- Before server object security processing] 1900 HTTP/1.1 200 OK 1901 Content-Type: text/plain 1902 Body: Exterminate! Exterminate! 1904 [HTTP response -- HTTP Server to Proxy] 1906 HTTP/1.1 200 OK 1907 Content-Type: application/oscore 1908 CoAP-Object-Security: "" 1909 Body: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] 1911 [CoAP response - Proxy to CoAP Client] 1913 2.04 Changed 1914 Object-Security: [empty] 1915 Payload: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] 1917 [CoAP response -- After client object security processing] 1919 2.05 Content 1920 Content-Format: 0 1921 Payload: Exterminate! Exterminate! 1923 Note that the HTTP Code 2.04 (Changed) in the next-to-last message is 1924 the mapping of HTTP Status Code 200, whereas the CoAP Code 2.05 1925 (Content) in the last message is the value that was encrypted within 1926 the compressed COSE object carried in the Body of the HTTP response. 1928 11. Security Considerations 1930 11.1. End-to-end protection 1932 In scenarios with intermediary nodes such as proxies or gateways, 1933 transport layer security such as (D)TLS only protects data hop-by- 1934 hop. As a consequence, the intermediary nodes can read and modify 1935 information. The trust model where all intermediary nodes are 1936 considered trustworthy is problematic, not only from a privacy 1937 perspective, but also from a security perspective, as the 1938 intermediaries are free to delete resources on sensors and falsify 1939 commands to actuators (such as "unlock door", "start fire alarm", 1940 "raise bridge"). Even in the rare cases, where all the owners of the 1941 intermediary nodes are fully trusted, attacks and data breaches make 1942 such an architecture brittle. 1944 (D)TLS protects hop-by-hop the entire message. OSCORE protects end- 1945 to-end all information that is not required for proxy operations (see 1946 Section 4). (D)TLS and OSCORE can be combined, thereby enabling end- 1947 to-end security of the message payload, in combination with hop-by- 1948 hop protection of the entire message, during transport between end- 1949 point and intermediary node. The CoAP messaging layer, including 1950 header fields such as Type and Message ID, as well as CoAP message 1951 fields Token and Token Length may be changed by a proxy and thus 1952 cannot be protected end-to-end. Error messages occurring during CoAP 1953 processing are protected end-to-end. Error messages occurring during 1954 OSCORE processing are not always possible to protect, e.g. if the 1955 receiving endpoint cannot locate the right security context. It may 1956 still be favorable to send an unprotected error message, e.g. to 1957 prevent extensive retransmissions, so unprotected error messages are 1958 allowed as specified. Similar to error messages, signaling messages 1959 are not always possible to protect as they may be intended for an 1960 intermediary. Hop-by-hop protection of signaling messages can be 1961 achieved with (D)TLS. Applications using unprotected error and 1962 signaling messages need to consider the threat that these messages 1963 may be spoofed. 1965 11.2. Security Context Establishment 1967 The use of COSE to protect messages as specified in this document 1968 requires an established security context. The method to establish 1969 the security context described in Section 3.2 is based on a common 1970 shared secret material in client and server, which may be obtained, 1971 e.g., by using the ACE framework [I-D.ietf-ace-oauth-authz]. An 1972 OSCORE profile of ACE is described in [I-D.ietf-ace-oscore-profile]. 1974 11.3. Replay Protection 1976 Most AEAD algorithms require a unique nonce for each message, for 1977 which the sender sequence numbers in the COSE message field 'Partial 1978 IV' is used. If the recipient accepts any sequence number larger 1979 than the one previously received, then the problem of sequence number 1980 synchronization is avoided. With reliable transport, it may be 1981 defined that only messages with sequence number which are equal to 1982 previous sequence number + 1 are accepted. The alternatives to 1983 sequence numbers have their issues: very constrained devices may not 1984 be able to support accurate time, or to generate and store large 1985 numbers of random nonces. The requirement to change key at counter 1986 wrap is a complication, but it also forces the user of this 1987 specification to think about implementing key renewal. 1989 11.4. Cryptographic Considerations 1991 The maximum sender sequence number is dependent on the AEAD 1992 algorithm. The maximum sender sequence number SHALL be 2^40 - 1, or 1993 any algorithm specific lower limit, after which a new security 1994 context must be generated. The mechanism to build the nonce 1995 (Section 5.2) assumes that the nonce is at least 56 bit-long, and the 1996 Partial IV is at most 40 bit-long. The mandatory-to-implement AEAD 1997 algorithm AES-CCM-16-64-128 is selected for compatibility with CCM*. 1999 The security level of a system with m Masters Keys of length k used 2000 together with Master Salts with entropy n is k + n - log2(m). 2001 Similarly, the security level of a system with m AEAD keys of length 2002 k used together with AEAD nonces of length n is k + n - log2(m). 2003 Security level here means that an attacker can recover one of the m 2004 keys with complexity 2^(k + n) / m. Protection against such attacks 2005 can be provided by increasing the size of the keys or the entropy of 2006 the Master Salt. The complexity of recovering a specific key is 2007 still 2^k (assuming the Master Salt/AEAD nonce is public). The 2008 Master Secret, Sender Key, and Recipient Key MUST be secret, the rest 2009 of the parameters MAY be public. The Master Secret MUST be uniformly 2010 random. 2012 11.5. Message Fragmentation 2014 The Inner Block options enable the sender to split large messages 2015 into OSCORE-protected blocks such that the receiving endpoint can 2016 verify blocks before having received the complete message. The Outer 2017 Block options allow for arbitrary proxy fragmentation operations that 2018 cannot be verified by the endpoints, but can by policy be restricted 2019 in size since the Inner Block options allow for secure fragmentation 2020 of very large messages. A maximum message size (above which the 2021 sending endpoint fragments the message and the receiving endpoint 2022 discards the message, if complying to the policy) may be obtained as 2023 part of normal resource discovery. 2025 11.6. Privacy Considerations 2027 Privacy threats executed through intermediary nodes are considerably 2028 reduced by means of OSCORE. End-to-end integrity protection and 2029 encryption of the message payload and all options that are not used 2030 for proxy operations, provide mitigation against attacks on sensor 2031 and actuator communication, which may have a direct impact on the 2032 personal sphere. 2034 The unprotected options (Figure 5) may reveal privacy sensitive 2035 information. In particular Uri-Host SHOULD NOT contain privacy 2036 sensitive information. CoAP headers sent in plaintext allow, for 2037 example, matching of CON and ACK (CoAP Message Identifier), matching 2038 of request and responses (Token) and traffic analysis. OSCORE does 2039 not provide protection for HTTP header fields which are not CoAP- 2040 mappable. 2042 Unprotected error messages reveal information about the security 2043 state in the communication between the endpoints. Unprotected 2044 signalling messages reveal information about the reliable transport 2045 used on a leg of the path. Using the mechanisms described in 2046 Section 7.5 may reveal when a device goes through a reboot. This can 2047 be mitigated by the device storing the precise state of sender 2048 sequence number and replay window on a clean shutdown. 2050 The length of message fields can reveal information about the 2051 message. Applications may use a padding scheme to protect against 2052 traffic analysis. As an example, the strings "YES" and "NO" even if 2053 encrypted can be distinguished from each other as there is no padding 2054 supplied by the current set of encryption algorithms. Some 2055 information can be determined even from looking at boundary 2056 conditions. An example of this would be returning an integer between 2057 0 and 100 where lengths of 1, 2 and 3 will provide information about 2058 where in the range things are. Three different methods to deal with 2059 this are: 1) ensure that all messages are the same length. For 2060 example, using 0 and 1 instead of "yes" and "no". 2) Use a character 2061 which is not part of the responses to pad to a fixed length. For 2062 example, pad with a space to three characters. 3) Use the PKCS #7 2063 style padding scheme where m bytes are appended each having the value 2064 of m. For example, appending a 0 to "YES" and two 1's to "NO". This 2065 style of padding means that all values need to be padded. Similar 2066 arguments apply to other message fields such as resource names. 2068 12. IANA Considerations 2070 Note to RFC Editor: Please replace all occurrences of "[[this 2071 document]]" with the RFC number of this specification. 2073 Note to IANA: Please note all occurrences of "TBD" in this 2074 specification should be assigned the same number. 2076 12.1. COSE Header Parameters Registry 2078 The 'kid context' parameter is added to the "COSE Header Parameters 2079 Registry": 2081 o Name: kid context 2083 o Label: TBD1 (Integer value between 1 and 255) 2085 o Value Type: bstr 2087 o Value Registry: 2089 o Description: kid context 2091 o Reference: Section 5.1 of this document 2093 12.2. CoAP Option Numbers Registry 2095 The Object-Security option is added to the CoAP Option Numbers 2096 registry: 2098 +--------+-----------------+-------------------+ 2099 | Number | Name | Reference | 2100 +--------+-----------------+-------------------+ 2101 | TBD | Object-Security | [[this document]] | 2102 +--------+-----------------+-------------------+ 2104 12.3. CoAP Signaling Option Numbers Registry 2106 The Object-Security option is added to the CoAP Signaling Option 2107 Numbers registry: 2109 +------------+--------+---------------------+-------------------+ 2110 | Applies to | Number | Name | Reference | 2111 +------------+--------+---------------------+-------------------+ 2112 | 7.xx | TBD | Object-Security | [[this document]] | 2113 +------------+--------+---------------------+-------------------+ 2115 12.4. Header Field Registrations 2117 The HTTP header field CoAP-Object-Security is added to the Message 2118 Headers registry: 2120 +----------------------+----------+----------+-------------------+ 2121 | Header Field Name | Protocol | Status | Reference | 2122 +----------------------+----------+----------+-------------------+ 2123 | CoAP-Object-Security | http | standard | [[this document]] | 2124 +----------------------+----------+----------+-------------------+ 2126 12.5. Media Type Registrations 2128 This section registers the 'application/oscore' media type in the 2129 "Media Types" registry. 2130 These media types are used to indicate that the content is an OSCORE 2131 message. 2133 Type name: application 2135 Subtype name: oscore 2137 Required parameters: N/A 2139 Optional parameters: N/A 2141 Encoding considerations: binary 2143 Security considerations: See the Security Considerations section 2144 of [[This document]]. 2146 Interoperability considerations: N/A 2148 Published specification: [[This document]] 2150 Applications that use this media type: IoT applications sending 2151 security content over HTTP(S) transports. 2153 Fragment identifier considerations: N/A 2155 Additional information: 2157 * Deprecated alias names for this type: N/A 2159 * Magic number(s): N/A 2161 * File extension(s): N/A 2163 * Macintosh file type code(s): N/A 2165 Person & email address to contact for further information: 2166 iesg@ietf.org 2168 Intended usage: COMMON 2170 Restrictions on usage: N/A 2172 Author: Goeran Selander, goran.selander@ericsson.com 2174 Change Controller: IESG 2176 Provisional registration? No 2178 13. References 2180 13.1. Normative References 2182 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2183 Requirement Levels", BCP 14, RFC 2119, 2184 DOI 10.17487/RFC2119, March 1997, . 2187 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 2188 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 2189 . 2191 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 2192 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 2193 January 2012, . 2195 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 2196 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 2197 October 2013, . 2199 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 2200 Protocol (HTTP/1.1): Message Syntax and Routing", 2201 RFC 7230, DOI 10.17487/RFC7230, June 2014, 2202 . 2204 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 2205 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 2206 DOI 10.17487/RFC7231, June 2014, . 2209 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 2210 Application Protocol (CoAP)", RFC 7252, 2211 DOI 10.17487/RFC7252, June 2014, . 2214 [RFC7641] Hartke, K., "Observing Resources in the Constrained 2215 Application Protocol (CoAP)", RFC 7641, 2216 DOI 10.17487/RFC7641, September 2015, . 2219 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 2220 the Constrained Application Protocol (CoAP)", RFC 7959, 2221 DOI 10.17487/RFC7959, August 2016, . 2224 [RFC8075] Castellani, A., Loreto, S., Rahman, A., Fossati, T., and 2225 E. Dijk, "Guidelines for Mapping Implementations: HTTP to 2226 the Constrained Application Protocol (CoAP)", RFC 8075, 2227 DOI 10.17487/RFC8075, February 2017, . 2230 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 2231 FETCH Methods for the Constrained Application Protocol 2232 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 2233 . 2235 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 2236 RFC 8152, DOI 10.17487/RFC8152, July 2017, 2237 . 2239 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2240 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2241 May 2017, . 2243 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 2244 DOI 10.17487/RFC8288, October 2017, . 2247 [RFC8323] Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 2248 Silverajan, B., and B. Raymor, Ed., "CoAP (Constrained 2249 Application Protocol) over TCP, TLS, and WebSockets", 2250 RFC 8323, DOI 10.17487/RFC8323, February 2018, 2251 . 2253 13.2. Informative References 2255 [I-D.bormann-6lo-coap-802-15-ie] 2256 Bormann, C., "Constrained Application Protocol (CoAP) over 2257 IEEE 802.15.4 Information Element for IETF", draft- 2258 bormann-6lo-coap-802-15-ie-00 (work in progress), April 2259 2016. 2261 [I-D.hartke-core-e2e-security-reqs] 2262 Selander, G., Palombini, F., and K. Hartke, "Requirements 2263 for CoAP End-To-End Security", draft-hartke-core-e2e- 2264 security-reqs-03 (work in progress), July 2017. 2266 [I-D.ietf-6tisch-minimal-security] 2267 Vucinic, M., Simon, J., Pister, K., and M. Richardson, 2268 "Minimal Security Framework for 6TiSCH", draft-ietf- 2269 6tisch-minimal-security-05 (work in progress), March 2018. 2271 [I-D.ietf-ace-oauth-authz] 2272 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 2273 H. Tschofenig, "Authentication and Authorization for 2274 Constrained Environments (ACE)", draft-ietf-ace-oauth- 2275 authz-10 (work in progress), February 2018. 2277 [I-D.ietf-ace-oscore-profile] 2278 Seitz, L., Palombini, F., and M. Gunnarsson, "OSCORE 2279 profile of the Authentication and Authorization for 2280 Constrained Environments Framework", draft-ietf-ace- 2281 oscore-profile-00 (work in progress), December 2017. 2283 [I-D.ietf-cbor-cddl] 2284 Birkholz, H., Vigano, C., and C. Bormann, "Concise data 2285 definition language (CDDL): a notational convention to 2286 express CBOR data structures", draft-ietf-cbor-cddl-02 2287 (work in progress), February 2018. 2289 [I-D.ietf-core-echo-request-tag] 2290 Amsuess, C., Mattsson, J., and G. Selander, "Echo and 2291 Request-Tag", draft-ietf-core-echo-request-tag-00 (work in 2292 progress), October 2017. 2294 [I-D.ietf-core-oscore-groupcomm] 2295 Tiloca, M., Selander, G., Palombini, F., and J. Park, 2296 "Secure group communication for CoAP", draft-ietf-core- 2297 oscore-groupcomm-01 (work in progress), March 2018. 2299 [I-D.mattsson-ace-tls-oscore] 2300 Mattsson, J., "Using Transport Layer Security (TLS) to 2301 Secure OSCORE", draft-mattsson-ace-tls-oscore-00 (work in 2302 progress), October 2017. 2304 [I-D.mattsson-core-coap-actuators] 2305 Mattsson, J., Fornehed, J., Selander, G., Palombini, F., 2306 and C. Amsuess, "Controlling Actuators with CoAP", draft- 2307 mattsson-core-coap-actuators-04 (work in progress), March 2308 2018. 2310 [I-D.selander-ace-cose-ecdhe] 2311 Selander, G., Mattsson, J., and F. Palombini, "Ephemeral 2312 Diffie-Hellman Over COSE (EDHOC)", draft-selander-ace- 2313 cose-ecdhe-07 (work in progress), July 2017. 2315 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2316 Resource Identifier (URI): Generic Syntax", STD 66, 2317 RFC 3986, DOI 10.17487/RFC3986, January 2005, 2318 . 2320 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 2321 Encryption", RFC 5116, DOI 10.17487/RFC5116, January 2008, 2322 . 2324 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 2325 Key Derivation Function (HKDF)", RFC 5869, 2326 DOI 10.17487/RFC5869, May 2010, . 2329 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 2330 Constrained-Node Networks", RFC 7228, 2331 DOI 10.17487/RFC7228, May 2014, . 2334 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 2335 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 2336 2015, . 2338 [RFC7967] Bhattacharyya, A., Bandyopadhyay, S., Pal, A., and T. 2339 Bose, "Constrained Application Protocol (CoAP) Option for 2340 No Server Response", RFC 7967, DOI 10.17487/RFC7967, 2341 August 2016, . 2343 Appendix A. Scenario Examples 2345 This section gives examples of OSCORE, targeting scenarios in 2346 Section 2.2.1.1 of [I-D.hartke-core-e2e-security-reqs]. The message 2347 exchanges are made, based on the assumption that there is a security 2348 context established between client and server. For simplicity, these 2349 examples only indicate the content of the messages without going into 2350 detail of the (compressed) COSE message format. 2352 A.1. Secure Access to Sensor 2354 This example illustrates a client requesting the alarm status from a 2355 server. 2357 Client Proxy Server 2358 | | | 2359 +------>| | Code: 0.02 (POST) 2360 | POST | | Token: 0x8c 2361 | | | Object-Security: [kid:5f,Partial IV:42] 2362 | | | Payload: {Code:0.01, 2363 | | | Uri-Path:"alarm_status"} 2364 | | | 2365 | +------>| Code: 0.02 (POST) 2366 | | POST | Token: 0x7b 2367 | | | Object-Security: [kid:5f,Partial IV:42] 2368 | | | Payload: {Code:0.01, 2369 | | | Uri-Path:"alarm_status"} 2370 | | | 2371 | |<------+ Code: 2.04 (Changed) 2372 | | 2.04 | Token: 0x7b 2373 | | | Object-Security: - 2374 | | | Payload: {Code:2.05, "OFF"} 2375 | | | 2376 |<------+ | Code: 2.04 (Changed) 2377 | 2.04 | | Token: 0x8c 2378 | | | Object-Security: - 2379 | | | Payload: {Code:2.05, "OFF"} 2380 | | | 2382 Figure 11: Secure Access to Sensor. Square brackets [ ... ] indicate 2383 content of compressed COSE object. Curly brackets { ... } indicate 2384 encrypted data. 2386 The request/response Codes are encrypted by OSCORE and only dummy 2387 Codes (POST/Changed) are visible in the header of the OSCORE message. 2388 The option Uri-Path ("alarm_status") and payload ("OFF") are 2389 encrypted. 2391 The COSE header of the request contains an identifier (5f), 2392 indicating which security context was used to protect the message and 2393 a Partial IV (42). 2395 The server verifies the request as specified in Section 8.2. The 2396 client verifies the response as specified in Section 8.4. 2398 A.2. Secure Subscribe to Sensor 2400 This example illustrates a client requesting subscription to a blood 2401 sugar measurement resource (GET /glucose), first receiving the value 2402 220 mg/dl and then a second value 180 mg/dl. 2404 Client Proxy Server 2405 | | | 2406 +------>| | Code: 0.05 (FETCH) 2407 | FETCH | | Token: 0x83 2408 | | | Observe: 0 2409 | | | Object-Security: [kid:ca,Partial IV:15] 2410 | | | Payload: {Code:0.01, 2411 | | | Uri-Path:"glucose"} 2412 | | | 2413 | +------>| Code: 0.05 (FETCH) 2414 | | FETCH | Token: 0xbe 2415 | | | Observe: 0 2416 | | | Object-Security: [kid:ca,Partial IV:15] 2417 | | | Payload: {Code:0.01, 2418 | | | Uri-Path:"glucose"} 2419 | | | 2420 | |<------+ Code: 2.04 (Changed) 2421 | | 2.04 | Token: 0xbe 2422 | | | Observe: 7 2423 | | | Object-Security: [Partial IV:32] 2424 | | | Payload: {Code:2.05, 2425 | | | Content-Format:0, "220"} 2426 | | | 2427 |<------+ | Code: 2.04 (Changed) 2428 | 2.04 | | Token: 0x83 2429 | | | Observe: 7 2430 | | | Object-Security: [Partial IV:32] 2431 | | | Payload: {Code:2.05, 2432 | | | Content-Format:0, "220"} 2433 ... ... ... 2434 | | | 2435 | |<------+ Code: 2.04 (Changed) 2436 | | 2.04 | Token: 0xbe 2437 | | | Observe: 8 2438 | | | Object-Security: [Partial IV:36] 2439 | | | Payload: {Code:2.05, 2440 | | | Content-Format:0, "180"} 2441 | | | 2442 |<------+ | Code: 2.04 (Changed) 2443 | 2.04 | | Token: 0x83 2444 | | | Observe: 8 2445 | | | Object-Security: [Partial IV:36] 2446 | | | Payload: {Code:2.05, 2447 | | | Content-Format:0, "180"} 2448 | | | 2450 Figure 12: Secure Subscribe to Sensor. Square brackets [ ... ] 2451 indicate content of compressed COSE object header. Curly brackets { 2452 ... } indicate encrypted data. 2454 The request/response Codes are encrypted by OSCORE and only dummy 2455 Codes (FETCH/Changed) are visible in the header of the OSCORE 2456 message. The options Content-Format (0) and the payload ("220" and 2457 "180"), are encrypted. 2459 The COSE header of the request contains an identifier (ca), 2460 indicating the security context used to protect the message and a 2461 Partial IV (15). The COSE headers of the responses contains Partial 2462 IVs (32 and 36). 2464 The server verifies that the Partial IV has not been received before. 2465 The client verifies that the responses are bound to the request and 2466 that the Partial IVs are greater than any Partial IV previously 2467 received in a response bound to the request. 2469 Appendix B. Deployment examples 2471 OSCORE may be deployed in a variety of settings, a few examples are 2472 given in this section. 2474 B.1. Master Secret Used Once 2476 For settings where the Master Secret is only used during deployment, 2477 the uniqueness of AEAD nonce may be assured by persistent storage of 2478 the security context as described in this specification (see 2479 Section 7.5). For many IoT deployments, a 128 bit uniformly random 2480 Master Key is sufficient for encrypting all data exchanged with the 2481 IoT device throughout its lifetime. 2483 B.2. Master Secret Used Multiple Times 2485 In cases where the Master Secret needs to be used to derive multiple 2486 security contexts, e.g. due to recommissioning or where the security 2487 context is not persistently stored, a stochastically unique Master 2488 Salt prevents the reuse of AEAD nonce and key. The Master Salt may 2489 be transported between client and server in the kid context parameter 2490 (see Section 5.1) of the request. 2492 In this section we give an example of a procedure which may be 2493 implemented in client and server to establish the OSCORE security 2494 context based on pre-established input parameters (see Section 3.2) 2495 except for the Master Salt which is transported in kid context. 2497 1. In order to establish a security context with a server for the 2498 first time, or a new security context replacing an old security 2499 context, the client generates a (pseudo-)random uniformly 2500 distributed 64-bit Master Salt and derives the security context 2501 as specified in Section 3.2. The client protects a request with 2502 the new Sender Context and sends the message with kid context set 2503 to the Master Salt. 2505 2. The server, receiving an OSCORE request with a non-empty kid 2506 context derives the new security context using the received kid 2507 context as Master Salt. The server processes the request as 2508 specified in this document using the new Recipient Context. If 2509 the processing of the request completes without error, the server 2510 responds with an Echo option as specified in 2511 [I-D.ietf-core-echo-request-tag]. The response is protected with 2512 the new Sender Context. 2514 3. The client, receiving a response with an Echo option to a request 2515 which used a new security context, verifies the response using 2516 the new Recipient Context, and if valid repeats the request with 2517 the Echo option (see [I-D.ietf-core-echo-request-tag]) using the 2518 new Sender Context. Subsequent message exchanges (unless 2519 superseded) are processed using the new security context without 2520 including the Master Salt in the kid context. 2522 4. The server, receiving a request with a kid context and a valid 2523 Echo option (see [I-D.ietf-core-echo-request-tag]), repeats the 2524 processing described in step 2. If it completes without error, 2525 then the new security context is established, and the request is 2526 valid. If the server already had an old security context with 2527 this client that is now replaced by the new security context. 2529 If the server receives a request without kid context from a client 2530 with which no security context is established, then the server 2531 responds with a 4.01 Unauthorized error message with diagnostic 2532 payload containing the string "Security context not found". This 2533 could be the result of the server having lost its security context or 2534 that a new security context has not been successfully established, 2535 which may be a trigger for the client to run this procedure. 2537 B.3. Client Aliveness 2539 The use of a single OSCORE request and response enables the client to 2540 verify that the server's identity and aliveness through actual 2541 communications. While a verified OSCORE request enables the server 2542 to verify the identity of the entity who generated the message, it 2543 does not verify that the client is currently involved in the 2544 communication, since the message may be a delayed delivery of a 2545 previously generated request which now reaches the server. To verify 2546 the aliveness of the client the server may initiate an OSCORE 2547 protected message exchange with the client, e.g. by switching the 2548 roles of client and server as described in Section 3.1, or by using 2549 the Echo option in the response to a request from the client 2550 [I-D.ietf-core-echo-request-tag]. 2552 Appendix C. Test Vectors 2554 This appendix includes the test vectors for different examples of 2555 CoAP messages using OSCORE. 2557 C.1. Test Vector 1: Key Derivation with Master Salt 2559 Given a set of inputs, OSCORE defines how to set up the Security 2560 Context in both the client and the server. The default values are 2561 used for AEAD Algorithm and KDF. 2563 C.1.1. Client 2565 Inputs: 2567 o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes) 2569 o Master Salt: 0x9e7ca92223786340 (8 bytes) 2571 o Sender ID: 0x (0 byte) 2573 o Recipient ID: 0x01 (1 byte) 2575 From the previous parameters, 2577 o info (for Sender Key): 0x84400A634b657910 (8 bytes) 2579 o info (for Recipient Key): 0x8441010A634b657910 (9 bytes) 2581 o info (for Common IV): 0x84400a6249560d (7 bytes) 2583 Outputs: 2585 o Sender Key: 0x7230aab3b549d94c9224aacc744e93ab (16 bytes) 2587 o Recipient Key: 0xe534a26a64aa3982e988e31f1e401e65 (16 bytes) 2589 o Common IV: 0x01727733ab49ead385b18f7d91 (13 bytes) 2591 C.1.2. Server 2593 Inputs: 2595 o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes) 2596 o Master Salt: 0x9e7ca92223786340 (64 bytes) 2598 o Sender ID: 0x01 (1 byte) 2600 o Recipient ID: 0x (0 byte) 2602 From the previous parameters, 2604 o info (for Sender Key): 0x8441010A634b657910 (9 bytes) 2606 o info (for Recipient Key): 0x84400A634b657910 (8 bytes) 2608 o info (for Common IV): 0x84400a6249560d (7 bytes) 2610 Outputs: 2612 o Sender Key: 0xe534a26a64aa3982e988e31f1e401e65 (16 bytes) 2614 o Recipient Key: 0x7230aab3b549d94c9224aacc744e93ab (16 bytes) 2616 o Common IV: 0x01727733ab49ead385b18f7d91 (13 bytes) 2618 C.2. Test Vector 2: Key Derivation without Master Salt 2620 Given a set of inputs, OSCORE defines how to set up the Security 2621 Context in both the client and the server. The default values are 2622 used for AEAD Algorithm, KDF, and Master Salt. 2624 C.2.1. Client 2626 Inputs: 2628 o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes) 2630 o Sender ID: 0x00 (1 byte) 2632 o Recipient ID: 0x01 (1 byte) 2634 From the previous parameters, 2636 o info (for Sender Key): 0x8441000A634b657910 (9 bytes) 2638 o info (for Recipient Key): 0x8441010A634b657910 (9 bytes) 2640 o info (for Common IV): 0x84400a6249560d (7 bytes) 2642 Outputs: 2644 o Sender Key: 0xf8f3b887436285ed5a66f6026ac2cdc1 (16 bytes) 2646 o Recipient Key: 0xd904cb101f7341c3f4c56c300fa69941 (16 bytes) 2648 o Common IV: 0xd1a1949aa253278f34c528d2cc (13 bytes) 2650 C.2.2. Server 2652 Inputs: 2654 o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes) 2656 o Sender ID: 0x01 (1 byte) 2658 o Recipient ID: 0x00 (1 byte) 2660 From the previous parameters, 2662 o info (for Sender Key): 0x8441010A634b657910 (9 bytes) 2664 o info (for Recipient Key): 0x8441000A634b657910 (9 bytes) 2666 o info (for Common IV): 0x84400a6249560d (7 bytes) 2668 Outputs: 2670 o Sender Key: 0xd904cb101f7341c3f4c56c300fa69941 (16 bytes) 2672 o Recipient Key: 0xf8f3b887436285ed5a66f6026ac2cdc1 (16 bytes) 2674 o Common IV: 0xd1a1949aa253278f34c528d2cc (13 bytes) 2676 C.3. Test Vector 3: OSCORE Request, Client 2678 This section contains a test vector for a OSCORE protected CoAP GET 2679 request using the security context derived in Appendix C.1. The 2680 unprotected request only contains the Uri-Path option. 2682 Unprotected CoAP request: 2683 0x440149c60000f2a7396c6f63616c686f737483747631 (22 bytes) 2685 Common Context: 2687 o AEAD Algorithm: 10 (AES-CCM-16-64-128) 2689 o Key Derivation Function: HKDF SHA-256 2691 o Common IV: 0xd1a1949aa253278f34c528d2cc (13 bytes) 2692 Sender Context: 2694 o Sender ID: 0x00 (1 byte) 2696 o Sender Key: 0xf8f3b887436285ed5a66f6026ac2cdc1 (16 bytes) 2698 o Sender Sequence Number: 20 2700 The following COSE and cryptographic parameters are derived: 2702 o Partial IV: 0x14 (1 byte) 2704 o kid: 0x00 (1 byte) 2706 o external_aad: 0x8501810a4100411440 (9 bytes) 2708 o AAD: 0x8368456e63727970743040498501810a4100411440 (21 bytes) 2710 o plaintext: 0x01b3747631 (5 bytes) 2712 o encryption key: 0xf8f3b887436285ed5a66f6026ac2cdc1 (16 bytes) 2714 o nonce: 0xd0a1949aa253278f34c528d2d8 (13 bytes) 2716 From the previous parameter, the following is derived: 2718 o Object-Security value: 0x091400 (3 bytes) 2720 o ciphertext: 0x55b3710d47c611cd3924838a44 (13 bytes) 2722 From there: 2724 o Protected CoAP request (OSCORE message): 0x44026dd30000acc5396c6f6 2725 3616c686f7374d305091400ff55b3710d47c611cd3924838a44 (37 bytes) 2727 C.4. Test Vector 4: OSCORE Request, Client 2729 This section contains a test vector for a OSCORE protected CoAP GET 2730 request using the security context derived in Appendix C.2. The 2731 unprotected request only contains the Uri-Path option. 2733 Unprotected CoAP request: 2734 0x440149c60000f2a7396c6f63616c686f737483747631 (22 bytes) 2736 Common Context: 2738 o AEAD Algorithm: 10 (AES-CCM-16-64-128) 2739 o Key Derivation Function: HKDF SHA-256 2741 o Common IV: 0x01727733ab49ead385b18f7d91 (13 bytes) 2743 Sender Context: 2745 o Sender ID: 0x (0 bytes) 2747 o Sender Key: 0x7230aab3b549d94c9224aacc744e93ab (16 bytes) 2749 o Sender Sequence Number: 20 2751 The following COSE and cryptographic parameters are derived: 2753 o Partial IV: 0x14 (1 byte) 2755 o kid: 0x (0 byte) 2757 o external_aad: 0x8501810a40411440 (8 bytes) 2759 o AAD: 0x8368456e63727970743040488501810a40411440 (20 bytes) 2761 o plaintext: 0x01b3747631 (5 bytes) 2763 o encryption key: 0x7230aab3b549d94c9224aacc744e93ab (16 bytes) 2765 o nonce: 0x01727733ab49ead385b18f7d85 (13 bytes) 2767 From the previous parameter, the following is derived: 2769 o Object-Security value: 0x0914 (2 bytes) 2771 o ciphertext: 0x6be9214aad448260ff1be1f594 (13 bytes) 2773 From there: 2775 o Protected CoAP request (OSCORE message): 0x44023bfc000066ef396c6f6 2776 3616c686f7374d2050914ff6be9214aad448260ff1be1f594 (36 bytes) 2778 C.5. Test Vector 5: OSCORE Response, Server 2780 This section contains a test vector for a OSCORE protected 2.05 2781 Content response to the request in Appendix C.3. The unprotected 2782 response has payload "Hello World!" and no options. The protected 2783 response does not contain a kid nor a Partial IV. 2785 Unprotected CoAP response: 2786 0x644549c60000f2a7ff48656c6c6f20576f726c6421 (21 bytes) 2787 Common Context: 2789 o AEAD Algorithm: 10 (AES-CCM-16-64-128) 2791 o Key Derivation Function: HKDF SHA-256 2793 o Common IV: 0xd1a1949aa253278f34c528d2cc (13 bytes) 2795 Sender Context: 2797 o Sender ID: 0x01 (1 byte) 2799 o Sender Key: 0xd904cb101f7341c3f4c56c300fa69941 (16 bytes) 2801 o Sender Sequence Number: 0 2803 The following COSE and cryptographic parameters are derived: 2805 o external_aad: 0x8501810a4100411440 (9 bytes) 2807 o AAD: 0x8368456e63727970743040498501810a4100411440 (21 bytes) 2809 o plaintext: 0x45ff48656c6c6f20576f726c6421 (14 bytes) 2811 o encryption key: 0xd904cb101f7341c3f4c56c300fa69941 (16 bytes) 2813 o nonce: 0xd0a1949aa253278f34c528d2d8 (13 bytes) 2815 From the previous parameter, the following is derived: 2817 o Object-Security value: 0x (0 bytes) 2819 o ciphertext: e4e8c28c41c8f31ca56eec24f6c71d94eacbcdffdc6d (22 2820 bytes) 2822 From there: 2824 o Protected CoAP response (OSCORE message): 0x64446dd30000acc5d008ff 2825 e4e8c28c41c8f31ca56eec24f6c71d94eacbcdffdc6d (33 bytes) 2827 C.6. Test Vector 6: OSCORE Response with Partial IV, Server 2829 This section contains a test vector for a OSCORE protected 2.05 2830 Content response to the request in Appendix C.3. The unprotected 2831 response has payload "Hello World!" and no options. The protected 2832 response does not contain a kid, but contains a Partial IV. 2834 Unprotected CoAP response: 2835 0x644549c60000f2a7ff48656c6c6f20576f726c6421 (21 bytes) 2837 Common Context: 2839 o AEAD Algorithm: 10 (AES-CCM-16-64-128) 2841 o Key Derivation Function: HKDF SHA-256 2843 o Common IV: 0xd1a1949aa253278f34c528d2cc (13 bytes) 2845 Sender Context: 2847 o Sender ID: 0x01 (1 byte) 2849 o Sender Key: 0xd904cb101f7341c3f4c56c300fa69941 (16 bytes) 2851 o Sender Sequence Number: 0 2853 The following COSE and cryptographic parameters are derived: 2855 o Partial IV: 0x00 (1 byte) 2857 o external_aad: 0x8501810a4100411440 (9 bytes) 2859 o AAD: 0x8368456e63727970743040498501810a4100411440 (21 bytes) 2861 o plaintext: 0x45ff48656c6c6f20576f726c6421 (14 bytes) 2863 o encryption key: 0xd904cb101f7341c3f4c56c300fa69941 (16 bytes) 2865 o nonce: 0xd0a1949aa253278e34c528d2cc (13 bytes) 2867 From the previous parameter, the following is derived: 2869 o Object-Security value: 0x0100 (2 bytes) 2871 o ciphertext: 0xa7e3ca27f221f453c0ba68c350bf652ea096b328a1bf (22 2872 bytes) 2874 From there: 2876 o Protected CoAP response (OSCORE message): 0x64442b130000b29ed20801 2877 00ffa7e3ca27f221f453c0ba68c350bf652ea096b328a1bf (35 bytes) 2879 Appendix D. Security properties 2881 This appendix discusses security properties of OSCORE. 2883 TODO 2885 Appendix E. CDDL Summary 2887 Data structure definitions in the present specification employ the 2888 CDDL language for conciseness and precision. CDDL is defined in 2889 [I-D.ietf-cbor-cddl], which at the time of writing this appendix is 2890 in the process of completion. As the document is not yet available 2891 for a normative reference, the present appendix defines the small 2892 subset of CDDL that is being used in the present specification. 2894 Within the subset being used here, a CDDL rule is of the form "name = 2895 type", where "name" is the name given to the "type". A "type" can be 2896 one of: 2898 o a reference to another named type, by giving its name. The 2899 predefined named types used in the present specification are: 2900 "uint", an unsigned integer (as represented in CBOR by major type 2901 0); "int", an unsigned or negative integer (as represented in CBOR 2902 by major type 0 or 1); "bstr", a byte string (as represented in 2903 CBOR by major type 2); "tstr", a text string (as represented in 2904 CBOR by major type 3); 2906 o a choice between two types, by giving both types separated by a 2907 "/"; 2909 o an array type (as represented in CBOR by major type 4), where the 2910 sequence of elements of the array is described by giving a 2911 sequence of entries separated by commas ",", and this sequence is 2912 enclosed by square brackets "[" and "]". Arrays described by an 2913 array description contain elements that correspond one-to-one to 2914 the sequence of entries given. Each entry of an array description 2915 is of the form "name : type", where "name" is the name given to 2916 the entry and "type" is the type of the array element 2917 corresponding to this entry. 2919 Acknowledgments 2921 The following individuals provided input to this document: Christian 2922 Amsuess, Tobias Andersson, Carsten Bormann, Joakim Brorsson, Esko 2923 Dijk, Thomas Fossati, Martin Gunnarsson, Klaus Hartke, Jim Schaad, 2924 Peter van der Stok, Dave Thaler, Marco Tiloca, and Malisa Vucinic. 2926 Ludwig Seitz and Goeran Selander worked on this document as part of 2927 the CelticPlus project CyberWI, with funding from Vinnova. 2929 Authors' Addresses 2931 Goeran Selander 2932 Ericsson AB 2934 Email: goran.selander@ericsson.com 2936 John Mattsson 2937 Ericsson AB 2939 Email: john.mattsson@ericsson.com 2941 Francesca Palombini 2942 Ericsson AB 2944 Email: francesca.palombini@ericsson.com 2946 Ludwig Seitz 2947 RISE SICS 2949 Email: ludwig.seitz@ri.se