idnits 2.17.1 draft-ietf-core-object-security-05.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 (September 29, 2017) is 2400 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 5988 (Obsoleted by RFC 8288) ** 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 (-46) exists of draft-ietf-ace-oauth-authz-07 == Outdated reference: A later version (-11) exists of draft-ietf-core-coap-tcp-tls-09 == Outdated reference: A later version (-06) exists of draft-mattsson-core-coap-actuators-02 == Outdated reference: A later version (-06) exists of draft-seitz-ace-oscoap-profile-04 == Outdated reference: A later version (-04) exists of draft-tiloca-core-multicast-oscoap-03 Summary: 4 errors (**), 0 flaws (~~), 6 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: April 2, 2018 Ericsson AB 6 L. Seitz 7 SICS Swedish ICT 8 September 29, 2017 10 Object Security for Constrained RESTful Environments (OSCORE) 11 draft-ietf-core-object-security-05 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 over any layer and across intermediaries, 22 and also with HTTP. OSCORE may be used to protect group 23 communications as is 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 April 2, 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 . . . . . . 8 65 3.3. Requirements on the Security Context Parameters . . . . . 10 66 4. Protected Message Fields . . . . . . . . . . . . . . . . . . 11 67 4.1. CoAP Payload . . . . . . . . . . . . . . . . . . . . . . 12 68 4.2. CoAP Options . . . . . . . . . . . . . . . . . . . . . . 12 69 4.3. CoAP Header . . . . . . . . . . . . . . . . . . . . . . . 18 70 5. The COSE Object . . . . . . . . . . . . . . . . . . . . . . . 19 71 5.1. Nonce . . . . . . . . . . . . . . . . . . . . . . . . . . 20 72 5.2. Plaintext . . . . . . . . . . . . . . . . . . . . . . . . 20 73 5.3. Additional Authenticated Data . . . . . . . . . . . . . . 21 74 6. Sequence Numbers, Replay, Message Binding, and Freshness . . 22 75 6.1. Message Binding . . . . . . . . . . . . . . . . . . . . . 22 76 6.2. AEAD Nonce Uniqueness . . . . . . . . . . . . . . . . . . 22 77 6.3. Freshness . . . . . . . . . . . . . . . . . . . . . . . . 22 78 6.4. Replay Protection . . . . . . . . . . . . . . . . . . . . 23 79 6.5. Losing Part of the Context State . . . . . . . . . . . . 23 80 7. Processing . . . . . . . . . . . . . . . . . . . . . . . . . 24 81 7.1. Protecting the Request . . . . . . . . . . . . . . . . . 24 82 7.2. Verifying the Request . . . . . . . . . . . . . . . . . . 25 83 7.3. Protecting the Response . . . . . . . . . . . . . . . . . 26 84 7.4. Verifying the Response . . . . . . . . . . . . . . . . . 27 85 8. OSCORE Compression . . . . . . . . . . . . . . . . . . . . . 28 86 8.1. Encoding of the Object-Security Value . . . . . . . . . . 28 87 8.2. Encoding of the OSCORE Payload . . . . . . . . . . . . . 29 88 8.3. Context Hint . . . . . . . . . . . . . . . . . . . . . . 30 89 8.4. Compression Examples . . . . . . . . . . . . . . . . . . 30 90 9. Web Linking . . . . . . . . . . . . . . . . . . . . . . . . . 32 91 10. Proxy Operations . . . . . . . . . . . . . . . . . . . . . . 32 92 10.1. CoAP-to-CoAP Forwarding Proxy . . . . . . . . . . . . . 33 93 10.2. HTTP-to-CoAP Translation Proxy . . . . . . . . . . . . . 33 94 10.3. CoAP-to-HTTP Translation Proxy . . . . . . . . . . . . . 34 95 11. Security Considerations . . . . . . . . . . . . . . . . . . . 35 96 12. Privacy Considerations . . . . . . . . . . . . . . . . . . . 37 97 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 38 98 13.1. CoAP Option Numbers Registry . . . . . . . . . . . . . . 38 99 13.2. Header Field Registrations . . . . . . . . . . . . . . . 38 100 14. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 38 101 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 38 102 15.1. Normative References . . . . . . . . . . . . . . . . . . 38 103 15.2. Informative References . . . . . . . . . . . . . . . . . 40 104 Appendix A. Test Vectors . . . . . . . . . . . . . . . . . . . . 41 105 Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 41 106 B.1. Secure Access to Sensor . . . . . . . . . . . . . . . . . 41 107 B.2. Secure Subscribe to Sensor . . . . . . . . . . . . . . . 42 108 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 44 110 1. Introduction 112 The Constrained Application Protocol (CoAP) is a web application 113 protocol, designed for constrained nodes and networks [RFC7228]. 114 CoAP specifies the use of proxies for scalability and efficiency, and 115 a mapping to HTTP is also specified [RFC8075]. CoAP [RFC7252] 116 references DTLS [RFC6347] for security. CoAP and HTTP proxies 117 require (D)TLS to be terminated at the proxy. The proxy therefore 118 not only has access to the data required for performing the intended 119 proxy functionality, but is also able to eavesdrop on, or manipulate 120 any part of the message payload and metadata, in transit between the 121 endpoints. The proxy can also inject, delete, or reorder packets 122 since they are no longer protected by (D)TLS. 124 This document defines the Object Security for Constrained RESTful 125 Environments (OSCORE) security protocol, protecting CoAP and CoAP- 126 mappable HTTP requests and responses end-to-end across intermediary 127 nodes such as CoAP forward proxies and cross-protocol translators 128 including HTTP-to-CoAP proxies [RFC8075]. In addition to the core 129 CoAP features defined in [RFC7252], OSCORE supports Observe [RFC7641] 130 and Blockwise [RFC7959]. An analysis of end-to-end security for CoAP 131 messages through some types of intermediary nodes is performed in 132 [I-D.hartke-core-e2e-security-reqs]. OSCORE protects the Request/ 133 Response layer only, and not the CoAP Messaging Layer (Section 2 of 134 [RFC7252]). Therefore, all the CoAP messages mentioned in this 135 document refer to non-empty CON, NON, and ACK messages. 136 Additionally, since the message formats for CoAP over unreliable 137 transport [RFC7252] and for CoAP over reliable transport 138 [I-D.ietf-core-coap-tcp-tls] differ only in terms of Messaging Layer, 139 OSCORE can be applied to both unreliable and reliable transports. 141 OSCORE is designed for constrained nodes and networks and provides an 142 in-layer security protocol that does not depend on underlying layers. 143 OSCORE can be used anywhere where CoAP or HTTP can be used, including 144 non-IP transports (e.g., [I-D.bormann-6lo-coap-802-15-ie]). An 145 extension of OSCORE may also be used to protect group communication 146 for CoAP [I-D.tiloca-core-multicast-oscoap]. The use of OSCORE does 147 not affect the URI scheme and OSCORE can therefore be used with any 148 URI scheme defined for CoAP or HTTP. The application decides the 149 conditions for which OSCORE is required. 151 OSCORE builds on CBOR Object Signing and Encryption (COSE) [RFC8152], 152 providing end-to-end encryption, integrity, replay protection, and 153 secure message binding. A compressed version of COSE is used, as 154 discussed in Section 8. The use of OSCORE is signaled with the 155 Object-Security CoAP option or HTTP header, defined in Section 2 and 156 Section 10.2. OSCORE is designed to protect as much information as 157 possible, while still allowing proxy operations (Section 10). OSCORE 158 provides protection of message payload, almost all CoAP options, and 159 the RESTful method. The solution transforms a message into an 160 "OSCORE message" before sending, and vice versa after receiving. The 161 OSCORE message is related to the original message in the following 162 way: the original message is translated to CoAP (if not already in 163 CoAP) and the resulting message payload (if present), options not 164 processed by a proxy, and the request/response method (CoAP Code) are 165 protected in a COSE object. The message fields of the original 166 messages that are encrypted are not present in the OSCORE message, 167 and instead the Object-Security option/header and the compressed COSE 168 object are included, see Figure 1. 170 Client Server 171 | OSCORE request - POST example.com: | 172 | Header, Token, | 173 | Options: {Object-Security, ...}, | 174 | Payload: Compressed COSE object | 175 +--------------------------------------------->| 176 | OSCORE response - 2.04 (Changed): | 177 | Header, Token, | 178 | Options: {Object-Security, ...}, | 179 | Payload: Compressed COSE object | 180 |<---------------------------------------------+ 181 | | 183 Figure 1: Sketch of OSCORE with CoAP 185 OSCORE may be used in very constrained settings, thanks to its small 186 message size and the restricted code and memory requirements in 187 addition to what is required by CoAP. OSCORE can be combined with 188 transport layer security such as DTLS or TLS, thereby enabling end- 189 to-end security of e.g. CoAP Payload, Options and Code, in 190 combination with hop-by-hop protection of the Messaging Layer, during 191 transport between end-point and intermediary node. Examples of the 192 use of OSCORE are given in Appendix B. 194 An implementation supporting this specification MAY only implement 195 the client part, MAY only implement the server part, or MAY only 196 implement one of the proxy parts. OSCORE is designed to work with 197 legacy CoAP-to-CoAP forward proxies [RFC7252], but an OSCORE-aware 198 proxy will be more efficient. HTTP-to-CoAP proxies [RFC8075] and 199 CoAP-to-HTTP proxies need to implement respective parts of this 200 specification to work with OSCORE (see Section 10). 202 1.1. Terminology 204 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 205 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 206 document are to be interpreted as described in [RFC2119]. These 207 words may also appear in this document in lowercase, absent their 208 normative meanings. 210 Readers are expected to be familiar with the terms and concepts 211 described in CoAP [RFC7252], Observe [RFC7641], Blockwise [RFC7959], 212 COSE [RFC8152], CBOR [RFC7049], CDDL 213 [I-D.greevenbosch-appsawg-cbor-cddl], and constrained environments 214 [RFC7228]. 216 The terms Common/Sender/Recipient Context, Master Secret/Salt, Sender 217 ID/Key, Recipient ID/Key, and Common IV are defined in Section 3.1. 219 2. The CoAP Object-Security Option 221 The CoAP Object-Security option (see Figure 2) indicates that the 222 CoAP message is an OSCORE message and that it contains a compressed 223 COSE object (see Section 5 and Section 8). The Object-Security 224 option is critical, safe to forward, part of the cache key, and not 225 repeatable. 227 +-----+---+---+---+---+-----------------+-----------+--------+---------+ 228 | No. | C | U | N | R | Name | Format | Length | Default | 229 +-----+---+---+---+---+-----------------+-----------+--------+---------+ 230 | TBD | x | | | | Object-Security | see below | 0-255 | (none) | 231 +-----+---+---+---+---+-----------------+-----------+--------+---------+ 232 C = Critical, U = Unsafe, N = NoCacheKey, R = Repeatable 234 Figure 2: The Object-Security Option 236 The Object-Security option contains the OSCORE flag byte and for 237 requests, the Sender ID (see Section 8). If the flag byte is all 238 zero (0x00) the Option value SHALL be empty (Option Length = 0). An 239 endpoint receiving a CoAP message without payload, that also contains 240 an Object-Security option SHALL treat it as malformed and reject it. 242 A successful response to a request with the Object-Security option 243 SHALL contain the Object-Security option. Whether error responses 244 contain the Object-Security option depends on the error type (see 245 Section 7). 247 Since the payload and most options are encrypted Section 4, and the 248 corresponding plain text message fields of the original are not 249 included in the OSCORE message, the processing of these fields does 250 not expand the total message size. 252 A CoAP proxy SHOULD NOT cache a response to a request with an Object- 253 Security option, since the response is only applicable to the 254 original client's request, see Section 10.1. As the compressed COSE 255 Object is included in the cache key, messages with the Object- 256 Security option will never generate cache hits. For Max-Age 257 processing, see Section 4.2.3.1. 259 3. The Security Context 261 OSCORE requires that client and server establish a shared security 262 context used to process the COSE objects. OSCORE uses COSE with an 263 Authenticated Encryption with Additional Data (AEAD) algorithm for 264 protecting message data between a client and a server. In this 265 section, we define the security context and how it is derived in 266 client and server based on a common shared master secret and a key 267 derivation function (KDF). 269 3.1. Security Context Definition 271 The security context is the set of information elements necessary to 272 carry out the cryptographic operations in OSCORE. For each endpoint, 273 the security context is composed of a "Common Context", a "Sender 274 Context", and a "Recipient Context". 276 The endpoints protect messages to send using the Sender Context and 277 verify messages received using the Recipient Context, both contexts 278 being derived from the Common Context and other data. Clients and 279 Servers need to be able to retrieve the correct security context to 280 use. 282 An endpoint uses its Sender ID (SID) to derive its Sender Context, 283 and the other endpoint uses the same ID, now called Recipient ID 284 (RID), to derive its Recipient Context. In communication between two 285 endpoints, the Sender Context of one endpoint matches the Recipient 286 Context of the other endpoint, and vice versa. Thus, the two 287 security contexts identified by the same IDs in the two endpoints are 288 not the same, but they are partly mirrored. Retrieval and use of the 289 security context are shown in Figure 3. 291 .-------------. .-------------. 292 | Common, | | Common, | 293 | Sender, | | Recipient, | 294 | Recipient | | Sender | 295 '-------------' '-------------' 296 Client Server 297 | | 298 Retrieve context for | OSCORE request: | 299 target resource | Token = Token1, | 300 Protect request with | kid = SID, ... | 301 Sender Context +---------------------->| Retrieve context with 302 | | RID = kid 303 | | Verify request with 304 | | Recipient Context 305 | OSCORE response: | Protect response with 306 | Token = Token1, ... | Sender Context 307 Retrieve context with |<----------------------+ 308 Token = Token1 | | 309 Verify request with | | 310 Recipient Context | | 312 Figure 3: Retrieval and use of the Security Context 314 The Common Context contains the following parameters: 316 o AEAD Algorithm (alg). The COSE AEAD algorithm to use for 317 encryption. Its value is immutable once the security context is 318 established. 320 o Key Derivation Function. The HMAC based HKDF [RFC5869] used to 321 derive Sender Key, Recipient Key, and Common IV. 323 o Master Secret. Variable length, uniformly random byte string 324 containing the key used to derive traffic keys and IVs. Its value 325 is immutable once the security context is established. 327 o Master Salt (OPTIONAL). Variable length byte string containing 328 the salt used to derive traffic keys and IVs. Its value is 329 immutable once the security context is established. 331 o Common IV. Byte string derived from Master Secret and Master 332 Salt. Length is determined by the AEAD Algorithm. Its value is 333 immutable once the security context is established. 335 The Sender Context contains the following parameters: 337 o Sender ID. Non-negative integer used to identify the Sender 338 Context and to assure unique nonces. Length is determined by the 339 AEAD Algorithm. Its value is immutable once the security context 340 is established. 342 o Sender Key. Byte string containing the symmetric key to protect 343 messages to send. Derived from Common Context and Sender ID. 344 Length is determined by the AEAD Algorithm. Its value is 345 immutable once the security context is established. 347 o Sender Sequence Number. Non-negative integer used by the sender 348 to protect requests and Observe notifications. Used as "Partial 349 IV" [RFC8152] to generate unique nonces for the AEAD. Maximum 350 value is determined by the AEAD Algorithm. 352 The Recipient Context contains the following parameters: 354 o Recipient ID. Non-negative integer used to identify the Recipient 355 Context and to assure unique nonces. Length is determined by the 356 AEAD Algorithm. Its value is immutable once the security context 357 is established. 359 o Recipient Key. Byte string containing the symmetric key to verify 360 messages received. Derived from Common Context and Recipient ID. 361 Length is determined by the AEAD Algorithm. Its value is 362 immutable once the security context is established. 364 o Replay Window (Server only). The replay window to verify requests 365 received. 367 An endpoint may free up memory by not storing the Common IV, Sender 368 Key, and Recipient Key, deriving them from the Master Key and Master 369 Salt when needed. Alternatively, an endpoint may free up memory by 370 not storing the Master Secret and Master Salt after the other 371 parameters have been derived. 373 The endpoints MAY interchange the client and server roles while 374 maintaining the same security context. When this happens, the former 375 server still protects messages to send using its Sender Context, and 376 verifies messages received using its Recipient Context. The same is 377 also true for the former client. The endpoints MUST NOT change the 378 Sender/Recipient ID when changing roles. In other words, changing 379 the roles does not change the set of keys to be used. 381 3.2. Establishment of Security Context Parameters 383 The parameters in the security context are derived from a small set 384 of input parameters. The following input parameters SHALL be pre- 385 established: 387 o Master Secret 389 o Sender ID 391 o Recipient ID 393 The following input parameters MAY be pre-established. In case any 394 of these parameters is not pre-established, the default value 395 indicated below is used: 397 o AEAD Algorithm (alg) 399 * Default is AES-CCM-16-64-128 (COSE algorithm encoding: 10) 401 o Master Salt 403 * Default is the empty string 405 o Key Derivation Function (KDF) 407 * Default is HKDF SHA-256 409 o Replay Window Type and Size 411 * Default is DTLS-type replay protection with a window size of 32 412 ([RFC6347]) 414 All input parameters need to be known to and agreed on by both 415 endpoints, but the replay window may be different in the two 416 endpoints. The replay window type and size is used by the client in 417 the processing of the Request-Tag 418 [I-D.amsuess-core-repeat-request-tag]. How the input parameters are 419 pre-established, is application specific. The ACE framework may be 420 used to establish the necessary input parameters 421 [I-D.ietf-ace-oauth-authz]. 423 3.2.1. Derivation of Sender Key, Recipient Key, and Common IV 425 The KDF MUST be one of the HMAC based HKDF [RFC5869] algorithms 426 defined in COSE. HKDF SHA-256 is mandatory to implement. The 427 security context parameters Sender Key, Recipient Key, and Common IV 428 SHALL be derived from the input parameters using the HKDF, which 429 consists of the composition of the HKDF-Extract and HKDF-Expand steps 430 ([RFC5869]): 432 output parameter = HKDF(salt, IKM, info, L) 434 where: 436 o salt is the Master Salt as defined above 438 o IKM is the Master Secret is defined above 440 o info is a CBOR array consisting of: 442 info = [ 443 id : bstr / nil, 444 alg : int, 445 type : tstr, 446 L : uint 447 ] 449 where: 451 o id is the Sender ID or Recipient ID when deriving keys and nil 452 when deriving the Common IV. Sender ID and Recipient ID are 453 encoded as described in Section 5 455 o type is "Key" or "IV" 457 o L is the size of the key/IV for the AEAD algorithm used, in octets 459 For example, if the algorithm AES-CCM-16-64-128 (see Section 10.2 in 460 [RFC8152]) is used, the value for L is 16 for keys and 13 for the 461 Common IV. 463 3.2.2. Initial Sequence Numbers and Replay Window 465 The Sender Sequence Number is initialized to 0. The supported types 466 of replay protection and replay window length is application specific 467 and depends on the lower layers. The default is DTLS-type replay 468 protection with a window size of 32 initiated as described in 469 Section 4.1.2.6 of [RFC6347]. 471 3.3. Requirements on the Security Context Parameters 473 As collisions may lead to the loss of both confidentiality and 474 integrity, Sender ID SHALL be unique in the set of all security 475 contexts using the same Master Secret and Master Salt. When a 476 trusted third party assigns identifiers (e.g., using 477 [I-D.ietf-ace-oauth-authz]) or by using a protocol that allows the 478 parties to negotiate locally unique identifiers in each endpoint, the 479 Sender IDs can be very short. The maximum Sender ID is 2^(nonce 480 length in bits - 40) - 1, For AES-CCM-16-64-128 the maximum Sender ID 481 is 2^64 - 1. If Sender ID uniqueness cannot be guaranteed, random 482 Sender IDs MUST be used. Random Sender IDs MUST be long enough so 483 that the probability of collisions is negligible. 485 To enable retrieval of the right Recipient Context, the Recipient ID 486 SHOULD be unique in the sets of all Recipient Contexts used by an 487 endpoint. The Client MAY provide a Context Hint Section 8.3 to help 488 the Server find the right context. 490 While the triple (Master Secret, Master Salt, Sender ID) MUST be 491 unique, the same Master Salt MAY be used with several Master Secrets 492 and the same Master Secret MAY be used with several Master Salts. 494 4. Protected Message Fields 496 OSCORE transforms a CoAP message (which may have been generated from 497 an HTTP message) into an OSCORE message, and vice versa. OSCORE 498 protects as much of the original message as possible while still 499 allowing certain proxy operations (see Section 10). This section 500 defines how OSCORE protects the message fields and transfers them 501 end-to-end between client and server (in any direction). 503 The remainder of this section and later sections discuss the behavior 504 in terms of CoAP messages. If HTTP is used for a particular leg in 505 the end-to-end path, then this section applies to the conceptual CoAP 506 message that is mappable to/from the original HTTP message as 507 discussed in Section 10. That is, an HTTP message is conceptually 508 transformed to a CoAP message and then to an OSCORE message, and 509 similarly in the reverse direction. An actual implementation might 510 translate directly from HTTP to OSCORE without the intervening CoAP 511 representation. 513 Message fields of the CoAP message may be protected end-to-end 514 between CoAP client and CoAP server in different ways: 516 o Class E: encrypted and integrity protected, 518 o Class I: integrity protected only, or 520 o Class U: unprotected. 522 The sending endpoint SHALL transfer Class E message fields in the 523 ciphertext of the COSE object in the OSCORE message. The sending 524 endpoint SHALL include Class I message fields in the Additional 525 Authenticated Data (AAD) of the AEAD algorithm, allowing the 526 receiving endpoint to detect if the value has changed in transfer. 527 Class U message fields SHALL NOT be protected in transfer. Class I 528 and Class U message field values are transferred in the header or 529 options part of the OSCORE message which is visible to proxies. 531 Message fields not visible to proxies, i.e., transported in the 532 ciphertext of the COSE object, are called "Inner" (Class E). Message 533 fields transferred in the header or options part of the OSCORE 534 message, which is visible to proxies, are called "Outer" (Class I or 535 U). 537 CoAP message fields are either Inner or Outer: Inner if the value is 538 intended for the destination endpoint, Outer if the value is intended 539 for a proxy. An OSCORE message may contain both an Inner and an 540 Outer message field of certain CoAP message fields. Inner and Outer 541 message fields are processed independently. 543 4.1. CoAP Payload 545 The CoAP Payload, if present in the original CoAP message, SHALL be 546 encrypted and integrity protected and is thus an Inner message field. 547 The sending endpoint writes the payload of the original CoAP message 548 into the plaintext (Section 5.2) input to the COSE object. The 549 receiving endpoint verifies and decrypts the COSE object, and 550 recreates the payload of the original CoAP message. 552 4.2. CoAP Options 554 A summary of how options are protected is shown in Figure 4. Options 555 which require special processing, in particular those which may have 556 both Inner and Outer message fields, are labelled with asterisks. 558 +----+----------------+---+---+---+ 559 | No.| Name | E | I | U | 560 +----+----------------+---+---+---+ 561 | 1 | If-Match | x | | | 562 | 3 | Uri-Host | | | x | 563 | 4 | ETag | x | | | 564 | 5 | If-None-Match | x | | | 565 | 6 | Observe | | | * | 566 | 7 | Uri-Port | | | x | 567 | 8 | Location-Path | x | | | 568 | 11 | Uri-Path | x | | | 569 | 12 | Content-Format | x | | | 570 | 14 | Max-Age | * | | * | 571 | 15 | Uri-Query | x | | | 572 | 17 | Accept | x | | | 573 | 20 | Location-Query | x | | | 574 | 23 | Block2 | * | | * | 575 | 27 | Block1 | * | | * | 576 | 28 | Size2 | * | | * | 577 | 35 | Proxy-Uri | * | | * | 578 | 39 | Proxy-Scheme | | | x | 579 | 60 | Size1 | * | | * | 580 +----+----------------+---+---+---+ 582 E = Encrypt and Integrity Protect (Inner) 583 I = Integrity Protect only (Outer) 584 U = Unprotected (Outer) 585 * = Special 587 Figure 4: Protection of CoAP Options 589 Unknown CoAP options SHALL be processed as class E (and no special 590 processing). Specifications of new CoAP options SHOULD define how 591 they are processed with OSCORE. A new COAP option SHOULD be of class 592 E unless it requires proxy processing. 594 4.2.1. Inner Options 596 When using OSCORE, Inner option message fields (marked in column E of 597 Figure 4) are sent in a way analogous to communicating in a protected 598 manner directly with the other endpoint. 600 The sending endpoint SHALL write the Inner option message fields 601 present in the original CoAP message into the plaintext of the COSE 602 object Section 5.2, and then remove the Inner option message fields 603 from the OSCORE message. 605 The processing of Inner option message fields by the receiving 606 endpoint is specified in Section 7.2 and Section 7.4. 608 4.2.2. Outer Options 610 Outer option message fields (marked in column U or I of Figure 4) are 611 used to support proxy operations. 613 The sending endpoint SHALL include the Outer option message field 614 present in the original message in the options part of the OSCORE 615 message. All Outer option message fields, including Object-Security, 616 SHALL be encoded as described in Section 3.1 of [RFC7252], where the 617 delta is the difference to the previously included Outer option 618 message field. 620 The processing of Outer options by the receiving endpoint is 621 specified in Section 7.2 and Section 7.4. 623 A procedure for integrity-protection-only of Class I option message 624 fields is specified in Section 5.3. 626 Note: There are currently no Class I option message fields defined. 628 4.2.3. Special Options 630 Some options require special processing, marked with an asterisk '*' 631 in Figure 4. An asterisk in the columns E and U indicate that the 632 option may be added as an Inner and/or Outer message by the sending 633 endpoint; the processing is specified in this section. 635 4.2.3.1. Max-Age 637 The Inner Max-Age option is used to specify the freshness (as defined 638 in [RFC7252]) of the resource, end-to-end from the server to the 639 client, taking into account that the option is not accessible to 640 proxies. The Inner Max-Age SHALL be processed by OSCORE as specified 641 in Section 4.2.1. 643 The Outer Max-Age option is used to avoid unnecessary caching of 644 OSCORE responses at OSCORE unaware intermediary nodes. A server MAY 645 set a Class U Max-Age option with value zero to Observe responses 646 (see Section 5.6.1 of [RFC7252]) which is then processed according to 647 Section 4.2.2. The Outer Max-Age option value SHALL be discarded by 648 the OSCORE client. 650 Non-Observe OSCORE responses do not need to include a Max-Age option 651 since the responses are non-cacheable by construction (see 652 Section 4.3). 654 4.2.3.2. The Block Options 656 Blockwise [RFC7959] is an optional feature. An implementation MAY 657 support [RFC7252] and the Object-Security option without supporting 658 [RFC7959]. The Block options are used to secure message 659 fragmentation end-to-end (Inner options) or for proxies to fragment 660 the OSCORE message for the next hop (Outer options). Inner and Outer 661 block processing may have different performance properties depending 662 on the underlying transport. The integrity of the message can be 663 verified end-to-end both in case of Inner and Outer Blockwise 664 provided all blocks are received (see Section 4.2.3.2.2). 666 4.2.3.2.1. Inner Block Options 668 The sending CoAP endpoint MAY fragment a CoAP message as defined in 669 [RFC7959] before the message is processed by OSCORE. In this case 670 the Block options SHALL be processed by OSCORE as Inner options 671 (Section 4.2.1). The receiving CoAP endpoint SHALL process the 672 OSCORE message according to Section 4.2.1 before processing blockwise 673 as defined in [RFC7959]. 675 For blockwise request operations using Block1, an endpoint MUST 676 comply with the Request-Tag processing defined in Section 3 of 677 [I-D.amsuess-core-repeat-request-tag]. In particular, the rules in 678 section 3.3.1 of [I-D.amsuess-core-repeat-request-tag] MUST be 679 followed, which guarantee that a specific request body is assembled 680 only from the corresponding request blocks. 682 For blockwise response operations using Block2, an endpoint MUST 683 comply with the ETag processing defined in Section 4 of 684 [I-D.amsuess-core-repeat-request-tag]. 686 4.2.3.2.2. Outer Block Options 688 Proxies MAY fragment an OSCORE message using [RFC7959], which then 689 introduces Outer Block options not generated by the sending endpoint. 690 Note that the Outer Block options are neither encrypted nor integrity 691 protected. As a consequence, a proxy can maliciously inject block 692 fragments indefinitely, since the receiving endpoint needs to receive 693 the last block (see [RFC7959]) to be able to compose the OSCORE 694 message and verify its integrity. Therefore, applications supporting 695 OSCORE and [RFC7959] MUST specify a security policy defining a 696 maximum unfragmented message size (MAX_UNFRAGMENTED_SIZE) considering 697 the maximum size of message which can be handled by the endpoints. 698 Messages exceeding this size SHOULD be fragmented by the sending 699 endpoint using Inner Block options (Section 4.2.3.2.1). 701 An endpoint receiving an OSCORE message with an Outer Block option 702 SHALL first process this option according to [RFC7959], until all 703 blocks of the OSCORE message have been received, or the cumulated 704 message size of the blocks exceeds MAX_UNFRAGMENTED_SIZE. In the 705 former case, the processing of the OSCORE message continues as 706 defined in this document. In the latter case the message SHALL be 707 discarded. 709 To allow multiple concurrent request operations to the same server 710 (not only same resource), a CoAP proxy SHOULD follow the Request-Tag 711 processing specified in section 3.3.2 of 712 [I-D.amsuess-core-repeat-request-tag]. 714 4.2.3.3. Proxy-Uri 716 Proxy-Uri, when present, is split by OSCORE into class U options and 717 class E options, which are processed accordingly. When Proxy-Uri is 718 used in the original CoAP message, Uri-* are not present [RFC7252]. 720 The sending endpoint SHALL first decompose the Proxy-Uri value of the 721 original CoAP message into the Proxy-Scheme, Uri-Host, Uri-Port, Uri- 722 Path, and Uri-Query options (if present) according to section 6.4 of 723 [RFC7252]. 725 Uri-Path and Uri-Query are class E options and SHALL be protected and 726 processed as Inner options (Section 4.2.1). 728 The Proxy-Uri option of the OSCORE message SHALL be set to the 729 composition of Proxy-Scheme, Uri-Host and Uri-Port options (if 730 present) as specified in section 6.5 of [RFC7252], and processed as 731 an Outer option of Class U (Section 4.2.2). 733 Note that replacing the Proxy-Uri value with the Proxy-Scheme and 734 Uri-* options works by design for all CoAP URIs (see Section 6 of 735 [RFC7252]. OSCORE-aware HTTP servers should not use the userinfo 736 component of the HTTP URI (as defined in section 3.2.1. of 737 [RFC3986]), so that this type of replacement is possible in the 738 presence of CoAP-to-HTTP proxies. In other documents specifying 739 cross-protocol proxying behavior using different URI structures, it 740 is expected that the authors will create Uri-* options that allow 741 decomposing the Proxy-Uri, and specify in which OSCORE class they 742 belong. 744 An example of how Proxy-Uri is processed is given here. Assume that 745 the original CoAP message contains: 747 o Proxy-Uri = "coap://example.com/resource?q=1" 748 During OSCORE processing, Proxy-Uri is split into: 750 o Proxy-Scheme = "coap" 752 o Uri-Host = "example.com" 754 o Uri-Port = "5683" 756 o Uri-Path = "resource" 758 o Uri-Query = "q=1" 760 Uri-Path and Uri-Query follow the processing defined in 761 Section 4.2.1, and are thus encrypted and transported in the COSE 762 object. The remaining options are composed into the Proxy-Uri 763 included in the options part of the OSCORE message, which has value: 765 o Proxy-Uri = "coap://example.com" 767 See Section 6.1 and 12.6 of [RFC7252] for more information. 769 4.2.3.4. Observe 771 Observe [RFC7641] is an optional feature. An implementation MAY 772 support [RFC7252] and the Object-Security option without supporting 773 [RFC7641]. The Observe option as used here targets the requirements 774 on forwarding of [I-D.hartke-core-e2e-security-reqs] 775 (Section 2.2.1.2). 777 In order for an OSCORE-unaware proxy to support forwarding of Observe 778 messages ([RFC7641]), there SHALL be an Outer Observe option, i.e., 779 present in the options part of the OSCORE message. The processing of 780 the CoAP Code for Observe messages is described in Section 4.3. 782 To secure the order of notifications, the client SHALL maintain a 783 Notification Number for each Observation it registers. The 784 Notification Number is a non-negative integer containing the largest 785 Partial IV of the successfully received notifications for the 786 associated Observe registration, see Section 6.4. The Notification 787 Number is initialized to the Partial IV of the first successfully 788 received notification response to the registration request. In 789 contrast to [RFC7641], the received Partial IV MUST always be 790 compared with the Notification Number, which thus MUST NOT be 791 forgotten after 128 seconds. 793 If the verification fails, the client SHALL stop processing the 794 response, and in the case of CON respond with an empty ACK. The 795 client MAY ignore the Observe option value. 797 The Observe option in the CoAP request may be legitimately removed by 798 a proxy. If the Observe option is removed from a CoAP request by a 799 proxy, then the server can still verify the request (as a non-Observe 800 request), and produce a non-Observe response. If the OSCORE client 801 receives a response to an Observe request without an outer Observe 802 value, then it MUST verify the response as a non-Observe response. 803 (The reverse case is covered in the verification of the response, see 804 Section 7.) 806 4.3. CoAP Header 808 Most CoAP header fields are required to be read and/or changed by 809 CoAP proxies and thus cannot in general be protected end-to-end 810 between the endpoints. As mentioned in Section 1, OSCORE protects 811 the CoAP Request/Response layer only, and not the Messaging Layer 812 (Section 2 of [RFC7252]), so fields such as Type and Message ID are 813 not protected with OSCORE. 815 The CoAP header field Code is protected by OSCORE. Code SHALL be 816 encrypted and integrity protected (Class E) to prevent an 817 intermediary from eavesdropping or manipulating the Code (e.g., 818 changing from GET to DELETE). 820 The sending endpoint SHALL write the Code of the original CoAP 821 message into the plaintext of the COSE object Section 5.2. After 822 that, the Outer Code of the OSCORE message SHALL be set to 0.02 823 (POST) for requests and to 2.04 (Changed) for responses, except for 824 Observe messages. For Observe messages, the Outer Code of the OSCORE 825 message SHALL be set to 0.05 (FETCH) for requests and to 2.05 826 (Content) for responses. This exception allows OSCORE to be 827 compliant with the Observe processing in OSCORE-unaware proxies. The 828 choice of POST and FETCH ([RFC8132]) allows all OSCORE messages to 829 have payload. 831 The receiving endpoint SHALL discard the Code in the OSCORE message 832 and write the Code of the Plaintext in the COSE object (Section 5.2) 833 into the decrypted CoAP message. 835 The other CoAP header fields are Unprotected (Class U). The sending 836 endpoint SHALL write all other header fields of the original message 837 into the header of the OSCORE message. The receiving endpoint SHALL 838 write the header fields from the received OSCORE message into the 839 header of the decrypted CoAP message. 841 5. The COSE Object 843 This section defines how to use COSE [RFC8152] to wrap and protect 844 data in the original message. OSCORE uses the untagged COSE_Encrypt0 845 structure with an Authenticated Encryption with Additional Data 846 (AEAD) algorithm. The key lengths, IV length, nonce length, and 847 maximum Sender Sequence Number are algorithm dependent. 849 The AEAD algorithm AES-CCM-16-64-128 defined in Section 10.2 of 850 [RFC8152] is mandatory to implement. For AES-CCM-16-64-128 the 851 length of Sender Key and Recipient Key is 128 bits, the length of 852 nonce and Common IV is 13 bytes. The maximum Sender Sequence Number 853 is specified in Section 11. 855 We denote by Plaintext the data that is encrypted and integrity 856 protected, and by Additional Authenticated Data (AAD) the data that 857 is integrity protected only. 859 The COSE Object SHALL be a COSE_Encrypt0 object with fields defined 860 as follows 862 o The "protected" field is empty. 864 o The "unprotected" field includes: 866 * The "Partial IV" parameter. The value is set to the Sender 867 Sequence Number. All leading zeroes SHALL be removed when 868 encoding the Partial IV, i.e. the first byte (if any) SHALL 869 never be zero. This parameter SHALL be present in requests. 870 In case of Observe (Section 4.2.3.4) the Partial IV SHALL be 871 present in responses, and otherwise the Partial IV SHALL NOT be 872 present in responses. 874 * The "kid" parameter. The value is set to the Sender ID (see 875 Section 3). All leading zeroes SHALL be removed when encoding 876 the Partial IV, i.e. the first byte (if any) SHALL never be 877 zero. This parameter SHALL be present in requests and SHALL 878 NOT be present in responses. 880 o The "ciphertext" field is computed from the secret key (Sender Key 881 or Recipient Key), Nonce (see Section 5.1), Plaintext (see 882 Section 5.2), and the Additional Authenticated Data (AAD) (see 883 Section 5.3) following Section 5.2 of [RFC8152]. 885 The encryption process is described in Section 5.3 of [RFC8152]. 887 5.1. Nonce 889 The nonce is constructed by left-padding the Partial IV (in network 890 byte order) with zeroes to exactly 5 bytes, left-padding the Sender 891 ID of the endpoint that generated the Partial IV (in network byte 892 order) with zeroes to exactly nonce length - 5 bytes, concatenating 893 the padded Partial IV with the padded ID, and then XORing with the 894 Common IV. 896 When observe is not used, the request and the response uses the same 897 nonce. In this way, the Partial IV does not have to be sent in 898 responses, which reduces the size. For processing instructions, see 899 Section 7. 901 +--------------------------+--+--+--+--+--+ 902 | ID of PIV generator | Partial IV |---+ 903 +--------------------------+--+--+--+--+--+ | 904 | 905 +-----------------------------------------+ | 906 | Common IV |->(+) 907 +-----------------------------------------+ | 908 | 909 +-----------------------------------------+ | 910 | Nonce |<--+ 911 +-----------------------------------------+ 913 Figure 5: AEAD Nonce Formation 915 5.2. Plaintext 917 The Plaintext is formatted as a CoAP message without Header (see 918 Figure 6) consisting of: 920 o the Code of the original CoAP message as defined in Section 3 of 921 [RFC7252]; and 923 o all Inner option message fields (see Section 4.2.1) present in the 924 original CoAP message (see Section 4.2). The options are encoded 925 as described in Section 3.1 of [RFC7252], where the delta is the 926 difference to the previously included Class E option; and 928 o the Payload of original CoAP message, if present, and in that case 929 prefixed by the one-byte Payload Marker (0xFF). 931 0 1 2 3 932 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 933 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 934 | Code | Class E options (if any) ... 935 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 936 |1 1 1 1 1 1 1 1| Payload (if any) ... 937 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 938 (only if there 939 is payload) 941 Figure 6: Plaintext 943 5.3. Additional Authenticated Data 945 The external_aad SHALL be a CBOR array as defined below: 947 external_aad = [ 948 version : uint, 949 alg : int, 950 request_kid : bstr, 951 request_piv : bstr, 952 options : bstr 953 ] 955 where: 957 o version: contains the OSCORE version number. Implementations of 958 this specification MUST set this field to 1. Other values are 959 reserved for future versions. 961 o alg: contains the AEAD Algorithm from the security context used 962 for the exchange (see Section 3.1). 964 o request_kid: contains the value of the 'kid' in the COSE object of 965 the request (see Section 5). 967 o request_piv: contains the value of the 'Partial IV' in the COSE 968 object of the request (see Section 5). 970 o options: contains the (non-special) Class I options (see 971 Section 4.2.2) present in the original CoAP message encoded as 972 described in Section 3.1 of [RFC7252], where the delta is the 973 difference to the previously included class I option. 975 6. Sequence Numbers, Replay, Message Binding, and Freshness 977 6.1. Message Binding 979 In order to prevent response delay and mismatch attacks 980 [I-D.mattsson-core-coap-actuators] from on-path attackers and 981 compromised proxies, OSCORE binds responses to the request by 982 including the request's ID (Sender ID or Recipient ID) and Partial IV 983 in the AAD of the response. The server therefore needs to store the 984 request's ID (Sender ID or Recipient ID) and Partial IV until all 985 responses have been sent. 987 6.2. AEAD Nonce Uniqueness 989 An AEAD nonce MUST NOT be used more than once per AEAD key. In order 990 to assure unique nonces, each Sender Context contains a Sender 991 Sequence Number used to protect requests, and - in case of Observe - 992 responses. If messages are processed concurrently, the operation of 993 reading and increasing the Sender Sequence Number MUST be atomic. 995 The maximum Sender Sequence Number is algorithm dependent, see 996 Section 11. If the Sender Sequence Number exceeds the maximum, the 997 endpoint MUST NOT process any more messages with the given Sender 998 Context. The endpoint SHOULD acquire a new security context (and 999 consequently inform the other endpoint) before this happens. The 1000 latter is out of scope of this document. 1002 6.3. Freshness 1004 For requests, OSCORE provides weak absolute freshness as the only 1005 guarantee is that the request is not older than the security context. 1006 For applications having stronger demands on request freshness (e.g., 1007 control of actuators), OSCORE needs to be augmented with mechanisms 1008 providing freshness [I-D.amsuess-core-repeat-request-tag]. 1010 For responses, the message binding guarantees that a response is not 1011 older than its request. For responses without Observe, this gives 1012 strong absolute freshness. For responses with Observe, the absolute 1013 freshness gets weaker with time, and it is RECOMMENDED that the 1014 client regularly restart the observation. 1016 For requests, and responses with Observe, OSCORE also provides 1017 relative freshness in the sense that the received Partial IV allows a 1018 recipient to determine the relative order of responses. 1020 6.4. Replay Protection 1022 In order to protect from replay of requests, the server's Recipient 1023 Context includes a Replay Window. A server SHALL verify that a 1024 Partial IV received in the COSE object has not been received before. 1025 If this verification fails and the message received is a CON message, 1026 the server SHALL respond with a 5.03 Service Unavailable error 1027 message with the inner Max-Age option set to 0. The diagnostic 1028 payload MAY contain the "Replay protection failed" string. The size 1029 and type of the Replay Window depends on the use case and lower 1030 protocol layers. In case of reliable and ordered transport from 1031 endpoint to endpoint, the server MAY just store the last received 1032 Partial IV and require that newly received Partial IVs equals the 1033 last received Partial IV + 1. 1035 Responses to non-Observe requests are protected against replay as 1036 they are cryptographically bound to the request. 1038 In the case of Observe, a client receiving a notification SHALL 1039 verify that the Partial IV of a received notification is greater than 1040 the Notification Number bound to that Observe registration. If the 1041 verification fails, the client SHALL stop processing the response, 1042 and in the case of CON respond with an empty ACK. If the 1043 verification succeeds, the client SHALL overwrite the corresponding 1044 Notification Number with the received Partial IV. 1046 If messages are processed concurrently, the Partial IV needs to be 1047 validated a second time after decryption and before updating the 1048 replay protection data. The operation of validating the Partial IV 1049 and updating the replay protection data MUST be atomic. 1051 6.5. Losing Part of the Context State 1053 To prevent reuse of the Nonce with the same key, or from accepting 1054 replayed messages, a node needs to handle the situation of losing 1055 rapidly changing parts of the context, such as the request Token, 1056 Sender Sequence Number, Replay Window, and Nofitifcation Numbers. 1057 These are typically stored in RAM and therefore lost in the case of 1058 an unplanned reboot. 1060 After boot, a node MAY reject to use existing security contexts from 1061 before it booted and MAY establish a new security context with each 1062 party it communicates. However, establishing a fresh security 1063 context may have a non-negligible cost in terms of, e.g., power 1064 consumption. 1066 After boot, a node MAY use a partly persistently stored security 1067 context, but then the node MUST NOT reuse a previous Sender Sequence 1068 Number and MUST NOT accept previously accepted messages. Some ways 1069 to achieve this is described below: 1071 6.5.1. Sequence Number 1073 To prevent reuse of Sender Sequence Numbers, a node MAY perform the 1074 following procedure during normal operations: 1076 o Each time the Sender Sequence Number is evenly divisible by K, 1077 where K is a positive integer, store the Sender Sequence Number in 1078 persistent memory. After boot, the node initiates the Sender 1079 Sequence Number to the value stored in persistent memory + K - 1. 1080 Storing to persistent memory can be costly. The value K gives a 1081 trade-off between the number of storage operations and efficient 1082 use of Sender Sequence Numbers. 1084 6.5.2. Replay Window 1086 To prevent accepting replay of previously received requests, the 1087 server MAY perform the following procedure after boot: 1089 o For each stored security context, the first time after boot the 1090 server receives an OSCORE request, the server uses the Repeat 1091 option [I-D.amsuess-core-repeat-request-tag] to get a request with 1092 verifiable freshness and uses that to synchronize the replay 1093 window. If the server can verify the fresh request, the Partial 1094 IV in the fresh request is set as the lower limit of the replay 1095 window. 1097 6.5.3. Replay Protection of Observe Notifications 1099 To prevent accepting replay of previously received notification 1100 responses, the client MAY perform the following procedure after boot: 1102 o The client rejects notifications bound to the earlier 1103 registration, removes all Notification Numbers and re-register 1104 using Observe. 1106 7. Processing 1108 This section describes the OSCORE message processing. 1110 7.1. Protecting the Request 1112 Given a CoAP request, the client SHALL perform the following steps to 1113 create an OSCORE request: 1115 1. Retrieve the Sender Context associated with the target resource. 1117 2. Compose the Additional Authenticated Data, as described in 1118 Section 5. 1120 3. Compute the AEAD nonce from the Sender ID, Common IV, and Partial 1121 IV (Sender Sequence Number in network byte order). Then (in one 1122 atomic operation, see Section 6.2) increment the Sender Sequence 1123 Number by one. 1125 4. Encrypt the COSE object using the Sender Key. Compress the COSE 1126 Object as specified in Section 8. 1128 5. Format the OSCORE message according to Section 4. The Object- 1129 Security option is added, see Section 4.2.2. 1131 6. Store the association Token - Security Context. The client SHALL 1132 be able to find the Recipient Context from the Token in the 1133 response. 1135 7.2. Verifying the Request 1137 A server receiving a request containing the Object-Security option 1138 SHALL perform the following steps: 1140 1. Process outer Block options according to [RFC7959], until all 1141 blocks of the request have been received, see Section 4.2.3.2. 1143 2. Discard the message Code and all non-special Inner option 1144 message fields (marked with 'x' in column E of Figure 4) present 1145 in the received message. For example, an If-Match Outer option 1146 is discarded, but an Uri-Host Outer option is not discarded. 1148 3. Decompress the COSE Object (Section 8) and retrieve the 1149 Recipient Context associated with the Recipient ID in the 'kid' 1150 parameter. If the request is a NON message and either the 1151 decompression or the COSE message fails to decode, or the server 1152 fails to retrieve a Recipient Context with Recipient ID 1153 corresponding to the 'kid' parameter received, then the server 1154 SHALL stop processing the request. If the request is a CON 1155 message, and: 1157 * either the decompression or the COSE message fails to decode, 1158 the server SHALL respond with a 4.02 Bad Option error 1159 message. The diagnostic payload SHOULD contain the string 1160 "Failed to decode COSE". 1162 * the server fails to retrieve a Recipient Context with 1163 Recipient ID corresponding to the 'kid' parameter received, 1164 the server SHALL respond with a 4.01 Unauthorized error 1165 message. The diagnostic payload MAY contain the string 1166 "Security context not found". 1168 4. Verify the 'Partial IV' parameter using the Replay Window, as 1169 described in Section 6. 1171 5. Compose the Additional Authenticated Data, as described in 1172 Section 5. 1174 6. Compute the AEAD nonce from the Recipient ID, Common IV, and the 1175 'Partial IV' parameter, received in the COSE Object. 1177 7. Decrypt the COSE object using the Recipient Key. 1179 * If decryption fails, the server MUST stop processing the 1180 request and, if the request is a CON message, the server MUST 1181 respond with a 4.00 Bad Request error message. The 1182 diagnostic payload MAY contain the "Decryption failed" 1183 string. 1185 * If decryption succeeds, update the Replay Window, as 1186 described in Section 6. 1188 8. For each decrypted option, check if the option is also present 1189 as an Outer option: if it is, discard the Outer. For example: 1190 the message contains a Max-Age Inner and a Max-Age Outer option. 1191 The Outer Max-Age is discarded. 1193 9. Add decrypted code, options and payload to the decrypted 1194 request. The Object-Security option is removed. 1196 10. The decrypted CoAP request is processed according to [RFC7252] 1198 7.3. Protecting the Response 1200 Given a CoAP response, the server SHALL perform the following steps 1201 to create an OSCORE response. Note that CoAP error responses derived 1202 from CoAP processing (point 10. in Section 7.2) are protected, as 1203 well as successful CoAP responses, while the OSCORE errors (point 3., 1204 4., 7. in Section 7.2) do not follow the processing below, but are 1205 sent as simple CoAP responses, without OSCORE processing. 1207 1. Retrieve the Sender Context in the Security Context used to 1208 verify the request. 1210 2. Compose the Additional Authenticated Data, as described in 1211 Section 5. 1213 3. Compute the AEAD nonce 1215 * If Observe is not used, the nonce from the request is used. 1217 * If Observe is used, Compute the AEAD nonce from the Sender ID, 1218 Common IV, and Partial IV (Sender Sequence Number in network 1219 byte order). Then (in one atomic operation, see Section 6.2) 1220 increment the Sender Sequence Number by one. 1222 4. Encrypt the COSE object using the Sender Key. Compress the COSE 1223 Object as specified in Section 8. 1225 5. Format the OSCORE message according to Section 4. The Object- 1226 Security option is added, see Section 4.2.2. 1228 7.4. Verifying the Response 1230 A client receiving a response containing the Object-Security option 1231 SHALL perform the following steps: 1233 1. Process outer Block options according to [RFC7959], until all 1234 blocks of the OSCORE message have been received, see 1235 Section 4.2.3.2. 1237 2. Discard the message Code and all non-special Class E options 1238 from the message. For example, ETag Outer option is discarded, 1239 Max-Age Outer option is not discarded. 1241 3. Retrieve the Recipient Context associated with the Token. 1242 Decompress the COSE Object (Section 8). If either the 1243 decompression or the COSE message fails to decode, then go to 1244 11. 1246 4. For Observe notifications, verify the received 'Partial IV' 1247 parameter against the corresponding Notification Number as 1248 described in Section 6. If the client receives a notification 1249 for which no Observe request was sent, then go to 11. 1251 5. Compose the Additional Authenticated Data, as described in 1252 Section 5. 1254 6. Compute the AEAD nonce 1256 * If the Observe option is not present in the response, the 1257 nonce from the request is used. 1259 * If the Observe option is present in the response, compute the 1260 AEAD nonce from the Recipient ID, Common IV, and the 'Partial 1261 IV' parameter, received in the COSE Object. 1263 7. Decrypt the COSE object using the Recipient Key. 1265 * If decryption fails, then go to 11. 1267 * If decryption succeeds and Observe is used, update the 1268 corresponding Notification Number, as described in Section 6. 1270 8. For each decrypted option, check if the option is also present 1271 as an Outer option: if it is, discard the Outer. For example: 1272 the message contains a Max-Age Inner and a Max-Age Outer option. 1273 The Outer Max-Age is discarded. 1275 9. Add decrypted code, options and payload to the decrypted 1276 request. The Object-Security option is removed. 1278 10. The decrypted CoAP response is processed according to [RFC7252] 1280 11. (Optional) In case any of the previous erroneous conditions 1281 apply: if the response is a CON message, then the client SHALL 1282 send an empty ACK back and stop processing the response; if the 1283 response is a ACK or a NON message, then the client SHALL simply 1284 stop processing the response. 1286 8. OSCORE Compression 1288 The Concise Binary Object Representation (CBOR) [RFC7049] combines 1289 very small message sizes with extensibility. The CBOR Object Signing 1290 and Encryption (COSE) [RFC8152] uses CBOR to create compact encoding 1291 of signed and encrypted data. COSE is however constructed to support 1292 a large number of different stateless use cases, and is not fully 1293 optimized for use as a stateful security protocol, leading to a 1294 larger than necessary message expansion. In this section, we define 1295 a simple stateless compression mechanism for OSCORE called the 1296 "compressed COSE object", which significantly reduces the per-packet 1297 overhead. 1299 8.1. Encoding of the Object-Security Value 1301 The value of the Object-Security option SHALL contain the OSCORE flag 1302 byte and the kid parameter as follows: 1304 0 1 2 3 1305 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 1306 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1307 |0 0 0|h|k| n | kid (if any) ... 1308 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1310 Figure 7: Object-Security Value 1312 o The first byte (= the OSCORE flag byte) encodes a set of flags and 1313 the length of the Partial IV parameter. 1315 * The three least significant bits, n, encode the Partial IV 1316 length + 1. If n = 0 then the Partial IV is not present in the 1317 compressed COSE object. The value n = 7 is reserved. 1319 * The fourth least significant bit is the kid flag, k: it is set 1320 to 1 if the kid is present in the compressed COSE object. 1322 * The fifth least significant bit is the Context Hint flag, h: it 1323 is set to 1 if the compressed COSE object contains a Context 1324 Hint, see Section 8.3. 1326 * The sixth-eighth least significant bits are reserved and SHALL 1327 be set to zero when not in use. 1329 o The remaining bytes encode the value of the kid, if the kid is 1330 present (k = 1) 1332 The presence of Partial IV and kid in requests and responses is 1333 specified in Section 5, and summarized in Figure 8. 1335 +--------------------------+-----+-----+ 1336 | | k | n | 1337 +--------------------------+-----+-----+ 1338 | Request | 1 | > 0 | 1339 | Response without Observe | 0 | 0 | 1340 | Response with Observe | 0 | > 0 | 1341 +--------------------------+-----+-----+ 1343 Figure 8: Presence of data fields in OSCORE flag byte 1345 8.2. Encoding of the OSCORE Payload 1347 The payload of the OSCORE message SHALL be encoded as follows: 1349 o The first n - 1 bytes encode the value of the Partial IV, if the 1350 Partial IV is present (n > 0). 1352 o The following 1 byte encode the length of the Context Hint 1353 (Section 8.3), s, if the Context Hint flag is set (h = 1). 1355 o The following s bytes encode the Context Hint, if the Context Hint 1356 flag is set (h = 1). 1358 o The remaining bytes encode the ciphertext. 1360 8.3. Context Hint 1362 For certain use cases, e.g. deployments where the same Recipient ID 1363 is used with multiple contexts, it is necessary or favorable for the 1364 sending endpoint to provide a Context Hint in order for the receiving 1365 endpoint to retrieve the recipient context. The Context Hint is 1366 implicitly integrity protected, as a manipulation leads to the wrong 1367 or no context being retrieved resulting in a verification error. 1369 Examples: 1371 o If the sending endpoint has an identifier in some other namespace 1372 which can be used by the recipient endpoint to retrieve or 1373 establish the security context, then that identifier can be used 1374 as Context Hint. 1376 o In case of a group communication scenario 1377 [I-D.tiloca-core-multicast-oscoap], if the recipient endpoint 1378 belongs to multiple groups, involving the same endpoints, then a 1379 group identifier can be used as Context Hint to enable the 1380 receiving endpoint to find the right group security context. 1382 8.4. Compression Examples 1384 This section provides examples of COSE Objects before and after 1385 OSCORE compression. 1387 8.4.1. Example: Request 1389 Before compression: 1391 [ 1392 h'', 1393 { 4:h'25', 6:h'05' }, 1394 h'aea0155667924dff8a24e4cb35b9' 1395 ] 1397 0x83 40 a2 04 41 25 06 41 05 4e ae a0 15 56 67 92 1398 4d ff 8a 24 e4 cb 35 b9 (24 bytes) 1399 After compression: 1401 Flag byte: 0b00001010 = 0x0a 1403 Option Value: 0a 25 (2 bytes) 1405 Payload: 05 ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (15 bytes) 1407 8.4.2. Example: Request 2 1409 Before compression: 1411 [ 1412 h'', 1413 { 4:h'00', 6:h'00' }, 1414 h'aea0155667924dff8a24e4cb35b9' 1415 ] 1417 0x83 40 a2 04 41 00 06 41 00 4e ae a0 15 56 67 92 1418 4d ff 8a 24 e4 cb 35 b9 (24 bytes) 1420 After compression: 1422 Flag byte: 0b00001001 = 0x09 1424 Option Value: 09 (1 bytes) 1426 Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) 1428 8.4.3. Example: Response (without Observe) 1430 Before compression: 1432 [ 1433 h'', 1434 {}, 1435 h'aea0155667924dff8a24e4cb35b9' 1436 ] 1438 0x83 40 a0 4e ae a0 15 56 67 92 4d ff 8a 24 e4 cb 1439 35 b9 (18 bytes) 1441 After compression: 1443 Flag byte: 0b00000000 = 0x00 1445 Option Value: (0 bytes) 1447 Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) 1449 8.4.4. Example: Response (with Observe) 1451 Before compression: 1453 [ 1454 h'', 1455 { 6:h'07' }, 1456 h'aea0155667924dff8a24e4cb35b9' 1457 ] 1459 0x83 40 a1 06 41 07 4e ae a0 15 56 67 92 4d ff 1460 8a 24 e4 cb 35 b9 (21 bytes) 1462 After compression: 1464 Flag byte: 0b00000010 = 0x02 1466 Option Value: 02 (1 bytes) 1468 Payload: 07 ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (15 bytes) 1470 9. Web Linking 1472 The use of OSCORE MAY be indicated by a target attribute "osc" in a 1473 web link [RFC5988] to a resource. This attribute is a hint 1474 indicating that the destination of that link is to be accessed using 1475 OSCORE. Note that this is simply a hint, it does not include any 1476 security context material or any other information required to run 1477 OSCORE. 1479 A value MUST NOT be given for the "osc" attribute; any present value 1480 MUST be ignored by parsers. The "osc" attribute MUST NOT appear more 1481 than once in a given link-value; occurrences after the first MUST be 1482 ignored by parsers. 1484 10. Proxy Operations 1486 RFC 7252 defines operations for a CoAP-to-CoAP proxy (see Section 5.7 1487 of [RFC7252]) and for proxying between CoAP and HTTP (Section 10 of 1488 [RFC7252]). A more detailed description of the HTTP-to-CoAP mapping 1489 is provided by [RFC8075]. This section describes the operations of 1490 OSCORE-aware proxies. 1492 10.1. CoAP-to-CoAP Forwarding Proxy 1494 OSCORE is designed to work with legacy CoAP-to-CoAP forward proxies 1495 [RFC7252], but OSCORE-aware proxies provide certain simplifications 1496 as specified in this section. 1498 The targeted proxy operations are specified in Section 2.2.1 of 1499 [I-D.hartke-core-e2e-security-reqs]. In particular caching is 1500 disabled since the CoAP response is only applicable to the original 1501 client's CoAP request. An OSCORE-aware proxy SHALL NOT cache a 1502 response to a request with an Object-Security option. As a 1503 consequence, the search for cache hits and CoAP freshness/Max-Age 1504 processing can be omitted. 1506 Proxy processing of the (Outer) Proxy-Uri option is as defined in 1507 [RFC7252]. 1509 Proxy processing of the (Outer) Block options is as defined in 1510 [RFC7959] and [I-D.amsuess-core-repeat-request-tag]. 1512 Proxy processing of the (Outer) Observe option is as defined in 1513 [RFC7641]. OSCORE-aware proxies MAY look at the Partial IV value 1514 instead of the Outer Observe option. 1516 10.2. HTTP-to-CoAP Translation Proxy 1518 Section 10.2 of [RFC7252] and [RFC8075] specify the behavior of an 1519 HTTP-to-CoAP proxy. As requested in Section 1 of [RFC8075], this 1520 section describes the HTTP mapping for the OSCORE protocol extension 1521 of CoAP. 1523 The presence of the Object-Security option, both in requests and 1524 responses, is expressed in an HTTP header field named Object-Security 1525 in the mapped request or response. The value of the field is the 1526 value of the Object-Security option Section 8.1 in base64url encoding 1527 (Section 5 of [RFC4648]) without padding (see [RFC7515] Appendix C 1528 for implementation notes for this encoding). The value of the 1529 payload is the OSCORE payload Section 8.2, also base64url-encoded 1530 without padding. 1532 Example: 1534 Mapping and notation here is based on "Simple Form" (Section 5.4.1.1 1535 of [RFC8075]). 1537 [HTTP request -- Before object security processing] 1539 GET http://proxy.url/hc/?target_uri=coap://device.url/orders HTTP/1.1 1541 [HTTP request -- HTTP Client to Proxy] 1543 POST http://proxy.url/hc/?target_uri=coap://device.url/ HTTP/1.1 1544 Object-Security: 0b 25 1545 Body: 09 07 01 13 61 f7 0f d2 97 b1 [binary] 1547 [CoAP request -- Proxy to CoAP Server] 1549 POST coap://device.url/ 1550 Object-Security: 0b 25 1551 Payload: 09 07 01 13 61 f7 0f d2 97 b1 [binary] 1553 [CoAP response -- CoAP Server to Proxy] 1555 2.04 Changed 1556 Object-Security: [empty] 1557 Payload: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] 1559 [HTTP response -- Proxy to HTTP Client] 1561 HTTP/1.1 200 OK 1562 Object-Security: [empty] 1563 Body: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] 1565 [HTTP response -- After object security processing] 1567 HTTP/1.1 200 OK 1568 Body: Exterminate! Exterminate! 1570 Note that the HTTP Status Code 200 in the next-to-last message is the 1571 mapping of CoAP Code 2.04 (Changed), whereas the HTTP Status Code 200 1572 in the last message is the mapping of the CoAP Code 2.05 (Content), 1573 which was encrypted within the compressed COSE object carried in the 1574 Body of the HTTP response. 1576 10.3. CoAP-to-HTTP Translation Proxy 1578 Section 10.1 of [RFC7252] describes the behavior of a CoAP-to-HTTP 1579 proxy. RFC 8075 [RFC8075] does not cover this direction in any more 1580 detail and so an example instantiation of Section 10.1 of [RFC7252] 1581 is used below. 1583 Example: 1585 [CoAP request -- Before object security processing] 1587 GET coap://proxy.url/ 1588 Proxy-Uri=http://device.url/orders 1590 [CoAP request -- CoAP Client to Proxy] 1592 POST coap://proxy.url/ 1593 Proxy-Uri=http://device.url/ 1594 Object-Security: 0b 25 1595 Payload: 09 07 01 13 61 f7 0f d2 97 b1 [binary] 1597 [HTTP request -- Proxy to HTTP Server] 1599 POST http://device.url/ HTTP/1.1 1600 Object-Security: 0b 25 1601 Body: 09 07 01 13 61 f7 0f d2 97 b1 [binary] 1603 [HTTP response -- HTTP Server to Proxy] 1605 HTTP/1.1 200 OK 1606 Object-Security: [empty] 1607 Body: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] 1609 [CoAP response -- CoAP Server to Proxy] 1611 2.04 Changed 1612 Object-Security: [empty] 1613 Payload: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] 1615 [CoAP response -- After object security processing] 1617 2.05 Content 1618 Payload: Exterminate! Exterminate! 1620 Note that the HTTP Code 2.04 (Changed) in the next-to-last message is 1621 the mapping of HTTP Status Code 200, whereas the CoAP Code 2.05 1622 (Content) in the last message is the value that was encrypted within 1623 the compressed COSE object carried in the Body of the HTTP response. 1625 11. Security Considerations 1627 In scenarios with intermediary nodes such as proxies or brokers, 1628 transport layer security such as (D)TLS only protects data hop-by- 1629 hop. As a consequence, the intermediary nodes can read and modify 1630 information. The trust model where all intermediate nodes are 1631 considered trustworthy is problematic, not only from a privacy 1632 perspective, but also from a security perspective, as the 1633 intermediaries are free to delete resources on sensors and falsify 1634 commands to actuators (such as "unlock door", "start fire alarm", 1635 "raise bridge"). Even in the rare cases, where all the owners of the 1636 intermediary nodes are fully trusted, attacks and data breaches make 1637 such an architecture brittle. 1639 (D)TLS protects hop-by-hop the entire message, including header, 1640 options, and payload. OSCORE protects end-to-end the payload, and 1641 all information in the options and header, that is not required for 1642 proxy operations (see Section 4). (D)TLS and OSCORE can be combined, 1643 thereby enabling end-to-end security of the message payload, in 1644 combination with hop-by-hop protection of the entire message, during 1645 transport between end-point and intermediary node. The message 1646 layer, however, cannot be protected end-to-end through intermediary 1647 devices since, even if the protocol itself isn't translated, the 1648 parameters Type, Message ID, Token, and Token Length may be changed 1649 by a proxy. 1651 The use of COSE to protect messages as specified in this document 1652 requires an established security context. The method to establish 1653 the security context described in Section 3.2 is based on a common 1654 shared secret material in client and server, which may be obtained, 1655 e.g., by using the ACE framework [I-D.ietf-ace-oauth-authz]. An 1656 OSCORE profile of ACE is described in [I-D.seitz-ace-oscoap-profile]. 1658 Most AEAD algorithms require a unique nonce for each message, for 1659 which the sender sequence numbers in the COSE message field "Partial 1660 IV" is used. If the recipient accepts any sequence number larger 1661 than the one previously received, then the problem of sequence number 1662 synchronization is avoided. With reliable transport, it may be 1663 defined that only messages with sequence number which are equal to 1664 previous sequence number + 1 are accepted. The alternatives to 1665 sequence numbers have their issues: very constrained devices may not 1666 be able to support accurate time, or to generate and store large 1667 numbers of random nonces. The requirement to change key at counter 1668 wrap is a complication, but it also forces the user of this 1669 specification to think about implementing key renewal. 1671 The maximum sender sequence number is dependent on the AEAD 1672 algorithm. The maximum sender sequence number SHALL be 2^40 - 1, or 1673 any algorithm specific lower limit. The compression mechanism 1674 (Section 8) assumes that the Partial IV is 40 bits or less. The 1675 mandatory-to-implement AEAD algorithm AES-CCM-16-64-128 is selected 1676 for compatibility with CCM*. 1678 The inner block options enable the sender to split large messages 1679 into OSCORE-protected blocks such that the receiving node can verify 1680 blocks before having received the complete message. The outer block 1681 options allow for arbitrary proxy fragmentation operations that 1682 cannot be verified by the endpoints, but can by policy be restricted 1683 in size since the encrypted options allow for secure fragmentation of 1684 very large messages. A maximum message size (above which the sending 1685 endpoint fragments the message and the receiving endpoint discards 1686 the message, if complying to the policy) may be obtained as part of 1687 normal resource discovery. 1689 12. Privacy Considerations 1691 Privacy threats executed through intermediate nodes are considerably 1692 reduced by means of OSCORE. End-to-end integrity protection and 1693 encryption of the message payload and all options that are not used 1694 for proxy operations, provide mitigation against attacks on sensor 1695 and actuator communication, which may have a direct impact on the 1696 personal sphere. 1698 The unprotected options (Figure 4) may reveal privacy sensitive 1699 information. In particular Uri-Host SHOULD NOT contain privacy 1700 sensitive information. 1702 CoAP headers sent in plaintext allow for example matching of CON and 1703 ACK (CoAP Message Identifier), matching of request and responses 1704 (Token) and traffic analysis. 1706 Using the mechanisms described in Section 6.5 may reveal when a 1707 device goes through a reboot. This can be mitigated by the device 1708 storing the precise state of sender sequence number and replay window 1709 on a clean shutdown. 1711 The length of message fields can reveal information about the 1712 message. Applications may use a padding scheme to protect against 1713 traffic analysis. As an example, the strings "YES" and "NO" even if 1714 encrypted can be distinguished from each other as there is no padding 1715 supplied by the current set of encryption algorithms. Some 1716 information can be determined even from looking at boundary 1717 conditions. An example of this would be returning an integer between 1718 0 and 100 where lengths of 1, 2 and 3 will provide information about 1719 where in the range things are. Three different methods to deal with 1720 this are: 1) ensure that all messages are the same length. For 1721 example, using 0 and 1 instead of 'yes' and 'no'. 2) Use a character 1722 which is not part of the responses to pad to a fixed length. For 1723 example, pad with a space to three characters. 3) Use the PKCS #7 1724 style padding scheme where m bytes are appended each having the value 1725 of m. For example, appending a 0 to "YES" and two 1's to "NO". This 1726 style of padding means that all values need to be padded. Similar 1727 arguments apply to other message fields such as resource names. 1729 13. IANA Considerations 1731 Note to RFC Editor: Please replace all occurrences of "[[this 1732 document]]" with the RFC number of this specification. 1734 13.1. CoAP Option Numbers Registry 1736 The Object-Security option is added to the CoAP Option Numbers 1737 registry: 1739 +--------+-----------------+-------------------+ 1740 | Number | Name | Reference | 1741 +--------+-----------------+-------------------+ 1742 | TBD | Object-Security | [[this document]] | 1743 +--------+-----------------+-------------------+ 1745 13.2. Header Field Registrations 1747 The HTTP header field Object-Security is added to the Message Headers 1748 registry: 1750 +-------------------+----------+----------+-------------------+ 1751 | Header Field Name | Protocol | Status | Reference | 1752 +-------------------+----------+----------+-------------------+ 1753 | Object-Security | http | standard | [[this document]] | 1754 +-------------------+----------+----------+-------------------+ 1756 14. Acknowledgments 1758 The following individuals provided input to this document: Christian 1759 Amsuess, Tobias Andersson, Carsten Bormann, Joakim Brorsson, Thomas 1760 Fossati, Martin Gunnarsson, Klaus Hartke, Jim Schaad, Dave Thaler, 1761 Marco Tiloca, and Malisa Vučinić. 1763 Ludwig Seitz and Goeran Selander worked on this document as part of 1764 the CelticPlus project CyberWI, with funding from Vinnova. 1766 15. References 1768 15.1. Normative References 1770 [I-D.amsuess-core-repeat-request-tag] 1771 Amsuess, C., Mattsson, J., and G. Selander, "Repeat And 1772 Request-Tag", draft-amsuess-core-repeat-request-tag-00 1773 (work in progress), July 2017. 1775 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1776 Requirement Levels", BCP 14, RFC 2119, 1777 DOI 10.17487/RFC2119, March 1997, 1778 . 1780 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1781 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 1782 . 1784 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 1785 DOI 10.17487/RFC5988, October 2010, 1786 . 1788 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 1789 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 1790 January 2012, . 1792 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1793 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1794 October 2013, . 1796 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1797 Application Protocol (CoAP)", RFC 7252, 1798 DOI 10.17487/RFC7252, June 2014, 1799 . 1801 [RFC7641] Hartke, K., "Observing Resources in the Constrained 1802 Application Protocol (CoAP)", RFC 7641, 1803 DOI 10.17487/RFC7641, September 2015, 1804 . 1806 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 1807 the Constrained Application Protocol (CoAP)", RFC 7959, 1808 DOI 10.17487/RFC7959, August 2016, 1809 . 1811 [RFC8075] Castellani, A., Loreto, S., Rahman, A., Fossati, T., and 1812 E. Dijk, "Guidelines for Mapping Implementations: HTTP to 1813 the Constrained Application Protocol (CoAP)", RFC 8075, 1814 DOI 10.17487/RFC8075, February 2017, 1815 . 1817 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 1818 FETCH Methods for the Constrained Application Protocol 1819 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 1820 . 1822 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 1823 RFC 8152, DOI 10.17487/RFC8152, July 2017, 1824 . 1826 15.2. Informative References 1828 [I-D.bormann-6lo-coap-802-15-ie] 1829 Bormann, C., "Constrained Application Protocol (CoAP) over 1830 IEEE 802.15.4 Information Element for IETF", draft- 1831 bormann-6lo-coap-802-15-ie-00 (work in progress), April 1832 2016. 1834 [I-D.greevenbosch-appsawg-cbor-cddl] 1835 Birkholz, H., Vigano, C., and C. Bormann, "Concise data 1836 definition language (CDDL): a notational convention to 1837 express CBOR data structures", draft-greevenbosch-appsawg- 1838 cbor-cddl-11 (work in progress), July 2017. 1840 [I-D.hartke-core-e2e-security-reqs] 1841 Selander, G., Palombini, F., and K. Hartke, "Requirements 1842 for CoAP End-To-End Security", draft-hartke-core-e2e- 1843 security-reqs-03 (work in progress), July 2017. 1845 [I-D.ietf-ace-oauth-authz] 1846 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 1847 H. Tschofenig, "Authentication and Authorization for 1848 Constrained Environments (ACE)", draft-ietf-ace-oauth- 1849 authz-07 (work in progress), August 2017. 1851 [I-D.ietf-core-coap-tcp-tls] 1852 Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 1853 Silverajan, B., and B. Raymor, "CoAP (Constrained 1854 Application Protocol) over TCP, TLS, and WebSockets", 1855 draft-ietf-core-coap-tcp-tls-09 (work in progress), May 1856 2017. 1858 [I-D.mattsson-core-coap-actuators] 1859 Mattsson, J., Fornehed, J., Selander, G., and F. 1860 Palombini, "Controlling Actuators with CoAP", draft- 1861 mattsson-core-coap-actuators-02 (work in progress), 1862 November 2016. 1864 [I-D.seitz-ace-oscoap-profile] 1865 Seitz, L., Palombini, F., and M. Gunnarsson, "OSCOAP 1866 profile of the Authentication and Authorization for 1867 Constrained Environments Framework", draft-seitz-ace- 1868 oscoap-profile-04 (work in progress), July 2017. 1870 [I-D.tiloca-core-multicast-oscoap] 1871 Tiloca, M., Selander, G., and F. Palombini, "Secure group 1872 communication for CoAP", draft-tiloca-core-multicast- 1873 oscoap-03 (work in progress), July 2017. 1875 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1876 Resource Identifier (URI): Generic Syntax", STD 66, 1877 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1878 . 1880 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 1881 Key Derivation Function (HKDF)", RFC 5869, 1882 DOI 10.17487/RFC5869, May 2010, 1883 . 1885 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 1886 Constrained-Node Networks", RFC 7228, 1887 DOI 10.17487/RFC7228, May 2014, 1888 . 1890 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 1891 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 1892 2015, . 1894 Appendix A. Test Vectors 1896 TODO: This section needs to be updated. 1898 Appendix B. Examples 1900 This section gives examples of OSCORE. The message exchanges are 1901 made, based on the assumption that there is a security context 1902 established between client and server. For simplicity, these 1903 examples only indicate the content of the messages without going into 1904 detail of the COSE message format. 1906 B.1. Secure Access to Sensor 1908 This example targets the scenario in Section 3.1 of 1909 [I-D.hartke-core-e2e-security-reqs] and illustrates a client 1910 requesting the alarm status from a server. 1912 Client Proxy Server 1913 | | | 1914 +------>| | Code: 0.02 (POST) 1915 | POST | | Token: 0x8c 1916 | | | Object-Security: [kid:5f] 1917 | | | Payload: [Partial IV:42, 1918 | | | {Code:0.01, 1919 | | | Uri-Path:"alarm_status"}] 1920 | | | 1921 | +------>| Code: 0.02 (POST) 1922 | | POST | Token: 0x7b 1923 | | | Object-Security: [kid:5f] 1924 | | | Payload: [Partial IV:42, 1925 | | | {Code:0.01, 1926 | | | Uri-Path:"alarm_status"}] 1927 | | | 1928 | |<------+ Code: 2.04 (Changed) 1929 | | 2.04 | Token: 0x7b 1930 | | | Object-Security: - 1931 | | | Payload: [{Code:2.05, "OFF"}] 1932 | | | 1933 |<------+ | Code: 2.04 (Changed) 1934 | 2.04 | | Token: 0x8c 1935 | | | Object-Security: - 1936 | | | Payload: [{Code:2.05, "OFF"}] 1937 | | | 1939 Figure 9: Secure Access to Sensor. Square brackets [ ... ] indicate 1940 a COSE object. Curly brackets { ... } indicate encrypted data. 1942 The request/response Codes are encrypted by OSCORE and only dummy 1943 Codes (POST/Changed) are visible in the header of the OSCORE message. 1944 The option Uri-Path ("alarm_status") and payload ("OFF") are 1945 encrypted. 1947 The COSE header of the request contains an identifier (5f), 1948 indicating which security context was used to protect the message and 1949 a Partial IV (42). 1951 The server verifies that the Partial IV has not been received before. 1952 The client verifies that the response is bound to the request. 1954 B.2. Secure Subscribe to Sensor 1956 This example targets the scenario in Section 3.2 of 1957 [I-D.hartke-core-e2e-security-reqs] and illustrates a client 1958 requesting subscription to a blood sugar measurement resource (GET 1959 /glucose), first receiving the value 220 mg/dl and then a second 1960 value 180 mg/dl. 1962 Client Proxy Server 1963 | | | 1964 +------>| | Code: 0.05 (FETCH) 1965 | FETCH | | Token: 0x83 1966 | | | Observe: 0 1967 | | | Object-Security: [kid:ca] 1968 | | | Payload: [Partial IV:15, 1969 | | | {Code:0.01, 1970 | | | Uri-Path:"glucose"}] 1971 | | | 1972 | +------>| Code: 0.05 (FETCH) 1973 | | FETCH | Token: 0xbe 1974 | | | Observe: 0 1975 | | | Object-Security: [kid:ca] 1976 | | | Payload: [Partial IV:15, 1977 | | | {Code:0.01, 1978 | | | Uri-Path:"glucose"}] 1979 | | | 1980 | |<------+ Code: 2.05 (Content) 1981 | | 2.05 | Token: 0xbe 1982 | | | Observe: 7 1983 | | | Object-Security: - 1984 | | | Payload: [Partial IV:32, 1985 | | | {Code:2.05, 1986 | | | Content-Format:0, "220"}] 1987 | | | 1988 |<------+ | Code: 2.05 (Content) 1989 | 2.05 | | Token: 0x83 1990 | | | Observe: 7 1991 | | | Object-Security: - 1992 | | | Payload: [Partial IV:32, 1993 | | | {Code:2.05, 1994 | | | Content-Format:0, "220"}] 1995 ... ... ... 1996 | | | 1997 | |<------+ Code: 2.05 (Content) 1998 | | 2.05 | Token: 0xbe 1999 | | | Observe: 8 2000 | | | Object-Security: - 2001 | | | Payload: [Partial IV:36, 2002 | | | {Code:2.05, 2003 | | | Content-Format:0, "180"}] 2004 | | | 2005 |<------+ | Code: 2.05 (Content) 2006 | 2.05 | | Token: 0x83 2007 | | | Observe: 8 2008 | | | Object-Security: - 2009 | | | Payload: [Partial IV:36, 2010 | | | {Code:2.05, 2011 | | | Content-Format:0, "180"}] 2012 | | | 2014 Figure 10: Secure Subscribe to Sensor. Square brackets [ ... ] 2015 indicate a COSE object. Curly brackets { ... } indicate encrypted 2016 data. 2018 The request/response Codes are encrypted by OSCORE and only dummy 2019 Codes (FETCH/Content) are visible in the header of the OSCORE 2020 message. The options Content-Format (0) and the payload ("220" and 2021 "180"), are encrypted. 2023 The COSE header of the request contains an identifier (ca), 2024 indicating the security context used to protect the message and a 2025 Partial IV (15). The COSE headers of the responses contains Partial 2026 IVs (32 and 36). 2028 The server verifies that the Partial IV has not been received before. 2029 The client verifies that the responses are bound to the request and 2030 that the Partial IVs are greater than any Partial IV previously 2031 received in a response bound to the request. 2033 Authors' Addresses 2035 Goeran Selander 2036 Ericsson AB 2038 Email: goran.selander@ericsson.com 2040 John Mattsson 2041 Ericsson AB 2043 Email: john.mattsson@ericsson.com 2045 Francesca Palombini 2046 Ericsson AB 2048 Email: francesca.palombini@ericsson.com 2049 Ludwig Seitz 2050 SICS Swedish ICT 2052 Email: ludwig@sics.se