idnits 2.17.1 draft-ietf-core-object-security-06.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 (October 25, 2017) is 2368 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 (-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-05 == Outdated reference: A later version (-04) exists of draft-tiloca-core-multicast-oscoap-03 Summary: 3 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 28, 2018 Ericsson AB 6 L. Seitz 7 SICS Swedish ICT 8 October 25, 2017 10 Object Security for Constrained RESTful Environments (OSCORE) 11 draft-ietf-core-object-security-06 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 28, 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 . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . . . . . . . . . . 25 81 7.1. Protecting the Request . . . . . . . . . . . . . . . . . 25 82 7.2. Verifying the Request . . . . . . . . . . . . . . . . . . 25 83 7.3. Protecting the Response . . . . . . . . . . . . . . . . . 27 84 7.4. Verifying the Response . . . . . . . . . . . . . . . . . 27 85 8. OSCORE Compression . . . . . . . . . . . . . . . . . . . . . 29 86 8.1. Encoding of the Object-Security Value . . . . . . . . . . 29 87 8.2. Encoding of the OSCORE Payload . . . . . . . . . . . . . 30 88 8.3. Context Hint . . . . . . . . . . . . . . . . . . . . . . 30 89 8.4. Examples of Compressed COSE Objects . . . . . . . . . . . 30 90 9. Web Linking . . . . . . . . . . . . . . . . . . . . . . . . . 32 91 10. Proxy Operations . . . . . . . . . . . . . . . . . . . . . . 33 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 . . . . . . . . . . . . . 35 95 11. Security Considerations . . . . . . . . . . . . . . . . . . . 36 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 . . . . . . . . . . . . . . . . . . . . . . . . . 39 102 15.1. Normative References . . . . . . . . . . . . . . . . . . 39 103 15.2. Informative References . . . . . . . . . . . . . . . . . 40 104 Appendix A. Test Vectors . . . . . . . . . . . . . . . . . . . . 41 105 Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 41 106 B.1. Secure Access to Sensor . . . . . . . . . . . . . . . . . 42 107 B.2. Secure Subscribe to Sensor . . . . . . . . . . . . . . . 43 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 [RFC7252]. 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 message that are encrypted are transported in the payload of the 167 OSCORE message, and the Object-Security option is included, see 168 Figure 1. 170 Client Server 171 | OSCORE request - POST example.com: | 172 | Header, Token, | 173 | Options: {Object-Security, ...}, | 174 | Payload: COSE ciphertext | 175 +--------------------------------------------->| 176 | | 177 |<---------------------------------------------+ 178 | OSCORE response - 2.04 (Changed): | 179 | Header, Token, | 180 | Options: {Object-Security, ...}, | 181 | Payload: COSE ciphertext | 182 | | 184 Figure 1: Sketch of CoAP with OSCORE 186 OSCORE may be used in very constrained settings, thanks to its small 187 message size and the restricted code and memory requirements in 188 addition to what is required by CoAP. OSCORE can be combined with 189 transport layer security such as DTLS or TLS, thereby enabling end- 190 to-end security of e.g. CoAP Payload, Options and Code, in 191 combination with hop-by-hop protection of the Messaging Layer, during 192 transport between end-point and intermediary node. Examples of the 193 use of OSCORE are given in Appendix B. 195 An implementation supporting this specification MAY only implement 196 the client part, MAY only implement the server part, or MAY only 197 implement one of the proxy parts. OSCORE is designed to work with 198 legacy CoAP-to-CoAP forward proxies [RFC7252], but an OSCORE-aware 199 proxy will be more efficient. HTTP-to-CoAP proxies [RFC8075] and 200 CoAP-to-HTTP proxies need to implement respective parts of this 201 specification to work with OSCORE (see Section 10). 203 1.1. Terminology 205 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 206 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 207 document are to be interpreted as described in [RFC2119]. These 208 words may also appear in this document in lowercase, absent their 209 normative meanings. 211 Readers are expected to be familiar with the terms and concepts 212 described in CoAP [RFC7252], Observe [RFC7641], Blockwise [RFC7959], 213 COSE [RFC8152], CBOR [RFC7049], CDDL 214 [I-D.greevenbosch-appsawg-cbor-cddl], and constrained environments 215 [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 contains 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. Indpendent 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 422 [I-D.amsuess-core-repeat-request-tag]. How the input parameters are 423 pre-established, is application specific. The ACE framework may be 424 used to establish the necessary input parameters 425 [I-D.ietf-ace-oauth-authz]. 427 3.2.1. Derivation of Sender Key, Recipient Key, and Common IV 429 The KDF MUST be one of the HMAC based HKDF [RFC5869] algorithms 430 defined in COSE. HKDF SHA-256 is mandatory to implement. The 431 security context parameters Sender Key, Recipient Key, and Common IV 432 SHALL be derived from the input parameters using the HKDF, which 433 consists of the composition of the HKDF-Extract and HKDF-Expand steps 434 ([RFC5869]): 436 output parameter = HKDF(salt, IKM, info, L) 438 where: 440 o salt is the Master Salt as defined above 442 o IKM is the Master Secret is defined above 444 o info is a CBOR array consisting of: 446 info = [ 447 id : bstr / nil, 448 alg : int / tstr, 449 type : tstr, 450 L : uint 451 ] 453 where: 455 o id is the Sender ID or Recipient ID when deriving keys and nil 456 when deriving the Common IV. The encoding is described in 457 Section 5 459 o type is "Key" or "IV" 461 o L is the size of the key/IV for the AEAD algorithm used, in octets 463 For example, if the algorithm AES-CCM-16-64-128 (see Section 10.2 in 464 [RFC8152]) is used, the value for L is 16 for keys and 13 for the 465 Common IV. 467 3.2.2. Initial Sequence Numbers and Replay Window 469 The Sender Sequence Number is initialized to 0. The supported types 470 of replay protection and replay window length is application specific 471 and depends on the lower layers. The default is DTLS-type replay 472 protection with a window size of 32 initiated as described in 473 Section 4.1.2.6 of [RFC6347]. 475 3.3. Requirements on the Security Context Parameters 477 As collisions may lead to the loss of both confidentiality and 478 integrity, Sender ID SHALL be unique in the set of all security 479 contexts using the same Master Secret and Master Salt. When a 480 trusted third party assigns identifiers (e.g., using 481 [I-D.ietf-ace-oauth-authz]) or by using a protocol that allows the 482 parties to negotiate locally unique identifiers in each endpoint, the 483 Sender IDs can be very short. The maximum length of Sender ID is 484 length of nonce - 6 bytes. For AES-CCM-16-64-128 the maximum length 485 of Sender ID is 7 bytes. If Sender ID uniqueness cannot be 486 guaranteed by construction, Sender IDs MUST be long uniformly random 487 distributed byte strings such that the probability of collisions is 488 negligible. 490 To enable retrieval of the right Recipient Context, the Recipient ID 491 SHOULD be unique in the sets of all Recipient Contexts used by an 492 endpoint. The Client MAY provide a Context Hint Section 8.3 to help 493 the Server find the right context. 495 While the triple (Master Secret, Master Salt, Sender ID) MUST be 496 unique, the same Master Salt MAY be used with several Master Secrets 497 and the same Master Secret MAY be used with several Master Salts. 499 4. Protected Message Fields 501 OSCORE transforms a CoAP message (which may have been generated from 502 an HTTP message) into an OSCORE message, and vice versa. OSCORE 503 protects as much of the original message as possible while still 504 allowing certain proxy operations (see Section 10). This section 505 defines how OSCORE protects the message fields and transfers them 506 end-to-end between client and server (in any direction). 508 The remainder of this section and later sections discuss the behavior 509 in terms of CoAP messages. If HTTP is used for a particular leg in 510 the end-to-end path, then this section applies to the conceptual CoAP 511 message that is mappable to/from the original HTTP message as 512 discussed in Section 10. That is, an HTTP message is conceptually 513 transformed to a CoAP message and then to an OSCORE message, and 514 similarly in the reverse direction. An actual implementation might 515 translate directly from HTTP to OSCORE without the intervening CoAP 516 representation. 518 Message fields of the CoAP message may be protected end-to-end 519 between CoAP client and CoAP server in different ways: 521 o Class E: encrypted and integrity protected, 522 o Class I: integrity protected only, or 524 o Class U: unprotected. 526 The sending endpoint SHALL transfer Class E message fields in the 527 ciphertext of the COSE object in the OSCORE message. The sending 528 endpoint SHALL include Class I message fields in the Additional 529 Authenticated Data (AAD) of the AEAD algorithm, allowing the 530 receiving endpoint to detect if the value has changed in transfer. 531 Class U message fields SHALL NOT be protected in transfer. Class I 532 and Class U message field values are transferred in the header or 533 options part of the OSCORE message which is visible to proxies. 535 Message fields not visible to proxies, i.e., transported in the 536 ciphertext of the COSE object, are called "Inner" (Class E). Message 537 fields transferred in the header or options part of the OSCORE 538 message, which is visible to proxies, are called "Outer" (Class I or 539 U). 541 An OSCORE message may contain both an Inner and an Outer message 542 field of certain CoAP message fields. Inner if the value is intended 543 for the destination endpoint, Outer if the value is intended for a 544 proxy. Inner and Outer message fields are processed independently. 546 4.1. CoAP Payload 548 The CoAP Payload, if present in the original CoAP message, SHALL be 549 encrypted and integrity protected and is thus an Inner message field. 550 The sending endpoint writes the payload of the original CoAP message 551 into the plaintext (Section 5.2) input to the COSE object. The 552 receiving endpoint verifies and decrypts the COSE object, and 553 recreates the payload of the original CoAP message. 555 4.2. CoAP Options 557 A summary of how options are protected is shown in Figure 4. Options 558 which require special processing, in particular those which may have 559 both Inner and Outer message fields, are labelled with asterisks. 561 +----+----------------+---+---+---+ 562 | No.| Name | E | I | U | 563 +----+----------------+---+---+---+ 564 | 1 | If-Match | x | | | 565 | 3 | Uri-Host | | | x | 566 | 4 | ETag | x | | | 567 | 5 | If-None-Match | x | | | 568 | 6 | Observe | | | * | 569 | 7 | Uri-Port | | | x | 570 | 8 | Location-Path | x | | | 571 | 11 | Uri-Path | x | | | 572 | 12 | Content-Format | x | | | 573 | 14 | Max-Age | * | | * | 574 | 15 | Uri-Query | x | | | 575 | 17 | Accept | x | | | 576 | 20 | Location-Query | x | | | 577 | 23 | Block2 | * | | * | 578 | 27 | Block1 | * | | * | 579 | 28 | Size2 | * | | * | 580 | 35 | Proxy-Uri | * | | * | 581 | 39 | Proxy-Scheme | | | x | 582 | 60 | Size1 | * | | * | 583 +----+----------------+---+---+---+ 585 E = Encrypt and Integrity Protect (Inner) 586 I = Integrity Protect only (Outer) 587 U = Unprotected (Outer) 588 * = Special 590 Figure 4: Protection of CoAP Options 592 Options that are unknown or for which OSCORE processing is not 593 defined SHALL be processed as class E (and no special processing). 594 Specifications of new CoAP options SHOULD define how they are 595 processed with OSCORE. A new COAP option SHOULD be of class E unless 596 it requires proxy processing. New CoAP options which are repeatable 597 and of class I MUST specify that proxies MUST NOT change the order of 598 the option's occurences. 600 4.2.1. Inner Options 602 When using OSCORE, Inner option message fields (marked in column E of 603 Figure 4) are sent in a way analogous to communicating in a protected 604 manner directly with the other endpoint. 606 The sending endpoint SHALL write the Inner option message fields 607 present in the original CoAP message into the plaintext of the COSE 608 object Section 5.2, and then remove the Inner option message fields 609 from the OSCORE message. 611 The processing of Inner option message fields by the receiving 612 endpoint is specified in Section 7.2 and Section 7.4. 614 4.2.2. Outer Options 616 Outer option message fields (marked in column U or I of Figure 4) are 617 used to support proxy operations. 619 The sending endpoint SHALL include the Outer option message field 620 present in the original message in the options part of the OSCORE 621 message. All Outer option message fields, including Object-Security, 622 SHALL be encoded as described in Section 3.1 of [RFC7252], where the 623 delta is the difference to the previously included Outer option 624 message field. 626 The processing of Outer options by the receiving endpoint is 627 specified in Section 7.2 and Section 7.4. 629 A procedure for integrity-protection-only of Class I option message 630 fields is specified in Section 5.3. 632 Note: There are currently no Class I option message fields defined. 634 4.2.3. Special Options 636 Some options require special processing, marked with an asterisk '*' 637 in Figure 4. An asterisk in the columns E and U indicate that the 638 option may be added as an Inner and/or Outer message by the sending 639 endpoint; the processing is specified in this section. 641 4.2.3.1. Max-Age 643 The Inner Max-Age option is used to specify the freshness (as defined 644 in [RFC7252]) of the resource, end-to-end from the server to the 645 client, taking into account that the option is not accessible to 646 proxies. The Inner Max-Age SHALL be processed by OSCORE as specified 647 in Section 4.2.1. 649 The Outer Max-Age option is used to avoid unnecessary caching of 650 OSCORE responses at OSCORE unaware intermediary nodes. A server MAY 651 set a Class U Max-Age option with value zero to Observe responses 652 (see Section 5.6.1 of [RFC7252]) which is then processed according to 653 Section 4.2.2. The Outer Max-Age option value SHALL be discarded by 654 the OSCORE client. 656 Non-Observe OSCORE responses do not need to include a Max-Age option 657 since the responses are non-cacheable by construction (see 658 Section 4.3). 660 4.2.3.2. The Block Options 662 Blockwise [RFC7959] is an optional feature. An implementation MAY 663 support [RFC7252] and the Object-Security option without supporting 664 [RFC7959]. The Block options are used to secure message 665 fragmentation end-to-end (Inner options) or for proxies to fragment 666 the OSCORE message for the next hop (Outer options). Inner and Outer 667 block processing may have different performance properties depending 668 on the underlying transport. The integrity of the message can be 669 verified end-to-end both in case of Inner and Outer Blockwise 670 provided all blocks are received (see Section 4.2.3.2.2). 672 4.2.3.2.1. Inner Block Options 674 The sending CoAP endpoint MAY fragment a CoAP message as defined in 675 [RFC7959] before the message is processed by OSCORE. In this case 676 the Block options SHALL be processed by OSCORE as Inner options 677 (Section 4.2.1). The receiving CoAP endpoint SHALL process the 678 OSCORE message according to Section 4.2.1 before processing blockwise 679 as defined in [RFC7959]. 681 For blockwise request operations using Block1, an endpoint MUST 682 comply with the Request-Tag processing defined in Section 3 of 683 [I-D.amsuess-core-repeat-request-tag]. In particular, the rules in 684 section 3.3.1 of [I-D.amsuess-core-repeat-request-tag] MUST be 685 followed, which guarantee that a specific request body is assembled 686 only from the corresponding request blocks. 688 For blockwise response operations using Block2, an endpoint MUST 689 comply with the ETag processing defined in Section 4 of 690 [I-D.amsuess-core-repeat-request-tag]. 692 4.2.3.2.2. Outer Block Options 694 Proxies MAY fragment an OSCORE message using [RFC7959], which then 695 introduces Outer Block options not generated by the sending endpoint. 696 Note that the Outer Block options are neither encrypted nor integrity 697 protected. As a consequence, a proxy can maliciously inject block 698 fragments indefinitely, since the receiving endpoint needs to receive 699 the last block (see [RFC7959]) to be able to compose the OSCORE 700 message and verify its integrity. Therefore, applications supporting 701 OSCORE and [RFC7959] MUST specify a security policy defining a 702 maximum unfragmented message size (MAX_UNFRAGMENTED_SIZE) considering 703 the maximum size of message which can be handled by the endpoints. 705 Messages exceeding this size SHOULD be fragmented by the sending 706 endpoint using Inner Block options (Section 4.2.3.2.1). 708 An endpoint receiving an OSCORE message with an Outer Block option 709 SHALL first process this option according to [RFC7959], until all 710 blocks of the OSCORE message have been received, or the cumulated 711 message size of the blocks exceeds MAX_UNFRAGMENTED_SIZE. In the 712 former case, the processing of the OSCORE message continues as 713 defined in this document. In the latter case the message SHALL be 714 discarded. 716 To allow multiple concurrent request operations to the same server 717 (not only same resource), a CoAP proxy SHOULD follow the Request-Tag 718 processing specified in section 3.3.2 of 719 [I-D.amsuess-core-repeat-request-tag]. 721 4.2.3.3. Proxy-Uri 723 Proxy-Uri, when present, is split by OSCORE into class U options and 724 class E options, which are processed accordingly. When Proxy-Uri is 725 used in the original CoAP message, Uri-* are not present [RFC7252]. 727 The sending endpoint SHALL first decompose the Proxy-Uri value of the 728 original CoAP message into the Proxy-Scheme, Uri-Host, Uri-Port, Uri- 729 Path, and Uri-Query options (if present) according to section 6.4 of 730 [RFC7252]. 732 Uri-Path and Uri-Query are class E options and SHALL be protected and 733 processed as Inner options (Section 4.2.1). 735 The Proxy-Uri option of the OSCORE message SHALL be set to the 736 composition of Proxy-Scheme, Uri-Host and Uri-Port options (if 737 present) as specified in section 6.5 of [RFC7252], and processed as 738 an Outer option of Class U (Section 4.2.2). 740 Note that replacing the Proxy-Uri value with the Proxy-Scheme and 741 Uri-* options works by design for all CoAP URIs (see Section 6 of 742 [RFC7252]. OSCORE-aware HTTP servers should not use the userinfo 743 component of the HTTP URI (as defined in section 3.2.1. of 744 [RFC3986]), so that this type of replacement is possible in the 745 presence of CoAP-to-HTTP proxies. In other documents specifying 746 cross-protocol proxying behavior using different URI structures, it 747 is expected that the authors will create Uri-* options that allow 748 decomposing the Proxy-Uri, and specify in which OSCORE class they 749 belong. 751 An example of how Proxy-Uri is processed is given here. Assume that 752 the original CoAP message contains: 754 o Proxy-Uri = "coap://example.com/resource?q=1" 756 During OSCORE processing, Proxy-Uri is split into: 758 o Proxy-Scheme = "coap" 760 o Uri-Host = "example.com" 762 o Uri-Port = "5683" 764 o Uri-Path = "resource" 766 o Uri-Query = "q=1" 768 Uri-Path and Uri-Query follow the processing defined in 769 Section 4.2.1, and are thus encrypted and transported in the COSE 770 object. The remaining options are composed into the Proxy-Uri 771 included in the options part of the OSCORE message, which has value: 773 o Proxy-Uri = "coap://example.com" 775 See Section 6.1 and 12.6 of [RFC7252] for more information. 777 4.2.3.4. Observe 779 Observe [RFC7641] is an optional feature. An implementation MAY 780 support [RFC7252] and the Object-Security option without supporting 781 [RFC7641]. The Observe option as used here targets the requirements 782 on forwarding of [I-D.hartke-core-e2e-security-reqs] 783 (Section 2.2.1.2). 785 In order for an OSCORE-unaware proxy to support forwarding of Observe 786 messages ([RFC7641]), there SHALL be an Outer Observe option, i.e., 787 present in the options part of the OSCORE message. The processing of 788 the CoAP Code for Observe messages is described in Section 4.3. 790 To secure the order of notifications, the client SHALL maintain a 791 Notification Number for each Observation it registers. The 792 Notification Number is a non-negative integer containing the largest 793 Partial IV of the successfully received notifications for the 794 associated Observe registration, see Section 6.4. The Notification 795 Number is initialized to the Partial IV of the first successfully 796 received notification response to the registration request. In 797 contrast to [RFC7641], the received Partial IV MUST always be 798 compared with the Notification Number, which thus MUST NOT be 799 forgotten after 128 seconds. 801 If the verification fails, the client SHALL stop processing the 802 response, and in the case of CON respond with an empty ACK. The 803 client MAY ignore the Observe option value. 805 The Observe option in the CoAP request may be legitimately removed by 806 a proxy. If the Observe option is removed from a CoAP request by a 807 proxy, then the server can still verify the request (as a non-Observe 808 request), and produce a non-Observe response. If the OSCORE client 809 receives a response to an Observe request without an outer Observe 810 value, then it MUST verify the response as a non-Observe response. 811 (The reverse case is covered in the verification of the response, see 812 Section 7.) 814 4.3. CoAP Header 816 Most CoAP header fields (i.e. the message fields in the fixed 4-byte 817 header) are required to be read and/or changed by CoAP proxies and 818 thus cannot in general be protected end-to-end between the endpoints. 819 As mentioned in Section 1, OSCORE protects the CoAP Request/Response 820 layer only, and not the Messaging Layer (Section 2 of [RFC7252]), so 821 fields such as Type and Message ID are not protected with OSCORE. 823 The CoAP header field Code is protected by OSCORE. Code SHALL be 824 encrypted and integrity protected (Class E) to prevent an 825 intermediary from eavesdropping or manipulating the Code (e.g., 826 changing from GET to DELETE). 828 The sending endpoint SHALL write the Code of the original CoAP 829 message into the plaintext of the COSE object Section 5.2. After 830 that, the Outer Code of the OSCORE message SHALL be set to 0.02 831 (POST) for requests and to 2.04 (Changed) for responses, except for 832 Observe messages. For Observe messages, the Outer Code of the OSCORE 833 message SHALL be set to 0.05 (FETCH) for requests and to 2.05 834 (Content) for responses. This exception allows OSCORE to be 835 compliant with the Observe processing in OSCORE-unaware proxies. The 836 choice of POST and FETCH ([RFC8132]) allows all OSCORE messages to 837 have payload. 839 The receiving endpoint SHALL discard the Code in the OSCORE message 840 and write the Code of the Plaintext in the COSE object (Section 5.2) 841 into the decrypted CoAP message. 843 The other CoAP header fields are Unprotected (Class U). The sending 844 endpoint SHALL write all other header fields of the original message 845 into the header of the OSCORE message. The receiving endpoint SHALL 846 write the header fields from the received OSCORE message into the 847 header of the decrypted CoAP message. 849 5. The COSE Object 851 This section defines how to use COSE [RFC8152] to wrap and protect 852 data in the original message. OSCORE uses the untagged COSE_Encrypt0 853 structure with an Authenticated Encryption with Additional Data 854 (AEAD) algorithm. The key lengths, IV length, nonce length, and 855 maximum Sender Sequence Number are algorithm dependent. 857 The AEAD algorithm AES-CCM-16-64-128 defined in Section 10.2 of 858 [RFC8152] is mandatory to implement. For AES-CCM-16-64-128 the 859 length of Sender Key and Recipient Key is 128 bits, the length of 860 nonce and Common IV is 13 bytes. The maximum Sender Sequence Number 861 is specified in Section 11. 863 We denote by Plaintext the data that is encrypted and integrity 864 protected, and by Additional Authenticated Data (AAD) the data that 865 is integrity protected only. 867 The COSE Object SHALL be a COSE_Encrypt0 object with fields defined 868 as follows 870 o The "protected" field is empty. 872 o The "unprotected" field includes: 874 * The "Partial IV" parameter. The value is set to the Sender 875 Sequence Number. All leading zeroes SHALL be removed when 876 encoding the Partial IV. The value 0 encodes to the byte 877 string 0x00. This parameter SHALL be present in requests. In 878 case of Observe (Section 4.2.3.4) the Partial IV SHALL be 879 present in responses, and otherwise the Partial IV SHOULD NOT 880 be present in responses. (A non-Observe example where the 881 Partial IV is included in a response is provided in 882 Section 6.5.2.) 884 * The "kid" parameter. The value is set to the Sender ID. This 885 parameter SHALL be present in requests and SHOULD NOT be 886 present in responses. (An example where the Sender ID is 887 included in a response is the extension of OSCORE to group 888 communication [I-D.tiloca-core-multicast-oscoap].) 890 o The "ciphertext" field is computed from the secret key (Sender Key 891 or Recipient Key), Nonce (see Section 5.1), Plaintext (see 892 Section 5.2), and the Additional Authenticated Data (AAD) (see 893 Section 5.3) following Section 5.2 of [RFC8152]. 895 The encryption process is described in Section 5.3 of [RFC8152]. 897 5.1. Nonce 899 The nonce is constructed in the following way (see Figure 5): 901 1. left-padding the Partial IV (in network byte order) with zeroes 902 to exactly 5 bytes, 904 2. left-padding the (Sender) ID of the endpoint that generated the 905 Partial IV (in network byte order) with zeroes to exactly nonce 906 length - 6 bytes, 908 3. concatenating the size of the ID (S) with the padded ID and the 909 padded Partial IV, 911 4. and then XORing with the Common IV. 913 Note that in this specification only algorithms that use nonces equal 914 or greater than 7 bytes are supported. 916 When observe is not used, the request and the response may use the 917 same nonce. In this way, the Partial IV does not have to be sent in 918 responses, which reduces the size. For processing instructions, see 919 Section 7. 921 +---+-----------------------+--+--+--+--+--+ 922 | S | ID of PIV generator | Partial IV |----+ 923 +---+-----------------------+--+--+--+--+--+ | 924 | 925 +------------------------------------------+ | 926 | Common IV |->(XOR) 927 +------------------------------------------+ | 928 | 929 +------------------------------------------+ | 930 | Nonce |<---+ 931 +------------------------------------------+ 933 Figure 5: AEAD Nonce Formation 935 5.2. Plaintext 937 The Plaintext is formatted as a CoAP message without Header (see 938 Figure 6) consisting of: 940 o the Code of the original CoAP message as defined in Section 3 of 941 [RFC7252]; and 943 o all Inner option message fields (see Section 4.2.1) present in the 944 original CoAP message (see Section 4.2). The options are encoded 945 as described in Section 3.1 of [RFC7252], where the delta is the 946 difference to the previously included Class E option; and 948 o the Payload of original CoAP message, if present, and in that case 949 prefixed by the one-byte Payload Marker (0xFF). 951 0 1 2 3 952 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 953 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 954 | Code | Class E options (if any) ... 955 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 956 |1 1 1 1 1 1 1 1| Payload (if any) ... 957 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 958 (only if there 959 is payload) 961 Figure 6: Plaintext 963 5.3. Additional Authenticated Data 965 The external_aad SHALL be a CBOR array as defined below: 967 external_aad = [ 968 version : uint, 969 alg : int / tstr, 970 request_kid : bstr, 971 request_piv : bstr, 972 options : bstr 973 ] 975 where: 977 o version: contains the OSCORE version number. Implementations of 978 this specification MUST set this field to 1. Other values are 979 reserved for future versions. 981 o alg: contains the AEAD Algorithm from the security context used 982 for the exchange (see Section 3.1). 984 o request_kid: contains the value of the 'kid' in the COSE object of 985 the request (see Section 5). 987 o request_piv: contains the value of the 'Partial IV' in the COSE 988 object of the request (see Section 5). 990 o options: contains the Class I options (see Section 4.2.2) present 991 in the original CoAP message encoded as described in Section 3.1 992 of [RFC7252], where the delta is the difference to the previously 993 included class I option. 995 NOTE: The format of the external_aad is for simplicity the same for 996 requests and responses, although some parameters, e.g. request_kid 997 need not be integrity protected in the requests. 999 6. Sequence Numbers, Replay, Message Binding, and Freshness 1001 6.1. Message Binding 1003 In order to prevent response delay and mismatch attacks 1004 [I-D.mattsson-core-coap-actuators] from on-path attackers and 1005 compromised proxies, OSCORE binds responses to the requests by 1006 including the kid and Partial IV of the request in the AAD of the 1007 response. The server therefore needs to store the kid and Partial IV 1008 of the request until all responses have been sent. 1010 6.2. AEAD Nonce Uniqueness 1012 An AEAD nonce MUST NOT be used more than once per AEAD key. In order 1013 to assure unique nonces, each Sender Context contains a Sender 1014 Sequence Number used to protect requests, and - in case of Observe - 1015 responses. If messages are processed concurrently, the operation of 1016 reading and increasing the Sender Sequence Number MUST be atomic. 1018 The maximum Sender Sequence Number is algorithm dependent, see 1019 Section 11, and no greater than 2^40 - 1. If the Sender Sequence 1020 Number exceeds the maximum, the endpoint MUST NOT process any more 1021 messages with the given Sender Context. The endpoint SHOULD acquire 1022 a new security context (and consequently inform the other endpoint) 1023 before this happens. The latter is out of scope of this document. 1025 6.3. Freshness 1027 For requests, OSCORE provides weak absolute freshness as the only 1028 guarantee is that the request is not older than the security context. 1029 For applications having stronger demands on request freshness (e.g., 1030 control of actuators), OSCORE needs to be augmented with mechanisms 1031 providing freshness [I-D.amsuess-core-repeat-request-tag]. 1033 For responses, the message binding guarantees that a response is not 1034 older than its request. For responses without Observe, this gives 1035 strong absolute freshness. For responses with Observe, the absolute 1036 freshness gets weaker with time, and it is RECOMMENDED that the 1037 client regularly restart the observation. 1039 For requests, and responses with Observe, OSCORE also provides 1040 relative freshness in the sense that the received Partial IV allows a 1041 recipient to determine the relative order of responses. 1043 6.4. Replay Protection 1045 In order to protect from replay of requests, the server's Recipient 1046 Context includes a Replay Window. A server SHALL verify that a 1047 Partial IV received in the COSE object has not been received before. 1048 If this verification fails and the message received is a CON message, 1049 the server SHALL respond with a 5.03 Service Unavailable error 1050 message with the inner Max-Age option set to 0. The diagnostic 1051 payload MAY contain the "Replay protection failed" string. The size 1052 and type of the Replay Window depends on the use case and lower 1053 protocol layers. In case of reliable and ordered transport from 1054 endpoint to endpoint, the server MAY just store the last received 1055 Partial IV and require that newly received Partial IVs equals the 1056 last received Partial IV + 1. 1058 Responses to non-Observe requests are protected against replay as 1059 they are cryptographically bound to the request. 1061 In the case of Observe, a client receiving a notification SHALL 1062 verify that the Partial IV of a received notification is greater than 1063 the Notification Number bound to that Observe registration. If the 1064 verification fails, the client SHALL stop processing the response, 1065 and in the case of CON respond with an empty ACK. If the 1066 verification succeeds, the client SHALL overwrite the corresponding 1067 Notification Number with the received Partial IV. 1069 If messages are processed concurrently, the Partial IV needs to be 1070 validated a second time after decryption and before updating the 1071 replay protection data. The operation of validating the Partial IV 1072 and updating the replay protection data MUST be atomic. 1074 6.5. Losing Part of the Context State 1076 To prevent reuse of the Nonce with the same key, or from accepting 1077 replayed messages, a node needs to handle the situation of losing 1078 rapidly changing parts of the context, such as the request Token, 1079 Sender Sequence Number, Replay Window, and Nofitifcation Numbers. 1080 These are typically stored in RAM and therefore lost in the case of 1081 an unplanned reboot. 1083 After boot, a node MAY reject to use existing security contexts from 1084 before it booted and MAY establish a new security context with each 1085 party it communicates. However, establishing a fresh security 1086 context may have a non-negligible cost in terms of, e.g., power 1087 consumption. 1089 After boot, a node MAY use a partly persistently stored security 1090 context, but then the node MUST NOT reuse a previous Sender Sequence 1091 Number and MUST NOT accept previously accepted messages. Some ways 1092 to achieve this is described below: 1094 6.5.1. Sequence Number 1096 To prevent reuse of Sender Sequence Numbers, a node MAY perform the 1097 following procedure during normal operations: 1099 o Each time the Sender Sequence Number is evenly divisible by K, 1100 where K is a positive integer, store the Sender Sequence Number in 1101 persistent memory. After boot, the node initiates the Sender 1102 Sequence Number to the value stored in persistent memory + K - 1. 1103 Storing to persistent memory can be costly. The value K gives a 1104 trade-off between the number of storage operations and efficient 1105 use of Sender Sequence Numbers. 1107 6.5.2. Replay Window 1109 To prevent accepting replay of previously received requests, the 1110 server MAY perform the following procedure after boot: 1112 o For each stored security context, the first time after boot the 1113 server receives an OSCORE request, the server responds with the 1114 Repeat option [I-D.amsuess-core-repeat-request-tag] to get a 1115 request with verifiable freshness. The server MUST use its 1116 Partial IV when generating the nonce and MUST include the Partial 1117 IV in the response. 1119 If the server using the Repeat option can verify a second request as 1120 fresh, then the Partial IV of the second request is set as the lower 1121 limit of the replay window. 1123 6.5.3. Replay Protection of Observe Notifications 1125 To prevent accepting replay of previously received notification 1126 responses, the client MAY perform the following procedure after boot: 1128 o The client rejects notifications bound to the earlier 1129 registration, removes all Notification Numbers and re-register 1130 using Observe. 1132 7. Processing 1134 This section describes the OSCORE message processing. 1136 7.1. Protecting the Request 1138 Given a CoAP request, the client SHALL perform the following steps to 1139 create an OSCORE request: 1141 1. Retrieve the Sender Context associated with the target resource. 1143 2. Compose the Additional Authenticated Data, as described in 1144 Section 5. 1146 3. Compute the AEAD nonce from the Sender ID, Common IV, and Partial 1147 IV (Sender Sequence Number in network byte order) as described in 1148 Section 5.1. Then (in one atomic operation, see Section 6.2) 1149 increment the Sender Sequence Number by one. 1151 4. Encrypt the COSE object using the Sender Key. Compress the COSE 1152 Object as specified in Section 8. 1154 5. Format the OSCORE message according to Section 4. The Object- 1155 Security option is added, see Section 4.2.2. 1157 6. Store the association Token - Security Context. The client SHALL 1158 be able to find the Recipient Context from the Token in the 1159 response. 1161 7.2. Verifying the Request 1163 A server receiving a request containing the Object-Security option 1164 SHALL perform the following steps: 1166 1. Process outer Block options according to [RFC7959], until all 1167 blocks of the request have been received, see Section 4.2.3.2. 1169 2. Discard the message Code and all non-special Inner option 1170 message fields (marked with 'x' in column E of Figure 4) present 1171 in the received message. For example, an If-Match Outer option 1172 is discarded, but an Uri-Host Outer option is not discarded. 1174 3. Decompress the COSE Object (Section 8) and retrieve the 1175 Recipient Context associated with the Recipient ID in the 'kid' 1176 parameter. If the request is a NON message and either the 1177 decompression or the COSE message fails to decode, or the server 1178 fails to retrieve a Recipient Context with Recipient ID 1179 corresponding to the 'kid' parameter received, then the server 1180 SHALL stop processing the request. If the request is a CON 1181 message, and: 1183 * either the decompression or the COSE message fails to decode, 1184 the server SHALL respond with a 4.02 Bad Option error 1185 message. The diagnostic payload SHOULD contain the string 1186 "Failed to decode COSE". 1188 * the server fails to retrieve a Recipient Context with 1189 Recipient ID corresponding to the 'kid' parameter received, 1190 the server SHALL respond with a 4.01 Unauthorized error 1191 message. The diagnostic payload MAY contain the string 1192 "Security context not found". 1194 4. Verify the 'Partial IV' parameter using the Replay Window, as 1195 described in Section 6. 1197 5. Compose the Additional Authenticated Data, as described in 1198 Section 5. 1200 6. Compute the AEAD nonce from the Recipient ID, Common IV, and the 1201 'Partial IV' parameter, received in the COSE Object. 1203 7. Decrypt the COSE object using the Recipient Key. 1205 * If decryption fails, the server MUST stop processing the 1206 request and, if the request is a CON message, the server MUST 1207 respond with a 4.00 Bad Request error message. The 1208 diagnostic payload MAY contain the "Decryption failed" 1209 string. 1211 * If decryption succeeds, update the Replay Window, as 1212 described in Section 6. 1214 8. For each decrypted option, check if the option is also present 1215 as an Outer option: if it is, discard the Outer. For example: 1216 the message contains a Max-Age Inner and a Max-Age Outer option. 1217 The Outer Max-Age is discarded. 1219 9. Add decrypted code, options and payload to the decrypted 1220 request. The Object-Security option is removed. 1222 10. The decrypted CoAP request is processed according to [RFC7252] 1224 7.3. Protecting the Response 1226 Given a CoAP response, the server SHALL perform the following steps 1227 to create an OSCORE response. Note that CoAP error responses derived 1228 from CoAP processing (point 10. in Section 7.2) are protected, as 1229 well as successful CoAP responses, while the OSCORE errors (point 3., 1230 4., 7. in Section 7.2) do not follow the processing below, but are 1231 sent as simple CoAP responses, without OSCORE processing. 1233 1. Retrieve the Sender Context in the Security Context used to 1234 verify the request. 1236 2. Compose the Additional Authenticated Data, as described in 1237 Section 5. 1239 3. Compute the AEAD nonce 1241 * If Observe is used, Compute the AEAD nonce from the Sender ID, 1242 Common IV, and Partial IV (Sender Sequence Number in network 1243 byte order). Then (in one atomic operation, see Section 6.2) 1244 increment the Sender Sequence Number by one. 1246 * If Observe is not used, either the nonce from the request is 1247 used or a new Partial IV is used. 1249 4. Encrypt the COSE object using the Sender Key. Compress the COSE 1250 Object as specified in Section 8. If in 3. the nonce was 1251 constructed from a new Partial IV, this Partial IV MUST be 1252 included in the message. If the nonce from the request was used, 1253 the Partial IV MUST NOT be included in the message. 1255 5. Format the OSCORE message according to Section 4. The Object- 1256 Security option is added, see Section 4.2.2. 1258 7.4. Verifying the Response 1260 A client receiving a response containing the Object-Security option 1261 SHALL perform the following steps: 1263 1. Process outer Block options according to [RFC7959], until all 1264 blocks of the OSCORE message have been received, see 1265 Section 4.2.3.2. 1267 2. Discard the message Code and all non-special Class E options 1268 from the message. For example, ETag Outer option is discarded, 1269 Max-Age Outer option is not discarded. 1271 3. Retrieve the Recipient Context associated with the Token. 1272 Decompress the COSE Object (Section 8). If either the 1273 decompression or the COSE message fails to decode, then go to 1274 11. 1276 4. For Observe notifications, verify the received 'Partial IV' 1277 parameter against the corresponding Notification Number as 1278 described in Section 6. If the client receives a notification 1279 for which no Observe request was sent, then go to 11. 1281 5. Compose the Additional Authenticated Data, as described in 1282 Section 5. 1284 6. Compute the AEAD nonce 1286 1. If the Observe option and the Partial IV are not present in 1287 the response, the nonce from the request is used. 1289 2. If the Observe option is present in the response, and the 1290 Partial IV is not present in the response, then go to 11. 1292 3. If the Partial IV is present in the response, compute the 1293 AEAD nonce from the Recipient ID, Common IV, and the 1294 'Partial IV' parameter, received in the COSE Object. 1296 7. Decrypt the COSE object using the Recipient Key. 1298 * If decryption fails, then go to 11. 1300 * If decryption succeeds and Observe is used, update the 1301 corresponding Notification Number, as described in Section 6. 1303 8. For each decrypted option, check if the option is also present 1304 as an Outer option: if it is, discard the Outer. For example: 1305 the message contains a Max-Age Inner and a Max-Age Outer option. 1306 The Outer Max-Age is discarded. 1308 9. Add decrypted code, options and payload to the decrypted 1309 request. The Object-Security option is removed. 1311 10. The decrypted CoAP response is processed according to [RFC7252] 1313 11. (Optional) In case any of the previous erroneous conditions 1314 apply: if the response is a CON message, then the client SHALL 1315 send an empty ACK back and stop processing the response; if the 1316 response is a ACK or a NON message, then the client SHALL simply 1317 stop processing the response. 1319 8. OSCORE Compression 1321 The Concise Binary Object Representation (CBOR) [RFC7049] combines 1322 very small message sizes with extensibility. The CBOR Object Signing 1323 and Encryption (COSE) [RFC8152] uses CBOR to create compact encoding 1324 of signed and encrypted data. COSE is however constructed to support 1325 a large number of different stateless use cases, and is not fully 1326 optimized for use as a stateful security protocol, leading to a 1327 larger than necessary message expansion. In this section, we define 1328 a simple stateless compression mechanism for OSCORE called the 1329 "compressed COSE object", which significantly reduces the per-packet 1330 overhead. 1332 8.1. Encoding of the Object-Security Value 1334 The value of the Object-Security option SHALL contain the OSCORE flag 1335 byte, the Partial IV parameter, the Context Hint parameter (length 1336 and value), and the kid parameter as follows: 1338 0 1 2 3 4 5 6 7 <--------- n bytes -------------> 1339 +-+-+-+-+-+-+-+-+--------------------------------- 1340 |0 0 0|h|k| n | Partial IV (if any) 1341 +-+-+-+-+-+-+-+-+--------------------------------- 1343 <-- 1 byte --> <------ s bytes ------> 1344 +------------+-----------------------+------------------+ 1345 | s (if any) | Context Hint (if any) | kid (if any) ... | 1346 +------------+-----------------------+------------------+ 1348 Figure 7: Object-Security Value 1350 o The first byte (= the OSCORE flag byte) encodes a set of flags and 1351 the length of the Partial IV parameter. 1353 * The three least significant bits encode the Partial IV length 1354 n. If n = 0 then the Partial IV is not present in the 1355 compressed COSE object. The values n = 6 and n = 7 is 1356 reserved. 1358 * The fourth least significant bit is the kid flag, k: it is set 1359 to 1 if the kid is present in the compressed COSE object. 1361 * The fifth least significant bit is the Context Hint flag, h: it 1362 is set to 1 if the compressed COSE object contains a Context 1363 Hint, see Section 8.3. 1365 * The sixth-eighth least significant bits are reserved and SHALL 1366 be set to zero when not in use. 1368 o The following n bytes encode the value of the Partial IV, if the 1369 Partial IV is present (n > 0). 1371 o The following 1 byte encode the length of the Context Hint 1372 (Section 8.3) s, if the Context Hint flag is set (h = 1). 1374 o The following s bytes encode the Context Hint, if the Context Hint 1375 flag is set (h = 1). 1377 o The remaining bytes encode the value of the kid, if the kid is 1378 present (k = 1) 1380 Note that the kid MUST be the last field of the object-security 1381 value, even in case reserved bits are used and additional fields are 1382 added to it. 1384 8.2. Encoding of the OSCORE Payload 1386 The payload of the OSCORE message SHALL encode the ciphertext of the 1387 COSE object. 1389 8.3. Context Hint 1391 For certain use cases, e.g. deployments where the same Recipient ID 1392 is used with multiple contexts, it is necessary or favorable for the 1393 client to provide a Context Hint in order for the server to retrieve 1394 the Recipient Context. The Context Hint is implicitly integrity 1395 protected, as manipulation leads to the wrong or no context being 1396 retrieved resulting in a verification error, as described in 1397 Section 7.2. This parameter MAY be present in requests and SHALL NOT 1398 be present in responses. 1400 Examples: 1402 o If the client has an identifier in some other namespace which can 1403 be used by the server to retrieve or establish the security 1404 context, then that identifier can be used as Context Hint. 1406 o In case of a group communication scenario 1407 [I-D.tiloca-core-multicast-oscoap], if the server belongs to 1408 multiple groups, then a group identifier can be used as Context 1409 Hint to enable the server to find the right security context. 1411 8.4. Examples of Compressed COSE Objects 1412 8.4.1. Example: Requests 1414 Request with kid = 25 and Partial IV = 5 1416 Before compression (24 bytes): 1418 [ 1419 h'', 1420 { 4:h'25', 6:h'05' }, 1421 h'aea0155667924dff8a24e4cb35b9' 1422 ] 1424 After compression (17 bytes): 1426 Flag byte: 0b00001001 = 0x09 1428 Option Value: 09 05 25 (3 bytes) 1430 Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) 1432 Request with kid = empty string and Partial IV = 0 1434 After compression (16 bytes): 1436 Flag byte: 0b00001001 = 0x09 1438 Option Value: 09 00 (2 bytes) 1440 Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) 1442 Request with kid = empty string, Partial IV = 5, and Context Hint = 1443 0x44616c656b 1445 After compression (22 bytes): 1447 Flag byte: 0b00011001 = 0x19 1449 Option Value: 19 05 01 44 61 6c 65 6b (8 bytes) 1451 Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) 1453 8.4.2. Example: Response (without Observe) 1455 Before compression (18 bytes): 1457 [ 1458 h'', 1459 {}, 1460 h'aea0155667924dff8a24e4cb35b9' 1461 ] 1463 After compression (14 bytes): 1465 Flag byte: 0b00000000 = 0x00 1467 Option Value: (0 bytes) 1469 Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) 1471 8.4.3. Example: Response (with Observe) 1473 Before compression (21 bytes): 1475 [ 1476 h'', 1477 { 6:h'07' }, 1478 h'aea0155667924dff8a24e4cb35b9' 1479 ] 1481 After compression (16 bytes): 1483 Flag byte: 0b00000001 = 0x01 1485 Option Value: 01 07 (2 bytes) 1487 Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) 1489 9. Web Linking 1491 The use of OSCORE MAY be indicated by a target attribute "osc" in a 1492 web link [RFC8288] to a resource. This attribute is a hint 1493 indicating that the destination of that link is to be accessed using 1494 OSCORE. Note that this is simply a hint, it does not include any 1495 security context material or any other information required to run 1496 OSCORE. 1498 A value MUST NOT be given for the "osc" attribute; any present value 1499 MUST be ignored by parsers. The "osc" attribute MUST NOT appear more 1500 than once in a given link-value; occurrences after the first MUST be 1501 ignored by parsers. 1503 10. Proxy Operations 1505 RFC 7252 defines operations for a CoAP-to-CoAP proxy (see Section 5.7 1506 of [RFC7252]) and for proxying between CoAP and HTTP (Section 10 of 1507 [RFC7252]). A more detailed description of the HTTP-to-CoAP mapping 1508 is provided by [RFC8075]. This section describes the operations of 1509 OSCORE-aware proxies. 1511 10.1. CoAP-to-CoAP Forwarding Proxy 1513 OSCORE is designed to work with legacy CoAP-to-CoAP forward proxies 1514 [RFC7252], but OSCORE-aware proxies provide certain simplifications 1515 as specified in this section. 1517 The targeted proxy operations are specified in Section 2.2.1 of 1518 [I-D.hartke-core-e2e-security-reqs]. In particular caching is 1519 disabled since the CoAP response is only applicable to the original 1520 client's CoAP request. An OSCORE-aware proxy SHALL NOT cache a 1521 response to a request with an Object-Security option. As a 1522 consequence, the search for cache hits and CoAP freshness/Max-Age 1523 processing can be omitted. 1525 Proxy processing of the (Outer) Proxy-Uri option is as defined in 1526 [RFC7252]. 1528 Proxy processing of the (Outer) Block options is as defined in 1529 [RFC7959] and [I-D.amsuess-core-repeat-request-tag]. 1531 Proxy processing of the (Outer) Observe option is as defined in 1532 [RFC7641]. OSCORE-aware proxies MAY look at the Partial IV value 1533 instead of the Outer Observe option. 1535 10.2. HTTP-to-CoAP Translation Proxy 1537 Section 10.2 of [RFC7252] and [RFC8075] specify the behavior of an 1538 HTTP-to-CoAP proxy. As requested in Section 1 of [RFC8075], this 1539 section describes the HTTP mapping for the OSCORE protocol extension 1540 of CoAP. 1542 The presence of the Object-Security option, both in requests and 1543 responses, is expressed in an HTTP header field named Object-Security 1544 in the mapped request or response. The value of the field is the 1545 value of the Object-Security option Section 8.1 in base64url encoding 1546 (Section 5 of [RFC4648]) without padding (see [RFC7515] Appendix C 1547 for implementation notes for this encoding). The value of the 1548 payload is the OSCORE payload Section 8.2, also base64url-encoded 1549 without padding. 1551 Example: 1553 Mapping and notation here is based on "Simple Form" (Section 5.4.1.1 1554 of [RFC8075]). 1556 [HTTP request -- Before object security processing] 1558 GET http://proxy.url/hc/?target_uri=coap://server.url/orders HTTP/1.1 1560 [HTTP request -- HTTP Client to Proxy] 1562 POST http://proxy.url/hc/?target_uri=coap://server.url/ HTTP/1.1 1563 Object-Security: 0b 25 1564 Body: 09 07 01 13 61 f7 0f d2 97 b1 [binary] 1566 [CoAP request -- Proxy to CoAP Server] 1568 POST coap://server.url/ 1569 Object-Security: 0b 25 1570 Payload: 09 07 01 13 61 f7 0f d2 97 b1 [binary] 1572 [CoAP response -- CoAP Server to Proxy] 1574 2.04 Changed 1575 Object-Security: [empty] 1576 Payload: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] 1578 [HTTP response -- Proxy to HTTP Client] 1580 HTTP/1.1 200 OK 1581 Object-Security: [empty] 1582 Body: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] 1584 [HTTP response -- After object security processing] 1586 HTTP/1.1 200 OK 1587 Body: Exterminate! Exterminate! 1589 Note that the HTTP Status Code 200 in the next-to-last message is the 1590 mapping of CoAP Code 2.04 (Changed), whereas the HTTP Status Code 200 1591 in the last message is the mapping of the CoAP Code 2.05 (Content), 1592 which was encrypted within the compressed COSE object carried in the 1593 Body of the HTTP response. 1595 10.3. CoAP-to-HTTP Translation Proxy 1597 Section 10.1 of [RFC7252] describes the behavior of a CoAP-to-HTTP 1598 proxy. RFC 8075 [RFC8075] does not cover this direction in any more 1599 detail and so an example instantiation of Section 10.1 of [RFC7252] 1600 is used below. 1602 Example: 1604 [CoAP request -- Before object security processing] 1606 GET coap://proxy.url/ 1607 Proxy-Uri=http://server.url/orders 1609 [CoAP request -- CoAP Client to Proxy] 1611 POST coap://proxy.url/ 1612 Proxy-Uri=http://server.url/ 1613 Object-Security: 0b 25 1614 Payload: 09 07 01 13 61 f7 0f d2 97 b1 [binary] 1616 [HTTP request -- Proxy to HTTP Server] 1618 POST http://server.url/ HTTP/1.1 1619 Object-Security: 0b 25 1620 Body: 09 07 01 13 61 f7 0f d2 97 b1 [binary] 1622 [HTTP response -- HTTP Server to Proxy] 1624 HTTP/1.1 200 OK 1625 Object-Security: [empty] 1626 Body: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] 1628 [CoAP response -- CoAP Server to Proxy] 1630 2.04 Changed 1631 Object-Security: [empty] 1632 Payload: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] 1634 [CoAP response -- After object security processing] 1636 2.05 Content 1637 Payload: Exterminate! Exterminate! 1639 Note that the HTTP Code 2.04 (Changed) in the next-to-last message is 1640 the mapping of HTTP Status Code 200, whereas the CoAP Code 2.05 1641 (Content) in the last message is the value that was encrypted within 1642 the compressed COSE object carried in the Body of the HTTP response. 1644 11. Security Considerations 1646 In scenarios with intermediary nodes such as proxies or brokers, 1647 transport layer security such as (D)TLS only protects data hop-by- 1648 hop. As a consequence, the intermediary nodes can read and modify 1649 information. The trust model where all intermediate nodes are 1650 considered trustworthy is problematic, not only from a privacy 1651 perspective, but also from a security perspective, as the 1652 intermediaries are free to delete resources on sensors and falsify 1653 commands to actuators (such as "unlock door", "start fire alarm", 1654 "raise bridge"). Even in the rare cases, where all the owners of the 1655 intermediary nodes are fully trusted, attacks and data breaches make 1656 such an architecture brittle. 1658 (D)TLS protects hop-by-hop the entire message, including header, 1659 options, and payload. OSCORE protects end-to-end the payload, and 1660 all information in the options and header, that is not required for 1661 proxy operations (see Section 4). (D)TLS and OSCORE can be combined, 1662 thereby enabling end-to-end security of the message payload, in 1663 combination with hop-by-hop protection of the entire message, during 1664 transport between end-point and intermediary node. The message 1665 layer, however, cannot be protected end-to-end through intermediary 1666 devices since, even if the protocol itself isn't translated, the 1667 parameters Type, Message ID, Token, and Token Length may be changed 1668 by a proxy. 1670 The use of COSE to protect messages as specified in this document 1671 requires an established security context. The method to establish 1672 the security context described in Section 3.2 is based on a common 1673 shared secret material in client and server, which may be obtained, 1674 e.g., by using the ACE framework [I-D.ietf-ace-oauth-authz]. An 1675 OSCORE profile of ACE is described in [I-D.seitz-ace-oscoap-profile]. 1677 Most AEAD algorithms require a unique nonce for each message, for 1678 which the sender sequence numbers in the COSE message field "Partial 1679 IV" is used. If the recipient accepts any sequence number larger 1680 than the one previously received, then the problem of sequence number 1681 synchronization is avoided. With reliable transport, it may be 1682 defined that only messages with sequence number which are equal to 1683 previous sequence number + 1 are accepted. The alternatives to 1684 sequence numbers have their issues: very constrained devices may not 1685 be able to support accurate time, or to generate and store large 1686 numbers of random nonces. The requirement to change key at counter 1687 wrap is a complication, but it also forces the user of this 1688 specification to think about implementing key renewal. 1690 The maximum sender sequence number is dependent on the AEAD 1691 algorithm. The maximum sender sequence number SHALL be 2^40 - 1, or 1692 any algorithm specific lower limit, after which a new security 1693 context must be generated. The mechanism to build the nonce 1694 (Section 5.1) assumes that the nonce is at least 56 bit-long, and the 1695 Partial IV is at most 40 bit-long. The mandatory-to-implement AEAD 1696 algorithm AES-CCM-16-64-128 is selected for compatibility with CCM*. 1698 The inner block options enable the sender to split large messages 1699 into OSCORE-protected blocks such that the receiving node can verify 1700 blocks before having received the complete message. The outer block 1701 options allow for arbitrary proxy fragmentation operations that 1702 cannot be verified by the endpoints, but can by policy be restricted 1703 in size since the encrypted options allow for secure fragmentation of 1704 very large messages. A maximum message size (above which the sending 1705 endpoint fragments the message and the receiving endpoint discards 1706 the message, if complying to the policy) may be obtained as part of 1707 normal resource discovery. 1709 12. Privacy Considerations 1711 Privacy threats executed through intermediate nodes are considerably 1712 reduced by means of OSCORE. End-to-end integrity protection and 1713 encryption of the message payload and all options that are not used 1714 for proxy operations, provide mitigation against attacks on sensor 1715 and actuator communication, which may have a direct impact on the 1716 personal sphere. 1718 The unprotected options (Figure 4) may reveal privacy sensitive 1719 information. In particular Uri-Host SHOULD NOT contain privacy 1720 sensitive information. 1722 CoAP headers sent in plaintext allow for example matching of CON and 1723 ACK (CoAP Message Identifier), matching of request and responses 1724 (Token) and traffic analysis. 1726 Using the mechanisms described in Section 6.5 may reveal when a 1727 device goes through a reboot. This can be mitigated by the device 1728 storing the precise state of sender sequence number and replay window 1729 on a clean shutdown. 1731 The length of message fields can reveal information about the 1732 message. Applications may use a padding scheme to protect against 1733 traffic analysis. As an example, the strings "YES" and "NO" even if 1734 encrypted can be distinguished from each other as there is no padding 1735 supplied by the current set of encryption algorithms. Some 1736 information can be determined even from looking at boundary 1737 conditions. An example of this would be returning an integer between 1738 0 and 100 where lengths of 1, 2 and 3 will provide information about 1739 where in the range things are. Three different methods to deal with 1740 this are: 1) ensure that all messages are the same length. For 1741 example, using 0 and 1 instead of 'yes' and 'no'. 2) Use a character 1742 which is not part of the responses to pad to a fixed length. For 1743 example, pad with a space to three characters. 3) Use the PKCS #7 1744 style padding scheme where m bytes are appended each having the value 1745 of m. For example, appending a 0 to "YES" and two 1's to "NO". This 1746 style of padding means that all values need to be padded. Similar 1747 arguments apply to other message fields such as resource names. 1749 13. IANA Considerations 1751 Note to RFC Editor: Please replace all occurrences of "[[this 1752 document]]" with the RFC number of this specification. 1754 13.1. CoAP Option Numbers Registry 1756 The Object-Security option is added to the CoAP Option Numbers 1757 registry: 1759 +--------+-----------------+-------------------+ 1760 | Number | Name | Reference | 1761 +--------+-----------------+-------------------+ 1762 | TBD | Object-Security | [[this document]] | 1763 +--------+-----------------+-------------------+ 1765 13.2. Header Field Registrations 1767 The HTTP header field Object-Security is added to the Message Headers 1768 registry: 1770 +-------------------+----------+----------+-------------------+ 1771 | Header Field Name | Protocol | Status | Reference | 1772 +-------------------+----------+----------+-------------------+ 1773 | Object-Security | http | standard | [[this document]] | 1774 +-------------------+----------+----------+-------------------+ 1776 14. Acknowledgments 1778 The following individuals provided input to this document: Christian 1779 Amsuess, Tobias Andersson, Carsten Bormann, Joakim Brorsson, Thomas 1780 Fossati, Martin Gunnarsson, Klaus Hartke, Jim Schaad, Dave Thaler, 1781 Marco Tiloca, and Malisa Vučinić. 1783 Ludwig Seitz and Goeran Selander worked on this document as part of 1784 the CelticPlus project CyberWI, with funding from Vinnova. 1786 15. References 1788 15.1. Normative References 1790 [I-D.amsuess-core-repeat-request-tag] 1791 Amsuess, C., Mattsson, J., and G. Selander, "Repeat And 1792 Request-Tag", draft-amsuess-core-repeat-request-tag-00 1793 (work in progress), July 2017. 1795 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1796 Requirement Levels", BCP 14, RFC 2119, 1797 DOI 10.17487/RFC2119, March 1997, 1798 . 1800 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1801 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 1802 . 1804 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 1805 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 1806 January 2012, . 1808 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1809 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1810 October 2013, . 1812 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1813 Application Protocol (CoAP)", RFC 7252, 1814 DOI 10.17487/RFC7252, June 2014, 1815 . 1817 [RFC7641] Hartke, K., "Observing Resources in the Constrained 1818 Application Protocol (CoAP)", RFC 7641, 1819 DOI 10.17487/RFC7641, September 2015, 1820 . 1822 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 1823 the Constrained Application Protocol (CoAP)", RFC 7959, 1824 DOI 10.17487/RFC7959, August 2016, 1825 . 1827 [RFC8075] Castellani, A., Loreto, S., Rahman, A., Fossati, T., and 1828 E. Dijk, "Guidelines for Mapping Implementations: HTTP to 1829 the Constrained Application Protocol (CoAP)", RFC 8075, 1830 DOI 10.17487/RFC8075, February 2017, 1831 . 1833 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 1834 FETCH Methods for the Constrained Application Protocol 1835 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 1836 . 1838 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 1839 RFC 8152, DOI 10.17487/RFC8152, July 2017, 1840 . 1842 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 1843 DOI 10.17487/RFC8288, October 2017, 1844 . 1846 15.2. Informative References 1848 [I-D.bormann-6lo-coap-802-15-ie] 1849 Bormann, C., "Constrained Application Protocol (CoAP) over 1850 IEEE 802.15.4 Information Element for IETF", draft- 1851 bormann-6lo-coap-802-15-ie-00 (work in progress), April 1852 2016. 1854 [I-D.greevenbosch-appsawg-cbor-cddl] 1855 Birkholz, H., Vigano, C., and C. Bormann, "Concise data 1856 definition language (CDDL): a notational convention to 1857 express CBOR data structures", draft-greevenbosch-appsawg- 1858 cbor-cddl-11 (work in progress), July 2017. 1860 [I-D.hartke-core-e2e-security-reqs] 1861 Selander, G., Palombini, F., and K. Hartke, "Requirements 1862 for CoAP End-To-End Security", draft-hartke-core-e2e- 1863 security-reqs-03 (work in progress), July 2017. 1865 [I-D.ietf-ace-oauth-authz] 1866 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 1867 H. Tschofenig, "Authentication and Authorization for 1868 Constrained Environments (ACE)", draft-ietf-ace-oauth- 1869 authz-07 (work in progress), August 2017. 1871 [I-D.ietf-core-coap-tcp-tls] 1872 Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 1873 Silverajan, B., and B. Raymor, "CoAP (Constrained 1874 Application Protocol) over TCP, TLS, and WebSockets", 1875 draft-ietf-core-coap-tcp-tls-09 (work in progress), May 1876 2017. 1878 [I-D.mattsson-core-coap-actuators] 1879 Mattsson, J., Fornehed, J., Selander, G., and F. 1880 Palombini, "Controlling Actuators with CoAP", draft- 1881 mattsson-core-coap-actuators-02 (work in progress), 1882 November 2016. 1884 [I-D.seitz-ace-oscoap-profile] 1885 Seitz, L., Palombini, F., and M. Gunnarsson, "OSCOAP 1886 profile of the Authentication and Authorization for 1887 Constrained Environments Framework", draft-seitz-ace- 1888 oscoap-profile-05 (work in progress), October 2017. 1890 [I-D.tiloca-core-multicast-oscoap] 1891 Tiloca, M., Selander, G., and F. Palombini, "Secure group 1892 communication for CoAP", draft-tiloca-core-multicast- 1893 oscoap-03 (work in progress), July 2017. 1895 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1896 Resource Identifier (URI): Generic Syntax", STD 66, 1897 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1898 . 1900 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 1901 Key Derivation Function (HKDF)", RFC 5869, 1902 DOI 10.17487/RFC5869, May 2010, 1903 . 1905 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 1906 Constrained-Node Networks", RFC 7228, 1907 DOI 10.17487/RFC7228, May 2014, 1908 . 1910 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 1911 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 1912 2015, . 1914 Appendix A. Test Vectors 1916 TODO: This section needs to be updated. 1918 Appendix B. Examples 1920 This section gives examples of OSCORE. The message exchanges are 1921 made, based on the assumption that there is a security context 1922 established between client and server. For simplicity, these 1923 examples only indicate the content of the messages without going into 1924 detail of the (compressed) COSE message format. 1926 B.1. Secure Access to Sensor 1928 This example targets the scenario in Section 3.1 of 1929 [I-D.hartke-core-e2e-security-reqs] and illustrates a client 1930 requesting the alarm status from a server. 1932 Client Proxy Server 1933 | | | 1934 +------>| | Code: 0.02 (POST) 1935 | POST | | Token: 0x8c 1936 | | | Object-Security: [kid:5f,Partial IV:42] 1937 | | | Payload: {Code:0.01, 1938 | | | Uri-Path:"alarm_status"} 1939 | | | 1940 | +------>| Code: 0.02 (POST) 1941 | | POST | Token: 0x7b 1942 | | | Object-Security: [kid:5f,Partial IV:42] 1943 | | | Payload: {Code:0.01, 1944 | | | Uri-Path:"alarm_status"} 1945 | | | 1946 | |<------+ Code: 2.04 (Changed) 1947 | | 2.04 | Token: 0x7b 1948 | | | Object-Security: - 1949 | | | Payload: {Code:2.05, "OFF"} 1950 | | | 1951 |<------+ | Code: 2.04 (Changed) 1952 | 2.04 | | Token: 0x8c 1953 | | | Object-Security: - 1954 | | | Payload: {Code:2.05, "OFF"} 1955 | | | 1957 Figure 8: Secure Access to Sensor. Square brackets [ ... ] indicate 1958 content of compressed COSE object. Curly brackets { ... } indicate 1959 encrypted data. 1961 The request/response Codes are encrypted by OSCORE and only dummy 1962 Codes (POST/Changed) are visible in the header of the OSCORE message. 1963 The option Uri-Path ("alarm_status") and payload ("OFF") are 1964 encrypted. 1966 The COSE header of the request contains an identifier (5f), 1967 indicating which security context was used to protect the message and 1968 a Partial IV (42). 1970 The server verifies that the Partial IV has not been received before. 1971 The client verifies that the response is bound to the request. 1973 B.2. Secure Subscribe to Sensor 1975 This example targets the scenario in Section 3.2 of 1976 [I-D.hartke-core-e2e-security-reqs] and illustrates a client 1977 requesting subscription to a blood sugar measurement resource (GET 1978 /glucose), first receiving the value 220 mg/dl and then a second 1979 value 180 mg/dl. 1981 Client Proxy Server 1982 | | | 1983 +------>| | Code: 0.05 (FETCH) 1984 | FETCH | | Token: 0x83 1985 | | | Observe: 0 1986 | | | Object-Security: [kid:ca,Partial IV:15] 1987 | | | Payload: {Code:0.01, 1988 | | | Uri-Path:"glucose"} 1989 | | | 1990 | +------>| Code: 0.05 (FETCH) 1991 | | FETCH | Token: 0xbe 1992 | | | Observe: 0 1993 | | | Object-Security: [kid:ca,Partial IV:15] 1994 | | | Payload: {Code:0.01, 1995 | | | Uri-Path:"glucose"} 1996 | | | 1997 | |<------+ Code: 2.05 (Content) 1998 | | 2.05 | Token: 0xbe 1999 | | | Observe: 7 2000 | | | Object-Security: [Partial IV:32] 2001 | | | Payload: {Code:2.05, 2002 | | | Content-Format:0, "220"} 2003 | | | 2004 |<------+ | Code: 2.05 (Content) 2005 | 2.05 | | Token: 0x83 2006 | | | Observe: 7 2007 | | | Object-Security: [Partial IV:32] 2008 | | | Payload: {Code:2.05, 2009 | | | Content-Format:0, "220"} 2010 ... ... ... 2011 | | | 2012 | |<------+ Code: 2.05 (Content) 2013 | | 2.05 | Token: 0xbe 2014 | | | Observe: 8 2015 | | | Object-Security: [Partial IV:36] 2016 | | | Payload: {Code:2.05, 2017 | | | Content-Format:0, "180"} 2018 | | | 2019 |<------+ | Code: 2.05 (Content) 2020 | 2.05 | | Token: 0x83 2021 | | | Observe: 8 2022 | | | Object-Security: [Partial IV:36] 2023 | | | Payload: {Code:2.05, 2024 | | | Content-Format:0, "180"} 2025 | | | 2027 Figure 9: Secure Subscribe to Sensor. Square brackets [ ... ] 2028 indicate content of compressed COSE header. Curly brackets { ... } 2029 indicate encrypted data. 2031 The request/response Codes are encrypted by OSCORE and only dummy 2032 Codes (FETCH/Content) are visible in the header of the OSCORE 2033 message. The options Content-Format (0) and the payload ("220" and 2034 "180"), are encrypted. 2036 The COSE header of the request contains an identifier (ca), 2037 indicating the security context used to protect the message and a 2038 Partial IV (15). The COSE headers of the responses contains Partial 2039 IVs (32 and 36). 2041 The server verifies that the Partial IV has not been received before. 2042 The client verifies that the responses are bound to the request and 2043 that the Partial IVs are greater than any Partial IV previously 2044 received in a response bound to the request. 2046 Authors' Addresses 2048 Goeran Selander 2049 Ericsson AB 2051 Email: goran.selander@ericsson.com 2053 John Mattsson 2054 Ericsson AB 2056 Email: john.mattsson@ericsson.com 2058 Francesca Palombini 2059 Ericsson AB 2061 Email: francesca.palombini@ericsson.com 2062 Ludwig Seitz 2063 SICS Swedish ICT 2065 Email: ludwig@sics.se