idnits 2.17.1 draft-ietf-core-object-security-16.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 : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([RFC7252]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 06, 2019) is 1878 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 6347 (Obsoleted by RFC 9147) ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 8152 (Obsoleted by RFC 9052, RFC 9053) == Outdated reference: A later version (-46) exists of draft-ietf-ace-oauth-authz-22 == Outdated reference: A later version (-19) exists of draft-ietf-ace-oscore-profile-07 == Outdated reference: A later version (-08) exists of draft-ietf-cbor-cddl-07 == Outdated reference: A later version (-14) exists of draft-ietf-core-echo-request-tag-03 == Outdated reference: A later version (-21) exists of draft-ietf-core-oscore-groupcomm-03 Summary: 6 errors (**), 0 flaws (~~), 6 warnings (==), 2 comments (--). 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 Updates: 7252 (if approved) F. Palombini 5 Intended status: Standards Track Ericsson AB 6 Expires: September 7, 2019 L. Seitz 7 RISE SICS 8 March 06, 2019 10 Object Security for Constrained RESTful Environments (OSCORE) 11 draft-ietf-core-object-security-16 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 Although being an optional functionality of CoAP, OSCORE alters CoAP 25 options processing and IANA registration. Therefore, this document 26 updates [RFC7252]. 28 Status of This Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. 33 Internet-Drafts are working documents of the Internet Engineering 34 Task Force (IETF). Note that other groups may also distribute 35 working documents as Internet-Drafts. The list of current Internet- 36 Drafts is at https://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on September 7, 2019. 45 Copyright Notice 47 Copyright (c) 2019 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents 52 (https://trustee.ietf.org/license-info) in effect on the date of 53 publication of this document. Please review these documents 54 carefully, as they describe your rights and restrictions with respect 55 to this document. Code Components extracted from this document must 56 include Simplified BSD License text as described in Section 4.e of 57 the Trust Legal Provisions and are provided without warranty as 58 described in the Simplified BSD License. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 63 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 64 2. The OSCORE Option . . . . . . . . . . . . . . . . . . . . . . 7 65 3. The Security Context . . . . . . . . . . . . . . . . . . . . 7 66 3.1. Security Context Definition . . . . . . . . . . . . . . . 8 67 3.2. Establishment of Security Context Parameters . . . . . . 10 68 3.3. Requirements on the Security Context Parameters . . . . . 12 69 4. Protected Message Fields . . . . . . . . . . . . . . . . . . 13 70 4.1. CoAP Options . . . . . . . . . . . . . . . . . . . . . . 14 71 4.2. CoAP Header Fields and Payload . . . . . . . . . . . . . 23 72 4.3. Signaling Messages . . . . . . . . . . . . . . . . . . . 23 73 5. The COSE Object . . . . . . . . . . . . . . . . . . . . . . . 24 74 5.1. ID Context and 'kid context' . . . . . . . . . . . . . . 25 75 5.2. AEAD Nonce . . . . . . . . . . . . . . . . . . . . . . . 26 76 5.3. Plaintext . . . . . . . . . . . . . . . . . . . . . . . . 27 77 5.4. Additional Authenticated Data . . . . . . . . . . . . . . 28 78 6. OSCORE Header Compression . . . . . . . . . . . . . . . . . . 29 79 6.1. Encoding of the OSCORE Option Value . . . . . . . . . . . 30 80 6.2. Encoding of the OSCORE Payload . . . . . . . . . . . . . 31 81 6.3. Examples of Compressed COSE Objects . . . . . . . . . . . 31 82 7. Message Binding, Sequence Numbers, Freshness, and Replay 83 Protection . . . . . . . . . . . . . . . . . . . . . . . . . 34 84 7.1. Message Binding . . . . . . . . . . . . . . . . . . . . . 34 85 7.2. Sequence Numbers . . . . . . . . . . . . . . . . . . . . 34 86 7.3. Freshness . . . . . . . . . . . . . . . . . . . . . . . . 34 87 7.4. Replay Protection . . . . . . . . . . . . . . . . . . . . 35 88 7.5. Losing Part of the Context State . . . . . . . . . . . . 36 89 8. Processing . . . . . . . . . . . . . . . . . . . . . . . . . 37 90 8.1. Protecting the Request . . . . . . . . . . . . . . . . . 37 91 8.2. Verifying the Request . . . . . . . . . . . . . . . . . . 37 92 8.3. Protecting the Response . . . . . . . . . . . . . . . . . 39 93 8.4. Verifying the Response . . . . . . . . . . . . . . . . . 40 94 9. Web Linking . . . . . . . . . . . . . . . . . . . . . . . . . 42 95 10. CoAP-to-CoAP Forwarding Proxy . . . . . . . . . . . . . . . . 42 96 11. HTTP Operations . . . . . . . . . . . . . . . . . . . . . . . 43 97 11.1. The HTTP OSCORE Header Field . . . . . . . . . . . . . . 43 98 11.2. CoAP-to-HTTP Mapping . . . . . . . . . . . . . . . . . . 44 99 11.3. HTTP-to-CoAP Mapping . . . . . . . . . . . . . . . . . . 45 100 11.4. HTTP Endpoints . . . . . . . . . . . . . . . . . . . . . 45 101 11.5. Example: HTTP Client and CoAP Server . . . . . . . . . . 46 102 11.6. Example: CoAP Client and HTTP Server . . . . . . . . . . 47 103 12. Security Considerations . . . . . . . . . . . . . . . . . . . 48 104 12.1. End-to-end Protection . . . . . . . . . . . . . . . . . 48 105 12.2. Security Context Establishment . . . . . . . . . . . . . 49 106 12.3. Master Secret . . . . . . . . . . . . . . . . . . . . . 49 107 12.4. Replay Protection . . . . . . . . . . . . . . . . . . . 50 108 12.5. Client Aliveness . . . . . . . . . . . . . . . . . . . . 50 109 12.6. Cryptographic Considerations . . . . . . . . . . . . . . 50 110 12.7. Message Segmentation . . . . . . . . . . . . . . . . . . 51 111 12.8. Privacy Considerations . . . . . . . . . . . . . . . . . 51 112 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 52 113 13.1. COSE Header Parameters Registry . . . . . . . . . . . . 52 114 13.2. CoAP Option Numbers Registry . . . . . . . . . . . . . . 53 115 13.3. CoAP Signaling Option Numbers Registry . . . . . . . . . 54 116 13.4. Header Field Registrations . . . . . . . . . . . . . . . 54 117 13.5. Media Type Registrations . . . . . . . . . . . . . . . . 54 118 13.6. CoAP Content-Formats Registry . . . . . . . . . . . . . 56 119 13.7. OSCORE Flag Bits Registry . . . . . . . . . . . . . . . 56 120 13.8. Expert Review Instructions . . . . . . . . . . . . . . . 57 121 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 58 122 14.1. Normative References . . . . . . . . . . . . . . . . . . 58 123 14.2. Informative References . . . . . . . . . . . . . . . . . 59 124 Appendix A. Scenario Examples . . . . . . . . . . . . . . . . . 62 125 A.1. Secure Access to Sensor . . . . . . . . . . . . . . . . . 62 126 A.2. Secure Subscribe to Sensor . . . . . . . . . . . . . . . 63 127 Appendix B. Deployment Examples . . . . . . . . . . . . . . . . 64 128 B.1. Security Context Derived Once . . . . . . . . . . . . . . 64 129 B.2. Security Context Derived Multiple Times . . . . . . . . . 66 130 Appendix C. Test Vectors . . . . . . . . . . . . . . . . . . . . 71 131 C.1. Test Vector 1: Key Derivation with Master Salt . . . . . 72 132 C.2. Test Vector 2: Key Derivation without Master Salt . . . . 73 133 C.3. Test Vector 3: Key Derivation with ID Context . . . . . . 75 134 C.4. Test Vector 4: OSCORE Request, Client . . . . . . . . . . 76 135 C.5. Test Vector 5: OSCORE Request, Client . . . . . . . . . . 77 136 C.6. Test Vector 6: OSCORE Request, Client . . . . . . . . . . 79 137 C.7. Test Vector 7: OSCORE Response, Server . . . . . . . . . 80 138 C.8. Test Vector 8: OSCORE Response with Partial IV, Server . 81 139 Appendix D. Overview of Security Properties . . . . . . . . . . 82 140 D.1. Threat Model . . . . . . . . . . . . . . . . . . . . . . 82 141 D.2. Supporting Proxy Operations . . . . . . . . . . . . . . . 83 142 D.3. Protected Message Fields . . . . . . . . . . . . . . . . 84 143 D.4. Uniqueness of (key, nonce) . . . . . . . . . . . . . . . 85 144 D.5. Unprotected Message Fields . . . . . . . . . . . . . . . 86 145 Appendix E. CDDL Summary . . . . . . . . . . . . . . . . . . . . 89 146 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 90 147 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 90 149 1. Introduction 151 The Constrained Application Protocol (CoAP) [RFC7252] is a web 152 transfer protocol, designed for constrained nodes and networks 153 [RFC7228], and may be mapped from HTTP [RFC8075]. CoAP specifies the 154 use of proxies for scalability and efficiency and references DTLS 155 [RFC6347] for security. CoAP-to-CoAP, HTTP-to-CoAP, and CoAP-to-HTTP 156 proxies require DTLS or TLS [RFC8446] to be terminated at the proxy. 157 The proxy therefore not only has access to the data required for 158 performing the intended proxy functionality, but is also able to 159 eavesdrop on, or manipulate any part of, the message payload and 160 metadata in transit between the endpoints. The proxy can also 161 inject, delete, or reorder packets since they are no longer protected 162 by (D)TLS. 164 This document defines the Object Security for Constrained RESTful 165 Environments (OSCORE) security protocol, protecting CoAP and CoAP- 166 mappable HTTP requests and responses end-to-end across intermediary 167 nodes such as CoAP forward proxies and cross-protocol translators 168 including HTTP-to-CoAP proxies [RFC8075]. In addition to the core 169 CoAP features defined in [RFC7252], OSCORE supports the Observe 170 [RFC7641], Block-wise [RFC7959], and No-Response [RFC7967] options, 171 as well as the PATCH and FETCH methods [RFC8132]. An analysis of 172 end-to-end security for CoAP messages through some types of 173 intermediary nodes is performed in 174 [I-D.hartke-core-e2e-security-reqs]. OSCORE essentially protects the 175 RESTful interactions; the request method, the requested resource, the 176 message payload, etc. (see Section 4). OSCORE protects neither the 177 CoAP Messaging Layer nor the CoAP Token which may change between the 178 endpoints, and those are therefore processed as defined in [RFC7252]. 179 Additionally, since the message formats for CoAP over unreliable 180 transport [RFC7252] and for CoAP over reliable transport [RFC8323] 181 differ only in terms of CoAP Messaging Layer, OSCORE can be applied 182 to both unreliable and reliable transports (see Figure 1). 184 OSCORE works in very constrained nodes and networks, thanks to its 185 small message size and the restricted code and memory requirements in 186 addition to what is required by CoAP. Examples of the use of OSCORE 187 are given in Appendix A. OSCORE may be used over any underlying 188 layer, such as e.g. UDP or TCP, and with non-IP transports (e.g., 190 [I-D.bormann-6lo-coap-802-15-ie]). OSCORE may also be used in 191 different ways with HTTP. OSCORE messages may be transported in 192 HTTP, and OSCORE may also be used to protect CoAP-mappable HTTP 193 messages, as described below. 195 +-----------------------------------+ 196 | Application | 197 +-----------------------------------+ 198 +-----------------------------------+ \ 199 | Requests / Responses / Signaling | | 200 |-----------------------------------| | 201 | OSCORE | | CoAP 202 |-----------------------------------| | 203 | Messaging Layer / Message Framing | | 204 +-----------------------------------+ / 205 +-----------------------------------+ 206 | UDP / TCP / ... | 207 +-----------------------------------+ 209 Figure 1: Abstract Layering of CoAP with OSCORE 211 OSCORE is designed to protect as much information as possible while 212 still allowing CoAP proxy operations (Section 10). It works with 213 existing CoAP-to-CoAP forward proxies [RFC7252], but an OSCORE-aware 214 proxy will be more efficient. HTTP-to-CoAP proxies [RFC8075] and 215 CoAP-to-HTTP proxies can also be used with OSCORE, as specified in 216 Section 11. OSCORE may be used together with TLS or DTLS over one or 217 more hops in the end-to-end path, e.g. transported with HTTPS in one 218 hop and with plain CoAP in another hop. The use of OSCORE does not 219 affect the URI scheme and OSCORE can therefore be used with any URI 220 scheme defined for CoAP or HTTP. The application decides the 221 conditions for which OSCORE is required. 223 OSCORE uses pre-shared keys which may have been established out-of- 224 band or with a key establishment protocol (see Section 3.2). The 225 technical solution builds on CBOR Object Signing and Encryption 226 (COSE) [RFC8152], providing end-to-end encryption, integrity, replay 227 protection, and binding of response to request. A compressed version 228 of COSE is used, as specified in Section 6. The use of OSCORE is 229 signaled in CoAP with a new option (Section 2), and in HTTP with a 230 new header field (Section 11.1) and content type (Section 13.5). The 231 solution transforms a CoAP/HTTP message into an "OSCORE message" 232 before sending, and vice versa after receiving. The OSCORE message 233 is a CoAP/HTTP message related to the original message in the 234 following way: the original CoAP/HTTP message is translated to CoAP 235 (if not already in CoAP) and protected in a COSE object. The 236 encrypted message fields of this COSE object are transported in the 237 CoAP payload/HTTP body of the OSCORE message, and the OSCORE option/ 238 header field is included in the message. A sketch of an exchange of 239 OSCORE messages, in the case of the original message being CoAP, is 240 provided in Figure 2. The use of OSCORE with HTTP is detailed in 241 Section 11. 243 Client Server 244 | OSCORE request - POST example.com: | 245 | Header, Token, | 246 | Options: OSCORE, ..., | 247 | Payload: COSE ciphertext | 248 +--------------------------------------------->| 249 | | 250 |<---------------------------------------------+ 251 | OSCORE response - 2.04 (Changed): | 252 | Header, Token, | 253 | Options: OSCORE, ..., | 254 | Payload: COSE ciphertext | 255 | | 257 Figure 2: Sketch of CoAP with OSCORE 259 An implementation supporting this specification MAY implement only 260 the client part, MAY implement only the server part, or MAY implement 261 only one of the proxy parts. 263 1.1. Terminology 265 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 266 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 267 "OPTIONAL" in this document are to be interpreted as described in BCP 268 14 [RFC2119] [RFC8174] when, and only when, they appear in all 269 capitals, as shown here. 271 Readers are expected to be familiar with the terms and concepts 272 described in CoAP [RFC7252], Observe [RFC7641], Block-wise [RFC7959], 273 COSE [RFC8152], CBOR [RFC7049], CDDL [I-D.ietf-cbor-cddl] as 274 summarized in Appendix E, and constrained environments [RFC7228]. 276 The term "hop" is used to denote a particular leg in the end-to-end 277 path. The concept "hop-by-hop" (as in "hop-by-hop encryption" or 278 "hop-by-hop fragmentation") opposed to "end-to-end", is used in this 279 document to indicate that the messages are processed accordingly in 280 the intermediaries, rather than just forwarded to the next node. 282 The term "stop processing" is used throughout the document to denote 283 that the message is not passed up to the CoAP Request/Response Layer 284 (see Figure 1). 286 The terms Common/Sender/Recipient Context, Master Secret/Salt, Sender 287 ID/Key, Recipient ID/Key, ID Context, and Common IV are defined in 288 Section 3.1. 290 2. The OSCORE Option 292 The OSCORE option defined in this section (see Figure 3, which 293 extends Table 4: Options of [RFC7252]) indicates that the CoAP 294 message is an OSCORE message and that it contains a compressed COSE 295 object (see Sections 5 and 6). The OSCORE option is critical, safe 296 to forward, part of the cache key, and not repeatable. 298 +------+---+---+---+---+----------------+--------+--------+---------+ 299 | No. | C | U | N | R | Name | Format | Length | Default | 300 +------+---+---+---+---+----------------+--------+--------+---------+ 301 | TBD1 | x | | | | OSCORE | (*) | 0-255 | (none) | 302 +------+---+---+---+---+----------------+--------+--------+---------+ 303 C = Critical, U = Unsafe, N = NoCacheKey, R = Repeatable 304 (*) See below. 306 Figure 3: The OSCORE Option 308 The OSCORE option includes the OSCORE flag bits (Section 6), the 309 Sender Sequence Number, the Sender ID, and the ID Context when these 310 fields are present (Section 3). The detailed format and length is 311 specified in Section 6. If the OSCORE flag bits are all zero (0x00) 312 the Option value SHALL be empty (Option Length = 0). An endpoint 313 receiving a CoAP message without payload, that also contains an 314 OSCORE option SHALL treat it as malformed and reject it. 316 A successful response to a request with the OSCORE option SHALL 317 contain the OSCORE option. Whether error responses contain the 318 OSCORE option depends on the error type (see Section 8). 320 For CoAP proxy operations, see Section 10. 322 3. The Security Context 324 OSCORE requires that client and server establish a shared security 325 context used to process the COSE objects. OSCORE uses COSE with an 326 Authenticated Encryption with Additional Data (AEAD, [RFC5116]) 327 algorithm for protecting message data between a client and a server. 328 In this section, we define the security context and how it is derived 329 in client and server based on a shared secret and a key derivation 330 function. 332 3.1. Security Context Definition 334 The security context is the set of information elements necessary to 335 carry out the cryptographic operations in OSCORE. For each endpoint, 336 the security context is composed of a "Common Context", a "Sender 337 Context", and a "Recipient Context". 339 The endpoints protect messages to send using the Sender Context and 340 verify messages received using the Recipient Context, both contexts 341 being derived from the Common Context and other data. Clients and 342 servers need to be able to retrieve the correct security context to 343 use. 345 An endpoint uses its Sender ID (SID) to derive its Sender Context, 346 and the other endpoint uses the same ID, now called Recipient ID 347 (RID), to derive its Recipient Context. In communication between two 348 endpoints, the Sender Context of one endpoint matches the Recipient 349 Context of the other endpoint, and vice versa. Thus, the two 350 security contexts identified by the same IDs in the two endpoints are 351 not the same, but they are partly mirrored. Retrieval and use of the 352 security context are shown in Figure 4. 354 .-----------------------------------------------. 355 | Common Context | 356 +---------------------.---.---------------------+ 357 | Sender Context | = | Recipient Context | 358 +---------------------+ +---------------------+ 359 | Recipient Context | = | Sender Context | 360 '---------------------' '---------------------' 361 Client Server 362 | | 363 Retrieve context for | OSCORE request: | 364 target resource | Token = Token1, | 365 Protect request with | kid = SID, ... | 366 Sender Context +---------------------->| Retrieve context with 367 | | RID = kid 368 | | Verify request with 369 | | Recipient Context 370 | OSCORE response: | Protect response with 371 | Token = Token1, ... | Sender Context 372 Retrieve context with |<----------------------+ 373 Token = Token1 | | 374 Verify request with | | 375 Recipient Context | | 377 Figure 4: Retrieval and Use of the Security Context 379 The Common Context contains the following parameters: 381 o AEAD Algorithm. The COSE AEAD algorithm to use for encryption. 383 o HKDF Algorithm. An HMAC-based key derivation function HKDF 384 [RFC5869] used to derive Sender Key, Recipient Key, and Common IV. 386 o Master Secret. Variable length, random byte string (see 387 Section 12.3) used to derive AEAD keys and Common IV. 389 o Master Salt. Optional variable length byte string containing the 390 salt used to derive AEAD keys and Common IV. 392 o ID Context. Optional variable length byte string providing 393 additional information to identify the Common Context and to 394 derive AEAD keys and Common IV. The use of ID Context is 395 described in Section 5.1. 397 o Common IV. Byte string derived from Master Secret, Master Salt, 398 and ID Context. Used to generate the AEAD Nonce (see 399 Section 5.2). Same length as the nonce of the AEAD Algorithm. 401 The Sender Context contains the following parameters: 403 o Sender ID. Byte string used to identify the Sender Context, to 404 derive AEAD keys and Common IV, and to assure unique AEAD nonces. 405 Maximum length is determined by the AEAD Algorithm. 407 o Sender Key. Byte string containing the symmetric AEAD key to 408 protect messages to send. Derived from Common Context and Sender 409 ID. Length is determined by the AEAD Algorithm. 411 o Sender Sequence Number. Non-negative integer used by the sender 412 to enumerate requests and certain responses, e.g. Observe 413 notifications. Used as 'Partial IV' [RFC8152] to generate unique 414 AEAD nonces. Maximum value is determined by the AEAD Algorithm. 415 Initialization is described in Section 3.2.2. 417 The Recipient Context contains the following parameters: 419 o Recipient ID. Byte string used to identify the Recipient Context, 420 to derive AEAD keys and Common IV, and to assure unique AEAD 421 nonces. Maximum length is determined by the AEAD Algorithm. 423 o Recipient Key. Byte string containing the symmetric AEAD key to 424 verify messages received. Derived from Common Context and 425 Recipient ID. Length is determined by the AEAD Algorithm. 427 o Replay Window (Server only). The replay window to verify requests 428 received. Replay protection is described in Section 7.4 and 429 Section 3.2.2. 431 All parameters except Sender Sequence Number and Replay Window are 432 immutable once the security context is established. An endpoint may 433 free up memory by not storing the Common IV, Sender Key, and 434 Recipient Key, deriving them when needed. Alternatively, an endpoint 435 may free up memory by not storing the Master Secret and Master Salt 436 after the other parameters have been derived. 438 Endpoints MAY operate as both client and server and use the same 439 security context for those roles. Independent of being client or 440 server, the endpoint protects messages to send using its Sender 441 Context, and verifies messages received using its Recipient Context. 442 The endpoints MUST NOT change the Sender/Recipient ID when changing 443 roles. In other words, changing the roles does not change the set of 444 AEAD keys to be used. 446 3.2. Establishment of Security Context Parameters 448 Each endpoint derives the parameters in the security context from a 449 small set of input parameters. The following input parameters SHALL 450 be pre-established: 452 o Master Secret 454 o Sender ID 456 o Recipient ID 458 The following input parameters MAY be pre-established. In case any 459 of these parameters is not pre-established, the default value 460 indicated below is used: 462 o AEAD Algorithm 464 * Default is AES-CCM-16-64-128 (COSE algorithm encoding: 10) 466 o Master Salt 468 * Default is the empty byte string 470 o HKDF Algorithm 472 * Default is HKDF SHA-256 474 o Replay Window 475 * Default is DTLS-type replay protection with a window size of 32 476 [RFC6347] 478 All input parameters need to be known to and agreed on by both 479 endpoints, but the replay window may be different in the two 480 endpoints. The way the input parameters are pre-established, is 481 application specific. Considerations of security context 482 establishment are given in Section 12.2 and examples of deploying 483 OSCORE in Appendix B. 485 3.2.1. Derivation of Sender Key, Recipient Key, and Common IV 487 The HKDF MUST be one of the HMAC-based HKDF [RFC5869] algorithms 488 defined for COSE [RFC8152]. HKDF SHA-256 is mandatory to implement. 489 The security context parameters Sender Key, Recipient Key, and Common 490 IV SHALL be derived from the input parameters using the HKDF, which 491 consists of the composition of the HKDF-Extract and HKDF-Expand steps 492 [RFC5869]: 494 output parameter = HKDF(salt, IKM, info, L) 496 where: 498 o salt is the Master Salt as defined above 500 o IKM is the Master Secret as defined above 502 o info is the serialization of a CBOR array consisting of (the 503 notation follows Appendix E): 505 info = [ 506 id : bstr, 507 id_context : bstr / nil, 508 alg_aead : int / tstr, 509 type : tstr, 510 L : uint, 511 ] 513 where: 515 o id is the Sender ID or Recipient ID when deriving Sender Key and 516 Recipient Key, respectively, and the empty byte string when 517 deriving the Common IV. 519 o id_context is the ID Context, or nil if ID Context is not 520 provided. 522 o alg_aead is the AEAD Algorithm, encoded as defined in [RFC8152]. 524 o type is "Key" or "IV". The label is an ASCII string, and does not 525 include a trailing NUL byte. 527 o L is the size of the key/nonce for the AEAD algorithm used, in 528 bytes. 530 For example, if the algorithm AES-CCM-16-64-128 (see Section 10.2 in 531 [RFC8152]) is used, the integer value for alg_aead is 10, the value 532 for L is 16 for keys and 13 for the Common IV. Assuming use of the 533 default algorithms HKDF SHA-256 and AES-CCM-16-64-128, the extract 534 phase of HKDF produces a pseudorandom key (PRK) as follows: 536 PRK = HMAC-SHA-256(Master Salt, Master Secret) 538 and as L is smaller than the hash function output size, the expand 539 phase of HKDF consists of a single HMAC invocation, and the Sender 540 Key, Recipient Key, and Common IV are therefore the first 16 or 13 541 bytes of 543 output parameter = HMAC-SHA-256(PRK, info || 0x01) 545 where different info are used for each derived parameter and where || 546 denotes byte string concatenation. 548 Note that [RFC5869] specifies that if the salt is not provided, it is 549 set to a string of zeros. For implementation purposes, not providing 550 the salt is the same as setting the salt to the empty byte string. 551 OSCORE sets the salt default value to empty byte string, which is 552 converted to a string of zeroes (see Section 2.2 of [RFC5869]). 554 3.2.2. Initial Sequence Numbers and Replay Window 556 The Sender Sequence Number is initialized to 0. 558 The supported types of replay protection and replay window length is 559 application specific and depends on how OSCORE is transported, see 560 Section 7.4. The default is DTLS-type replay protection with a 561 window size of 32 initiated as described in Section 4.1.2.6 of 562 [RFC6347]. 564 3.3. Requirements on the Security Context Parameters 566 To ensure unique Sender Keys, the quartet (Master Secret, Master 567 Salt, ID Context, Sender ID) MUST be unique, i.e. the pair (ID 568 Context, Sender ID) SHALL be unique in the set of all security 569 contexts using the same Master Secret and Master Salt. This means 570 that Sender ID SHALL be unique in the set of all security contexts 571 using the same Master Secret, Master Salt, and ID Context; such a 572 requirement guarantees unique (key, nonce) pairs for the AEAD. 574 Different methods can be used to assign Sender IDs: a protocol that 575 allows the parties to negotiate locally unique identifiers, a trusted 576 third party (e.g., [I-D.ietf-ace-oauth-authz]), or the identifiers 577 can be assigned out-of-band. The Sender IDs can be very short (note 578 that the empty string is a legitimate value). The maximum length of 579 Sender ID in bytes equals the length of AEAD nonce minus 6, see 580 Section 5.2. For AES-CCM-16-64-128 the maximum length of Sender ID 581 is 7 bytes. 583 To simplify retrieval of the right Recipient Context, the Recipient 584 ID SHOULD be unique in the sets of all Recipient Contexts used by an 585 endpoint. If an endpoint has the same Recipient ID with different 586 Recipient Contexts, i.e. the Recipient Contexts are derived from 587 different Common Contexts, then the endpoint may need to try multiple 588 times before verifying the right security context associated to the 589 Recipient ID. 591 The ID Context is used to distinguish between security contexts. The 592 methods used for assigning Sender ID can also be used for assigning 593 the ID Context. Additionally, the ID Context can be used to 594 introduce randomness into new Sender and Recipient Contexts (see 595 Appendix B.2). ID Context can be arbitrarily long. 597 4. Protected Message Fields 599 OSCORE transforms a CoAP message (which may have been generated from 600 an HTTP message) into an OSCORE message, and vice versa. OSCORE 601 protects as much of the original message as possible while still 602 allowing certain proxy operations (see Sections 10 and 11). This 603 section defines how OSCORE protects the message fields and transfers 604 them end-to-end between client and server (in any direction). 606 The remainder of this section and later sections focus on the 607 behavior in terms of CoAP messages. If HTTP is used for a particular 608 hop in the end-to-end path, then this section applies to the 609 conceptual CoAP message that is mappable to/from the original HTTP 610 message as discussed in Section 11. That is, an HTTP message is 611 conceptually transformed to a CoAP message and then to an OSCORE 612 message, and similarly in the reverse direction. An actual 613 implementation might translate directly from HTTP to OSCORE without 614 the intervening CoAP representation. 616 Protection of Signaling messages (Section 5 of [RFC8323]) is 617 specified in Section 4.3. The other parts of this section target 618 Request/Response messages. 620 Message fields of the CoAP message may be protected end-to-end 621 between CoAP client and CoAP server in different ways: 623 o Class E: encrypted and integrity protected, 625 o Class I: integrity protected only, or 627 o Class U: unprotected. 629 The sending endpoint SHALL transfer Class E message fields in the 630 ciphertext of the COSE object in the OSCORE message. The sending 631 endpoint SHALL include Class I message fields in the Additional 632 Authenticated Data (AAD) of the AEAD algorithm, allowing the 633 receiving endpoint to detect if the value has changed in transfer. 634 Class U message fields SHALL NOT be protected in transfer. Class I 635 and Class U message field values are transferred in the header or 636 options part of the OSCORE message, which is visible to proxies. 638 Message fields not visible to proxies, i.e., transported in the 639 ciphertext of the COSE object, are called "Inner" (Class E). Message 640 fields transferred in the header or options part of the OSCORE 641 message, which is visible to proxies, are called "Outer" (Class I or 642 U). There are currently no Class I options defined. 644 An OSCORE message may contain both an Inner and an Outer instance of 645 a certain CoAP message field. Inner message fields are intended for 646 the receiving endpoint, whereas Outer message fields are used to 647 enable proxy operations. 649 4.1. CoAP Options 651 A summary of how options are protected is shown in Figure 5. Note 652 that some options may have both Inner and Outer message fields which 653 are protected accordingly. Certain options require special 654 processing as is described in Section 4.1.3. 656 Options that are unknown or for which OSCORE processing is not 657 defined SHALL be processed as class E (and no special processing). 658 Specifications of new CoAP options SHOULD define how they are 659 processed with OSCORE. A new COAP option SHOULD be of class E unless 660 it requires proxy processing. If a new CoAP option is of class U, 661 the potential issues with the option being unprotected SHOULD be 662 documented (see Appendix D.5). 664 4.1.1. Inner Options 666 Inner option message fields (class E) are used to communicate 667 directly with the other endpoint. 669 The sending endpoint SHALL write the Inner option message fields 670 present in the original CoAP message into the plaintext of the COSE 671 object (Section 5.3), and then remove the Inner option message fields 672 from the OSCORE message. 674 The processing of Inner option message fields by the receiving 675 endpoint is specified in Sections 8.2 and 8.4. 677 +------+-----------------+---+---+ 678 | No. | Name | E | U | 679 +------+-----------------+---+---+ 680 | 1 | If-Match | x | | 681 | 3 | Uri-Host | | x | 682 | 4 | ETag | x | | 683 | 5 | If-None-Match | x | | 684 | 6 | Observe | x | x | 685 | 7 | Uri-Port | | x | 686 | 8 | Location-Path | x | | 687 | TBD1 | OSCORE | | x | 688 | 11 | Uri-Path | x | | 689 | 12 | Content-Format | x | | 690 | 14 | Max-Age | x | x | 691 | 15 | Uri-Query | x | | 692 | 17 | Accept | x | | 693 | 20 | Location-Query | x | | 694 | 23 | Block2 | x | x | 695 | 27 | Block1 | x | x | 696 | 28 | Size2 | x | x | 697 | 35 | Proxy-Uri | | x | 698 | 39 | Proxy-Scheme | | x | 699 | 60 | Size1 | x | x | 700 | 258 | No-Response | x | x | 701 +------+-----------------+---+---+ 703 E = Encrypt and Integrity Protect (Inner) 704 U = Unprotected (Outer) 706 Figure 5: Protection of CoAP Options 708 4.1.2. Outer Options 710 Outer option message fields (Class U or I) are used to support proxy 711 operations, see Appendix D.2. 713 The sending endpoint SHALL include the Outer option message field 714 present in the original message in the options part of the OSCORE 715 message. All Outer option message fields, including the OSCORE 716 option, SHALL be encoded as described in Section 3.1 of [RFC7252], 717 where the delta is the difference to the previously included instance 718 of Outer option message field. 720 The processing of Outer options by the receiving endpoint is 721 specified in Sections 8.2 and 8.4. 723 A procedure for integrity-protection-only of Class I option message 724 fields is specified in Section 5.4. Specifications that introduce 725 repeatable Class I options MUST specify that proxies MUST NOT change 726 the order of the instances of such an option in the CoAP message. 728 Note: There are currently no Class I option message fields defined. 730 4.1.3. Special Options 732 Some options require special processing as specified in this section. 734 4.1.3.1. Max-Age 736 An Inner Max-Age message field is used to indicate the maximum time a 737 response may be cached by the client (as defined in [RFC7252]), end- 738 to-end from the server to the client, taking into account that the 739 option is not accessible to proxies. The Inner Max-Age SHALL be 740 processed by OSCORE as a normal Inner option, specified in 741 Section 4.1.1. 743 An Outer Max-Age message field is used to avoid unnecessary caching 744 of error responses caused by OSCORE processing at OSCORE-unaware 745 intermediary nodes. A server MAY set a Class U Max-Age message field 746 with value zero to such error responses, described in Sections 7.4, 747 8.2, and 8.4, since these error responses are cacheable, but 748 subsequent OSCORE requests would never create a hit in the 749 intermediary caching it. Setting the Outer Max-Age to zero relieves 750 the intermediary from uselessly caching responses. Successful OSCORE 751 responses do not need to include an Outer Max-Age option since the 752 responses appear to the OSCORE-unaware intermediary as 2.04 (Changed) 753 responses, which are non-cacheable (see Section 4.2). 755 The Outer Max-Age message field is processed according to 756 Section 4.1.2. 758 4.1.3.2. Uri-Host and Uri-Port 760 When the Uri-Host and Uri-Port are set to their default values (see 761 Section 5.10.1 [RFC7252]), they are omitted from the message 762 (Section 5.4.4 of [RFC7252]), which is favorable both for overhead 763 and privacy. 765 In order to support forward proxy operations, Proxy-Scheme, Uri-Host, 766 and Uri-Port need to be Class U. For the use of Proxy-Uri, see 767 Section 4.1.3.3. 769 Manipulation of unprotected message fields (including Uri-Host, Uri- 770 Port, destination IP/port or request scheme) MUST NOT lead to an 771 OSCORE message becoming verified by an unintended server. Different 772 servers SHALL have different security contexts. 774 4.1.3.3. Proxy-Uri 776 When Proxy-Uri is present, the client SHALL first decompose the 777 Proxy-Uri value of the original CoAP message into the Proxy-Scheme, 778 Uri-Host, Uri-Port, Uri-Path, and Uri-Query options according to 779 Section 6.4 of [RFC7252]. 781 Uri-Path and Uri-Query are class E options and SHALL be protected and 782 processed as Inner options (Section 4.1.1). 784 The Proxy-Uri option of the OSCORE message SHALL be set to the 785 composition of Proxy-Scheme, Uri-Host, and Uri-Port options as 786 specified in Section 6.5 of [RFC7252], and processed as an Outer 787 option of Class U (Section 4.1.2). 789 Note that replacing the Proxy-Uri value with the Proxy-Scheme and 790 Uri-* options works by design for all CoAP URIs (see Section 6 of 791 [RFC7252]). OSCORE-aware HTTP servers should not use the userinfo 792 component of the HTTP URI (as defined in Section 3.2.1 of [RFC3986]), 793 so that this type of replacement is possible in the presence of CoAP- 794 to-HTTP proxies (see Section 11.2). In future specifications of 795 cross-protocol proxying behavior using different URI structures, it 796 is expected that the authors will create Uri-* options that allow 797 decomposing the Proxy-Uri, and specifying the OSCORE processing. 799 An example of how Proxy-Uri is processed is given here. Assume that 800 the original CoAP message contains: 802 o Proxy-Uri = "coap://example.com/resource?q=1" 803 During OSCORE processing, Proxy-Uri is split into: 805 o Proxy-Scheme = "coap" 807 o Uri-Host = "example.com" 809 o Uri-Port = "5683" 811 o Uri-Path = "resource" 813 o Uri-Query = "q=1" 815 Uri-Path and Uri-Query follow the processing defined in 816 Section 4.1.1, and are thus encrypted and transported in the COSE 817 object: 819 o Uri-Path = "resource" 821 o Uri-Query = "q=1" 823 The remaining options are composed into the Proxy-Uri included in the 824 options part of the OSCORE message, which has value: 826 o Proxy-Uri = "coap://example.com" 828 See Sections 6.1 and 12.6 of [RFC7252] for more details. 830 4.1.3.4. The Block Options 832 Block-wise [RFC7959] is an optional feature. An implementation MAY 833 support [RFC7252] and the OSCORE option without supporting block-wise 834 transfers. The Block options (Block1, Block2, Size1, Size2), when 835 Inner message fields, provide secure message segmentation such that 836 each segment can be verified. The Block options, when Outer message 837 fields, enables hop-by-hop fragmentation of the OSCORE message. 838 Inner and Outer block processing may have different performance 839 properties depending on the underlying transport. The end-to-end 840 integrity of the message can be verified both in case of Inner and 841 Outer Block-wise transfers provided all blocks are received. 843 4.1.3.4.1. Inner Block Options 845 The sending CoAP endpoint MAY fragment a CoAP message as defined in 846 [RFC7959] before the message is processed by OSCORE. In this case 847 the Block options SHALL be processed by OSCORE as normal Inner 848 options (Section 4.1.1). The receiving CoAP endpoint SHALL process 849 the OSCORE message before processing Block-wise as defined in 850 [RFC7959]. 852 4.1.3.4.2. Outer Block Options 854 Proxies MAY fragment an OSCORE message using [RFC7959], by 855 introducing Block option message fields that are Outer 856 (Section 4.1.2). Note that the Outer Block options are neither 857 encrypted nor integrity protected. As a consequence, a proxy can 858 maliciously inject block fragments indefinitely, since the receiving 859 endpoint needs to receive the last block (see [RFC7959]) to be able 860 to compose the OSCORE message and verify its integrity. Therefore, 861 applications supporting OSCORE and [RFC7959] MUST specify a security 862 policy defining a maximum unfragmented message size 863 (MAX_UNFRAGMENTED_SIZE) considering the maximum size of message which 864 can be handled by the endpoints. Messages exceeding this size SHOULD 865 be fragmented by the sending endpoint using Inner Block options 866 (Section 4.1.3.4.1). 868 An endpoint receiving an OSCORE message with an Outer Block option 869 SHALL first process this option according to [RFC7959], until all 870 blocks of the OSCORE message have been received, or the cumulated 871 message size of the blocks exceeds MAX_UNFRAGMENTED_SIZE. In the 872 former case, the processing of the OSCORE message continues as 873 defined in this document. In the latter case the message SHALL be 874 discarded. 876 Because of encryption of Uri-Path and Uri-Query, messages to the same 877 server may, from the point of view of a proxy, look like they also 878 target the same resource. A proxy SHOULD mitigate a potential mix-up 879 of blocks from concurrent requests to the same server, for example 880 using the Request-Tag processing specified in Section 3.3.2 of 881 [I-D.ietf-core-echo-request-tag]. 883 4.1.3.5. Observe 885 Observe [RFC7641] is an optional feature. An implementation MAY 886 support [RFC7252] and the OSCORE option without supporting [RFC7641], 887 in which case the Observe related processing can be omitted. 889 The support for Observe [RFC7641] with OSCORE targets the 890 requirements on forwarding of Section 2.2.1 of 891 [I-D.hartke-core-e2e-security-reqs], i.e. that observations go 892 through intermediary nodes, as illustrated in Figure 8 of [RFC7641]. 894 Inner Observe SHALL be used to protect the value of the Observe 895 option between the endpoints. Outer Observe SHALL be used to support 896 forwarding by intermediary nodes. 898 The server SHALL include a new Partial IV (see Section 5) in 899 responses (with or without the Observe option) to Observe 900 registrations, except for the first response where Partial IV MAY be 901 omitted. 903 For cancellations, Section 3.6 of [RFC7641] specifies that all 904 options MUST be identical to those in the registration request except 905 for Observe and the set of ETag Options. For OSCORE messages, this 906 matching is to be done to the options in the decrypted message. 908 [RFC7252] does not specify how the server should act upon receiving 909 the same Token in different requests. When using OSCORE, the server 910 SHOULD NOT remove an active observation just because it receives a 911 request with the same Token. 913 Since POST with Observe is not defined, for messages with Observe, 914 the Outer Code MUST be set to 0.05 (FETCH) for requests and to 2.05 915 (Content) for responses (see Section 4.2). 917 4.1.3.5.1. Registrations and Cancellations 919 The Inner and Outer Observe in the request MUST contain the Observe 920 value of the original CoAP request; 0 (registration) or 1 921 (cancellation). 923 Every time a client issues a new Observe request, a new Partial IV 924 MUST be used (see Section 5), and so the payload and OSCORE option 925 are changed. The server uses the Partial IV of the new request as 926 the 'request_piv' of all associated notifications (see Section 5.4). 928 Intermediaries are not assumed to have access to the OSCORE security 929 context used by the endpoints, and thus cannot make requests or 930 transform responses with the OSCORE option which verify at the 931 receiving endpoint as coming from the other endpoint. This has the 932 following consequences and limitations for Observe operations. 934 o An intermediary node removing the Outer Observe 0 does not change 935 the registration request to a request without Observe (see 936 Section 2 of [RFC7641]). Instead other means for cancellation may 937 be used as described in Section 3.6 of [RFC7641]. 939 o An intermediary node is not able to transform a normal response 940 into an OSCORE protected Observe notification (see figure 7 of 941 [RFC7641]) which verifies as coming from the server. 943 o An intermediary node is not able to initiate an OSCORE protected 944 Observe registration (Observe with value 0) which verifies as 945 coming from the client. An OSCORE-aware intermediary SHALL NOT 946 initiate registrations of observations (see Section 10). If an 947 OSCORE-unaware proxy re-sends an old registration message from a 948 client this will trigger the replay protection mechanism in the 949 server. To prevent this from resulting in the OSCORE-unaware 950 proxy to cancel of the registration, a server MAY respond to a 951 replayed registration request with a replay of a cached 952 notification. Alternatively, the server MAY send a new 953 notification. 955 o An intermediary node is not able to initiate an OSCORE protected 956 Observe cancellation (Observe with value 1) which verifies as 957 coming from the client. An application MAY decide to allow 958 intermediaries to cancel Observe registrations, e.g. to send 959 Observe with value 1 (see Section 3.6 of [RFC7641]), but that can 960 also be done with other methods, e.g. reusing the Token in a 961 different request or sending a RST message. This is out of scope 962 for this specification. 964 4.1.3.5.2. Notifications 966 If the server accepts an Observe registration, a Partial IV MUST be 967 included in all notifications (both successful and error), except for 968 the first one where Partial IV MAY be omitted. To protect against 969 replay, the client SHALL maintain a Notification Number for each 970 Observation it registers. The Notification Number is a non-negative 971 integer containing the largest Partial IV of the received 972 notifications for the associated Observe registration. Further 973 details of replay protection of notifications are specified in 974 Section 7.4.1. 976 For notifications, the Inner Observe value MUST be empty (see 977 Section 3.2 of [RFC7252]). The Outer Observe in a notification is 978 needed for intermediary nodes to allow multiple responses to one 979 request, and may be set to the value of Observe in the original CoAP 980 message. The client performs ordering of notifications and replay 981 protection by comparing their Partial IVs and SHALL ignore the outer 982 Observe value. 984 If the client receives a response to an Observe request without an 985 Inner Observe option, then it verifies the response as a non-Observe 986 response, as specified in Section 8.4. If the client receives a 987 response to a non-Observe request with an Inner Observe option, then 988 it stops processing the message, as specified in Section 8.4. 990 A client MUST consider the notification with the highest Partial IV 991 as the freshest, regardless of the order of arrival. In order to 992 support existing Observe implementations the OSCORE client 993 implementation MAY set the Observe value to the three least 994 significant bytes of the Partial IV. Implementations need to make 995 sure that the notification without Partial IV is considered the 996 oldest. 998 4.1.3.6. No-Response 1000 No-Response [RFC7967] is an optional feature used by the client to 1001 communicate its disinterest in certain classes of responses to a 1002 particular request. An implementation MAY support [RFC7252] and the 1003 OSCORE option without supporting [RFC7967]. 1005 If used, No-Response MUST be Inner. The Inner No-Response SHALL be 1006 processed by OSCORE as specified in Section 4.1.1. The Outer option 1007 SHOULD NOT be present. The server SHALL ignore the Outer No-Response 1008 option. The client MAY set the Outer No-Response value to 26 1009 ('suppress all known codes') if the Inner value is set to 26. The 1010 client MUST be prepared to receive and discard 5.04 (Gateway Timeout) 1011 error messages from intermediaries potentially resulting from 1012 destination time out due to no response. 1014 4.1.3.7. OSCORE 1016 The OSCORE option is only defined to be present in OSCORE messages, 1017 as an indication that OSCORE processing have been performed. The 1018 content in the OSCORE option is neither encrypted nor integrity 1019 protected as a whole but some part of the content of this option is 1020 protected (see Section 5.4). Nested use of OSCORE is not supported: 1021 If OSCORE processing detects an OSCORE option in the original CoAP 1022 message, then processing SHALL be stopped. 1024 +------------------+---+---+ 1025 | Field | E | U | 1026 +------------------+---+---+ 1027 | Version (UDP) | | x | 1028 | Type (UDP) | | x | 1029 | Length (TCP) | | x | 1030 | Token Length | | x | 1031 | Code | x | | 1032 | Message ID (UDP) | | x | 1033 | Token | | x | 1034 | Payload | x | | 1035 +------------------+---+---+ 1037 E = Encrypt and Integrity Protect (Inner) 1038 U = Unprotected (Outer) 1040 Figure 6: Protection of CoAP Header Fields and Payload 1042 4.2. CoAP Header Fields and Payload 1044 A summary of how the CoAP header fields and payload are protected is 1045 shown in Figure 6, including fields specific to CoAP over UDP and 1046 CoAP over TCP (marked accordingly in the table). 1048 Most CoAP Header fields (i.e. the message fields in the fixed 4-byte 1049 header) are required to be read and/or changed by CoAP proxies and 1050 thus cannot in general be protected end-to-end between the endpoints. 1051 As mentioned in Section 1, OSCORE protects the CoAP Request/Response 1052 Layer only, and not the Messaging Layer (Section 2 of [RFC7252]), so 1053 fields such as Type and Message ID are not protected with OSCORE. 1055 The CoAP Header field Code is protected by OSCORE. Code SHALL be 1056 encrypted and integrity protected (Class E) to prevent an 1057 intermediary from eavesdropping on or manipulating the Code (e.g., 1058 changing from GET to DELETE). 1060 The sending endpoint SHALL write the Code of the original CoAP 1061 message into the plaintext of the COSE object (see Section 5.3). 1062 After that, the sending endpoint writes an Outer Code to the OSCORE 1063 message. With one exception (see Section 4.1.3.5) the Outer Code 1064 SHALL be set to 0.02 (POST) for requests and to 2.04 (Changed) for 1065 responses. The receiving endpoint SHALL discard the Outer Code in 1066 the OSCORE message and write the Code of the COSE object plaintext 1067 (Section 5.3) into the decrypted CoAP message. 1069 The other currently defined CoAP Header fields are Unprotected (Class 1070 U). The sending endpoint SHALL write all other header fields of the 1071 original message into the header of the OSCORE message. The 1072 receiving endpoint SHALL write the header fields from the received 1073 OSCORE message into the header of the decrypted CoAP message. 1075 The CoAP Payload, if present in the original CoAP message, SHALL be 1076 encrypted and integrity protected and is thus an Inner message field. 1077 The sending endpoint writes the payload of the original CoAP message 1078 into the plaintext (Section 5.3) input to the COSE object. The 1079 receiving endpoint verifies and decrypts the COSE object, and 1080 recreates the payload of the original CoAP message. 1082 4.3. Signaling Messages 1084 Signaling messages (CoAP Code 7.00-7.31) were introduced to exchange 1085 information related to an underlying transport connection in the 1086 specific case of CoAP over reliable transports [RFC8323]. 1088 OSCORE MAY be used to protect Signaling if the endpoints for OSCORE 1089 coincide with the endpoints for the signaling message. If OSCORE is 1090 used to protect Signaling then: 1092 o To comply with [RFC8323], an initial empty CSM message SHALL be 1093 sent. The subsequent signaling message SHALL be protected. 1095 o Signaling messages SHALL be protected as CoAP Request messages, 1096 except in the case the Signaling message is a response to a 1097 previous Signaling message, in which case it SHALL be protected as 1098 a CoAP Response message. For example, 7.02 (Ping) is protected as 1099 a CoAP Request and 7.03 (Pong) as a CoAP response. 1101 o The Outer Code for Signaling messages SHALL be set to 0.02 (POST), 1102 unless it is a response to a previous Signaling message, in which 1103 case it SHALL be set to 2.04 (Changed). 1105 o All Signaling options, except the OSCORE option, SHALL be Inner 1106 (Class E). 1108 NOTE: Option numbers for Signaling messages are specific to the CoAP 1109 Code (see Section 5.2 of [RFC8323]). 1111 If OSCORE is not used to protect Signaling, Signaling messages SHALL 1112 be unaltered by OSCORE. 1114 5. The COSE Object 1116 This section defines how to use COSE [RFC8152] to wrap and protect 1117 data in the original message. OSCORE uses the untagged COSE_Encrypt0 1118 structure with an Authenticated Encryption with Additional Data 1119 (AEAD) algorithm. The AEAD key lengths, AEAD nonce length, and 1120 maximum Sender Sequence Number are algorithm dependent. 1122 The AEAD algorithm AES-CCM-16-64-128 defined in Section 10.2 of 1123 [RFC8152] is mandatory to implement. For AES-CCM-16-64-128 the 1124 length of Sender Key and Recipient Key is 128 bits, the length of 1125 AEAD nonce and Common IV is 13 bytes. The maximum Sender Sequence 1126 Number is specified in Section 12. 1128 As specified in [RFC5116], plaintext denotes the data that is to be 1129 encrypted and integrity protected, and Additional Authenticated Data 1130 (AAD) denotes the data that is to be integrity protected only. 1132 The COSE Object SHALL be a COSE_Encrypt0 object with fields defined 1133 as follows 1135 o The 'protected' field is empty. 1137 o The 'unprotected' field includes: 1139 * The 'Partial IV' parameter. The value is set to the Sender 1140 Sequence Number. All leading bytes of value zero SHALL be 1141 removed when encoding the Partial IV, except in the case of 1142 Partial IV of value 0 which is encoded to the byte string 0x00. 1143 This parameter SHALL be present in requests. The Partial IV 1144 SHALL be present in responses to Observe registrations (see 1145 Section 4.1.3.5.1), otherwise the Partial IV will not typically 1146 be present in responses (for one exception, see 1147 Appendix B.1.2). 1149 * The 'kid' parameter. The value is set to the Sender ID. This 1150 parameter SHALL be present in requests and will not typically 1151 be present in responses. An example where the Sender ID is 1152 included in a response is the extension of OSCORE to group 1153 communication [I-D.ietf-core-oscore-groupcomm]. 1155 * Optionally, a 'kid context' parameter (see Section 5.1). This 1156 parameter MAY be present in requests, and if so, MUST contain 1157 an ID Context (see Section 3.1). This parameter SHOULD NOT be 1158 present in responses: an example of how 'kid context' can be 1159 used in responses is given in Appendix B.2. If 'kid context' 1160 is present in the request, then the server SHALL use a security 1161 context with that ID Context when verifying the request. 1163 o The 'ciphertext' field is computed from the secret key (Sender Key 1164 or Recipient Key), AEAD nonce (see Section 5.2), plaintext (see 1165 Section 5.3), and the Additional Authenticated Data (AAD) (see 1166 Section 5.4) following Section 5.2 of [RFC8152]. 1168 The encryption process is described in Section 5.3 of [RFC8152]. 1170 5.1. ID Context and 'kid context' 1172 For certain use cases, e.g. deployments where the same Sender ID is 1173 used with multiple contexts, it is possible (and sometimes necessary, 1174 see Section 3.3) for the client to use an ID Context to distinguish 1175 the security contexts (see Section 3.1). For example: 1177 o If the client has a unique identifier in some namespace then that 1178 identifier can be used as ID Context. 1180 o The ID Context may be used to add randomness into new Sender and 1181 Recipient Contexts, see Appendix B.2. 1183 o In case of group communication [I-D.ietf-core-oscore-groupcomm], a 1184 group identifier is used as ID Context to enable different 1185 security contexts for a server belonging to multiple groups. 1187 The Sender ID and ID Context are used to establish the necessary 1188 input parameters and in the derivation of the security context (see 1189 Section 3.2). 1191 Whereas the 'kid' parameter is used to transport the Sender ID, the 1192 new COSE header parameter 'kid context' is used to transport the ID 1193 Context in requests, see Figure 7. 1195 +----------+--------+------------+----------------+-----------------+ 1196 | name | label | value type | value registry | description | 1197 +----------+--------+------------+----------------+-----------------+ 1198 | kid | TBD2 | bstr | | Identifies the | 1199 | context | | | | context for kid | 1200 +----------+--------+------------+----------------+-----------------+ 1202 Figure 7: Common Header Parameter 'kid context' for the COSE object 1204 If ID Context is non-empty and the client sends a request without 1205 'kid context' which results in an error indicating that the server 1206 could not find the security context, then the client could include 1207 the ID Context in the 'kid context' when making another request. 1208 Note that since the error is unprotected it may have been spoofed and 1209 the real response blocked by an on-path attacker. 1211 5.2. AEAD Nonce 1213 The high level design of the AEAD nonce follows Section 4.4 of 1214 [I-D.mcgrew-iv-gen], here follows the detailed construction (see 1215 Figure 8): 1217 1. left-pad the Partial IV (PIV) with zeroes to exactly 5 bytes, 1219 2. left-pad the Sender ID of the endpoint that generated the Partial 1220 IV (ID_PIV) with zeroes to exactly nonce length minus 6 bytes, 1222 3. concatenate the size of the ID_PIV (a single byte S) with the 1223 padded ID_PIV and the padded PIV, 1225 4. and then XOR with the Common IV. 1227 Note that in this specification only AEAD algorithms that use nonces 1228 equal or greater than 7 bytes are supported. The nonce construction 1229 with S, ID_PIV, and PIV together with endpoint unique IDs and 1230 encryption keys makes it easy to verify that the nonces used with a 1231 specific key will be unique, see Appendix D.4. 1233 If the Partial IV is not present in a response, the nonce from the 1234 request is used. For responses that are not notifications (i.e. when 1235 there is a single response to a request), the request and the 1236 response should typically use the same nonce to reduce message 1237 overhead. Both alternatives provide all the required security 1238 properties, see Section 7.4 and Appendix D.4. The only non-Observe 1239 scenario where a Partial IV must be included in a response is when 1240 the server is unable to perform replay protection, see 1241 Appendix B.1.2. For processing instructions see Section 8. 1243 <- nonce length minus 6 B -> <-- 5 bytes --> 1244 +---+-------------------+--------+---------+-----+ 1245 | S | padding | ID_PIV | padding | PIV |----+ 1246 +---+-------------------+--------+---------+-----+ | 1247 | 1248 <---------------- nonce length ----------------> | 1249 +------------------------------------------------+ | 1250 | Common IV |->(XOR) 1251 +------------------------------------------------+ | 1252 | 1253 <---------------- nonce length ----------------> | 1254 +------------------------------------------------+ | 1255 | Nonce |<---+ 1256 +------------------------------------------------+ 1258 Figure 8: AEAD Nonce Formation 1260 5.3. Plaintext 1262 The plaintext is formatted as a CoAP message without Header (see 1263 Figure 9) consisting of: 1265 o the Code of the original CoAP message as defined in Section 3 of 1266 [RFC7252]; and 1268 o all Inner option message fields (see Section 4.1.1) present in the 1269 original CoAP message (see Section 4.1). The options are encoded 1270 as described in Section 3.1 of [RFC7252], where the delta is the 1271 difference to the previously included instance of Class E option; 1272 and 1274 o the Payload of original CoAP message, if present, and in that case 1275 prefixed by the one-byte Payload Marker (0xff). 1277 NOTE: The plaintext contains all CoAP data that needs to be encrypted 1278 end-to-end between the endpoints. 1280 0 1 2 3 1281 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 1282 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1283 | Code | Class E options (if any) ... 1284 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1285 |1 1 1 1 1 1 1 1| Payload (if any) ... 1286 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1287 (only if there 1288 is payload) 1290 Figure 9: Plaintext 1292 5.4. Additional Authenticated Data 1294 The external_aad SHALL be a CBOR array wrapped in a bstr object as 1295 defined below: 1297 external_aad = bstr .cbor aad_array 1299 aad_array = [ 1300 oscore_version : uint, 1301 algorithms : [ alg_aead : int / tstr ], 1302 request_kid : bstr, 1303 request_piv : bstr, 1304 options : bstr, 1305 ] 1307 where: 1309 o oscore_version: contains the OSCORE version number. 1310 Implementations of this specification MUST set this field to 1. 1311 Other values are reserved for future versions. 1313 o algorithms: contains (for extensibility) an array of algorithms, 1314 according to this specification only containing alg_aead. 1316 o alg_aead: contains the AEAD Algorithm from the security context 1317 used for the exchange (see Section 3.1). 1319 o request_kid: contains the value of the 'kid' in the COSE object of 1320 the request (see Section 5). 1322 o request_piv: contains the value of the 'Partial IV' in the COSE 1323 object of the request (see Section 5). 1325 o options: contains the Class I options (see Section 4.1.2) present 1326 in the original CoAP message encoded as described in Section 3.1 1327 of [RFC7252], where the delta is the difference to the previously 1328 included instance of class I option. 1330 The oscore_version and algorithms parameters are established out-of- 1331 band and are thus never transported in OSCORE, but the external_aad 1332 allows to verify that they are the same in both endpoints. 1334 NOTE: The format of the external_aad is for simplicity the same for 1335 requests and responses, although some parameters, e.g. request_kid, 1336 need not be integrity protected in all requests. 1338 The Additional Authenticated Data (AAD) is composed from the 1339 external_aad as described in Section 5.3 of [RFC8152]: 1341 AAD = Enc_structure = [ "Encrypt0", h'', external_aad ] 1343 The following is an example of AAD constructed using AEAD Algorithm = 1344 AES-CCM-16-64-128 (10), request_kid = 0x00, request_piv = 0x25 and no 1345 Class I options: 1347 o oscore_version: 0x01 (1 byte) 1349 o algorithms: 0x810a (2 bytes) 1351 o request_kid: 0x00 (1 byte) 1353 o request_piv: 0x25 (1 byte) 1355 o options: 0x (0 bytes) 1357 o aad_array: 0x8501810a4100412540 (9 bytes) 1359 o external_aad: 0x498501810a4100412540 (10 bytes) 1361 o AAD: 0x8368456e63727970743040498501810a4100412540 (21 bytes) 1363 Note that the AAD consists of a fixed string of 11 bytes concatenated 1364 with the external_aad. 1366 6. OSCORE Header Compression 1368 The Concise Binary Object Representation (CBOR) [RFC7049] combines 1369 very small message sizes with extensibility. The CBOR Object Signing 1370 and Encryption (COSE) [RFC8152] uses CBOR to create compact encoding 1371 of signed and encrypted data. COSE is however constructed to support 1372 a large number of different stateless use cases, and is not fully 1373 optimized for use as a stateful security protocol, leading to a 1374 larger than necessary message expansion. In this section, we define 1375 a stateless header compression mechanism, simply removing redundant 1376 information from the COSE objects, which significantly reduces the 1377 per-packet overhead. The result of applying this mechanism to a COSE 1378 object is called the "compressed COSE object". 1380 The COSE_Encrypt0 object used in OSCORE is transported in the OSCORE 1381 option and in the Payload. The Payload contains the Ciphertext of 1382 the COSE object. The headers of the COSE object are compactly 1383 encoded as described in the next section. 1385 6.1. Encoding of the OSCORE Option Value 1387 The value of the OSCORE option SHALL contain the OSCORE flag bits, 1388 the Partial IV parameter, the 'kid context' parameter (length and 1389 value), and the 'kid' parameter as follows: 1391 0 1 2 3 4 5 6 7 <------------- n bytes --------------> 1392 +-+-+-+-+-+-+-+-+-------------------------------------- 1393 |0 0 0|h|k| n | Partial IV (if any) ... 1394 +-+-+-+-+-+-+-+-+-------------------------------------- 1396 <- 1 byte -> <----- s bytes ------> 1397 +------------+----------------------+------------------+ 1398 | s (if any) | kid context (if any) | kid (if any) ... | 1399 +------------+----------------------+------------------+ 1401 Figure 10: The OSCORE Option Value 1403 o The first byte, containing the OSCORE flag bits, encodes the 1404 following set of bits and the length of the Partial IV parameter: 1406 * The three least significant bits encode the Partial IV length 1407 n. If n = 0 then the Partial IV is not present in the 1408 compressed COSE object. The values n = 6 and n = 7 are 1409 reserved. 1411 * The fourth least significant bit is the 'kid' flag, k: it is 1412 set to 1 if the kid is present in the compressed COSE object. 1414 * The fifth least significant bit is the 'kid context' flag, h: 1415 it is set to 1 if the compressed COSE object contains a 'kid 1416 context (see Section 5.1). 1418 * The sixth to eighth least significant bits are reserved for 1419 future use. These bits SHALL be set to zero when not in use. 1420 According to this specification, if any of these bits are set 1421 to 1 the message is considered to be malformed and 1422 decompression fails as specified in item 2 of Section 8.2. 1424 The flag bits are registered in the OSCORE Flag Bits registry 1425 specified in Section 13.7. 1427 o The following n bytes encode the value of the Partial IV, if the 1428 Partial IV is present (n > 0). 1430 o The following 1 byte encode the length of the 'kid context' 1431 (Section 5.1) s, if the 'kid context' flag is set (h = 1). 1433 o The following s bytes encode the 'kid context', if the 'kid 1434 context' flag is set (h = 1). 1436 o The remaining bytes encode the value of the 'kid', if the 'kid' is 1437 present (k = 1). 1439 Note that the 'kid' MUST be the last field of the OSCORE option 1440 value, even in case reserved bits are used and additional fields are 1441 added to it. 1443 The length of the OSCORE option thus depends on the presence and 1444 length of Partial IV, 'kid context', 'kid', as specified in this 1445 section, and on the presence and length of the other parameters, as 1446 defined in the separate documents. 1448 6.2. Encoding of the OSCORE Payload 1450 The payload of the OSCORE message SHALL encode the ciphertext of the 1451 COSE object. 1453 6.3. Examples of Compressed COSE Objects 1455 This section covers a list of OSCORE Header Compression examples for 1456 requests and responses. The examples assume the COSE_Encrypt0 object 1457 is set (which means the CoAP message and cryptographic material is 1458 known). Note that the full CoAP unprotected message, as well as the 1459 full security context, is not reported in the examples, but only the 1460 input necessary to the compression mechanism, i.e. the COSE_Encrypt0 1461 object. The output is the compressed COSE object as defined in 1462 Section 6, divided into two parts, since the object is transported in 1463 two CoAP fields: OSCORE option and payload. 1465 1. Request with ciphertext = 0xaea0155667924dff8a24e4cb35b9, kid = 1466 0x25, and Partial IV = 0x05 1467 Before compression (24 bytes): 1469 [ 1470 h'', 1471 { 4:h'25', 6:h'05' }, 1472 h'aea0155667924dff8a24e4cb35b9', 1473 ] 1475 After compression (17 bytes): 1477 Flag byte: 0b00001001 = 0x09 (1 byte) 1479 Option Value: 0x090525 (3 bytes) 1481 Payload: 0xaea0155667924dff8a24e4cb35b9 (14 bytes) 1483 2. Request with ciphertext = 0xaea0155667924dff8a24e4cb35b9, kid = 1484 empty string, and Partial IV = 0x00 1486 Before compression (23 bytes): 1488 [ 1489 h'', 1490 { 4:h'', 6:h'00' }, 1491 h'aea0155667924dff8a24e4cb35b9', 1492 ] 1494 After compression (16 bytes): 1496 Flag byte: 0b00001001 = 0x09 (1 byte) 1498 Option Value: 0x0900 (2 bytes) 1500 Payload: 0xaea0155667924dff8a24e4cb35b9 (14 bytes) 1502 3. Request with ciphertext = 0xaea0155667924dff8a24e4cb35b9, kid = 1503 empty string, Partial IV = 0x05, and kid context = 0x44616c656b 1505 Before compression (30 bytes): 1507 [ 1508 h'', 1509 { 4:h'', 6:h'05', 8:h'44616c656b' }, 1510 h'aea0155667924dff8a24e4cb35b9', 1511 ] 1513 After compression (22 bytes): 1515 Flag byte: 0b00011001 = 0x19 (1 byte) 1517 Option Value: 0x19050544616c656b (8 bytes) 1519 Payload: 0xae a0155667924dff8a24e4cb35b9 (14 bytes) 1521 4. Response with ciphertext = 0xaea0155667924dff8a24e4cb35b9 and no 1522 Partial IV 1524 Before compression (18 bytes): 1526 [ 1527 h'', 1528 {}, 1529 h'aea0155667924dff8a24e4cb35b9', 1530 ] 1532 After compression (14 bytes): 1534 Flag byte: 0b00000000 = 0x00 (1 byte) 1536 Option Value: 0x (0 bytes) 1538 Payload: 0xaea0155667924dff8a24e4cb35b9 (14 bytes) 1540 5. Response with ciphertext = 0xaea0155667924dff8a24e4cb35b9 and 1541 Partial IV = 0x07 1543 Before compression (21 bytes): 1545 [ 1546 h'', 1547 { 6:h'07' }, 1548 h'aea0155667924dff8a24e4cb35b9', 1549 ] 1551 After compression (16 bytes): 1553 Flag byte: 0b00000001 = 0x01 (1 byte) 1555 Option Value: 0x0107 (2 bytes) 1557 Payload: 0xaea0155667924dff8a24e4cb35b9 (14 bytes) 1559 7. Message Binding, Sequence Numbers, Freshness, and Replay Protection 1561 7.1. Message Binding 1563 In order to prevent response delay and mismatch attacks 1564 [I-D.mattsson-core-coap-actuators] from on-path attackers and 1565 compromised intermediaries, OSCORE binds responses to the requests by 1566 including the 'kid' and Partial IV of the request in the AAD of the 1567 response. The server therefore needs to store the 'kid' and Partial 1568 IV of the request until all responses have been sent. 1570 7.2. Sequence Numbers 1572 An AEAD nonce MUST NOT be used more than once per AEAD key. The 1573 uniqueness of (key, nonce) pairs is shown in Appendix D.4, and in 1574 particular depends on a correct usage of Partial IVs (which encode 1575 the Sender Sequence Numbers, see Section 5). If messages are 1576 processed concurrently, the operation of reading and increasing the 1577 Sender Sequence Number MUST be atomic. 1579 7.2.1. Maximum Sequence Number 1581 The maximum Sender Sequence Number is algorithm dependent (see 1582 Section 12), and SHALL be less than 2^40. If the Sender Sequence 1583 Number exceeds the maximum, the endpoint MUST NOT process any more 1584 messages with the given Sender Context. If necessary, the endpoint 1585 SHOULD acquire a new security context before this happens. The 1586 latter is out of scope of this document. 1588 7.3. Freshness 1590 For requests, OSCORE provides only the guarantee that the request is 1591 not older than the security context. For applications having 1592 stronger demands on request freshness (e.g., control of actuators), 1593 OSCORE needs to be augmented with mechanisms providing freshness, for 1594 example as specified in [I-D.ietf-core-echo-request-tag]. 1596 Assuming an honest server (see Appendix D), the message binding 1597 guarantees that a response is not older than its request. For 1598 responses that are not notifications (i.e. when there is a single 1599 response to a request), this gives absolute freshness. For 1600 notifications, the absolute freshness gets weaker with time, and it 1601 is RECOMMENDED that the client regularly re-register the observation. 1602 Note that the message binding does not guarantee that misbehaving 1603 server created the response before receiving the request, i.e. it 1604 does not verify server aliveness. 1606 For requests and notifications, OSCORE also provides relative 1607 freshness in the sense that the received Partial IV allows a 1608 recipient to determine the relative order of requests or responses. 1610 7.4. Replay Protection 1612 In order to protect from replay of requests, the server's Recipient 1613 Context includes a Replay Window. A server SHALL verify that a 1614 Partial IV = Sender Sequence Number received in the COSE object has 1615 not been received before. If this verification fails, the server 1616 SHALL stop processing the message, and MAY optionally respond with a 1617 4.01 (Unauthorized) error message. Also, the server MAY set an Outer 1618 Max-Age option with value zero, to inform any intermediary that the 1619 response is not to be cached. The diagnostic payload MAY contain the 1620 "Replay detected" string. The size and type of the Replay Window 1621 depends on the use case and the protocol with which the OSCORE 1622 message is transported. In case of reliable and ordered transport 1623 from endpoint to endpoint, e.g. TCP, the server MAY just store the 1624 last received Partial IV and require that newly received Partial IVs 1625 equals the last received Partial IV + 1. However, in case of mixed 1626 reliable and unreliable transports and where messages may be lost, 1627 such a replay mechanism may be too restrictive and the default replay 1628 window be more suitable (see Section 3.2.2). 1630 Responses (with or without Partial IV) are protected against replay 1631 as they are bound to the request and the fact that only a single 1632 response is accepted. Note that the Partial IV is not used for 1633 replay protection in this case. 1635 The operation of validating the Partial IV and updating the replay 1636 protection MUST be atomic. 1638 7.4.1. Replay Protection of Notifications 1640 The following applies additionally when Observe is supported. 1642 The Notification Number is initialized to the Partial IV of the first 1643 successfully verified notification in response to the registration 1644 request. A client MUST only accept at most one Observe notifications 1645 without Partial IV, and treat it as the oldest notification received. 1646 A client receiving a notification containing a Partial IV SHALL 1647 compare the Partial IV with the Notification Number associated to 1648 that Observe registration. The client MUST stop processing 1649 notifications with a Partial IV which has been previously received. 1650 Applications MAY decide that a client only processes notifications 1651 which have greater Partial IV than the Notification Number. 1653 If the verification of the response succeeds, and the received 1654 Partial IV was greater than the Notification Number then the client 1655 SHALL overwrite the corresponding Notification Number with the 1656 received Partial IV. 1658 7.5. Losing Part of the Context State 1660 To prevent reuse of an AEAD nonce with the same AEAD key, or from 1661 accepting replayed messages, an endpoint needs to handle the 1662 situation of losing rapidly changing parts of the context, such as 1663 the Sender Sequence Number, and Replay Window. These are typically 1664 stored in RAM and therefore lost in the case of e.g. an unplanned 1665 reboot. There are different alternatives to recover, for example: 1667 1. The endpoints can reuse an existing Security Context after 1668 updating the mutable parts of the security context (Sender 1669 Sequence Number, and Replay Window). This requires that the 1670 mutable parts of the security context are available throughout 1671 the lifetime of the device, or that the device can establish safe 1672 security context after loss of mutable security context data. 1673 Examples is given based on careful use of non-volatile memory, 1674 see Appendix B.1.1, and additionally the use of the Echo option, 1675 see Appendix B.1.2. If an endpoint makes use of a partial 1676 security context stored in non-volatile memory, it MUST NOT reuse 1677 a previous Sender Sequence Number and MUST NOT accept previously 1678 received messages. 1680 2. The endpoints can reuse an existing shared Master Secret and 1681 derive new Sender and Recipient Contexts, see Appendix B.2 for an 1682 example. This typically requires a good source of randomness. 1684 3. The endpoints can use a trusted-third party assisted key 1685 establishment protocol such as [I-D.ietf-ace-oscore-profile]. 1686 This requires the execution of three-party protocol and may 1687 require a good source of randomness. 1689 4. The endpoints can run a key exchange protocol providing forward 1690 secrecy resulting in a fresh Master Secret, from which an 1691 entirely new Security Context is derived. This requires a good 1692 source of randomness, and additionally, the transmission and 1693 processing of the protocol may have a non-negligible cost, e.g. 1694 in terms of power consumption. 1696 The endpoints need to be configured with information about which 1697 method is used. The choice of method may depend on capabilities of 1698 the devices deployed and the solution architecture. Using a key 1699 exchange protocol is necessary for deployments that require forward 1700 secrecy. 1702 8. Processing 1704 This section describes the OSCORE message processing. Additional 1705 processing for Observe or Block-wise are described in subsections. 1707 Note that, analogously to [RFC7252] where the Token and source/ 1708 destination pair are used to match a response with a request, both 1709 endpoints MUST keep the association (Token, {Security Context, 1710 Partial IV of the request}), in order to be able to find the Security 1711 Context and compute the AAD to protect or verify the response. The 1712 association MAY be forgotten after it has been used to successfully 1713 protect or verify the response, with the exception of Observe 1714 processing, where the association MUST be kept as long as the 1715 Observation is active. 1717 The processing of the Sender Sequence Number follows the procedure 1718 described in Section 3 of [I-D.mcgrew-iv-gen]. 1720 8.1. Protecting the Request 1722 Given a CoAP request, the client SHALL perform the following steps to 1723 create an OSCORE request: 1725 1. Retrieve the Sender Context associated with the target resource. 1727 2. Compose the Additional Authenticated Data and the plaintext, as 1728 described in Sections 5.3 and 5.4. 1730 3. Encode the Partial IV (Sender Sequence Number in network byte 1731 order) and increment the Sender Sequence Number by one. Compute 1732 the AEAD nonce from the Sender ID, Common IV, and Partial IV as 1733 described in Section 5.2. 1735 4. Encrypt the COSE object using the Sender Key. Compress the COSE 1736 Object as specified in Section 6. 1738 5. Format the OSCORE message according to Section 4. The OSCORE 1739 option is added (see Section 4.1.2). 1741 8.2. Verifying the Request 1743 A server receiving a request containing the OSCORE option SHALL 1744 perform the following steps: 1746 1. Discard Code and all class E options (marked in Figure 5 with 'x' 1747 in column E) present in the received message. For example, an 1748 If-Match Outer option is discarded, but an Uri-Host Outer option 1749 is not discarded. 1751 2. Decompress the COSE Object (Section 6) and retrieve the Recipient 1752 Context associated with the Recipient ID in the 'kid' parameter, 1753 additionally using the 'kid context', if present. If either the 1754 decompression or the COSE message fails to decode, or the server 1755 fails to retrieve a Recipient Context with Recipient ID 1756 corresponding to the 'kid' parameter received, then the server 1757 SHALL stop processing the request. 1759 * If either the decompression or the COSE message fails to 1760 decode, the server MAY respond with a 4.02 (Bad Option) error 1761 message. The server MAY set an Outer Max-Age option with 1762 value zero. The diagnostic payload MAY contain the string 1763 "Failed to decode COSE". 1765 * If the server fails to retrieve a Recipient Context with 1766 Recipient ID corresponding to the 'kid' parameter received, 1767 the server MAY respond with a 4.01 (Unauthorized) error 1768 message. The server MAY set an Outer Max-Age option with 1769 value zero. The diagnostic payload MAY contain the string 1770 "Security context not found". 1772 3. Verify that the 'Partial IV' has not been received before using 1773 the Replay Window, as described in Section 7.4. 1775 4. Compose the Additional Authenticated Data, as described in 1776 Section 5.4. 1778 5. Compute the AEAD nonce from the Recipient ID, Common IV, and the 1779 'Partial IV' parameter, received in the COSE Object. 1781 6. Decrypt the COSE object using the Recipient Key, as per [RFC8152] 1782 Section 5.3. (The decrypt operation includes the verification of 1783 the integrity.) 1785 * If decryption fails, the server MUST stop processing the 1786 request and MAY respond with a 4.00 (Bad Request) error 1787 message. The server MAY set an Outer Max-Age option with 1788 value zero. The diagnostic payload MAY contain the 1789 "Decryption failed" string. 1791 * If decryption succeeds, update the Replay Window, as described 1792 in Section 7. 1794 7. Add decrypted Code, options, and payload to the decrypted 1795 request. The OSCORE option is removed. 1797 8. The decrypted CoAP request is processed according to [RFC7252]. 1799 8.2.1. Supporting Block-wise 1801 If Block-wise is supported, insert the following step before any 1802 other: 1804 A. If Block-wise is present in the request, then process the Outer 1805 Block options according to [RFC7959], until all blocks of the request 1806 have been received (see Section 4.1.3.4). 1808 8.3. Protecting the Response 1810 If a CoAP response is generated in response to an OSCORE request, the 1811 server SHALL perform the following steps to create an OSCORE 1812 response. Note that CoAP error responses derived from CoAP 1813 processing (step 8 in Section 8.2) are protected, as well as 1814 successful CoAP responses, while the OSCORE errors (steps 2, 3, and 6 1815 in Section 8.2) do not follow the processing below, but are sent as 1816 simple CoAP responses, without OSCORE processing. 1818 1. Retrieve the Sender Context in the Security Context associated 1819 with the Token. 1821 2. Compose the Additional Authenticated Data and the plaintext, as 1822 described in Sections 5.3 and 5.4. 1824 3. Compute the AEAD nonce as described in Section 5.2: 1826 * Either use the AEAD nonce from the request, or 1828 * Encode the Partial IV (Sender Sequence Number in network byte 1829 order) and increment the Sender Sequence Number by one. 1830 Compute the AEAD nonce from the Sender ID, Common IV, and 1831 Partial IV. 1833 4. Encrypt the COSE object using the Sender Key. Compress the COSE 1834 Object as specified in Section 6. If the AEAD nonce was 1835 constructed from a new Partial IV, this Partial IV MUST be 1836 included in the message. If the AEAD nonce from the request was 1837 used, the Partial IV MUST NOT be included in the message. 1839 5. Format the OSCORE message according to Section 4. The OSCORE 1840 option is added (see Section 4.1.2). 1842 8.3.1. Supporting Observe 1844 If Observe is supported, insert the following step between step 2 and 1845 3 of Section 8.3: 1847 A. If the response is an observe notification: 1849 o If the response is the first notification: 1851 * compute the AEAD nonce as described in Section 5.2: 1853 + Either use the AEAD nonce from the request, or 1855 + Encode the Partial IV (Sender Sequence Number in network 1856 byte order) and increment the Sender Sequence Number by one. 1857 Compute the AEAD nonce from the Sender ID, Common IV, and 1858 Partial IV. 1860 Then go to 4. 1862 o If the response is not the first notification: 1864 * encode the Partial IV (Sender Sequence Number in network byte 1865 order) and increment the Sender Sequence Number by one. 1866 Compute the AEAD nonce from the Sender ID, Common IV, and 1867 Partial IV, then go to 4. 1869 8.4. Verifying the Response 1871 A client receiving a response containing the OSCORE option SHALL 1872 perform the following steps: 1874 1. Discard Code and all class E options (marked in Figure 5 with 'x' 1875 in column E) present in the received message. For example, ETag 1876 Outer option is discarded, as well as Max-Age Outer option. 1878 2. Retrieve the Recipient Context in the Security Context associated 1879 with the Token. Decompress the COSE Object (Section 6). If 1880 either the decompression or the COSE message fails to decode, 1881 then go to 8. 1883 3. Compose the Additional Authenticated Data, as described in 1884 Section 5.4. 1886 4. Compute the AEAD nonce 1888 * If the Partial IV is not present in the response, the AEAD 1889 nonce from the request is used. 1891 * If the Partial IV is present in the response, compute the AEAD 1892 nonce from the Recipient ID, Common IV, and the 'Partial IV' 1893 parameter, received in the COSE Object. 1895 5. Decrypt the COSE object using the Recipient Key, as per [RFC8152] 1896 Section 5.3. (The decrypt operation includes the verification of 1897 the integrity.) If decryption fails, then go to 8. 1899 6. Add decrypted Code, options and payload to the decrypted request. 1900 The OSCORE option is removed. 1902 7. The decrypted CoAP response is processed according to [RFC7252]. 1904 8. In case any of the previous erroneous conditions apply: the 1905 client SHALL stop processing the response. 1907 8.4.1. Supporting Block-wise 1909 If Block-wise is supported, insert the following step before any 1910 other: 1912 A. If Block-wise is present in the request, then process the Outer 1913 Block options according to [RFC7959], until all blocks of the request 1914 have been received (see Section 4.1.3.4). 1916 8.4.2. Supporting Observe 1918 If Observe is supported: 1920 Insert the following step between step 5 and step 6: 1922 A. If the request was an Observe registration, then: 1924 o If the Partial IV is not present in the response, and Inner 1925 Observe is present, and the AEAD nonce from the request was 1926 already used once, then go to 8. 1928 o If the Partial IV is present in the response and Inner Observe is 1929 present, then follow the processing described in Section 4.1.3.5.2 1930 and Section 7.4.1, then: 1932 * initialize the Notification Number (if first successfully 1933 verified notification), or 1935 * overwrite the Notification Number (if the received Partial IV 1936 was greater than the Notification Number). 1938 Replace step 8 of Section 8.4 with: 1940 B. In case any of the previous erroneous conditions apply: the 1941 client SHALL stop processing the response. An error condition 1942 occurring while processing a response to an observation request does 1943 not cancel the observation. A client MUST NOT react to failure by 1944 re-registering the observation immediately. 1946 9. Web Linking 1948 The use of OSCORE MAY be indicated by a target attribute "osc" in a 1949 web link [RFC8288] to a resource, e.g. using a link-format document 1950 [RFC6690] if the resource is accessible over CoAP. 1952 The "osc" attribute is a hint indicating that the destination of that 1953 link is only accessible using OSCORE, and unprotected access to it is 1954 not supported. Note that this is simply a hint, it does not include 1955 any security context material or any other information required to 1956 run OSCORE. 1958 A value MUST NOT be given for the "osc" attribute; any present value 1959 MUST be ignored by parsers. The "osc" attribute MUST NOT appear more 1960 than once in a given link-value; occurrences after the first MUST be 1961 ignored by parsers. 1963 The example in Figure 11 shows a use of the "osc" attribute: the 1964 client does resource discovery on a server, and gets back a list of 1965 resources, one of which includes the "osc" attribute indicating that 1966 the resource is protected with OSCORE. The link-format notation (see 1967 Section 5 of [RFC6690]) is used. 1969 REQ: GET /.well-known/core 1971 RES: 2.05 Content 1972 ;osc, 1973 ;if="sensor" 1975 Figure 11: The web link 1977 10. CoAP-to-CoAP Forwarding Proxy 1979 CoAP is designed for proxy operations (see Section 5.7 of [RFC7252]). 1981 OSCORE is designed to work with OSCORE-unaware CoAP proxies. 1982 Security requirements for forwarding are listed in Section 2.2.1 of 1983 [I-D.hartke-core-e2e-security-reqs]. Proxy processing of the (Outer) 1984 Proxy-Uri option works as defined in [RFC7252]. Proxy processing of 1985 the (Outer) Block options works as defined in [RFC7959]. 1987 However, not all CoAP proxy operations are useful: 1989 o Since a CoAP response is only applicable to the original CoAP 1990 request, caching is in general not useful. In support of existing 1991 proxies, OSCORE uses the outer Max-Age option, see 1992 Section 4.1.3.1. 1994 o Proxy processing of the (Outer) Observe option as defined in 1995 [RFC7641] is specified in Section 4.1.3.5. 1997 Optionally, a CoAP proxy MAY detect OSCORE and act accordingly. An 1998 OSCORE-aware CoAP proxy: 2000 o SHALL bypass caching for the request if the OSCORE option is 2001 present 2003 o SHOULD avoid caching responses to requests with an OSCORE option 2005 In the case of Observe (see Section 4.1.3.5) the OSCORE-aware CoAP 2006 proxy: 2008 o SHALL NOT initiate an Observe registration 2010 o MAY verify the order of notifications using Partial IV rather than 2011 the Observe option 2013 11. HTTP Operations 2015 The CoAP request/response model may be mapped to HTTP and vice versa 2016 as described in Section 10 of [RFC7252]. The HTTP-CoAP mapping is 2017 further detailed in [RFC8075]. This section defines the components 2018 needed to map and transport OSCORE messages over HTTP hops. By 2019 mapping between HTTP and CoAP and by using cross-protocol proxies 2020 OSCORE may be used end-to-end between e.g. an HTTP client and a CoAP 2021 server. Examples are provided at the end of the section. 2023 11.1. The HTTP OSCORE Header Field 2025 The HTTP OSCORE Header Field (see Section 13.4) is used for carrying 2026 the content of the CoAP OSCORE option when transporting OSCORE 2027 messages over HTTP hops. 2029 The HTTP OSCORE header field is only used in POST requests and 200 2030 (OK) responses. When used, the HTTP header field Content-Type is set 2031 to 'application/oscore' (see Section 13.5) indicating that the HTTP 2032 body of this message contains the OSCORE payload (see Section 6.2). 2033 No additional semantics is provided by other message fields. 2035 Using the Augmented Backus-Naur Form (ABNF) notation of [RFC5234], 2036 including the following core ABNF syntax rules defined by that 2037 specification: ALPHA (letters) and DIGIT (decimal digits), the HTTP 2038 OSCORE header field value is as follows. 2040 base64url-char = ALPHA / DIGIT / "-" / "_" 2042 OSCORE = 2*base64url-char 2044 The HTTP OSCORE header field is not appropriate to list in the 2045 Connection header field (see Section 6.1 of [RFC7230]) since it is 2046 not hop-by-hop. OSCORE messages are generally not useful when served 2047 from cache (i.e., they will generally be marked Cache-Control: no- 2048 cache) and so interaction with Vary is not relevant (Section 7.1.4 of 2049 [RFC7231]). Since the HTTP OSCORE header field is critical for 2050 message processing, moving it from headers to trailers renders the 2051 message unusable in case trailers are ignored (see Section 4.1 of 2052 [RFC7230]). 2054 Intermediaries are in general not allowed to insert, delete, or 2055 modify the OSCORE header. Changes to the HTTP OSCORE header field 2056 will in general violate the integrity of the OSCORE message resulting 2057 in an error. For the same reason the HTTP OSCORE header field is in 2058 general not preserved across redirects. 2060 Since redirects are not defined in the mappings between HTTP and CoAP 2061 [RFC8075][RFC7252], a number of conditions need to be fulfilled for 2062 redirects to work. For CoAP client to HTTP server, such conditions 2063 include: 2065 o the CoAP-to-HTTP proxy follows the redirect, instead of the CoAP 2066 client as in the HTTP case 2068 o the CoAP-to-HTTP proxy copies the HTTP OSCORE header field and 2069 body to the new request 2071 o the target of the redirect has the necessary OSCORE security 2072 context required to decrypt and verify the message 2074 Since OSCORE requires HTTP body to be preserved across redirects, the 2075 HTTP server is RECOMMENDED to reply with 307 or 308 instead of 301 or 2076 302. 2078 For the case of HTTP client to CoAP server, although redirect is not 2079 defined for CoAP servers [RFC7252], an HTTP client receiving a 2080 redirect should generate a new OSCORE request for the server it was 2081 redirected to. 2083 11.2. CoAP-to-HTTP Mapping 2085 Section 10.1 of [RFC7252] describes the fundamentals of the CoAP-to- 2086 HTTP cross-protocol mapping process. The additional rules for OSCORE 2087 messages are: 2089 o The HTTP OSCORE header field value is set to 2091 * AA if the CoAP OSCORE option is empty, otherwise 2093 * the value of the CoAP OSCORE option (Section 6.1) in base64url 2094 (Section 5 of [RFC4648]) encoding without padding. 2095 Implementation notes for this encoding are given in Appendix C 2096 of [RFC7515]. 2098 o The HTTP Content-Type is set to 'application/oscore' (see 2099 Section 13.5), independent of CoAP Content-Format. 2101 11.3. HTTP-to-CoAP Mapping 2103 Section 10.2 of [RFC7252] and [RFC8075] specify the behavior of an 2104 HTTP-to-CoAP proxy. The additional rules for HTTP messages with the 2105 OSCORE header field are: 2107 o The CoAP OSCORE option is set as follows: 2109 * empty if the value of the HTTP OSCORE header field is a single 2110 zero byte (0x00) represented by AA, otherwise 2112 * the value of the HTTP OSCORE header field decoded from 2113 base64url (Section 5 of [RFC4648]) without padding. 2114 Implementation notes for this encoding are given in Appendix C 2115 of [RFC7515]. 2117 o The CoAP Content-Format option is omitted, the content format for 2118 OSCORE (Section 13.6) MUST NOT be used. 2120 11.4. HTTP Endpoints 2122 Restricted to subsets of HTTP and CoAP supporting a bijective 2123 mapping, OSCORE can be originated or terminated in HTTP endpoints. 2125 The sending HTTP endpoint uses [RFC8075] to translate the HTTP 2126 message into a CoAP message. The CoAP message is then processed with 2127 OSCORE as defined in this document. The OSCORE message is then 2128 mapped to HTTP as described in Section 11.2 and sent in compliance 2129 with the rules in Section 11.1. 2131 The receiving HTTP endpoint maps the HTTP message to a CoAP message 2132 using [RFC8075] and Section 11.3. The resulting OSCORE message is 2133 processed as defined in this document. If successful, the plaintext 2134 CoAP message is translated to HTTP for normal processing in the 2135 endpoint. 2137 11.5. Example: HTTP Client and CoAP Server 2139 This section is giving an example of how a request and a response 2140 between an HTTP client and a CoAP server could look like. The 2141 example is not a test vector but intended as an illustration of how 2142 the message fields are translated in the different steps. 2144 Mapping and notation here is based on "Simple Form" (Section 5.4.1 of 2145 [RFC8075]). 2147 [HTTP request -- Before client object security processing] 2149 GET http://proxy.url/hc/?target_uri=coap://server.url/orders 2150 HTTP/1.1 2152 [HTTP request -- HTTP Client to Proxy] 2154 POST http://proxy.url/hc/?target_uri=coap://server.url/ HTTP/1.1 2155 Content-Type: application/oscore 2156 OSCORE: CSU 2157 Body: 09 07 01 13 61 f7 0f d2 97 b1 [binary] 2159 [CoAP request -- Proxy to CoAP Server] 2161 POST coap://server.url/ 2162 OSCORE: 09 25 2163 Payload: 09 07 01 13 61 f7 0f d2 97 b1 [binary] 2165 [CoAP request -- After server object security processing] 2167 GET coap://server.url/orders 2169 [CoAP response -- Before server object security processing] 2171 2.05 Content 2172 Content-Format: 0 2173 Payload: Exterminate! Exterminate! 2175 [CoAP response -- CoAP Server to Proxy] 2177 2.04 Changed 2178 OSCORE: [empty] 2179 Payload: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] 2181 [HTTP response -- Proxy to HTTP Client] 2183 HTTP/1.1 200 OK 2184 Content-Type: application/oscore 2185 OSCORE: AA 2186 Body: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] 2188 [HTTP response -- After client object security processing] 2190 HTTP/1.1 200 OK 2191 Content-Type: text/plain 2192 Body: Exterminate! Exterminate! 2194 Note that the HTTP Status Code 200 in the next-to-last message is the 2195 mapping of CoAP Code 2.04 (Changed), whereas the HTTP Status Code 200 2196 in the last message is the mapping of the CoAP Code 2.05 (Content), 2197 which was encrypted within the compressed COSE object carried in the 2198 Body of the HTTP response. 2200 11.6. Example: CoAP Client and HTTP Server 2202 This section is giving an example of how a request and a response 2203 between a CoAP client and an HTTP server could look like. The 2204 example is not a test vector but intended as an illustration of how 2205 the message fields are translated in the different steps 2207 [CoAP request -- Before client object security processing] 2209 GET coap://proxy.url/ 2210 Proxy-Uri=http://server.url/orders 2212 [CoAP request -- CoAP Client to Proxy] 2214 POST coap://proxy.url/ 2215 Proxy-Uri=http://server.url/ 2216 OSCORE: 09 25 2217 Payload: 09 07 01 13 61 f7 0f d2 97 b1 [binary] 2219 [HTTP request -- Proxy to HTTP Server] 2221 POST http://server.url/ HTTP/1.1 2222 Content-Type: application/oscore 2223 OSCORE: CSU 2224 Body: 09 07 01 13 61 f7 0f d2 97 b1 [binary] 2226 [HTTP request -- After server object security processing] 2228 GET http://server.url/orders HTTP/1.1 2230 [HTTP response -- Before server object security processing] 2232 HTTP/1.1 200 OK 2233 Content-Type: text/plain 2234 Body: Exterminate! Exterminate! 2236 [HTTP response -- HTTP Server to Proxy] 2238 HTTP/1.1 200 OK 2239 Content-Type: application/oscore 2240 OSCORE: AA 2241 Body: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] 2243 [CoAP response -- Proxy to CoAP Client] 2245 2.04 Changed 2246 OSCORE: [empty] 2247 Payload: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] 2249 [CoAP response -- After client object security processing] 2251 2.05 Content 2252 Content-Format: 0 2253 Payload: Exterminate! Exterminate! 2255 Note that the HTTP Code 2.04 (Changed) in the next-to-last message is 2256 the mapping of HTTP Status Code 200, whereas the CoAP Code 2.05 2257 (Content) in the last message is the value that was encrypted within 2258 the compressed COSE object carried in the Body of the HTTP response. 2260 12. Security Considerations 2262 An overview of the security properties is given in Appendix D. 2264 12.1. End-to-end Protection 2266 In scenarios with intermediary nodes such as proxies or gateways, 2267 transport layer security such as (D)TLS only protects data hop-by- 2268 hop. As a consequence, the intermediary nodes can read and modify 2269 any information. The trust model where all intermediary nodes are 2270 considered trustworthy is problematic, not only from a privacy 2271 perspective, but also from a security perspective, as the 2272 intermediaries are free to delete resources on sensors and falsify 2273 commands to actuators (such as "unlock door", "start fire alarm", 2274 "raise bridge"). Even in the rare cases where all the owners of the 2275 intermediary nodes are fully trusted, attacks and data breaches make 2276 such an architecture brittle. 2278 (D)TLS protects hop-by-hop the entire message. OSCORE protects end- 2279 to-end all information that is not required for proxy operations (see 2280 Section 4). (D)TLS and OSCORE can be combined, thereby enabling end- 2281 to-end security of the message payload, in combination with hop-by- 2282 hop protection of the entire message, during transport between end- 2283 point and intermediary node. In particular when OSCORE is used with 2284 HTTP, the additional TLS protection of HTTP hops is RECOMMENDED, e.g. 2285 between an HTTP endpoint and a proxy translating between HTTP and 2286 CoAP. 2288 Applications need to consider that certain message fields and 2289 messages types are not protected end-to-end and may be spoofed or 2290 manipulated. The consequences of unprotected message fields are 2291 analyzed in Appendix D.5. 2293 12.2. Security Context Establishment 2295 The use of COSE_Encrypt0 and AEAD to protect messages as specified in 2296 this document requires an established security context. The method 2297 to establish the security context described in Section 3.2 is based 2298 on a common Master Secret and unique Sender IDs. The necessary input 2299 parameters may be pre-established or obtained using a key 2300 establishment protocol augmented with establishment of Sender/ 2301 Recipient ID, such as a key exchange protocol or the OSCORE profile 2302 of the ACE framework [I-D.ietf-ace-oscore-profile]. Such a procedure 2303 must ensure that the requirements of the security context parameters 2304 for the intended use are complied with (see Section 3.3) and also in 2305 error situations. While recipient IDs are allowed to coincide 2306 between different security contexts (see Section 3.3), this may cause 2307 a server to process multiple verifications before finding the right 2308 security context or rejecting a message. Considerations for 2309 deploying OSCORE with a fixed Master Secret are given in Appendix B. 2311 12.3. Master Secret 2313 OSCORE uses HKDF [RFC5869] and the established input parameters to 2314 derive the security context. The required properties of the security 2315 context parameters are discussed in Section 3.3, in this section we 2316 focus on the Master Secret. HKDF denotes in this specification the 2317 composition of the expand and extract functions as defined in 2318 [RFC5869] and the Master Secret is used as Input Key Material (IKM). 2320 Informally, HKDF takes as source an IKM containing some good amount 2321 of randomness but not necessarily distributed uniformly (or for which 2322 an attacker has some partial knowledge) and derive from it one or 2323 more cryptographically strong secret keys [RFC5869]. 2325 Therefore, the main requirement for the OSCORE Master Secret, in 2326 addition to being secret, is that it is has a good amount of 2327 randomness. The selected key establishment schemes must ensure that 2328 the necessary properties for the Master Secret are fulfilled. For 2329 pre-shared key deployments and key transport solutions such as 2330 [I-D.ietf-ace-oscore-profile], the Master Secret can be generated 2331 offline using a good random number generator. Randomness 2332 requirements for security are described in [RFC4086]. 2334 12.4. Replay Protection 2336 Replay attacks need to be considered in different parts of the 2337 implementation. Most AEAD algorithms require a unique nonce for each 2338 message, for which the sender sequence numbers in the COSE message 2339 field 'Partial IV' is used. If the recipient accepts any sequence 2340 number larger than the one previously received, then the problem of 2341 sequence number synchronization is avoided. With reliable transport, 2342 it may be defined that only messages with sequence number which are 2343 equal to previous sequence number + 1 are accepted. An adversary may 2344 try to induce a device reboot for the purpose of replaying a message 2345 (see Section 7.5). 2347 Note that sharing a security context between servers may open up for 2348 replay attacks, for example if the replay windows are not 2349 synchronized. 2351 12.5. Client Aliveness 2353 A verified OSCORE request enables the server to verify the identity 2354 of the entity who generated the message. However, it does not verify 2355 that the client is currently involved in the communication, since the 2356 message may be a delayed delivery of a previously generated request 2357 which now reaches the server. To verify the aliveness of the client 2358 the server may use the Echo option in the response to a request from 2359 the client (see [I-D.ietf-core-echo-request-tag]). 2361 12.6. Cryptographic Considerations 2363 The maximum sender sequence number is dependent on the AEAD 2364 algorithm. The maximum sender sequence number is 2^40 - 1, or any 2365 algorithm specific lower limit, after which a new security context 2366 must be generated. The mechanism to build the AEAD nonce 2367 (Section 5.2) assumes that the nonce is at least 56 bits, and the 2368 Partial IV is at most 40 bits. The mandatory-to-implement AEAD 2369 algorithm AES-CCM-16-64-128 is selected for compatibility with CCM*. 2370 AEAD algorithms that require unpredictable nonces are not supported. 2372 In order to prevent cryptanalysis when the same plaintext is 2373 repeatedly encrypted by many different users with distinct AEAD keys, 2374 the AEAD nonce is formed by mixing the sequence number with a secret 2375 per-context initialization vector (Common IV) derived along with the 2376 keys (see Section 3.1 of [RFC8152]), and by using a Master Salt in 2377 the key derivation (see [MF00] for an overview). The Master Secret, 2378 Sender Key, Recipient Key, and Common IV must be secret, the rest of 2379 the parameters may be public. The Master Secret must have a good 2380 amount of randomness (see Section 12.3). 2382 The ID Context, Sender ID, and Partial IV are always at least 2383 implicitly integrity protected, as manipulation leads to the wrong 2384 nonce or key being used and therefore results in decryption failure. 2386 12.7. Message Segmentation 2388 The Inner Block options enable the sender to split large messages 2389 into OSCORE-protected blocks such that the receiving endpoint can 2390 verify blocks before having received the complete message. The Outer 2391 Block options allow for arbitrary proxy fragmentation operations that 2392 cannot be verified by the endpoints, but can by policy be restricted 2393 in size since the Inner Block options allow for secure fragmentation 2394 of very large messages. A maximum message size (above which the 2395 sending endpoint fragments the message and the receiving endpoint 2396 discards the message, if complying to the policy) may be obtained as 2397 part of normal resource discovery. 2399 12.8. Privacy Considerations 2401 Privacy threats executed through intermediary nodes are considerably 2402 reduced by means of OSCORE. End-to-end integrity protection and 2403 encryption of the message payload and all options that are not used 2404 for proxy operations, provide mitigation against attacks on sensor 2405 and actuator communication, which may have a direct impact on the 2406 personal sphere. 2408 The unprotected options (Figure 5) may reveal privacy sensitive 2409 information, see Appendix D.5. CoAP headers sent in plaintext allow, 2410 for example, matching of CON and ACK (CoAP Message Identifier), 2411 matching of request and responses (Token) and traffic analysis. 2412 OSCORE does not provide protection for HTTP header fields which are 2413 not both CoAP-mappable and class E. The HTTP message fields which 2414 are visible to on-path entity are only used for the purpose of 2415 transporting the OSCORE message, whereas the application layer 2416 message is encoded in CoAP and encrypted. 2418 COSE message fields, i.e. the OSCORE option, may reveal information 2419 about the communicating endpoints. E.g. 'kid' and 'kid context', 2420 which are intended to help the server find the right context, may 2421 reveal information about the client. Tracking 'kid' and 'kid 2422 context' to one server may be used for correlating requests from one 2423 client. 2425 Unprotected error messages reveal information about the security 2426 state in the communication between the endpoints. Unprotected 2427 signaling messages reveal information about the reliable transport 2428 used on a leg of the path. Using the mechanisms described in 2429 Section 7.5 may reveal when a device goes through a reboot. This can 2430 be mitigated by the device storing the precise state of sender 2431 sequence number and replay window on a clean shutdown. 2433 The length of message fields can reveal information about the 2434 message. Applications may use a padding scheme to protect against 2435 traffic analysis. 2437 13. IANA Considerations 2439 Note to RFC Editor: Please replace all occurrences of "[[this 2440 document]]" with the RFC number of this specification. 2442 Note to IANA: Please note all occurrences of "TBD1" in this 2443 specification should be assigned the same number. 2445 13.1. COSE Header Parameters Registry 2447 The 'kid context' parameter is added to the "COSE Header Parameters 2448 Registry": 2450 o Name: kid context 2452 o Label: TBD2 2454 o Value Type: bstr 2456 o Value Registry: 2458 o Description: Identifies the context for 'kid' 2460 o Reference: Section 5.1 of this document 2462 Note to IANA: Label assignment in (Integer value between 1 and 255) 2463 is requested. (RFC Editor: Delete this note after IANA assignment) 2465 13.2. CoAP Option Numbers Registry 2467 The OSCORE option is added to the CoAP Option Numbers registry: 2469 +--------+-----------------+-------------------+ 2470 | Number | Name | Reference | 2471 +--------+-----------------+-------------------+ 2472 | TBD1 | OSCORE | [[this document]] | 2473 +--------+-----------------+-------------------+ 2475 Note to IANA: Label assignment in (Integer value between 0 and 12) is 2476 requested. We also request Expert review if possible, to make sure a 2477 correct number for the option is selected (RFC Editor: Delete this 2478 note after IANA assignment) 2480 Furthermore, the following existing entries in the CoAP Option 2481 Numbers registry are updated with a reference to the document 2482 specifying OSCORE processing of that option: 2484 +--------+-----------------+---------------------------------------+ 2485 | Number | Name | Reference | 2486 +--------+-----------------+---------------------------------------+ 2487 | 1 | If-Match | [RFC7252] [[this document]] | 2488 | 3 | Uri-Host | [RFC7252] [[this document]] | 2489 | 4 | ETag | [RFC7252] [[this document]] | 2490 | 5 | If-None-Match | [RFC7252] [[this document]] | 2491 | 6 | Observe | [RFC7641] [[this document]] | 2492 | 7 | Uri-Port | [RFC7252] [[this document]] | 2493 | 8 | Location-Path | [RFC7252] [[this document]] | 2494 | 11 | Uri-Path | [RFC7252] [[this document]] | 2495 | 12 | Content-Format | [RFC7252] [[this document]] | 2496 | 14 | Max-Age | [RFC7252] [[this document]] | 2497 | 15 | Uri-Query | [RFC7252] [[this document]] | 2498 | 17 | Accept | [RFC7252] [[this document]] | 2499 | 20 | Location-Query | [RFC7252] [[this document]] | 2500 | 23 | Block2 | [RFC7959] [RFC8323] [[this document]] | 2501 | 27 | Block1 | [RFC7959] [RFC8323] [[this document]] | 2502 | 28 | Size2 | [RFC7959] [[this document]] | 2503 | 35 | Proxy-Uri | [RFC7252] [[this document]] | 2504 | 39 | Proxy-Scheme | [RFC7252] [[this document]] | 2505 | 60 | Size1 | [RFC7252] [[this document]] | 2506 | 258 | No-Response | [RFC7967] [[this document]] | 2507 +--------+-----------------+---------------------------------------+ 2509 Future additions to the CoAP Option Numbers registry need to provide 2510 a reference to the document where the OSCORE processing of that CoAP 2511 Option is defined. 2513 13.3. CoAP Signaling Option Numbers Registry 2515 The OSCORE option is added to the CoAP Signaling Option Numbers 2516 registry: 2518 +------------+--------+---------------------+-------------------+ 2519 | Applies to | Number | Name | Reference | 2520 +------------+--------+---------------------+-------------------+ 2521 | 7.xx (all) | TBD1 | OSCORE | [[this document]] | 2522 +------------+--------+---------------------+-------------------+ 2524 Note to IANA: The value in the "Number" field is the same value 2525 that's being assigned to the new Option Number. Please make sure 2526 TBD1 is not the same as any value in Numbers for any existing entry 2527 in the CoAP Signaling Option Numbers registry (at the time of writing 2528 this, that means make sure TBD1 is not 2 or 4)(RFC Editor: Delete 2529 this note after IANA assignment) 2531 13.4. Header Field Registrations 2533 The HTTP OSCORE header field is added to the Message Headers 2534 registry: 2536 +-------------------+----------+----------+---------------------+ 2537 | Header Field Name | Protocol | Status | Reference | 2538 +-------------------+----------+----------+---------------------+ 2539 | OSCORE | http | standard | [[this document]], | 2540 | | | | Section 11.1 | 2541 +-------------------+----------+----------+---------------------+ 2543 13.5. Media Type Registrations 2545 This section registers the 'application/oscore' media type in the 2546 "Media Types" registry. These media types are used to indicate that 2547 the content is an OSCORE message. The OSCORE body cannot be 2548 understood without the OSCORE header field value and the security 2549 context. 2551 Type name: application 2553 Subtype name: oscore 2555 Required parameters: N/A 2557 Optional parameters: N/A 2559 Encoding considerations: binary 2561 Security considerations: See the Security Considerations section 2562 of [[This document]]. 2564 Interoperability considerations: N/A 2566 Published specification: [[This document]] 2568 Applications that use this media type: IoT applications sending 2569 security content over HTTP(S) transports. 2571 Fragment identifier considerations: N/A 2573 Additional information: 2575 * Deprecated alias names for this type: N/A 2577 * Magic number(s): N/A 2579 * File extension(s): N/A 2581 * Macintosh file type code(s): N/A 2583 Person & email address to contact for further information: 2584 iesg@ietf.org 2586 Intended usage: COMMON 2588 Restrictions on usage: N/A 2590 Author: Goeran Selander, goran.selander@ericsson.com 2592 Change Controller: IESG 2594 Provisional registration? No 2596 13.6. CoAP Content-Formats Registry 2598 Note to IANA: ID assignment in the 10000-64999 range is requested. 2599 (RFC Editor: Delete this note after IANA assignment) 2601 This section registers the media type 'application/oscore' media type 2602 in the "CoAP Content-Formats" registry. This Content-Format for the 2603 OSCORE payload is defined for potential future use cases and SHALL 2604 NOT be used in the OSCORE message. The OSCORE payload cannot be 2605 understood without the OSCORE option value and the security context. 2607 +----------------------+----------+----------+-------------------+ 2608 | Media Type | Encoding | ID | Reference | 2609 +----------------------+----------+----------+-------------------+ 2610 | application/oscore | | TBD3 | [[this document]] | 2611 +----------------------+----------+----------+-------------------+ 2613 13.7. OSCORE Flag Bits Registry 2615 This document defines a sub-registry for the OSCORE flag bits within 2616 the "CoRE Parameters" registry. The name of the sub-registry is 2617 "OSCORE Flag Bits". The registry should be created with the Expert 2618 Review policy. Guidelines for the experts are provided in 2619 Section 13.8. 2621 The columns of the registry are: 2623 o bit position: This indicates the position of the bit in the set of 2624 OSCORE flag bits, starting at 0 for the most significant bit. The 2625 bit position must be an integer or a range of integers, in the 2626 range 0 to 63. 2628 o name: The name is present to make it easier to refer to and 2629 discuss the registration entry. The value is not used in the 2630 protocol. Names are to be unique in the table. 2632 o description: This contains a brief description of the use of the 2633 bit. 2635 o specification: This contains a pointer to the specification 2636 defining the entry. 2638 The initial contents of the registry can be found in the table below. 2639 The specification column for all rows in that table should be this 2640 document. The entries with Bit Position of 0 and 1 are to be marked 2641 as 'Reserved'. The entry with Bit Position of 1 is going to be 2642 specified in a future document, and will be used to expand the space 2643 for the OSCORE flag bits in Section 6.1, so that entries 8-63 of the 2644 registry are defined. 2646 +--------------+-------------+---------------------+-------------------+ 2647 | Bit Position | Name | Description | Specification | 2648 +--------------+-------------+---------------------+-------------------+ 2649 | 0 | Reserved | | | 2650 +--------------+-------------+---------------------+-------------------+ 2651 | 1 | Reserved | | | 2652 +--------------+-------------+---------------------+-------------------+ 2653 | 2 | Unassigned | | | 2654 +--------------+-------------+---------------------+-------------------+ 2655 | 3 | Kid Context | Set to 1 if 'kid | [[this document]] | 2656 | | Flag | context' is present | | 2657 | | | in the compressed | | 2658 | | | COSE object | | 2659 +--------------+-------------+---------------------+-------------------+ 2660 | 4 | Kid Flag | Set to 1 if kid is | [[this document]] | 2661 | | | present in the com- | | 2662 | | | pressed COSE object | | 2663 +--------------+-------------+---------------------+-------------------+ 2664 | 5-7 | Partial IV | Encodes the Partial | [[this document]] | 2665 | | Length | IV length; can have | | 2666 | | | value 0 to 5 | | 2667 +--------------+-------------+---------------------+-------------------+ 2668 | 8-63 | Unassigned | | | 2669 +--------------+-------------+---------------------+-------------------+ 2671 13.8. Expert Review Instructions 2673 The expert reviewers for the registry defined in this document are 2674 expected to ensure that the usage solves a valid use case that could 2675 not be solved better in a different way, that it is not going to 2676 duplicate one that is already registered, and that the registered 2677 point is likely to be used in deployments. They are furthermore 2678 expected to check the clarity of purpose and use of the requested 2679 code points. Experts should take into account the expected usage of 2680 entries when approving point assignment, and the length of the 2681 encoded value should be weighed against the number of code points 2682 left that encode to that size and the size of device it will be used 2683 on. Experts should block registration for entries 8-63 until these 2684 points are defined (i.e. until the mechanism for the OSCORE flag bits 2685 expansion via bit 1 is specified). 2687 14. References 2689 14.1. Normative References 2691 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2692 Requirement Levels", BCP 14, RFC 2119, 2693 DOI 10.17487/RFC2119, March 1997, 2694 . 2696 [RFC4086] Eastlake 3rd, D., Schiller, J., and S. Crocker, 2697 "Randomness Requirements for Security", BCP 106, RFC 4086, 2698 DOI 10.17487/RFC4086, June 2005, 2699 . 2701 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 2702 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 2703 . 2705 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 2706 Specifications: ABNF", STD 68, RFC 5234, 2707 DOI 10.17487/RFC5234, January 2008, 2708 . 2710 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 2711 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 2712 January 2012, . 2714 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 2715 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 2716 October 2013, . 2718 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 2719 Protocol (HTTP/1.1): Message Syntax and Routing", 2720 RFC 7230, DOI 10.17487/RFC7230, June 2014, 2721 . 2723 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 2724 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 2725 DOI 10.17487/RFC7231, June 2014, 2726 . 2728 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 2729 Application Protocol (CoAP)", RFC 7252, 2730 DOI 10.17487/RFC7252, June 2014, 2731 . 2733 [RFC7641] Hartke, K., "Observing Resources in the Constrained 2734 Application Protocol (CoAP)", RFC 7641, 2735 DOI 10.17487/RFC7641, September 2015, 2736 . 2738 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 2739 the Constrained Application Protocol (CoAP)", RFC 7959, 2740 DOI 10.17487/RFC7959, August 2016, 2741 . 2743 [RFC8075] Castellani, A., Loreto, S., Rahman, A., Fossati, T., and 2744 E. Dijk, "Guidelines for Mapping Implementations: HTTP to 2745 the Constrained Application Protocol (CoAP)", RFC 8075, 2746 DOI 10.17487/RFC8075, February 2017, 2747 . 2749 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 2750 FETCH Methods for the Constrained Application Protocol 2751 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 2752 . 2754 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 2755 RFC 8152, DOI 10.17487/RFC8152, July 2017, 2756 . 2758 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2759 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2760 May 2017, . 2762 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 2763 DOI 10.17487/RFC8288, October 2017, 2764 . 2766 [RFC8323] Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 2767 Silverajan, B., and B. Raymor, Ed., "CoAP (Constrained 2768 Application Protocol) over TCP, TLS, and WebSockets", 2769 RFC 8323, DOI 10.17487/RFC8323, February 2018, 2770 . 2772 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 2773 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 2774 . 2776 14.2. Informative References 2778 [I-D.bormann-6lo-coap-802-15-ie] 2779 Bormann, C., "Constrained Application Protocol (CoAP) over 2780 IEEE 802.15.4 Information Element for IETF", draft- 2781 bormann-6lo-coap-802-15-ie-00 (work in progress), April 2782 2016. 2784 [I-D.hartke-core-e2e-security-reqs] 2785 Selander, G., Palombini, F., and K. Hartke, "Requirements 2786 for CoAP End-To-End Security", draft-hartke-core-e2e- 2787 security-reqs-03 (work in progress), July 2017. 2789 [I-D.ietf-ace-oauth-authz] 2790 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 2791 H. Tschofenig, "Authentication and Authorization for 2792 Constrained Environments (ACE) using the OAuth 2.0 2793 Framework (ACE-OAuth)", draft-ietf-ace-oauth-authz-22 2794 (work in progress), March 2019. 2796 [I-D.ietf-ace-oscore-profile] 2797 Palombini, F., Seitz, L., Selander, G., and M. Gunnarsson, 2798 "OSCORE profile of the Authentication and Authorization 2799 for Constrained Environments Framework", draft-ietf-ace- 2800 oscore-profile-07 (work in progress), February 2019. 2802 [I-D.ietf-cbor-cddl] 2803 Birkholz, H., Vigano, C., and C. Bormann, "Concise data 2804 definition language (CDDL): a notational convention to 2805 express CBOR and JSON data structures", draft-ietf-cbor- 2806 cddl-07 (work in progress), February 2019. 2808 [I-D.ietf-core-echo-request-tag] 2809 Amsuess, C., Mattsson, J., and G. Selander, "Echo and 2810 Request-Tag", draft-ietf-core-echo-request-tag-03 (work in 2811 progress), October 2018. 2813 [I-D.ietf-core-oscore-groupcomm] 2814 Tiloca, M., Selander, G., Palombini, F., and J. Park, 2815 "Group OSCORE - Secure Group Communication for CoAP", 2816 draft-ietf-core-oscore-groupcomm-03 (work in progress), 2817 October 2018. 2819 [I-D.mattsson-core-coap-actuators] 2820 Mattsson, J., Fornehed, J., Selander, G., Palombini, F., 2821 and C. Amsuess, "Controlling Actuators with CoAP", draft- 2822 mattsson-core-coap-actuators-06 (work in progress), 2823 September 2018. 2825 [I-D.mcgrew-iv-gen] 2826 McGrew, D., "Generation of Deterministic Initialization 2827 Vectors (IVs) and Nonces", draft-mcgrew-iv-gen-03 (work in 2828 progress), October 2013. 2830 [MF00] McGrew, D. and S. Fluhrer, "Attacks on Encryption of 2831 Redundant Plaintext and Implications on Internet 2832 Security", the Proceedings of the Seventh Annual Workshop 2833 on Selected Areas in Cryptography (SAC 2000), Springer- 2834 Verlag. , 2000. 2836 [RFC3552] Rescorla, E. and B. Korver, "Guidelines for Writing RFC 2837 Text on Security Considerations", BCP 72, RFC 3552, 2838 DOI 10.17487/RFC3552, July 2003, 2839 . 2841 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2842 Resource Identifier (URI): Generic Syntax", STD 66, 2843 RFC 3986, DOI 10.17487/RFC3986, January 2005, 2844 . 2846 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 2847 Encryption", RFC 5116, DOI 10.17487/RFC5116, January 2008, 2848 . 2850 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 2851 Key Derivation Function (HKDF)", RFC 5869, 2852 DOI 10.17487/RFC5869, May 2010, 2853 . 2855 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 2856 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 2857 . 2859 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 2860 Constrained-Node Networks", RFC 7228, 2861 DOI 10.17487/RFC7228, May 2014, 2862 . 2864 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 2865 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 2866 2015, . 2868 [RFC7967] Bhattacharyya, A., Bandyopadhyay, S., Pal, A., and T. 2869 Bose, "Constrained Application Protocol (CoAP) Option for 2870 No Server Response", RFC 7967, DOI 10.17487/RFC7967, 2871 August 2016, . 2873 Appendix A. Scenario Examples 2875 This section gives examples of OSCORE, targeting scenarios in 2876 Section 2.2.1.1 of [I-D.hartke-core-e2e-security-reqs]. The message 2877 exchanges are made, based on the assumption that there is a security 2878 context established between client and server. For simplicity, these 2879 examples only indicate the content of the messages without going into 2880 detail of the (compressed) COSE message format. 2882 A.1. Secure Access to Sensor 2884 This example illustrates a client requesting the alarm status from a 2885 server. 2887 Client Proxy Server 2888 | | | 2889 +------>| | Code: 0.02 (POST) 2890 | POST | | Token: 0x8c 2891 | | | OSCORE: [kid:5f, Partial IV:42] 2892 | | | Payload: {Code:0.01, 2893 | | | Uri-Path:"alarm_status"} 2894 | | | 2895 | +------>| Code: 0.02 (POST) 2896 | | POST | Token: 0x7b 2897 | | | OSCORE: [kid:5f, Partial IV:42] 2898 | | | Payload: {Code:0.01, 2899 | | | Uri-Path:"alarm_status"} 2900 | | | 2901 | |<------+ Code: 2.04 (Changed) 2902 | | 2.04 | Token: 0x7b 2903 | | | OSCORE: - 2904 | | | Payload: {Code:2.05, "0"} 2905 | | | 2906 |<------+ | Code: 2.04 (Changed) 2907 | 2.04 | | Token: 0x8c 2908 | | | OSCORE: - 2909 | | | Payload: {Code:2.05, "0"} 2910 | | | 2912 Figure 12: Secure Access to Sensor. Square brackets [ ... ] indicate 2913 content of compressed COSE object. Curly brackets { ... } indicate 2914 encrypted data. 2916 The request/response Codes are encrypted by OSCORE and only dummy 2917 Codes (POST/Changed) are visible in the header of the OSCORE message. 2918 The option Uri-Path ("alarm_status") and payload ("0") are encrypted. 2920 The COSE header of the request contains an identifier (5f), 2921 indicating which security context was used to protect the message and 2922 a Partial IV (42). 2924 The server verifies the request as specified in Section 8.2. The 2925 client verifies the response as specified in Section 8.4. 2927 A.2. Secure Subscribe to Sensor 2929 This example illustrates a client requesting subscription to a blood 2930 sugar measurement resource (GET /glucose), first receiving the value 2931 220 mg/dl and then a second value 180 mg/dl. 2933 Client Proxy Server 2934 | | | 2935 +------>| | Code: 0.05 (FETCH) 2936 | FETCH | | Token: 0x83 2937 | | | Observe: 0 2938 | | | OSCORE: [kid:ca, Partial IV:15] 2939 | | | Payload: {Code:0.01, 2940 | | | Uri-Path:"glucose"} 2941 | | | 2942 | +------>| Code: 0.05 (FETCH) 2943 | | FETCH | Token: 0xbe 2944 | | | Observe: 0 2945 | | | OSCORE: [kid:ca, Partial IV:15] 2946 | | | Payload: {Code:0.01, 2947 | | | Uri-Path:"glucose"} 2948 | | | 2949 | |<------+ Code: 2.05 (Content) 2950 | | 2.05 | Token: 0xbe 2951 | | | Observe: 7 2952 | | | OSCORE: [Partial IV:32] 2953 | | | Payload: {Code:2.05, 2954 | | | Content-Format:0, "220"} 2955 | | | 2956 |<------+ | Code: 2.05 (Content) 2957 | 2.05 | | Token: 0x83 2958 | | | Observe: 7 2959 | | | OSCORE: [Partial IV:32] 2960 | | | Payload: {Code:2.05, 2961 | | | Content-Format:0, "220"} 2962 ... ... ... 2963 | | | 2964 | |<------+ Code: 2.05 (Content) 2965 | | 2.05 | Token: 0xbe 2966 | | | Observe: 8 2967 | | | OSCORE: [Partial IV:36] 2968 | | | Payload: {Code:2.05, 2969 | | | Content-Format:0, "180"} 2970 | | | 2971 |<------+ | Code: 2.05 (Content) 2972 | 2.05 | | Token: 0x83 2973 | | | Observe: 8 2974 | | | OSCORE: [Partial IV:36] 2975 | | | Payload: {Code:2.05, 2976 | | | Content-Format:0, "180"} 2977 | | | 2979 Figure 13: Secure Subscribe to Sensor. Square brackets [ ... ] 2980 indicate content of compressed COSE object header. Curly brackets { 2981 ... } indicate encrypted data. 2983 The dummy Codes (FETCH/Content) are used to allow forwarding of 2984 Observe messages. The options Content-Format (0) and the payload 2985 ("220" and "180"), are encrypted. 2987 The COSE header of the request contains an identifier (ca), 2988 indicating the security context used to protect the message and a 2989 Partial IV (15). The COSE headers of the responses contains Partial 2990 IVs (32 and 36). 2992 The server verifies that the Partial IV has not been received before. 2993 The client verifies that the responses are bound to the request and 2994 that the Partial IVs are greater than any Partial IV previously 2995 received in a response bound to the request. 2997 Appendix B. Deployment Examples 2999 For many IoT deployments, a 128 bit uniformly random Master Key is 3000 sufficient for encrypting all data exchanged with the IoT device 3001 throughout its lifetime. Two examples are given in this section. In 3002 the first example, the security context is only derived once from the 3003 Master Secret. In the second example, security contexts are derived 3004 multiple times using random inputs. 3006 B.1. Security Context Derived Once 3008 An application that only derives the security context once needs to 3009 handle the loss of mutable security context parameters, e.g. due to 3010 reboot. 3012 B.1.1. Sender Sequence Number 3014 In order to handle loss of Sender Sequence Numbers, the device may 3015 implement procedures for writing to non-volatile memory during normal 3016 operations and updating the security context after reboot, provided 3017 that the procedures comply with the requirements on the security 3018 context parameters (Section 3.3). This section gives an example of 3019 such a procedure. 3021 There are known issues related to writing to non-volatile memory. 3022 For example, flash drives may have a limited number of erase 3023 operations during its life time. Also, the time for a write 3024 operation to non-volatile memory to be completed may be 3025 unpredictable, e.g. due to caching, which could result in important 3026 security context data not being stored at the time when the device 3027 reboots. 3029 However, many devices have predictable limits for writing to non- 3030 volatile memory, are physically limited to only send a small amount 3031 of messages per minute, and may have no good source of randomness. 3033 To prevent reuse of Sender Sequence Numbers (SSN), an endpoint may 3034 perform the following procedure during normal operations: 3036 o Before using a Sender Sequence Number that is evenly divisible by 3037 K, where K is a positive integer, store the Sender Sequence Number 3038 (SSN1) in non-volatile memory. After boot, the endpoint initiates 3039 the new Sender Sequence Number (SSN2) to the value stored in 3040 persistent memory plus K plus F: SSN2 = SSN1 + K + F, where F is a 3041 positive integer. 3043 * Writing to non-volatile memory can be costly; the value K gives 3044 a trade-off between frequency of storage operations and 3045 efficient use of Sender Sequence Numbers. 3047 * Writing to non-volatile memory may be subject to delays, or 3048 failure; F MUST be set so that the last Sender Sequence Number 3049 used before reboot is never larger than SSN2. 3051 If F cannot be set so SSN2 is always larger than the last Sender 3052 Sequence Number used before reboot, the method described in this 3053 section MUST NOT be used. 3055 B.1.2. Replay Window 3057 In case of loss of security context on the server, to prevent 3058 accepting replay of previously received requests, the server may 3059 perform the following procedure after boot: 3061 o The server updates its Sender Sequence Number as specified in 3062 Appendix B.1.1, to be used as Partial IV in the response 3063 containing the Echo option (next bullet). 3065 o For each stored security context, the first time after boot the 3066 server receives an OSCORE request, the server responds with an 3067 OSCORE protected 4.01 (Unauthorized), containing only the Echo 3068 option [I-D.ietf-core-echo-request-tag] and no diagnostic payload. 3069 The server MUST use its Partial IV when generating the AEAD nonce 3070 and MUST include the Partial IV in the response (see Section 5). 3071 If the server with use of the Echo option can verify a second 3072 OSCORE request as fresh, then the Partial IV of the second request 3073 is set as the lower limit of the replay window of that security 3074 context. 3076 B.1.3. Notifications 3078 To prevent accepting replay of previously received notifications, the 3079 client may perform the following procedure after boot: 3081 o The client forgets about earlier registrations, removes all 3082 Notification Numbers and registers using Observe. 3084 B.2. Security Context Derived Multiple Times 3086 An application which does not require forward secrecy may allow 3087 multiple security contexts to be derived from one Master Secret. The 3088 requirements on the security context parameters MUST be fulfilled 3089 (Section 3.3) even if the client or server is rebooted, 3090 recommissioned or in error cases. 3092 This section gives an example of a protocol which adds randomness to 3093 the ID Context parameter and uses that together with input parameters 3094 pre-established between client and server, in particular Master 3095 Secret, Master Salt, and Sender/Recipient ID (see Section 3.2), to 3096 derive new security contexts. The random input is transported 3097 between client and server in the 'kid context' parameter. This 3098 protocol MUST NOT be used unless both endpoints have good sources of 3099 randomness. 3101 During normal requests the ID Context of an established security 3102 context may be sent in the 'kid context' which, together with 'kid', 3103 facilitates for the server to locate a security context. 3104 Alternatively, the 'kid context' may be omitted since the ID Context 3105 is expected to be known to both client and server, see Section 5.1. 3107 The protocol described in this section may only be needed when the 3108 mutable part of security context is lost in the client or server, 3109 e.g. when the endpoint has rebooted. The protocol may additionally 3110 be used whenever the client and server need to derive a new security 3111 context. For example, if a device is provisioned with one fixed set 3112 of input parameters (including Master Secret, Sender and Recipient 3113 Identifiers) then a randomized ID Context ensures that the security 3114 context is different for each deployment. 3116 The protocol is described below with reference to Figure 14. The 3117 client or the server may initiate the protocol, in the latter case 3118 step 1 is omitted. 3120 Client Server 3121 | | 3122 1. Protect with | request #1 | 3123 ID Context = ID1 |--------------------->| 2. Verify with 3124 | kid_context = ID1 | ID Context = ID1 3125 | | 3126 | response #1 | Protect with 3127 3. Verify with |<---------------------| ID Context = R2||ID1 3128 ID Context = R2||ID1 | kid_context = R2 | 3129 | | 3130 Protect with | request #2 | 3131 ID Context = R2||R3 |--------------------->| 4. Verify with 3132 | kid_context = R2||R3 | ID Context = R2||R3 3133 | | 3134 | response #2 | Protect with 3135 5. Verify with |<---------------------| ID Context = R2||R3 3136 ID Context = R2||R3 | | 3138 Figure 14: Protocol for establishing a new security context. 3140 1. (Optional) If the client does not have a valid security context 3141 with the server, e.g. because of reboot or because this is the 3142 first time it contacts the server, then it generates a random 3143 string R1, and uses this as ID Context together with the input 3144 parameters shared with the server to derive a first security 3145 context. The client sends an OSCORE request to the server 3146 protected with the first security context, containing R1 wrapped 3147 in a CBOR bstr as 'kid context'. The request may target a 3148 special resource used for updating security contexts. 3150 2. The server receives an OSCORE request for which it does not have 3151 a valid security context, either because the client has generated 3152 a new security context ID1 = R1, or because the server has lost 3153 part of its security context, e.g. ID Context, Sender Sequence 3154 Number or replay window. If the server is able to verify the 3155 request (see Section 8.2) with the new derived first security 3156 context using the received ID1 (transported in 'kid context') as 3157 ID Context and the input parameters associated to the received 3158 'kid', then the server generates a random string R2, and derives 3159 a second security context with ID Context = ID2 = R2 || ID1. The 3160 server sends a 4.01 (Unauthorized) response protected with the 3161 second security context, containing R2 wrapped in a CBOR bstr as 3162 'kid context', and caches R2. R2 MUST NOT be reused as that may 3163 lead to reuse of key and nonce in reponse #1. Note that the 3164 server may receive several requests #1 associated with one 3165 security context, leading to multiple parallel protocol runs. 3166 Multiple instances of R2 may need to be cached until one of the 3167 protocol runs is completed, see Appendix B.2.1. 3169 3. The client receives a response with 'kid context' containing a 3170 CBOR bstr wrapping R2 to an OSCORE request it made with ID 3171 Context = ID1. The client derives a second security context 3172 using ID Context = ID2 = R2 || ID1. If the client can verify the 3173 response (see Section 8.4) using the second security context, 3174 then the client makes a request protected with a third security 3175 context derived from ID Context = ID3 = R2 || R3, where R3 is a 3176 random byte string generated by the client. The request includes 3177 R2 || R3 wrapped in a CBOR bstr as 'kid context'. 3179 4. If the server receives a request with 'kid context' containing a 3180 CBOR bstr wrapping ID3, where the first part of ID3 is identical 3181 to an R2 sent in a previous response #1 which it has not received 3182 before, then the server derives a third security context with ID 3183 Context = ID3. The server MUST NOT accept replayed request #2 3184 messages. If the server can verify the request (see Section 8.2) 3185 with the third security context, then the server marks the third 3186 security context to be used with this client and removes all 3187 instances of R2 associated to this security context from the 3188 cache. This security context replaces the previous security 3189 context with the client, and the first and the second security 3190 contexts are deleted. The server responds using the same 3191 security context as in the request. 3193 5. If the client receives a response to the request with the third 3194 security context and the response verifies (see Section 8.4), 3195 then the client marks the third security context to be used with 3196 this server. This security context replaces the previous 3197 security context with the server, and the first and second 3198 security contexts are deleted. 3200 If verification fails in any step, the endpoint stops processing that 3201 message. 3203 The length of the nonces R1, R2, and R3 is application specific. The 3204 application needs to set the length of each nonce such the 3205 probability of its value being repeated is negligible; typically, at 3206 least 8 bytes long. Since R2 may be generated as the result of a 3207 replayed request #1, the probability for collision of R2s is impacted 3208 by the birthday paradox. For example, setting the length of R2 to 8 3209 bytes results in an average collision after 2^32 response #1 3210 messages, which should not be an issue for a constrained server 3211 handling on the order of one request per second. 3213 Request #2 can be an ordinary request. The server performs the 3214 action of the request and sends response #2 after having successfully 3215 completed the security context related operations in step 4. The 3216 client acts on response #2 after having successfully completed step 3217 5. 3219 When sending request #2, the client is assured that the Sender Key 3220 (derived with the random value R3) has never been used before. When 3221 receiving response #2, the client is assured that the response 3222 (protected with a key derived from the random value R3 and the Master 3223 Secret) was created by the server in response to request #2. 3225 Similarly, when receiving request #2, the server is assured that the 3226 request (protected with a key derived from the random value R2 and 3227 the Master Secret) was created by the client in response to response 3228 #1. When sending response #2, the server is assured that the Sender 3229 Key (derived with the random value R2) has never been used before. 3231 Implementation and denial-of-service considerations are made in 3232 Appendix B.2.1 and Appendix B.2.2. 3234 B.2.1. Implementation Considerations 3236 This section add some implemention considerations to the protocol 3237 described in the previous section. 3239 The server may only have space for a few security contexts, or only 3240 be able to handle a few protocol runs in parallel. The server may 3241 legitimately receive multiple request #1 messages using the same non- 3242 mutable security context, e.g. due to packet loss. Replays of old 3243 request #1 messages could be difficult for the server to distinguish 3244 from legitimate. The server needs to handle the case when the 3245 maximum number of cached R2s is reached. If the server receives a 3246 request #1 and is not capable of executing it then it may respond 3247 with an unprotected 5.03 (Service Unavailable). The server may clear 3248 up state from protocol runs which never complete, e.g. set a timer 3249 when caching R2, and remove R2 and the associated security contexts 3250 from the cache at timeout. Additionally, state information can be 3251 flushed at reboot. 3253 As an alternative to caching R2, the server could generate R2 in such 3254 a way that it can be sent (in response #1) and verified (at reception 3255 of request #2) as the value of R2 it had generated. Such a procedure 3256 MUST NOT lead to the server accepting replayed request #2 messages. 3257 One construction described in the following is based on using a 3258 secret random HMAC key K_HMAC per set of non-mutable security context 3259 parameters associated to a client. This construction allows the 3260 server to handle verification of R2 in response #2 at the cost of 3261 storing the K_HMAC keys and a slightly larger message overhead in 3262 response #1. Steps below refer to modifications to Appendix B.2: 3264 o In step 2, R2 is generated in the following way. First, the 3265 server generates a random K_HMAC (unless it already has one 3266 associated with the security context), then it sets R2 = S2 || 3267 HMAC(K_HMAC, S2) where S2 is a random byte string, and the HMAC is 3268 truncated to 8 bytes. K_HMAC may have an expiration time, after 3269 which it is erased. Note that neither R2, S2 nor the derived 3270 first and second security contexts need to be cached. 3272 o In step 4, instead of verifying that R2 coincides with a cached 3273 value, the server looks up the associated K_HMAC and verifies the 3274 truncated HMAC, and the processing continues accordingly depending 3275 on verification success or failure. K_HMAC is used until a run of 3276 the protocol is completed (after verification of request #2), or 3277 until it expires (whatever comes first), after which K_HMAC is 3278 erased. (The latter corresponds to removing the cached values of 3279 R2 in step 4 of Appendix B.2, and makes the server reject replays 3280 of request #2.) 3282 The length of S2 is application specific and the probability for 3283 collision of S2s is impacted by the birthday paradox. For example, 3284 setting the length of S2 to 8 bytes results in an average collision 3285 after 2^32 response #1 messages, which should not be an issue for a 3286 constrained server handling on the order of one request per second. 3288 Two endpoints sharing a security context may accidently initiate two 3289 instances of the protocol at the same time, each in the role of 3290 client, e.g. after a power outage affecting both endpoints. Such a 3291 race condition could potentially lead to both protocols failing, and 3292 both endpoints repeatedly re-initiating the protocol without 3293 converging. Both endpoints can detect this situation and it can be 3294 handled in different ways. The requests could potentially be more 3295 spread out in time, for example by only initiating this protocol when 3296 the endpoint actually needs to make a request, potentially adding a 3297 random delay before requests immediately after reboot or if such 3298 parallel protocol runs are detected. 3300 B.2.2. Attack Considerations 3302 An on-path attacker may inject a message causing the endpoint to 3303 process verification of the message. A message crafted without 3304 access to the Master Secret will fail to verify. 3306 Replaying an old request with a value of 'kid_context' which the 3307 server does not recognize could trigger the protocol. This causes 3308 the server to generate the first and second security context and send 3309 a response. But if the client did not expect a response it will be 3310 discarded. This may still result in a denial-of-service attack 3311 against the server e.g. because of not being able to manage the state 3312 associated with many parallel protocol runs, and it may prevent 3313 legitimate client requests. Implementation alternatives with less 3314 data caching per request #1 message are favorable in this respect, 3315 see Appendix B.2.1. 3317 Replaying response #1 in response to some request other than request 3318 #1 will fail to verify, since response #1 is associated to request 3319 #1, through the dependencies of ID Contexts and the Partial IV of 3320 request #1 included in the external_aad of response #1. 3322 If request #2 has already been well received, then the server has a 3323 valid security context, so a replay of request #2 is handled by the 3324 normal replay protection mechanism. Similarly if response #2 has 3325 already been received, a replay of response #2 to some other request 3326 from the client will fail by the normal verification of binding of 3327 response to request. 3329 Appendix C. Test Vectors 3331 This appendix includes the test vectors for different examples of 3332 CoAP messages using OSCORE. Given a set of inputs, OSCORE defines 3333 how to set up the Security Context in both the client and the server. 3335 Note that in Appendix C.4 and all following test vectors the Token 3336 and the Message ID of the OSCORE-protected CoAP messages are set to 3337 the same value of the unprotected CoAP message, to help the reader 3338 with comparisons. 3340 [NOTE: the following examples use option number = 9 (TBD1 assigned by 3341 IANA). If that differs, the RFC editor is asked to update the test 3342 vectors with data provided by the authors. Please remove this 3343 paragraph before publication.] 3345 C.1. Test Vector 1: Key Derivation with Master Salt 3347 In this test vector, a Master Salt of 8 bytes is used. The default 3348 values are used for AEAD Algorithm and HKDF. 3350 C.1.1. Client 3352 Inputs: 3354 o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes) 3356 o Master Salt: 0x9e7ca92223786340 (8 bytes) 3358 o Sender ID: 0x (0 byte) 3360 o Recipient ID: 0x01 (1 byte) 3362 From the previous parameters, 3364 o info (for Sender Key): 0x8540f60a634b657910 (9 bytes) 3366 o info (for Recipient Key): 0x854101f60a634b657910 (10 bytes) 3368 o info (for Common IV): 0x8540f60a6249560d (8 bytes) 3370 Outputs: 3372 o Sender Key: 0xf0910ed7295e6ad4b54fc793154302ff (16 bytes) 3374 o Recipient Key: 0xffb14e093c94c9cac9471648b4f98710 (16 bytes) 3376 o Common IV: 0x4622d4dd6d944168eefb54987c (13 bytes) 3378 From the previous parameters and a Partial IV equal to 0 (both for 3379 sender and recipient): 3381 o sender nonce: 0x4622d4dd6d944168eefb54987c (13 bytes) 3383 o recipient nonce: 0x4722d4dd6d944169eefb54987c (13 bytes) 3385 C.1.2. Server 3387 Inputs: 3389 o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes) 3391 o Master Salt: 0x9e7ca92223786340 (8 bytes) 3392 o Sender ID: 0x01 (1 byte) 3394 o Recipient ID: 0x (0 byte) 3396 From the previous parameters, 3398 o info (for Sender Key): 0x854101f60a634b657910 (10 bytes) 3400 o info (for Recipient Key): 0x8540f60a634b657910 (9 bytes) 3402 o info (for Common IV): 0x8540f60a6249560d (8 bytes) 3404 Outputs: 3406 o Sender Key: 0xffb14e093c94c9cac9471648b4f98710 (16 bytes) 3408 o Recipient Key: 0xf0910ed7295e6ad4b54fc793154302ff (16 bytes) 3410 o Common IV: 0x4622d4dd6d944168eefb54987c (13 bytes) 3412 From the previous parameters and a Partial IV equal to 0 (both for 3413 sender and recipient): 3415 o sender nonce: 0x4722d4dd6d944169eefb54987c (13 bytes) 3417 o recipient nonce: 0x4622d4dd6d944168eefb54987c (13 bytes) 3419 C.2. Test Vector 2: Key Derivation without Master Salt 3421 In this test vector, the default values are used for AEAD Algorithm, 3422 HKDF, and Master Salt. 3424 C.2.1. Client 3426 Inputs: 3428 o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes) 3430 o Sender ID: 0x00 (1 byte) 3432 o Recipient ID: 0x01 (1 byte) 3434 From the previous parameters, 3436 o info (for Sender Key): 0x854100f60a634b657910 (10 bytes) 3438 o info (for Recipient Key): 0x854101f60a634b657910 (10 bytes) 3439 o info (for Common IV): 0x8540f60a6249560d (8 bytes) 3441 Outputs: 3443 o Sender Key: 0x321b26943253c7ffb6003b0b64d74041 (16 bytes) 3445 o Recipient Key: 0xe57b5635815177cd679ab4bcec9d7dda (16 bytes) 3447 o Common IV: 0xbe35ae297d2dace910c52e99f9 (13 bytes) 3449 From the previous parameters and a Partial IV equal to 0 (both for 3450 sender and recipient): 3452 o sender nonce: 0xbf35ae297d2dace910c52e99f9 (13 bytes) 3454 o recipient nonce: 0xbf35ae297d2dace810c52e99f9 (13 bytes) 3456 C.2.2. Server 3458 Inputs: 3460 o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes) 3462 o Sender ID: 0x01 (1 byte) 3464 o Recipient ID: 0x00 (1 byte) 3466 From the previous parameters, 3468 o info (for Sender Key): 0x854101f60a634b657910 (10 bytes) 3470 o info (for Recipient Key): 0x854100f60a634b657910 (10 bytes) 3472 o info (for Common IV): 0x8540f60a6249560d (8 bytes) 3474 Outputs: 3476 o Sender Key: 0xe57b5635815177cd679ab4bcec9d7dda (16 bytes) 3478 o Recipient Key: 0x321b26943253c7ffb6003b0b64d74041 (16 bytes) 3480 o Common IV: 0xbe35ae297d2dace910c52e99f9 (13 bytes) 3482 From the previous parameters and a Partial IV equal to 0 (both for 3483 sender and recipient): 3485 o sender nonce: 0xbf35ae297d2dace810c52e99f9 (13 bytes) 3486 o recipient nonce: 0xbf35ae297d2dace910c52e99f9 (13 bytes) 3488 C.3. Test Vector 3: Key Derivation with ID Context 3490 In this test vector, a Master Salt of 8 bytes and a ID Context of 8 3491 bytes are used. The default values are used for AEAD Algorithm and 3492 HKDF. 3494 C.3.1. Client 3496 Inputs: 3498 o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes) 3500 o Master Salt: 0x9e7ca92223786340 (8 bytes) 3502 o Sender ID: 0x (0 byte) 3504 o Recipient ID: 0x01 (1 byte) 3506 o ID Context: 0x37cbf3210017a2d3 (8 bytes) 3508 From the previous parameters, 3510 o info (for Sender Key): 0x85404837cbf3210017a2d30a634b657910 (17 3511 bytes) 3513 o info (for Recipient Key): 0x8541014837cbf3210017a2d30a634b657910 3514 (18 bytes) 3516 o info (for Common IV): 0x85404837cbf3210017a2d30a6249560d (16 3517 bytes) 3519 Outputs: 3521 o Sender Key: 0xaf2a1300a5e95788b356336eeecd2b92 (16 bytes) 3523 o Recipient Key: 0xe39a0c7c77b43f03b4b39ab9a268699f (16 bytes) 3525 o Common IV: 0x2ca58fb85ff1b81c0b7181b85e (13 bytes) 3527 From the previous parameters and a Partial IV equal to 0 (both for 3528 sender and recipient): 3530 o sender nonce: 0x2ca58fb85ff1b81c0b7181b85e (13 bytes) 3532 o recipient nonce: 0x2da58fb85ff1b81d0b7181b85e (13 bytes) 3534 C.3.2. Server 3536 Inputs: 3538 o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes) 3540 o Master Salt: 0x9e7ca92223786340 (8 bytes) 3542 o Sender ID: 0x01 (1 byte) 3544 o Recipient ID: 0x (0 byte) 3546 o ID Context: 0x37cbf3210017a2d3 (8 bytes) 3548 From the previous parameters, 3550 o info (for Sender Key): 0x8541014837cbf3210017a2d30a634b657910 (18 3551 bytes) 3553 o info (for Recipient Key): 0x85404837cbf3210017a2d30a634b657910 (17 3554 bytes) 3556 o info (for Common IV): 0x85404837cbf3210017a2d30a6249560d (16 3557 bytes) 3559 Outputs: 3561 o Sender Key: 0xe39a0c7c77b43f03b4b39ab9a268699f (16 bytes) 3563 o Recipient Key: 0xaf2a1300a5e95788b356336eeecd2b92 (16 bytes) 3565 o Common IV: 0x2ca58fb85ff1b81c0b7181b85e (13 bytes) 3567 From the previous parameters and a Partial IV equal to 0 (both for 3568 sender and recipient): 3570 o sender nonce: 0x2da58fb85ff1b81d0b7181b85e (13 bytes) 3572 o recipient nonce: 0x2ca58fb85ff1b81c0b7181b85e (13 bytes) 3574 C.4. Test Vector 4: OSCORE Request, Client 3576 This section contains a test vector for an OSCORE protected CoAP GET 3577 request using the security context derived in Appendix C.1. The 3578 unprotected request only contains the Uri-Path and Uri-Host options. 3580 Unprotected CoAP request: 3581 0x44015d1f00003974396c6f63616c686f737483747631 (22 bytes) 3582 Common Context: 3584 o AEAD Algorithm: 10 (AES-CCM-16-64-128) 3586 o Key Derivation Function: HKDF SHA-256 3588 o Common IV: 0x4622d4dd6d944168eefb54987c (13 bytes) 3590 Sender Context: 3592 o Sender ID: 0x (0 byte) 3594 o Sender Key: 0xf0910ed7295e6ad4b54fc793154302ff (16 bytes) 3596 o Sender Sequence Number: 20 3598 The following COSE and cryptographic parameters are derived: 3600 o Partial IV: 0x14 (1 byte) 3602 o kid: 0x (0 byte) 3604 o external_aad: 0x8501810a40411440 (8 bytes) 3606 o AAD: 0x8368456e63727970743040488501810a40411440 (20 bytes) 3608 o plaintext: 0x01b3747631 (5 bytes) 3610 o encryption key: 0xf0910ed7295e6ad4b54fc793154302ff (16 bytes) 3612 o nonce: 0x4622d4dd6d944168eefb549868 (13 bytes) 3614 From the previous parameter, the following is derived: 3616 o OSCORE option value: 0x0914 (2 bytes) 3618 o ciphertext: 0x612f1092f1776f1c1668b3825e (13 bytes) 3620 From there: 3622 o Protected CoAP request (OSCORE message): 0x44025d1f00003974396c6f6 3623 3616c686f7374620914ff612f1092f1776f1c1668b3825e (35 bytes) 3625 C.5. Test Vector 5: OSCORE Request, Client 3627 This section contains a test vector for an OSCORE protected CoAP GET 3628 request using the security context derived in Appendix C.2. The 3629 unprotected request only contains the Uri-Path and Uri-Host options. 3631 Unprotected CoAP request: 3632 0x440171c30000b932396c6f63616c686f737483747631 (22 bytes) 3634 Common Context: 3636 o AEAD Algorithm: 10 (AES-CCM-16-64-128) 3638 o Key Derivation Function: HKDF SHA-256 3640 o Common IV: 0xbe35ae297d2dace910c52e99f9 (13 bytes) 3642 Sender Context: 3644 o Sender ID: 0x00 (1 bytes) 3646 o Sender Key: 0x321b26943253c7ffb6003b0b64d74041 (16 bytes) 3648 o Sender Sequence Number: 20 3650 The following COSE and cryptographic parameters are derived: 3652 o Partial IV: 0x14 (1 byte) 3654 o kid: 0x00 (1 byte) 3656 o external_aad: 0x8501810a4100411440 (9 bytes) 3658 o AAD: 0x8368456e63727970743040498501810a4100411440 (21 bytes) 3660 o plaintext: 0x01b3747631 (5 bytes) 3662 o encryption key: 0x321b26943253c7ffb6003b0b64d74041 (16 bytes) 3664 o nonce: 0xbf35ae297d2dace910c52e99ed (13 bytes) 3666 From the previous parameter, the following is derived: 3668 o OSCORE option value: 0x091400 (3 bytes) 3670 o ciphertext: 0x4ed339a5a379b0b8bc731fffb0 (13 bytes) 3672 From there: 3674 o Protected CoAP request (OSCORE message): 0x440271c30000b932396c6f6 3675 3616c686f737463091400ff4ed339a5a379b0b8bc731fffb0 (36 bytes) 3677 C.6. Test Vector 6: OSCORE Request, Client 3679 This section contains a test vector for an OSCORE protected CoAP GET 3680 request for an application that sets the ID Context and requires it 3681 to be sent in the request, so 'kid context' is present in the 3682 protected message. This test vector uses the security context 3683 derived in Appendix C.3. The unprotected request only contains the 3684 Uri-Path and Uri-Host options. 3686 Unprotected CoAP request: 3687 0x44012f8eef9bbf7a396c6f63616c686f737483747631 (22 bytes) 3689 Common Context: 3691 o AEAD Algorithm: 10 (AES-CCM-16-64-128) 3693 o Key Derivation Function: HKDF SHA-256 3695 o Common IV: 0x2ca58fb85ff1b81c0b7181b85e (13 bytes) 3697 o ID Context: 0x37cbf3210017a2d3 (8 bytes) 3699 Sender Context: 3701 o Sender ID: 0x (0 bytes) 3703 o Sender Key: 0xaf2a1300a5e95788b356336eeecd2b92 (16 bytes) 3705 o Sender Sequence Number: 20 3707 The following COSE and cryptographic parameters are derived: 3709 o Partial IV: 0x14 (1 byte) 3711 o kid: 0x (0 byte) 3713 o kid context: 0x37cbf3210017a2d3 (8 bytes) 3715 o external_aad: 0x8501810a40411440 (8 bytes) 3717 o AAD: 0x8368456e63727970743040488501810a40411440 (20 bytes) 3719 o plaintext: 0x01b3747631 (5 bytes) 3721 o encryption key: 0xaf2a1300a5e95788b356336eeecd2b92 (16 bytes) 3723 o nonce: 0x2ca58fb85ff1b81c0b7181b84a (13 bytes) 3724 From the previous parameter, the following is derived: 3726 o OSCORE option value: 0x19140837cbf3210017a2d3 (11 bytes) 3728 o ciphertext: 0x72cd7273fd331ac45cffbe55c3 (13 bytes) 3730 From there: 3732 o Protected CoAP request (OSCORE message): 3733 0x44022f8eef9bbf7a396c6f63616c686f73746b19140837cbf3210017a2d3ff 3734 72cd7273fd331ac45cffbe55c3 (44 bytes) 3736 C.7. Test Vector 7: OSCORE Response, Server 3738 This section contains a test vector for an OSCORE protected 2.05 3739 (Content) response to the request in Appendix C.4. The unprotected 3740 response has payload "Hello World!" and no options. The protected 3741 response does not contain a 'kid' nor a Partial IV. Note that some 3742 parameters are derived from the request. 3744 Unprotected CoAP response: 3745 0x64455d1f00003974ff48656c6c6f20576f726c6421 (21 bytes) 3747 Common Context: 3749 o AEAD Algorithm: 10 (AES-CCM-16-64-128) 3751 o Key Derivation Function: HKDF SHA-256 3753 o Common IV: 0x4622d4dd6d944168eefb54987c (13 bytes) 3755 Sender Context: 3757 o Sender ID: 0x01 (1 byte) 3759 o Sender Key: 0xffb14e093c94c9cac9471648b4f98710 (16 bytes) 3761 o Sender Sequence Number: 0 3763 The following COSE and cryptographic parameters are derived: 3765 o external_aad: 0x8501810a40411440 (8 bytes) 3767 o AAD: 0x8368456e63727970743040488501810a40411440 (20 bytes) 3769 o plaintext: 0x45ff48656c6c6f20576f726c6421 (14 bytes) 3771 o encryption key: 0xffb14e093c94c9cac9471648b4f98710 (16 bytes) 3772 o nonce: 0x4622d4dd6d944168eefb549868 (13 bytes) 3774 From the previous parameter, the following is derived: 3776 o OSCORE option value: 0x (0 bytes) 3778 o ciphertext: 0xdbaad1e9a7e7b2a813d3c31524378303cdafae119106 (22 3779 bytes) 3781 From there: 3783 o Protected CoAP response (OSCORE message): 3784 0x64445d1f0000397490ffdbaad1e9a7e7b2a813d3c31524378303cdafae119106 3785 (32 bytes) 3787 C.8. Test Vector 8: OSCORE Response with Partial IV, Server 3789 This section contains a test vector for an OSCORE protected 2.05 3790 (Content) response to the request in Appendix C.4. The unprotected 3791 response has payload "Hello World!" and no options. The protected 3792 response does not contain a 'kid', but contains a Partial IV. Note 3793 that some parameters are derived from the request. 3795 Unprotected CoAP response: 3796 0x64455d1f00003974ff48656c6c6f20576f726c6421 (21 bytes) 3798 Common Context: 3800 o AEAD Algorithm: 10 (AES-CCM-16-64-128) 3802 o Key Derivation Function: HKDF SHA-256 3804 o Common IV: 0x4622d4dd6d944168eefb54987c (13 bytes) 3806 Sender Context: 3808 o Sender ID: 0x01 (1 byte) 3810 o Sender Key: 0xffb14e093c94c9cac9471648b4f98710 (16 bytes) 3812 o Sender Sequence Number: 0 3814 The following COSE and cryptographic parameters are derived: 3816 o Partial IV: 0x00 (1 byte) 3818 o external_aad: 0x8501810a40411440 (8 bytes) 3819 o AAD: 0x8368456e63727970743040488501810a40411440 (20 bytes) 3821 o plaintext: 0x45ff48656c6c6f20576f726c6421 (14 bytes) 3823 o encryption key: 0xffb14e093c94c9cac9471648b4f98710 (16 bytes) 3825 o nonce: 0x4722d4dd6d944169eefb54987c (13 bytes) 3827 From the previous parameter, the following is derived: 3829 o OSCORE option value: 0x0100 (2 bytes) 3831 o ciphertext: 0x4d4c13669384b67354b2b6175ff4b8658c666a6cf88e (22 3832 bytes) 3834 From there: 3836 o Protected CoAP response (OSCORE message): 0x64445d1f00003974920100 3837 ff4d4c13669384b67354b2b6175ff4b8658c666a6cf88e (34 bytes) 3839 Appendix D. Overview of Security Properties 3841 D.1. Threat Model 3843 This section describes the threat model using the terms of [RFC3552]. 3845 It is assumed that the endpoints running OSCORE have not themselves 3846 been compromised. The attacker is assumed to have control of the 3847 CoAP channel over which the endpoints communicate, including 3848 intermediary nodes. The attacker is capable of launching any passive 3849 or active, on-path or off-path attacks; including eavesdropping, 3850 traffic analysis, spoofing, insertion, modification, deletion, delay, 3851 replay, man-in-the-middle, and denial-of-service attacks. This means 3852 that the attacker can read any CoAP message on the network and 3853 undetectably remove, change, or inject forged messages onto the wire. 3855 OSCORE targets the protection of the CoAP request/response layer 3856 (Section 2 of [RFC7252]) between the endpoints, including the CoAP 3857 Payload, Code, Uri-Path/Uri-Query, and the other Class E option 3858 instances (Section 4.1). 3860 OSCORE does not protect the CoAP messaging layer (Section 2 of 3861 [RFC7252]) or other lower layers involved in routing and transporting 3862 the CoAP requests and responses. 3864 Additionally, OSCORE does not protect Class U option instances 3865 (Section 4.1), as these are used to support CoAP forward proxy 3866 operations (see Section 5.7.2 of [RFC7252]). The supported proxies 3867 (forwarding, cross-protocol e.g. CoAP to CoAP-mappable protocols 3868 such as HTTP) must be able to change certain Class U options (by 3869 instruction from the Client), resulting in the CoAP request being 3870 redirected to the server. Changes caused by the proxy may result in 3871 the request not reaching the server or reaching the wrong server. 3872 For cross-protocol proxies, mappings are done on the Outer part of 3873 the message so these protocols are essentially used as transport. 3874 Manipulation of these options may thus impact whether the protected 3875 message reaches or does not reach the destination endpoint. 3877 Attacks on unprotected CoAP message fields generally causes denial- 3878 of-service attacks which are out of scope of this document, more 3879 details are given in Appendix D.5. 3881 Attacks against the CoAP request-response layer are in scope. OSCORE 3882 is intended to protect against eavesdropping, spoofing, insertion, 3883 modification, deletion, replay, and man-in-the middle attacks. 3885 OSCORE is susceptible to traffic analysis as discussed later in 3886 Appendix D. 3888 D.2. Supporting Proxy Operations 3890 CoAP is designed to work with intermediaries reading and/or changing 3891 CoAP message fields to perform supporting operations in constrained 3892 environments, e.g. forwarding and cross-protocol translations. 3894 Securing CoAP on transport layer protects the entire message between 3895 the endpoints in which case CoAP proxy operations are not possible. 3896 In order to enable proxy operations, security on transport layer 3897 needs to be terminated at the proxy in which case the CoAP message in 3898 its entirety is unprotected in the proxy. 3900 Requirements for CoAP end-to-end security are specified in 3901 [I-D.hartke-core-e2e-security-reqs], in particular forwarding is 3902 detailed in Section 2.2.1. The client and server are assumed to be 3903 honest, while proxies and gateways are only trusted to perform their 3904 intended operations. 3906 By working at the CoAP layer, OSCORE enables different CoAP message 3907 fields to be protected differently, which allows message fields 3908 required for proxy operations to be available to the proxy while 3909 message fields intended for the other endpoint remain protected. In 3910 the remainder of this section we analyze how OSCORE protects the 3911 protected message fields and the consequences of message fields 3912 intended for proxy operation being unprotected. 3914 D.3. Protected Message Fields 3916 Protected message fields are included in the Plaintext (Section 5.3) 3917 and the Additional Authenticated Data (Section 5.4) of the 3918 COSE_Encrypt0 object and encrypted using an AEAD algorithm. 3920 OSCORE depends on a pre-established random Master Secret 3921 (Section 12.3) used to derive encryption keys, and a construction for 3922 making (key, nonce) pairs unique (Appendix D.4). Assuming this is 3923 true, and the keys are used for no more data than indicated in 3924 Section 7.2.1, OSCORE should provide the following guarantees: 3926 o Confidentiality: An attacker should not be able to determine the 3927 plaintext contents of a given OSCORE message or determine that 3928 different plaintexts are related (Section 5.3). 3930 o Integrity: An attacker should not be able to craft a new OSCORE 3931 message with protected message fields different from an existing 3932 OSCORE message which will be accepted by the receiver. 3934 o Request-response binding: An attacker should not be able to make a 3935 client match a response to the wrong request. 3937 o Non-replayability: An attacker should not be able to cause the 3938 receiver to accept a message which it has previously received and 3939 accepted. 3941 In the above, the attacker is anyone except the endpoints, e.g. a 3942 compromised intermediary. Informally, OSCORE provides these 3943 properties by AEAD-protecting the plaintext with a strong key and 3944 uniqueness of (key, nonce) pairs. AEAD encryption [RFC5116] provides 3945 confidentiality and integrity for the data. Response-request binding 3946 is provided by including the 'kid' and Partial IV of the request in 3947 the AAD of the response. Non-replayability of requests and 3948 notifications is provided by using unique (key, nonce) pairs and a 3949 replay protection mechanism (application dependent, see Section 7.4). 3951 OSCORE is susceptible to a variety of traffic analysis attacks based 3952 on observing the length and timing of encrypted packets. OSCORE does 3953 not provide any specific defenses against this form of attack but the 3954 application may use a padding mechanism to prevent an attacker from 3955 directly determine the length of the padding. However, information 3956 about padding may still be revealed by side-channel attacks observing 3957 differences in timing. 3959 D.4. Uniqueness of (key, nonce) 3961 In this section we show that (key, nonce) pairs are unique as long as 3962 the requirements in Sections 3.3 and 7.2.1 are followed. 3964 Fix a Common Context (Section 3.1) and an endpoint, called the 3965 encrypting endpoint. An endpoint may alternate between client and 3966 server roles, but each endpoint always encrypts with the Sender Key 3967 of its Sender Context. Sender Keys are (stochastically) unique since 3968 they are derived with HKDF using unique Sender IDs, so messages 3969 encrypted by different endpoints use different keys. It remains to 3970 prove that the nonces used by the fixed endpoint are unique. 3972 Since the Common IV is fixed, the nonces are determined by a Partial 3973 IV (PIV) and the Sender ID of the endpoint generating that Partial IV 3974 (ID_PIV). The nonce construction (Section 5.2) with the size of the 3975 ID_PIV (S) creates unique nonces for different (ID_PIV, PIV) pairs. 3976 There are two cases: 3978 A. For requests, and responses with Partial IV (e.g. Observe 3979 notifications): 3981 o ID_PIV = Sender ID of the encrypting endpoint 3983 o PIV = current Partial IV of the encrypting endpoint 3985 Since the encrypting endpoint steps the Partial IV for each use, the 3986 nonces used in case A are all unique as long as the number of 3987 encrypted messages is kept within the required range (Section 7.2.1). 3989 B. For responses without Partial IV (e.g. single response to a 3990 request): 3992 o ID_PIV = Sender ID of the endpoint generating the request 3994 o PIV = Partial IV of the request 3996 Since the Sender IDs are unique, ID_PIV is different from the Sender 3997 ID of the encrypting endpoint. Therefore, the nonces in case B are 3998 different compared to nonces in case A, where the encrypting endpoint 3999 generated the Partial IV. Since the Partial IV of the request is 4000 verified for replay (Section 7.4) associated to this Recipient 4001 Context, PIV is unique for this ID_PIV, which makes all nonces in 4002 case B distinct. 4004 D.5. Unprotected Message Fields 4006 This sections analyses attacks on message fields which are not 4007 protected by OSCORE according to the threat model Appendix D.1. 4009 D.5.1. CoAP Header Fields 4011 o Version. The CoAP version [RFC7252] is not expected to be 4012 sensitive to disclose. Currently there is only one CoAP version 4013 defined. A change of this parameter is potentially a denial-of- 4014 service attack. Future versions of CoAP need to analyze attacks 4015 to OSCORE protected messages due to an adversary changing the CoAP 4016 version. 4018 o Token/Token Length. The Token field is a client-local identifier 4019 for differentiating between concurrent requests [RFC7252]. CoAP 4020 proxies are allowed to read and change Token and Token Length 4021 between hops. An eavesdropper reading the Token can match 4022 requests to responses which can be used in traffic analysis. In 4023 particular this is true for notifications, where multiple 4024 responses are matched with one request. Modifications of Token 4025 and Token Length by an on-path attacker may become a denial-of- 4026 service attack, since it may prevent the client to identify to 4027 which request the response belongs or to find the correct 4028 information to verify integrity of the response. 4030 o Code. The Outer CoAP Code of an OSCORE message is POST or FETCH 4031 for requests with corresponding response codes. An endpoint 4032 receiving the message discards the Outer CoAP Code and uses the 4033 Inner CoAP Code instead (see Section 4.2). Hence, modifications 4034 from attackers to the Outer Code do not impact the receiving 4035 endpoint. However, changing the Outer Code from FETCH to a Code 4036 value for a method that does not work with Observe (such as POST) 4037 may, depending on proxy implementation since Observe is undefined 4038 for several Codes, cause the proxy to not forward notifications, 4039 which is a denial-of-service attack. The use of FETCH rather than 4040 POST reveals no more than what is revealed by the presence of the 4041 Outer Observe option. 4043 o Type/Message ID. The Type/Message ID fields [RFC7252] reveal 4044 information about the UDP transport binding, e.g. an eavesdropper 4045 reading the Type or Message ID gain information about how UDP 4046 messages are related to each other. CoAP proxies are allowed to 4047 change Type and Message ID. These message fields are not present 4048 in CoAP over TCP [RFC8323], and does not impact the request/ 4049 response message. A change of these fields in a UDP hop is a 4050 denial-of-service attack. By sending an ACK, an attacker can make 4051 the endpoint believe that it does not need to retransmit the 4052 previous message. By sending a RST, an attacker may be able to 4053 cancel an observation. By changing a NON to a CON, the attacker 4054 can cause the receiving endpoint to ACK messages for which no ACK 4055 was requested. 4057 o Length. This field contain the length of the message [RFC8323] 4058 which may be used for traffic analysis. These message fields are 4059 not present in CoAP over UDP, and does not impact the request/ 4060 response message. A change of Length is a denial-of-service 4061 attack similar to changing TCP header fields. 4063 D.5.2. CoAP Options 4065 o Max-Age. The Outer Max-Age is set to zero to avoid unnecessary 4066 caching of OSCORE error responses. Changing this value thus may 4067 cause unnecessary caching. No additional information is carried 4068 with this option. 4070 o Proxy-Uri/Proxy-Scheme. These options are used in CoAP forward 4071 proxy deployments. With OSCORE, the Proxy-Uri option does not 4072 contain the Uri-Path/Uri-Query parts of the URI. The other parts 4073 of Proxy-Uri cannot be protected because forward proxies need to 4074 change them in order to perform their functions. The server can 4075 verify what scheme is used in the last hop, but not what was 4076 requested by the client or what was used in previous hops. 4078 o Uri-Host/Uri-Port. In forward proxy deployments, the Uri-Host/ 4079 Uri-Port may be changed by an adversary, and the application needs 4080 to handle the consequences of that (see Section 4.1.3.2). The 4081 Uri-Host may either be omitted, reveal information equivalent to 4082 that of the IP address or more privacy-sensitive information, 4083 which is discouraged. 4085 o Observe. The Outer Observe option is intended for a proxy to 4086 support forwarding of Observe messages, but is ignored by the 4087 endpoints since the Inner Observe determines the processing in the 4088 endpoints. Since the Partial IV provides absolute ordering of 4089 notifications it is not possible for an intermediary to spoof 4090 reordering (see Section 4.1.3.5). The absence of Partial IV, 4091 since only allowed for the first notification, does not prevent 4092 correct ordering of notifications. The size and distributions of 4093 notifications over time may reveal information about the content 4094 or nature of the notifications. Cancellations (Section 4.1.3.5.1) 4095 are not bound to the corresponding registrations in the same way 4096 responses are bound to requests in OSCORE (see Appendix D.3), but 4097 that does not open up for attacks based on mismatched 4098 cancellations, since for cancellations to be accepted, all options 4099 in the decrypted message except for ETag Options MUST be the same 4100 (see Section 4.1.3.5). 4102 o Block1/Block2/Size1/Size2. The Outer Block options enables 4103 fragmentation of OSCORE messages in addition to segmentation 4104 performed by the Inner Block options. The presence of these 4105 options indicates a large message being sent and the message size 4106 can be estimated and used for traffic analysis. Manipulating 4107 these options is a potential denial-of-service attack, e.g. 4108 injection of alleged Block fragments. The specification of a 4109 maximum size of message, MAX_UNFRAGMENTED_SIZE 4110 (Section 4.1.3.4.2), above which messages will be dropped, is 4111 intended as one measure to mitigate this kind of attack. 4113 o No-Response. The Outer No-Response option is used to support 4114 proxy functionality, specifically to avoid error transmissions 4115 from proxies to clients, and to avoid bandwidth reduction to 4116 servers by proxies applying congestion control when not receiving 4117 responses. Modifying or introducing this option is a potential 4118 denial-of-service attack against the proxy operations, but since 4119 the option has an Inner value its use can be securely agreed 4120 between the endpoints. The presence of this option is not 4121 expected to reveal any sensitive information about the message 4122 exchange. 4124 o OSCORE. The OSCORE option contains information about the 4125 compressed COSE header. Changing this field may cause OSCORE 4126 verification to fail. 4128 D.5.3. Error and Signaling Messages 4130 Error messages occurring during CoAP processing are protected end-to- 4131 end. Error messages occurring during OSCORE processing are not 4132 always possible to protect, e.g. if the receiving endpoint cannot 4133 locate the right security context. For this setting, unprotected 4134 error messages are allowed as specified to prevent extensive 4135 retransmissions. Those error messages can be spoofed or manipulated, 4136 which is a potential denial-of-service attack. 4138 This document specifies OPTIONAL error codes and specific diagnostic 4139 payloads for OSCORE processing error messages. Such messages might 4140 reveal information about how many and which security contexts exist 4141 on the server. Servers MAY want to omit the diagnostic payload of 4142 error messages, use the same error code for all errors, or avoid 4143 responding altogether in case of OSCORE processing errors, if that is 4144 a security concern for the application. Moreover, clients MUST NOT 4145 rely on the error code or the diagnostic payload to trigger specific 4146 actions, as these errors are unprotected and can be spoofed or 4147 manipulated. 4149 Signaling messages used in CoAP over TCP [RFC8323] are intended to be 4150 hop-by-hop; spoofing signaling messages can be used as a denial-of- 4151 service attack of a TCP connection. 4153 D.5.4. HTTP Message Fields 4155 In contrast to CoAP, where OSCORE does not protect header fields to 4156 enable CoAP-CoAP proxy operations, the use of OSCORE with HTTP is 4157 restricted to transporting a protected CoAP message over an HTTP hop. 4158 Any unprotected HTTP message fields may reveal information about the 4159 transport of the OSCORE message and enable various denial-of-service 4160 attacks. It is RECOMMENDED to additionally use TLS [RFC8446] for 4161 HTTP hops, which enables encryption and integrity protection of 4162 headers, but still leaves some information for traffic analysis. 4164 Appendix E. CDDL Summary 4166 Data structure definitions in the present specification employ the 4167 CDDL language for conciseness and precision. CDDL is defined in 4168 [I-D.ietf-cbor-cddl], which at the time of writing this appendix is 4169 in the process of completion. As the document is not yet available 4170 for a normative reference, the present appendix defines the small 4171 subset of CDDL that is being used in the present specification. 4173 Within the subset being used here, a CDDL rule is of the form "name = 4174 type", where "name" is the name given to the "type". A "type" can be 4175 one of: 4177 o a reference to another named type, by giving its name. The 4178 predefined named types used in the present specification are: 4179 "uint", an unsigned integer (as represented in CBOR by major type 4180 0); "int", an unsigned or negative integer (as represented in CBOR 4181 by major type 0 or 1); "bstr", a byte string (as represented in 4182 CBOR by major type 2); "tstr", a text string (as represented in 4183 CBOR by major type 3); 4185 o a choice between two types, by giving both types separated by a 4186 "/"; 4188 o an array type (as represented in CBOR by major type 4), where the 4189 sequence of elements of the array is described by giving a 4190 sequence of entries separated by commas ",", and this sequence is 4191 enclosed by square brackets "[" and "]". Arrays described by an 4192 array description contain elements that correspond one-to-one to 4193 the sequence of entries given. Each entry of an array description 4194 is of the form "name : type", where "name" is the name given to 4195 the entry and "type" is the type of the array element 4196 corresponding to this entry. 4198 Acknowledgments 4200 The following individuals provided input to this document: Christian 4201 Amsuess, Tobias Andersson, Carsten Bormann, Joakim Brorsson, Ben 4202 Campbell, Esko Dijk, Jaro Fietz, Thomas Fossati, Martin Gunnarsson, 4203 Klaus Hartke, Mirja Kuehlewind, Kathleen Moriarty, Eric Rescorla, 4204 Michael Richardson, Adam Roach, Jim Schaad, Peter van der Stok, Dave 4205 Thaler, Martin Thomson, Marco Tiloca, William Vignat, and Malisa 4206 Vucinic. 4208 Ludwig Seitz and Goeran Selander worked on this document as part of 4209 the CelticPlus project CyberWI, with funding from Vinnova. 4211 Authors' Addresses 4213 Goeran Selander 4214 Ericsson AB 4216 Email: goran.selander@ericsson.com 4218 John Mattsson 4219 Ericsson AB 4221 Email: john.mattsson@ericsson.com 4223 Francesca Palombini 4224 Ericsson AB 4226 Email: francesca.palombini@ericsson.com 4228 Ludwig Seitz 4229 RISE SICS 4231 Email: ludwig.seitz@ri.se