idnits 2.17.1 draft-ietf-core-object-security-15.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 : ---------------------------------------------------------------------------- ** There are 5 instances of too long lines in the document, the longest one being 5 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (August 31, 2018) is 2063 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 6347 (Obsoleted by RFC 9147) ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 8152 (Obsoleted by RFC 9052, RFC 9053) == Outdated reference: A later version (-46) exists of draft-ietf-ace-oauth-authz-13 == Outdated reference: A later version (-19) exists of draft-ietf-ace-oscore-profile-02 == Outdated reference: A later version (-08) exists of draft-ietf-cbor-cddl-05 == Outdated reference: A later version (-14) exists of draft-ietf-core-echo-request-tag-02 == Outdated reference: A later version (-21) exists of draft-ietf-core-oscore-groupcomm-02 == Outdated reference: A later version (-06) exists of draft-mattsson-core-coap-actuators-05 Summary: 6 errors (**), 0 flaws (~~), 7 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CoRE Working Group G. Selander 3 Internet-Draft J. Mattsson 4 Intended status: Standards Track F. Palombini 5 Expires: March 4, 2019 Ericsson AB 6 L. Seitz 7 RISE SICS 8 August 31, 2018 10 Object Security for Constrained RESTful Environments (OSCORE) 11 draft-ietf-core-object-security-15 13 Abstract 15 This document defines Object Security for Constrained RESTful 16 Environments (OSCORE), a method for application-layer protection of 17 the Constrained Application Protocol (CoAP), using CBOR Object 18 Signing and Encryption (COSE). OSCORE provides end-to-end protection 19 between endpoints communicating using CoAP or CoAP-mappable HTTP. 20 OSCORE is designed for constrained nodes and networks supporting a 21 range of proxy operations, including translation between different 22 transport protocols. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at https://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on March 4, 2019. 41 Copyright Notice 43 Copyright (c) 2018 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (https://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 59 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 60 2. The OSCORE Option . . . . . . . . . . . . . . . . . . . . . . 7 61 3. The Security Context . . . . . . . . . . . . . . . . . . . . 7 62 3.1. Security Context Definition . . . . . . . . . . . . . . . 8 63 3.2. Establishment of Security Context Parameters . . . . . . 10 64 3.3. Requirements on the Security Context Parameters . . . . . 13 65 4. Protected Message Fields . . . . . . . . . . . . . . . . . . 14 66 4.1. CoAP Options . . . . . . . . . . . . . . . . . . . . . . 15 67 4.2. CoAP Header Fields and Payload . . . . . . . . . . . . . 23 68 4.3. Signaling Messages . . . . . . . . . . . . . . . . . . . 24 69 5. The COSE Object . . . . . . . . . . . . . . . . . . . . . . . 24 70 5.1. Kid Context . . . . . . . . . . . . . . . . . . . . . . . 26 71 5.2. AEAD Nonce . . . . . . . . . . . . . . . . . . . . . . . 26 72 5.3. Plaintext . . . . . . . . . . . . . . . . . . . . . . . . 27 73 5.4. Additional Authenticated Data . . . . . . . . . . . . . . 28 74 6. OSCORE Header Compression . . . . . . . . . . . . . . . . . . 29 75 6.1. Encoding of the OSCORE Option Value . . . . . . . . . . . 30 76 6.2. Encoding of the OSCORE Payload . . . . . . . . . . . . . 31 77 6.3. Examples of Compressed COSE Objects . . . . . . . . . . . 31 78 7. Message Binding, Sequence Numbers, Freshness and Replay 79 Protection . . . . . . . . . . . . . . . . . . . . . . . . . 34 80 7.1. Message Binding . . . . . . . . . . . . . . . . . . . . . 34 81 7.2. Sequence Numbers . . . . . . . . . . . . . . . . . . . . 34 82 7.3. Freshness . . . . . . . . . . . . . . . . . . . . . . . . 34 83 7.4. Replay Protection . . . . . . . . . . . . . . . . . . . . 35 84 7.5. Losing Part of the Context State . . . . . . . . . . . . 36 85 8. Processing . . . . . . . . . . . . . . . . . . . . . . . . . 37 86 8.1. Protecting the Request . . . . . . . . . . . . . . . . . 37 87 8.2. Verifying the Request . . . . . . . . . . . . . . . . . . 38 88 8.3. Protecting the Response . . . . . . . . . . . . . . . . . 39 89 8.4. Verifying the Response . . . . . . . . . . . . . . . . . 40 90 9. Web Linking . . . . . . . . . . . . . . . . . . . . . . . . . 42 91 10. CoAP-to-CoAP Forwarding Proxy . . . . . . . . . . . . . . . . 43 92 11. HTTP Operations . . . . . . . . . . . . . . . . . . . . . . . 44 93 11.1. The HTTP OSCORE Header Field . . . . . . . . . . . . . . 44 94 11.2. CoAP-to-HTTP Mapping . . . . . . . . . . . . . . . . . . 45 95 11.3. HTTP-to-CoAP Mapping . . . . . . . . . . . . . . . . . . 45 96 11.4. HTTP Endpoints . . . . . . . . . . . . . . . . . . . . . 46 97 11.5. Example: HTTP Client and CoAP Server . . . . . . . . . . 46 98 11.6. Example: CoAP Client and HTTP Server . . . . . . . . . . 48 99 12. Security Considerations . . . . . . . . . . . . . . . . . . . 49 100 12.1. End-to-end Protection . . . . . . . . . . . . . . . . . 49 101 12.2. Security Context Establishment . . . . . . . . . . . . . 50 102 12.3. Master Secret . . . . . . . . . . . . . . . . . . . . . 50 103 12.4. Replay Protection . . . . . . . . . . . . . . . . . . . 50 104 12.5. Client Aliveness . . . . . . . . . . . . . . . . . . . . 51 105 12.6. Cryptographic Considerations . . . . . . . . . . . . . . 51 106 12.7. Message Segmentation . . . . . . . . . . . . . . . . . . 51 107 12.8. Privacy Considerations . . . . . . . . . . . . . . . . . 52 108 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 53 109 13.1. COSE Header Parameters Registry . . . . . . . . . . . . 53 110 13.2. CoAP Option Numbers Registry . . . . . . . . . . . . . . 53 111 13.3. CoAP Signaling Option Numbers Registry . . . . . . . . . 54 112 13.4. Header Field Registrations . . . . . . . . . . . . . . . 55 113 13.5. Media Type Registrations . . . . . . . . . . . . . . . . 55 114 13.6. CoAP Content-Formats Registry . . . . . . . . . . . . . 57 115 13.7. OSCORE Flag Bits Registry . . . . . . . . . . . . . . . 57 116 13.8. Expert Review Instructions . . . . . . . . . . . . . . . 58 117 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 59 118 14.1. Normative References . . . . . . . . . . . . . . . . . . 59 119 14.2. Informative References . . . . . . . . . . . . . . . . . 60 120 Appendix A. Scenario Examples . . . . . . . . . . . . . . . . . 62 121 A.1. Secure Access to Sensor . . . . . . . . . . . . . . . . . 63 122 A.2. Secure Subscribe to Sensor . . . . . . . . . . . . . . . 64 123 Appendix B. Deployment Examples . . . . . . . . . . . . . . . . 65 124 B.1. Master Secret Used Once . . . . . . . . . . . . . . . . . 65 125 B.2. Master Secret Used Multiple Times . . . . . . . . . . . . 65 126 Appendix C. Test Vectors . . . . . . . . . . . . . . . . . . . . 66 127 C.1. Test Vector 1: Key Derivation with Master Salt . . . . . 67 128 C.2. Test Vector 2: Key Derivation without Master Salt . . . . 68 129 C.3. Test Vector 3: Key Derivation with ID Context . . . . . . 70 130 C.4. Test Vector 4: OSCORE Request, Client . . . . . . . . . . 71 131 C.5. Test Vector 5: OSCORE Request, Client . . . . . . . . . . 73 132 C.6. Test Vector 6: OSCORE Request, Client . . . . . . . . . . 74 133 C.7. Test Vector 7: OSCORE Response, Server . . . . . . . . . 75 134 C.8. Test Vector 8: OSCORE Response with Partial IV, Server . 76 135 Appendix D. Overview of Security Properties . . . . . . . . . . 77 136 D.1. Supporting Proxy Operations . . . . . . . . . . . . . . . 77 137 D.2. Protected Message Fields . . . . . . . . . . . . . . . . 78 138 D.3. Uniqueness of (key, nonce) . . . . . . . . . . . . . . . 79 139 D.4. Unprotected Message Fields . . . . . . . . . . . . . . . 80 140 Appendix E. CDDL Summary . . . . . . . . . . . . . . . . . . . . 83 141 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 83 142 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 84 144 1. Introduction 146 The Constrained Application Protocol (CoAP) [RFC7252] is a web 147 transfer protocol, designed for constrained nodes and networks 148 [RFC7228], and may be mapped from HTTP [RFC8075]. CoAP specifies the 149 use of proxies for scalability and efficiency and references DTLS 150 [RFC6347] for security. CoAP-to-CoAP, HTTP-to-CoAP, and CoAP-to-HTTP 151 proxies require DTLS or TLS [RFC8446] to be terminated at the proxy. 152 The proxy therefore not only has access to the data required for 153 performing the intended proxy functionality, but is also able to 154 eavesdrop on, or manipulate any part of, the message payload and 155 metadata in transit between the endpoints. The proxy can also 156 inject, delete, or reorder packets since they are no longer protected 157 by (D)TLS. 159 This document defines the Object Security for Constrained RESTful 160 Environments (OSCORE) security protocol, protecting CoAP and CoAP- 161 mappable HTTP requests and responses end-to-end across intermediary 162 nodes such as CoAP forward proxies and cross-protocol translators 163 including HTTP-to-CoAP proxies [RFC8075]. In addition to the core 164 CoAP features defined in [RFC7252], OSCORE supports the Observe 165 [RFC7641], Block-wise [RFC7959], and No-Response [RFC7967] options, 166 as well as the PATCH and FETCH methods [RFC8132]. An analysis of 167 end-to-end security for CoAP messages through some types of 168 intermediary nodes is performed in 169 [I-D.hartke-core-e2e-security-reqs]. OSCORE essentially protects the 170 RESTful interactions; the request method, the requested resource, the 171 message payload, etc. (see Section 4). OSCORE protects neither the 172 CoAP Messaging Layer nor the CoAP Token which may change between the 173 endpoints, and those are therefore processed as defined in [RFC7252]. 174 Additionally, since the message formats for CoAP over unreliable 175 transport [RFC7252] and for CoAP over reliable transport [RFC8323] 176 differ only in terms of CoAP Messaging Layer, OSCORE can be applied 177 to both unreliable and reliable transports (see Figure 1). 179 +-----------------------------------+ 180 | Application | 181 +-----------------------------------+ 182 +-----------------------------------+ \ 183 | Requests / Responses / Signaling | | 184 |-----------------------------------| | 185 | OSCORE | | CoAP 186 |-----------------------------------| | 187 | Messaging Layer / Message Framing | | 188 +-----------------------------------+ / 189 +-----------------------------------+ 190 | UDP / TCP / ... | 191 +-----------------------------------+ 193 Figure 1: Abstract Layering of CoAP with OSCORE 195 OSCORE works in very constrained nodes and networks, thanks to its 196 small message size and the restricted code and memory requirements in 197 addition to what is required by CoAP. Examples of the use of OSCORE 198 are given in Appendix A. OSCORE may be used over any underlying 199 layer, such as e.g. UDP or TCP, and with non-IP transports (e.g., 200 [I-D.bormann-6lo-coap-802-15-ie]). OSCORE may also be used in 201 different ways with HTTP. OSCORE messages may be transported in 202 HTTP, and OSCORE may also be used to protect CoAP-mappable HTTP 203 messages, as described below. 205 OSCORE is designed to protect as much information as possible while 206 still allowing CoAP proxy operations (Section 10). It works with 207 existing CoAP-to-CoAP forward proxies [RFC7252], but an OSCORE-aware 208 proxy will be more efficient. HTTP-to-CoAP proxies [RFC8075] and 209 CoAP-to-HTTP proxies can also be used with OSCORE, as specified in 210 Section 11. OSCORE may be used together with TLS or DTLS over one or 211 more hops in the end-to-end path, e.g. transported with HTTPS in one 212 hop and with plain CoAP in another hop. The use of OSCORE does not 213 affect the URI scheme and OSCORE can therefore be used with any URI 214 scheme defined for CoAP or HTTP. The application decides the 215 conditions for which OSCORE is required. 217 OSCORE uses pre-shared keys which may have been established out-of- 218 band or with a key establishment protocol (see Section 3.2). The 219 technical solution builds on CBOR Object Signing and Encryption 220 (COSE) [RFC8152], providing end-to-end encryption, integrity, replay 221 protection, and binding of response to request. A compressed version 222 of COSE is used, as specified in Section 6. The use of OSCORE is 223 signaled in CoAP with a new option (Section 2), and in HTTP with a 224 new header field (Section 11.1) and content type (Section 13.5). The 225 solution transforms a CoAP/HTTP message into an "OSCORE message" 226 before sending, and vice versa after receiving. The OSCORE message 227 is a CoAP/HTTP message related to the original message in the 228 following way: the original CoAP/HTTP message is translated to CoAP 229 (if not already in CoAP) and protected in a COSE object. The 230 encrypted message fields of this COSE object are transported in the 231 CoAP payload/HTTP body of the OSCORE message, and the OSCORE option/ 232 header field is included in the message. A sketch of an exchange of 233 OSCORE messages, in the case of the original message being CoAP, is 234 provided in Figure 2. The use of OSCORE with HTTP is detailed in 235 Section 11. 237 Client Server 238 | OSCORE request - POST example.com: | 239 | Header, Token, | 240 | Options: OSCORE, ..., | 241 | Payload: COSE ciphertext | 242 +--------------------------------------------->| 243 | | 244 |<---------------------------------------------+ 245 | OSCORE response - 2.04 (Changed): | 246 | Header, Token, | 247 | Options: OSCORE, ..., | 248 | Payload: COSE ciphertext | 249 | | 251 Figure 2: Sketch of CoAP with OSCORE 253 An implementation supporting this specification MAY implement only 254 the client part, MAY implement only the server part, or MAY implement 255 only one of the proxy parts. 257 1.1. Terminology 259 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 260 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 261 "OPTIONAL" in this document are to be interpreted as described in BCP 262 14 [RFC2119] [RFC8174] when, and only when, they appear in all 263 capitals, as shown here. 265 Readers are expected to be familiar with the terms and concepts 266 described in CoAP [RFC7252], Observe [RFC7641], Block-wise [RFC7959], 267 COSE [RFC8152], CBOR [RFC7049], CDDL [I-D.ietf-cbor-cddl] as 268 summarized in Appendix E, and constrained environments [RFC7228]. 270 The term "hop" is used to denote a particular leg in the end-to-end 271 path. The concept "hop-by-hop" (as in "hop-by-hop encryption" or 272 "hop-by-hop fragmentation") opposed to "end-to-end", is used in this 273 document to indicate that the messages are processed accordingly in 274 the intermediaries, rather than just forwarded to the next node. 276 The term "stop processing" is used throughout the document to denote 277 that the message is not passed up to the CoAP Request/Response layer 278 (see Figure 1). 280 The terms Common/Sender/Recipient Context, Master Secret/Salt, Sender 281 ID/Key, Recipient ID/Key, ID Context, and Common IV are defined in 282 Section 3.1. 284 2. The OSCORE Option 286 The OSCORE option defined in this section (see Figure 3, which 287 extends Table 4: Options of [RFC7252]) indicates that the CoAP 288 message is an OSCORE message and that it contains a compressed COSE 289 object (see Sections 5 and 6). The OSCORE option is critical, safe 290 to forward, part of the cache key, and not repeatable. 292 +------+---+---+---+---+----------------+--------+--------+---------+ 293 | No. | C | U | N | R | Name | Format | Length | Default | 294 +------+---+---+---+---+----------------+--------+--------+---------+ 295 | TBD1 | x | | | | OSCORE | (*) | 0-255 | (none) | 296 +------+---+---+---+---+----------------+--------+--------+---------+ 297 C = Critical, U = Unsafe, N = NoCacheKey, R = Repeatable 298 (*) See below. 300 Figure 3: The OSCORE Option 302 The OSCORE option includes the OSCORE flag bits (Section 6), the 303 Sender Sequence Number, the Sender ID, and the ID Context when these 304 fields are present (Section 3). The detailed format and length is 305 specified in Section 6. If the OSCORE flag bits are all zero (0x00) 306 the Option value SHALL be empty (Option Length = 0). An endpoint 307 receiving a CoAP message without payload, that also contains an 308 OSCORE option SHALL treat it as malformed and reject it. 310 A successful response to a request with the OSCORE option SHALL 311 contain the OSCORE option. Whether error responses contain the 312 OSCORE option depends on the error type (see Section 8). 314 For CoAP proxy operations, see Section 10. 316 3. The Security Context 318 OSCORE requires that client and server establish a shared security 319 context used to process the COSE objects. OSCORE uses COSE with an 320 Authenticated Encryption with Additional Data (AEAD, [RFC5116]) 321 algorithm for protecting message data between a client and a server. 322 In this section, we define the security context and how it is derived 323 in client and server based on a shared secret and a key derivation 324 function. 326 3.1. Security Context Definition 328 The security context is the set of information elements necessary to 329 carry out the cryptographic operations in OSCORE. For each endpoint, 330 the security context is composed of a "Common Context", a "Sender 331 Context", and a "Recipient Context". 333 The endpoints protect messages to send using the Sender Context and 334 verify messages received using the Recipient Context, both contexts 335 being derived from the Common Context and other data. Clients and 336 servers need to be able to retrieve the correct security context to 337 use. 339 An endpoint uses its Sender ID (SID) to derive its Sender Context, 340 and the other endpoint uses the same ID, now called Recipient ID 341 (RID), to derive its Recipient Context. In communication between two 342 endpoints, the Sender Context of one endpoint matches the Recipient 343 Context of the other endpoint, and vice versa. Thus, the two 344 security contexts identified by the same IDs in the two endpoints are 345 not the same, but they are partly mirrored. Retrieval and use of the 346 security context are shown in Figure 4. 348 .------------------------------------------------. 349 | Common Context | 350 +---------------------.----.---------------------+ 351 | Sender Context | = | Recipient Context | 352 +---------------------+ +---------------------+ 353 | Recipient Context | = | Sender Context | 354 '---------------------' '---------------------' 355 Client Server 356 | | 357 Retrieve context for | OSCORE request: | 358 target resource | Token = Token1, | 359 Protect request with | kid = SID, ... | 360 Sender Context +---------------------->| Retrieve context with 361 | | RID = kid 362 | | Verify request with 363 | | Recipient Context 364 | OSCORE response: | Protect response with 365 | Token = Token1, ... | Sender Context 366 Retrieve context with |<----------------------+ 367 Token = Token1 | | 368 Verify request with | | 369 Recipient Context | | 371 Figure 4: Retrieval and Use of the Security Context 373 The Common Context contains the following parameters: 375 o AEAD Algorithm. The COSE AEAD algorithm to use for encryption. 377 o An HMAC-based key derivation function HKDF [RFC5869] used to 378 derive Sender Key, Recipient Key, and Common IV. 380 o Master Secret. Variable length, random byte string (see 381 Section 12.3) used to derive AEAD keys and Common IV. 383 o Master Salt. Optional variable length byte string containing the 384 salt used to derive AEAD keys and Common IV. 386 o ID Context. Optional variable length byte string providing 387 additional information to identify the Common Context and to 388 derive AEAD keys and Common IV. The use of ID Context is 389 described in Section 5.1. 391 o Common IV. Byte string derived from Master Secret, Master Salt, 392 and ID Context. Used to generate the AEAD Nonce (see 393 Section 5.2). Same length as the nonce of the AEAD Algorithm. 395 The Sender Context contains the following parameters: 397 o Sender ID. Byte string used to identify the Sender Context, to 398 derive AEAD keys and Common IV, and to assure unique AEAD nonces. 399 Maximum length is determined by the AEAD Algorithm. 401 o Sender Key. Byte string containing the symmetric AEAD key to 402 protect messages to send. Derived from Common Context and Sender 403 ID. Length is determined by the AEAD Algorithm. 405 o Sender Sequence Number. Non-negative integer used by the sender 406 to enumerate requests and certain responses, e.g. Observe 407 notifications. Used as 'Partial IV' [RFC8152] to generate unique 408 AEAD nonces. Maximum value is determined by the AEAD Algorithm. 409 Initialization is described in Section 3.2.2. 411 The Recipient Context contains the following parameters: 413 o Recipient ID. Byte string used to identify the Recipient Context, 414 to derive AEAD keys and Common IV, and to assure unique AEAD 415 nonces. Maximum length is determined by the AEAD Algorithm. 417 o Recipient Key. Byte string containing the symmetric AEAD key to 418 verify messages received. Derived from Common Context and 419 Recipient ID. Length is determined by the AEAD Algorithm. 421 o Replay Window (Server only). The replay window to verify requests 422 received. Replay protection is described in Section 7.4 and 423 Section 3.2.2. 425 All parameters except Sender Sequence Number and Replay Window are 426 immutable once the security context is established. An endpoint may 427 free up memory by not storing the Common IV, Sender Key, and 428 Recipient Key, deriving them when needed. Alternatively, an endpoint 429 may free up memory by not storing the Master Secret and Master Salt 430 after the other parameters have been derived. 432 Endpoints MAY operate as both client and server and use the same 433 security context for those roles. Independent of being client or 434 server, the endpoint protects messages to send using its Sender 435 Context, and verifies messages received using its Recipient Context. 436 The endpoints MUST NOT change the Sender/Recipient ID when changing 437 roles. In other words, changing the roles does not change the set of 438 AEAD keys to be used. 440 3.2. Establishment of Security Context Parameters 442 Each endpoint derives the parameters in the security context from a 443 small set of input parameters. The following input parameters SHALL 444 be pre-established: 446 o Master Secret 448 o Sender ID 450 o Recipient ID 452 The following input parameters MAY be pre-established. In case any 453 of these parameters is not pre-established, the default value 454 indicated below is used: 456 o AEAD Algorithm 458 * Default is AES-CCM-16-64-128 (COSE algorithm encoding: 10) 460 o Master Salt 462 * Default is the empty byte string 464 o HMAC-based Key Derivation Function (HKDF) 466 * Default is HKDF SHA-256 468 o Replay Window 470 * Default is DTLS-type replay protection with a window size of 32 471 [RFC6347] 473 All input parameters need to be known to and agreed on by both 474 endpoints, but the replay window may be different in the two 475 endpoints. The way the input parameters are pre-established, is 476 application specific. Considerations of security context 477 establishment are given in Section 12.2 and examples of deploying 478 OSCORE in Appendix B. 480 3.2.1. Derivation of Sender Key, Recipient Key, and Common IV 482 The HKDF MUST be one of the HMAC-based HKDF [RFC5869] algorithms 483 defined for COSE [RFC8152]. HKDF SHA-256 is mandatory to implement. 484 The security context parameters Sender Key, Recipient Key, and Common 485 IV SHALL be derived from the input parameters using the HKDF, which 486 consists of the composition of the HKDF-Extract and HKDF-Expand steps 487 [RFC5869]: 489 output parameter = HKDF(salt, IKM, info, L) 491 where: 493 o salt is the Master Salt as defined above 494 o IKM is the Master Secret as defined above 496 o info is the serialization of a CBOR array consisting of (the 497 notation follows Appendix E): 499 info = [ 500 id : bstr, 501 id_context : bstr / nil, 502 alg_aead : int / tstr, 503 type : tstr, 504 L : uint 505 ] 507 where: 509 o id is the Sender ID or Recipient ID when deriving Sender Key and 510 Recipient Key, respectively, and the empty byte string when 511 deriving the Common IV. 513 o id_context is the ID Context, or nil if ID Context is not 514 provided. 516 o alg_aead is the AEAD Algorithm, encoded as defined in [RFC8152]. 518 o type is "Key" or "IV". The label is an ASCII string, and does not 519 include a trailing NUL byte. 521 o L is the size of the key/nonce for the AEAD algorithm used, in 522 bytes. 524 For example, if the algorithm AES-CCM-16-64-128 (see Section 10.2 in 525 [RFC8152]) is used, the integer value for alg_aead is 10, the value 526 for L is 16 for keys and 13 for the Common IV. Assuming use of the 527 default algorithms HKDF SHA-256 and AES-CCM-16-64-128, the extract 528 phase of HKDF produces a pseudorandom key (PRK) as follows: 530 PRK = HMAC-SHA-256(Master Salt, Master Secret) 532 and as L is smaller than the hash function output size, the expand 533 phase of HKDF consists of a single HMAC invocation, and the Sender 534 Key, Recipient Key, and Common IV are therefore the first 16 or 13 535 bytes of 537 output parameter = HMAC-SHA-256(PRK, info | 0x01) 539 where different info are used for each derived parameter and where | 540 denotes byte string concatenation. 542 Note that [RFC5869] specifies that if the salt is not provided, it is 543 set to a string of zeros. For implementation purposes, not providing 544 the salt is the same as setting the salt to the empty byte string. 545 OSCORE sets the salt default value to empty byte string, which is 546 converted to a string of zeroes (see Section 2.2 of [RFC5869]). 548 3.2.2. Initial Sequence Numbers and Replay Window 550 The Sender Sequence Number is initialized to 0. The supported types 551 of replay protection and replay window length is application specific 552 and depends on how OSCORE is transported, see Section 7.4. The 553 default is DTLS-type replay protection with a window size of 32 554 initiated as described in Section 4.1.2.6 of [RFC6347]. 556 3.3. Requirements on the Security Context Parameters 558 To ensure unique Sender Keys, the quartet (Master Secret, Master 559 Salt, ID Context, Sender ID) MUST be unique, i.e. the pair (ID 560 Context, Sender ID) SHALL be unique in the set of all security 561 contexts using the same Master Secret and Master Salt. This means 562 that Sender ID SHALL be unique in the set of all security contexts 563 using the same Master Secret, Master Salt, and ID Context; such a 564 requirement guarantees unique (key, nonce) pairs for the AEAD. 566 Different methods can be used to assign Sender IDs: a protocol that 567 allows the parties to negotiate locally unique identifiers, a trusted 568 third party (e.g., [I-D.ietf-ace-oauth-authz]), or the identifiers 569 can be assigned out-of-band. The Sender IDs can be very short (note 570 that the empty string is a legitimate value). The maximum length of 571 Sender ID in bytes equals the length of AEAD nonce minus 6, see 572 Section 5.2. For AES-CCM-16-64-128 the maximum length of Sender ID 573 is 7 bytes. 575 To simplify retrieval of the right Recipient Context, the Recipient 576 ID SHOULD be unique in the sets of all Recipient Contexts used by an 577 endpoint. If an endpoint has the same Recipient ID with different 578 Recipient Contexts, i.e. the Recipient Contexts are derived from 579 different Common Contexts, then the endpoint may need to try multiple 580 times before verifying the right security context associated to the 581 Recipient ID. 583 The ID Context is used to distinguish between security contexts. The 584 methods used for assigning Sender ID can also be used for assigning 585 the ID Context. Additionally, the ID Context can be generated by the 586 client (see Appendix B.2). ID Context can be arbitrarily long. 588 4. Protected Message Fields 590 OSCORE transforms a CoAP message (which may have been generated from 591 an HTTP message) into an OSCORE message, and vice versa. OSCORE 592 protects as much of the original message as possible while still 593 allowing certain proxy operations (see Sections 10 and 11). This 594 section defines how OSCORE protects the message fields and transfers 595 them end-to-end between client and server (in any direction). 597 The remainder of this section and later sections focus on the 598 behavior in terms of CoAP messages. If HTTP is used for a particular 599 hop in the end-to-end path, then this section applies to the 600 conceptual CoAP message that is mappable to/from the original HTTP 601 message as discussed in Section 11. That is, an HTTP message is 602 conceptually transformed to a CoAP message and then to an OSCORE 603 message, and similarly in the reverse direction. An actual 604 implementation might translate directly from HTTP to OSCORE without 605 the intervening CoAP representation. 607 Protection of Signaling messages (Section 5 of [RFC8323]) is 608 specified in Section 4.3. The other parts of this section target 609 Request/Response messages. 611 Message fields of the CoAP message may be protected end-to-end 612 between CoAP client and CoAP server in different ways: 614 o Class E: encrypted and integrity protected, 616 o Class I: integrity protected only, or 618 o Class U: unprotected. 620 The sending endpoint SHALL transfer Class E message fields in the 621 ciphertext of the COSE object in the OSCORE message. The sending 622 endpoint SHALL include Class I message fields in the Additional 623 Authenticated Data (AAD) of the AEAD algorithm, allowing the 624 receiving endpoint to detect if the value has changed in transfer. 625 Class U message fields SHALL NOT be protected in transfer. Class I 626 and Class U message field values are transferred in the header or 627 options part of the OSCORE message, which is visible to proxies. 629 Message fields not visible to proxies, i.e., transported in the 630 ciphertext of the COSE object, are called "Inner" (Class E). Message 631 fields transferred in the header or options part of the OSCORE 632 message, which is visible to proxies, are called "Outer" (Class I or 633 U). There are currently no Class I options defined. 635 An OSCORE message may contain both an Inner and an Outer instance of 636 a certain CoAP message field. Inner message fields are intended for 637 the receiving endpoint, whereas Outer message fields are used to 638 enable proxy operations. 640 4.1. CoAP Options 642 A summary of how options are protected is shown in Figure 5. Note 643 that some options may have both Inner and Outer message fields which 644 are protected accordingly. Certain options require special 645 processing as is described in Section 4.1.3. 647 +------+-----------------+---+---+ 648 | No. | Name | E | U | 649 +------+-----------------+---+---+ 650 | 1 | If-Match | x | | 651 | 3 | Uri-Host | | x | 652 | 4 | ETag | x | | 653 | 5 | If-None-Match | x | | 654 | 6 | Observe | x | x | 655 | 7 | Uri-Port | | x | 656 | 8 | Location-Path | x | | 657 | TBD1 | OSCORE | | x | 658 | 11 | Uri-Path | x | | 659 | 12 | Content-Format | x | | 660 | 14 | Max-Age | x | x | 661 | 15 | Uri-Query | x | | 662 | 17 | Accept | x | | 663 | 20 | Location-Query | x | | 664 | 23 | Block2 | x | x | 665 | 27 | Block1 | x | x | 666 | 28 | Size2 | x | x | 667 | 35 | Proxy-Uri | | x | 668 | 39 | Proxy-Scheme | | x | 669 | 60 | Size1 | x | x | 670 | 258 | No-Response | x | x | 671 +------+-----------------+---+---+ 673 E = Encrypt and Integrity Protect (Inner) 674 U = Unprotected (Outer) 676 Figure 5: Protection of CoAP Options 678 Options that are unknown or for which OSCORE processing is not 679 defined SHALL be processed as class E (and no special processing). 680 Specifications of new CoAP options SHOULD define how they are 681 processed with OSCORE. A new COAP option SHOULD be of class E unless 682 it requires proxy processing. If a new CoAP option is of class U, 683 the potential issues with the option being unprotected SHOULD be 684 documented (see Appendix D.4). 686 4.1.1. Inner Options 688 Inner option message fields (class E) are used to communicate 689 directly with the other endpoint. 691 The sending endpoint SHALL write the Inner option message fields 692 present in the original CoAP message into the plaintext of the COSE 693 object (Section 5.3), and then remove the Inner option message fields 694 from the OSCORE message. 696 The processing of Inner option message fields by the receiving 697 endpoint is specified in Sections 8.2 and 8.4. 699 4.1.2. Outer Options 701 Outer option message fields (Class U or I) are used to support proxy 702 operations, see Appendix D.1. 704 The sending endpoint SHALL include the Outer option message field 705 present in the original message in the options part of the OSCORE 706 message. All Outer option message fields, including the OSCORE 707 option, SHALL be encoded as described in Section 3.1 of [RFC7252], 708 where the delta is the difference to the previously included instance 709 of Outer option message field. 711 The processing of Outer options by the receiving endpoint is 712 specified in Sections 8.2 and 8.4. 714 A procedure for integrity-protection-only of Class I option message 715 fields is specified in Section 5.4. Specifications that introduce 716 repeatable Class I options MUST specify that proxies MUST NOT change 717 the order of the instances of such an option in the CoAP message. 719 Note: There are currently no Class I option message fields defined. 721 4.1.3. Special Options 723 Some options require special processing as specified in this section. 725 4.1.3.1. Max-Age 727 An Inner Max-Age message field is used to indicate the maximum time a 728 response may be cached by the client (as defined in [RFC7252]), end- 729 to-end from the server to the client, taking into account that the 730 option is not accessible to proxies. The Inner Max-Age SHALL be 731 processed by OSCORE as a normal Inner option, specified in 732 Section 4.1.1. 734 An Outer Max-Age message field is used to avoid unnecessary caching 735 of error responses caused by OSCORE processing at OSCORE-unaware 736 intermediary nodes. A server MAY set a Class U Max-Age message field 737 with value zero to such error responses, described in Sections 7.4, 738 8.2, and 8.4, since these error responses are cacheable, but 739 subsequent OSCORE requests would never create a hit in the 740 intermediary caching it. Setting the Outer Max-Age to zero relieves 741 the intermediary from uselessly caching responses. Successful OSCORE 742 responses do not need to include an Outer Max-Age option since the 743 responses appear to the OSCORE-unaware intermediary as 2.04 Changed 744 responses, which are non-cacheable (see Section 4.2). 746 The Outer Max-Age message field is processed according to 747 Section 4.1.2. 749 4.1.3.2. Uri-Host and Uri-Port 751 When the Uri-Host and Uri-Port are set to their default values (see 752 Section 5.10.1 [RFC7252]), they are omitted from the message 753 (Section 5.4.4 of [RFC7252]), which is favorable both for overhead 754 and privacy. 756 In order to support forward proxy operations, Proxy-Scheme, Uri-Host, 757 and Uri-Port need to be Class U. For the use of Proxy-Uri, see 758 Section 4.1.3.3. 760 Manipulation of unprotected message fields (including Uri-Host, Uri- 761 Port, destination IP/port or request scheme) MUST NOT lead to an 762 OSCORE message becoming verified by an unintended server. Different 763 servers SHOULD have different security contexts. 765 4.1.3.3. Proxy-Uri 767 When Proxy-Uri is present, the client SHALL first decompose the 768 Proxy-Uri value of the original CoAP message into the Proxy-Scheme, 769 Uri-Host, Uri-Port, Uri-Path, and Uri-Query options according to 770 Section 6.4 of [RFC7252]. 772 Uri-Path and Uri-Query are class E options and SHALL be protected and 773 processed as Inner options (Section 4.1.1). 775 The Proxy-Uri option of the OSCORE message SHALL be set to the 776 composition of Proxy-Scheme, Uri-Host, and Uri-Port options as 777 specified in Section 6.5 of [RFC7252], and processed as an Outer 778 option of Class U (Section 4.1.2). 780 Note that replacing the Proxy-Uri value with the Proxy-Scheme and 781 Uri-* options works by design for all CoAP URIs (see Section 6 of 782 [RFC7252]). OSCORE-aware HTTP servers should not use the userinfo 783 component of the HTTP URI (as defined in Section 3.2.1 of [RFC3986]), 784 so that this type of replacement is possible in the presence of CoAP- 785 to-HTTP proxies (see Section 11.2). In future specifications of 786 cross-protocol proxying behavior using different URI structures, it 787 is expected that the authors will create Uri-* options that allow 788 decomposing the Proxy-Uri, and specifying the OSCORE processing. 790 An example of how Proxy-Uri is processed is given here. Assume that 791 the original CoAP message contains: 793 o Proxy-Uri = "coap://example.com/resource?q=1" 795 During OSCORE processing, Proxy-Uri is split into: 797 o Proxy-Scheme = "coap" 799 o Uri-Host = "example.com" 801 o Uri-Port = "5683" 803 o Uri-Path = "resource" 805 o Uri-Query = "q=1" 807 Uri-Path and Uri-Query follow the processing defined in 808 Section 4.1.1, and are thus encrypted and transported in the COSE 809 object: 811 o Uri-Path = "resource" 813 o Uri-Query = "q=1" 815 The remaining options are composed into the Proxy-Uri included in the 816 options part of the OSCORE message, which has value: 818 o Proxy-Uri = "coap://example.com" 820 See Sections 6.1 and 12.6 of [RFC7252] for more details. 822 4.1.3.4. The Block Options 824 Block-wise [RFC7959] is an optional feature. An implementation MAY 825 support [RFC7252] and the OSCORE option without supporting block-wise 826 transfers. The Block options (Block1, Block2, Size1, Size2), when 827 Inner message fields, provide secure message segmentation such that 828 each segment can be verified. The Block options, when Outer message 829 fields, enables hop-by-hop fragmentation of the OSCORE message. 830 Inner and Outer block processing may have different performance 831 properties depending on the underlying transport. The end-to-end 832 integrity of the message can be verified both in case of Inner and 833 Outer Block-wise transfers provided all blocks are received. 835 4.1.3.4.1. Inner Block Options 837 The sending CoAP endpoint MAY fragment a CoAP message as defined in 838 [RFC7959] before the message is processed by OSCORE. In this case 839 the Block options SHALL be processed by OSCORE as normal Inner 840 options (Section 4.1.1). The receiving CoAP endpoint SHALL process 841 the OSCORE message before processing Block-wise as defined in 842 [RFC7959]. 844 4.1.3.4.2. Outer Block Options 846 Proxies MAY fragment an OSCORE message using [RFC7959], by 847 introducing Block option message fields that are Outer 848 (Section 4.1.2). Note that the Outer Block options are neither 849 encrypted nor integrity protected. As a consequence, a proxy can 850 maliciously inject block fragments indefinitely, since the receiving 851 endpoint needs to receive the last block (see [RFC7959]) to be able 852 to compose the OSCORE message and verify its integrity. Therefore, 853 applications supporting OSCORE and [RFC7959] MUST specify a security 854 policy defining a maximum unfragmented message size 855 (MAX_UNFRAGMENTED_SIZE) considering the maximum size of message which 856 can be handled by the endpoints. Messages exceeding this size SHOULD 857 be fragmented by the sending endpoint using Inner Block options 858 (Section 4.1.3.4.1). 860 An endpoint receiving an OSCORE message with an Outer Block option 861 SHALL first process this option according to [RFC7959], until all 862 blocks of the OSCORE message have been received, or the cumulated 863 message size of the blocks exceeds MAX_UNFRAGMENTED_SIZE. In the 864 former case, the processing of the OSCORE message continues as 865 defined in this document. In the latter case the message SHALL be 866 discarded. 868 Because of encryption of Uri-Path and Uri-Query, messages to the same 869 server may, from the point of view of a proxy, look like they also 870 target the same resource. A proxy SHOULD mitigate a potential mix-up 871 of blocks from concurrent requests to the same server, for example 872 using the Request-Tag processing specified in Section 3.3.2 of 873 [I-D.ietf-core-echo-request-tag]. 875 4.1.3.5. Observe 877 Observe [RFC7641] is an optional feature. An implementation MAY 878 support [RFC7252] and the OSCORE option without supporting [RFC7641], 879 in which case the Observe related processing can be omitted. 881 The support for Observe [RFC7641] with OSCORE targets the 882 requirements on forwarding of Section 2.2.1 of 883 [I-D.hartke-core-e2e-security-reqs], i.e. that observations go 884 through intermediary nodes, as illustrated in Figure 8 of [RFC7641]. 886 Inner Observe SHALL be used to protect the value of the Observe 887 option between the endpoints. Outer Observe SHALL be used to support 888 forwarding by intermediary nodes. 890 The server SHALL include a new Partial IV (see Section 5) in 891 responses (with or without the Observe option) to Observe 892 registrations, except for the first response where Partial IV MAY be 893 omitted. 895 For cancellations, Section 3.6 of [RFC7641] specifies that all 896 options MUST be identical to those in the registration request except 897 for Observe and the set of ETag Options. For OSCORE messages, this 898 matching is to be done to the options in the decrypted message. 900 [RFC7252] does not specify how the server should act upon receiving 901 the same Token in different requests. When using OSCORE, the server 902 SHOULD NOT remove an active observation just because it receives a 903 request with the same Token. 905 Since POST with Observe is not defined, for messages with Observe, 906 the Outer Code MUST be set to 0.05 (FETCH) for requests and to 2.05 907 (Content) for responses (see Section 4.2). 909 4.1.3.5.1. Registrations and Cancellations 911 The Inner and Outer Observe in the request MUST contain the Observe 912 value of the original CoAP request; 0 (registration) or 1 913 (cancellation). 915 Every time a client issues a new Observe request, a new Partial IV 916 MUST be used (see Section 5), and so the payload and OSCORE option 917 are changed. The server uses the Partial IV of the new request as 918 the 'request_piv' of all associated notifications (see Section 5.4). 920 Intermediaries are not assumed to have access to the OSCORE security 921 context used by the endpoints, and thus cannot make requests or 922 transform responses with the OSCORE option which verify at the 923 receiving endpoint as coming from the other endpoint. This has the 924 following consequences and limitations for Observe operations. 926 o An intermediary node removing the Outer Observe 0 does not change 927 the registration request to a request without Observe (see 928 Section 2 of [RFC7641]). Instead other means for cancellation may 929 be used as described in Section 3.6 of [RFC7641]. 931 o An intermediary node is not able to transform a normal response 932 into an OSCORE protected Observe notification (see figure 7 of 933 [RFC7641]) which verifies as coming from the server. 935 o An intermediary node is not able to initiate an OSCORE protected 936 Observe registration (Observe with value 0) which verifies as 937 coming from the client. An OSCORE-aware intermediary SHALL NOT 938 initiate registrations of observations (see Section 10). If an 939 OSCORE-unaware proxy re-sends an old registration message from a 940 client this will trigger the replay protection mechanism in the 941 server. To prevent this from resulting in the OSCORE-unaware 942 proxy to cancel of the registration, a server MAY respond to a 943 replayed registration request with a replay of a cached 944 notification. Alternatively, the server MAY send a new 945 notification. 947 o An intermediary node is not able to initiate an OSCORE protected 948 Observe cancellation (Observe with value 1) which verifies as 949 coming from the client. An application MAY decide to allow 950 intermediaries to cancel Observe registrations, e.g. to send 951 Observe with value 1 (see Section 3.6 of [RFC7641]), but that can 952 also be done with other methods, e.g. reusing the Token in a 953 different request or sending a RST message. This is out of scope 954 for this specification. 956 4.1.3.5.2. Notifications 958 If the server accepts an Observe registration, a Partial IV MUST be 959 included in all notifications (both successful and error), except for 960 the first one where Partial IV MAY be omitted. To protect against 961 replay, the client SHALL maintain a Notification Number for each 962 Observation it registers. The Notification Number is a non-negative 963 integer containing the largest Partial IV of the received 964 notifications for the associated Observe registration. Further 965 details of replay protection of notifications are specified in 966 Section 7.4.1. 968 For notifications, the Inner Observe value MUST be empty (see 969 Section 3.2 of [RFC7252]). The Outer Observe in a notification is 970 needed for intermediary nodes to allow multiple responses to one 971 request, and may be set to the value of Observe in the original CoAP 972 message. The client performs ordering of notifications and replay 973 protection by comparing their Partial IVs and SHALL ignore the outer 974 Observe value. 976 If the client receives a response to an Observe request without an 977 Inner Observe option, then it verifies the response as a non-Observe 978 response, as specified in Section 8.4. If the client receives a 979 response to a non-Observe request with an Inner Observe option, then 980 it stops processing the message, as specified in Section 8.4. 982 A client MUST consider the notification with the highest Partial IV 983 as the freshest, regardless of the order of arrival. In order to 984 support existing Observe implementations the OSCORE client 985 implementation MAY set the Observe value to the three least 986 significant bytes of the Partial IV. Implementations need to make 987 sure that the notification without Partial IV is considered the 988 oldest. 990 4.1.3.6. No-Response 992 No-Response [RFC7967] is an optional feature used by the client to 993 communicate its disinterest in certain classes of responses to a 994 particular request. An implementation MAY support [RFC7252] and the 995 OSCORE option without supporting [RFC7967]. 997 If used, No-Response MUST be Inner. The Inner No-Response SHALL be 998 processed by OSCORE as specified in Section 4.1.1. The Outer option 999 SHOULD NOT be present. The server SHALL ignore the Outer No-Response 1000 option. The client MAY set the Outer No-Response value to 26 1001 ('suppress all known codes') if the Inner value is set to 26. The 1002 client MUST be prepared to receive and discard 5.04 Gateway Timeout 1003 error messages from intermediaries potentially resulting from 1004 destination time out due to no response. 1006 4.1.3.7. OSCORE 1008 The OSCORE option is only defined to be present in OSCORE messages, 1009 as an indication that OSCORE processing have been performed. The 1010 content in the OSCORE option is neither encrypted nor integrity 1011 protected as a whole but some part of the content of this option is 1012 protected (see Section 5.4). Nested use of OSCORE is not supported: 1013 If OSCORE processing detects an OSCORE option in the original CoAP 1014 message, then processing SHALL be stopped. 1016 4.2. CoAP Header Fields and Payload 1018 A summary of how the CoAP header fields and payload are protected is 1019 shown in Figure 6, including fields specific to CoAP over UDP and 1020 CoAP over TCP (marked accordingly in the table). 1022 +------------------+---+---+ 1023 | Field | E | U | 1024 +------------------+---+---+ 1025 | Version (UDP) | | x | 1026 | Type (UDP) | | x | 1027 | Length (TCP) | | x | 1028 | Token Length | | x | 1029 | Code | x | | 1030 | Message ID (UDP) | | x | 1031 | Token | | x | 1032 | Payload | x | | 1033 +------------------+---+---+ 1035 E = Encrypt and Integrity Protect (Inner) 1036 U = Unprotected (Outer) 1038 Figure 6: Protection of CoAP Header Fields and Payload 1040 Most CoAP Header fields (i.e. the message fields in the fixed 4-byte 1041 header) are required to be read and/or changed by CoAP proxies and 1042 thus cannot in general be protected end-to-end between the endpoints. 1043 As mentioned in Section 1, OSCORE protects the CoAP Request/Response 1044 layer only, and not the Messaging Layer (Section 2 of [RFC7252]), so 1045 fields such as Type and Message ID are not protected with OSCORE. 1047 The CoAP Header field Code is protected by OSCORE. Code SHALL be 1048 encrypted and integrity protected (Class E) to prevent an 1049 intermediary from eavesdropping on or manipulating the Code (e.g., 1050 changing from GET to DELETE). 1052 The sending endpoint SHALL write the Code of the original CoAP 1053 message into the plaintext of the COSE object (see Section 5.3). 1054 After that, the sending endpoint writes an Outer Code to the OSCORE 1055 message. With one exception (see Section 4.1.3.5) the Outer Code 1056 SHALL be set to 0.02 (POST) for requests and to 2.04 (Changed) for 1057 responses. The receiving endpoint SHALL discard the Outer Code in 1058 the OSCORE message and write the Code of the COSE object plaintext 1059 (Section 5.3) into the decrypted CoAP message. 1061 The other currently defined CoAP Header fields are Unprotected (Class 1062 U). The sending endpoint SHALL write all other header fields of the 1063 original message into the header of the OSCORE message. The 1064 receiving endpoint SHALL write the header fields from the received 1065 OSCORE message into the header of the decrypted CoAP message. 1067 The CoAP Payload, if present in the original CoAP message, SHALL be 1068 encrypted and integrity protected and is thus an Inner message field. 1069 The sending endpoint writes the payload of the original CoAP message 1070 into the plaintext (Section 5.3) input to the COSE object. The 1071 receiving endpoint verifies and decrypts the COSE object, and 1072 recreates the payload of the original CoAP message. 1074 4.3. Signaling Messages 1076 Signaling messages (CoAP Code 7.00-7.31) were introduced to exchange 1077 information related to an underlying transport connection in the 1078 specific case of CoAP over reliable transports [RFC8323]. 1080 OSCORE MAY be used to protect Signaling if the endpoints for OSCORE 1081 coincide with the endpoints for the signaling message. If OSCORE is 1082 used to protect Signaling then: 1084 o To comply with [RFC8323], an initial empty CSM message SHALL be 1085 sent. The subsequent signaling message SHALL be protected. 1087 o Signaling messages SHALL be protected as CoAP Request messages, 1088 except in the case the Signaling message is a response to a 1089 previous Signaling message, in which case it SHALL be protected as 1090 a CoAP Response message. For example, 7.02 (Ping) is protected as 1091 a CoAP Request and 7.03 (Pong) as a CoAP response. 1093 o The Outer Code for Signaling messages SHALL be set to 0.02 (POST), 1094 unless it is a response to a previous Signaling message, in which 1095 case it SHALL be set to 2.04 (Changed). 1097 o All Signaling options, except the OSCORE option, SHALL be Inner 1098 (Class E). 1100 NOTE: Option numbers for Signaling messages are specific to the CoAP 1101 Code (see Section 5.2 of [RFC8323]). 1103 If OSCORE is not used to protect Signaling, Signaling messages SHALL 1104 be unaltered by OSCORE. 1106 5. The COSE Object 1108 This section defines how to use COSE [RFC8152] to wrap and protect 1109 data in the original message. OSCORE uses the untagged COSE_Encrypt0 1110 structure with an Authenticated Encryption with Additional Data 1111 (AEAD) algorithm. The AEAD key lengths, AEAD nonce length, and 1112 maximum Sender Sequence Number are algorithm dependent. 1114 The AEAD algorithm AES-CCM-16-64-128 defined in Section 10.2 of 1115 [RFC8152] is mandatory to implement. For AES-CCM-16-64-128 the 1116 length of Sender Key and Recipient Key is 128 bits, the length of 1117 AEAD nonce and Common IV is 13 bytes. The maximum Sender Sequence 1118 Number is specified in Section 12. 1120 As specified in [RFC5116], plaintext denotes the data that is to be 1121 encrypted and integrity protected, and Additional Authenticated Data 1122 (AAD) denotes the data that is to be integrity protected only. 1124 The COSE Object SHALL be a COSE_Encrypt0 object with fields defined 1125 as follows 1127 o The 'protected' field is empty. 1129 o The 'unprotected' field includes: 1131 * The 'Partial IV' parameter. The value is set to the Sender 1132 Sequence Number. All leading bytes of value zero SHALL be 1133 removed when encoding the Partial IV, except in the case of 1134 Partial IV of value 0 which is encoded to the byte string 0x00. 1135 This parameter SHALL be present in requests. The Partial IV 1136 SHALL be present in responses to Observe registrations (see 1137 Section 4.1.3.5.1), otherwise the Partial IV will not typically 1138 be present in responses. 1140 * The 'kid' parameter. The value is set to the Sender ID. This 1141 parameter SHALL be present in requests and will not typically 1142 be present in responses. An example where the Sender ID is 1143 included in a response is the extension of OSCORE to group 1144 communication [I-D.ietf-core-oscore-groupcomm]. 1146 * Optionally, a 'kid context' parameter (see Section 5.1) 1147 containing an ID Context (see Section 3.1). This parameter MAY 1148 be present in requests and MUST NOT be present in responses. 1149 If 'kid context' is present in the request, then the server 1150 SHALL use a security context with that ID Context when 1151 verifying the request. 1153 o The 'ciphertext' field is computed from the secret key (Sender Key 1154 or Recipient Key), AEAD nonce (see Section 5.2), plaintext (see 1155 Section 5.3), and the Additional Authenticated Data (AAD) (see 1156 Section 5.4) following Section 5.2 of [RFC8152]. 1158 The encryption process is described in Section 5.3 of [RFC8152]. 1160 5.1. Kid Context 1162 For certain use cases, e.g. deployments where the same Sender ID is 1163 used with multiple contexts, it is possible (and sometimes necessary, 1164 see Section 3.3) for the client to use an ID Context to distinguish 1165 the security contexts (see Section 3.1). For example: 1167 o If the client has a unique identifier in some namespace, then that 1168 identifier can be used as ID Context. 1170 o In case of group communication [I-D.ietf-core-oscore-groupcomm], a 1171 group identifier can be used as ID Context to enable different 1172 security contexts for a server belonging to multiple groups. 1174 The Sender ID and Context ID are used to establish the necessary 1175 input parameters and in the derivation of the security context (see 1176 Section 3.2). Whereas the 'kid' parameter is used to transport the 1177 Sender ID, the new COSE header parameter 'kid context' is used to 1178 transport the ID Context, see Figure 7. 1180 +----------+--------+------------+----------------+-----------------+ 1181 | name | label | value type | value registry | description | 1182 +----------+--------+------------+----------------+-----------------+ 1183 | kid | TBD2 | bstr | | Identifies the | 1184 | context | | | | context for kid | 1185 +----------+--------+------------+----------------+-----------------+ 1187 Figure 7: Common Header Parameter kid context for the COSE object 1189 5.2. AEAD Nonce 1191 The high level design of the AEAD nonce follows Section 4.4 of 1192 [I-D.mcgrew-iv-gen], here follows the detailed construction (see 1193 Figure 8): 1195 1. left-pad the Partial IV (PIV) in network byte order with zeroes 1196 to exactly 5 bytes, 1198 2. left-pad the Sender ID of the endpoint that generated the Partial 1199 IV (ID_PIV) in network byte order with zeroes to exactly nonce 1200 length minus 6 bytes, 1202 3. concatenate the size of the ID_PIV (a single byte S) with the 1203 padded ID_PIV and the padded PIV, 1205 4. and then XOR with the Common IV. 1207 Note that in this specification only AEAD algorithms that use nonces 1208 equal or greater than 7 bytes are supported. The nonce construction 1209 with S, ID_PIV, and PIV together with endpoint unique IDs and 1210 encryption keys makes it easy to verify that the nonces used with a 1211 specific key will be unique, see Appendix D.3. 1213 If the Partial IV is not present in a response, the nonce from the 1214 request is used. For responses that are not notifications (i.e. when 1215 there is a single response to a request), the request and the 1216 response should typically use the same nonce to reduce message 1217 overhead. Both alternatives provide all the required security 1218 properties, see Section 7.4 and Appendix D.3. The only non-Observe 1219 scenario where a Partial IV must be included in a response is when 1220 the server is unable to perform replay protection, see Section 7.5.2. 1221 For processing instructions see Section 8. 1223 <- nonce length minus 6 B -> <-- 5 bytes --> 1224 +---+-------------------+--------+---------+-----+ 1225 | S | padding | ID_PIV | padding | PIV |----+ 1226 +---+-------------------+--------+---------+-----+ | 1227 | 1228 <---------------- nonce length ----------------> | 1229 +------------------------------------------------+ | 1230 | Common IV |->(XOR) 1231 +------------------------------------------------+ | 1232 | 1233 <---------------- nonce length ----------------> | 1234 +------------------------------------------------+ | 1235 | Nonce |<---+ 1236 +------------------------------------------------+ 1238 Figure 8: AEAD Nonce Formation 1240 5.3. Plaintext 1242 The plaintext is formatted as a CoAP message without Header (see 1243 Figure 9) consisting of: 1245 o the Code of the original CoAP message as defined in Section 3 of 1246 [RFC7252]; and 1248 o all Inner option message fields (see Section 4.1.1) present in the 1249 original CoAP message (see Section 4.1). The options are encoded 1250 as described in Section 3.1 of [RFC7252], where the delta is the 1251 difference to the previously included instance of Class E option; 1252 and 1254 o the Payload of original CoAP message, if present, and in that case 1255 prefixed by the one-byte Payload Marker (0xFF). 1257 0 1 2 3 1258 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 1259 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1260 | Code | Class E options (if any) ... 1261 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1262 |1 1 1 1 1 1 1 1| Payload (if any) ... 1263 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1264 (only if there 1265 is payload) 1267 Figure 9: Plaintext 1269 NOTE: The plaintext contains all CoAP data that needs to be encrypted 1270 end-to-end between the endpoints. 1272 5.4. Additional Authenticated Data 1274 The external_aad SHALL be a CBOR array wrapped in a bstr object as 1275 defined below: 1277 external_aad = bstr .cbor aad_array 1279 aad_array = [ 1280 oscore_version : uint, 1281 algorithms : [ alg_aead : int / tstr ], 1282 request_kid : bstr, 1283 request_piv : bstr, 1284 options : bstr 1285 ] 1287 where: 1289 o oscore_version: contains the OSCORE version number. 1290 Implementations of this specification MUST set this field to 1. 1291 Other values are reserved for future versions. 1293 o algorithms: contains (for extensibility) an array of algorithms, 1294 according to this specification only containing alg_aead. 1296 o alg_aead: contains the AEAD Algorithm from the security context 1297 used for the exchange (see Section 3.1). 1299 o request_kid: contains the value of the 'kid' in the COSE object of 1300 the request (see Section 5). 1302 o request_piv: contains the value of the 'Partial IV' in the COSE 1303 object of the request (see Section 5). 1305 o options: contains the Class I options (see Section 4.1.2) present 1306 in the original CoAP message encoded as described in Section 3.1 1307 of [RFC7252], where the delta is the difference to the previously 1308 included instance of class I option. 1310 The oscore_version and algorithms parameters are established out-of- 1311 band and are thus never transported in OSCORE, but the external_aad 1312 allows to verify that they are the same in both endpoints. 1314 NOTE: The format of the external_aad is for simplicity the same for 1315 requests and responses, although some parameters, e.g. request_kid, 1316 need not be integrity protected in all requests. 1318 The Additional Authenticated Data (AAD) is composed from the 1319 external_aad as described in Section 5.3 of [RFC8152]: 1321 AAD = Enc_structure = [ "Encrypt0", h'', external_aad ] 1323 The following is an example of AAD constructed using AEAD Algorithm = 1324 AES-CCM-16-64-128 (10), request_kid = 0x00, request_piv = 0x25 and no 1325 Class I options. 1327 oscore_version = 0x01 1328 algorithms = 0x810A 1329 request_kid = 0x00 1330 request_piv = 0x25 1331 options = 0x 1333 aad_array = 0x8501810A4100412540 1335 external_aad = 0x498501810A4100412540 1337 AAD = 0x8368456E63727970743040498501810A4100412540 1339 Note that the AAD consists of a fixed string of 11 bytes concatenated 1340 with the external_aad. 1342 6. OSCORE Header Compression 1344 The Concise Binary Object Representation (CBOR) [RFC7049] combines 1345 very small message sizes with extensibility. The CBOR Object Signing 1346 and Encryption (COSE) [RFC8152] uses CBOR to create compact encoding 1347 of signed and encrypted data. COSE is however constructed to support 1348 a large number of different stateless use cases, and is not fully 1349 optimized for use as a stateful security protocol, leading to a 1350 larger than necessary message expansion. In this section, we define 1351 a stateless header compression mechanism, simply removing redundant 1352 information from the COSE objects, which significantly reduces the 1353 per-packet overhead. The result of applying this mechanism to a COSE 1354 object is called the "compressed COSE object". 1356 The COSE_Encrypt0 object used in OSCORE is transported in the OSCORE 1357 option and in the Payload. The Payload contains the Ciphertext of 1358 the COSE object. The headers of the COSE object are compactly 1359 encoded as described in the next section. 1361 6.1. Encoding of the OSCORE Option Value 1363 The value of the OSCORE option SHALL contain the OSCORE flag bits, 1364 the Partial IV parameter, the kid context parameter (length and 1365 value), and the kid parameter as follows: 1367 0 1 2 3 4 5 6 7 <------------- n bytes --------------> 1368 +-+-+-+-+-+-+-+-+-------------------------------------- 1369 |0 0 0|h|k| n | Partial IV (if any) ... 1370 +-+-+-+-+-+-+-+-+-------------------------------------- 1372 <- 1 byte -> <----- s bytes ------> 1373 +------------+----------------------+------------------+ 1374 | s (if any) | kid context (if any) | kid (if any) ... | 1375 +------------+----------------------+------------------+ 1377 Figure 10: The OSCORE Option Value 1379 o The first byte, containing the OSCORE flag bits, encodes the 1380 following set of bits and the length of the Partial IV parameter: 1382 * The three least significant bits encode the Partial IV length 1383 n. If n = 0 then the Partial IV is not present in the 1384 compressed COSE object. The values n = 6 and n = 7 are 1385 reserved. 1387 * The fourth least significant bit is the kid flag, k: it is set 1388 to 1 if the kid is present in the compressed COSE object. 1390 * The fifth least significant bit is the kid context flag, h: it 1391 is set to 1 if the compressed COSE object contains a kid 1392 context (see Section 5.1). 1394 * The sixth to eighth least significant bits are reserved for 1395 future use. These bits SHALL be set to zero when not in use. 1396 According to this specification, if any of these bits are set 1397 to 1 the message is considered to be malformed and 1398 decompression fails as specified in item 3 of Section 8.2. 1400 The flag bits are registered in the OSCORE Flag Bits registry 1401 specified in Section 13.7. 1403 o The following n bytes encode the value of the Partial IV, if the 1404 Partial IV is present (n > 0). 1406 o The following 1 byte encode the length of the kid context 1407 (Section 5.1) s, if the kid context flag is set (h = 1). 1409 o The following s bytes encode the kid context, if the kid context 1410 flag is set (h = 1). 1412 o The remaining bytes encode the value of the kid, if the kid is 1413 present (k = 1). 1415 Note that the kid MUST be the last field of the OSCORE option value, 1416 even in case reserved bits are used and additional fields are added 1417 to it. 1419 The length of the OSCORE option thus depends on the presence and 1420 length of Partial IV, kid context, kid, as specified in this section, 1421 and on the presence and length of the other parameters, as defined in 1422 the separate documents. 1424 6.2. Encoding of the OSCORE Payload 1426 The payload of the OSCORE message SHALL encode the ciphertext of the 1427 COSE object. 1429 6.3. Examples of Compressed COSE Objects 1431 This section covers a list of OSCORE Header Compression examples for 1432 requests and responses. The examples assume the COSE_Encrypt0 object 1433 is set (which means the CoAP message and cryptographic material is 1434 known). Note that the full CoAP unprotected message, as well as the 1435 full security context, is not reported in the examples, but only the 1436 input necessary to the compression mechanism, i.e. the COSE_Encrypt0 1437 object. The output is the compressed COSE object as defined in 1438 Section 6, divided into two parts, since the object is transported in 1439 two CoAP fields: OSCORE option and payload. 1441 1. Request with ciphertext = 0xaea0155667924dff8a24e4cb35b9, kid = 1442 0x25, and Partial IV = 0x05 1443 Before compression (24 bytes): 1445 [ 1446 h'', 1447 { 4:h'25', 6:h'05' }, 1448 h'aea0155667924dff8a24e4cb35b9' 1449 ] 1451 After compression (17 bytes): 1453 Flag byte: 0b00001001 = 0x09 1455 Option Value: 09 05 25 (3 bytes) 1457 Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) 1459 2. Request with ciphertext = 0xaea0155667924dff8a24e4cb35b9, kid = 1460 empty string, and Partial IV = 0x00 1462 Before compression (23 bytes): 1464 [ 1465 h'', 1466 { 4:h'', 6:h'00' }, 1467 h'aea0155667924dff8a24e4cb35b9' 1468 ] 1470 After compression (16 bytes): 1472 Flag byte: 0b00001001 = 0x09 1474 Option Value: 09 00 (2 bytes) 1476 Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) 1478 3. Request with ciphertext = 0xaea0155667924dff8a24e4cb35b9, kid = 1479 empty string, Partial IV = 0x05, and kid context = 0x44616c656b 1481 Before compression (30 bytes): 1483 [ 1484 h'', 1485 { 4:h'', 6:h'05', 8:h'44616c656b' }, 1486 h'aea0155667924dff8a24e4cb35b9' 1487 ] 1489 After compression (22 bytes): 1491 Flag byte: 0b00011001 = 0x19 1493 Option Value: 19 05 05 44 61 6c 65 6b (8 bytes) 1495 Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) 1497 4. Response with ciphertext = 0xaea0155667924dff8a24e4cb35b9 and no 1498 Partial IV 1500 Before compression (18 bytes): 1502 [ 1503 h'', 1504 {}, 1505 h'aea0155667924dff8a24e4cb35b9' 1506 ] 1508 After compression (14 bytes): 1510 Flag byte: 0b00000000 = 0x00 1512 Option Value: (0 bytes) 1514 Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) 1516 5. Response with ciphertext = 0xaea0155667924dff8a24e4cb35b9 and 1517 Partial IV = 0x07 1519 Before compression (21 bytes): 1521 [ 1522 h'', 1523 { 6:h'07' }, 1524 h'aea0155667924dff8a24e4cb35b9' 1525 ] 1527 After compression (16 bytes): 1529 Flag byte: 0b00000001 = 0x01 1531 Option Value: 01 07 (2 bytes) 1533 Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) 1535 7. Message Binding, Sequence Numbers, Freshness and Replay Protection 1537 7.1. Message Binding 1539 In order to prevent response delay and mismatch attacks 1540 [I-D.mattsson-core-coap-actuators] from on-path attackers and 1541 compromised intermediaries, OSCORE binds responses to the requests by 1542 including the kid and Partial IV of the request in the AAD of the 1543 response. The server therefore needs to store the kid and Partial IV 1544 of the request until all responses have been sent. 1546 7.2. Sequence Numbers 1548 An AEAD nonce MUST NOT be used more than once per AEAD key. The 1549 uniqueness of (key, nonce) pairs is shown in Appendix D.3, and in 1550 particular depends on a correct usage of Partial IVs (which encode 1551 the Sender Sequence Numbers, see Section 5). If messages are 1552 processed concurrently, the operation of reading and increasing the 1553 Sender Sequence Number MUST be atomic. 1555 7.2.1. Maximum Sequence Number 1557 The maximum Sender Sequence Number is algorithm dependent (see 1558 Section 12), and SHALL be less than 2^40. If the Sender Sequence 1559 Number exceeds the maximum, the endpoint MUST NOT process any more 1560 messages with the given Sender Context. If necessary, the endpoint 1561 SHOULD acquire a new security context before this happens. The 1562 latter is out of scope of this document. 1564 7.3. Freshness 1566 For requests, OSCORE provides only the guarantee that the request is 1567 not older than the security context. For applications having 1568 stronger demands on request freshness (e.g., control of actuators), 1569 OSCORE needs to be augmented with mechanisms providing freshness, for 1570 example as specified in [I-D.ietf-core-echo-request-tag]. 1572 Assuming an honest server (see Appendix D), the message binding 1573 guarantees that a response is not older than its request. For 1574 responses that are not notifications (i.e. when there is a single 1575 response to a request), this gives absolute freshness. For 1576 notifications, the absolute freshness gets weaker with time, and it 1577 is RECOMMENDED that the client regularly re-register the observation. 1578 Note that the message binding does not guarantee that misbehaving 1579 server created the response before receiving the request, i.e. it 1580 does not verify server aliveness. 1582 For requests and notifications, OSCORE also provides relative 1583 freshness in the sense that the received Partial IV allows a 1584 recipient to determine the relative order of requests or responses. 1586 7.4. Replay Protection 1588 In order to protect from replay of requests, the server's Recipient 1589 Context includes a Replay Window. A server SHALL verify that a 1590 Partial IV = Sender Sequence Number received in the COSE object has 1591 not been received before. If this verification fails the server 1592 SHALL stop processing the message, and MAY optionally respond with a 1593 4.01 Unauthorized error message. Also, the server MAY set an Outer 1594 Max-Age option with value zero, to inform any intermediary that the 1595 response is not to be cached. The diagnostic payload MAY contain the 1596 "Replay detected" string. The size and type of the Replay Window 1597 depends on the use case and the protocol with which the OSCORE 1598 message is transported. In case of reliable and ordered transport 1599 from endpoint to endpoint, e.g. TCP, the server MAY just store the 1600 last received Partial IV and require that newly received Partial IVs 1601 equals the last received Partial IV + 1. However, in case of mixed 1602 reliable and unreliable transports and where messages may be lost, 1603 such a replay mechanism may be too restrictive and the default replay 1604 window be more suitable (see Section 3.2.2). 1606 Responses (with or without Partial IV) are protected against replay 1607 as they are bound to the request and the fact that only a single 1608 response is accepted. Note that the Partial IV is not used for 1609 replay protection in this case. 1611 The operation of validating the Partial IV and updating the replay 1612 protection MUST be atomic. 1614 7.4.1. Replay Protection of Notifications 1616 The following applies additionally when Observe is supported. 1618 The Notification Number is initialized to the Partial IV of the first 1619 successfully verified notification in response to the registration 1620 request. A client MUST only accept at most one Observe notifications 1621 without Partial IV, and treat it as the oldest notification received. 1622 A client receiving a notification containing a Partial IV SHALL 1623 compare the Partial IV with the Notification Number associated to 1624 that Observe registration. The client MUST stop processing 1625 notifications with a Partial IV which has been previously received. 1626 Applications MAY decide that a client only processes notifications 1627 which have greater Partial IV than the Notification Number. 1629 If the verification of the response succeeds, and the received 1630 Partial IV was greater than the Notification Number then the client 1631 SHALL overwrite the corresponding Notification Number with the 1632 received Partial IV. 1634 7.5. Losing Part of the Context State 1636 To prevent reuse of an AEAD nonce with the same AEAD key, or from 1637 accepting replayed messages, an endpoint needs to handle the 1638 situation of losing rapidly changing parts of the context, such as 1639 the request Token, Sender Sequence Number, Replay Window, and 1640 Notification Numbers. These are typically stored in RAM and 1641 therefore lost in the case of an unplanned reboot. 1643 After boot, an endpoint can either use a persistently stored complete 1644 or partial security context, or establish a new security context with 1645 each endpoint it communicates with. However, establishing a fresh 1646 security context may have a non-negligible cost in terms of, e.g., 1647 power consumption. 1649 If the endpoint uses a persistently stored partial security context, 1650 it MUST NOT reuse a previous Sender Sequence Number and MUST NOT 1651 accept previously received messages. Some ways to achieve this are 1652 described in the following sections. 1654 7.5.1. Sequence Number 1656 To prevent reuse of Sender Sequence Numbers, an endpoint may perform 1657 the following procedure during normal operations: 1659 o Before using a Sender Sequence Number that is evenly divisible by 1660 K, where K is a positive integer, store the Sender Sequence Number 1661 in persistent memory. After boot, the endpoint initiates the 1662 Sender Sequence Number to the value stored in persistent memory + 1663 K. Storing to persistent memory can be costly. The value K gives 1664 a trade-off between the number of storage operations and efficient 1665 use of Sender Sequence Numbers. 1667 7.5.2. Replay Window 1669 To prevent accepting replay of previously received requests, the 1670 server may perform the following procedure after boot: 1672 o For each stored security context, the first time after boot the 1673 server receives an OSCORE request, the server responds with the 1674 Echo option [I-D.ietf-core-echo-request-tag] to get a request with 1675 verifiable freshness. The server MUST use its Sender Sequence 1676 Number (initiated as in Section 7.5.1) when generating the AEAD 1677 nonce and MUST include it as Partial IV in the response. 1679 If the server using the Echo option can verify a second request as 1680 fresh, then the Partial IV of the second request is set as the lower 1681 limit of the replay window of Sender Sequence Numbers. 1683 7.5.3. Replay of Notifications 1685 To prevent accepting replay of previously received notifications, the 1686 client may perform the following procedure after boot: 1688 o The client forgets about earlier registrations, removes all 1689 Notification Numbers and registers using Observe. 1691 8. Processing 1693 This section describes the OSCORE message processing. Additional 1694 processing for Observe or Block-wise are described in subsections. 1696 Note that, analogously to [RFC7252] where the Token and source/ 1697 destination pair are used to match a response with a request, both 1698 endpoints MUST keep the association (Token, {Security Context, 1699 Partial IV of the request}), in order to be able to find the Security 1700 Context and compute the AAD to protect or verify the response. The 1701 association MAY be forgotten after it has been used to successfully 1702 protect or verify the response, with the exception of Observe 1703 processing, where the association MUST be kept as long as the 1704 Observation is active. 1706 The processing of the Sender Sequence Number follows the procedure 1707 described in Section 3 of [I-D.mcgrew-iv-gen]. 1709 8.1. Protecting the Request 1711 Given a CoAP request, the client SHALL perform the following steps to 1712 create an OSCORE request: 1714 1. Retrieve the Sender Context associated with the target resource. 1716 2. Compose the Additional Authenticated Data and the plaintext, as 1717 described in Sections 5.3 and 5.4. 1719 3. Encode the Partial IV (Sender Sequence Number in network byte 1720 order) and increment the Sender Sequence Number by one. Compute 1721 the AEAD nonce from the Sender ID, Common IV, and Partial IV as 1722 described in Section 5.2. 1724 4. Encrypt the COSE object using the Sender Key. Compress the COSE 1725 Object as specified in Section 6. 1727 5. Format the OSCORE message according to Section 4. The OSCORE 1728 option is added (see Section 4.1.2). 1730 8.2. Verifying the Request 1732 A server receiving a request containing the OSCORE option SHALL 1733 perform the following steps: 1735 1. Discard Code and all class E options (marked in Figure 5 with 'x' 1736 in column E) present in the received message. For example, an 1737 If-Match Outer option is discarded, but an Uri-Host Outer option 1738 is not discarded. 1740 2. Decompress the COSE Object (Section 6) and retrieve the Recipient 1741 Context associated with the Recipient ID in the 'kid' parameter, 1742 additionally using the 'kid context', if present. If either the 1743 decompression or the COSE message fails to decode, or the server 1744 fails to retrieve a Recipient Context with Recipient ID 1745 corresponding to the 'kid' parameter received, then the server 1746 SHALL stop processing the request. 1748 * If either the decompression or the COSE message fails to 1749 decode, the server MAY respond with a 4.02 Bad Option error 1750 message. The server MAY set an Outer Max-Age option with 1751 value zero. The diagnostic payload SHOULD contain the string 1752 "Failed to decode COSE". 1754 * If the server fails to retrieve a Recipient Context with 1755 Recipient ID corresponding to the 'kid' parameter received, 1756 the server MAY respond with a 4.01 Unauthorized error message. 1757 The server MAY set an Outer Max-Age option with value zero. 1758 The diagnostic payload SHOULD contain the string "Security 1759 context not found". 1761 3. Verify that the 'Partial IV' has not been received before using 1762 the Replay Window, as described in Section 7.4. 1764 4. Compose the Additional Authenticated Data, as described in 1765 Section 5.4. 1767 5. Compute the AEAD nonce from the Recipient ID, Common IV, and the 1768 'Partial IV' parameter, received in the COSE Object. 1770 6. Decrypt the COSE object using the Recipient Key, as per [RFC8152] 1771 Section 5.3. (The decrypt operation includes the verification of 1772 the integrity.) 1774 * If decryption fails, the server MUST stop processing the 1775 request and MAY respond with a 4.00 Bad Request error message. 1776 The server MAY set an Outer Max-Age option with value zero. 1777 The diagnostic payload MAY contain the "Decryption failed" 1778 string. 1780 * If decryption succeeds, update the Replay Window, as described 1781 in Section 7. 1783 7. Add decrypted Code, options, and payload to the decrypted 1784 request. The OSCORE option is removed. 1786 8. The decrypted CoAP request is processed according to [RFC7252]. 1788 8.2.1. Supporting Block-wise 1790 If Block-wise is supported, insert the following step before any 1791 other: 1793 A. If Block-wise is present in the request then process the Outer 1794 Block options according to [RFC7959], until all blocks of the request 1795 have been received (see Section 4.1.3.4). 1797 8.3. Protecting the Response 1799 If a CoAP response is generated in response to an OSCORE request, the 1800 server SHALL perform the following steps to create an OSCORE 1801 response. Note that CoAP error responses derived from CoAP 1802 processing (step 8 in Section 8.2) are protected, as well as 1803 successful CoAP responses, while the OSCORE errors (steps 2, 3, and 6 1804 in Section 8.2) do not follow the processing below, but are sent as 1805 simple CoAP responses, without OSCORE processing. 1807 1. Retrieve the Sender Context in the Security Context associated 1808 with the Token. 1810 2. Compose the Additional Authenticated Data and the plaintext, as 1811 described in Sections 5.3 and 5.4. 1813 3. Compute the AEAD nonce as described in Section 5.2: 1815 * Either use the AEAD nonce from the request, or 1816 * Encode the Partial IV (Sender Sequence Number in network byte 1817 order) and increment the Sender Sequence Number by one. 1818 Compute the AEAD nonce from the Sender ID, Common IV, and 1819 Partial IV. 1821 4. Encrypt the COSE object using the Sender Key. Compress the COSE 1822 Object as specified in Section 6. If the AEAD nonce was 1823 constructed from a new Partial IV, this Partial IV MUST be 1824 included in the message. If the AEAD nonce from the request was 1825 used, the Partial IV MUST NOT be included in the message. 1827 5. Format the OSCORE message according to Section 4. The OSCORE 1828 option is added (see Section 4.1.2). 1830 8.3.1. Supporting Observe 1832 If Observe is supported, insert the following step between step 2 and 1833 3 of Section 8.3: 1835 A. If the response is an observe notification: 1837 o If the response is the first notification: 1839 * compute the AEAD nonce as described in Section 5.2: 1841 + Either use the AEAD nonce from the request, or 1843 + Encode the Partial IV (Sender Sequence Number in network 1844 byte order) and increment the Sender Sequence Number by one. 1845 Compute the AEAD nonce from the Sender ID, Common IV, and 1846 Partial IV. 1848 Then go to 4. 1850 o If the response is not the first notification: 1852 * encode the Partial IV (Sender Sequence Number in network byte 1853 order) and increment the Sender Sequence Number by one. 1854 Compute the AEAD nonce from the Sender ID, Common IV, and 1855 Partial IV, then go to 4. 1857 8.4. Verifying the Response 1859 A client receiving a response containing the OSCORE option SHALL 1860 perform the following steps: 1862 1. Discard Code and all class E options (marked in Figure 5 with 'x' 1863 in column E) present in the received message. For example, ETag 1864 Outer option is discarded, as well as Max-Age Outer option. 1866 2. Retrieve the Recipient Context in the Security Context associated 1867 with the Token. Decompress the COSE Object (Section 6). If 1868 either the decompression or the COSE message fails to decode, 1869 then go to 8. 1871 3. Compose the Additional Authenticated Data, as described in 1872 Section 5.4. 1874 4. Compute the AEAD nonce 1876 * If the Partial IV is not present in the response, the AEAD 1877 nonce from the request is used. 1879 * If the Partial IV is present in the response, compute the AEAD 1880 nonce from the Recipient ID, Common IV, and the 'Partial IV' 1881 parameter, received in the COSE Object. 1883 5. Decrypt the COSE object using the Recipient Key, as per [RFC8152] 1884 Section 5.3. (The decrypt operation includes the verification of 1885 the integrity.) If decryption fails, then go to 8. 1887 6. Add decrypted Code, options and payload to the decrypted request. 1888 The OSCORE option is removed. 1890 7. The decrypted CoAP response is processed according to [RFC7252]. 1892 8. In case any of the previous erroneous conditions apply: the 1893 client SHALL stop processing the response. 1895 8.4.1. Supporting Block-wise 1897 If Block-wise is supported, insert the following step before any 1898 other: 1900 A. If Block-wise is present in the request then process the Outer 1901 Block options according to [RFC7959], until all blocks of the request 1902 have been received (see Section 4.1.3.4). 1904 8.4.2. Supporting Observe 1906 If Observe is supported: 1908 Insert the following step between step 5 and step 6: 1910 A. If the request was an Observe registration, then: 1912 o If the Partial IV is not present in the response, and Inner 1913 Observe is present, and the AEAD nonce from the request was 1914 already used once, then go to 8. 1916 o If the Partial IV is present in the response and Inner Observe is 1917 present, then follow the processing described in Section 4.1.3.5.2 1918 and Section 7.4.1, then: 1920 * initialize the Notification Number (if first successfully 1921 verified notification), or 1923 * overwrite the Notification Number (if the received Partial IV 1924 was greater than the Notification Number). 1926 Replace step 8 of Section 8.4 with: 1928 B. In case any of the previous erroneous conditions apply: the 1929 client SHALL stop processing the response. An error condition 1930 occurring while processing a response to an observation request does 1931 not cancel the observation. A client MUST NOT react to failure by 1932 re-registering the observation immediately. 1934 9. Web Linking 1936 The use of OSCORE MAY be indicated by a target attribute "osc" in a 1937 web link [RFC8288] to a resource, e.g. using a link-format document 1938 [RFC6690] if the resource is accessible over CoAP. 1940 The "osc" attribute is a hint indicating that the destination of that 1941 link is only accessible using OSCORE, and unprotected access to it is 1942 not supported. Note that this is simply a hint, it does not include 1943 any security context material or any other information required to 1944 run OSCORE. 1946 A value MUST NOT be given for the "osc" attribute; any present value 1947 MUST be ignored by parsers. The "osc" attribute MUST NOT appear more 1948 than once in a given link-value; occurrences after the first MUST be 1949 ignored by parsers. 1951 The example in Figure 11 shows a use of the "osc" attribute: the 1952 client does resource discovery on a server, and gets back a list of 1953 resources, one of which includes the "osc" attribute indicating that 1954 the resource is protected with OSCORE. The link-format notation (see 1955 Section 5 of [RFC6690]) is used. 1957 REQ: GET /.well-known/core 1959 RES: 2.05 Content 1960 ;osc, 1961 ;if="sensor" 1963 Figure 11: The web link 1965 10. CoAP-to-CoAP Forwarding Proxy 1967 CoAP is designed for proxy operations (see Section 5.7 of [RFC7252]). 1969 OSCORE is designed to work with OSCORE-unaware CoAP proxies. 1970 Security requirements for forwarding are listed in Section 2.2.1 of 1971 [I-D.hartke-core-e2e-security-reqs]. Proxy processing of the (Outer) 1972 Proxy-Uri option works as defined in [RFC7252]. Proxy processing of 1973 the (Outer) Block options works as defined in [RFC7959]. 1975 However, not all CoAP proxy operations are useful: 1977 o Since a CoAP response is only applicable to the original CoAP 1978 request, caching is in general not useful. In support of existing 1979 proxies, OSCORE uses the outer Max-Age option, see 1980 Section 4.1.3.1. 1982 o Proxy processing of the (Outer) Observe option as defined in 1983 [RFC7641] is specified in Section 4.1.3.5. 1985 Optionally, a CoAP proxy MAY detect OSCORE and act accordingly. An 1986 OSCORE-aware CoAP proxy: 1988 o SHALL bypass caching for the request if the OSCORE option is 1989 present 1991 o SHOULD avoid caching responses to requests with an OSCORE option 1993 In the case of Observe (see Section 4.1.3.5) the OSCORE-aware CoAP 1994 proxy: 1996 o SHALL NOT initiate an Observe registration 1998 o MAY verify the order of notifications using Partial IV rather than 1999 the Observe option 2001 11. HTTP Operations 2003 The CoAP request/response model may be mapped to HTTP and vice versa 2004 as described in Section 10 of [RFC7252]. The HTTP-CoAP mapping is 2005 further detailed in [RFC8075]. This section defines the components 2006 needed to map and transport OSCORE messages over HTTP hops. By 2007 mapping between HTTP and CoAP and by using cross-protocol proxies 2008 OSCORE may be used end-to-end between e.g. an HTTP client and a CoAP 2009 server. Examples are provided at the end of the section. 2011 11.1. The HTTP OSCORE Header Field 2013 The HTTP OSCORE Header Field (see Section 13.4) is used for carrying 2014 the content of the CoAP OSCORE option when transporting OSCORE 2015 messages over HTTP hops. 2017 The HTTP OSCORE header field is only used in POST requests and 200 2018 (OK) responses. When used, the HTTP header field Content-Type is set 2019 to 'application/oscore' (see Section 13.5) indicating that the HTTP 2020 body of this message contains the OSCORE payload (see Section 6.2). 2021 No additional semantics is provided by other message fields. 2023 Using the Augmented Backus-Naur Form (ABNF) notation of [RFC5234], 2024 including the following core ABNF syntax rules defined by that 2025 specification: ALPHA (letters) and DIGIT (decimal digits), the HTTP 2026 OSCORE header field value is as follows. 2028 base64url-char = ALPHA / DIGIT / "-" / "_" 2030 OSCORE = 2*base64url-char 2032 The HTTP OSCORE header field is not appropriate to list in the 2033 Connection header field (see Section 6.1 of [RFC7230]) since it is 2034 not hop-by-hop. OSCORE messages are generally not useful when served 2035 from cache (i.e., they will generally be marked Cache-Control: no- 2036 cache) and so interaction with Vary is not relevant (Section 7.1.4 of 2037 [RFC7231]). Since the HTTP OSCORE header field is critical for 2038 message processing, moving it from headers to trailers renders the 2039 message unusable in case trailers are ignored (see Section 4.1 of 2040 [RFC7230]). 2042 Intermediaries are in general not allowed to insert, delete, or 2043 modify the OSCORE header. Changes to the HTTP OSCORE header field 2044 will in general violate the integrity of the OSCORE message resulting 2045 in an error. For the same reason the HTTP OSCORE header field is in 2046 general not preserved across redirects. 2048 Since redirects are not defined in the mappings between HTTP and CoAP 2049 [RFC8075][RFC7252], a number of conditions need to be fulfilled for 2050 redirects to work. For CoAP client to HTTP server, such conditions 2051 include: 2053 o the CoAP-to-HTTP proxy follows the redirect, instead of the CoAP 2054 client as in the HTTP case 2056 o the CoAP-to-HTTP proxy copies the HTTP OSCORE header field and 2057 body to the new request 2059 o the target of the redirect has the necessary OSCORE security 2060 context required to decrypt and verify the message 2062 Since OSCORE requires HTTP body to be preserved across redirects, the 2063 HTTP server is recommended to reply with 307 or 308 instead of 301 or 2064 302. 2066 For the case of HTTP client to CoAP server, although redirect is not 2067 defined for CoAP servers [RFC7252], an HTTP client receiving a 2068 redirect should generate a new OSCORE request for the server it was 2069 redirected to. 2071 11.2. CoAP-to-HTTP Mapping 2073 Section 10.1 of [RFC7252] describes the fundamentals of the CoAP-to- 2074 HTTP cross-protocol mapping process. The additional rules for OSCORE 2075 messages are: 2077 o The HTTP OSCORE header field value is set to 2079 * AA if the CoAP OSCORE option is empty, otherwise 2081 * the value of the CoAP OSCORE option (Section 6.1) in base64url 2082 (Section 5 of [RFC4648]) encoding without padding. 2083 Implementation notes for this encoding are given in Appendix C 2084 of [RFC7515]. 2086 o The HTTP Content-Type is set to 'application/oscore' (see 2087 Section 13.5), independent of CoAP Content-Format. 2089 11.3. HTTP-to-CoAP Mapping 2091 Section 10.2 of [RFC7252] and [RFC8075] specify the behavior of an 2092 HTTP-to-CoAP proxy. The additional rules for HTTP messages with the 2093 OSCORE header field are: 2095 o The CoAP OSCORE option is set as follows: 2097 * empty if the value of the HTTP OSCORE header field is a single 2098 zero byte (0x00) represented by AA, otherwise 2100 * the value of the HTTP OSCORE header field decoded from 2101 base64url (Section 5 of [RFC4648]) without padding. 2102 Implementation notes for this encoding are given in Appendix C 2103 of [RFC7515]. 2105 o The CoAP Content-Format option is omitted, the content format for 2106 OSCORE (Section 13.6) MUST NOT be used. 2108 11.4. HTTP Endpoints 2110 Restricted to subsets of HTTP and CoAP supporting a bijective 2111 mapping, OSCORE can be originated or terminated in HTTP endpoints. 2113 The sending HTTP endpoint uses [RFC8075] to translate the HTTP 2114 message into a CoAP message. The CoAP message is then processed with 2115 OSCORE as defined in this document. The OSCORE message is then 2116 mapped to HTTP as described in Section 11.2 and sent in compliance 2117 with the rules in Section 11.1. 2119 The receiving HTTP endpoint maps the HTTP message to a CoAP message 2120 using [RFC8075] and Section 11.3. The resulting OSCORE message is 2121 processed as defined in this document. If successful, the plaintext 2122 CoAP message is translated to HTTP for normal processing in the 2123 endpoint. 2125 11.5. Example: HTTP Client and CoAP Server 2127 This section is giving an example of how a request and a response 2128 between an HTTP client and a CoAP server could look like. The 2129 example is not a test vector but intended as an illustration of how 2130 the message fields are translated in the different steps. 2132 Mapping and notation here is based on "Simple Form" (Section 5.4.1 of 2133 [RFC8075]). 2135 [HTTP request -- Before client object security processing] 2137 GET http://proxy.url/hc/?target_uri=coap://server.url/orders 2138 HTTP/1.1 2140 [HTTP request -- HTTP Client to Proxy] 2142 POST http://proxy.url/hc/?target_uri=coap://server.url/ HTTP/1.1 2143 Content-Type: application/oscore 2144 OSCORE: CSU 2145 Body: 09 07 01 13 61 f7 0f d2 97 b1 [binary] 2147 [CoAP request -- Proxy to CoAP Server] 2149 POST coap://server.url/ 2150 OSCORE: 09 25 2151 Payload: 09 07 01 13 61 f7 0f d2 97 b1 [binary] 2153 [CoAP request -- After server object security processing] 2155 GET coap://server.url/orders 2157 [CoAP response -- Before server object security processing] 2159 2.05 Content 2160 Content-Format: 0 2161 Payload: Exterminate! Exterminate! 2163 [CoAP response -- CoAP Server to Proxy] 2165 2.04 Changed 2166 OSCORE: [empty] 2167 Payload: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] 2169 [HTTP response -- Proxy to HTTP Client] 2171 HTTP/1.1 200 OK 2172 Content-Type: application/oscore 2173 OSCORE: AA 2174 Body: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] 2176 [HTTP response -- After client object security processing] 2178 HTTP/1.1 200 OK 2179 Content-Type: text/plain 2180 Body: Exterminate! Exterminate! 2182 Note that the HTTP Status Code 200 in the next-to-last message is the 2183 mapping of CoAP Code 2.04 (Changed), whereas the HTTP Status Code 200 2184 in the last message is the mapping of the CoAP Code 2.05 (Content), 2185 which was encrypted within the compressed COSE object carried in the 2186 Body of the HTTP response. 2188 11.6. Example: CoAP Client and HTTP Server 2190 This section is giving an example of how a request and a response 2191 between a CoAP client and an HTTP server could look like. The 2192 example is not a test vector but intended as an illustration of how 2193 the message fields are translated in the different steps 2195 [CoAP request -- Before client object security processing] 2197 GET coap://proxy.url/ 2198 Proxy-Uri=http://server.url/orders 2200 [CoAP request -- CoAP Client to Proxy] 2202 POST coap://proxy.url/ 2203 Proxy-Uri=http://server.url/ 2204 OSCORE: 09 25 2205 Payload: 09 07 01 13 61 f7 0f d2 97 b1 [binary] 2207 [HTTP request -- Proxy to HTTP Server] 2209 POST http://server.url/ HTTP/1.1 2210 Content-Type: application/oscore 2211 OSCORE: CSU 2212 Body: 09 07 01 13 61 f7 0f d2 97 b1 [binary] 2214 [HTTP request -- After server object security processing] 2216 GET http://server.url/orders HTTP/1.1 2218 [HTTP response -- Before server object security processing] 2220 HTTP/1.1 200 OK 2221 Content-Type: text/plain 2222 Body: Exterminate! Exterminate! 2224 [HTTP response -- HTTP Server to Proxy] 2226 HTTP/1.1 200 OK 2227 Content-Type: application/oscore 2228 OSCORE: AA 2229 Body: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] 2231 [CoAP response -- Proxy to CoAP Client] 2233 2.04 Changed 2234 OSCORE: [empty] 2235 Payload: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] 2237 [CoAP response -- After client object security processing] 2239 2.05 Content 2240 Content-Format: 0 2241 Payload: Exterminate! Exterminate! 2243 Note that the HTTP Code 2.04 (Changed) in the next-to-last message is 2244 the mapping of HTTP Status Code 200, whereas the CoAP Code 2.05 2245 (Content) in the last message is the value that was encrypted within 2246 the compressed COSE object carried in the Body of the HTTP response. 2248 12. Security Considerations 2250 An overview of the security properties is given in Appendix D. 2252 12.1. End-to-end Protection 2254 In scenarios with intermediary nodes such as proxies or gateways, 2255 transport layer security such as (D)TLS only protects data hop-by- 2256 hop. As a consequence, the intermediary nodes can read and modify 2257 any information. The trust model where all intermediary nodes are 2258 considered trustworthy is problematic, not only from a privacy 2259 perspective, but also from a security perspective, as the 2260 intermediaries are free to delete resources on sensors and falsify 2261 commands to actuators (such as "unlock door", "start fire alarm", 2262 "raise bridge"). Even in the rare cases where all the owners of the 2263 intermediary nodes are fully trusted, attacks and data breaches make 2264 such an architecture brittle. 2266 (D)TLS protects hop-by-hop the entire message. OSCORE protects end- 2267 to-end all information that is not required for proxy operations (see 2268 Section 4). (D)TLS and OSCORE can be combined, thereby enabling end- 2269 to-end security of the message payload, in combination with hop-by- 2270 hop protection of the entire message, during transport between end- 2271 point and intermediary node. In particular when OSCORE is used with 2272 HTTP, the additional TLS protection of HTTP hops is recommended, e.g. 2273 between an HTTP endpoint and a proxy translating between HTTP and 2274 CoAP. 2276 Applications need to consider that certain message fields and 2277 messages types are not protected end-to-end and may be spoofed or 2278 manipulated. The consequences of unprotected message fields are 2279 analyzed in Appendix D.4. 2281 12.2. Security Context Establishment 2283 The use of COSE_Encrypt0 and AEAD to protect messages as specified in 2284 this document requires an established security context. The method 2285 to establish the security context described in Section 3.2 is based 2286 on a common Master Secret and unique Sender IDs. The necessary input 2287 parameters may be pre-established or obtained using a key 2288 establishment protocol augmented with establishment of Sender/ 2289 Recipient ID such as the OSCORE profile of the ACE framework 2290 [I-D.ietf-ace-oscore-profile]. Such a procedure must ensure that the 2291 requirements of the security context parameters for the intended use 2292 are complied with (see Section 3.3) and also in error situations. 2293 While recipient IDs are allowed to coincide between different 2294 security contexts (see Section 3.3), this may cause a server to 2295 process multiple verifications before finding the right security 2296 context or rejecting a message. Moreover, it is recommended to use a 2297 key establishment protocol which provides forward secrecy whenever 2298 possible. Considerations for deploying OSCORE with a fixed Master 2299 Secret are given in Appendix B. 2301 12.3. Master Secret 2303 OSCORE uses HKDF [RFC5869] and the established input parameters to 2304 derive the security context. The required properties of the security 2305 context parameters are discussed in Section 3.3, in this section we 2306 focus on the Master Secret. HKDF denotes in this specification the 2307 composition of the expand and extract functions as defined in 2308 [RFC5869] and the Master Secret is used as Input Key Material (IKM). 2310 Informally, HKDF takes as source an IKM containing some good amount 2311 of randomness but not necessarily distributed uniformly (or for which 2312 an attacker has some partial knowledge) and derive from it one or 2313 more cryptographically strong secret keys [RFC5869]. 2315 Therefore, the main requirement for the OSCORE Master Secret, in 2316 addition to being secret, is that it is has a good amount of 2317 randomness. The selected key establishment schemes must ensure that 2318 the necessary properties for the Master Secret are fulfilled. For 2319 pre-shared key deployments and key transport solutions such as 2320 [I-D.ietf-ace-oscore-profile], the Master Secret can be generated 2321 offline using a good random number generator. Randomness 2322 requirements for security are described in [RFC4086]. 2324 12.4. Replay Protection 2326 Replay attacks need to be considered in different parts of the 2327 implementation. Most AEAD algorithms require a unique nonce for each 2328 message, for which the sender sequence numbers in the COSE message 2329 field 'Partial IV' is used. If the recipient accepts any sequence 2330 number larger than the one previously received, then the problem of 2331 sequence number synchronization is avoided. With reliable transport, 2332 it may be defined that only messages with sequence number which are 2333 equal to previous sequence number + 1 are accepted. An adversary may 2334 try to induce a device reboot for the purpose of replaying a message 2335 (see Section 7.5). 2337 Note that sharing a security context between servers may open up for 2338 replay attacks, for example if the replay windows are not 2339 synchronized. 2341 12.5. Client Aliveness 2343 A verified OSCORE request enables the server to verify the identity 2344 of the entity who generated the message. However, it does not verify 2345 that the client is currently involved in the communication, since the 2346 message may be a delayed delivery of a previously generated request 2347 which now reaches the server. To verify the aliveness of the client 2348 the server may use the Echo option in the response to a request from 2349 the client (see [I-D.ietf-core-echo-request-tag]). 2351 12.6. Cryptographic Considerations 2353 The maximum sender sequence number is dependent on the AEAD 2354 algorithm. The maximum sender sequence number is 2^40 - 1, or any 2355 algorithm specific lower limit, after which a new security context 2356 must be generated. The mechanism to build the AEAD nonce 2357 (Section 5.2) assumes that the nonce is at least 56 bits, and the 2358 Partial IV is at most 40 bits. The mandatory-to-implement AEAD 2359 algorithm AES-CCM-16-64-128 is selected for compatibility with CCM*. 2360 AEAD algorithms that require unpredictable nonces are not supported. 2362 In order to prevent cryptanalysis when the same plaintext is 2363 repeatedly encrypted by many different users with distinct AEAD keys, 2364 the AEAD nonce is formed by mixing the sequence number with a secret 2365 per-context initialization vector (Common IV) derived along with the 2366 keys (see Section 3.1 of [RFC8152]), and by using a Master Salt in 2367 the key derivation (see [MF00] for an overview). The Master Secret, 2368 Sender Key, Recipient Key, and Common IV must be secret, the rest of 2369 the parameters may be public. The Master Secret must have a good 2370 amount of randomness (see Section 12.3). 2372 12.7. Message Segmentation 2374 The Inner Block options enable the sender to split large messages 2375 into OSCORE-protected blocks such that the receiving endpoint can 2376 verify blocks before having received the complete message. The Outer 2377 Block options allow for arbitrary proxy fragmentation operations that 2378 cannot be verified by the endpoints, but can by policy be restricted 2379 in size since the Inner Block options allow for secure fragmentation 2380 of very large messages. A maximum message size (above which the 2381 sending endpoint fragments the message and the receiving endpoint 2382 discards the message, if complying to the policy) may be obtained as 2383 part of normal resource discovery. 2385 12.8. Privacy Considerations 2387 Privacy threats executed through intermediary nodes are considerably 2388 reduced by means of OSCORE. End-to-end integrity protection and 2389 encryption of the message payload and all options that are not used 2390 for proxy operations, provide mitigation against attacks on sensor 2391 and actuator communication, which may have a direct impact on the 2392 personal sphere. 2394 The unprotected options (Figure 5) may reveal privacy sensitive 2395 information, see Appendix D.4. CoAP headers sent in plaintext allow, 2396 for example, matching of CON and ACK (CoAP Message Identifier), 2397 matching of request and responses (Token) and traffic analysis. 2398 OSCORE does not provide protection for HTTP header fields which are 2399 not both CoAP-mappable and class E. The HTTP message fields which 2400 are visible to on-path entity are only used for the purpose of 2401 transporting the OSCORE message, whereas the application layer 2402 message is encoded in CoAP and encrypted. 2404 COSE message fields, i.e. the OSCORE option, may reveal information 2405 about the communicating endpoints. E.g. 'kid' and 'kid context', 2406 which are intended to help the server find the right context, may 2407 reveal information about the client. Tracking 'kid' and 'kid 2408 context' to one server may be used for correlating requests from one 2409 client. 2411 Unprotected error messages reveal information about the security 2412 state in the communication between the endpoints. Unprotected 2413 signaling messages reveal information about the reliable transport 2414 used on a leg of the path. Using the mechanisms described in 2415 Section 7.5 may reveal when a device goes through a reboot. This can 2416 be mitigated by the device storing the precise state of sender 2417 sequence number and replay window on a clean shutdown. 2419 The length of message fields can reveal information about the 2420 message. Applications may use a padding scheme to protect against 2421 traffic analysis. 2423 13. IANA Considerations 2425 Note to RFC Editor: Please replace all occurrences of "[[this 2426 document]]" with the RFC number of this specification. 2428 Note to IANA: Please note all occurrences of "TBDx" in this 2429 specification should be assigned the same number. 2431 13.1. COSE Header Parameters Registry 2433 The 'kid context' parameter is added to the "COSE Header Parameters 2434 Registry": 2436 o Name: kid context 2438 o Label: TBD2 2440 o Value Type: bstr 2442 o Value Registry: 2444 o Description: Identifies the context for kid 2446 o Reference: Section 5.1 of this document 2448 Note to IANA: Label assignment in (Integer value between 1 and 255) 2449 is requested. (RFC Editor: Delete this note after IANA assignment) 2451 13.2. CoAP Option Numbers Registry 2453 The OSCORE option is added to the CoAP Option Numbers registry: 2455 +--------+-----------------+-------------------+ 2456 | Number | Name | Reference | 2457 +--------+-----------------+-------------------+ 2458 | TBD1 | OSCORE | [[this document]] | 2459 +--------+-----------------+-------------------+ 2461 Note to IANA: Label assignment in (Integer value between 0 and 12) is 2462 requested. We also request Expert review if possible, to make sure a 2463 correct number for the option is selected (RFC Editor: Delete this 2464 note after IANA assignment) 2466 Furthermore, the following existing entries in the CoAP Option 2467 Numbers registry are updated with a reference to the document 2468 specifying OSCORE processing of that option: 2470 +--------+-----------------+---------------------------------------+ 2471 | Number | Name | Reference | 2472 +--------+-----------------+---------------------------------------+ 2473 | 1 | If-Match | [RFC7252] [[this document]] | 2474 | 3 | Uri-Host | [RFC7252] [[this document]] | 2475 | 4 | ETag | [RFC7252] [[this document]] | 2476 | 5 | If-None-Match | [RFC7252] [[this document]] | 2477 | 6 | Observe | [RFC7641] [[this document]] | 2478 | 7 | Uri-Port | [RFC7252] [[this document]] | 2479 | 8 | Location-Path | [RFC7252] [[this document]] | 2480 | 11 | Uri-Path | [RFC7252] [[this document]] | 2481 | 12 | Content-Format | [RFC7252] [[this document]] | 2482 | 14 | Max-Age | [RFC7252] [[this document]] | 2483 | 15 | Uri-Query | [RFC7252] [[this document]] | 2484 | 17 | Accept | [RFC7252] [[this document]] | 2485 | 20 | Location-Query | [RFC7252] [[this document]] | 2486 | 23 | Block2 | [RFC7959] [RFC8323] [[this document]] | 2487 | 27 | Block1 | [RFC7959] [RFC8323] [[this document]] | 2488 | 28 | Size2 | [RFC7959] [[this document]] | 2489 | 35 | Proxy-Uri | [RFC7252] [[this document]] | 2490 | 39 | Proxy-Scheme | [RFC7252] [[this document]] | 2491 | 60 | Size1 | [RFC7252] [[this document]] | 2492 | 258 | No-Response | [RFC7967] [[this document]] | 2493 +--------+-----------------+---------------------------------------+ 2495 Future additions to the CoAP Option Numbers registry need to provide 2496 a reference to the document where the OSCORE processing of that CoAP 2497 Option is defined. 2499 13.3. CoAP Signaling Option Numbers Registry 2501 The OSCORE option is added to the CoAP Signaling Option Numbers 2502 registry: 2504 +------------+--------+---------------------+-------------------+ 2505 | Applies to | Number | Name | Reference | 2506 +------------+--------+---------------------+-------------------+ 2507 | 7.xx (all) | TBD1 | OSCORE | [[this document]] | 2508 +------------+--------+---------------------+-------------------+ 2510 Note to IANA: The value in the "Number" field is the same value 2511 that's being assigned to the new Option Number. Please make sure 2512 TBD1 is not the same as any value in Numbers for any existing entry 2513 in the CoAP Signaling Option Numbers registry (at the time of writing 2514 this, that means make sure TBD1 is not 2 or 4)(RFC Editor: Delete 2515 this note after IANA assignment) 2517 13.4. Header Field Registrations 2519 The HTTP OSCORE header field is added to the Message Headers 2520 registry: 2522 +-------------------+----------+----------+---------------------------------+ 2523 | Header Field Name | Protocol | Status | Reference | 2524 +-------------------+----------+----------+---------------------------------+ 2525 | OSCORE | http | standard | [[this document]], Section 11.1 | 2526 +-------------------+----------+----------+---------------------------------+ 2528 13.5. Media Type Registrations 2530 This section registers the 'application/oscore' media type in the 2531 "Media Types" registry. These media types are used to indicate that 2532 the content is an OSCORE message. The OSCORE body cannot be 2533 understood without the OSCORE header field value and the security 2534 context. 2536 Type name: application 2538 Subtype name: oscore 2540 Required parameters: N/A 2542 Optional parameters: N/A 2544 Encoding considerations: binary 2546 Security considerations: See the Security Considerations section 2547 of [[This document]]. 2549 Interoperability considerations: N/A 2551 Published specification: [[This document]] 2553 Applications that use this media type: IoT applications sending 2554 security content over HTTP(S) transports. 2556 Fragment identifier considerations: N/A 2558 Additional information: 2560 * Deprecated alias names for this type: N/A 2562 * Magic number(s): N/A 2564 * File extension(s): N/A 2566 * Macintosh file type code(s): N/A 2568 Person & email address to contact for further information: 2569 iesg@ietf.org 2571 Intended usage: COMMON 2573 Restrictions on usage: N/A 2575 Author: Goeran Selander, goran.selander@ericsson.com 2577 Change Controller: IESG 2579 Provisional registration? No 2581 13.6. CoAP Content-Formats Registry 2583 Note to IANA: ID assignment in the 10000-64999 range is requested. 2584 (RFC Editor: Delete this note after IANA assignment) 2586 This section registers the media type 'application/oscore' media type 2587 in the "CoAP Content-Formats" registry. This Content-Format for the 2588 OSCORE payload is defined for potential future use cases and SHALL 2589 NOT be used in the OSCORE message. The OSCORE payload cannot be 2590 understood without the OSCORE option value and the security context. 2592 +----------------------+----------+----------+-------------------+ 2593 | Media Type | Encoding | ID | Reference | 2594 +----------------------+----------+----------+-------------------+ 2595 | application/oscore | | TBD3 | [[this document]] | 2596 +----------------------+----------+----------+-------------------+ 2598 13.7. OSCORE Flag Bits Registry 2600 This document defines a sub-registry for the OSCORE flag bits within 2601 the "CoRE Parameters" registry. The name of the sub-registry is 2602 "OSCORE Flag Bits". The registry should be created with the Expert 2603 Review policy. Guidelines for the experts are provided in 2604 Section 13.8. 2606 The columns of the registry are: 2608 o bit position: This indicates the position of the bit in the set of 2609 OSCORE flag bits, starting at 0 for the most significant bit. The 2610 bit position must be an integer or a range of integers, in the 2611 range 0 to 63. 2613 o name: The name is present to make it easier to refer to and 2614 discuss the registration entry. The value is not used in the 2615 protocol. Names are to be unique in the table. 2617 o description: This contains a brief description of the use of the 2618 bit. 2620 o specification: This contains a pointer to the specification 2621 defining the entry. 2623 The initial contents of the registry can be found in the table below. 2624 The specification column for all rows in that table should be this 2625 document. The entries with Bit Position of 0 and 1 are to be marked 2626 as 'Reserved'. The entry with Bit Position of 1 is going to be 2627 specified in a future document, and will be used to expand the space 2628 for the OSCORE flag bits in Section 6.1, so that entries 8-63 of the 2629 registry are defined. 2631 +--------------+-------------+---------------------+-------------------+ 2632 | Bit Position | Name | Description | Specification | 2633 +--------------+-------------+---------------------+-------------------+ 2634 | 0 | Reserved | | | 2635 +--------------+-------------+---------------------+-------------------+ 2636 | 1 | Reserved | | | 2637 +--------------+-------------+---------------------+-------------------+ 2638 | 2 | Unassigned | | | 2639 +--------------+-------------+---------------------+-------------------+ 2640 | 3 | Kid Context | Set to 1 if kid | [[this document]] | 2641 | | Flag | context is present | | 2642 | | | in the compressed | | 2643 | | | COSE object | | 2644 +--------------+-------------+---------------------+-------------------+ 2645 | 4 | Kid Flag | Set to 1 if kid is | [[this document]] | 2646 | | | present in the com- | | 2647 | | | pressed COSE object | | 2648 +--------------+-------------+---------------------+-------------------+ 2649 | 5-7 | Partial IV | Encodes the Partial | [[this document]] | 2650 | | Length | IV length; can have | | 2651 | | | value 0 to 5 | | 2652 +--------------+-------------+---------------------+-------------------+ 2653 | 8-63 | Unassigned | | | 2654 +--------------+-------------+---------------------+-------------------+ 2656 13.8. Expert Review Instructions 2658 The expert reviewers for the registry defined in this document are 2659 expected to ensure that the usage solves a valid use case that could 2660 not be solved better in a different way, that it is not going to 2661 duplicate one that is already registered, and that the registered 2662 point is likely to be used in deployments. They are furthermore 2663 expected to check the clarity of purpose and use of the requested 2664 code points. Experts should take into account the expected usage of 2665 entries when approving point assignment, and the length of the 2666 encoded value should be weighed against the number of code points 2667 left that encode to that size and the size of device it will be used 2668 on. Experts should block registration for entries 8-63 until these 2669 points are defined (i.e. until the mechanism for the OSCORE flag bits 2670 expansion via bit 1 is specified). 2672 14. References 2674 14.1. Normative References 2676 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2677 Requirement Levels", BCP 14, RFC 2119, 2678 DOI 10.17487/RFC2119, March 1997, 2679 . 2681 [RFC4086] Eastlake 3rd, D., Schiller, J., and S. Crocker, 2682 "Randomness Requirements for Security", BCP 106, RFC 4086, 2683 DOI 10.17487/RFC4086, June 2005, 2684 . 2686 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 2687 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 2688 . 2690 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 2691 Specifications: ABNF", STD 68, RFC 5234, 2692 DOI 10.17487/RFC5234, January 2008, 2693 . 2695 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 2696 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 2697 January 2012, . 2699 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 2700 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 2701 October 2013, . 2703 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 2704 Protocol (HTTP/1.1): Message Syntax and Routing", 2705 RFC 7230, DOI 10.17487/RFC7230, June 2014, 2706 . 2708 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 2709 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 2710 DOI 10.17487/RFC7231, June 2014, 2711 . 2713 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 2714 Application Protocol (CoAP)", RFC 7252, 2715 DOI 10.17487/RFC7252, June 2014, 2716 . 2718 [RFC7641] Hartke, K., "Observing Resources in the Constrained 2719 Application Protocol (CoAP)", RFC 7641, 2720 DOI 10.17487/RFC7641, September 2015, 2721 . 2723 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 2724 the Constrained Application Protocol (CoAP)", RFC 7959, 2725 DOI 10.17487/RFC7959, August 2016, 2726 . 2728 [RFC8075] Castellani, A., Loreto, S., Rahman, A., Fossati, T., and 2729 E. Dijk, "Guidelines for Mapping Implementations: HTTP to 2730 the Constrained Application Protocol (CoAP)", RFC 8075, 2731 DOI 10.17487/RFC8075, February 2017, 2732 . 2734 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 2735 FETCH Methods for the Constrained Application Protocol 2736 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 2737 . 2739 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 2740 RFC 8152, DOI 10.17487/RFC8152, July 2017, 2741 . 2743 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2744 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2745 May 2017, . 2747 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 2748 DOI 10.17487/RFC8288, October 2017, 2749 . 2751 [RFC8323] Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 2752 Silverajan, B., and B. Raymor, Ed., "CoAP (Constrained 2753 Application Protocol) over TCP, TLS, and WebSockets", 2754 RFC 8323, DOI 10.17487/RFC8323, February 2018, 2755 . 2757 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 2758 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 2759 . 2761 14.2. Informative References 2763 [I-D.bormann-6lo-coap-802-15-ie] 2764 Bormann, C., "Constrained Application Protocol (CoAP) over 2765 IEEE 802.15.4 Information Element for IETF", draft- 2766 bormann-6lo-coap-802-15-ie-00 (work in progress), April 2767 2016. 2769 [I-D.hartke-core-e2e-security-reqs] 2770 Selander, G., Palombini, F., and K. Hartke, "Requirements 2771 for CoAP End-To-End Security", draft-hartke-core-e2e- 2772 security-reqs-03 (work in progress), July 2017. 2774 [I-D.ietf-ace-oauth-authz] 2775 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 2776 H. Tschofenig, "Authentication and Authorization for 2777 Constrained Environments (ACE) using the OAuth 2.0 2778 Framework (ACE-OAuth)", draft-ietf-ace-oauth-authz-13 2779 (work in progress), July 2018. 2781 [I-D.ietf-ace-oscore-profile] 2782 Seitz, L., Palombini, F., Gunnarsson, M., and G. Selander, 2783 "OSCORE profile of the Authentication and Authorization 2784 for Constrained Environments Framework", draft-ietf-ace- 2785 oscore-profile-02 (work in progress), June 2018. 2787 [I-D.ietf-cbor-cddl] 2788 Birkholz, H., Vigano, C., and C. Bormann, "Concise data 2789 definition language (CDDL): a notational convention to 2790 express CBOR and JSON data structures", draft-ietf-cbor- 2791 cddl-05 (work in progress), August 2018. 2793 [I-D.ietf-core-echo-request-tag] 2794 Amsuess, C., Mattsson, J., and G. Selander, "Echo and 2795 Request-Tag", draft-ietf-core-echo-request-tag-02 (work in 2796 progress), June 2018. 2798 [I-D.ietf-core-oscore-groupcomm] 2799 Tiloca, M., Selander, G., Palombini, F., and J. Park, 2800 "Secure group communication for CoAP", draft-ietf-core- 2801 oscore-groupcomm-02 (work in progress), June 2018. 2803 [I-D.mattsson-core-coap-actuators] 2804 Mattsson, J., Fornehed, J., Selander, G., Palombini, F., 2805 and C. Amsuess, "Controlling Actuators with CoAP", draft- 2806 mattsson-core-coap-actuators-05 (work in progress), March 2807 2018. 2809 [I-D.mcgrew-iv-gen] 2810 McGrew, D., "Generation of Deterministic Initialization 2811 Vectors (IVs) and Nonces", draft-mcgrew-iv-gen-03 (work in 2812 progress), October 2013. 2814 [MF00] McGrew, D. and S. Fluhrer, "Attacks on Encryption of 2815 Redundant Plaintext and Implications on Internet 2816 Security", the Proceedings of the Seventh Annual Workshop 2817 on Selected Areas in Cryptography (SAC 2000), Springer- 2818 Verlag. , 2000. 2820 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2821 Resource Identifier (URI): Generic Syntax", STD 66, 2822 RFC 3986, DOI 10.17487/RFC3986, January 2005, 2823 . 2825 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 2826 Encryption", RFC 5116, DOI 10.17487/RFC5116, January 2008, 2827 . 2829 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 2830 Key Derivation Function (HKDF)", RFC 5869, 2831 DOI 10.17487/RFC5869, May 2010, 2832 . 2834 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 2835 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 2836 . 2838 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 2839 Constrained-Node Networks", RFC 7228, 2840 DOI 10.17487/RFC7228, May 2014, 2841 . 2843 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 2844 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 2845 2015, . 2847 [RFC7967] Bhattacharyya, A., Bandyopadhyay, S., Pal, A., and T. 2848 Bose, "Constrained Application Protocol (CoAP) Option for 2849 No Server Response", RFC 7967, DOI 10.17487/RFC7967, 2850 August 2016, . 2852 Appendix A. Scenario Examples 2854 This section gives examples of OSCORE, targeting scenarios in 2855 Section 2.2.1.1 of [I-D.hartke-core-e2e-security-reqs]. The message 2856 exchanges are made, based on the assumption that there is a security 2857 context established between client and server. For simplicity, these 2858 examples only indicate the content of the messages without going into 2859 detail of the (compressed) COSE message format. 2861 A.1. Secure Access to Sensor 2863 This example illustrates a client requesting the alarm status from a 2864 server. 2866 Client Proxy Server 2867 | | | 2868 +------>| | Code: 0.02 (POST) 2869 | POST | | Token: 0x8c 2870 | | | OSCORE: [kid:5f,Partial IV:42] 2871 | | | Payload: {Code:0.01, 2872 | | | Uri-Path:"alarm_status"} 2873 | | | 2874 | +------>| Code: 0.02 (POST) 2875 | | POST | Token: 0x7b 2876 | | | OSCORE: [kid:5f,Partial IV:42] 2877 | | | Payload: {Code:0.01, 2878 | | | Uri-Path:"alarm_status"} 2879 | | | 2880 | |<------+ Code: 2.04 (Changed) 2881 | | 2.04 | Token: 0x7b 2882 | | | OSCORE: - 2883 | | | Payload: {Code:2.05, "0"} 2884 | | | 2885 |<------+ | Code: 2.04 (Changed) 2886 | 2.04 | | Token: 0x8c 2887 | | | OSCORE: - 2888 | | | Payload: {Code:2.05, "0"} 2889 | | | 2891 Figure 12: Secure Access to Sensor. Square brackets [ ... ] indicate 2892 content of compressed COSE object. Curly brackets { ... } indicate 2893 encrypted data. 2895 The request/response Codes are encrypted by OSCORE and only dummy 2896 Codes (POST/Changed) are visible in the header of the OSCORE message. 2897 The option Uri-Path ("alarm_status") and payload ("0") are encrypted. 2899 The COSE header of the request contains an identifier (5f), 2900 indicating which security context was used to protect the message and 2901 a Partial IV (42). 2903 The server verifies the request as specified in Section 8.2. The 2904 client verifies the response as specified in Section 8.4. 2906 A.2. Secure Subscribe to Sensor 2908 This example illustrates a client requesting subscription to a blood 2909 sugar measurement resource (GET /glucose), first receiving the value 2910 220 mg/dl and then a second value 180 mg/dl. 2912 Client Proxy Server 2913 | | | 2914 +------>| | Code: 0.05 (FETCH) 2915 | FETCH | | Token: 0x83 2916 | | | Observe: 0 2917 | | | OSCORE: [kid:ca,Partial IV:15] 2918 | | | Payload: {Code:0.01, 2919 | | | Uri-Path:"glucose"} 2920 | | | 2921 | +------>| Code: 0.05 (FETCH) 2922 | | FETCH | Token: 0xbe 2923 | | | Observe: 0 2924 | | | OSCORE: [kid:ca,Partial IV:15] 2925 | | | Payload: {Code:0.01, 2926 | | | Uri-Path:"glucose"} 2927 | | | 2928 | |<------+ Code: 2.05 (Content) 2929 | | 2.05 | Token: 0xbe 2930 | | | Observe: 7 2931 | | | OSCORE: [Partial IV:32] 2932 | | | Payload: {Code:2.05, 2933 | | | Content-Format:0, "220"} 2934 | | | 2935 |<------+ | Code: 2.05 (Content) 2936 | 2.05 | | Token: 0x83 2937 | | | Observe: 7 2938 | | | OSCORE: [Partial IV:32] 2939 | | | Payload: {Code:2.05, 2940 | | | Content-Format:0, "220"} 2941 ... ... ... 2942 | | | 2943 | |<------+ Code: 2.05 (Content) 2944 | | 2.05 | Token: 0xbe 2945 | | | Observe: 8 2946 | | | OSCORE: [Partial IV:36] 2947 | | | Payload: {Code:2.05, 2948 | | | Content-Format:0, "180"} 2949 | | | 2950 |<------+ | Code: 2.05 (Content) 2951 | 2.05 | | Token: 0x83 2952 | | | Observe: 8 2953 | | | OSCORE: [Partial IV:36] 2954 | | | Payload: {Code:2.05, 2955 | | | Content-Format:0, "180"} 2956 | | | 2958 Figure 13: Secure Subscribe to Sensor. Square brackets [ ... ] 2959 indicate content of compressed COSE object header. Curly brackets { 2960 ... } indicate encrypted data. 2962 The dummy Codes (FETCH/Content) are used to allow forwarding of 2963 Observe messages. The options Content-Format (0) and the payload 2964 ("220" and "180"), are encrypted. 2966 The COSE header of the request contains an identifier (ca), 2967 indicating the security context used to protect the message and a 2968 Partial IV (15). The COSE headers of the responses contains Partial 2969 IVs (32 and 36). 2971 The server verifies that the Partial IV has not been received before. 2972 The client verifies that the responses are bound to the request and 2973 that the Partial IVs are greater than any Partial IV previously 2974 received in a response bound to the request. 2976 Appendix B. Deployment Examples 2978 Two examples complying with the requirements on the security context 2979 parameters (Section 3.3) are given in this section. 2981 B.1. Master Secret Used Once 2983 An application may derive a security context once and use it for the 2984 lifetime of a device. For many IoT deployments, a 128 bit uniformly 2985 random Master Key is sufficient for encrypting all data exchanged 2986 with the IoT device. This specification describes techniques for 2987 persistent storage of the security context and synchronization of 2988 sequence numbers (see Section 7.5) to ensure that security is 2989 maintained with the existing security context. 2991 B.2. Master Secret Used Multiple Times 2993 Section 12.2 recommends that the Master Secret is obtained from a key 2994 establishment protocol providing forward secrecy. 2996 An application which does not require forward secrecy may allow 2997 multiple security contexts to be derived from one Master Secret. The 2998 requirements on the security context parameters must be fulfilled 2999 (Section 3.3) even if the client or server is rebooted, 3000 recommissioned or in error cases. 3002 This section gives an example of an application allowing new security 3003 contexts to be derived from input parameters pre-established between 3004 client and server for this purpose: in particular Master Secret, 3005 Master Salt and Sender/Recipient ID (see Section 3.2): 3007 o The client generates an ID Context which has previously not been 3008 used with the pre-established input parameters and derives a new 3009 security context. ID context may be pseudo-random and large for 3010 stochastic uniqueness, but care must be taken e.g. to avoid re-use 3011 of the same seed for random number generation. Using this new 3012 security context, the client generates an OSCORE request with (kid 3013 context, kid) = (ID Context, Sender ID) in the OSCORE option. 3015 o The server receiving such an OSCORE request with kid matching the 3016 Recipient ID of pre-established input parameters, but with a new 3017 kid context, derives the security context using ID Context = kid 3018 context. If the message verifies then a new security context with 3019 this ID Context is stored in the server, and used in the response. 3020 Further requests with the same (kid context, kid) are verified 3021 with this security context. 3023 As an alternative procedure to reduce the subsequent overhead in 3024 requests due to kid context, the verification of a message with a new 3025 ID Context may trigger the server to generate a new kid to replace 3026 the Client Sender ID in future requests. A client may e.g. indicate 3027 support for such a procedure by requesting a special well-known URI 3028 and receive the new kid in the response, which together with the 3029 input parameters and the ID context is used to derive the new 3030 security context which may be identified only by its kid. The 3031 details are out of scope for this specification. 3033 The procedures may be complemented with the use of the Echo option 3034 for verifying the aliveness of the client requesting a new security 3035 context. 3037 Appendix C. Test Vectors 3039 This appendix includes the test vectors for different examples of 3040 CoAP messages using OSCORE. Given a set of inputs, OSCORE defines 3041 how to set up the Security Context in both the client and the server. 3043 Note that in Appendix C.4 and all following test vectors the Token 3044 and the Message ID of the OSCORE-protected CoAP messages are set to 3045 the same value of the unprotected CoAP message, to help the reader 3046 with comparisons. 3048 [NOTE: the following examples use option number = 9 (TBD1 assigned by 3049 IANA). If that differs, the RFC editor is asked to update the test 3050 vectors with data provided by the authors. Please remove this 3051 paragraph before publication.] 3053 C.1. Test Vector 1: Key Derivation with Master Salt 3055 In this test vector, a Master Salt of 8 bytes is used. The default 3056 values are used for AEAD Algorithm and HKDF. 3058 C.1.1. Client 3060 Inputs: 3062 o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes) 3064 o Master Salt: 0x9e7ca92223786340 (8 bytes) 3066 o Sender ID: 0x (0 byte) 3068 o Recipient ID: 0x01 (1 byte) 3070 From the previous parameters, 3072 o info (for Sender Key): 0x8540f60a634b657910 (9 bytes) 3074 o info (for Recipient Key): 0x854101f60a634b657910 (10 bytes) 3076 o info (for Common IV): 0x8540f60a6249560d (8 bytes) 3078 Outputs: 3080 o Sender Key: 0xf0910ed7295e6ad4b54fc793154302ff (16 bytes) 3082 o Recipient Key: 0xffb14e093c94c9cac9471648b4f98710 (16 bytes) 3084 o Common IV: 0x4622d4dd6d944168eefb54987c (13 bytes) 3086 From the previous parameters and a Partial IV equal to 0 (both for 3087 sender and recipient): 3089 o sender nonce: 0x4622d4dd6d944168eefb54987c (13 bytes) 3091 o recipient nonce: 0x4722d4dd6d944169eefb54987c (13 bytes) 3093 C.1.2. Server 3095 Inputs: 3097 o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes) 3098 o Master Salt: 0x9e7ca92223786340 (8 bytes) 3100 o Sender ID: 0x01 (1 byte) 3102 o Recipient ID: 0x (0 byte) 3104 From the previous parameters, 3106 o info (for Sender Key): 0x854101f60a634b657910 (10 bytes) 3108 o info (for Recipient Key): 0x8540f60a634b657910 (9 bytes) 3110 o info (for Common IV): 0x8540f60a6249560d (8 bytes) 3112 Outputs: 3114 o Sender Key: 0xffb14e093c94c9cac9471648b4f98710 (16 bytes) 3116 o Recipient Key: 0xf0910ed7295e6ad4b54fc793154302ff (16 bytes) 3118 o Common IV: 0x4622d4dd6d944168eefb54987c (13 bytes) 3120 From the previous parameters and a Partial IV equal to 0 (both for 3121 sender and recipient): 3123 o sender nonce: 0x4722d4dd6d944169eefb54987c (13 bytes) 3125 o recipient nonce: 0x4622d4dd6d944168eefb54987c (13 bytes) 3127 C.2. Test Vector 2: Key Derivation without Master Salt 3129 In this test vector, the default values are used for AEAD Algorithm, 3130 HKDF, and Master Salt. 3132 C.2.1. Client 3134 Inputs: 3136 o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes) 3138 o Sender ID: 0x00 (1 byte) 3140 o Recipient ID: 0x01 (1 byte) 3142 From the previous parameters, 3144 o info (for Sender Key): 0x854100f60a634b657910 (10 bytes) 3145 o info (for Recipient Key): 0x854101f60a634b657910 (10 bytes) 3147 o info (for Common IV): 0x8540f60a6249560d (8 bytes) 3149 Outputs: 3151 o Sender Key: 0x321b26943253c7ffb6003b0b64d74041 (16 bytes) 3153 o Recipient Key: 0xe57b5635815177cd679ab4bcec9d7dda (16 bytes) 3155 o Common IV: 0xbe35ae297d2dace910c52e99f9 (13 bytes) 3157 From the previous parameters and a Partial IV equal to 0 (both for 3158 sender and recipient): 3160 o sender nonce: 0xbf35ae297d2dace910c52e99f9 (13 bytes) 3162 o recipient nonce: 0xbf35ae297d2dace810c52e99f9 (13 bytes) 3164 C.2.2. Server 3166 Inputs: 3168 o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes) 3170 o Sender ID: 0x01 (1 byte) 3172 o Recipient ID: 0x00 (1 byte) 3174 From the previous parameters, 3176 o info (for Sender Key): 0x854101f60a634b657910 (10 bytes) 3178 o info (for Recipient Key): 0x854100f60a634b657910 (10 bytes) 3180 o info (for Common IV): 0x8540f60a6249560d (8 bytes) 3182 Outputs: 3184 o Sender Key: 0xe57b5635815177cd679ab4bcec9d7dda (16 bytes) 3186 o Recipient Key: 0x321b26943253c7ffb6003b0b64d74041 (16 bytes) 3188 o Common IV: 0xbe35ae297d2dace910c52e99f9 (13 bytes) 3190 From the previous parameters and a Partial IV equal to 0 (both for 3191 sender and recipient): 3193 o sender nonce: 0xbf35ae297d2dace810c52e99f9 (13 bytes) 3195 o recipient nonce: 0xbf35ae297d2dace910c52e99f9 (13 bytes) 3197 C.3. Test Vector 3: Key Derivation with ID Context 3199 In this test vector, a Master Salt of 8 bytes and a ID Context of 8 3200 bytes are used. The default values are used for AEAD Algorithm and 3201 HKDF. 3203 C.3.1. Client 3205 Inputs: 3207 o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes) 3209 o Master Salt: 0x9e7ca92223786340 (8 bytes) 3211 o Sender ID: 0x (0 byte) 3213 o Recipient ID: 0x01 (1 byte) 3215 o ID Context: 0x37cbf3210017a2d3 (8 bytes) 3217 From the previous parameters, 3219 o info (for Sender Key): 0x85404837cbf3210017a2d30a634b657910 (17 3220 bytes) 3222 o info (for Recipient Key): 0x8541014837cbf3210017a2d30a634b657910 3223 (18 bytes) 3225 o info (for Common IV): 0x85404837cbf3210017a2d30a6249560d (16 3226 bytes) 3228 Outputs: 3230 o Sender Key: 0xaf2a1300a5e95788b356336eeecd2b92 (16 bytes) 3232 o Recipient Key: 0xe39a0c7c77b43f03b4b39ab9a268699f (16 bytes) 3234 o Common IV: 0x2ca58fb85ff1b81c0b7181b85e (13 bytes) 3236 From the previous parameters and a Partial IV equal to 0 (both for 3237 sender and recipient): 3239 o sender nonce: 0x2ca58fb85ff1b81c0b7181b85e (13 bytes) 3240 o recipient nonce: 0x2da58fb85ff1b81d0b7181b85e (13 bytes) 3242 C.3.2. Server 3244 Inputs: 3246 o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes) 3248 o Master Salt: 0x9e7ca92223786340 (8 bytes) 3250 o Sender ID: 0x01 (1 byte) 3252 o Recipient ID: 0x (0 byte) 3254 o ID Context: 0x37cbf3210017a2d3 (8 bytes) 3256 From the previous parameters, 3258 o info (for Sender Key): 0x8541014837cbf3210017a2d30a634b657910 (18 3259 bytes) 3261 o info (for Recipient Key): 0x85404837cbf3210017a2d30a634b657910 (17 3262 bytes) 3264 o info (for Common IV): 0x85404837cbf3210017a2d30a6249560d (16 3265 bytes) 3267 Outputs: 3269 o Sender Key: 0xe39a0c7c77b43f03b4b39ab9a268699f (16 bytes) 3271 o Recipient Key: 0xaf2a1300a5e95788b356336eeecd2b92 (16 bytes) 3273 o Common IV: 0x2ca58fb85ff1b81c0b7181b85e (13 bytes) 3275 From the previous parameters and a Partial IV equal to 0 (both for 3276 sender and recipient): 3278 o sender nonce: 0x2da58fb85ff1b81d0b7181b85e (13 bytes) 3280 o recipient nonce: 0x2ca58fb85ff1b81c0b7181b85e (13 bytes) 3282 C.4. Test Vector 4: OSCORE Request, Client 3284 This section contains a test vector for an OSCORE protected CoAP GET 3285 request using the security context derived in Appendix C.1. The 3286 unprotected request only contains the Uri-Path and Uri-Host options. 3288 Unprotected CoAP request: 3289 0x44015d1f00003974396c6f63616c686f737483747631 (22 bytes) 3291 Common Context: 3293 o AEAD Algorithm: 10 (AES-CCM-16-64-128) 3295 o Key Derivation Function: HKDF SHA-256 3297 o Common IV: 0x4622d4dd6d944168eefb54987c (13 bytes) 3299 Sender Context: 3301 o Sender ID: 0x (0 byte) 3303 o Sender Key: 0xf0910ed7295e6ad4b54fc793154302ff (16 bytes) 3305 o Sender Sequence Number: 20 3307 The following COSE and cryptographic parameters are derived: 3309 o Partial IV: 0x14 (1 byte) 3311 o kid: 0x (0 byte) 3313 o external_aad: 0x8501810a40411440 (8 bytes) 3315 o AAD: 0x8368456e63727970743040488501810a40411440 (20 bytes) 3317 o plaintext: 0x01b3747631 (5 bytes) 3319 o encryption key: 0xf0910ed7295e6ad4b54fc793154302ff (16 bytes) 3321 o nonce: 0x4622d4dd6d944168eefb549868 (13 bytes) 3323 From the previous parameter, the following is derived: 3325 o OSCORE option value: 0x0914 (2 bytes) 3327 o ciphertext: 0x612f1092f1776f1c1668b3825e (13 bytes) 3329 From there: 3331 o Protected CoAP request (OSCORE message): 0x44025d1f00003974396c6f6 3332 3616c686f7374620914ff612f1092f1776f1c1668b3825e (35 bytes) 3334 C.5. Test Vector 5: OSCORE Request, Client 3336 This section contains a test vector for an OSCORE protected CoAP GET 3337 request using the security context derived in Appendix C.2. The 3338 unprotected request only contains the Uri-Path and Uri-Host options. 3340 Unprotected CoAP request: 3341 0x440171c30000b932396c6f63616c686f737483747631 (22 bytes) 3343 Common Context: 3345 o AEAD Algorithm: 10 (AES-CCM-16-64-128) 3347 o Key Derivation Function: HKDF SHA-256 3349 o Common IV: 0xbe35ae297d2dace910c52e99f9 (13 bytes) 3351 Sender Context: 3353 o Sender ID: 0x00 (1 bytes) 3355 o Sender Key: 0x321b26943253c7ffb6003b0b64d74041 (16 bytes) 3357 o Sender Sequence Number: 20 3359 The following COSE and cryptographic parameters are derived: 3361 o Partial IV: 0x14 (1 byte) 3363 o kid: 0x00 (1 byte) 3365 o external_aad: 0x8501810a4100411440 (9 bytes) 3367 o AAD: 0x8368456e63727970743040498501810a4100411440 (21 bytes) 3369 o plaintext: 0x01b3747631 (5 bytes) 3371 o encryption key: 0x321b26943253c7ffb6003b0b64d74041 (16 bytes) 3373 o nonce: 0xbf35ae297d2dace910c52e99ed (13 bytes) 3375 From the previous parameter, the following is derived: 3377 o OSCORE option value: 0x091400 (3 bytes) 3379 o ciphertext: 0x4ed339a5a379b0b8bc731fffb0 (13 bytes) 3381 From there: 3383 o Protected CoAP request (OSCORE message): 0x440271c30000b932396c6f6 3384 3616c686f737463091400ff4ed339a5a379b0b8bc731fffb0 (36 bytes) 3386 C.6. Test Vector 6: OSCORE Request, Client 3388 This section contains a test vector for an OSCORE protected CoAP GET 3389 request for an application that sets the ID Context and requires it 3390 to be sent in the request, so kid context is present in the protected 3391 message. This test vector uses the security context derived in 3392 Appendix C.3. The unprotected request only contains the Uri-Path and 3393 Uri-Host options. 3395 Unprotected CoAP request: 3396 0x44012f8eef9bbf7a396c6f63616c686f737483747631 (22 bytes) 3398 Common Context: 3400 o AEAD Algorithm: 10 (AES-CCM-16-64-128) 3402 o Key Derivation Function: HKDF SHA-256 3404 o Common IV: 0x2ca58fb85ff1b81c0b7181b85e (13 bytes) 3406 o ID Context: 0x37cbf3210017a2d3 (8 bytes) 3408 Sender Context: 3410 o Sender ID: 0x (0 bytes) 3412 o Sender Key: 0xaf2a1300a5e95788b356336eeecd2b92 (16 bytes) 3414 o Sender Sequence Number: 20 3416 The following COSE and cryptographic parameters are derived: 3418 o Partial IV: 0x14 (1 byte) 3420 o kid: 0x (0 byte) 3422 o kid context: 0x37cbf3210017a2d3 (8 bytes) 3424 o external_aad: 0x8501810a40411440 (8 bytes) 3426 o AAD: 0x8368456e63727970743040488501810a40411440 (20 bytes) 3428 o plaintext: 0x01b3747631 (5 bytes) 3430 o encryption key: 0xaf2a1300a5e95788b356336eeecd2b92 (16 bytes) 3431 o nonce: 0x2ca58fb85ff1b81c0b7181b84a (13 bytes) 3433 From the previous parameter, the following is derived: 3435 o OSCORE option value: 0x19140837cbf3210017a2d3 (11 bytes) 3437 o ciphertext: 0x72cd7273fd331ac45cffbe55c3 (13 bytes) 3439 From there: 3441 o Protected CoAP request (OSCORE message): 3442 0x44022f8eef9bbf7a396c6f63616c686f73746b19140837cbf3210017a2d3ff 3443 72cd7273fd331ac45cffbe55c3 (44 bytes) 3445 C.7. Test Vector 7: OSCORE Response, Server 3447 This section contains a test vector for an OSCORE protected 2.05 3448 Content response to the request in Appendix C.4. The unprotected 3449 response has payload "Hello World!" and no options. The protected 3450 response does not contain a kid nor a Partial IV. Note that some 3451 parameters are derived from the request. 3453 Unprotected CoAP response: 3454 0x64455d1f00003974ff48656c6c6f20576f726c6421 (21 bytes) 3456 Common Context: 3458 o AEAD Algorithm: 10 (AES-CCM-16-64-128) 3460 o Key Derivation Function: HKDF SHA-256 3462 o Common IV: 0x4622d4dd6d944168eefb54987c (13 bytes) 3464 Sender Context: 3466 o Sender ID: 0x01 (1 byte) 3468 o Sender Key: 0xffb14e093c94c9cac9471648b4f98710 (16 bytes) 3470 o Sender Sequence Number: 0 3472 The following COSE and cryptographic parameters are derived: 3474 o external_aad: 0x8501810a40411440 (8 bytes) 3476 o AAD: 0x8368456e63727970743040488501810a40411440 (20 bytes) 3478 o plaintext: 0x45ff48656c6c6f20576f726c6421 (14 bytes) 3479 o encryption key: 0xffb14e093c94c9cac9471648b4f98710 (16 bytes) 3481 o nonce: 0x4622d4dd6d944168eefb549868 (13 bytes) 3483 From the previous parameter, the following is derived: 3485 o OSCORE option value: 0x (0 bytes) 3487 o ciphertext: 0xdbaad1e9a7e7b2a813d3c31524378303cdafae119106 (22 3488 bytes) 3490 From there: 3492 o Protected CoAP response (OSCORE message): 3493 0x64445d1f0000397490ffdbaad1e9a7e7b2a813d3c31524378303cdafae119106 3494 (32 bytes) 3496 C.8. Test Vector 8: OSCORE Response with Partial IV, Server 3498 This section contains a test vector for an OSCORE protected 2.05 3499 Content response to the request in Appendix C.4. The unprotected 3500 response has payload "Hello World!" and no options. The protected 3501 response does not contain a kid, but contains a Partial IV. Note 3502 that some parameters are derived from the request. 3504 Unprotected CoAP response: 3505 0x64455d1f00003974ff48656c6c6f20576f726c6421 (21 bytes) 3507 Common Context: 3509 o AEAD Algorithm: 10 (AES-CCM-16-64-128) 3511 o Key Derivation Function: HKDF SHA-256 3513 o Common IV: 0x4622d4dd6d944168eefb54987c (13 bytes) 3515 Sender Context: 3517 o Sender ID: 0x01 (1 byte) 3519 o Sender Key: 0xffb14e093c94c9cac9471648b4f98710 (16 bytes) 3521 o Sender Sequence Number: 0 3523 The following COSE and cryptographic parameters are derived: 3525 o Partial IV: 0x00 (1 byte) 3526 o external_aad: 0x8501810a40411440 (8 bytes) 3528 o AAD: 0x8368456e63727970743040488501810a40411440 (20 bytes) 3530 o plaintext: 0x45ff48656c6c6f20576f726c6421 (14 bytes) 3532 o encryption key: 0xffb14e093c94c9cac9471648b4f98710 (16 bytes) 3534 o nonce: 0x4722d4dd6d944169eefb54987c (13 bytes) 3536 From the previous parameter, the following is derived: 3538 o OSCORE option value: 0x0100 (2 bytes) 3540 o ciphertext: 0x4d4c13669384b67354b2b6175ff4b8658c666a6cf88e (22 3541 bytes) 3543 From there: 3545 o Protected CoAP response (OSCORE message): 0x64445d1f00003974920100 3546 ff4d4c13669384b67354b2b6175ff4b8658c666a6cf88e (34 bytes) 3548 Appendix D. Overview of Security Properties 3550 D.1. Supporting Proxy Operations 3552 CoAP is designed to work with intermediaries reading and/or changing 3553 CoAP message fields to perform supporting operations in constrained 3554 environments, e.g. forwarding and cross-protocol translations. 3556 Securing CoAP on transport layer protects the entire message between 3557 the endpoints in which case CoAP proxy operations are not possible. 3558 In order to enable proxy operations, security on transport layer 3559 needs to be terminated at the proxy in which case the CoAP message in 3560 its entirety is unprotected in the proxy. 3562 Requirements for CoAP end-to-end security are specified in 3563 [I-D.hartke-core-e2e-security-reqs], in particular forwarding is 3564 detailed in Section 2.2.1. The client and server are assumed to be 3565 honest, while proxies and gateways are only trusted to perform their 3566 intended operations. 3568 By working at the CoAP layer, OSCORE enables different CoAP message 3569 fields to be protected differently, which allows message fields 3570 required for proxy operations to be available to the proxy while 3571 message fields intended for the other endpoint remain protected. In 3572 the remainder of this section we analyze how OSCORE protects the 3573 protected message fields and the consequences of message fields 3574 intended for proxy operation being unprotected. 3576 D.2. Protected Message Fields 3578 Protected message fields are included in the Plaintext (Section 5.3) 3579 and the Additional Authenticated Data (Section 5.4) of the 3580 COSE_Encrypt0 object and encrypted using an AEAD algorithm. 3582 OSCORE depends on a pre-established random Master Secret 3583 (Section 12.3) used to derive encryption keys, and a construction for 3584 making (key, nonce) pairs unique (Appendix D.3). Assuming this is 3585 true, and the keys are used for no more data than indicated in 3586 Section 7.2.1, OSCORE should provide the following guarantees: 3588 o Confidentiality: An attacker should not be able to determine the 3589 plaintext contents of a given OSCORE message or determine that 3590 different plaintexts are related (Section 5.3). 3592 o Integrity: An attacker should not be able to craft a new OSCORE 3593 message with protected message fields different from an existing 3594 OSCORE message which will be accepted by the receiver. 3596 o Request-response binding: An attacker should not be able to make a 3597 client match a response to the wrong request. 3599 o Non-replayability: An attacker should not be able to cause the 3600 receiver to accept a message which it has previously received and 3601 accepted. 3603 In the above, the attacker is anyone except the endpoints, e.g. a 3604 compromised intermediary. Informally, OSCORE provides these 3605 properties by AEAD-protecting the plaintext with a strong key and 3606 uniqueness of (key, nonce) pairs. AEAD encryption [RFC5116] provides 3607 confidentiality and integrity for the data. Response-request binding 3608 is provided by including the kid and Partial IV of the request in the 3609 AAD of the response. Non-replayability of requests and notifications 3610 is provided by using unique (key, nonce) pairs and a replay 3611 protection mechanism (application dependent, see Section 7.4). 3613 OSCORE is susceptible to a variety of traffic analysis attacks based 3614 on observing the length and timing of encrypted packets. OSCORE does 3615 not provide any specific defenses against this form of attack but the 3616 application may use a padding mechanism to prevent an attacker from 3617 directly determine the length of the padding. However, information 3618 about padding may still be revealed by side-channel attacks observing 3619 differences in timing. 3621 D.3. Uniqueness of (key, nonce) 3623 In this section we show that (key, nonce) pairs are unique as long as 3624 the requirements in Sections 3.3 and 7.2.1 are followed. 3626 Fix a Common Context (Section 3.1) and an endpoint, called the 3627 encrypting endpoint. An endpoint may alternate between client and 3628 server roles, but each endpoint always encrypts with the Sender Key 3629 of its Sender Context. Sender Keys are (stochastically) unique since 3630 they are derived with HKDF using unique Sender IDs, so messages 3631 encrypted by different endpoints use different keys. It remains to 3632 prove that the nonces used by the fixed endpoint are unique. 3634 Since the Common IV is fixed, the nonces are determined by a Partial 3635 IV (PIV) and the Sender ID of the endpoint generating that Partial IV 3636 (ID_PIV). The nonce construction (Section 5.2) with the size of the 3637 ID_PIV (S) creates unique nonces for different (ID_PIV, PIV) pairs. 3638 There are two cases: 3640 A. For requests, and responses with Partial IV (e.g. Observe 3641 notifications): 3643 o ID_PIV = Sender ID of the encrypting endpoint 3645 o PIV = current Partial IV of the encrypting endpoint 3647 Since the encrypting endpoint steps the Partial IV for each use, the 3648 nonces used in case A are all unique as long as the number of 3649 encrypted messages is kept within the required range (Section 7.2.1). 3651 B. For responses without Partial IV (e.g. single response to a 3652 request): 3654 o ID_PIV = Sender ID of the endpoint generating the request 3656 o PIV = Partial IV of the request 3658 Since the Sender IDs are unique, ID_PIV is different from the Sender 3659 ID of the encrypting endpoint. Therefore, the nonces in case B are 3660 different compared to nonces in case A, where the encrypting endpoint 3661 generated the Partial IV. Since the Partial IV of the request is 3662 verified for replay (Section 7.4) associated to this Recipient 3663 Context, PIV is unique for this ID_PIV, which makes all nonces in 3664 case B distinct. 3666 D.4. Unprotected Message Fields 3668 This section lists and discusses issues with unprotected message 3669 fields. 3671 D.4.1. CoAP Header Fields 3673 o Version. The CoAP version [RFC7252] is not expected to be 3674 sensitive to disclose. Currently there is only one CoAP version 3675 defined. A change of this parameter is potentially a denial-of- 3676 service attack. Future versions of CoAP need to analyze attacks 3677 to OSCORE protected messages due to an adversary changing the CoAP 3678 version. 3680 o Token/Token Length. The Token field is a client-local identifier 3681 for differentiating between concurrent requests [RFC7252]. CoAP 3682 proxies are allowed to read and change Token and Token Length 3683 between hops. An eavesdropper reading the Token can match 3684 requests to responses which can be used in traffic analysis. In 3685 particular this is true for notifications, where multiple 3686 responses are matched with one request. Modifications of Token 3687 and Token Length by an on-path attacker may become a denial-of- 3688 service attack, since it may prevent the client to identify to 3689 which request the response belongs or to find the correct 3690 information to verify integrity of the response. 3692 o Code. The Outer CoAP Code of an OSCORE message is POST or FETCH 3693 for requests with corresponding response codes. The use of FETCH 3694 reveals no more than what is revealed by the Outer Observe option. 3695 Changing the Outer Code may be a denial-of-service attack by 3696 causing errors in the proxy processing. 3698 o Type/Message ID. The Type/Message ID fields [RFC7252] reveal 3699 information about the UDP transport binding, e.g. an eavesdropper 3700 reading the Type or Message ID gain information about how UDP 3701 messages are related to each other. CoAP proxies are allowed to 3702 change Type and Message ID. These message fields are not present 3703 in CoAP over TCP [RFC8323], and does not impact the request/ 3704 response message. A change of these fields in a UDP hop is a 3705 denial-of-service attack. By sending an ACK, an attacker can make 3706 the endpoint believe that the other endpoint received the previous 3707 message. By sending a RST, an attacker may be able to cancel an 3708 observation, make one endpoint believe the other endpoint is 3709 alive, or make one endpoint endpoint believe that the other 3710 endpoint is missing some context. By changing a NON to a CON, the 3711 attacker can cause the receiving endpoint to respond to messages 3712 for which no response was requested. 3714 o Length. This field contain the length of the message [RFC8323] 3715 which may be used for traffic analysis. These message fields are 3716 not present in CoAP over UDP, and does not impact the request/ 3717 response message. A change of Length is a denial-of-service 3718 attack similar to changing TCP header fields. 3720 D.4.2. CoAP Options 3722 o Max-Age. The Outer Max-Age is set to zero to avoid unnecessary 3723 caching of OSCORE error responses. Changing this value thus may 3724 cause unnecessary caching. No additional information is carried 3725 with this option. 3727 o Proxy-Uri/Proxy-Scheme. These options are used in forward proxy 3728 deployments. With OSCORE, the Proxy-Uri option does not contain 3729 the Uri-Path/Uri-Query parts of the URI. The other parts of 3730 Proxy-Uri cannot be protected since they are allowed to be changed 3731 by a forward proxy. The server can verify what scheme is used in 3732 the last hop, but not what was requested by the client or what was 3733 used in previous hops. 3735 o Uri-Host/Uri-Port. In forward proxy deployments, the Uri-Host/ 3736 Uri-Port may be changed by an adversary, and the application needs 3737 to handle the consequences of that (see Section 4.1.3.2). The 3738 Uri-Host may either be omitted, reveal information equivalent to 3739 that of the IP address or more privacy-sensitive information, 3740 which is discouraged. 3742 o Observe. The Outer Observe option is intended for a proxy to 3743 support forwarding of Observe messages, but is ignored by the 3744 endpoints since the Inner Observe determines the processing in the 3745 endpoints. Since the Partial IV provides absolute ordering of 3746 notifications it is not possible for an intermediary to spoof 3747 reordering (see Section 4.1.3.5). The absence of Partial IV, 3748 since only allowed for the first notification, does not prevent 3749 correct ordering of notifications. The size and distributions of 3750 notifications over time may reveal information about the content 3751 or nature of the notifications. Cancellations (Section 4.1.3.5.1) 3752 are not bound to the corresponding registrations in the same way 3753 responses are bound to requests in OSCORE (see Appendix D.2), but 3754 that does not open up for attacks based on mismatched 3755 cancellations, since for cancellations to be accepted, all options 3756 in the decrypted message except for ETag Options MUST be the same 3757 (see Section 4.1.3.5). 3759 o Block1/Block2/Size1/Size2. The Outer Block options enables 3760 fragmentation of OSCORE messages in addition to segmentation 3761 performed by the Inner Block options. The presence of these 3762 options indicates a large message being sent and the message size 3763 can be estimated and used for traffic analysis. Manipulating 3764 these options is a potential denial-of-service attack, e.g. 3765 injection of alleged Block fragments. The specification of a 3766 maximum size of message, MAX_UNFRAGMENTED_SIZE 3767 (Section 4.1.3.4.2), above which messages will be dropped, is 3768 intended as one measure to mitigate this kind of attack. 3770 o No-Response. The Outer No-Response option is used to support 3771 proxy functionality, specifically to avoid error transmissions 3772 from proxies to clients, and to avoid bandwidth reduction to 3773 servers by proxies applying congestion control when not receiving 3774 responses. Modifying or introducing this option is a potential 3775 denial-of-service attack against the proxy operations, but since 3776 the option has an Inner value its use can be securely agreed 3777 between the endpoints. The presence of this option is not 3778 expected to reveal any sensitive information about the message 3779 exchange. 3781 o OSCORE. The OSCORE option contains information about the 3782 compressed COSE header. Changing this field may cause OSCORE 3783 verification to fail. 3785 D.4.3. Error and Signaling Messages 3787 Error messages occurring during CoAP processing are protected end-to- 3788 end. Error messages occurring during OSCORE processing are not 3789 always possible to protect, e.g. if the receiving endpoint cannot 3790 locate the right security context. For this setting, unprotected 3791 error messages are allowed as specified to prevent extensive 3792 retransmissions. Those error messages can be spoofed or manipulated, 3793 which is a potential denial-of-service attack. 3795 Signaling messages used in CoAP over TCP [RFC8323] are intended to be 3796 hop-by-hop; spoofing signaling messages can be used as a denial-of- 3797 service attack of a TCP connection. 3799 D.4.4. HTTP Message Fields 3801 In contrast to CoAP, where OSCORE does not protect header fields to 3802 enable CoAP-CoAP proxy operations, the use of OSCORE with HTTP is 3803 restricted to transporting a protected CoAP message over an HTTP hop. 3804 Any unprotected HTTP message fields may reveal information about the 3805 transport of the OSCORE message and enable various denial-of-service 3806 attacks. It is recommended to additionally use TLS [RFC8446] for 3807 HTTP hops, which enables encryption and integrity protection of 3808 headers, but still leaves some information for traffic analysis. 3810 Appendix E. CDDL Summary 3812 Data structure definitions in the present specification employ the 3813 CDDL language for conciseness and precision. CDDL is defined in 3814 [I-D.ietf-cbor-cddl], which at the time of writing this appendix is 3815 in the process of completion. As the document is not yet available 3816 for a normative reference, the present appendix defines the small 3817 subset of CDDL that is being used in the present specification. 3819 Within the subset being used here, a CDDL rule is of the form "name = 3820 type", where "name" is the name given to the "type". A "type" can be 3821 one of: 3823 o a reference to another named type, by giving its name. The 3824 predefined named types used in the present specification are: 3825 "uint", an unsigned integer (as represented in CBOR by major type 3826 0); "int", an unsigned or negative integer (as represented in CBOR 3827 by major type 0 or 1); "bstr", a byte string (as represented in 3828 CBOR by major type 2); "tstr", a text string (as represented in 3829 CBOR by major type 3); 3831 o a choice between two types, by giving both types separated by a 3832 "/"; 3834 o an array type (as represented in CBOR by major type 4), where the 3835 sequence of elements of the array is described by giving a 3836 sequence of entries separated by commas ",", and this sequence is 3837 enclosed by square brackets "[" and "]". Arrays described by an 3838 array description contain elements that correspond one-to-one to 3839 the sequence of entries given. Each entry of an array description 3840 is of the form "name : type", where "name" is the name given to 3841 the entry and "type" is the type of the array element 3842 corresponding to this entry. 3844 Acknowledgments 3846 The following individuals provided input to this document: Christian 3847 Amsuess, Tobias Andersson, Carsten Bormann, Joakim Brorsson, Esko 3848 Dijk, Thomas Fossati, Martin Gunnarsson, Klaus Hartke, Michael 3849 Richardson, Jim Schaad, Peter van der Stok, Dave Thaler, Marco 3850 Tiloca, William Vignat, and Malisa Vucinic. 3852 Ludwig Seitz and Goeran Selander worked on this document as part of 3853 the CelticPlus project CyberWI, with funding from Vinnova. 3855 Authors' Addresses 3857 Goeran Selander 3858 Ericsson AB 3860 Email: goran.selander@ericsson.com 3862 John Mattsson 3863 Ericsson AB 3865 Email: john.mattsson@ericsson.com 3867 Francesca Palombini 3868 Ericsson AB 3870 Email: francesca.palombini@ericsson.com 3872 Ludwig Seitz 3873 RISE SICS 3875 Email: ludwig.seitz@ri.se