idnits 2.17.1 draft-ietf-core-object-security-07.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (November 20, 2017) is 2347 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 8152 (Obsoleted by RFC 9052, RFC 9053) == Outdated reference: A later version (-15) exists of draft-ietf-6tisch-minimal-security-04 == Outdated reference: A later version (-46) exists of draft-ietf-ace-oauth-authz-09 == Outdated reference: A later version (-08) exists of draft-ietf-cbor-cddl-00 == Outdated reference: A later version (-11) exists of draft-ietf-core-coap-tcp-tls-10 == Outdated reference: A later version (-14) exists of draft-ietf-core-echo-request-tag-00 == Outdated reference: A later version (-06) exists of draft-mattsson-core-coap-actuators-03 Summary: 3 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: May 24, 2018 Ericsson AB 6 L. Seitz 7 SICS Swedish ICT 8 November 20, 2017 10 Object Security for Constrained RESTful Environments (OSCORE) 11 draft-ietf-core-object-security-07 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 19 encryption, integrity and replay protection, as well as a secure 20 message binding. OSCORE is designed for constrained nodes and 21 networks and can be used whereever CoAP can be used, and also with 22 HTTP. OSCORE may be used to protect group communications as is 23 specified in a separate draft. 25 Status of This Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at https://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on May 24, 2018. 42 Copyright Notice 44 Copyright (c) 2017 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (https://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 60 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 61 2. The CoAP Object-Security Option . . . . . . . . . . . . . . . 5 62 3. The Security Context . . . . . . . . . . . . . . . . . . . . 6 63 3.1. Security Context Definition . . . . . . . . . . . . . . . 6 64 3.2. Establishment of Security Context Parameters . . . . . . 9 65 3.3. Requirements on the Security Context Parameters . . . . . 11 66 4. Protected Message Fields . . . . . . . . . . . . . . . . . . 11 67 4.1. CoAP Payload . . . . . . . . . . . . . . . . . . . . . . 12 68 4.2. CoAP Options . . . . . . . . . . . . . . . . . . . . . . 13 69 4.3. CoAP Header . . . . . . . . . . . . . . . . . . . . . . . 18 70 5. The COSE Object . . . . . . . . . . . . . . . . . . . . . . . 19 71 5.1. Kid Context . . . . . . . . . . . . . . . . . . . . . . . 20 72 5.2. Nonce . . . . . . . . . . . . . . . . . . . . . . . . . . 21 73 5.3. Plaintext . . . . . . . . . . . . . . . . . . . . . . . . 22 74 5.4. Additional Authenticated Data . . . . . . . . . . . . . . 23 75 6. Sequence Numbers, Replay, Message Binding, and Freshness . . 23 76 6.1. Message Binding . . . . . . . . . . . . . . . . . . . . . 23 77 6.2. AEAD Nonce Uniqueness . . . . . . . . . . . . . . . . . . 24 78 6.3. Freshness . . . . . . . . . . . . . . . . . . . . . . . . 24 79 6.4. Replay Protection . . . . . . . . . . . . . . . . . . . . 24 80 6.5. Losing Part of the Context State . . . . . . . . . . . . 25 81 7. Processing . . . . . . . . . . . . . . . . . . . . . . . . . 26 82 7.1. Protecting the Request . . . . . . . . . . . . . . . . . 26 83 7.2. Verifying the Request . . . . . . . . . . . . . . . . . . 27 84 7.3. Protecting the Response . . . . . . . . . . . . . . . . . 28 85 7.4. Verifying the Response . . . . . . . . . . . . . . . . . 29 86 8. OSCORE Compression . . . . . . . . . . . . . . . . . . . . . 30 87 8.1. Encoding of the Object-Security Value . . . . . . . . . . 30 88 8.2. Encoding of the OSCORE Payload . . . . . . . . . . . . . 32 89 8.3. Examples of Compressed COSE Objects . . . . . . . . . . . 32 90 9. Web Linking . . . . . . . . . . . . . . . . . . . . . . . . . 33 91 10. Proxy Operations . . . . . . . . . . . . . . . . . . . . . . 34 92 10.1. CoAP-to-CoAP Forwarding Proxy . . . . . . . . . . . . . 34 93 10.2. HTTP-to-CoAP Translation Proxy . . . . . . . . . . . . . 34 94 10.3. CoAP-to-HTTP Translation Proxy . . . . . . . . . . . . . 36 95 11. Security Considerations . . . . . . . . . . . . . . . . . . . 37 96 12. Privacy Considerations . . . . . . . . . . . . . . . . . . . 38 97 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 39 98 13.1. COSE Header Parameters Registry . . . . . . . . . . . . 39 99 13.2. CoAP Option Numbers Registry . . . . . . . . . . . . . . 39 100 13.3. Header Field Registrations . . . . . . . . . . . . . . . 40 101 14. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 40 102 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 40 103 15.1. Normative References . . . . . . . . . . . . . . . . . . 40 104 15.2. Informative References . . . . . . . . . . . . . . . . . 41 105 Appendix A. Test Vectors . . . . . . . . . . . . . . . . . . . . 43 106 Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 43 107 B.1. Secure Access to Sensor . . . . . . . . . . . . . . . . . 43 108 B.2. Secure Subscribe to Sensor . . . . . . . . . . . . . . . 44 109 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 46 111 1. Introduction 113 The Constrained Application Protocol (CoAP) is a web application 114 protocol, designed for constrained nodes and networks [RFC7228]. 115 CoAP specifies the use of proxies for scalability and efficiency, and 116 a mapping to HTTP is also specified [RFC8075]. CoAP [RFC7252] 117 references DTLS [RFC6347] for security. CoAP and HTTP proxies 118 require (D)TLS to be terminated at the proxy. The proxy therefore 119 not only has access to the data required for performing the intended 120 proxy functionality, but is also able to eavesdrop on, or manipulate 121 any part of the message payload and metadata, in transit between the 122 endpoints. The proxy can also inject, delete, or reorder packets 123 since they are no longer protected by (D)TLS. 125 This document defines the Object Security for Constrained RESTful 126 Environments (OSCORE) security protocol, protecting CoAP and CoAP- 127 mappable HTTP requests and responses end-to-end across intermediary 128 nodes such as CoAP forward proxies and cross-protocol translators 129 including HTTP-to-CoAP proxies [RFC8075]. In addition to the core 130 CoAP features defined in [RFC7252], OSCORE supports Observe 131 [RFC7641], Blockwise [RFC7959], PATCH and FETCH [RFC8132]. An 132 analysis of end-to-end security for CoAP messages through some types 133 of intermediary nodes is performed in 134 [I-D.hartke-core-e2e-security-reqs]. OSCORE protects the Request/ 135 Response layer only, and not the CoAP Messaging Layer (Section 2 of 136 [RFC7252]). Therefore, any Messaging Layer processing follows 137 [RFC7252]. Additionally, since the message formats for CoAP over 138 unreliable transport [RFC7252] and for CoAP over reliable transport 139 [I-D.ietf-core-coap-tcp-tls] differ only in terms of Messaging Layer, 140 OSCORE can be applied to both unreliable and reliable transports. 142 OSCORE is designed for constrained nodes and networks and provides an 143 in-layer security protocol that does not depend on underlying layers. 144 OSCORE can be used anywhere where CoAP or HTTP can be used, including 145 non-IP transports (e.g., [I-D.bormann-6lo-coap-802-15-ie]). An 146 extension of OSCORE may also be used to protect group communication 147 for CoAP [I-D.tiloca-core-multicast-oscoap]. The use of OSCORE does 148 not affect the URI scheme and OSCORE can therefore be used with any 149 URI scheme defined for CoAP or HTTP. The application decides the 150 conditions for which OSCORE is required. 152 OSCORE builds on CBOR Object Signing and Encryption (COSE) [RFC8152], 153 providing end-to-end encryption, integrity, replay protection, and 154 secure the binding of response to request. A compressed version of 155 COSE is used, as discussed in Section 8. The use of OSCORE is 156 signaled with the Object-Security CoAP option or HTTP header, defined 157 in Section 2 and Section 10.2. OSCORE is designed to protect as much 158 information as possible, while still allowing proxy operations 159 (Section 10). OSCORE provides protection of message payload, almost 160 all CoAP options, and the RESTful method. The solution transforms a 161 message into an "OSCORE message" before sending, and vice versa after 162 receiving. The OSCORE message is related to the original message in 163 the following way: the original message is translated to CoAP (if not 164 already in CoAP) and the resulting message payload (if present), 165 options not processed by a proxy, and the request/response method 166 (CoAP Code) are protected in a COSE object. The message fields of 167 the original message that are encrypted are transported in the 168 payload of the OSCORE message, and the Object-Security option is 169 included, see Figure 1. 171 Client Server 172 | OSCORE request - POST example.com: | 173 | Header, Token, | 174 | Options: {Object-Security, ...}, | 175 | Payload: COSE ciphertext | 176 +--------------------------------------------->| 177 | | 178 |<---------------------------------------------+ 179 | OSCORE response - 2.04 (Changed): | 180 | Header, Token, | 181 | Options: {Object-Security, ...}, | 182 | Payload: COSE ciphertext | 183 | | 185 Figure 1: Sketch of CoAP with OSCORE 187 OSCORE may be used in very constrained settings, thanks to its small 188 message size and the restricted code and memory requirements in 189 addition to what is required by CoAP. OSCORE can be combined with 190 transport layer security such as DTLS or TLS, thereby enabling end- 191 to-end security of e.g. CoAP Payload, Options and Code, in 192 combination with hop-by-hop protection of the Messaging Layer, during 193 transport between end-point and intermediary node. Examples of the 194 use of OSCORE are given in Appendix B. 196 An implementation supporting this specification MAY only implement 197 the client part, MAY only implement the server part, or MAY only 198 implement one of the proxy parts. OSCORE is designed to work with 199 legacy CoAP-to-CoAP forward proxies [RFC7252], but an OSCORE-aware 200 proxy will be more efficient. HTTP-to-CoAP proxies [RFC8075] and 201 CoAP-to-HTTP proxies need to implement respective parts of this 202 specification to work with OSCORE (see Section 10). 204 1.1. Terminology 206 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 207 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 208 document are to be interpreted as described in [RFC2119]. These 209 words may also appear in this document in lowercase, absent their 210 normative meanings. 212 Readers are expected to be familiar with the terms and concepts 213 described in CoAP [RFC7252], Observe [RFC7641], Blockwise [RFC7959], 214 COSE [RFC8152], CBOR [RFC7049], CDDL [I-D.ietf-cbor-cddl], and 215 constrained environments [RFC7228]. 217 The terms Common/Sender/Recipient Context, Master Secret/Salt, Sender 218 ID/Key, Recipient ID/Key, and Common IV are defined in Section 3.1. 220 2. The CoAP Object-Security Option 222 The CoAP Object-Security option (see Figure 2) indicates that the 223 CoAP message is an OSCORE message and that it contains a compressed 224 COSE object (see Section 5 and Section 8). The Object-Security 225 option is critical, safe to forward, part of the cache key, and not 226 repeatable. 228 +-----+---+---+---+---+-----------------+--------+--------+---------+ 229 | No. | C | U | N | R | Name | Format | Length | Default | 230 +-----+---+---+---+---+-----------------+--------+--------+---------+ 231 | TBD | x | | | | Object-Security | (*) | 0-255 | (none) | 232 +-----+---+---+---+---+-----------------+--------+--------+---------+ 233 C = Critical, U = Unsafe, N = NoCacheKey, R = Repeatable 234 (*) See below. 236 Figure 2: The Object-Security Option 238 The Object-Security option includes the OSCORE flag byte (Section 8), 239 the Sender Sequence Number and the Sender ID when present 240 (Section 3). The detailed format is specified in Section 8). If the 241 OSCORE flag byte is all zero (0x00) the Option value SHALL be empty 242 (Option Length = 0). An endpoint receiving a CoAP message without 243 payload, that also contains an Object-Security option SHALL treat it 244 as malformed and reject it. 246 A successful response to a request with the Object-Security option 247 SHALL contain the Object-Security option. Whether error responses 248 contain the Object-Security option depends on the error type (see 249 Section 7). 251 Since the payload and most options are encrypted Section 4, and the 252 corresponding plain text message fields of the original are not 253 included in the OSCORE message, the processing of these fields does 254 not expand the total message size. 256 A CoAP proxy SHOULD NOT cache a response to a request with an Object- 257 Security option, since the response is only applicable to the 258 original client's request, see Section 10.1. As the compressed COSE 259 Object is included in the cache key, messages with the Object- 260 Security option will never generate cache hits. For Max-Age 261 processing, see Section 4.2.3.1. 263 3. The Security Context 265 OSCORE requires that client and server establish a shared security 266 context used to process the COSE objects. OSCORE uses COSE with an 267 Authenticated Encryption with Additional Data (AEAD) algorithm for 268 protecting message data between a client and a server. In this 269 section, we define the security context and how it is derived in 270 client and server based on a common shared master secret and a key 271 derivation function (KDF). 273 3.1. Security Context Definition 275 The security context is the set of information elements necessary to 276 carry out the cryptographic operations in OSCORE. For each endpoint, 277 the security context is composed of a "Common Context", a "Sender 278 Context", and a "Recipient Context". 280 The endpoints protect messages to send using the Sender Context and 281 verify messages received using the Recipient Context, both contexts 282 being derived from the Common Context and other data. Clients and 283 Servers need to be able to retrieve the correct security context to 284 use. 286 An endpoint uses its Sender ID (SID) to derive its Sender Context, 287 and the other endpoint uses the same ID, now called Recipient ID 288 (RID), to derive its Recipient Context. In communication between two 289 endpoints, the Sender Context of one endpoint matches the Recipient 290 Context of the other endpoint, and vice versa. Thus, the two 291 security contexts identified by the same IDs in the two endpoints are 292 not the same, but they are partly mirrored. Retrieval and use of the 293 security context are shown in Figure 3. 295 .-------------. .-------------. 296 | Common, | | Common, | 297 | Sender, | | Recipient, | 298 | Recipient | | Sender | 299 '-------------' '-------------' 300 Client Server 301 | | 302 Retrieve context for | OSCORE request: | 303 target resource | Token = Token1, | 304 Protect request with | kid = SID, ... | 305 Sender Context +---------------------->| Retrieve context with 306 | | RID = kid 307 | | Verify request with 308 | | Recipient Context 309 | OSCORE response: | Protect response with 310 | Token = Token1, ... | Sender Context 311 Retrieve context with |<----------------------+ 312 Token = Token1 | | 313 Verify request with | | 314 Recipient Context | | 316 Figure 3: Retrieval and use of the Security Context 318 The Common Context contains the following parameters: 320 o AEAD Algorithm (alg). The COSE AEAD algorithm to use for 321 encryption. Its value is immutable once the security context is 322 established. 324 o Key Derivation Function. The HMAC based HKDF [RFC5869] used to 325 derive Sender Key, Recipient Key, and Common IV. 327 o Master Secret. Variable length, uniformly random byte string 328 containing the key used to derive traffic keys and IVs. Its value 329 is immutable once the security context is established. 331 o Master Salt (OPTIONAL). Variable length byte string containing 332 the salt used to derive traffic keys and IVs. Its value is 333 immutable once the security context is established. 335 o Common IV. Byte string derived from Master Secret and Master 336 Salt. Length is determined by the AEAD Algorithm. Its value is 337 immutable once the security context is established. 339 The Sender Context contains the following parameters: 341 o Sender ID. Byte string used to identify the Sender Context and to 342 assure unique nonces. Maximum length is determined by the AEAD 343 Algorithm. Its value is immutable once the security context is 344 established. 346 o Sender Key. Byte string containing the symmetric key to protect 347 messages to send. Derived from Common Context and Sender ID. 348 Length is determined by the AEAD Algorithm. Its value is 349 immutable once the security context is established. 351 o Sender Sequence Number. Non-negative integer used by the sender 352 to protect requests and Observe notifications. Used as "Partial 353 IV" [RFC8152] to generate unique nonces for the AEAD. Maximum 354 value is determined by the AEAD Algorithm. 356 The Recipient Context contains the following parameters: 358 o Recipient ID. Byte string used to identify the Recipient Context 359 and to assure unique nonces. Maximum length is determined by the 360 AEAD Algorithm. Its value is immutable once the security context 361 is established. 363 o Recipient Key. Byte string containing the symmetric key to verify 364 messages received. Derived from Common Context and Recipient ID. 365 Length is determined by the AEAD Algorithm. Its value is 366 immutable once the security context is established. 368 o Replay Window (Server only). The replay window to verify requests 369 received. 371 An endpoint may free up memory by not storing the Common IV, Sender 372 Key, and Recipient Key, deriving them from the Master Key and Master 373 Salt when needed. Alternatively, an endpoint may free up memory by 374 not storing the Master Secret and Master Salt after the other 375 parameters have been derived. 377 Endpoints MAY operate in either or both roles as client and server 378 and use the same security context for those roles. Independent of 379 being client or server, the endpoint protects messages to send using 380 its Sender Context, and verifies messages received using its 381 Recipient Context. The endpoints MUST NOT change the Sender/ 382 Recipient ID when changing roles. In other words, changing the roles 383 does not change the set of keys to be used. 385 3.2. Establishment of Security Context Parameters 387 The parameters in the security context are derived from a small set 388 of input parameters. The following input parameters SHALL be pre- 389 established: 391 o Master Secret 393 o Sender ID 395 o Recipient ID 397 The following input parameters MAY be pre-established. In case any 398 of these parameters is not pre-established, the default value 399 indicated below is used: 401 o AEAD Algorithm (alg) 403 * Default is AES-CCM-16-64-128 (COSE algorithm encoding: 10) 405 o Master Salt 407 * Default is the empty string 409 o Key Derivation Function (KDF) 411 * Default is HKDF SHA-256 413 o Replay Window Type and Size 415 * Default is DTLS-type replay protection with a window size of 32 416 ([RFC6347]) 418 All input parameters need to be known to and agreed on by both 419 endpoints, but the replay window may be different in the two 420 endpoints. The replay window type and size is used by the client in 421 the processing of the Request-Tag [I-D.ietf-core-echo-request-tag]. 422 How the input parameters are pre-established, is application 423 specific. The ACE framework may be used to establish the necessary 424 input parameters [I-D.ietf-ace-oauth-authz]. 426 3.2.1. Derivation of Sender Key, Recipient Key, and Common IV 428 The KDF MUST be one of the HMAC based HKDF [RFC5869] algorithms 429 defined in COSE. HKDF SHA-256 is mandatory to implement. The 430 security context parameters Sender Key, Recipient Key, and Common IV 431 SHALL be derived from the input parameters using the HKDF, which 432 consists of the composition of the HKDF-Extract and HKDF-Expand steps 433 ([RFC5869]): 435 output parameter = HKDF(salt, IKM, info, L) 437 where: 439 o salt is the Master Salt as defined above 441 o IKM is the Master Secret as defined above 443 o info is a CBOR array consisting of: 445 info = [ 446 id : bstr / nil, 447 alg : int / tstr, 448 type : tstr, 449 L : uint 450 ] 452 where: 454 o id is the Sender ID or Recipient ID when deriving keys and nil 455 when deriving the Common IV. The encoding is described in 456 Section 5 458 o type is "Key" or "IV" 460 o L is the size of the key/IV for the AEAD algorithm used, in octets 462 For example, if the algorithm AES-CCM-16-64-128 (see Section 10.2 in 463 [RFC8152]) is used, the value for L is 16 for keys and 13 for the 464 Common IV. 466 3.2.2. Initial Sequence Numbers and Replay Window 468 The Sender Sequence Number is initialized to 0. The supported types 469 of replay protection and replay window length is application specific 470 and depends on the lower layers. The default is DTLS-type replay 471 protection with a window size of 32 initiated as described in 472 Section 4.1.2.6 of [RFC6347]. 474 3.3. Requirements on the Security Context Parameters 476 As collisions may lead to the loss of both confidentiality and 477 integrity, Sender ID SHALL be unique in the set of all security 478 contexts using the same Master Secret and Master Salt. When a 479 trusted third party assigns identifiers (e.g., using 480 [I-D.ietf-ace-oauth-authz]) or by using a protocol that allows the 481 parties to negotiate locally unique identifiers in each endpoint, the 482 Sender IDs can be very short. The maximum length of Sender ID is 483 length of nonce subtracted by 6 bytes. For AES-CCM-16-64-128 the 484 maximum length of Sender ID is 7 bytes. If Sender ID uniqueness 485 cannot be guaranteed by construction, Sender IDs MUST be long 486 uniformly random distributed byte strings such that the probability 487 of collisions is negligible. 489 To enable retrieval of the right Recipient Context, the Recipient ID 490 SHOULD be unique in the sets of all Recipient Contexts used by an 491 endpoint. The Client MAY provide a "kid context" parameter 492 Section 5.1 to help the Server find the right context. 494 While the triple (Master Secret, Master Salt, Sender ID) MUST be 495 unique, the same Master Salt MAY be used with several Master Secrets 496 and the same Master Secret MAY be used with several Master Salts. 498 4. Protected Message Fields 500 OSCORE transforms a CoAP message (which may have been generated from 501 an HTTP message) into an OSCORE message, and vice versa. OSCORE 502 protects as much of the original message as possible while still 503 allowing certain proxy operations (see Section 10). This section 504 defines how OSCORE protects the message fields and transfers them 505 end-to-end between client and server (in any direction). 507 The remainder of this section and later sections discuss the behavior 508 in terms of CoAP messages. If HTTP is used for a particular leg in 509 the end-to-end path, then this section applies to the conceptual CoAP 510 message that is mappable to/from the original HTTP message as 511 discussed in Section 10. That is, an HTTP message is conceptually 512 transformed to a CoAP message and then to an OSCORE message, and 513 similarly in the reverse direction. An actual implementation might 514 translate directly from HTTP to OSCORE without the intervening CoAP 515 representation. 517 Message fields of the CoAP message may be protected end-to-end 518 between CoAP client and CoAP server in different ways: 520 o Class E: encrypted and integrity protected, 521 o Class I: integrity protected only, or 523 o Class U: unprotected. 525 The sending endpoint SHALL transfer Class E message fields in the 526 ciphertext of the COSE object in the OSCORE message. The sending 527 endpoint SHALL include Class I message fields in the Additional 528 Authenticated Data (AAD) of the AEAD algorithm, allowing the 529 receiving endpoint to detect if the value has changed in transfer. 530 Class U message fields SHALL NOT be protected in transfer. Class I 531 and Class U message field values are transferred in the header or 532 options part of the OSCORE message, which is visible to proxies. 534 Message fields not visible to proxies, i.e., transported in the 535 ciphertext of the COSE object, are called "Inner" (Class E). Message 536 fields transferred in the header or options part of the OSCORE 537 message, which is visible to proxies, are called "Outer" (Class I or 538 U). There are currently no Class I options defined. 540 An OSCORE message may contain both an Inner and an Outer instance of 541 a certain CoAP message field. Inner message fields are intended for 542 the receiving endpoint, whereas Outer message fields are intended for 543 a proxy. Inner and Outer message fields are processed independently. 545 4.1. CoAP Payload 547 The CoAP Payload, if present in the original CoAP message, SHALL be 548 encrypted and integrity protected and is thus an Inner message field. 549 See Figure 4. 551 +------------------+---+---+ 552 | Field | E | U | 553 +------------------+---+---+ 554 | Payload | x | | 555 +------------------+---+---+ 557 E = Encrypt and Integrity Protect (Inner) 558 U = Unprotected (Outer) 560 Figure 4: Protection of CoAP Payload 562 The sending endpoint writes the payload of the original CoAP message 563 into the Plaintext (Section 5.3) input to the COSE object. The 564 receiving endpoint verifies and decrypts the COSE object, and 565 recreates the payload of the original CoAP message. 567 4.2. CoAP Options 569 A summary of how options are protected is shown in Figure 5. Note 570 that some options may have both Inner and Outer message fields which 571 are protected accordingly. The options which require special 572 processing are labelled with asterisks. 574 +-----+-----------------+---+---+ 575 | No. | Name | E | U | 576 +-----+-----------------+---+---+ 577 | 1 | If-Match | x | | 578 | 3 | Uri-Host | | x | 579 | 4 | ETag | x | | 580 | 5 | If-None-Match | x | | 581 | 6 | Observe | | * | 582 | 7 | Uri-Port | | x | 583 | 8 | Location-Path | x | | 584 | TBD | Object-Security | | * | 585 | 11 | Uri-Path | x | | 586 | 12 | Content-Format | x | | 587 | 14 | Max-Age | * | * | 588 | 15 | Uri-Query | x | | 589 | 17 | Accept | x | | 590 | 20 | Location-Query | x | | 591 | 23 | Block2 | * | * | 592 | 27 | Block1 | * | * | 593 | 28 | Size2 | * | * | 594 | 35 | Proxy-Uri | | * | 595 | 39 | Proxy-Scheme | | x | 596 | 60 | Size1 | x | x | 597 +-----+-----------------+---+---+ 599 E = Encrypt and Integrity Protect (Inner) 600 U = Unprotected (Outer) 601 * = Special 603 Figure 5: Protection of CoAP Options 605 Options that are unknown or for which OSCORE processing is not 606 defined SHALL be processed as class E (and no special processing). 607 Specifications of new CoAP options SHOULD define how they are 608 processed with OSCORE. A new COAP option SHOULD be of class E unless 609 it requires proxy processing. 611 4.2.1. Inner Options 613 Inner option message fields (class E) are used in a way analogous to 614 communicating in a protected manner directly with the other endpoint. 616 The sending endpoint SHALL write the Inner option message fields 617 present in the original CoAP message into the plaintext of the COSE 618 object Section 5.3, and then remove the Inner option message fields 619 from the OSCORE message. 621 The processing of Inner option message fields by the receiving 622 endpoint is specified in Section 7.2 and Section 7.4. 624 4.2.2. Outer Options 626 Outer option message fields (Class U or I) are used to support proxy 627 operations. 629 The sending endpoint SHALL include the Outer option message field 630 present in the original message in the options part of the OSCORE 631 message. All Outer option message fields, including Object-Security, 632 SHALL be encoded as described in Section 3.1 of [RFC7252], where the 633 delta is the difference to the previously included Outer option 634 message field. 636 The processing of Outer options by the receiving endpoint is 637 specified in Section 7.2 and Section 7.4. 639 A procedure for integrity-protection-only of Class I option message 640 fields is specified in Section 5.4. New CoAP options which are 641 repeatable and of class I MUST specify that proxies MUST NOT change 642 the order of the option's occurrences. 644 Note: There are currently no Class I option message fields defined. 646 4.2.3. Special Options 648 Some options require special processing, marked with an asterisk '*' 649 in Figure 5; the processing is specified in this section. 651 4.2.3.1. Max-Age 653 An Inner Max-Age message field is used to specify the freshness (as 654 defined in [RFC7252]) of the resource, end-to-end from the server to 655 the client, taking into account that the option is not accessible to 656 proxies. The Inner Max-Age SHALL be processed by OSCORE as specified 657 in Section 4.2.1. 659 An Outer Max-Age message field is used to avoid unnecessary caching 660 of OSCORE error responses at OSCORE unaware intermediary nodes. A 661 server MAY set a Class U Max-Age message field with value zero to 662 OSCORE error responses described in Section 6.4, Section 7.2 and 663 Section 7.4, which is then processed according to Section 4.2.2. 665 Non-error OSCORE responses do not need to include a Max-Age option 666 since the responses are non-cacheable by construction (see 667 Section 4.3). 669 4.2.3.2. The Block Options 671 Blockwise [RFC7959] is an optional feature. An implementation MAY 672 support [RFC7252] and the Object-Security option without supporting 673 [RFC7959]. The Block options (Block1, Block2, Size1, Size2), when 674 Inner message fields, provide secure message fragmentation such that 675 each fragment can be verified. The Block options, when Outer message 676 fields, enables hop-by-hop fragmentation of the OSCORE message. 677 Inner and Outer block processing may have different performance 678 properties depending on the underlying transport. The end-to-end 679 integrity of the message can be verified both in case of Inner and 680 Outer Blockwise provided all blocks are received (see 681 Section 4.2.3.2.2). 683 4.2.3.2.1. Inner Block Options 685 The sending CoAP endpoint MAY fragment a CoAP message as defined in 686 [RFC7959] before the message is processed by OSCORE. In this case 687 the Block options SHALL be processed by OSCORE as Inner options 688 (Section 4.2.1). The receiving CoAP endpoint SHALL process the 689 OSCORE message according to Section 4.2.1 before processing blockwise 690 as defined in [RFC7959]. 692 For concurrent blockwise operations the sending endpoint MUST ensure 693 that the receiving endpoint can distinguish between blocks from 694 different operations. One mechanism enabling this is specified in 695 [I-D.ietf-core-echo-request-tag]. 697 4.2.3.2.2. Outer Block Options 699 Proxies MAY fragment an OSCORE message using [RFC7959], by 700 introducing Block option message fields that are Outer Section 4.2.2 701 and not generated by the sending endpoint. Note that the Outer Block 702 options are neither encrypted nor integrity protected. As a 703 consequence, a proxy can maliciously inject block fragments 704 indefinitely, since the receiving endpoint needs to receive the last 705 block (see [RFC7959]) to be able to compose the OSCORE message and 706 verify its integrity. Therefore, applications supporting OSCORE and 708 [RFC7959] MUST specify a security policy defining a maximum 709 unfragmented message size (MAX_UNFRAGMENTED_SIZE) considering the 710 maximum size of message which can be handled by the endpoints. 711 Messages exceeding this size SHOULD be fragmented by the sending 712 endpoint using Inner Block options (Section 4.2.3.2.1). 714 An endpoint receiving an OSCORE message with an Outer Block option 715 SHALL first process this option according to [RFC7959], until all 716 blocks of the OSCORE message have been received, or the cumulated 717 message size of the blocks exceeds MAX_UNFRAGMENTED_SIZE. In the 718 former case, the processing of the OSCORE message continues as 719 defined in this document. In the latter case the message SHALL be 720 discarded. 722 To allow multiple concurrent request operations to the same server 723 (not only same resource), a CoAP proxy SHOULD follow the Request-Tag 724 processing specified in section 3.3.2 of 725 [I-D.ietf-core-echo-request-tag]. 727 4.2.3.3. Proxy-Uri 729 Proxy-Uri, when present, is split by OSCORE into class U options and 730 class E options, which are processed accordingly. When Proxy-Uri is 731 used in the original CoAP message, Uri-* are not present [RFC7252]. 733 The sending endpoint SHALL first decompose the Proxy-Uri value of the 734 original CoAP message into the Proxy-Scheme, Uri-Host, Uri-Port, Uri- 735 Path, and Uri-Query options (if present) according to section 6.4 of 736 [RFC7252]. 738 Uri-Path and Uri-Query are class E options and SHALL be protected and 739 processed as Inner options (Section 4.2.1). 741 The Proxy-Uri option of the OSCORE message SHALL be set to the 742 composition of Proxy-Scheme, Uri-Host and Uri-Port options (if 743 present) as specified in section 6.5 of [RFC7252], and processed as 744 an Outer option of Class U (Section 4.2.2). 746 Note that replacing the Proxy-Uri value with the Proxy-Scheme and 747 Uri-* options works by design for all CoAP URIs (see Section 6 of 748 [RFC7252]. OSCORE-aware HTTP servers should not use the userinfo 749 component of the HTTP URI (as defined in section 3.2.1 of [RFC3986]), 750 so that this type of replacement is possible in the presence of CoAP- 751 to-HTTP proxies. In other documents specifying cross-protocol 752 proxying behavior using different URI structures, it is expected that 753 the authors will create Uri-* options that allow decomposing the 754 Proxy-Uri, and specify in which OSCORE class they belong. 756 An example of how Proxy-Uri is processed is given here. Assume that 757 the original CoAP message contains: 759 o Proxy-Uri = "coap://example.com/resource?q=1" 761 During OSCORE processing, Proxy-Uri is split into: 763 o Proxy-Scheme = "coap" 765 o Uri-Host = "example.com" 767 o Uri-Port = "5683" 769 o Uri-Path = "resource" 771 o Uri-Query = "q=1" 773 Uri-Path and Uri-Query follow the processing defined in 774 Section 4.2.1, and are thus encrypted and transported in the COSE 775 object. The remaining options are composed into the Proxy-Uri 776 included in the options part of the OSCORE message, which has value: 778 o Proxy-Uri = "coap://example.com" 780 See Section 6.1 and 12.6 of [RFC7252] for more information. 782 4.2.3.4. Observe 784 Observe [RFC7641] is an optional feature. An implementation MAY 785 support [RFC7252] and the Object-Security option without supporting 786 [RFC7641]. The Observe option as used here targets the requirements 787 on forwarding of [I-D.hartke-core-e2e-security-reqs] 788 (Section 2.2.1.2). 790 In order for an OSCORE-unaware proxy to support forwarding of Observe 791 messages ([RFC7641]), there SHALL be an Outer Observe option, i.e., 792 present in the options part of the OSCORE message. The processing of 793 the CoAP Code for Observe messages is described in Section 4.3. 795 To secure the order of notifications, the client SHALL maintain a 796 Notification Number for each Observation it registers. The 797 Notification Number is a non-negative integer containing the largest 798 Partial IV of the successfully received notifications for the 799 associated Observe registration, see Section 6.4. The Notification 800 Number is initialized to the Partial IV of the first successfully 801 received notification response to the registration request. In 802 contrast to [RFC7641], the received Partial IV MUST always be 803 compared with the Notification Number, which thus MUST NOT be 804 forgotten after 128 seconds. 806 If the verification fails, the client SHALL stop processing the 807 response. The client MAY ignore the Observe option value. 809 The Observe option in the CoAP request may be legitimately removed by 810 a proxy. If the Observe option is removed from a CoAP request by a 811 proxy, then the server can still verify the request (as a non-Observe 812 request), and produce a non-Observe response. If the OSCORE client 813 receives a response to an Observe request without an outer Observe 814 value, then it MUST verify the response as a non-Observe response. 815 (The reverse case is covered in the verification of the response, see 816 Section 7.) 818 4.2.3.5. Object-Security 820 The Object-Security option is only defined to be present in OSCORE 821 messages, as an indication that OSCORE processing have been 822 performed. The content in the Object-Security option is neither 823 encrypted nor inegrity protected as a whole but some part of the 824 content of this option is protected, see Section 5.4. "OSCORE over 825 OSCORE" is not supported: If OSCORE processing detects an OSCORE 826 option in the original CoAP message, then processing SHALL be 827 stopped. 829 4.3. CoAP Header 831 A summary of how the CoAP Header fields are protected is shown in 832 Figure 6. 834 +------------------+---+---+ 835 | Field | E | U | 836 +------------------+---+---+ 837 | Version (UDP) | | x | 838 | Type (UDP) | | x | 839 | Length (TCP) | | x | 840 | Token Length | | x | 841 | Code | x | | 842 | Message ID (UDP) | | x | 843 | Token | | x | 844 +------------------+---+---+ 846 E = Encrypt and Integrity Protect (Inner) 847 U = Unprotected (Outer) 849 Figure 6: Protection of CoAP Header Fields 851 Most CoAP Header fields (i.e. the message fields in the fixed 4-byte 852 header) are required to be read and/or changed by CoAP proxies and 853 thus cannot in general be protected end-to-end between the endpoints. 854 As mentioned in Section 1, OSCORE protects the CoAP Request/Response 855 layer only, and not the Messaging Layer (Section 2 of [RFC7252]), so 856 fields such as Type and Message ID are not protected with OSCORE. 858 The CoAP Header field Code is protected by OSCORE. Code SHALL be 859 encrypted and integrity protected (Class E) to prevent an 860 intermediary from eavesdropping or manipulating the Code (e.g., 861 changing from GET to DELETE). 863 The sending endpoint SHALL write the Code of the original CoAP 864 message into the plaintext of the COSE object Section 5.3. After 865 that, the Outer Code of the OSCORE message SHALL be set to 0.02 866 (POST) for requests without Observe option, to 0.05 (FETCH) for 867 requests with Observe option, and to 2.04 (Changed) for responses. 868 Using FETCH with Observe allows OSCORE to be compliant with the 869 Observe processing in OSCORE-unaware proxies. The choice of POST and 870 FETCH ([RFC8132]) allows all OSCORE messages to have payload. 872 The receiving endpoint SHALL discard the Code in the OSCORE message 873 and write the Code of the Plaintext in the COSE object (Section 5.3) 874 into the decrypted CoAP message. 876 The other CoAP Header fields are Unprotected (Class U). The sending 877 endpoint SHALL write all other header fields of the original message 878 into the header of the OSCORE message. The receiving endpoint SHALL 879 write the header fields from the received OSCORE message into the 880 header of the decrypted CoAP message. 882 5. The COSE Object 884 This section defines how to use COSE [RFC8152] to wrap and protect 885 data in the original message. OSCORE uses the untagged COSE_Encrypt0 886 structure with an Authenticated Encryption with Additional Data 887 (AEAD) algorithm. The key lengths, IV length, nonce length, and 888 maximum Sender Sequence Number are algorithm dependent. 890 The AEAD algorithm AES-CCM-16-64-128 defined in Section 10.2 of 891 [RFC8152] is mandatory to implement. For AES-CCM-16-64-128 the 892 length of Sender Key and Recipient Key is 128 bits, the length of 893 nonce and Common IV is 13 bytes. The maximum Sender Sequence Number 894 is specified in Section 11. 896 We denote by Plaintext the data that is encrypted and integrity 897 protected, and by Additional Authenticated Data (AAD) the data that 898 is integrity protected only. 900 The COSE Object SHALL be a COSE_Encrypt0 object with fields defined 901 as follows 903 o The "protected" field is empty. 905 o The "unprotected" field includes: 907 * The "Partial IV" parameter. The value is set to the Sender 908 Sequence Number. All leading zeroes SHALL be removed when 909 encoding the Partial IV. The value 0 encodes to the byte 910 string 0x00. This parameter SHALL be present in requests. In 911 case of Observe (Section 4.2.3.4) the Partial IV SHALL be 912 present in responses, and otherwise the Partial IV SHOULD NOT 913 be present in responses. (A non-Observe example where the 914 Partial IV is included in a response is provided in 915 Section 6.5.2.) 917 * The "kid" parameter. The value is set to the Sender ID. This 918 parameter SHALL be present in requests and SHOULD NOT be 919 present in responses. (An example where the Sender ID is 920 included in a response is the extension of OSCORE to group 921 communication [I-D.tiloca-core-multicast-oscoap].) 923 * Optionally, a "kid context" parameter as defined in 924 Section 5.1. This parameter MAY be present in requests and 925 SHALL NOT be present in responses. 927 o The "ciphertext" field is computed from the secret key (Sender Key 928 or Recipient Key), Nonce (see Section 5.2), Plaintext (see 929 Section 5.3), and the Additional Authenticated Data (AAD) (see 930 Section 5.4) following Section 5.2 of [RFC8152]. 932 The encryption process is described in Section 5.3 of [RFC8152]. 934 5.1. Kid Context 936 For certain use cases, e.g. deployments where the same "kid" is used 937 with multiple contexts, it is necessary or favorable for the sender 938 to provide an additional identifier of the security material to use, 939 in order for the receiver to retrieve or establish the correct key. 940 The "kid context" parameter is used to provide such additional input. 941 The "kid context" is implicitly integrity protected, as manipulation 942 that leads to the wrong key (or no key) being retrieved which results 943 in an error, as described in Section 7.2. 945 A summary of the COSE header parameter "kid context" defined above 946 can be found in Figure 7. 948 Some examples of relevant uses of kid context are the following: 950 o If the client has an identifier in some other namespace which can 951 be used by the server to retrieve or establish the security 952 context, then that identifier can be used as kid context. The kid 953 context may be used as Master Salt Section 3.1 for additional 954 entropy of the security contexts, see for example 955 [I-D.ietf-6tisch-minimal-security]. 957 o In case of a group communication scenario 958 [I-D.tiloca-core-multicast-oscoap], if the server belongs to 959 multiple groups, then a group identifier can be used as kid 960 context to enable the server to find the right security context. 962 +----------+--------+------------+----------------+-----------------+ 963 | name | label | value type | value registry | description | 964 +----------+--------+------------+----------------+-----------------+ 965 | kid | kidctx | bstr | | Identifies the | 966 | context | | | | kid context | 967 +----------+--------+------------+----------------+-----------------+ 969 Figure 7: Additional common header parameter for the COSE object 971 5.2. Nonce 973 The nonce is constructed in the following way (see Figure 8): 975 1. left-padding the Partial IV (in network byte order) with zeroes 976 to exactly 5 bytes, 978 2. left-padding the (Sender) ID of the endpoint that generated the 979 Partial IV (in network byte order) with zeroes to exactly nonce 980 length - 6 bytes, 982 3. concatenating the size of the ID (S) with the padded ID and the 983 padded Partial IV, 985 4. and then XORing with the Common IV. 987 Note that in this specification only algorithms that use nonces equal 988 or greater than 7 bytes are supported. 990 When observe is not used, the request and the response may use the 991 same nonce. In this way, the Partial IV does not have to be sent in 992 responses, which reduces the size. For processing instructions, see 993 Section 7. 995 +---+-----------------------+--+--+--+--+--+ 996 | S | ID of PIV generator | Partial IV |----+ 997 +---+-----------------------+--+--+--+--+--+ | 998 | 999 +------------------------------------------+ | 1000 | Common IV |->(XOR) 1001 +------------------------------------------+ | 1002 | 1003 +------------------------------------------+ | 1004 | Nonce |<---+ 1005 +------------------------------------------+ 1007 Figure 8: AEAD Nonce Formation 1009 5.3. Plaintext 1011 The Plaintext is formatted as a CoAP message without Header (see 1012 Figure 9) consisting of: 1014 o the Code of the original CoAP message as defined in Section 3 of 1015 [RFC7252]; and 1017 o all Inner option message fields (see Section 4.2.1) present in the 1018 original CoAP message (see Section 4.2). The options are encoded 1019 as described in Section 3.1 of [RFC7252], where the delta is the 1020 difference to the previously included Class E option; and 1022 o the Payload of original CoAP message, if present, and in that case 1023 prefixed by the one-byte Payload Marker (0xFF). 1025 0 1 2 3 1026 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 1027 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1028 | Code | Class E options (if any) ... 1029 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1030 |1 1 1 1 1 1 1 1| Payload (if any) ... 1031 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1032 (only if there 1033 is payload) 1035 Figure 9: Plaintext 1037 NOTE: The Plaintext contains all CoAP data that needs to be encrypted 1038 end-to-end between the endpoints. 1040 5.4. Additional Authenticated Data 1042 The external_aad SHALL be a CBOR array as defined below: 1044 external_aad = [ 1045 version : uint, 1046 alg : int / tstr, 1047 request_kid : bstr, 1048 request_piv : bstr, 1049 options : bstr 1050 ] 1052 where: 1054 o version: contains the OSCORE version number. Implementations of 1055 this specification MUST set this field to 1. Other values are 1056 reserved for future versions. 1058 o alg: contains the AEAD Algorithm from the security context used 1059 for the exchange (see Section 3.1). 1061 o request_kid: contains the value of the 'kid' in the COSE object of 1062 the request (see Section 5). 1064 o request_piv: contains the value of the 'Partial IV' in the COSE 1065 object of the request (see Section 5). 1067 o options: contains the Class I options (see Section 4.2.2) present 1068 in the original CoAP message encoded as described in Section 3.1 1069 of [RFC7252], where the delta is the difference to the previously 1070 included class I option. 1072 NOTE: The format of the external_aad is for simplicity the same for 1073 requests and responses, although some parameters, e.g. request_kid 1074 need not be integrity protected in the requests. 1076 6. Sequence Numbers, Replay, Message Binding, and Freshness 1078 6.1. Message Binding 1080 In order to prevent response delay and mismatch attacks 1081 [I-D.mattsson-core-coap-actuators] from on-path attackers and 1082 compromised proxies, OSCORE binds responses to the requests by 1083 including the kid and Partial IV of the request in the AAD of the 1084 response. The server therefore needs to store the kid and Partial IV 1085 of the request until all responses have been sent. 1087 6.2. AEAD Nonce Uniqueness 1089 An AEAD nonce MUST NOT be used more than once per AEAD key. In order 1090 to assure unique nonces, each Sender Context contains a Sender 1091 Sequence Number used to protect requests, and - in case of Observe - 1092 responses. If messages are processed concurrently, the operation of 1093 reading and increasing the Sender Sequence Number MUST be atomic. 1095 The maximum Sender Sequence Number is algorithm dependent, see 1096 Section 11, and no greater than 2^40 - 1. If the Sender Sequence 1097 Number exceeds the maximum, the endpoint MUST NOT process any more 1098 messages with the given Sender Context. The endpoint SHOULD acquire 1099 a new security context (and consequently inform the other endpoint) 1100 before this happens. The latter is out of scope of this document. 1102 6.3. Freshness 1104 For requests, OSCORE provides weak absolute freshness as the only 1105 guarantee is that the request is not older than the security context. 1106 For applications having stronger demands on request freshness (e.g., 1107 control of actuators), OSCORE needs to be augmented with mechanisms 1108 providing freshness, for example as specified in 1109 [I-D.ietf-core-echo-request-tag]. 1111 For responses, the message binding guarantees that a response is not 1112 older than its request. For responses without Observe, this gives 1113 strong absolute freshness. For responses with Observe, the absolute 1114 freshness gets weaker with time, and it is RECOMMENDED that the 1115 client regularly restart the observation. 1117 For requests, and responses with Observe, OSCORE also provides 1118 relative freshness in the sense that the received Partial IV allows a 1119 recipient to determine the relative order of responses. 1121 6.4. Replay Protection 1123 In order to protect from replay of requests, the server's Recipient 1124 Context includes a Replay Window. A server SHALL verify that a 1125 Partial IV received in the COSE object has not been received before. 1126 If this verification fails the server SHALL stop processing the 1127 message and, MAY optionally respond with a 4.01 Unauthorized error 1128 message. The server MAY set an Outer Max-Age option with value zero. 1129 The diagnostic payload MAY contain the "Replay protection failed" 1130 string. The size and type of the Replay Window depends on the use 1131 case and lower protocol layers. In case of reliable and ordered 1132 transport from endpoint to endpoint, the server MAY just store the 1133 last received Partial IV and require that newly received Partial IVs 1134 equals the last received Partial IV + 1. 1136 Responses to non-Observe requests are protected against replay as 1137 they are cryptographically bound to the request. 1139 In the case of Observe, a client receiving a notification SHALL 1140 verify that the Partial IV of a received notification is greater than 1141 the Notification Number bound to that Observe registration. If the 1142 verification fails, the client SHALL stop processing the response. 1143 If the verification succeeds, the client SHALL overwrite the 1144 corresponding Notification Number with the received Partial IV. 1146 If messages are processed concurrently, the Partial IV needs to be 1147 validated a second time after decryption and before updating the 1148 replay protection data. The operation of validating the Partial IV 1149 and updating the replay protection data MUST be atomic. 1151 6.5. Losing Part of the Context State 1153 To prevent reuse of the Nonce with the same key, or from accepting 1154 replayed messages, a node needs to handle the situation of losing 1155 rapidly changing parts of the context, such as the request Token, 1156 Sender Sequence Number, Replay Window, and Notififcation Numbers. 1157 These are typically stored in RAM and therefore lost in the case of 1158 an unplanned reboot. 1160 After boot, a node MAY reject to use existing security contexts from 1161 before it booted and MAY establish a new security context with each 1162 party it communicates. However, establishing a fresh security 1163 context may have a non-negligible cost in terms of, e.g., power 1164 consumption. 1166 After boot, a node MAY use a partly persistently stored security 1167 context, but then the node MUST NOT reuse a previous Sender Sequence 1168 Number and MUST NOT accept previously accepted messages. Some ways 1169 to achieve this is described below: 1171 6.5.1. Sequence Number 1173 To prevent reuse of Sender Sequence Numbers, a node MAY perform the 1174 following procedure during normal operations: 1176 o Each time the Sender Sequence Number is evenly divisible by K, 1177 where K is a positive integer, store the Sender Sequence Number in 1178 persistent memory. After boot, the node initiates the Sender 1179 Sequence Number to the value stored in persistent memory + K - 1. 1180 Storing to persistent memory can be costly. The value K gives a 1181 trade-off between the number of storage operations and efficient 1182 use of Sender Sequence Numbers. 1184 6.5.2. Replay Window 1186 To prevent accepting replay of previously received requests, the 1187 server MAY perform the following procedure after boot: 1189 o For each stored security context, the first time after boot the 1190 server receives an OSCORE request, the server responds with the 1191 Echo option [I-D.ietf-core-echo-request-tag] to get a request with 1192 verifiable freshness. The server MUST use its Partial IV when 1193 generating the nonce and MUST include the Partial IV in the 1194 response. 1196 If the server using the Echo option can verify a second request as 1197 fresh, then the Partial IV of the second request is set as the lower 1198 limit of the replay window. 1200 6.5.3. Replay Protection of Observe Notifications 1202 To prevent accepting replay of previously received notification 1203 responses, the client MAY perform the following procedure after boot: 1205 o The client rejects notifications bound to the earlier 1206 registration, removes all Notification Numbers and re-register 1207 using Observe. 1209 7. Processing 1211 This section describes the OSCORE message processing. 1213 7.1. Protecting the Request 1215 Given a CoAP request, the client SHALL perform the following steps to 1216 create an OSCORE request: 1218 1. Retrieve the Sender Context associated with the target resource. 1220 2. Compose the Additional Authenticated Data and the Plaintext, as 1221 described in Section 5.4 and Section 5.3. 1223 3. Compute the AEAD nonce from the Sender ID, Common IV, and Partial 1224 IV (Sender Sequence Number in network byte order) as described in 1225 Section 5.2. Then (in one atomic operation, see Section 6.2) 1226 increment the Sender Sequence Number by one. 1228 4. Encrypt the COSE object using the Sender Key. Compress the COSE 1229 Object as specified in Section 8. 1231 5. Format the OSCORE message according to Section 4. The Object- 1232 Security option is added, see Section 4.2.2. 1234 6. Store the association Token - Security Context. The client SHALL 1235 be able to find the Recipient Context from the Token in the 1236 response. 1238 7.2. Verifying the Request 1240 A server receiving a request containing the Object-Security option 1241 SHALL perform the following steps: 1243 1. Process outer Block options according to [RFC7959], until all 1244 blocks of the request have been received, see Section 4.2.3.2. 1246 2. Discard the message Code and all non-special Inner option 1247 message fields (marked with 'x' in column E of Figure 5) present 1248 in the received message. For example, an If-Match Outer option 1249 is discarded, but an Uri-Host Outer option is not discarded. 1251 3. Decompress the COSE Object (Section 8) and retrieve the 1252 Recipient Context associated with the Recipient ID in the 'kid' 1253 parameter. If either the decompression or the COSE message 1254 fails to decode, or the server fails to retrieve a Recipient 1255 Context with Recipient ID corresponding to the 'kid' parameter 1256 received, then the server SHALL stop processing the request. 1257 If: 1259 * either the decompression or the COSE message fails to decode, 1260 the server MAY respond with a 4.02 Bad Option error message. 1261 The server MAY set an Outer Max-Age option with value zero. 1262 The diagnostic payload SHOULD contain the string "Failed to 1263 decode COSE". 1265 * the server fails to retrieve a Recipient Context with 1266 Recipient ID corresponding to the 'kid' parameter received, 1267 the server MAY respond with a 4.01 Unauthorized error 1268 message. The server MAY set an Outer Max-Age option with 1269 value zero. The diagnostic payload SHOULD contain the string 1270 "Security context not found". 1272 4. Verify the 'Partial IV' parameter using the Replay Window, as 1273 described in Section 6. 1275 5. Compose the Additional Authenticated Data, as described in 1276 Section 5. 1278 6. Compute the AEAD nonce from the Recipient ID, Common IV, and the 1279 'Partial IV' parameter, received in the COSE Object. 1281 7. Decrypt the COSE object using the Recipient Key. 1283 * If decryption fails, the server MUST stop processing the 1284 request and MAY respond with a 4.00 Bad Request error 1285 message. The server MAY set an Outer Max-Age option with 1286 value zero. The diagnostic payload SHOULD contain the 1287 "Decryption failed" string. 1289 * If decryption succeeds, update the Replay Window, as 1290 described in Section 6. 1292 8. For each decrypted option, check if the option is also present 1293 as an Outer option: if it is, discard the Outer. For example: 1294 the message contains a Max-Age Inner and a Max-Age Outer option. 1295 The Outer Max-Age is discarded. 1297 9. Add decrypted code, options and payload to the decrypted 1298 request. The Object-Security option is removed. 1300 10. The decrypted CoAP request is processed according to [RFC7252] 1302 7.3. Protecting the Response 1304 Given a CoAP response, the server SHALL perform the following steps 1305 to create an OSCORE response. Note that CoAP error responses derived 1306 from CoAP processing (point 10. in Section 7.2) are protected, as 1307 well as successful CoAP responses, while the OSCORE errors (point 3, 1308 4, and 7 in Section 7.2) do not follow the processing below, but are 1309 sent as simple CoAP responses, without OSCORE processing. 1311 1. Retrieve the Sender Context in the Security Context used to 1312 verify the request. 1314 2. Compose the Additional Authenticated Data and the Plaintext, as 1315 described in Section 5.4 and Section 5.3. 1317 3. Compute the AEAD nonce 1319 * If Observe is used, Compute the AEAD nonce from the Sender ID, 1320 Common IV, and Partial IV (Sender Sequence Number in network 1321 byte order). Then (in one atomic operation, see Section 6.2) 1322 increment the Sender Sequence Number by one. 1324 * If Observe is not used, either the nonce from the request is 1325 used or a new Partial IV is used. 1327 4. Encrypt the COSE object using the Sender Key. Compress the COSE 1328 Object as specified in Section 8. If the nonce was constructed 1329 from a new Partial IV, this Partial IV MUST be included in the 1330 message. If the nonce from the request was used, the Partial IV 1331 MUST NOT be included in the message. 1333 5. Format the OSCORE message according to Section 4. The Object- 1334 Security option is added, see Section 4.2.2. 1336 7.4. Verifying the Response 1338 A client receiving a response containing the Object-Security option 1339 SHALL perform the following steps: 1341 1. Process outer Block options according to [RFC7959], until all 1342 blocks of the OSCORE message have been received, see 1343 Section 4.2.3.2. 1345 2. Discard the message Code and all non-special Class E options 1346 from the message. For example, ETag Outer option is discarded, 1347 Max-Age Outer option is not discarded. 1349 3. Retrieve the Recipient Context associated with the Token. 1350 Decompress the COSE Object (Section 8). If either the 1351 decompression or the COSE message fails to decode, then go to 1352 11. 1354 4. For Observe notifications, verify the received 'Partial IV' 1355 parameter against the corresponding Notification Number as 1356 described in Section 6. If the client receives a notification 1357 for which no Observe request was sent, then go to 11. 1359 5. Compose the Additional Authenticated Data, as described in 1360 Section 5. 1362 6. Compute the AEAD nonce 1364 1. If the Observe option and the Partial IV are not present in 1365 the response, the nonce from the request is used. 1367 2. If the Observe option is present in the response, and the 1368 Partial IV is not present in the response, then go to 11. 1370 3. If the Partial IV is present in the response, compute the 1371 AEAD nonce from the Recipient ID, Common IV, and the 1372 'Partial IV' parameter, received in the COSE Object. 1374 7. Decrypt the COSE object using the Recipient Key. 1376 * If decryption fails, then go to 11. 1378 * If decryption succeeds and Observe is used, update the 1379 corresponding Notification Number, as described in Section 6. 1381 8. For each decrypted option, check if the option is also present 1382 as an Outer option: if it is, discard the Outer. For example: 1383 the message contains a Max-Age Inner and a Max-Age Outer option. 1384 The Outer Max-Age is discarded. 1386 9. Add decrypted code, options and payload to the decrypted 1387 request. The Object-Security option is removed. 1389 10. The decrypted CoAP response is processed according to [RFC7252] 1391 11. (Optional) In case any of the previous erroneous conditions 1392 apply: the client SHALL stop processing the response. 1394 8. OSCORE Compression 1396 The Concise Binary Object Representation (CBOR) [RFC7049] combines 1397 very small message sizes with extensibility. The CBOR Object Signing 1398 and Encryption (COSE) [RFC8152] uses CBOR to create compact encoding 1399 of signed and encrypted data. COSE is however constructed to support 1400 a large number of different stateless use cases, and is not fully 1401 optimized for use as a stateful security protocol, leading to a 1402 larger than necessary message expansion. In this section, we define 1403 a simple stateless compression mechanism for OSCORE called the 1404 "compressed COSE object", which significantly reduces the per-packet 1405 overhead. 1407 8.1. Encoding of the Object-Security Value 1409 The value of the Object-Security option SHALL contain the OSCORE flag 1410 byte, the Partial IV parameter, the kid context parameter (length and 1411 value), and the kid parameter as follows: 1413 0 1 2 3 4 5 6 7 <--------- n bytes -------------> 1414 +-+-+-+-+-+-+-+-+--------------------------------- 1415 |0 0 0|h|k| n | Partial IV (if any) 1416 +-+-+-+-+-+-+-+-+--------------------------------- 1418 <-- 1 byte --><------ s bytes ------> 1419 +------------+----------------------+------------------+ 1420 | s (if any) | kid context (if any) | kid (if any) ... | 1421 +------------+----------------------+------------------+ 1423 Figure 10: Object-Security Value 1425 o The first byte (= the OSCORE flag byte) encodes a set of flags and 1426 the length of the Partial IV parameter. 1428 * The three least significant bits encode the Partial IV length 1429 n. If n = 0 then the Partial IV is not present in the 1430 compressed COSE object. The values n = 6 and n = 7 is 1431 reserved. 1433 * The fourth least significant bit is the kid flag, k: it is set 1434 to 1 if the kid is present in the compressed COSE object. 1436 * The fifth least significant bit is the kid context flag, h: it 1437 is set to 1 if the compressed COSE object contains a kid 1438 context, see Section 5.1. 1440 * The sixth least significant bit is reserved for indicating the 1441 presence of a signature. This needs to be specified in a 1442 separate document. The bit SHALL be set to zero when not in 1443 use. 1445 * The seventh least significant bit is reserved to expand the 1446 flag byte. This needs to be specified in a separate document. 1447 The bit SHALL be set to zero when not in use. 1449 * The eighth least significant bit is reserved for indicating if 1450 a non-compressed COSE object is used. This needs to be 1451 specified in a separate document. The bit SHALL be set to zero 1452 when not in use. 1454 o The following n bytes encode the value of the Partial IV, if the 1455 Partial IV is present (n > 0). 1457 o The following 1 byte encode the length of the kid context 1458 (Section 5.1) s, if the kid context flag is set (h = 1). 1460 o The following s bytes encode the kid context, if the kid context 1461 flag is set (h = 1). 1463 o The remaining bytes encode the value of the kid, if the kid is 1464 present (k = 1) 1466 Note that the kid MUST be the last field of the object-security 1467 value, even in case reserved bits are used and additional fields are 1468 added to it. 1470 8.2. Encoding of the OSCORE Payload 1472 The payload of the OSCORE message SHALL encode the ciphertext of the 1473 COSE object. 1475 8.3. Examples of Compressed COSE Objects 1477 8.3.1. Example: Requests 1479 Request with kid = 25 and Partial IV = 5 1481 Before compression (24 bytes): 1483 [ 1484 h'', 1485 { 4:h'25', 6:h'05' }, 1486 h'aea0155667924dff8a24e4cb35b9' 1487 ] 1489 After compression (17 bytes): 1491 Flag byte: 0b00001001 = 0x09 1493 Option Value: 09 05 25 (3 bytes) 1495 Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) 1497 Request with kid = empty string and Partial IV = 0 1499 After compression (16 bytes): 1501 Flag byte: 0b00001001 = 0x09 1503 Option Value: 09 00 (2 bytes) 1505 Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) 1507 Request with kid = empty string, Partial IV = 5, and kid context = 1508 0x44616c656b 1510 After compression (22 bytes): 1512 Flag byte: 0b00011001 = 0x19 1514 Option Value: 19 05 05 44 61 6c 65 6b (8 bytes) 1516 Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) 1518 8.3.2. Example: Response (without Observe) 1520 Before compression (18 bytes): 1522 [ 1523 h'', 1524 {}, 1525 h'aea0155667924dff8a24e4cb35b9' 1526 ] 1528 After compression (14 bytes): 1530 Flag byte: 0b00000000 = 0x00 1532 Option Value: (0 bytes) 1534 Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) 1536 8.3.3. Example: Response (with Observe) 1538 Before compression (21 bytes): 1540 [ 1541 h'', 1542 { 6:h'07' }, 1543 h'aea0155667924dff8a24e4cb35b9' 1544 ] 1546 After compression (16 bytes): 1548 Flag byte: 0b00000001 = 0x01 1550 Option Value: 01 07 (2 bytes) 1552 Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) 1554 9. Web Linking 1556 The use of OSCORE MAY be indicated by a target attribute "osc" in a 1557 web link [RFC8288] to a resource. This attribute is a hint 1558 indicating that the destination of that link is to be accessed using 1559 OSCORE. Note that this is simply a hint, it does not include any 1560 security context material or any other information required to run 1561 OSCORE. 1563 A value MUST NOT be given for the "osc" attribute; any present value 1564 MUST be ignored by parsers. The "osc" attribute MUST NOT appear more 1565 than once in a given link-value; occurrences after the first MUST be 1566 ignored by parsers. 1568 10. Proxy Operations 1570 RFC 7252 defines operations for a CoAP-to-CoAP proxy (see Section 5.7 1571 of [RFC7252]) and for proxying between CoAP and HTTP (Section 10 of 1572 [RFC7252]). A more detailed description of the HTTP-to-CoAP mapping 1573 is provided by [RFC8075]. This section describes the operations of 1574 OSCORE-aware proxies. 1576 10.1. CoAP-to-CoAP Forwarding Proxy 1578 OSCORE is designed to work with legacy CoAP-to-CoAP forward proxies 1579 [RFC7252], but OSCORE-aware proxies MAY provide certain 1580 simplifications as specified in this section. 1582 The targeted proxy operations are specified in Section 2.2.1 of 1583 [I-D.hartke-core-e2e-security-reqs]. In particular caching is 1584 disabled since the CoAP response is only applicable to the original 1585 client's CoAP request. An OSCORE-aware proxy SHALL NOT cache a 1586 response to a request with an Object-Security option. As a 1587 consequence, the search for cache hits and CoAP freshness/Max-Age 1588 processing can be omitted. 1590 Proxy processing of the (Outer) Proxy-Uri option is as defined in 1591 [RFC7252]. 1593 Proxy processing of the (Outer) Block options is as defined in 1594 [RFC7959] and [I-D.ietf-core-echo-request-tag]. 1596 Proxy processing of the (Outer) Observe option is as defined in 1597 [RFC7641]. OSCORE-aware proxies MAY look at the Partial IV value 1598 instead of the Outer Observe option. 1600 10.2. HTTP-to-CoAP Translation Proxy 1602 Section 10.2 of [RFC7252] and [RFC8075] specify the behavior of an 1603 HTTP-to-CoAP proxy. As requested in Section 1 of [RFC8075], this 1604 section describes the HTTP mapping for the OSCORE protocol extension 1605 of CoAP. 1607 The presence of the Object-Security option, both in requests and 1608 responses, is expressed in an HTTP header field named Object-Security 1609 in the mapped request or response. The value of the field is: 1611 o "" (empty string) if the CoAP Object-Security option is empty, or 1612 o the value of the CoAP Object-Security option Section 8.1 in 1613 base64url encoding (Section 5 of [RFC4648]) without padding (see 1614 [RFC7515] Appendix C for implementation notes for this encoding). 1616 The value of the body is the OSCORE payload Section 8.2. 1618 Example: 1620 Mapping and notation here is based on "Simple Form" (Section 5.4.1.1 1621 of [RFC8075]). 1623 [HTTP request -- Before object security processing] 1625 GET http://proxy.url/hc/?target_uri=coap://server.url/orders HTTP/1.1 1627 [HTTP request -- HTTP Client to Proxy] 1629 POST http://proxy.url/hc/?target_uri=coap://server.url/ HTTP/1.1 1630 Object-Security: 09 25 1631 Body: 09 07 01 13 61 f7 0f d2 97 b1 [binary] 1633 [CoAP request -- Proxy to CoAP Server] 1635 POST coap://server.url/ 1636 Object-Security: 09 25 1637 Payload: 09 07 01 13 61 f7 0f d2 97 b1 [binary] 1639 [CoAP response -- CoAP Server to Proxy] 1641 2.04 Changed 1642 Object-Security: [empty] 1643 Payload: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] 1645 [HTTP response -- Proxy to HTTP Client] 1647 HTTP/1.1 200 OK 1648 Object-Security: "" (empty string) 1649 Body: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] 1651 [HTTP response -- After object security processing] 1653 HTTP/1.1 200 OK 1654 Body: Exterminate! Exterminate! 1656 Note that the HTTP Status Code 200 in the next-to-last message is the 1657 mapping of CoAP Code 2.04 (Changed), whereas the HTTP Status Code 200 1658 in the last message is the mapping of the CoAP Code 2.05 (Content), 1659 which was encrypted within the compressed COSE object carried in the 1660 Body of the HTTP response. 1662 10.3. CoAP-to-HTTP Translation Proxy 1664 Section 10.1 of [RFC7252] describes the behavior of a CoAP-to-HTTP 1665 proxy. RFC 8075 [RFC8075] does not cover this direction in any more 1666 detail and so an example instantiation of Section 10.1 of [RFC7252] 1667 is used below. 1669 Example: 1671 [CoAP request -- Before object security processing] 1673 GET coap://proxy.url/ 1674 Proxy-Uri=http://server.url/orders 1676 [CoAP request -- CoAP Client to Proxy] 1678 POST coap://proxy.url/ 1679 Proxy-Uri=http://server.url/ 1680 Object-Security: 09 25 1681 Payload: 09 07 01 13 61 f7 0f d2 97 b1 [binary] 1683 [HTTP request -- Proxy to HTTP Server] 1685 POST http://server.url/ HTTP/1.1 1686 Object-Security: 09 25 1687 Body: 09 07 01 13 61 f7 0f d2 97 b1 [binary] 1689 [HTTP response -- HTTP Server to Proxy] 1691 HTTP/1.1 200 OK 1692 Object-Security: "" (empty string) 1693 Body: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] 1695 [CoAP response -- CoAP Server to Proxy] 1697 2.04 Changed 1698 Object-Security: [empty] 1699 Payload: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] 1701 [CoAP response -- After object security processing] 1703 2.05 Content 1704 Payload: Exterminate! Exterminate! 1706 Note that the HTTP Code 2.04 (Changed) in the next-to-last message is 1707 the mapping of HTTP Status Code 200, whereas the CoAP Code 2.05 1708 (Content) in the last message is the value that was encrypted within 1709 the compressed COSE object carried in the Body of the HTTP response. 1711 11. Security Considerations 1713 In scenarios with intermediary nodes such as proxies or brokers, 1714 transport layer security such as (D)TLS only protects data hop-by- 1715 hop. As a consequence, the intermediary nodes can read and modify 1716 information. The trust model where all intermediate nodes are 1717 considered trustworthy is problematic, not only from a privacy 1718 perspective, but also from a security perspective, as the 1719 intermediaries are free to delete resources on sensors and falsify 1720 commands to actuators (such as "unlock door", "start fire alarm", 1721 "raise bridge"). Even in the rare cases, where all the owners of the 1722 intermediary nodes are fully trusted, attacks and data breaches make 1723 such an architecture brittle. 1725 (D)TLS protects hop-by-hop the entire message, including header, 1726 options, and payload. OSCORE protects end-to-end the payload, and 1727 all information in the options and header, that is not required for 1728 proxy operations (see Section 4). (D)TLS and OSCORE can be combined, 1729 thereby enabling end-to-end security of the message payload, in 1730 combination with hop-by-hop protection of the entire message, during 1731 transport between end-point and intermediary node. The message 1732 layer, however, cannot be protected end-to-end through intermediary 1733 devices since, even if the protocol itself isn't translated, the 1734 parameters Type, Message ID, Token, and Token Length may be changed 1735 by a proxy. 1737 The use of COSE to protect messages as specified in this document 1738 requires an established security context. The method to establish 1739 the security context described in Section 3.2 is based on a common 1740 shared secret material in client and server, which may be obtained, 1741 e.g., by using the ACE framework [I-D.ietf-ace-oauth-authz]. An 1742 OSCORE profile of ACE is described in [I-D.seitz-ace-oscoap-profile]. 1744 Most AEAD algorithms require a unique nonce for each message, for 1745 which the sender sequence numbers in the COSE message field "Partial 1746 IV" is used. If the recipient accepts any sequence number larger 1747 than the one previously received, then the problem of sequence number 1748 synchronization is avoided. With reliable transport, it may be 1749 defined that only messages with sequence number which are equal to 1750 previous sequence number + 1 are accepted. The alternatives to 1751 sequence numbers have their issues: very constrained devices may not 1752 be able to support accurate time, or to generate and store large 1753 numbers of random nonces. The requirement to change key at counter 1754 wrap is a complication, but it also forces the user of this 1755 specification to think about implementing key renewal. 1757 The maximum sender sequence number is dependent on the AEAD 1758 algorithm. The maximum sender sequence number SHALL be 2^40 - 1, or 1759 any algorithm specific lower limit, after which a new security 1760 context must be generated. The mechanism to build the nonce 1761 (Section 5.2) assumes that the nonce is at least 56 bit-long, and the 1762 Partial IV is at most 40 bit-long. The mandatory-to-implement AEAD 1763 algorithm AES-CCM-16-64-128 is selected for compatibility with CCM*. 1765 The inner block options enable the sender to split large messages 1766 into OSCORE-protected blocks such that the receiving node can verify 1767 blocks before having received the complete message. The outer block 1768 options allow for arbitrary proxy fragmentation operations that 1769 cannot be verified by the endpoints, but can by policy be restricted 1770 in size since the encrypted options allow for secure fragmentation of 1771 very large messages. A maximum message size (above which the sending 1772 endpoint fragments the message and the receiving endpoint discards 1773 the message, if complying to the policy) may be obtained as part of 1774 normal resource discovery. 1776 12. Privacy Considerations 1778 Privacy threats executed through intermediate nodes are considerably 1779 reduced by means of OSCORE. End-to-end integrity protection and 1780 encryption of the message payload and all options that are not used 1781 for proxy operations, provide mitigation against attacks on sensor 1782 and actuator communication, which may have a direct impact on the 1783 personal sphere. 1785 The unprotected options (Figure 5) may reveal privacy sensitive 1786 information. In particular Uri-Host SHOULD NOT contain privacy 1787 sensitive information. 1789 CoAP headers sent in plaintext allow for example matching of CON and 1790 ACK (CoAP Message Identifier), matching of request and responses 1791 (Token) and traffic analysis. 1793 Using the mechanisms described in Section 6.5 may reveal when a 1794 device goes through a reboot. This can be mitigated by the device 1795 storing the precise state of sender sequence number and replay window 1796 on a clean shutdown. 1798 The length of message fields can reveal information about the 1799 message. Applications may use a padding scheme to protect against 1800 traffic analysis. As an example, the strings "YES" and "NO" even if 1801 encrypted can be distinguished from each other as there is no padding 1802 supplied by the current set of encryption algorithms. Some 1803 information can be determined even from looking at boundary 1804 conditions. An example of this would be returning an integer between 1805 0 and 100 where lengths of 1, 2 and 3 will provide information about 1806 where in the range things are. Three different methods to deal with 1807 this are: 1) ensure that all messages are the same length. For 1808 example, using 0 and 1 instead of 'yes' and 'no'. 2) Use a character 1809 which is not part of the responses to pad to a fixed length. For 1810 example, pad with a space to three characters. 3) Use the PKCS #7 1811 style padding scheme where m bytes are appended each having the value 1812 of m. For example, appending a 0 to "YES" and two 1's to "NO". This 1813 style of padding means that all values need to be padded. Similar 1814 arguments apply to other message fields such as resource names. 1816 13. IANA Considerations 1818 Note to RFC Editor: Please replace all occurrences of "[[this 1819 document]]" with the RFC number of this specification. 1821 13.1. COSE Header Parameters Registry 1823 The 'kid context' paramter is added to the "COSE Header Parameters 1824 Registry": 1826 o Name: kid context 1828 o Label: kidctx 1830 o Value Type: bstr 1832 o Value Registry: 1834 o Description: kid context 1836 o Reference: Section 5.1 of this document 1838 13.2. CoAP Option Numbers Registry 1840 The Object-Security option is added to the CoAP Option Numbers 1841 registry: 1843 +--------+-----------------+-------------------+ 1844 | Number | Name | Reference | 1845 +--------+-----------------+-------------------+ 1846 | TBD | Object-Security | [[this document]] | 1847 +--------+-----------------+-------------------+ 1849 13.3. Header Field Registrations 1851 The HTTP header field Object-Security is added to the Message Headers 1852 registry: 1854 +-------------------+----------+----------+-------------------+ 1855 | Header Field Name | Protocol | Status | Reference | 1856 +-------------------+----------+----------+-------------------+ 1857 | Object-Security | http | standard | [[this document]] | 1858 +-------------------+----------+----------+-------------------+ 1860 14. Acknowledgments 1862 The following individuals provided input to this document: Christian 1863 Amsuess, Tobias Andersson, Carsten Bormann, Joakim Brorsson, Thomas 1864 Fossati, Martin Gunnarsson, Klaus Hartke, Jim Schaad, Dave Thaler, 1865 Marco Tiloca, and Malisa Vučinić. 1867 Ludwig Seitz and Goeran Selander worked on this document as part of 1868 the CelticPlus project CyberWI, with funding from Vinnova. 1870 15. References 1872 15.1. Normative References 1874 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1875 Requirement Levels", BCP 14, RFC 2119, 1876 DOI 10.17487/RFC2119, March 1997, 1877 . 1879 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1880 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 1881 . 1883 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 1884 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 1885 January 2012, . 1887 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1888 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1889 October 2013, . 1891 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1892 Application Protocol (CoAP)", RFC 7252, 1893 DOI 10.17487/RFC7252, June 2014, 1894 . 1896 [RFC7641] Hartke, K., "Observing Resources in the Constrained 1897 Application Protocol (CoAP)", RFC 7641, 1898 DOI 10.17487/RFC7641, September 2015, 1899 . 1901 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 1902 the Constrained Application Protocol (CoAP)", RFC 7959, 1903 DOI 10.17487/RFC7959, August 2016, 1904 . 1906 [RFC8075] Castellani, A., Loreto, S., Rahman, A., Fossati, T., and 1907 E. Dijk, "Guidelines for Mapping Implementations: HTTP to 1908 the Constrained Application Protocol (CoAP)", RFC 8075, 1909 DOI 10.17487/RFC8075, February 2017, 1910 . 1912 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 1913 FETCH Methods for the Constrained Application Protocol 1914 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 1915 . 1917 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 1918 RFC 8152, DOI 10.17487/RFC8152, July 2017, 1919 . 1921 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 1922 DOI 10.17487/RFC8288, October 2017, 1923 . 1925 15.2. Informative References 1927 [I-D.bormann-6lo-coap-802-15-ie] 1928 Bormann, C., "Constrained Application Protocol (CoAP) over 1929 IEEE 802.15.4 Information Element for IETF", draft- 1930 bormann-6lo-coap-802-15-ie-00 (work in progress), April 1931 2016. 1933 [I-D.hartke-core-e2e-security-reqs] 1934 Selander, G., Palombini, F., and K. Hartke, "Requirements 1935 for CoAP End-To-End Security", draft-hartke-core-e2e- 1936 security-reqs-03 (work in progress), July 2017. 1938 [I-D.ietf-6tisch-minimal-security] 1939 Vucinic, M., Simon, J., Pister, K., and M. Richardson, 1940 "Minimal Security Framework for 6TiSCH", draft-ietf- 1941 6tisch-minimal-security-04 (work in progress), October 1942 2017. 1944 [I-D.ietf-ace-oauth-authz] 1945 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 1946 H. Tschofenig, "Authentication and Authorization for 1947 Constrained Environments (ACE)", draft-ietf-ace-oauth- 1948 authz-09 (work in progress), November 2017. 1950 [I-D.ietf-cbor-cddl] 1951 Birkholz, H., Vigano, C., and C. Bormann, "Concise data 1952 definition language (CDDL): a notational convention to 1953 express CBOR data structures", draft-ietf-cbor-cddl-00 1954 (work in progress), July 2017. 1956 [I-D.ietf-core-coap-tcp-tls] 1957 Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 1958 Silverajan, B., and B. Raymor, "CoAP (Constrained 1959 Application Protocol) over TCP, TLS, and WebSockets", 1960 draft-ietf-core-coap-tcp-tls-10 (work in progress), 1961 October 2017. 1963 [I-D.ietf-core-echo-request-tag] 1964 Amsuess, C., Mattsson, J., and G. Selander, "Echo and 1965 Request-Tag", draft-ietf-core-echo-request-tag-00 (work in 1966 progress), October 2017. 1968 [I-D.mattsson-core-coap-actuators] 1969 Mattsson, J., Fornehed, J., Selander, G., Palombini, F., 1970 and C. Amsuess, "Controlling Actuators with CoAP", draft- 1971 mattsson-core-coap-actuators-03 (work in progress), 1972 October 2017. 1974 [I-D.seitz-ace-oscoap-profile] 1975 Seitz, L., Palombini, F., and M. Gunnarsson, "OSCORE 1976 profile of the Authentication and Authorization for 1977 Constrained Environments Framework", draft-seitz-ace- 1978 oscoap-profile-06 (work in progress), October 2017. 1980 [I-D.tiloca-core-multicast-oscoap] 1981 Tiloca, M., Selander, G., Palombini, F., and J. Park, 1982 "Secure group communication for CoAP", draft-tiloca-core- 1983 multicast-oscoap-04 (work in progress), October 2017. 1985 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1986 Resource Identifier (URI): Generic Syntax", STD 66, 1987 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1988 . 1990 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 1991 Key Derivation Function (HKDF)", RFC 5869, 1992 DOI 10.17487/RFC5869, May 2010, 1993 . 1995 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 1996 Constrained-Node Networks", RFC 7228, 1997 DOI 10.17487/RFC7228, May 2014, 1998 . 2000 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 2001 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 2002 2015, . 2004 Appendix A. Test Vectors 2006 TODO: This section needs to be updated. 2008 Appendix B. Examples 2010 This section gives examples of OSCORE. The message exchanges are 2011 made, based on the assumption that there is a security context 2012 established between client and server. For simplicity, these 2013 examples only indicate the content of the messages without going into 2014 detail of the (compressed) COSE message format. 2016 B.1. Secure Access to Sensor 2018 This example targets the scenario in Section 3.1 of 2019 [I-D.hartke-core-e2e-security-reqs] and illustrates a client 2020 requesting the alarm status from a server. 2022 Client Proxy Server 2023 | | | 2024 +------>| | Code: 0.02 (POST) 2025 | POST | | Token: 0x8c 2026 | | | Object-Security: [kid:5f,Partial IV:42] 2027 | | | Payload: {Code:0.01, 2028 | | | Uri-Path:"alarm_status"} 2029 | | | 2030 | +------>| Code: 0.02 (POST) 2031 | | POST | Token: 0x7b 2032 | | | Object-Security: [kid:5f,Partial IV:42] 2033 | | | Payload: {Code:0.01, 2034 | | | Uri-Path:"alarm_status"} 2035 | | | 2036 | |<------+ Code: 2.04 (Changed) 2037 | | 2.04 | Token: 0x7b 2038 | | | Object-Security: - 2039 | | | Payload: {Code:2.05, "OFF"} 2040 | | | 2041 |<------+ | Code: 2.04 (Changed) 2042 | 2.04 | | Token: 0x8c 2043 | | | Object-Security: - 2044 | | | Payload: {Code:2.05, "OFF"} 2045 | | | 2047 Figure 11: Secure Access to Sensor. Square brackets [ ... ] indicate 2048 content of compressed COSE object. Curly brackets { ... } indicate 2049 encrypted data. 2051 The request/response Codes are encrypted by OSCORE and only dummy 2052 Codes (POST/Changed) are visible in the header of the OSCORE message. 2053 The option Uri-Path ("alarm_status") and payload ("OFF") are 2054 encrypted. 2056 The COSE header of the request contains an identifier (5f), 2057 indicating which security context was used to protect the message and 2058 a Partial IV (42). 2060 The server verifies that the Partial IV has not been received before. 2061 The client verifies that the response is bound to the request. 2063 B.2. Secure Subscribe to Sensor 2065 This example targets the scenario in Section 3.2 of 2066 [I-D.hartke-core-e2e-security-reqs] and illustrates a client 2067 requesting subscription to a blood sugar measurement resource (GET 2068 /glucose), first receiving the value 220 mg/dl and then a second 2069 value 180 mg/dl. 2071 Client Proxy Server 2072 | | | 2073 +------>| | Code: 0.05 (FETCH) 2074 | FETCH | | Token: 0x83 2075 | | | Observe: 0 2076 | | | Object-Security: [kid:ca,Partial IV:15] 2077 | | | Payload: {Code:0.01, 2078 | | | Uri-Path:"glucose"} 2079 | | | 2080 | +------>| Code: 0.05 (FETCH) 2081 | | FETCH | Token: 0xbe 2082 | | | Observe: 0 2083 | | | Object-Security: [kid:ca,Partial IV:15] 2084 | | | Payload: {Code:0.01, 2085 | | | Uri-Path:"glucose"} 2086 | | | 2087 | |<------+ Code: 2.04 (Changed) 2088 | | 2.04 | Token: 0xbe 2089 | | | Observe: 7 2090 | | | Object-Security: [Partial IV:32] 2091 | | | Payload: {Code:2.05, 2092 | | | Content-Format:0, "220"} 2093 | | | 2094 |<------+ | Code: 2.04 (Changed) 2095 | 2.04 | | Token: 0x83 2096 | | | Observe: 7 2097 | | | Object-Security: [Partial IV:32] 2098 | | | Payload: {Code:2.05, 2099 | | | Content-Format:0, "220"} 2100 ... ... ... 2101 | | | 2102 | |<------+ Code: 2.04 (Changed) 2103 | | 2.04 | Token: 0xbe 2104 | | | Observe: 8 2105 | | | Object-Security: [Partial IV:36] 2106 | | | Payload: {Code:2.05, 2107 | | | Content-Format:0, "180"} 2108 | | | 2109 |<------+ | Code: 2.04 (Changed) 2110 | 2.04 | | Token: 0x83 2111 | | | Observe: 8 2112 | | | Object-Security: [Partial IV:36] 2113 | | | Payload: {Code:2.05, 2114 | | | Content-Format:0, "180"} 2115 | | | 2117 Figure 12: Secure Subscribe to Sensor. Square brackets [ ... ] 2118 indicate content of compressed COSE header. Curly brackets { ... } 2119 indicate encrypted data. 2121 The request/response Codes are encrypted by OSCORE and only dummy 2122 Codes (FETCH/Changed) are visible in the header of the OSCORE 2123 message. The options Content-Format (0) and the payload ("220" and 2124 "180"), are encrypted. 2126 The COSE header of the request contains an identifier (ca), 2127 indicating the security context used to protect the message and a 2128 Partial IV (15). The COSE headers of the responses contains Partial 2129 IVs (32 and 36). 2131 The server verifies that the Partial IV has not been received before. 2132 The client verifies that the responses are bound to the request and 2133 that the Partial IVs are greater than any Partial IV previously 2134 received in a response bound to the request. 2136 Authors' Addresses 2138 Goeran Selander 2139 Ericsson AB 2141 Email: goran.selander@ericsson.com 2143 John Mattsson 2144 Ericsson AB 2146 Email: john.mattsson@ericsson.com 2148 Francesca Palombini 2149 Ericsson AB 2151 Email: francesca.palombini@ericsson.com 2153 Ludwig Seitz 2154 SICS Swedish ICT 2156 Email: ludwig@sics.se