idnits 2.17.1 draft-ietf-core-object-security-12.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 30, 2018) is 2217 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) == Unused Reference: 'RFC7230' is defined on line 2356, but no explicit reference was found in the text == Unused Reference: 'RFC7231' is defined on line 2361, but no explicit reference was found in the text ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** 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-11 == Outdated reference: A later version (-19) exists of draft-ietf-ace-oscore-profile-01 == Outdated reference: A later version (-08) exists of draft-ietf-cbor-cddl-02 == Outdated reference: A later version (-14) exists of draft-ietf-core-echo-request-tag-01 == Outdated reference: A later version (-21) exists of draft-ietf-core-oscore-groupcomm-01 == Outdated reference: A later version (-06) exists of draft-mattsson-core-coap-actuators-05 Summary: 6 errors (**), 0 flaws (~~), 10 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: October 1, 2018 Ericsson AB 6 L. Seitz 7 RISE SICS 8 March 30, 2018 10 Object Security for Constrained RESTful Environments (OSCORE) 11 draft-ietf-core-object-security-12 13 Abstract 15 This document defines Object Security for Constrained RESTful 16 Environments (OSCORE), a method for application-layer protection of 17 the Constrained Application Protocol (CoAP), using CBOR Object 18 Signing and Encryption (COSE). OSCORE provides end-to-end protection 19 between endpoints communicating using CoAP or CoAP-mappable HTTP. 20 OSCORE is designed for constrained nodes and networks supporting a 21 range of proxy operations, including translation between different 22 transport protocols. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at https://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on October 1, 2018. 41 Copyright Notice 43 Copyright (c) 2018 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (https://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 59 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 60 2. The OSCORE Option . . . . . . . . . . . . . . . . . . . . . . 7 61 3. The Security Context . . . . . . . . . . . . . . . . . . . . 7 62 3.1. Security Context Definition . . . . . . . . . . . . . . . 7 63 3.2. Establishment of Security Context Parameters . . . . . . 10 64 3.3. Requirements on the Security Context Parameters . . . . . 12 65 4. Protected Message Fields . . . . . . . . . . . . . . . . . . 12 66 4.1. CoAP Options . . . . . . . . . . . . . . . . . . . . . . 13 67 4.2. CoAP Header Fields and Payload . . . . . . . . . . . . . 20 68 4.3. Signaling Messages . . . . . . . . . . . . . . . . . . . 21 69 5. The COSE Object . . . . . . . . . . . . . . . . . . . . . . . 22 70 5.1. Kid Context . . . . . . . . . . . . . . . . . . . . . . . 23 71 5.2. Nonce . . . . . . . . . . . . . . . . . . . . . . . . . . 24 72 5.3. Plaintext . . . . . . . . . . . . . . . . . . . . . . . . 25 73 5.4. Additional Authenticated Data . . . . . . . . . . . . . . 26 74 6. OSCORE Header Compression . . . . . . . . . . . . . . . . . . 26 75 6.1. Encoding of the OSCORE Option Value . . . . . . . . . . . 27 76 6.2. Encoding of the OSCORE Payload . . . . . . . . . . . . . 28 77 6.3. Examples of Compressed COSE Objects . . . . . . . . . . . 28 78 7. Message Binding, Sequence Numbers, Freshness and Replay 79 Protection . . . . . . . . . . . . . . . . . . . . . . . . . 31 80 7.1. Message Binding . . . . . . . . . . . . . . . . . . . . . 31 81 7.2. Sequence Numbers . . . . . . . . . . . . . . . . . . . . 31 82 7.3. Freshness . . . . . . . . . . . . . . . . . . . . . . . . 31 83 7.4. Replay Protection . . . . . . . . . . . . . . . . . . . . 32 84 7.5. Losing Part of the Context State . . . . . . . . . . . . 32 85 8. Processing . . . . . . . . . . . . . . . . . . . . . . . . . 34 86 8.1. Protecting the Request . . . . . . . . . . . . . . . . . 34 87 8.2. Verifying the Request . . . . . . . . . . . . . . . . . . 34 88 8.3. Protecting the Response . . . . . . . . . . . . . . . . . 36 89 8.4. Verifying the Response . . . . . . . . . . . . . . . . . 36 90 9. Web Linking . . . . . . . . . . . . . . . . . . . . . . . . . 38 91 10. CoAP-to-CoAP Forwarding Proxy . . . . . . . . . . . . . . . . 38 92 11. HTTP Operations . . . . . . . . . . . . . . . . . . . . . . . 39 93 11.1. The HTTP OSCORE Header Field . . . . . . . . . . . . . . 39 94 11.2. CoAP-to-HTTP Mapping . . . . . . . . . . . . . . . . . . 40 95 11.3. HTTP-to-CoAP Mapping . . . . . . . . . . . . . . . . . . 40 96 11.4. HTTP Endpoints . . . . . . . . . . . . . . . . . . . . . 41 97 11.5. Example: HTTP Client and CoAP Server . . . . . . . . . . 41 98 11.6. Example: CoAP Client and HTTP Server . . . . . . . . . . 43 99 12. Security Considerations . . . . . . . . . . . . . . . . . . . 44 100 12.1. End-to-end Protection . . . . . . . . . . . . . . . . . 44 101 12.2. Security Context Establishment . . . . . . . . . . . . . 45 102 12.3. Master Secret . . . . . . . . . . . . . . . . . . . . . 45 103 12.4. Replay Protection . . . . . . . . . . . . . . . . . . . 45 104 12.5. Client Aliveness . . . . . . . . . . . . . . . . . . . . 46 105 12.6. Cryptographic Considerations . . . . . . . . . . . . . . 46 106 12.7. Message Segmentation . . . . . . . . . . . . . . . . . . 46 107 12.8. Privacy Considerations . . . . . . . . . . . . . . . . . 47 108 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 47 109 13.1. COSE Header Parameters Registry . . . . . . . . . . . . 47 110 13.2. CoAP Option Numbers Registry . . . . . . . . . . . . . . 48 111 13.3. CoAP Signaling Option Numbers Registry . . . . . . . . . 48 112 13.4. Header Field Registrations . . . . . . . . . . . . . . . 48 113 13.5. Media Type Registrations . . . . . . . . . . . . . . . . 49 114 13.6. CoAP Content-Formats Registry . . . . . . . . . . . . . 51 115 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 51 116 14.1. Normative References . . . . . . . . . . . . . . . . . . 51 117 14.2. Informative References . . . . . . . . . . . . . . . . . 53 118 Appendix A. Scenario Examples . . . . . . . . . . . . . . . . . 55 119 A.1. Secure Access to Sensor . . . . . . . . . . . . . . . . . 55 120 A.2. Secure Subscribe to Sensor . . . . . . . . . . . . . . . 56 121 Appendix B. Deployment Examples . . . . . . . . . . . . . . . . 57 122 B.1. Master Secret Used Once . . . . . . . . . . . . . . . . . 57 123 B.2. Master Secret Used Multiple Times . . . . . . . . . . . . 58 124 Appendix C. Test Vectors . . . . . . . . . . . . . . . . . . . . 59 125 C.1. Test Vector 1: Key Derivation with Master Salt . . . . . 59 126 C.2. Test Vector 2: Key Derivation without Master Salt . . . . 60 127 C.3. Test Vector 3: OSCORE Request, Client . . . . . . . . . . 61 128 C.4. Test Vector 4: OSCORE Request, Client . . . . . . . . . . 63 129 C.5. Test Vector 5: OSCORE Response, Server . . . . . . . . . 64 130 C.6. Test Vector 6: OSCORE Response with Partial IV, Server . 65 131 Appendix D. Overview of Security Properties . . . . . . . . . . 66 132 D.1. Supporting Proxy Operations . . . . . . . . . . . . . . . 66 133 D.2. Protected Message Fields . . . . . . . . . . . . . . . . 66 134 D.3. Uniqueness of (key, nonce) . . . . . . . . . . . . . . . 67 135 D.4. Unprotected Message Fields . . . . . . . . . . . . . . . 68 136 Appendix E. CDDL Summary . . . . . . . . . . . . . . . . . . . . 71 137 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 72 138 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 72 140 1. Introduction 142 The Constrained Application Protocol (CoAP) [RFC7252] is a web 143 transfer protocol, designed for constrained nodes and networks 144 [RFC7228], and may be mapped from HTTP [RFC8075]. CoAP specifies the 145 use of proxies for scalability and efficiency and references DTLS 146 [RFC6347] for security. CoAP-to-CoAP, HTTP-to-CoAP, and CoAP-to-HTTP 147 proxies require DTLS or TLS [RFC5246] to be terminated at the proxy. 148 The proxy therefore not only has access to the data required for 149 performing the intended proxy functionality, but is also able to 150 eavesdrop on, or manipulate any part of, the message payload and 151 metadata in transit between the endpoints. The proxy can also 152 inject, delete, or reorder packets since they are no longer protected 153 by (D)TLS. 155 This document defines the Object Security for Constrained RESTful 156 Environments (OSCORE) security protocol, protecting CoAP and CoAP- 157 mappable HTTP requests and responses end-to-end across intermediary 158 nodes such as CoAP forward proxies and cross-protocol translators 159 including HTTP-to-CoAP proxies [RFC8075]. In addition to the core 160 CoAP features defined in [RFC7252], OSCORE supports Observe 161 [RFC7641], Block-wise [RFC7959], No-Response [RFC7967], and PATCH and 162 FETCH [RFC8132]. An analysis of end-to-end security for CoAP 163 messages through some types of intermediary nodes is performed in 164 [I-D.hartke-core-e2e-security-reqs]. OSCORE essentially protects the 165 RESTful interactions; the request method, the requested resource, the 166 message payload, etc. (see Section 4). OSCORE protects neither the 167 CoAP Messaging Layer nor the CoAP Token which may change between the 168 endpoints, and those are therefore processed as defined in [RFC7252]. 169 Additionally, since the message formats for CoAP over unreliable 170 transport [RFC7252] and for CoAP over reliable transport [RFC8323] 171 differ only in terms of CoAP Messaging Layer, OSCORE can be applied 172 to both unreliable and reliable transports (see Figure 1). 174 +-----------------------------------+ 175 | Application | 176 +-----------------------------------+ 177 +-----------------------------------+ \ 178 | Requests / Responses / Signaling | | 179 |-----------------------------------| | 180 | OSCORE | | CoAP 181 |-----------------------------------| | 182 | Messaging Layer / Message Framing | | 183 +-----------------------------------+ / 184 +-----------------------------------+ 185 | UDP / TCP / ... | 186 +-----------------------------------+ 188 Figure 1: Abstract Layering of CoAP with OSCORE 190 OSCORE works in very constrained nodes and networks, thanks to its 191 small message size and the restricted code and memory requirements in 192 addition to what is required by CoAP. Examples of the use of OSCORE 193 are given in Appendix A. OSCORE does not depend on underlying 194 layers, and can be used with non-IP transports (e.g., 195 [I-D.bormann-6lo-coap-802-15-ie]). OSCORE may also be used in 196 different ways with HTTP. OSCORE messages may be transported in 197 HTTP, and OSCORE may also be used to protect CoAP-mappable HTTP 198 messages, as described below. 200 OSCORE is designed to protect as much information as possible while 201 still allowing CoAP proxy operations (Section 10). It works with 202 legacy CoAP-to-CoAP forward proxies [RFC7252], but an OSCORE-aware 203 proxy will be more efficient. HTTP-to-CoAP proxies [RFC8075] and 204 CoAP-to-HTTP proxies can also be used with OSCORE, as specified in 205 Section 11. OSCORE may be used together with TLS or DTLS over one or 206 more hops in the end-to-end path, e.g. transported with HTTPS in one 207 hop and with plain CoAP in another hop. The use of OSCORE does not 208 affect the URI scheme and OSCORE can therefore be used with any URI 209 scheme defined for CoAP or HTTP. The application decides the 210 conditions for which OSCORE is required. 212 OSCORE uses pre-shared keys which may have been established out-of- 213 band or with a key establishment protocol (see Section 3.2). The 214 technical solution builds on CBOR Object Signing and Encryption 215 (COSE) [RFC8152], providing end-to-end encryption, integrity, replay 216 protection, and binding of response to request. A compressed version 217 of COSE is used, as specified in Section 6. The use of OSCORE is 218 signaled in CoAP with a new option (Section 2), and in HTTP with a 219 new header field (Section 11.1) and content type (Section 13.5). The 220 solution transforms a CoAP/HTTP message into an "OSCORE message" 221 before sending, and vice versa after receiving. The OSCORE message 222 is a CoAP/HTTP message related to the original message in the 223 following way: the original CoAP/HTTP message is translated to CoAP 224 (if not already in CoAP) and protected in a COSE object. The 225 encrypted message fields of this COSE object are transported in the 226 CoAP payload/HTTP body of the OSCORE message, and the OSCORE option/ 227 header field is included in the message. A sketch of an exchange of 228 OSCORE messages, in the case of the original message being CoAP, is 229 provided in Figure 2. 231 Client Server 232 | OSCORE request - POST example.com: | 233 | Header, Token, | 234 | Options: {OSCORE, ...}, | 235 | Payload: COSE ciphertext | 236 +--------------------------------------------->| 237 | | 238 |<---------------------------------------------+ 239 | OSCORE response - 2.04 (Changed): | 240 | Header, Token, | 241 | Options: {OSCORE, ...}, | 242 | Payload: COSE ciphertext | 243 | | 245 Figure 2: Sketch of CoAP with OSCORE 247 An implementation supporting this specification MAY implement only 248 the client part, MAY implement only the server part, or MAY implement 249 only one of the proxy parts. 251 1.1. Terminology 253 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 254 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 255 "OPTIONAL" in this document are to be interpreted as described in BCP 256 14 [RFC2119] [RFC8174] when, and only when, they appear in all 257 capitals, as shown here. 259 Readers are expected to be familiar with the terms and concepts 260 described in CoAP [RFC7252], Observe [RFC7641], Block-wise [RFC7959], 261 COSE [RFC8152], CBOR [RFC7049], CDDL [I-D.ietf-cbor-cddl] as 262 summarized in Appendix E, and constrained environments [RFC7228]. 264 The term "hop" is used to denote a particular leg in the end-to-end 265 path. The concept "hop-by-hop" (as in "hop-by-hop encryption" or 266 "hop-by-hop fragmentation") opposed to "end-to-end", is used in this 267 document to indicate that the messages are processed accordingly in 268 the intermediaries, rather than just forwarded to the next node. 270 The term "stop processing" is used throughout the document to denote 271 that the message is not passed up to the CoAP Request/Response layer 272 (see Figure 1). 274 The terms Common/Sender/Recipient Context, Master Secret/Salt, Sender 275 ID/Key, Recipient ID/Key, and Common IV are defined in Section 3.1. 277 2. The OSCORE Option 279 The OSCORE option (see Figure 3, which extends Table 4 of [RFC7252]) 280 indicates that the CoAP message is an OSCORE message and that it 281 contains a compressed COSE object (see Section 5 and Section 6). The 282 OSCORE option is critical, safe to forward, part of the cache key, 283 and not repeatable. 285 +------+---+---+---+---+-----------------+--------+--------+---------+ 286 | No. | C | U | N | R | Name | Format | Length | Default | 287 +------+---+---+---+---+-----------------+--------+--------+---------+ 288 | TBD1 | x | | | | OSCORE | (*) | 0-255 | (none) | 289 +------+---+---+---+---+-----------------+--------+--------+---------+ 290 C = Critical, U = Unsafe, N = NoCacheKey, R = Repeatable 291 (*) See below. 293 Figure 3: The OSCORE Option 295 The OSCORE option includes the OSCORE flag bits (Section 6), the 296 Sender Sequence Number and the Sender ID when present (Section 3). 297 The detailed format and length is specified in Section 6. If the 298 OSCORE flag bits are all zero (0x00) the Option value SHALL be empty 299 (Option Length = 0). An endpoint receiving a CoAP message without 300 payload, that also contains an OSCORE option SHALL treat it as 301 malformed and reject it. 303 A successful response to a request with the OSCORE option SHALL 304 contain the OSCORE option. Whether error responses contain the 305 OSCORE option depends on the error type (see Section 8). 307 For CoAP proxy operations, see Section 10. 309 3. The Security Context 311 OSCORE requires that client and server establish a shared security 312 context used to process the COSE objects. OSCORE uses COSE with an 313 Authenticated Encryption with Additional Data (AEAD, [RFC5116]) 314 algorithm for protecting message data between a client and a server. 315 In this section, we define the security context and how it is derived 316 in client and server based on a shared secret and a key derivation 317 function (KDF). 319 3.1. Security Context Definition 321 The security context is the set of information elements necessary to 322 carry out the cryptographic operations in OSCORE. For each endpoint, 323 the security context is composed of a "Common Context", a "Sender 324 Context", and a "Recipient Context". 326 The endpoints protect messages to send using the Sender Context and 327 verify messages received using the Recipient Context, both contexts 328 being derived from the Common Context and other data. Clients and 329 servers need to be able to retrieve the correct security context to 330 use. 332 An endpoint uses its Sender ID (SID) to derive its Sender Context, 333 and the other endpoint uses the same ID, now called Recipient ID 334 (RID), to derive its Recipient Context. In communication between two 335 endpoints, the Sender Context of one endpoint matches the Recipient 336 Context of the other endpoint, and vice versa. Thus, the two 337 security contexts identified by the same IDs in the two endpoints are 338 not the same, but they are partly mirrored. Retrieval and use of the 339 security context are shown in Figure 4. 341 .-------------. .-------------. 342 | Common, | | Common, | 343 | Sender, | | Recipient, | 344 | Recipient | | Sender | 345 '-------------' '-------------' 346 Client Server 347 | | 348 Retrieve context for | OSCORE request: | 349 target resource | Token = Token1, | 350 Protect request with | kid = SID, ... | 351 Sender Context +---------------------->| Retrieve context with 352 | | RID = kid 353 | | Verify request with 354 | | Recipient Context 355 | OSCORE response: | Protect response with 356 | Token = Token1, ... | Sender Context 357 Retrieve context with |<----------------------+ 358 Token = Token1 | | 359 Verify request with | | 360 Recipient Context | | 362 Figure 4: Retrieval and use of the Security Context 364 The Common Context contains the following parameters: 366 o AEAD Algorithm. The COSE AEAD algorithm to use for encryption. 368 o Key Derivation Function. The HMAC based HKDF [RFC5869] used to 369 derive Sender Key, Recipient Key, and Common IV. 371 o Master Secret. Variable length, random byte string (see 372 Section 12.3) containing the keying material used to derive 373 traffic keys and IVs. 375 o Master Salt. Variable length byte string containing the salt used 376 to derive traffic keys and IVs. 378 o Common IV. Byte string derived from Master Secret and Master 379 Salt. Length is determined by the AEAD Algorithm. 381 The Sender Context contains the following parameters: 383 o Sender ID. Byte string used to identify the Sender Context and to 384 assure unique AEAD nonces. Maximum length is determined by the 385 AEAD Algorithm. 387 o Sender Key. Byte string containing the symmetric key to protect 388 messages to send. Derived from Common Context and Sender ID. 389 Length is determined by the AEAD Algorithm. 391 o Sender Sequence Number. Non-negative integer used by the sender 392 to protect requests and certain responses, e.g. Observe 393 notifications. Used as 'Partial IV' [RFC8152] to generate unique 394 nonces for the AEAD. Maximum value is determined by the AEAD 395 Algorithm. 397 The Recipient Context contains the following parameters: 399 o Recipient ID. Byte string used to identify the Recipient Context 400 and to assure unique AEAD nonces. Maximum length is determined by 401 the AEAD Algorithm. 403 o Recipient Key. Byte string containing the symmetric key to verify 404 messages received. Derived from Common Context and Recipient ID. 405 Length is determined by the AEAD Algorithm. 407 o Replay Window (Server only). The replay window to verify requests 408 received. 410 All parameters except Sender Sequence Number and Replay Window are 411 immutable once the security context is established. An endpoint may 412 free up memory by not storing the Common IV, Sender Key, and 413 Recipient Key, deriving them from the Master Key and Master Salt when 414 needed. Alternatively, an endpoint may free up memory by not storing 415 the Master Secret and Master Salt after the other parameters have 416 been derived. 418 Endpoints MAY operate as both client and server and use the same 419 security context for those roles. Independent of being client or 420 server, the endpoint protects messages to send using its Sender 421 Context, and verifies messages received using its Recipient Context. 422 The endpoints MUST NOT change the Sender/Recipient ID when changing 423 roles. In other words, changing the roles does not change the set of 424 keys to be used. 426 3.2. Establishment of Security Context Parameters 428 The parameters in the security context are derived from a small set 429 of input parameters. The following input parameters SHALL be pre- 430 established: 432 o Master Secret 434 o Sender ID 436 o Recipient ID 438 The following input parameters MAY be pre-established. In case any 439 of these parameters is not pre-established, the default value 440 indicated below is used: 442 o AEAD Algorithm 444 * Default is AES-CCM-16-64-128 (COSE algorithm encoding: 10) 446 o Master Salt 448 * Default is the empty string 450 o Key Derivation Function (KDF) 452 * Default is HKDF SHA-256 454 o Replay Window Type and Size 456 * Default is DTLS-type replay protection with a window size of 32 457 [RFC6347] 459 All input parameters need to be known to and agreed on by both 460 endpoints, but the replay window may be different in the two 461 endpoints. The way the input parameters are pre-established, is 462 application specific. Considerations of security context 463 establishment are given in Section 12.2 and examples of deploying 464 OSCORE in Appendix B. 466 3.2.1. Derivation of Sender Key, Recipient Key, and Common IV 468 The KDF MUST be one of the HMAC based HKDF [RFC5869] algorithms 469 defined in COSE. HKDF SHA-256 is mandatory to implement. The 470 security context parameters Sender Key, Recipient Key, and Common IV 471 SHALL be derived from the input parameters using the HKDF, which 472 consists of the composition of the HKDF-Extract and HKDF-Expand steps 473 [RFC5869]: 475 output parameter = HKDF(salt, IKM, info, L) 477 where: 479 o salt is the Master Salt as defined above 481 o IKM is the Master Secret as defined above 483 o info is a CBOR array consisting of: 485 info = [ 486 id : bstr, 487 alg_aead : int / tstr, 488 type : tstr, 489 L : uint 490 ] 492 where: 494 o id is the Sender ID or Recipient ID when deriving keys and the 495 empty string when deriving the Common IV. The encoding is 496 described in Section 5. 498 o alg_aead is the AEAD Algorithm, encoded as defined in [RFC8152]. 500 o type is "Key" or "IV". The label is an ASCII string, and does not 501 include a trailing NUL byte. 503 o L is the size of the key/IV for the AEAD algorithm used, in bytes. 505 For example, if the algorithm AES-CCM-16-64-128 (see Section 10.2 in 506 [RFC8152]) is used, the integer value for alg_aead is 10, the value 507 for L is 16 for keys and 13 for the Common IV. 509 3.2.2. Initial Sequence Numbers and Replay Window 511 The Sender Sequence Number is initialized to 0. The supported types 512 of replay protection and replay window length is application specific 513 and depends on how OSCORE is transported, see Section 7.4. The 514 default is DTLS-type replay protection with a window size of 32 515 initiated as described in Section 4.1.2.6 of [RFC6347]. 517 3.3. Requirements on the Security Context Parameters 519 As collisions may lead to the loss of both confidentiality and 520 integrity, Sender ID SHALL be unique in the set of all security 521 contexts using the same Master Secret and Master Salt. To assign 522 identifiers, a trusted third party (e.g., [I-D.ietf-ace-oauth-authz]) 523 or a protocol that allows the parties to negotiate locally unique 524 identifiers can be used. The Sender IDs can be very short. The 525 maximum length of Sender ID in bytes equals the length of AEAD nonce 526 minus 6. For AES-CCM-16-64-128 the maximum length of Sender ID is 7 527 bytes. 529 To simplify retrieval of the right Recipient Context, the Recipient 530 ID SHOULD be unique in the sets of all Recipient Contexts used by an 531 endpoint. If an endpoint has the same Recipient ID with different 532 Recipient Contexts, i.e. the Recipient Contexts are derived from 533 different keying material, then the endpoint may need to try multiple 534 times before finding the right security context associated to the 535 Recipient ID. The Client MAY provide a 'kid context' parameter 536 (Section 5.1) to help the Server find the right context. 538 While the triple (Master Secret, Master Salt, Sender ID) MUST be 539 unique, the same Master Salt MAY be used with several Master Secrets 540 and the same Master Secret MAY be used with several Master Salts. 542 4. Protected Message Fields 544 OSCORE transforms a CoAP message (which may have been generated from 545 an HTTP message) into an OSCORE message, and vice versa. OSCORE 546 protects as much of the original message as possible while still 547 allowing certain proxy operations (see Section 10 and Section 11). 548 This section defines how OSCORE protects the message fields and 549 transfers them end-to-end between client and server (in any 550 direction). 552 The remainder of this section and later sections focus on the 553 behavior in terms of CoAP messages. If HTTP is used for a particular 554 hop in the end-to-end path, then this section applies to the 555 conceptual CoAP message that is mappable to/from the original HTTP 556 message as discussed in Section 11. That is, an HTTP message is 557 conceptually transformed to a CoAP message and then to an OSCORE 558 message, and similarly in the reverse direction. An actual 559 implementation might translate directly from HTTP to OSCORE without 560 the intervening CoAP representation. 562 Protection of Signaling messages (Section 5 of [RFC8323]) is 563 specified in Section 4.3. The other parts of this section target 564 Request/Response messages. 566 Message fields of the CoAP message may be protected end-to-end 567 between CoAP client and CoAP server in different ways: 569 o Class E: encrypted and integrity protected, 571 o Class I: integrity protected only, or 573 o Class U: unprotected. 575 The sending endpoint SHALL transfer Class E message fields in the 576 ciphertext of the COSE object in the OSCORE message. The sending 577 endpoint SHALL include Class I message fields in the Additional 578 Authenticated Data (AAD) of the AEAD algorithm, allowing the 579 receiving endpoint to detect if the value has changed in transfer. 580 Class U message fields SHALL NOT be protected in transfer. Class I 581 and Class U message field values are transferred in the header or 582 options part of the OSCORE message, which is visible to proxies. 584 Message fields not visible to proxies, i.e., transported in the 585 ciphertext of the COSE object, are called "Inner" (Class E). Message 586 fields transferred in the header or options part of the OSCORE 587 message, which is visible to proxies, are called "Outer" (Class I or 588 U). There are currently no Class I options defined. 590 An OSCORE message may contain both an Inner and an Outer instance of 591 a certain CoAP message field. Inner message fields are intended for 592 the receiving endpoint, whereas Outer message fields are used to 593 enable proxy operations. Inner and Outer message fields are 594 processed independently. 596 4.1. CoAP Options 598 A summary of how options are protected is shown in Figure 5. Note 599 that some options may have both Inner and Outer message fields which 600 are protected accordingly. Certain options require special 601 processing as is described in Section 4.1.3. 603 +------+-----------------+---+---+ 604 | No. | Name | E | U | 605 +------+-----------------+---+---+ 606 | 1 | If-Match | x | | 607 | 3 | Uri-Host | | x | 608 | 4 | ETag | x | | 609 | 5 | If-None-Match | x | | 610 | 6 | Observe | | x | 611 | 7 | Uri-Port | | x | 612 | 8 | Location-Path | x | | 613 | TBD1 | OSCORE | | x | 614 | 11 | Uri-Path | x | | 615 | 12 | Content-Format | x | | 616 | 14 | Max-Age | x | x | 617 | 15 | Uri-Query | x | | 618 | 17 | Accept | x | | 619 | 20 | Location-Query | x | | 620 | 23 | Block2 | x | x | 621 | 27 | Block1 | x | x | 622 | 28 | Size2 | x | x | 623 | 35 | Proxy-Uri | | x | 624 | 39 | Proxy-Scheme | | x | 625 | 60 | Size1 | x | x | 626 | 258 | No-Response | x | x | 627 +------+-----------------+---+---+ 629 E = Encrypt and Integrity Protect (Inner) 630 U = Unprotected (Outer) 632 Figure 5: Protection of CoAP Options 634 Options that are unknown or for which OSCORE processing is not 635 defined SHALL be processed as class E (and no special processing). 636 Specifications of new CoAP options SHOULD define how they are 637 processed with OSCORE. A new COAP option SHOULD be of class E unless 638 it requires proxy processing. 640 4.1.1. Inner Options 642 Inner option message fields (class E) are used to communicate 643 directly with the other endpoint. 645 The sending endpoint SHALL write the Inner option message fields 646 present in the original CoAP message into the plaintext of the COSE 647 object (Section 5.3), and then remove the Inner option message fields 648 from the OSCORE message. 650 The processing of Inner option message fields by the receiving 651 endpoint is specified in Section 8.2 and Section 8.4. 653 4.1.2. Outer Options 655 Outer option message fields (Class U or I) are used to support proxy 656 operations, see Appendix D.1. 658 The sending endpoint SHALL include the Outer option message field 659 present in the original message in the options part of the OSCORE 660 message. All Outer option message fields, including the OSCORE 661 option, SHALL be encoded as described in Section 3.1 of [RFC7252], 662 where the delta is the difference to the previously included instance 663 of Outer option message field. 665 The processing of Outer options by the receiving endpoint is 666 specified in Section 8.2 and Section 8.4. 668 A procedure for integrity-protection-only of Class I option message 669 fields is specified in Section 5.4. Proxies MUST NOT change the 670 order of option's occurrences, for options repeatable and of class I. 672 Note: There are currently no Class I option message fields defined. 674 4.1.3. Special Options 676 Some options require special processing as specified in this section. 678 4.1.3.1. Max-Age 680 An Inner Max-Age message field is used to indicate the maximum time a 681 response may be cached by the client (as defined in [RFC7252]), end- 682 to-end from the server to the client, taking into account that the 683 option is not accessible to proxies. The Inner Max-Age SHALL be 684 processed by OSCORE as a normal Inner option, specified in 685 Section 4.1.1. 687 An Outer Max-Age message field is used to avoid unnecessary caching 688 of OSCORE error responses at OSCORE unaware intermediary nodes. A 689 server MAY set a Class U Max-Age message field with value zero to 690 OSCORE error responses, which are described in Section 7.4, 691 Section 8.2 and Section 8.4. Such message field is then processed 692 according to Section 4.1.2. 694 Successful OSCORE responses do not need to include an Outer Max-Age 695 option since the responses are non-cacheable by construction (see 696 Section 4.2). 698 4.1.3.2. Proxy-Uri 700 Proxy-Uri, when present, is split by OSCORE into class U options and 701 class E options, which are processed accordingly. When Proxy-Uri is 702 used in the original CoAP message, Uri-* are not present [RFC7252]. 704 The sending endpoint SHALL first decompose the Proxy-Uri value of the 705 original CoAP message into the Proxy-Scheme, Uri-Host, Uri-Port, Uri- 706 Path, and Uri-Query options (if present) according to Section 6.4 of 707 [RFC7252]. 709 Uri-Path and Uri-Query are class E options and SHALL be protected and 710 processed as Inner options (Section 4.1.1). Uri-Host being an Outer 711 option SHOULD NOT contain privacy sensitive information. 713 The Proxy-Uri option of the OSCORE message SHALL be set to the 714 composition of Proxy-Scheme, Uri-Host, and Uri-Port options (if 715 present) as specified in Section 6.5 of [RFC7252], and processed as 716 an Outer option of Class U (Section 4.1.2). 718 Note that replacing the Proxy-Uri value with the Proxy-Scheme and 719 Uri-* options works by design for all CoAP URIs (see Section 6 of 720 [RFC7252]). OSCORE-aware HTTP servers should not use the userinfo 721 component of the HTTP URI (as defined in Section 3.2.1 of [RFC3986]), 722 so that this type of replacement is possible in the presence of CoAP- 723 to-HTTP proxies. In future documents specifying cross-protocol 724 proxying behavior using different URI structures, it is expected that 725 the authors will create Uri-* options that allow decomposing the 726 Proxy-Uri, and specify in which OSCORE class they belong. 728 An example of how Proxy-Uri is processed is given here. Assume that 729 the original CoAP message contains: 731 o Proxy-Uri = "coap://example.com/resource?q=1" 733 During OSCORE processing, Proxy-Uri is split into: 735 o Proxy-Scheme = "coap" 737 o Uri-Host = "example.com" 739 o Uri-Port = "5683" 741 o Uri-Path = "resource" 743 o Uri-Query = "q=1" 744 Uri-Path and Uri-Query follow the processing defined in 745 Section 4.1.1, and are thus encrypted and transported in the COSE 746 object. The remaining options are composed into the Proxy-Uri 747 included in the options part of the OSCORE message, which has value: 749 o Proxy-Uri = "coap://example.com" 751 See Sections 6.1 and 12.6 of [RFC7252] for more information. 753 4.1.3.3. The Block Options 755 Block-wise [RFC7959] is an optional feature. An implementation MAY 756 support [RFC7252] and the OSCORE option without supporting block-wise 757 transfers. The Block options (Block1, Block2, Size1, Size2), when 758 Inner message fields, provide secure message segmentation such that 759 each segment can be verified. The Block options, when Outer message 760 fields, enables hop-by-hop fragmentation of the OSCORE message. 761 Inner and Outer block processing may have different performance 762 properties depending on the underlying transport. The end-to-end 763 integrity of the message can be verified both in case of Inner and 764 Outer Block-wise transfers provided all blocks are received. 766 4.1.3.3.1. Inner Block Options 768 The sending CoAP endpoint MAY fragment a CoAP message as defined in 769 [RFC7959] before the message is processed by OSCORE. In this case 770 the Block options SHALL be processed by OSCORE as normal Inner 771 options (Section 4.1.1). The receiving CoAP endpoint SHALL process 772 the OSCORE message before processing Block-wise as defined in 773 [RFC7959]. 775 4.1.3.3.2. Outer Block Options 777 Proxies MAY fragment an OSCORE message using [RFC7959], by 778 introducing Block option message fields that are Outer 779 (Section 4.1.2). Note that the Outer Block options are neither 780 encrypted nor integrity protected. As a consequence, a proxy can 781 maliciously inject block fragments indefinitely, since the receiving 782 endpoint needs to receive the last block (see [RFC7959]) to be able 783 to compose the OSCORE message and verify its integrity. Therefore, 784 applications supporting OSCORE and [RFC7959] MUST specify a security 785 policy defining a maximum unfragmented message size 786 (MAX_UNFRAGMENTED_SIZE) considering the maximum size of message which 787 can be handled by the endpoints. Messages exceeding this size SHOULD 788 be fragmented by the sending endpoint using Inner Block options 789 (Section 4.1.3.3.1). 791 An endpoint receiving an OSCORE message with an Outer Block option 792 SHALL first process this option according to [RFC7959], until all 793 blocks of the OSCORE message have been received, or the cumulated 794 message size of the blocks exceeds MAX_UNFRAGMENTED_SIZE. In the 795 former case, the processing of the OSCORE message continues as 796 defined in this document. In the latter case the message SHALL be 797 discarded. 799 Because of encryption of Uri-Path and Uri-Query, messages to the same 800 server may, from the point of view of a proxy, look like they also 801 target the same resource. A proxy SHOULD mitigate a potential mix-up 802 of blocks from concurrent requests to the same server, for example 803 using the Request-Tag processing specified in Section 3.3.2 of 804 [I-D.ietf-core-echo-request-tag]. 806 4.1.3.4. Observe 808 Observe [RFC7641] is an optional feature. An implementation MAY 809 support [RFC7252] and the OSCORE option without supporting [RFC7641]. 810 The Observe option as used here targets the requirements on 811 forwarding of [I-D.hartke-core-e2e-security-reqs] (Section 2.2.1). 813 An Observe intermediary MUST forward the OSCORE option unchanged. In 814 order for an OSCORE-unaware proxy to support forwarding of Observe 815 messages [RFC7641], there SHALL be an Outer Observe option, i.e., 816 present in the options part of the OSCORE message. With OSCORE, 817 Observe intermediaries are forwarding messages without being able to 818 re-send cached notifications to other clients. 820 In order to support multiple concurrent Observe registrations in the 821 same endpoint, Observe intermediaries are allowed to deviate from 822 [RFC7641] and register multiple times to the same (root) resource, 823 since the actual target resource is encrypted and not visible in the 824 OSCORE message. The processing of the CoAP Code for Observe messages 825 is described in Section 4.2. 827 The Observe option in the CoAP request may be legitimately removed by 828 a proxy or ignored by the server. In these cases, the server 829 processes the request as a non-Observe request and produce a non- 830 Observe response. If the OSCORE client receives a response to an 831 Observe request without an Outer Observe value, then it verifies the 832 response as a non-Observe response, as specified in Section 8.4. If 833 the OSCORE client receives a response to a non-Observe request with 834 an Outer Observe value, it stops processing the message, as specified 835 in Section 8.4. 837 It the server accepts the Observe registration, a Partial IV must be 838 included in all notifications (both successful and error). To secure 839 the order of notifications, the client SHALL maintain a Notification 840 Number for each Observation it registers. The Notification Number is 841 a non-negative integer containing the largest Partial IV of the 842 received notifications for the associated Observe registration (see 843 Section 7.4). The Notification Number is initialized to the Partial 844 IV of the first successfully received notification response to the 845 registration request. In contrast to [RFC7641], the received Partial 846 IV MUST always be compared with the Notification Number, which thus 847 MUST NOT be forgotten after 128 seconds. Further details of replay 848 protection of notifications are specified in Section 7.4. The client 849 MAY ignore the Observe option value. 851 Clients can re-register observations to ensure that the observation 852 is still active and establish freshness again ([RFC7641] 853 Section 3.3.1). When an OSCORE observation is refreshed, not only 854 the ETags, but also the partial IV (and thus the payload and OSCORE 855 option) change. The server uses the new request's Partial IV as the 856 'request_piv' of new responses. 858 4.1.3.5. No-Response 860 No-Response [RFC7967] is an optional feature. Clients using No- 861 Response MUST set both an Inner (Class E) and an Outer (Class U) No- 862 Response option, with the same value. 864 The Inner No-Response option is used to communicate to the server the 865 client's disinterest in certain classes of responses to a particular 866 request. The Inner No-Response SHALL be processed by OSCORE as 867 specified in Section 4.1.1. 869 The Outer No-Response option is used to support proxy functionality, 870 specifically to avoid error transmissions from proxies to clients, 871 and to avoid bandwidth reduction to servers by proxies applying 872 congestion control when not receiving responses. The Outer No- 873 Response option is processed according to Section 4.1.2. 875 Note the effect in step 8 of Section 8.4 when applied to No-Response. 876 Applications should consider that a proxy may remove the Outer No- 877 Response option from the request. Applications using No-Response can 878 specify policies to deal with cases where servers receive an Inner 879 No-Response option only, which may be the result of the request 880 having traversed a No-Response unaware proxy, and update the 881 processing in Section 8.4 accordingly. This avoids unnecessary error 882 responses to clients and bandwidth reductions to servers, due to No- 883 Response unaware proxies. 885 4.1.3.6. OSCORE 887 The OSCORE option is only defined to be present in OSCORE messages, 888 as an indication that OSCORE processing have been performed. The 889 content in the OSCORE option is neither encrypted nor integrity 890 protected as a whole but some part of the content of this option is 891 protected (see Section 5.4). Nested use of OSCORE is not supported: 892 If OSCORE processing detects an OSCORE option in the original CoAP 893 message, then processing SHALL be stopped. 895 4.2. CoAP Header Fields and Payload 897 A summary of how the CoAP header fields and payload are protected is 898 shown in Figure 6, including fields specific to CoAP over UDP and 899 CoAP over TCP (marked accordingly in the table). 901 +------------------+---+---+ 902 | Field | E | U | 903 +------------------+---+---+ 904 | Version (UDP) | | x | 905 | Type (UDP) | | x | 906 | Length (TCP) | | x | 907 | Token Length | | x | 908 | Code | x | | 909 | Message ID (UDP) | | x | 910 | Token | | x | 911 | Payload | x | | 912 +------------------+---+---+ 914 E = Encrypt and Integrity Protect (Inner) 915 U = Unprotected (Outer) 917 Figure 6: Protection of CoAP Header Fields and Payload 919 Most CoAP Header fields (i.e. the message fields in the fixed 4-byte 920 header) are required to be read and/or changed by CoAP proxies and 921 thus cannot in general be protected end-to-end between the endpoints. 922 As mentioned in Section 1, OSCORE protects the CoAP Request/Response 923 layer only, and not the Messaging Layer (Section 2 of [RFC7252]), so 924 fields such as Type and Message ID are not protected with OSCORE. 926 The CoAP Header field Code is protected by OSCORE. Code SHALL be 927 encrypted and integrity protected (Class E) to prevent an 928 intermediary from eavesdropping on or manipulating the Code (e.g., 929 changing from GET to DELETE). 931 The sending endpoint SHALL write the Code of the original CoAP 932 message into the plaintext of the COSE object (see Section 5.3). 934 After that, the sending endpoint writes an Outer Code to the OSCORE 935 message. The Outer Code SHALL be set to 0.02 (POST) or 0.05 (FETCH) 936 for requests. For non-Observe requests the client SHALL set the 937 Outer Code to 0.02 (POST). For responses, the sending endpoint SHALL 938 respond with Outer Code 2.04 (Changed) to 0.02 (POST) requests, and 939 with Outer Code 2.05 (Content) to 0.05 (FETCH) requests. Using FETCH 940 with Observe allows OSCORE to be compliant with the Observe 941 processing in OSCORE-unaware intermediaries. The choice of POST and 942 FETCH [RFC8132] allows all OSCORE messages to have payload. 944 The receiving endpoint SHALL discard the Outer Code in the OSCORE 945 message and write the Code of the COSE object plaintext (Section 5.3) 946 into the decrypted CoAP message. 948 The other currently defined CoAP Header fields are Unprotected (Class 949 U). The sending endpoint SHALL write all other header fields of the 950 original message into the header of the OSCORE message. The 951 receiving endpoint SHALL write the header fields from the received 952 OSCORE message into the header of the decrypted CoAP message. 954 The CoAP Payload, if present in the original CoAP message, SHALL be 955 encrypted and integrity protected and is thus an Inner message field. 956 The sending endpoint writes the payload of the original CoAP message 957 into the plaintext (Section 5.3) input to the COSE object. The 958 receiving endpoint verifies and decrypts the COSE object, and 959 recreates the payload of the original CoAP message. 961 4.3. Signaling Messages 963 Signaling messages (CoAP Code 7.00-7.31) were introduced to exchange 964 information related to an underlying transport connection in the 965 specific case of CoAP over reliable transports [RFC8323]. 967 OSCORE MAY be used to protect Signaling if the endpoints for OSCORE 968 coincide with the endpoints for the signaling message. If OSCORE is 969 used to protect Signaling then: 971 o To comply with [RFC8323], an initial empty CSM message SHALL be 972 sent. The subsequent signaling message SHALL be protected. 974 o Signaling messages SHALL be protected as CoAP Request messages, 975 except in the case the Signaling message is a response to a 976 previous Signaling message, in which case it SHALL be protected as 977 a CoAP Response message. For example, 7.02 (Ping) is protected as 978 a CoAP Request and 7.03 (Pong) as a CoAP response. 980 o The Outer Code for Signaling messages SHALL be set to 0.02 (POST), 981 unless it is a response to a previous Signaling message, in which 982 case it SHALL be set to 2.04 (Changed). 984 o All Signaling options, except the OSCORE option, SHALL be Inner 985 (Class E). 987 NOTE: Option numbers for Signaling messages are specific to the CoAP 988 Code (see Section 5.2 of [RFC8323]). 990 If OSCORE is not used to protect Signaling, Signaling messages SHALL 991 be unaltered by OSCORE. 993 5. The COSE Object 995 This section defines how to use COSE [RFC8152] to wrap and protect 996 data in the original message. OSCORE uses the untagged COSE_Encrypt0 997 structure with an Authenticated Encryption with Additional Data 998 (AEAD) algorithm. The key lengths, IV length, nonce length, and 999 maximum Sender Sequence Number are algorithm dependent. 1001 The AEAD algorithm AES-CCM-16-64-128 defined in Section 10.2 of 1002 [RFC8152] is mandatory to implement. For AES-CCM-16-64-128 the 1003 length of Sender Key and Recipient Key is 128 bits, the length of 1004 nonce and Common IV is 13 bytes. The maximum Sender Sequence Number 1005 is specified in Section 12. 1007 As specified in [RFC5116], plaintext denotes the data that is to be 1008 encrypted and integrity protected, and Additional Authenticated Data 1009 (AAD) denotes the data that is to be integrity protected only. 1011 The COSE Object SHALL be a COSE_Encrypt0 object with fields defined 1012 as follows 1014 o The 'protected' field is empty. 1016 o The 'unprotected' field includes: 1018 * The 'Partial IV' parameter. The value is set to the Sender 1019 Sequence Number. All leading zeroes SHALL be removed when 1020 encoding the Partial IV, except in the case of value 0 which is 1021 encoded to the byte string 0x00. This parameter SHALL be 1022 present in requests. In case of Observe notifications 1023 (Section 4.1.3.4) the Partial IV SHALL be present in responses, 1024 and otherwise the Partial IV will not typically be present in 1025 responses. 1027 * The 'kid' parameter. The value is set to the Sender ID. This 1028 parameter SHALL be present in requests and will not typically 1029 be present in responses. An example where the Sender ID is 1030 included in a response is the extension of OSCORE to group 1031 communication [I-D.ietf-core-oscore-groupcomm]. 1033 * Optionally, a 'kid context' parameter as defined in 1034 Section 5.1. This parameter MAY be present in requests and 1035 SHALL NOT be present in responses. 1037 o The 'ciphertext' field is computed from the secret key (Sender Key 1038 or Recipient Key), AEAD nonce (see Section 5.2), plaintext (see 1039 Section 5.3), and the Additional Authenticated Data (AAD) (see 1040 Section 5.4) following Section 5.2 of [RFC8152]. 1042 The encryption process is described in Section 5.3 of [RFC8152]. 1044 5.1. Kid Context 1046 For certain use cases, e.g. deployments where the same kid is used 1047 with multiple contexts, it is necessary or favorable for the sender 1048 to provide an additional identifier of the security material to use, 1049 in order for the receiver to retrieve or establish the correct key. 1050 The kid context parameter is used to provide such additional input. 1051 The kid context and kid are used to determine the security context, 1052 or to establish the necessary input parameters to derive the security 1053 context (see Section 3.2). The application defines how this is done. 1055 The kid context is implicitly integrity protected, as a manipulation 1056 that leads to the wrong key (or no key) being retrieved results in an 1057 error, as described in Section 8.2. 1059 A summary of the COSE header parameter kid context defined above can 1060 be found in Figure 7. 1062 Some examples of relevant uses of kid context are the following: 1064 o If the client has an identifier in some other namespace which can 1065 be used by the server to retrieve or establish the security 1066 context, then that identifier can be used as kid context. The kid 1067 context may be used as Master Salt (Section 3.1) for additional 1068 entropy of the security contexts (see for example Appendix B.2 or 1069 [I-D.ietf-6tisch-minimal-security]). 1071 o In case of a group communication scenario 1072 [I-D.ietf-core-oscore-groupcomm], if the server belongs to 1073 multiple groups, then a group identifier can be used as kid 1074 context to enable the server to find the right security context. 1076 +----------+--------+------------+----------------+-----------------+ 1077 | name | label | value type | value registry | description | 1078 +----------+--------+------------+----------------+-----------------+ 1079 | kid | TBD2 | bstr | | Identifies the | 1080 | context | | | | kid context | 1081 +----------+--------+------------+----------------+-----------------+ 1083 Figure 7: Additional common header parameter for the COSE object 1085 5.2. Nonce 1087 The AEAD nonce is constructed in the following way (see Figure 8): 1089 1. left-padding the Partial IV (PIV) in network byte order with 1090 zeroes to exactly 5 bytes, 1092 2. left-padding the Sender ID of the endpoint that generated the 1093 Partial IV (ID_PIV) in network byte order with zeroes to exactly 1094 nonce length minus 6 bytes, 1096 3. concatenating the size of the ID_PIV (a single byte S) with the 1097 padded ID_PIV and the padded PIV, 1099 4. and then XORing with the Common IV. 1101 Note that in this specification only algorithms that use nonces equal 1102 or greater than 7 bytes are supported. The nonce construction with 1103 S, ID_PIV, and PIV together with endpoint unique IDs and encryption 1104 keys makes it easy to verify that the nonces used with a specific key 1105 will be unique, see Appendix D.3. 1107 If the Partial IV is not present in a response, the nonce from the 1108 request is used. For responses that are not notifications (i.e. when 1109 there is a single response to a request), the request and the 1110 response should typically use the same nonce to reduce message 1111 overhead. Both alternatives provide all the required security 1112 properties, see Appendix D.3 and Section 7.4. The only non-Observe 1113 scenario where a Partial IV must be included in a response is when 1114 the server is unable to perform replay protection, see Section 7.5.2. 1115 For processing instructions see Section 8. 1117 <- nonce length minus 6 B -> <-- 5 bytes --> 1118 +---+-------------------+--------+---------+-----+ 1119 | S | padding | ID_PIV | padding | PIV |----+ 1120 +---+-------------------+--------+---------+-----+ | 1121 | 1122 <---------------- nonce length ----------------> | 1123 +------------------------------------------------+ | 1124 | Common IV |->(XOR) 1125 +------------------------------------------------+ | 1126 | 1127 <---------------- nonce length ----------------> | 1128 +------------------------------------------------+ | 1129 | Nonce |<---+ 1130 +------------------------------------------------+ 1132 Figure 8: AEAD Nonce Formation 1134 5.3. Plaintext 1136 The plaintext is formatted as a CoAP message without Header (see 1137 Figure 9) consisting of: 1139 o the Code of the original CoAP message as defined in Section 3 of 1140 [RFC7252]; and 1142 o all Inner option message fields (see Section 4.1.1) present in the 1143 original CoAP message (see Section 4.1). The options are encoded 1144 as described in Section 3.1 of [RFC7252], where the delta is the 1145 difference to the previously included instance of Class E option; 1146 and 1148 o the Payload of original CoAP message, if present, and in that case 1149 prefixed by the one-byte Payload Marker (0xFF). 1151 0 1 2 3 1152 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 1153 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1154 | Code | Class E options (if any) ... 1155 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1156 |1 1 1 1 1 1 1 1| Payload (if any) ... 1157 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1158 (only if there 1159 is payload) 1161 Figure 9: Plaintext 1163 NOTE: The plaintext contains all CoAP data that needs to be encrypted 1164 end-to-end between the endpoints. 1166 5.4. Additional Authenticated Data 1168 The external_aad SHALL be a CBOR array as defined below: 1170 external_aad = [ 1171 oscore_version : uint, 1172 algorithms : [ alg_aead : int / tstr ], 1173 request_kid : bstr, 1174 request_piv : bstr, 1175 options : bstr 1176 ] 1178 where: 1180 o oscore_version: contains the OSCORE version number. 1181 Implementations of this specification MUST set this field to 1. 1182 Other values are reserved for future versions. 1184 o algorithms: contains (for extensibility) an array of algorithms, 1185 according to this specification only containing alg_aead. 1187 o alg_aead: contains the AEAD Algorithm from the security context 1188 used for the exchange (see Section 3.1). 1190 o request_kid: contains the value of the 'kid' in the COSE object of 1191 the request (see Section 5). 1193 o request_piv: contains the value of the 'Partial IV' in the COSE 1194 object of the request (see Section 5). 1196 o options: contains the Class I options (see Section 4.1.2) present 1197 in the original CoAP message encoded as described in Section 3.1 1198 of [RFC7252], where the delta is the difference to the previously 1199 included instance of class I option. 1201 The oscore_version and algorithms parameters are established out-of- 1202 band and are thus never transported in OSCORE, but the external_aad 1203 allows to verify that they are the same in both endpoints. 1205 NOTE: The format of the external_aad is for simplicity the same for 1206 requests and responses, although some parameters, e.g. request_kid, 1207 need not be integrity protected in the requests. 1209 6. OSCORE Header Compression 1211 The Concise Binary Object Representation (CBOR) [RFC7049] combines 1212 very small message sizes with extensibility. The CBOR Object Signing 1213 and Encryption (COSE) [RFC8152] uses CBOR to create compact encoding 1214 of signed and encrypted data. COSE is however constructed to support 1215 a large number of different stateless use cases, and is not fully 1216 optimized for use as a stateful security protocol, leading to a 1217 larger than necessary message expansion. In this section, we define 1218 a stateless header compression mechanism, simply removing redundant 1219 information from the COSE objects, which significantly reduces the 1220 per-packet overhead. The result of applying this mechanism to a COSE 1221 object is called the "compressed COSE object". 1223 The COSE_Encrypt0 object used in OSCORE is transported in the OSCORE 1224 option and in the Payload. The Payload contains the Ciphertext and 1225 the headers of the COSE object are compactly encoded as described in 1226 the next section. 1228 6.1. Encoding of the OSCORE Option Value 1230 The value of the OSCORE option SHALL contain the OSCORE flag bits, 1231 the Partial IV parameter, the kid context parameter (length and 1232 value), and the kid parameter as follows: 1234 0 1 2 3 4 5 6 7 <--------- n bytes -------------> 1235 +-+-+-+-+-+-+-+-+--------------------------------- 1236 |0 0 0|h|k| n | Partial IV (if any) ... 1237 +-+-+-+-+-+-+-+-+--------------------------------- 1239 <- 1 byte -> <------ s bytes -----> 1240 +------------+----------------------+------------------+ 1241 | s (if any) | kid context (if any) | kid (if any) ... | 1242 +------------+----------------------+------------------+ 1244 Figure 10: The OSCORE Option Value 1246 o The first byte of flag bits encodes the following set of flags and 1247 the length of the Partial IV parameter: 1249 * The three least significant bits encode the Partial IV length 1250 n. If n = 0 then the Partial IV is not present in the 1251 compressed COSE object. The values n = 6 and n = 7 are 1252 reserved. 1254 * The fourth least significant bit is the kid flag, k: it is set 1255 to 1 if the kid is present in the compressed COSE object. 1257 * The fifth least significant bit is the kid context flag, h: it 1258 is set to 1 if the compressed COSE object contains a kid 1259 context (see Section 5.1). 1261 * The sixth to eighth least significant bits are reserved for 1262 future use. These bits SHALL be set to zero when not in use. 1263 According to this specification, if any of these bits are set 1264 to 1 the message is considered to be malformed and 1265 decompression fails as specified in item 3 of Section 8.2. 1267 o The following n bytes encode the value of the Partial IV, if the 1268 Partial IV is present (n > 0). 1270 o The following 1 byte encode the length of the kid context 1271 (Section 5.1) s, if the kid context flag is set (h = 1). 1273 o The following s bytes encode the kid context, if the kid context 1274 flag is set (h = 1). 1276 o The remaining bytes encode the value of the kid, if the kid is 1277 present (k = 1). 1279 Note that the kid MUST be the last field of the OSCORE option value, 1280 even in case reserved bits are used and additional fields are added 1281 to it. 1283 The length of the OSCORE option thus depends on the presence and 1284 length of Partial IV, kid context, kid, as specified in this section, 1285 and on the presence and length of the other parameters, as defined in 1286 the separate documents. 1288 6.2. Encoding of the OSCORE Payload 1290 The payload of the OSCORE message SHALL encode the ciphertext of the 1291 COSE object. 1293 6.3. Examples of Compressed COSE Objects 1295 This section covers a list of OSCORE Header Compression examples for 1296 requests and responses. The examples assume the COSE_Encrypt0 object 1297 is set (which means the CoAP message and cryptographic material is 1298 known). Note that the full CoAP unprotected message, as well as the 1299 full security context, is not reported in the examples, but only the 1300 input necessary to the compression mechanism, i.e. the COSE_Encrypt0 1301 object. The output is the compressed COSE object as defined in 1302 Section 6, divided into two parts, since the object is transported in 1303 two CoAP fields: OSCORE option and payload. 1305 1. Request with ciphertext = 0xaea0155667924dff8a24e4cb35b9, kid = 1306 0x25, and Partial IV = 0x05 1307 Before compression (24 bytes): 1309 [ 1310 h'', 1311 { 4:h'25', 6:h'05' }, 1312 h'aea0155667924dff8a24e4cb35b9' 1313 ] 1315 After compression (17 bytes): 1317 Flag byte: 0b00001001 = 0x09 1319 Option Value: 09 05 25 (3 bytes) 1321 Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) 1323 2. Request with ciphertext = 0xaea0155667924dff8a24e4cb35b9, kid = 1324 empty string, and Partial IV = 0x00 1326 Before compression (23 bytes): 1328 [ 1329 h'', 1330 { 4:h'', 6:h'00' }, 1331 h'aea0155667924dff8a24e4cb35b9' 1332 ] 1334 After compression (16 bytes): 1336 Flag byte: 0b00001001 = 0x09 1338 Option Value: 09 00 (2 bytes) 1340 Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) 1342 3. Request with ciphertext = 0xaea0155667924dff8a24e4cb35b9, kid = 1343 empty string, Partial IV = 0x05, and kid context = 0x44616c656b 1345 Before compression (30 bytes): 1347 [ 1348 h'', 1349 { 4:h'', 6:h'05', 8:h'44616c656b' }, 1350 h'aea0155667924dff8a24e4cb35b9' 1351 ] 1353 After compression (22 bytes): 1355 Flag byte: 0b00011001 = 0x19 1357 Option Value: 19 05 05 44 61 6c 65 6b (8 bytes) 1359 Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) 1361 4. Response with ciphertext = 0xaea0155667924dff8a24e4cb35b9 and no 1362 Partial IV 1364 Before compression (18 bytes): 1366 [ 1367 h'', 1368 {}, 1369 h'aea0155667924dff8a24e4cb35b9' 1370 ] 1372 After compression (14 bytes): 1374 Flag byte: 0b00000000 = 0x00 1376 Option Value: (0 bytes) 1378 Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) 1380 5. Response with ciphertext = 0xaea0155667924dff8a24e4cb35b9 and 1381 Partial IV = 0x07 1383 Before compression (21 bytes): 1385 [ 1386 h'', 1387 { 6:h'07' }, 1388 h'aea0155667924dff8a24e4cb35b9' 1389 ] 1391 After compression (16 bytes): 1393 Flag byte: 0b00000001 = 0x01 1395 Option Value: 01 07 (2 bytes) 1397 Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) 1399 7. Message Binding, Sequence Numbers, Freshness and Replay Protection 1401 7.1. Message Binding 1403 In order to prevent response delay and mismatch attacks 1404 [I-D.mattsson-core-coap-actuators] from on-path attackers and 1405 compromised intermediaries, OSCORE binds responses to the requests by 1406 including the kid and Partial IV of the request in the AAD of the 1407 response. The server therefore needs to store the kid and Partial IV 1408 of the request until all responses have been sent. 1410 7.2. Sequence Numbers 1412 An AEAD nonce MUST NOT be used more than once per AEAD key. The 1413 uniqueness of (key, nonce) pairs is shown in Appendix D.3, and in 1414 particular depends on a correct usage of Partial IVs. If messages 1415 are processed concurrently, the operation of reading and increasing 1416 the Sender Sequence Number MUST be atomic. 1418 The maximum Sender Sequence Number is algorithm dependent (see 1419 Section 12), and SHALL be less than 2^40. If the Sender Sequence 1420 Number exceeds the maximum, the endpoint MUST NOT process any more 1421 messages with the given Sender Context. If necessary, the endpoint 1422 SHOULD acquire a new security context before this happens. The 1423 latter is out of scope of this document. 1425 7.3. Freshness 1427 For requests, OSCORE provides only the guarantee that the request is 1428 not older than the security context. For applications having 1429 stronger demands on request freshness (e.g., control of actuators), 1430 OSCORE needs to be augmented with mechanisms providing freshness, for 1431 example as specified in [I-D.ietf-core-echo-request-tag]. 1433 Assuming an honest server, the message binding guarantees that a 1434 response is not older than its request. For responses that are not 1435 notifications (i.e. when there is a single response to a request), 1436 this gives absolute freshness. For notifications, the absolute 1437 freshness gets weaker with time, and it is RECOMMENDED that the 1438 client regularly re-register the observation. Note that the message 1439 binding does not guarantee that misbehaving server created the 1440 response before receiving the request, i.e. it does not verify server 1441 aliveness. 1443 For requests and notifications, OSCORE also provides relative 1444 freshness in the sense that the received Partial IV allows a 1445 recipient to determine the relative order of requests or responses. 1447 7.4. Replay Protection 1449 In order to protect from replay of requests, the server's Recipient 1450 Context includes a Replay Window. A server SHALL verify that a 1451 Partial IV received in the COSE object has not been received before. 1452 If this verification fails the server SHALL stop processing the 1453 message, and MAY optionally respond with a 4.01 Unauthorized error 1454 message. Also, the server MAY set an Outer Max-Age option with value 1455 zero. The diagnostic payload MAY contain the "Replay detected" 1456 string. The size and type of the Replay Window depends on the use 1457 case and the protocol with which the OSCORE message is transported. 1458 In case of reliable and ordered transport from endpoint to endpoint, 1459 e.g. TCP, the server MAY just store the last received Partial IV and 1460 require that newly received Partial IVs equals the last received 1461 Partial IV + 1. However, in case of mixed reliable and unreliable 1462 transports and where messages may be lost, such a replay mechanism 1463 may be too restrictive and the default replay window be more suitable 1464 (see Section 3.2.2). 1466 Responses that are not notifications (with or without Partial IV) are 1467 protected against replay as they are bound to the request and the 1468 fact that only a single response is accepted. Note that the Partial 1469 IV is not used for replay protection in this case. 1471 A client receiving a notification SHALL compare the Partial IV of a 1472 received notification with the Notification Number associated to that 1473 Observe registration. A client MUST consider the notification with 1474 the highest Partial IV as the freshest, regardless of the order of 1475 arrival. If the verification of the response succeeds, and the 1476 received Partial IV was greater than the Notification Number then the 1477 client SHALL overwrite the corresponding Notification Number with the 1478 received Partial IV (see step 7 of Section 8.4. The client MUST stop 1479 processing notifications with a Partial IV which has been previously 1480 received. The client MAY process only notifications which have 1481 greater Partial IV than the Notification Number. 1483 If messages are processed concurrently, the Partial IV needs to be 1484 validated a second time after decryption and before updating the 1485 replay protection data. The operation of validating the Partial IV 1486 and updating the replay protection data MUST be atomic. 1488 7.5. Losing Part of the Context State 1490 To prevent reuse of an AEAD nonce with the same key, or from 1491 accepting replayed messages, an endpoint needs to handle the 1492 situation of losing rapidly changing parts of the context, such as 1493 the request Token, Sender Sequence Number, Replay Window, and 1494 Notification Numbers. These are typically stored in RAM and 1495 therefore lost in the case of an unplanned reboot. 1497 After boot, an endpoint MAY reject to use pre-existing security 1498 contexts, and MAY establish a new security context with each endpoint 1499 it communicates with. However, establishing a fresh security context 1500 may have a non-negligible cost in terms of, e.g., power consumption. 1502 After boot, an endpoint MAY use a partly persistently stored security 1503 context, but then the endpoint MUST NOT reuse a previous Sender 1504 Sequence Number and MUST NOT accept previously accepted messages. 1505 Some ways to achieve this are described in the following sections. 1507 7.5.1. Sequence Number 1509 To prevent reuse of Sender Sequence Numbers, an endpoint MAY perform 1510 the following procedure during normal operations: 1512 o Before using a Sender Sequence Number that is evenly divisible by 1513 K, where K is a positive integer, store the Sender Sequence Number 1514 in persistent memory. After boot, the endpoint initiates the 1515 Sender Sequence Number to the value stored in persistent memory + 1516 K. Storing to persistent memory can be costly. The value K gives 1517 a trade-off between the number of storage operations and efficient 1518 use of Sender Sequence Numbers. 1520 7.5.2. Replay Window 1522 To prevent accepting replay of previously received requests, the 1523 server MAY perform the following procedure after boot: 1525 o For each stored security context, the first time after boot the 1526 server receives an OSCORE request, the server responds with the 1527 Echo option [I-D.ietf-core-echo-request-tag] to get a request with 1528 verifiable freshness. The server MUST use its Partial IV when 1529 generating the AEAD nonce and MUST include the Partial IV in the 1530 response. 1532 If the server using the Echo option can verify a second request as 1533 fresh, then the Partial IV of the second request is set as the lower 1534 limit of the replay window. 1536 7.5.3. Replay Protection of Observe Notifications 1538 To prevent accepting replay of previously received notification 1539 responses, the client MAY perform the following procedure after boot: 1541 o The client rejects notifications bound to the earlier 1542 registration, removes all Notification Numbers and re-registers 1543 using Observe. 1545 8. Processing 1547 This section describes the OSCORE message processing. 1549 8.1. Protecting the Request 1551 Given a CoAP request, the client SHALL perform the following steps to 1552 create an OSCORE request: 1554 1. Retrieve the Sender Context associated with the target resource. 1556 2. Compose the Additional Authenticated Data and the plaintext, as 1557 described in Section 5.4 and Section 5.3. 1559 3. Encode the Partial IV (Sender Sequence Number in network byte 1560 order) and increment the Sender Sequence Number by one. Compute 1561 the AEAD nonce from the Sender ID, Common IV, and Partial IV as 1562 described in Section 5.2. 1564 4. Encrypt the COSE object using the Sender Key. Compress the COSE 1565 Object as specified in Section 6. 1567 5. Format the OSCORE message according to Section 4. The OSCORE 1568 option is added (see Section 4.1.2). 1570 6. Store the attribute-value pair (Token, {Security Context, PIV}) 1571 in order to be able to find the Recipient Context and the 1572 request_piv from the Token in the response. 1574 8.2. Verifying the Request 1576 A server receiving a request containing the OSCORE option SHALL 1577 perform the following steps: 1579 1. Process Outer Block options according to [RFC7959], until all 1580 blocks of the request have been received (see Section 4.1.3.3). 1582 2. Discard the message Code and all non-special Inner option 1583 message fields (marked in Figure 5 with 'x' in column E only) 1584 present in the received message. For example, an If-Match Outer 1585 option is discarded, but an Uri-Host Outer option is not 1586 discarded. 1588 3. Decompress the COSE Object (Section 6) and retrieve the 1589 Recipient Context associated with the Recipient ID in the 'kid' 1590 parameter. If either the decompression or the COSE message 1591 fails to decode, or the server fails to retrieve a Recipient 1592 Context with Recipient ID corresponding to the 'kid' parameter 1593 received, then the server SHALL stop processing the request. 1594 If: 1596 * either the decompression or the COSE message fails to decode, 1597 the server MAY respond with a 4.02 Bad Option error message. 1598 The server MAY set an Outer Max-Age option with value zero. 1599 The diagnostic payload SHOULD contain the string "Failed to 1600 decode COSE". 1602 * the server fails to retrieve a Recipient Context with 1603 Recipient ID corresponding to the 'kid' parameter received, 1604 the server MAY respond with a 4.01 Unauthorized error 1605 message. The server MAY set an Outer Max-Age option with 1606 value zero. The diagnostic payload SHOULD contain the string 1607 "Security context not found". 1609 4. Verify the 'Partial IV' parameter using the Replay Window, as 1610 described in Section 7.4. 1612 5. Compose the Additional Authenticated Data, as described in 1613 Section 5.4. 1615 6. Compute the AEAD nonce from the Recipient ID, Common IV, and the 1616 'Partial IV' parameter, received in the COSE Object. 1618 7. Decrypt the COSE object using the Recipient Key, as per 1619 [RFC8152] Section 5.3. (The decrypt operation includes the 1620 verification of the integrity.) 1622 * If decryption fails, the server MUST stop processing the 1623 request and MAY respond with a 4.00 Bad Request error 1624 message. The server MAY set an Outer Max-Age option with 1625 value zero. The diagnostic payload MAY contain the 1626 "Decryption failed" string. 1628 * If decryption succeeds, update the Replay Window, as 1629 described in Section 7. 1631 8. For each decrypted option, check if the option is also present 1632 as an Outer option: if it is, discard the Outer. For example: 1633 the message contains a Max-Age Inner and a Max-Age Outer option. 1634 The Outer Max-Age is discarded. 1636 9. Add decrypted code, options and payload to the decrypted 1637 request. The OSCORE option is removed. 1639 10. The decrypted CoAP request is processed according to [RFC7252]. 1641 8.3. Protecting the Response 1643 If a CoAP response is generated in response to an OSCORE request, the 1644 server SHALL perform the following steps to create an OSCORE 1645 response. Note that CoAP error responses derived from CoAP 1646 processing (point 10. in Section 8.2) are protected, as well as 1647 successful CoAP responses, while the OSCORE errors (point 3, 4, and 7 1648 in Section 8.2) do not follow the processing below, but are sent as 1649 simple CoAP responses, without OSCORE processing. 1651 1. Retrieve the Sender Context in the Security Context used to 1652 verify the request. 1654 2. Compose the Additional Authenticated Data and the plaintext, as 1655 described in Section 5.4 and Section 5.3. 1657 3. Compute the AEAD nonce 1659 * For Observe notifications, encode the Partial IV (Sender 1660 Sequence Number in network byte order) and increment the 1661 Sender Sequence Number by one. Compute the AEAD nonce from 1662 the Sender ID, Common IV, and Partial IV as described in 1663 Section 5.2. 1665 * For responses that are not Observe notifications, either use 1666 the nonce from the request, or compute a new nonce from the 1667 Sender ID, Common IV, and a new Partial IV as described in 1668 Section 5.2, and increment the Sender Sequence Number by one. 1670 4. Encrypt the COSE object using the Sender Key. Compress the COSE 1671 Object as specified in Section 6. If the AEAD nonce was 1672 constructed from a new Partial IV, this Partial IV MUST be 1673 included in the message. If the AEAD nonce from the request was 1674 used, the Partial IV MUST NOT be included in the message. 1676 5. Format the OSCORE message according to Section 4. The OSCORE 1677 option is added (see Section 4.1.2). 1679 8.4. Verifying the Response 1681 A client receiving a response containing the OSCORE option SHALL 1682 perform the following steps: 1684 1. Process Outer Block options according to [RFC7959], until all 1685 blocks of the OSCORE message have been received (see 1686 Section 4.1.3.3). 1688 2. Discard the message Code and all non-special Class E options 1689 from the message. For example, ETag Outer option is discarded, 1690 Max-Age Outer option is not discarded. 1692 3. Retrieve the Recipient Context associated with the Token. 1693 Decompress the COSE Object (Section 6). If either the 1694 decompression or the COSE message fails to decode, then go to 1695 11. 1697 4. If the Observe option is present in the response, but the 1698 request was not an Observe registration, then go to 11. If a 1699 Partial IV is required (i.e. an Observe option is included or 1700 the Notification number for the observation has already been 1701 initiated), but not present in the response, then go to 11. For 1702 Observe notifications, verify the received 'Partial IV' 1703 parameter against the corresponding Notification Number as 1704 described in Section 7.4. 1706 5. Compose the Additional Authenticated Data, as described in 1707 Section 5.4. 1709 6. Compute the AEAD nonce 1711 * If the Partial IV are not present in the response, the nonce 1712 from the request is used. 1714 * If the Partial IV is present in the response, compute the 1715 nonce from the Recipient ID, Common IV, and the 'Partial IV' 1716 parameter, received in the COSE Object. 1718 7. Decrypt the COSE object using the Recipient Key, as per 1719 [RFC8152] Section 5.3. (The decrypt operation includes the 1720 verification of the integrity.) If decryption fails, then go to 1721 11. 1723 8. If the response is a notification, initiate or update the 1724 corresponding Notification Number, as described in Section 7. 1725 Otherwise, delete the attribute-value pair (Token, {Security 1726 Context, PIV}). 1728 9. For each decrypted option, check if the option is also present 1729 as an Outer option: if it is, discard the Outer. For example: 1730 the message contains a Max-Age Inner and a Max-Age Outer option. 1731 The Outer Max-Age is discarded. 1733 10. Add decrypted code, options and payload to the decrypted 1734 request. The OSCORE option is removed. 1736 11. The decrypted CoAP response is processed according to [RFC7252]. 1738 12. In case any of the previous erroneous conditions apply: the 1739 client SHALL stop processing the response. 1741 An error condition occurring while processing a response in an 1742 observation does not cancel the observation. A client MUST NOT react 1743 to failure in step 7 by re-registering the observation immediately. 1745 9. Web Linking 1747 The use of OSCORE MAY be indicated by a target attribute "osc" in a 1748 web link [RFC8288] to a resource, e.g. using a link-format document 1749 [RFC6690] if the resource is accessible over CoAP. 1751 The "osc" attribute is a hint indicating that the destination of that 1752 link is only accessible using OSCORE, and unprotected access to it is 1753 not supported. Note that this is simply a hint, it does not include 1754 any security context material or any other information required to 1755 run OSCORE. 1757 A value MUST NOT be given for the "osc" attribute; any present value 1758 MUST be ignored by parsers. The "osc" attribute MUST NOT appear more 1759 than once in a given link-value; occurrences after the first MUST be 1760 ignored by parsers. 1762 The example in Figure 11 shows a use of the "osc" attribute: the 1763 client does resource discovery on a server, and gets back a list of 1764 resources, one of which includes the "osc" attribute indicating that 1765 the resource is protected with OSCORE. The link-format notation (see 1766 Section 5. of [RFC6690]) is used. 1768 REQ: GET /.well-known/core 1770 RES: 2.05 Content 1771 ;osc, 1772 ;if="sensor" 1774 Figure 11: The web link 1776 10. CoAP-to-CoAP Forwarding Proxy 1778 CoAP is designed for proxy operations (see Section 5.7 of [RFC7252]). 1779 Security requirements for forwarding are presented in Section 2.2.1 1780 of [I-D.hartke-core-e2e-security-reqs]. 1782 OSCORE is designed to work with legacy CoAP proxies. Since a CoAP 1783 response is only applicable to the original CoAP request, caching is 1784 in general not useful. In support of legacy proxies, OSCORE defines 1785 special Max-Age processing, see Section 4.1.3.1. An OSCORE-aware 1786 proxy SHOULD NOT cache a response to a request with an OSCORE option 1788 Proxy processing of the (Outer) Proxy-Uri option is as defined in 1789 [RFC7252]. 1791 Proxy processing of the (Outer) Block options is as defined in 1792 [RFC7959]. 1794 Proxy processing of the (Outer) Observe option is as defined in 1795 [RFC7641]. OSCORE-aware proxies may look at the Partial IV value 1796 instead of the Outer Observe option. 1798 11. HTTP Operations 1800 The CoAP request/response model may be mapped to HTTP and vice versa 1801 as described in Section 10 of [RFC7252]. The HTTP-CoAP mapping is 1802 further detailed in [RFC8075]. This section defines the components 1803 needed to map and transport OSCORE messages over HTTP hops. By 1804 mapping between HTTP and CoAP and by using cross-protocol proxies 1805 OSCORE may be used end-to-end between e.g. an HTTP client and a CoAP 1806 server. Examples are provided at the end of the section. 1808 11.1. The HTTP OSCORE Header Field 1810 The HTTP OSCORE Header Field (see Section 13.4) is used for carrying 1811 the content of the CoAP OSCORE option when transporting OSCORE 1812 messages over HTTP hops. 1814 The HTTP OSCORE header field is only used in POST requests and 200 1815 (OK) responses. When used, the HTTP header field Content-Type is set 1816 to 'application/oscore' (see Section 13.5) indicating that the HTTP 1817 body of this message contains the OSCORE payload (see Section 6.2}. 1818 No additional semantics is provided by other message fields. 1820 Using the Augmented Backus-Naur Form (ABNF) notation of [RFC5234], 1821 including the following core ABNF syntax rules defined by that 1822 specification: ALPHA (letters) and DIGIT (decimal digits), the HTTP 1823 OSCORE header field value is as follows. 1825 base64url-char = ALPHA / DIGIT / "-" / "_" 1827 OSCORE = 2*base64url-char 1828 The HTTP OSCORE header field is not appropriate to list in the 1829 Connection header field (see Section 6.1 of [RFC7230]) since it is 1830 not hop-by-hop. The HTTP OSCORE header field is not appropriate to 1831 list in a Vary response header field (see Section 7.1.4 of [RFC7231]) 1832 since a cached response would in general not be useful for other 1833 clients. The HTTP OSCORE header field is not useful in trailers (see 1834 Section 4.1 of [RFC7230]). 1836 Intermediaries are in general not allowed to insert, delete, or 1837 modify the OSCORE header. Changes to the HTTP OSCORE header field 1838 will in general violate the integrity of the OSCORE message resulting 1839 in an error. For the same reason the HTTP OSCORE header field is in 1840 general not preserved across redirects. A CoAP-to-HTTP proxy 1841 receiving a request for redirect may copy the HTTP OSCORE header 1842 field to the new request, although the condition for this being 1843 successful is that the server to which the OSCORE message is 1844 redirected needs to be a clone of the server for which the OSCORE 1845 message was intended (same target resource, same OSCORE security 1846 context etc.). If an HTTP/OSCORE client receives a redirect it 1847 should instead generate a new OSCORE request for the server it was 1848 redirected to. 1850 11.2. CoAP-to-HTTP Mapping 1852 Section 10.1 of [RFC7252] describes the fundamentals of the CoAP-to- 1853 HTTP cross-protocol mapping process. The additional rules for OSCORE 1854 messages are: 1856 o The HTTP OSCORE header field value is set to 1858 * AA if the CoAP OSCORE option is empty, otherwise 1860 * the value of the CoAP OSCORE option (Section 6.1) in base64url 1861 (Section 5 of [RFC4648]) encoding without padding. 1862 Implementation notes for this encoding are given in Appendix C 1863 of [RFC7515]. 1865 o The HTTP Content-Type is set to 'application/oscore' (see 1866 Section 13.5), independent of CoAP Content-Format. 1868 11.3. HTTP-to-CoAP Mapping 1870 Section 10.2 of [RFC7252] and [RFC8075] specify the behavior of an 1871 HTTP-to-CoAP proxy. The additional rules for HTTP messages with the 1872 OSCORE header field are: 1874 o The CoAP OSCORE option is set as follows: 1876 * empty if the value of the HTTP OSCORE header field is a single 1877 zero byte (0x00) represented by AA, otherwise 1879 * the value of the HTTP OSCORE header field decoded from 1880 base64url (Section 5 of [RFC4648]) without padding. 1881 Implementation notes for this encoding are given in Appendix C 1882 of [RFC7515]. 1884 o The CoAP Content-Format option is omitted, the content format for 1885 OSCORE (Section 13.6) MUST NOT be used. 1887 11.4. HTTP Endpoints 1889 Restricted to subsets of HTTP and CoAP supporting a bijective 1890 mapping, OSCORE can be originated or terminated in HTTP endpoints. 1892 The sending HTTP endpoint uses [RFC8075] to translate the HTTP 1893 message into a CoAP message. The CoAP message is then processed with 1894 OSCORE as defined in this document. The OSCORE message is then 1895 mapped to HTTP as described in Section 11.2 and sent in compliance 1896 with the rules in Section 11.1. 1898 The receiving HTTP endpoint maps the HTTP message to a CoAP message 1899 using [RFC8075] and Section 11.3. The resulting OSCORE message is 1900 processed as defined in this document. If successful, the plaintext 1901 CoAP message is translated to HTTP for normal processing in the 1902 endpoint. 1904 11.5. Example: HTTP Client and CoAP Server 1906 This section is giving an example of how a request and a response 1907 between an HTTP client and a CoAP server could look like. The 1908 example is not a test vector but intended as an illustration of how 1909 the message fields are translated in the different steps. 1911 Mapping and notation here is based on "Simple Form" (Section 5.4.1 of 1912 [RFC8075]). 1914 [HTTP request -- Before client object security processing] 1916 GET http://proxy.url/hc/?target_uri=coap://server.url/orders 1917 HTTP/1.1 1919 [HTTP request -- HTTP Client to Proxy] 1921 POST http://proxy.url/hc/?target_uri=coap://server.url/ HTTP/1.1 1922 Content-Type: application/oscore 1923 OSCORE: CSU 1924 Body: 09 07 01 13 61 f7 0f d2 97 b1 [binary] 1926 [CoAP request -- Proxy to CoAP Server] 1928 POST coap://server.url/ 1929 OSCORE: 09 25 1930 Payload: 09 07 01 13 61 f7 0f d2 97 b1 [binary] 1932 [CoAP request -- After server object security processing] 1934 GET coap://server.url/orders 1936 [CoAP response -- Before server object security processing] 1938 2.05 Content 1939 Content-Format: 0 1940 Payload: Exterminate! Exterminate! 1942 [CoAP response -- CoAP Server to Proxy] 1944 2.04 Changed 1945 OSCORE: [empty] 1946 Payload: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] 1948 [HTTP response -- Proxy to HTTP Client] 1950 HTTP/1.1 200 OK 1951 Content-Type: application/oscore 1952 OSCORE: AA 1953 Body: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] 1955 [HTTP response -- After client object security processing] 1957 HTTP/1.1 200 OK 1958 Content-Type: text/plain 1959 Body: Exterminate! Exterminate! 1961 Note that the HTTP Status Code 200 in the next-to-last message is the 1962 mapping of CoAP Code 2.04 (Changed), whereas the HTTP Status Code 200 1963 in the last message is the mapping of the CoAP Code 2.05 (Content), 1964 which was encrypted within the compressed COSE object carried in the 1965 Body of the HTTP response. 1967 11.6. Example: CoAP Client and HTTP Server 1969 This section is giving an example of how a request and a response 1970 between a CoAP client and an HTTP server could look like. The 1971 example is not a test vector but intended as an illustration of how 1972 the message fields are translated in the different steps 1974 [CoAP request -- Before client object security processing] 1976 GET coap://proxy.url/ 1977 Proxy-Uri=http://server.url/orders 1979 [CoAP request -- CoAP Client to Proxy] 1981 POST coap://proxy.url/ 1982 Proxy-Uri=http://server.url/ 1983 OSCORE: 09 25 1984 Payload: 09 07 01 13 61 f7 0f d2 97 b1 [binary] 1986 [HTTP request -- Proxy to HTTP Server] 1988 POST http://server.url/ HTTP/1.1 1989 Content-Type: application/oscore 1990 OSCORE: CSU 1991 Body: 09 07 01 13 61 f7 0f d2 97 b1 [binary] 1993 [HTTP request -- After server object security processing] 1995 GET http://server.url/orders HTTP/1.1 1997 [HTTP response -- Before server object security processing] 1999 HTTP/1.1 200 OK 2000 Content-Type: text/plain 2001 Body: Exterminate! Exterminate! 2003 [HTTP response -- HTTP Server to Proxy] 2005 HTTP/1.1 200 OK 2006 Content-Type: application/oscore 2007 OSCORE: AA 2008 Body: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] 2010 [CoAP response -- Proxy to CoAP Client] 2012 2.04 Changed 2013 OSCORE: [empty] 2014 Payload: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] 2016 [CoAP response -- After client object security processing] 2018 2.05 Content 2019 Content-Format: 0 2020 Payload: Exterminate! Exterminate! 2022 Note that the HTTP Code 2.04 (Changed) in the next-to-last message is 2023 the mapping of HTTP Status Code 200, whereas the CoAP Code 2.05 2024 (Content) in the last message is the value that was encrypted within 2025 the compressed COSE object carried in the Body of the HTTP response. 2027 12. Security Considerations 2029 An overview of the security properties is given in Appendix D. 2031 12.1. End-to-end Protection 2033 In scenarios with intermediary nodes such as proxies or gateways, 2034 transport layer security such as (D)TLS only protects data hop-by- 2035 hop. As a consequence, the intermediary nodes can read and modify 2036 any information. The trust model where all intermediary nodes are 2037 considered trustworthy is problematic, not only from a privacy 2038 perspective, but also from a security perspective, as the 2039 intermediaries are free to delete resources on sensors and falsify 2040 commands to actuators (such as "unlock door", "start fire alarm", 2041 "raise bridge"). Even in the rare cases where all the owners of the 2042 intermediary nodes are fully trusted, attacks and data breaches make 2043 such an architecture brittle. 2045 (D)TLS protects hop-by-hop the entire message. OSCORE protects end- 2046 to-end all information that is not required for proxy operations (see 2047 Section 4). (D)TLS and OSCORE can be combined, thereby enabling end- 2048 to-end security of the message payload, in combination with hop-by- 2049 hop protection of the entire message, during transport between end- 2050 point and intermediary node. In particular when OSCORE is used with 2051 HTTP, the additional TLS protection of HTTP hops is recommended, e.g. 2052 between an HTTP endpoint and a proxy translating between HTTP and 2053 CoAP. 2055 The consequences of unprotected message fields are analyzed in 2056 Appendix D.4. Error messages occurring during CoAP processing are 2057 protected end-to-end. Error messages occurring during OSCORE 2058 processing are not always possible to protect, e.g. if the receiving 2059 endpoint cannot locate the right security context. It may still be 2060 favorable to send an unprotected error message, e.g. to prevent 2061 extensive retransmissions, so unprotected error messages are allowed 2062 as specified. Similar to error messages, signaling messages are not 2063 always possible to protect as they may be intended for an 2064 intermediary. Applications using unprotected error and signaling 2065 messages need to consider the threat that these messages may be 2066 spoofed. 2068 12.2. Security Context Establishment 2070 The use of COSE_Encrypt0 and AEAD to protect messages as specified in 2071 this document requires an established security context. The method 2072 to establish the security context described in Section 3.2 is based 2073 on a common Master Secret and unique Sender IDs. The necessary input 2074 parameters may be pre-established or obtained using a key 2075 establishment protocol augmented with establishment of Sender/ 2076 Recipient ID such as the OSCORE profile of the ACE framework 2077 [I-D.ietf-ace-oscore-profile]. This procedure must ensure that the 2078 requirements of the security context parameters are complied with 2079 Section 3.3 for the intended use and also in error situations. It is 2080 recommended to use a key establishment protocol which provides 2081 forward secrecy whenever possible. Considerations for the deploying 2082 OSCORE with a fixed Master Secret are given in Appendix B. 2084 12.3. Master Secret 2086 OSCORE uses HKDF [RFC5869] and the established input parameters to 2087 derive the security context. The required properties of the security 2088 context parameters are discussed in Section 3.3, in this section we 2089 focus on the Master Secret. HKDF denotes in this specification the 2090 composition of the expand and extract functions as defined in 2091 [RFC5869] and the Master Secret is used as Input Key Material (IKM). 2093 Informally, HKDF takes as source an IKM containing some good amount 2094 of randomness but not necessarily distributed uniformly (or for which 2095 an attacker has some partial knowledge) and derive from it one or 2096 more cryptographically strong secret keys [RFC5869]. 2098 Therefore, the main requirement for the OSCORE Master Secret, in 2099 addition to being secret, is that it is has a good amount of 2100 randomness. The selected key establishment schemes must ensure that 2101 the necessary properties for the Master Secret are fulfilled. For 2102 pre-shared key deployments and key transport solutions such as 2103 [I-D.ietf-ace-oscore-profile], the Master Secret can be generated 2104 offline using a good random number generator. 2106 12.4. Replay Protection 2108 Most AEAD algorithms require a unique nonce for each message, for 2109 which the sender sequence numbers in the COSE message field 'Partial 2110 IV' is used. If the recipient accepts any sequence number larger 2111 than the one previously received, then the problem of sequence number 2112 synchronization is avoided. With reliable transport, it may be 2113 defined that only messages with sequence number which are equal to 2114 previous sequence number + 1 are accepted. The alternatives to 2115 sequence numbers have their issues: very constrained devices may not 2116 be able to support accurate time, or to generate and store large 2117 numbers of random nonces. The requirement to change key at counter 2118 wrap is a complication, but it also forces the user of this 2119 specification to think about implementing key renewal. 2121 12.5. Client Aliveness 2123 A verified OSCORE request enables the server to verify the identity 2124 of the entity who generated the message. However, it does not verify 2125 that the client is currently involved in the communication, since the 2126 message may be a delayed delivery of a previously generated request 2127 which now reaches the server. To verify the aliveness of the client 2128 the server may use the Echo option in the response to a request from 2129 the client (see [I-D.ietf-core-echo-request-tag]). 2131 12.6. Cryptographic Considerations 2133 The maximum sender sequence number is dependent on the AEAD 2134 algorithm. The maximum sender sequence number is 2^40 - 1, or any 2135 algorithm specific lower limit, after which a new security context 2136 must be generated. The mechanism to build the nonce (Section 5.2) 2137 assumes that the nonce is at least 56 bits, and the Partial IV is at 2138 most 40 bits. The mandatory-to-implement AEAD algorithm AES-CCM- 2139 16-64-128 is selected for compatibility with CCM*. 2141 In order to prevent cryptanalysis when the same plaintext is 2142 repeatedly encrypted by many different users with distinct keys, the 2143 nonce is formed by mixing the sequence number with a secret per- 2144 context initialization vector (Common IV) derived along with the keys 2145 (see Section 3.1 of [RFC8152]), and by using a Master Salt in the key 2146 derivation (see [MF00] for an overview). The Master Secret, Sender 2147 Key, Recipient Key, and Common IV must be secret, the rest of the 2148 parameters may be public. The Master Secret must have a good amount 2149 of randomness (see Section 12.3)). 2151 12.7. Message Segmentation 2153 The Inner Block options enable the sender to split large messages 2154 into OSCORE-protected blocks such that the receiving endpoint can 2155 verify blocks before having received the complete message. The Outer 2156 Block options allow for arbitrary proxy fragmentation operations that 2157 cannot be verified by the endpoints, but can by policy be restricted 2158 in size since the Inner Block options allow for secure fragmentation 2159 of very large messages. A maximum message size (above which the 2160 sending endpoint fragments the message and the receiving endpoint 2161 discards the message, if complying to the policy) may be obtained as 2162 part of normal resource discovery. 2164 12.8. Privacy Considerations 2166 Privacy threats executed through intermediary nodes are considerably 2167 reduced by means of OSCORE. End-to-end integrity protection and 2168 encryption of the message payload and all options that are not used 2169 for proxy operations, provide mitigation against attacks on sensor 2170 and actuator communication, which may have a direct impact on the 2171 personal sphere. 2173 The unprotected options (Figure 5) may reveal privacy sensitive 2174 information, see Appendix D.4. CoAP headers sent in plaintext allow, 2175 for example, matching of CON and ACK (CoAP Message Identifier), 2176 matching of request and responses (Token) and traffic analysis. 2177 OSCORE does not provide protection for HTTP header fields which are 2178 not both CoAP-mappable and class E. The HTTP message fields which 2179 are visible to on-path entity are only used for the purpose of 2180 transporting the OSCORE message, whereas the application layer 2181 message is encoded in CoAP and encrypted. 2183 Unprotected error messages reveal information about the security 2184 state in the communication between the endpoints. Unprotected 2185 signaling messages reveal information about the reliable transport 2186 used on a leg of the path. Using the mechanisms described in 2187 Section 7.5 may reveal when a device goes through a reboot. This can 2188 be mitigated by the device storing the precise state of sender 2189 sequence number and replay window on a clean shutdown. 2191 The length of message fields can reveal information about the 2192 message. Applications may use a padding scheme to protect against 2193 traffic analysis. 2195 13. IANA Considerations 2197 Note to RFC Editor: Please replace all occurrences of "[[this 2198 document]]" with the RFC number of this specification. 2200 Note to IANA: Please note all occurrences of "TBDx" in this 2201 specification should be assigned the same number. 2203 13.1. COSE Header Parameters Registry 2205 The 'kid context' parameter is added to the "COSE Header Parameters 2206 Registry": 2208 o Name: kid context 2210 o Label: TBD2 2212 o Value Type: bstr 2214 o Value Registry: 2216 o Description: Identifies the kid context 2218 o Reference: Section 5.1 of this document 2220 Note to IANA: Label assignment in (Integer value between 1 and 255) 2221 is requested. (RFC Editor: Delete this note after IANA assignment) 2223 13.2. CoAP Option Numbers Registry 2225 The OSCORE option is added to the CoAP Option Numbers registry: 2227 +--------+-----------------+-------------------+ 2228 | Number | Name | Reference | 2229 +--------+-----------------+-------------------+ 2230 | TBD1 | OSCORE | [[this document]] | 2231 +--------+-----------------+-------------------+ 2233 13.3. CoAP Signaling Option Numbers Registry 2235 The OSCORE option is added to the CoAP Signaling Option Numbers 2236 registry: 2238 +------------+--------+---------------------+-------------------+ 2239 | Applies to | Number | Name | Reference | 2240 +------------+--------+---------------------+-------------------+ 2241 | 7.xx (any) | TBD1 | OSCORE | [[this document]] | 2242 +------------+--------+---------------------+-------------------+ 2244 13.4. Header Field Registrations 2246 The HTTP OSCORE header field is added to the Message Headers 2247 registry: 2249 +----------------------+----------+----------+-------------------+ 2250 | Header Field Name | Protocol | Status | Reference | 2251 +----------------------+----------+----------+-------------------+ 2252 | OSCORE | http | standard | [[this document]] | 2253 +----------------------+----------+----------+-------------------+ 2255 13.5. Media Type Registrations 2257 This section registers the 'application/oscore' media type in the 2258 "Media Types" registry. These media types are used to indicate that 2259 the content is an OSCORE message. The OSCORE body cannot be 2260 understood without the OSCORE header field value and the security 2261 context. 2263 Type name: application 2265 Subtype name: oscore 2267 Required parameters: N/A 2269 Optional parameters: N/A 2271 Encoding considerations: binary 2273 Security considerations: See the Security Considerations section 2274 of [[This document]]. 2276 Interoperability considerations: N/A 2278 Published specification: [[This document]] 2280 Applications that use this media type: IoT applications sending 2281 security content over HTTP(S) transports. 2283 Fragment identifier considerations: N/A 2285 Additional information: 2287 * Deprecated alias names for this type: N/A 2289 * Magic number(s): N/A 2291 * File extension(s): N/A 2293 * Macintosh file type code(s): N/A 2295 Person & email address to contact for further information: 2296 iesg@ietf.org 2298 Intended usage: COMMON 2300 Restrictions on usage: N/A 2302 Author: Goeran Selander, goran.selander@ericsson.com 2304 Change Controller: IESG 2306 Provisional registration? No 2308 13.6. CoAP Content-Formats Registry 2310 Note to IANA: ID assignment in the 10000-64999 range is requested. 2311 (RFC Editor: Delete this note after IANA assignment) 2313 This section registers the media type 'application/oscore' media type 2314 in the "CoAP Content-Format" registry. This Content-Format for the 2315 OSCORE payload is defined for potential future use cases and SHALL 2316 NOT be used in the OSCORE message. The OSCORE payload cannot be 2317 understood without the OSCORE option value and the security context. 2319 +----------------------+----------+----------+-------------------+ 2320 | Media Type | Encoding | ID | Reference | 2321 +----------------------+----------+----------+-------------------+ 2322 | application/oscore | | TBD3 | [[this document]] | 2323 +----------------------+----------+----------+-------------------+ 2325 14. References 2327 14.1. Normative References 2329 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2330 Requirement Levels", BCP 14, RFC 2119, 2331 DOI 10.17487/RFC2119, March 1997, 2332 . 2334 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 2335 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 2336 . 2338 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 2339 Specifications: ABNF", STD 68, RFC 5234, 2340 DOI 10.17487/RFC5234, January 2008, 2341 . 2343 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2344 (TLS) Protocol Version 1.2", RFC 5246, 2345 DOI 10.17487/RFC5246, August 2008, 2346 . 2348 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 2349 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 2350 January 2012, . 2352 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 2353 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 2354 October 2013, . 2356 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 2357 Protocol (HTTP/1.1): Message Syntax and Routing", 2358 RFC 7230, DOI 10.17487/RFC7230, June 2014, 2359 . 2361 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 2362 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 2363 DOI 10.17487/RFC7231, June 2014, 2364 . 2366 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 2367 Application Protocol (CoAP)", RFC 7252, 2368 DOI 10.17487/RFC7252, June 2014, 2369 . 2371 [RFC7641] Hartke, K., "Observing Resources in the Constrained 2372 Application Protocol (CoAP)", RFC 7641, 2373 DOI 10.17487/RFC7641, September 2015, 2374 . 2376 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 2377 the Constrained Application Protocol (CoAP)", RFC 7959, 2378 DOI 10.17487/RFC7959, August 2016, 2379 . 2381 [RFC8075] Castellani, A., Loreto, S., Rahman, A., Fossati, T., and 2382 E. Dijk, "Guidelines for Mapping Implementations: HTTP to 2383 the Constrained Application Protocol (CoAP)", RFC 8075, 2384 DOI 10.17487/RFC8075, February 2017, 2385 . 2387 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 2388 FETCH Methods for the Constrained Application Protocol 2389 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 2390 . 2392 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 2393 RFC 8152, DOI 10.17487/RFC8152, July 2017, 2394 . 2396 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2397 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2398 May 2017, . 2400 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 2401 DOI 10.17487/RFC8288, October 2017, 2402 . 2404 [RFC8323] Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 2405 Silverajan, B., and B. Raymor, Ed., "CoAP (Constrained 2406 Application Protocol) over TCP, TLS, and WebSockets", 2407 RFC 8323, DOI 10.17487/RFC8323, February 2018, 2408 . 2410 14.2. Informative References 2412 [I-D.bormann-6lo-coap-802-15-ie] 2413 Bormann, C., "Constrained Application Protocol (CoAP) over 2414 IEEE 802.15.4 Information Element for IETF", draft- 2415 bormann-6lo-coap-802-15-ie-00 (work in progress), April 2416 2016. 2418 [I-D.hartke-core-e2e-security-reqs] 2419 Selander, G., Palombini, F., and K. Hartke, "Requirements 2420 for CoAP End-To-End Security", draft-hartke-core-e2e- 2421 security-reqs-03 (work in progress), July 2017. 2423 [I-D.ietf-6tisch-minimal-security] 2424 Vucinic, M., Simon, J., Pister, K., and M. Richardson, 2425 "Minimal Security Framework for 6TiSCH", draft-ietf- 2426 6tisch-minimal-security-05 (work in progress), March 2018. 2428 [I-D.ietf-ace-oauth-authz] 2429 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 2430 H. Tschofenig, "Authentication and Authorization for 2431 Constrained Environments (ACE) using the OAuth 2.0 2432 Framework (ACE-OAuth)", draft-ietf-ace-oauth-authz-11 2433 (work in progress), March 2018. 2435 [I-D.ietf-ace-oscore-profile] 2436 Seitz, L., Palombini, F., Gunnarsson, M., and G. Selander, 2437 "OSCORE profile of the Authentication and Authorization 2438 for Constrained Environments Framework", draft-ietf-ace- 2439 oscore-profile-01 (work in progress), March 2018. 2441 [I-D.ietf-cbor-cddl] 2442 Birkholz, H., Vigano, C., and C. Bormann, "Concise data 2443 definition language (CDDL): a notational convention to 2444 express CBOR data structures", draft-ietf-cbor-cddl-02 2445 (work in progress), February 2018. 2447 [I-D.ietf-core-echo-request-tag] 2448 Amsuess, C., Mattsson, J., and G. Selander, "Echo and 2449 Request-Tag", draft-ietf-core-echo-request-tag-01 (work in 2450 progress), March 2018. 2452 [I-D.ietf-core-oscore-groupcomm] 2453 Tiloca, M., Selander, G., Palombini, F., and J. Park, 2454 "Secure group communication for CoAP", draft-ietf-core- 2455 oscore-groupcomm-01 (work in progress), March 2018. 2457 [I-D.mattsson-core-coap-actuators] 2458 Mattsson, J., Fornehed, J., Selander, G., Palombini, F., 2459 and C. Amsuess, "Controlling Actuators with CoAP", draft- 2460 mattsson-core-coap-actuators-05 (work in progress), March 2461 2018. 2463 [MF00] McGrew, D. and S. Fluhrer, "Attacks on Encryption of 2464 Redundant Plaintext and Implications on Internet 2465 Security", the Proceedings of the Seventh Annual Workshop 2466 on Selected Areas in Cryptography (SAC 2000), Springer- 2467 Verlag. , 2000. 2469 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2470 Resource Identifier (URI): Generic Syntax", STD 66, 2471 RFC 3986, DOI 10.17487/RFC3986, January 2005, 2472 . 2474 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 2475 Encryption", RFC 5116, DOI 10.17487/RFC5116, January 2008, 2476 . 2478 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 2479 Key Derivation Function (HKDF)", RFC 5869, 2480 DOI 10.17487/RFC5869, May 2010, 2481 . 2483 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 2484 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 2485 . 2487 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 2488 Constrained-Node Networks", RFC 7228, 2489 DOI 10.17487/RFC7228, May 2014, 2490 . 2492 [RFC7390] Rahman, A., Ed. and E. Dijk, Ed., "Group Communication for 2493 the Constrained Application Protocol (CoAP)", RFC 7390, 2494 DOI 10.17487/RFC7390, October 2014, 2495 . 2497 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 2498 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 2499 2015, . 2501 [RFC7967] Bhattacharyya, A., Bandyopadhyay, S., Pal, A., and T. 2502 Bose, "Constrained Application Protocol (CoAP) Option for 2503 No Server Response", RFC 7967, DOI 10.17487/RFC7967, 2504 August 2016, . 2506 Appendix A. Scenario Examples 2508 This section gives examples of OSCORE, targeting scenarios in 2509 Section 2.2.1.1 of [I-D.hartke-core-e2e-security-reqs]. The message 2510 exchanges are made, based on the assumption that there is a security 2511 context established between client and server. For simplicity, these 2512 examples only indicate the content of the messages without going into 2513 detail of the (compressed) COSE message format. 2515 A.1. Secure Access to Sensor 2517 This example illustrates a client requesting the alarm status from a 2518 server. 2520 Client Proxy Server 2521 | | | 2522 +------>| | Code: 0.02 (POST) 2523 | POST | | Token: 0x8c 2524 | | | OSCORE: [kid:5f,Partial IV:42] 2525 | | | Payload: {Code:0.01, 2526 | | | Uri-Path:"alarm_status"} 2527 | | | 2528 | +------>| Code: 0.02 (POST) 2529 | | POST | Token: 0x7b 2530 | | | OSCORE: [kid:5f,Partial IV:42] 2531 | | | Payload: {Code:0.01, 2532 | | | Uri-Path:"alarm_status"} 2533 | | | 2534 | |<------+ Code: 2.04 (Changed) 2535 | | 2.04 | Token: 0x7b 2536 | | | OSCORE: - 2537 | | | Payload: {Code:2.05, "OFF"} 2538 | | | 2539 |<------+ | Code: 2.04 (Changed) 2540 | 2.04 | | Token: 0x8c 2541 | | | OSCORE: - 2542 | | | Payload: {Code:2.05, "OFF"} 2543 | | | 2545 Figure 12: Secure Access to Sensor. Square brackets [ ... ] indicate 2546 content of compressed COSE object. Curly brackets { ... } indicate 2547 encrypted data. 2549 The request/response Codes are encrypted by OSCORE and only dummy 2550 Codes (POST/Changed) are visible in the header of the OSCORE message. 2551 The option Uri-Path ("alarm_status") and payload ("OFF") are 2552 encrypted. 2554 The COSE header of the request contains an identifier (5f), 2555 indicating which security context was used to protect the message and 2556 a Partial IV (42). 2558 The server verifies the request as specified in Section 8.2. The 2559 client verifies the response as specified in Section 8.4. 2561 A.2. Secure Subscribe to Sensor 2563 This example illustrates a client requesting subscription to a blood 2564 sugar measurement resource (GET /glucose), first receiving the value 2565 220 mg/dl and then a second value 180 mg/dl. 2567 Client Proxy Server 2568 | | | 2569 +------>| | Code: 0.05 (FETCH) 2570 | FETCH | | Token: 0x83 2571 | | | Observe: 0 2572 | | | OSCORE: [kid:ca,Partial IV:15] 2573 | | | Payload: {Code:0.01, 2574 | | | Uri-Path:"glucose"} 2575 | | | 2576 | +------>| Code: 0.05 (FETCH) 2577 | | FETCH | Token: 0xbe 2578 | | | Observe: 0 2579 | | | OSCORE: [kid:ca,Partial IV:15] 2580 | | | Payload: {Code:0.01, 2581 | | | Uri-Path:"glucose"} 2582 | | | 2583 | |<------+ Code: 2.05 (Content) 2584 | | 2.05 | Token: 0xbe 2585 | | | Observe: 7 2586 | | | OSCORE: [Partial IV:32] 2587 | | | Payload: {Code:2.05, 2588 | | | Content-Format:0, "220"} 2589 | | | 2590 |<------+ | Code: 2.05 (Content) 2591 | 2.05 | | Token: 0x83 2592 | | | Observe: 7 2593 | | | OSCORE: [Partial IV:32] 2594 | | | Payload: {Code:2.05, 2595 | | | Content-Format:0, "220"} 2596 ... ... ... 2598 | | | 2599 | |<------+ Code: 2.05 (Content) 2600 | | 2.05 | Token: 0xbe 2601 | | | Observe: 8 2602 | | | OSCORE: [Partial IV:36] 2603 | | | Payload: {Code:2.05, 2604 | | | Content-Format:0, "180"} 2605 | | | 2606 |<------+ | Code: 2.05 (Content) 2607 | 2.05 | | Token: 0x83 2608 | | | Observe: 8 2609 | | | OSCORE: [Partial IV:36] 2610 | | | Payload: {Code:2.05, 2611 | | | Content-Format:0, "180"} 2612 | | | 2614 Figure 13: Secure Subscribe to Sensor. Square brackets [ ... ] 2615 indicate content of compressed COSE object header. Curly brackets { 2616 ... } indicate encrypted data. 2618 The dummy Codes (FETCH/Content) are visible in the header of the 2619 OSCORE message to allow intermediary processing of Observe. The 2620 options Content-Format (0) and the payload ("220" and "180"), are 2621 encrypted. 2623 The COSE header of the request contains an identifier (ca), 2624 indicating the security context used to protect the message and a 2625 Partial IV (15). The COSE headers of the responses contains Partial 2626 IVs (32 and 36). 2628 The server verifies that the Partial IV has not been received before. 2629 The client verifies that the responses are bound to the request and 2630 that the Partial IVs are greater than any Partial IV previously 2631 received in a response bound to the request. 2633 Appendix B. Deployment Examples 2635 Two examples complying with the requirements on the security context 2636 parameters (Section 3.3) are given in this section. 2638 B.1. Master Secret Used Once 2640 For settings where the Master Secret is only used during deployment, 2641 the uniqueness of the AEAD nonce may be assured by persistent storage 2642 of the security context as described in this specification (see 2643 Section 7.5). For many IoT deployments, a 128 bit uniformly random 2644 Master Key is sufficient for encrypting all data exchanged with the 2645 IoT device throughout its lifetime. 2647 B.2. Master Secret Used Multiple Times 2649 One Master Secret can be used to derive multiple security contexts if 2650 unique Master Salts can be guaranteed. This may be useful e.g. in 2651 case of recommissioning with reused Master Secret. In order to 2652 prevent reuse of AEAD nonce and key, which would compromise the 2653 security, the Master Salt must never be used twice, even if the 2654 device is reset, recommissioned or in error cases. Examples of 2655 failures include derivation of pseudorandom master salt from a static 2656 seed, or a deterministic seeding procedure with inputs that are 2657 repeated or can be replayed. Techniques for persistent storage of 2658 security state may be used also in this case, to ensure uniqueness of 2659 Master Salt. 2661 Assuming the Master Salts are indeed unique (or stochastically 2662 unique) we give an example of a procedure which may be implemented in 2663 client and server to establish the OSCORE security context based on 2664 pre-established input parameters (see Section 3.2) except for the 2665 Master Salt, which is transported in kid context parameter (see 2666 Section 5.1) of the request. 2668 1. In order to establish a security context with a server for the 2669 first time, or a new security context replacing an old security 2670 context, the client generates a (pseudo-)random uniformly 2671 distributed 64-bit Master Salt and derives the security context 2672 as specified in Section 3.2. The client protects a request with 2673 the new Sender Context and sends the message with kid context set 2674 to the Master Salt. 2676 2. The server, receiving an OSCORE request with a non-empty kid 2677 context derives the new security context using the received kid 2678 context as Master Salt. The server processes the request as 2679 specified in this document using the new Recipient Context. If 2680 the processing of the request completes without error, the server 2681 responds with an Echo option as specified in 2682 [I-D.ietf-core-echo-request-tag]. The response is protected with 2683 the new Sender Context. 2685 3. The client, receiving a response with an Echo option to a request 2686 which used a new security context, verifies the response using 2687 the new Recipient Context, and if valid repeats the request with 2688 the Echo option (see [I-D.ietf-core-echo-request-tag]) using the 2689 new Sender Context. Subsequent message exchanges (unless 2690 superseded) are processed using the new security context without 2691 including the Master Salt in the kid context. 2693 4. The server, receiving a request with a kid context and a valid 2694 Echo option (see [I-D.ietf-core-echo-request-tag]), repeats the 2695 processing described in step 2. If it completes without error, 2696 then the new security context is established, and the request is 2697 valid. If the server already had an old security context with 2698 this client that is now replaced by the new security context. 2700 If the server receives a request without kid context from a client 2701 with which no security context is established, then the server 2702 responds with a 4.01 Unauthorized error message with diagnostic 2703 payload containing the string "Security context not found". This 2704 could be the result of the server having lost its security context or 2705 that a new security context has not been successfully established, 2706 which may be a trigger for the client to run this procedure. 2708 Appendix C. Test Vectors 2710 This appendix includes the test vectors for different examples of 2711 CoAP messages using OSCORE. 2713 C.1. Test Vector 1: Key Derivation with Master Salt 2715 Given a set of inputs, OSCORE defines how to set up the Security 2716 Context in both the client and the server. The default values are 2717 used for AEAD Algorithm and KDF. 2719 C.1.1. Client 2721 Inputs: 2723 o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes) 2725 o Master Salt: 0x9e7ca92223786340 (8 bytes) 2727 o Sender ID: 0x (0 byte) 2729 o Recipient ID: 0x01 (1 byte) 2731 From the previous parameters, 2733 o info (for Sender Key): 0x84400A634b657910 (8 bytes) 2735 o info (for Recipient Key): 0x8441010A634b657910 (9 bytes) 2737 o info (for Common IV): 0x84400a6249560d (7 bytes) 2739 Outputs: 2741 o Sender Key: 0x7230aab3b549d94c9224aacc744e93ab (16 bytes) 2742 o Recipient Key: 0xe534a26a64aa3982e988e31f1e401e65 (16 bytes) 2744 o Common IV: 0x01727733ab49ead385b18f7d91 (13 bytes) 2746 C.1.2. Server 2748 Inputs: 2750 o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes) 2752 o Master Salt: 0x9e7ca92223786340 (64 bytes) 2754 o Sender ID: 0x01 (1 byte) 2756 o Recipient ID: 0x (0 byte) 2758 From the previous parameters, 2760 o info (for Sender Key): 0x8441010A634b657910 (9 bytes) 2762 o info (for Recipient Key): 0x84400A634b657910 (8 bytes) 2764 o info (for Common IV): 0x84400a6249560d (7 bytes) 2766 Outputs: 2768 o Sender Key: 0xe534a26a64aa3982e988e31f1e401e65 (16 bytes) 2770 o Recipient Key: 0x7230aab3b549d94c9224aacc744e93ab (16 bytes) 2772 o Common IV: 0x01727733ab49ead385b18f7d91 (13 bytes) 2774 C.2. Test Vector 2: Key Derivation without Master Salt 2776 Given a set of inputs, OSCORE defines how to set up the Security 2777 Context in both the client and the server. The default values are 2778 used for AEAD Algorithm, KDF, and Master Salt. 2780 C.2.1. Client 2782 Inputs: 2784 o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes) 2786 o Sender ID: 0x00 (1 byte) 2788 o Recipient ID: 0x01 (1 byte) 2789 From the previous parameters, 2791 o info (for Sender Key): 0x8441000A634b657910 (9 bytes) 2793 o info (for Recipient Key): 0x8441010A634b657910 (9 bytes) 2795 o info (for Common IV): 0x84400a6249560d (7 bytes) 2797 Outputs: 2799 o Sender Key: 0xf8f3b887436285ed5a66f6026ac2cdc1 (16 bytes) 2801 o Recipient Key: 0xd904cb101f7341c3f4c56c300fa69941 (16 bytes) 2803 o Common IV: 0xd1a1949aa253278f34c528d2cc (13 bytes) 2805 C.2.2. Server 2807 Inputs: 2809 o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes) 2811 o Sender ID: 0x01 (1 byte) 2813 o Recipient ID: 0x00 (1 byte) 2815 From the previous parameters, 2817 o info (for Sender Key): 0x8441010A634b657910 (9 bytes) 2819 o info (for Recipient Key): 0x8441000A634b657910 (9 bytes) 2821 o info (for Common IV): 0x84400a6249560d (7 bytes) 2823 Outputs: 2825 o Sender Key: 0xd904cb101f7341c3f4c56c300fa69941 (16 bytes) 2827 o Recipient Key: 0xf8f3b887436285ed5a66f6026ac2cdc1 (16 bytes) 2829 o Common IV: 0xd1a1949aa253278f34c528d2cc (13 bytes) 2831 C.3. Test Vector 3: OSCORE Request, Client 2833 This section contains a test vector for an OSCORE protected CoAP GET 2834 request using the security context derived in Appendix C.1. The 2835 unprotected request only contains the Uri-Path option. 2837 Unprotected CoAP request: 2838 0x440149c60000f2a7396c6f63616c686f737483747631 (22 bytes) 2840 Common Context: 2842 o AEAD Algorithm: 10 (AES-CCM-16-64-128) 2844 o Key Derivation Function: HKDF SHA-256 2846 o Common IV: 0xd1a1949aa253278f34c528d2cc (13 bytes) 2848 Sender Context: 2850 o Sender ID: 0x00 (1 byte) 2852 o Sender Key: 0xf8f3b887436285ed5a66f6026ac2cdc1 (16 bytes) 2854 o Sender Sequence Number: 20 2856 The following COSE and cryptographic parameters are derived: 2858 o Partial IV: 0x14 (1 byte) 2860 o kid: 0x00 (1 byte) 2862 o external_aad: 0x8501810a4100411440 (9 bytes) 2864 o AAD: 0x8368456e63727970743040498501810a4100411440 (21 bytes) 2866 o plaintext: 0x01b3747631 (5 bytes) 2868 o encryption key: 0xf8f3b887436285ed5a66f6026ac2cdc1 (16 bytes) 2870 o nonce: 0xd0a1949aa253278f34c528d2d8 (13 bytes) 2872 From the previous parameter, the following is derived: 2874 o OSCORE option value: 0x091400 (3 bytes) 2876 o ciphertext: 0x55b3710d47c611cd3924838a44 (13 bytes) 2878 From there: 2880 o Protected CoAP request (OSCORE message): 0x44026dd30000acc5396c6f6 2881 3616c686f7374d305091400ff55b3710d47c611cd3924838a44 (37 bytes) 2883 C.4. Test Vector 4: OSCORE Request, Client 2885 This section contains a test vector for an OSCORE protected CoAP GET 2886 request using the security context derived in Appendix C.2. The 2887 unprotected request only contains the Uri-Path option. 2889 Unprotected CoAP request: 2890 0x440149c60000f2a7396c6f63616c686f737483747631 (22 bytes) 2892 Common Context: 2894 o AEAD Algorithm: 10 (AES-CCM-16-64-128) 2896 o Key Derivation Function: HKDF SHA-256 2898 o Common IV: 0x01727733ab49ead385b18f7d91 (13 bytes) 2900 Sender Context: 2902 o Sender ID: 0x (0 bytes) 2904 o Sender Key: 0x7230aab3b549d94c9224aacc744e93ab (16 bytes) 2906 o Sender Sequence Number: 20 2908 The following COSE and cryptographic parameters are derived: 2910 o Partial IV: 0x14 (1 byte) 2912 o kid: 0x (0 byte) 2914 o external_aad: 0x8501810a40411440 (8 bytes) 2916 o AAD: 0x8368456e63727970743040488501810a40411440 (20 bytes) 2918 o plaintext: 0x01b3747631 (5 bytes) 2920 o encryption key: 0x7230aab3b549d94c9224aacc744e93ab (16 bytes) 2922 o nonce: 0x01727733ab49ead385b18f7d85 (13 bytes) 2924 From the previous parameter, the following is derived: 2926 o OSCORE option value: 0x0914 (2 bytes) 2928 o ciphertext: 0x6be9214aad448260ff1be1f594 (13 bytes) 2930 From there: 2932 o Protected CoAP request (OSCORE message): 0x44023bfc000066ef396c6f6 2933 3616c686f7374d2050914ff6be9214aad448260ff1be1f594 (36 bytes) 2935 C.5. Test Vector 5: OSCORE Response, Server 2937 This section contains a test vector for an OSCORE protected 2.05 2938 Content response to the request in Appendix C.3. The unprotected 2939 response has payload "Hello World!" and no options. The protected 2940 response does not contain a kid nor a Partial IV. Note that some 2941 parameters are derived from the request. 2943 Unprotected CoAP response: 2944 0x644549c60000f2a7ff48656c6c6f20576f726c6421 (21 bytes) 2946 Common Context: 2948 o AEAD Algorithm: 10 (AES-CCM-16-64-128) 2950 o Key Derivation Function: HKDF SHA-256 2952 o Common IV: 0xd1a1949aa253278f34c528d2cc (13 bytes) 2954 Sender Context: 2956 o Sender ID: 0x01 (1 byte) 2958 o Sender Key: 0xd904cb101f7341c3f4c56c300fa69941 (16 bytes) 2960 o Sender Sequence Number: 0 2962 The following COSE and cryptographic parameters are derived: 2964 o external_aad: 0x8501810a4100411440 (9 bytes) 2966 o AAD: 0x8368456e63727970743040498501810a4100411440 (21 bytes) 2968 o plaintext: 0x45ff48656c6c6f20576f726c6421 (14 bytes) 2970 o encryption key: 0xd904cb101f7341c3f4c56c300fa69941 (16 bytes) 2972 o nonce: 0xd0a1949aa253278f34c528d2d8 (13 bytes) 2974 From the previous parameter, the following is derived: 2976 o OSCORE option value: 0x (0 bytes) 2978 o ciphertext: 0xe4e8c28c41c8f31ca56eec24f6c71d94eacbcdffdc6d (22 2979 bytes) 2981 From there: 2983 o Protected CoAP response (OSCORE message): 0x64446dd30000acc5d008ff 2984 e4e8c28c41c8f31ca56eec24f6c71d94eacbcdffdc6d (33 bytes) 2986 C.6. Test Vector 6: OSCORE Response with Partial IV, Server 2988 This section contains a test vector for an OSCORE protected 2.05 2989 Content response to the request in Appendix C.3. The unprotected 2990 response has payload "Hello World!" and no options. The protected 2991 response does not contain a kid, but contains a Partial IV. Note 2992 that some parameters are derived from the request. 2994 Unprotected CoAP response: 2995 0x644549c60000f2a7ff48656c6c6f20576f726c6421 (21 bytes) 2997 Common Context: 2999 o AEAD Algorithm: 10 (AES-CCM-16-64-128) 3001 o Key Derivation Function: HKDF SHA-256 3003 o Common IV: 0xd1a1949aa253278f34c528d2cc (13 bytes) 3005 Sender Context: 3007 o Sender ID: 0x01 (1 byte) 3009 o Sender Key: 0xd904cb101f7341c3f4c56c300fa69941 (16 bytes) 3011 o Sender Sequence Number: 0 3013 The following COSE and cryptographic parameters are derived: 3015 o Partial IV: 0x00 (1 byte) 3017 o external_aad: 0x8501810a4100411440 (9 bytes) 3019 o AAD: 0x8368456e63727970743040498501810a4100411440 (21 bytes) 3021 o plaintext: 0x45ff48656c6c6f20576f726c6421 (14 bytes) 3023 o encryption key: 0xd904cb101f7341c3f4c56c300fa69941 (16 bytes) 3025 o nonce: 0xd0a1949aa253278e34c528d2cc (13 bytes) 3027 From the previous parameter, the following is derived: 3029 o OSCORE option value: 0x0100 (2 bytes) 3031 o ciphertext: 0xa7e3ca27f221f453c0ba68c350bf652ea096b328a1bf (22 3032 bytes) 3034 From there: 3036 o Protected CoAP response (OSCORE message): 0x64442b130000b29ed20801 3037 00ffa7e3ca27f221f453c0ba68c350bf652ea096b328a1bf (35 bytes) 3039 Appendix D. Overview of Security Properties 3041 D.1. Supporting Proxy Operations 3043 CoAP is designed to work with intermediaries reading and/or changing 3044 CoAP message fields and performing supporting operations in 3045 constrained environments, e.g. forwarding and cross-protocol 3046 translations. 3048 Securing CoAP on transport layer protects the entire message between 3049 the endpoints in which case CoAP proxy operations are not possible. 3050 In order to enable proxy operations, security on transport layer 3051 needs to be terminated at the proxy in which case the CoAP message in 3052 its entirety is unprotected in the proxy. 3054 Requirements for CoAP end-to-end security are specified in 3055 [I-D.hartke-core-e2e-security-reqs]. The client and server are 3056 assumed to be honest, but proxies and gateways are only trusted to 3057 perform their intended operations. Forwarding is specified in 3058 Section 2.2.1 of [I-D.hartke-core-e2e-security-reqs]. HTTP-CoAP 3059 translation is specified in [RFC8075]. Intermediaries translating 3060 between different transport layers are intended to perform just that. 3062 By working at the CoAP layer, OSCORE enables different CoAP message 3063 fields to be protected differently, which allows message fields 3064 required for proxy operations to be available to the proxy while 3065 message fields intended for the other endpoint remain protected. In 3066 the remainder of this section we analyze how OSCORE protects the 3067 protected message fields and the consequences of message fields 3068 intended for proxy operation being unprotected. 3070 D.2. Protected Message Fields 3072 Protected message fields are included in the Plaintext (Section 5.3) 3073 and the Additional Authenticated Data (Section 5.4) of the 3074 COSE_Encrypt0 object using an AEAD algorithm. 3076 OSCORE depends on a pre-established random Master Secret 3077 (Section 12.3) which can be used to derive keys, and a construction 3078 for making (key, nonce) pairs unique (Appendix D.3). Assuming this 3079 is true, and the keys are used for no more data than indicated in 3080 Section 7.2, OSCORE should provide the following guarantees: 3082 o Confidentiality: An attacker should not be able to determine the 3083 plaintext contents of a given OSCORE message or determine that 3084 different plaintexts are related (Section 5.3). 3086 o Integrity: An attacker should not be able to craft a new OSCORE 3087 message with protected message fields different from an existing 3088 OSCORE message which will be accepted by the receiver. 3090 o Request-response binding: An attacker should not be able to make a 3091 client match a response to the wrong request. 3093 o Non-replayability: An attacker should not be able to cause the 3094 receiver to accept a message which it has already accepted. 3096 In the above, the attacker is anyone except the endpoints, e.g. a 3097 compromised intermediary. Informally, OSCORE provides these 3098 properties by AEAD-protecting the plaintext with a strong key and 3099 uniqueness of (key, nonce) pairs. AEAD encryption [RFC5116] provides 3100 confidentiality and integrity for the data. Response-request binding 3101 is provided by including the kid and Partial IV of the request in the 3102 AAD of the response. Non-replayability of requests and notifications 3103 is provided by using unique (key, nonce) pairs and a replay 3104 protection mechanism (application dependent, see Section 7.4). 3106 OSCORE is susceptible to a variety of traffic analysis attacks based 3107 on observing the length and timing of encrypted packets. OSCORE does 3108 not provide any specific defenses against this form of attack but the 3109 application may use a padding mechanism to prevent an attacker from 3110 directly determine the length of the padding. However, information 3111 about padding may still be revealed by side-channel attacks observing 3112 differences in timing. 3114 D.3. Uniqueness of (key, nonce) 3116 In this section we show that (key, nonce) pairs are unique as long as 3117 the requirements Section 3.3 and Section 7.2 are followed. 3119 Fix a security context and an endpoint, called the encrypting 3120 endpoint. Endpoints may alternate between client and server roles, 3121 but each endpoint encrypts with the Sender Key of its Sender Context. 3122 Sender Keys are (stochastically) unique since they are derived with 3123 HKDF from unique Sender IDs, so messages encrypted by different 3124 endpoints use different keys. It remains to prove that the nonces 3125 used by the fixed endpoint are unique. 3127 Since the Common IV is fixed, the nonces are determined by a Partial 3128 IV (PIV) and the Sender ID of the endpoint generating that Partial IV 3129 (ID_PIV). The nonce construction (Section 5.2) with the size of the 3130 ID_PIV (S) creates unique nonces for different (ID_PIV, PIV) pairs. 3132 For requests and responses with Partial IV (e.g. Observe 3133 notifications): 3135 o ID_PIV = Sender ID of the encrypting endpoint 3137 o PIV = current Partial IV of the encrypting endpoint 3139 Since the encrypting endpoint steps the Partial IV for each use, the 3140 nonces used are all unique as long as the number of encrypted 3141 messages is kept within the required range (Section 7.2). 3143 For responses without Partial IV (i.e. single response to a request): 3145 o ID_PIV = Sender ID of the endpoint generating the request 3147 o PIV = Partial IV of the request 3149 Since the Sender IDs are unique, ID_PIV is different from the Sender 3150 ID of the encrypting endpoint. Therefore, the nonce is different 3151 compared to nonces where the encrypting endpoint generated the 3152 Partial IV. Since the Partial IV of the request is verified for 3153 replay (Section 7.4) associated to this Recipient Context, PIV is 3154 unique for this ID_PIV. 3156 The argumentation also holds for group communication as specified in 3157 [RFC7390] (see [I-D.ietf-core-oscore-groupcomm]). 3159 D.4. Unprotected Message Fields 3161 This section lists and discusses issues with unprotected message 3162 fields. 3164 D.4.1. CoAP Code 3166 The CoAP Code of an OSCORE message is POST or FETCH for requests and 3167 with corresponding response codes. Since the use of Observe is 3168 indicated with the Outer Observe option, no additional information is 3169 revealed by having a special codes for Observe messages. A change of 3170 code does not affect the method of the end-to-end message but may be 3171 a denial service attack caused by error in the OSCORE processing. 3172 Other aspects of Observe are discussed in Appendix D.4.3. 3174 D.4.2. CoAP Header Fields 3176 o Version. The CoAP version [RFC7252] is not expected to be 3177 sensitive to disclose. Currently there is only one CoAP version 3178 defined. A change of this parameter is potentially a denial of 3179 service attack. Future versions of CoAP need to analyze attacks 3180 to OSCORE protected messages due to an adversary changing the CoAP 3181 version. 3183 o Token/Token Length. The Token field is a client-local identifier 3184 for differentiating between concurrent requests [RFC7252]. An 3185 eavesdropper reading the token can match requests to responses 3186 which can be used in traffic analysis. CoAP proxies are allowed 3187 to change Token and Token Length between UDP hops. However, 3188 modifications of Token and Token Length during a UDP hop may 3189 become a denial of service attack, since it may prevent the client 3190 to identify to which request the response belongs or to find the 3191 correct information to verify integrity of the response. 3193 o Type/Message ID. The Type/Message ID fields [RFC7252] reveal 3194 information about the UDP transport binding, e.g. an eavesdropper 3195 reading the Type or Message ID gain information about how UDP 3196 messages are related to each other. CoAP proxies are allowed to 3197 change Type and Message ID. These message fields are not present 3198 in CoAP over TCP, and does not impact the request/response 3199 message. A change of these fields in a UDP hop is a denial of 3200 service attack similar to changing UDP header fields. 3202 o Length. This field contain the length of the message [RFC8323] 3203 which may be used for traffic analysis. These message fields are 3204 not present in CoAP over UDP, and does not impact the request/ 3205 response message. A change of Length is a denial of service 3206 attack similar to changing TCP header fields. 3208 D.4.3. CoAP Options 3210 o Max-Age. The Outer Max-Age is set to zero to avoid unnecessary 3211 caching of OSCORE error responses. Changing this value thus may 3212 cause unnecessary caching. No additional information is carried 3213 with this option. 3215 o Proxy-Uri/Proxy-Scheme/Uri-Host/Uri-Port. With OSCORE, the Proxy- 3216 Uri option does not contain the Uri-Path/Uri-Query parts of the 3217 URI. Proxy-Uri/Proxy-Scheme/Uri-Host/Uri-Port cannot be integrity 3218 protected since they are allowed to be changed by a forward proxy. 3220 Depending on content, the Uri-Host may either reveal information 3221 equivalent to that of the IP address or more privacy-sensitive 3222 information, which is discouraged in Section 4.1.3.2. 3224 o Observe. The Outer Observe option is intended for an OSCORE- 3225 unaware proxy to support forwarding of Observe messages. Removing 3226 this option in the request turns the notification request into a 3227 normal request, which is allowed for a proxy and server and 3228 understood by the client but changes the performed operation from 3229 a request for notifications to a plain request, but the client 3230 cannot tell what party removed the option. 3232 Removing this option in the response may lead to notifications not 3233 being forwarded or cause a denial of service. The Outer option value 3234 indicates a relative order of notifications as read and written by 3235 the proxy and a change of that may affect proxy operations and 3236 potentially lead to denial of service. Since OSCORE provides 3237 absolute ordering of notifications it is not possible for an 3238 intermediary to spoof reordering (see Section 4.1.3.4). The size and 3239 distributions of notifications over time may reveal information about 3240 the content or nature of the notifications. 3242 o Block1/Block2/Size1/Size2. The Outer Block options enables 3243 fragmentation of OSCORE messages in addition to segmentation 3244 performed by the Inner Block options. The presence of these 3245 options indicates a large message being sent and the message size 3246 can be estimated and used for traffic analysis. Manipulating 3247 these options is a potential denial of service attack, e.g. 3248 injection of alleged Block fragments. The specification of 3249 MAX_UNFRAGMENTED_SIZE (Section 4.1.3.3.2), at which the messages 3250 will be dropped, is intended as one measure to mitigate this kind 3251 of attack. 3253 o No-Response. The Outer No-Response option is used to support 3254 proxy functionality, specifically to avoid error transmissions 3255 from proxies to clients, and to avoid bandwidth reduction to 3256 servers by proxies applying congestion control when not receiving 3257 responses. Modifying or introducing this option is a potential 3258 denial of service attack against the proxy operations, but since 3259 the option has an Inner value its use can be securely agreed 3260 between the endpoints. The presence of this option is not 3261 expected to reveal any sensitive information about the message 3262 exchange. 3264 o OSCORE. The OSCORE option contains information about the 3265 compressed COSE header. A change of this field may result in not 3266 being able to verify the OSCORE message. 3268 D.4.4. HTTP Message Fields 3270 In contrast to CoAP, where OSCORE does not protect header fields to 3271 enable CoAP-CoAP proxy operations, the use of OSCORE with HTTP is 3272 restricted to transporting a protected CoAP message over an HTTP hop. 3273 Any unprotected HTTP message fields may reveal information about the 3274 transport of the OSCORE message and enable various denial of service 3275 attacks. It is recommended to additionally use TLS [RFC5246] for 3276 HTTP hops, which enables encryption and integrity protection of 3277 headers, but still leaves some information for traffic analysis. 3279 Appendix E. CDDL Summary 3281 Data structure definitions in the present specification employ the 3282 CDDL language for conciseness and precision. CDDL is defined in 3283 [I-D.ietf-cbor-cddl], which at the time of writing this appendix is 3284 in the process of completion. As the document is not yet available 3285 for a normative reference, the present appendix defines the small 3286 subset of CDDL that is being used in the present specification. 3288 Within the subset being used here, a CDDL rule is of the form "name = 3289 type", where "name" is the name given to the "type". A "type" can be 3290 one of: 3292 o a reference to another named type, by giving its name. The 3293 predefined named types used in the present specification are: 3294 "uint", an unsigned integer (as represented in CBOR by major type 3295 0); "int", an unsigned or negative integer (as represented in CBOR 3296 by major type 0 or 1); "bstr", a byte string (as represented in 3297 CBOR by major type 2); "tstr", a text string (as represented in 3298 CBOR by major type 3); 3300 o a choice between two types, by giving both types separated by a 3301 "/"; 3303 o an array type (as represented in CBOR by major type 4), where the 3304 sequence of elements of the array is described by giving a 3305 sequence of entries separated by commas ",", and this sequence is 3306 enclosed by square brackets "[" and "]". Arrays described by an 3307 array description contain elements that correspond one-to-one to 3308 the sequence of entries given. Each entry of an array description 3309 is of the form "name : type", where "name" is the name given to 3310 the entry and "type" is the type of the array element 3311 corresponding to this entry. 3313 Acknowledgments 3315 The following individuals provided input to this document: Christian 3316 Amsuess, Tobias Andersson, Carsten Bormann, Joakim Brorsson, Esko 3317 Dijk, Thomas Fossati, Martin Gunnarsson, Klaus Hartke, Jim Schaad, 3318 Peter van der Stok, Dave Thaler, Marco Tiloca, William Vignat, and 3319 Malisa Vucinic. 3321 Ludwig Seitz and Goeran Selander worked on this document as part of 3322 the CelticPlus project CyberWI, with funding from Vinnova. 3324 Authors' Addresses 3326 Goeran Selander 3327 Ericsson AB 3329 Email: goran.selander@ericsson.com 3331 John Mattsson 3332 Ericsson AB 3334 Email: john.mattsson@ericsson.com 3336 Francesca Palombini 3337 Ericsson AB 3339 Email: francesca.palombini@ericsson.com 3341 Ludwig Seitz 3342 RISE SICS 3344 Email: ludwig.seitz@ri.se