idnits 2.17.1 draft-selander-ace-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 11, 2016) is 2751 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) == Outdated reference: A later version (-24) exists of draft-ietf-cose-msg-20 ** Obsolete normative reference: RFC 6347 (Obsoleted by RFC 9147) == Outdated reference: A later version (-03) exists of draft-hartke-core-e2e-security-reqs-01 == Outdated reference: A later version (-46) exists of draft-ietf-ace-oauth-authz-02 == Outdated reference: A later version (-11) exists of draft-ietf-core-coap-tcp-tls-04 == Outdated reference: A later version (-06) exists of draft-seitz-ace-oscoap-profile-00 == Outdated reference: A later version (-14) exists of draft-selander-ace-cose-ecdhe-02 Summary: 1 error (**), 0 flaws (~~), 7 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 ACE Working Group G. Selander 3 Internet-Draft J. Mattsson 4 Intended status: Standards Track F. Palombini 5 Expires: April 14, 2017 Ericsson AB 6 L. Seitz 7 SICS Swedish ICT 8 October 11, 2016 10 Object Security of CoAP (OSCOAP) 11 draft-selander-ace-object-security-06 13 Abstract 15 This memo defines Object Security of CoAP (OSCOAP), a method for 16 application layer protection of message exchanges with the 17 Constrained Application Protocol (CoAP), using the CBOR Object 18 Signing and Encryption (COSE) format. OSCOAP provides end-to-end 19 encryption, integrity and replay protection to CoAP payload, options, 20 and header fields, as well as a secure binding between CoAP request 21 and response messages. The use of OSCOAP is signaled with the CoAP 22 option Object-Security, also defined in this memo. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at http://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on April 14, 2017. 41 Copyright Notice 43 Copyright (c) 2016 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (http://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 59 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 60 2. The Object-Security Option . . . . . . . . . . . . . . . . . 5 61 3. The Security Context . . . . . . . . . . . . . . . . . . . . 6 62 3.1. Security Context Definition . . . . . . . . . . . . . . . 6 63 3.2. Security Context Establishment . . . . . . . . . . . . . 9 64 3.2.1. Derivation of Sender Key/IV, Recipient Key/IV . . . . 9 65 3.2.2. Sequence Numbers and Replay Window . . . . . . . . . 10 66 3.2.3. Context Identifier and Sender/Recipient ID . . . . . 10 67 4. Protected CoAP Message Fields . . . . . . . . . . . . . . . . 11 68 5. The COSE Object . . . . . . . . . . . . . . . . . . . . . . . 13 69 5.1. Plaintext . . . . . . . . . . . . . . . . . . . . . . . . 15 70 5.2. Additional Authenticated Data . . . . . . . . . . . . . . 15 71 6. Protecting CoAP Messages . . . . . . . . . . . . . . . . . . 17 72 6.1. Replay and Freshness Protection . . . . . . . . . . . . . 17 73 6.2. Protecting the Request . . . . . . . . . . . . . . . . . 18 74 6.3. Verifying the Request . . . . . . . . . . . . . . . . . . 19 75 6.4. Protecting the Response . . . . . . . . . . . . . . . . . 20 76 6.5. Verifying the Response . . . . . . . . . . . . . . . . . 21 77 7. Security Considerations . . . . . . . . . . . . . . . . . . . 21 78 8. Privacy Considerations . . . . . . . . . . . . . . . . . . . 23 79 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 80 9.1. Sid Registration . . . . . . . . . . . . . . . . . . . . 24 81 9.2. CoAP Option Number Registration . . . . . . . . . . . . . 24 82 9.3. Media Type Registrations . . . . . . . . . . . . . . . . 24 83 9.4. CoAP Content Format Registration . . . . . . . . . . . . 25 84 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 26 85 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 26 86 11.1. Normative References . . . . . . . . . . . . . . . . . . 26 87 11.2. Informative References . . . . . . . . . . . . . . . . . 27 88 Appendix A. Overhead . . . . . . . . . . . . . . . . . . . . . . 28 89 A.1. Length of the Object-Security Option . . . . . . . . . . 28 90 A.2. Size of the COSE Object . . . . . . . . . . . . . . . . . 28 91 A.3. Message Expansion . . . . . . . . . . . . . . . . . . . . 29 92 A.4. Example . . . . . . . . . . . . . . . . . . . . . . . . . 29 93 Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 30 94 B.1. Secure Access to Sensor . . . . . . . . . . . . . . . . . 31 95 B.2. Secure Subscribe to Sensor . . . . . . . . . . . . . . . 32 96 Appendix C. Object Security of Content (OSCON) . . . . . . . . . 34 97 C.1. Overhead OSCON . . . . . . . . . . . . . . . . . . . . . 35 98 C.2. MAC Only . . . . . . . . . . . . . . . . . . . . . . . . 35 99 C.3. Signature Only . . . . . . . . . . . . . . . . . . . . . 36 100 C.4. Authenticated Encryption with Additional Data (AEAD) . . 37 101 C.5. Symmetric Encryption with Asymmetric Signature (SEAS) . . 38 102 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 38 104 1. Introduction 106 The Constrained Application Protocol (CoAP) [RFC7252] is a web 107 application protocol, designed for constrained nodes and networks 108 [RFC7228]. CoAP specifies the use of proxies for scalability and 109 efficiency. At the same time CoAP references DTLS [RFC6347] for 110 security. Proxy operations on CoAP messages require DTLS to be 111 terminated at the proxy. The proxy therefore not only has access to 112 the data required for performing the intended proxy functionality, 113 but is also able to eavesdrop on, or manipulate any part of the CoAP 114 payload and metadata, in transit between client and server. The 115 proxy can also inject, delete, or reorder packages without being 116 protected or detected by DTLS. 118 This memo defines Object Security of CoAP (OSCOAP), a data object 119 based security protocol, protecting CoAP message exchanges end-to- 120 end, across intermediary nodes. An analysis of end-to-end security 121 for CoAP messages through intermediary nodes is performed in 122 [I-D.hartke-core-e2e-security-reqs], this specification addresses the 123 forwarding case. 125 The solution provides an in-layer security protocol for CoAP which 126 does not depend on underlying layers and is therefore favorable for 127 providing security for "CoAP over foo", e.g. CoAP messages passing 128 over both unreliable and reliable transport 129 [I-D.ietf-core-coap-tcp-tls], CoAP over IEEE 802.15.4 IE 130 [I-D.bormann-6lo-coap-802-15-ie]. 132 OSCOAP builds on CBOR Object Signing and Encryption (COSE) 133 [I-D.ietf-cose-msg], providing end-to-end encryption, integrity, and 134 replay protection. The use of OSCOAP is signaled with the CoAP 135 option Object-Security, also defined in this memo. The solution 136 transforms an unprotected CoAP message into a protected CoAP message 137 in the following way: the unprotected CoAP message is protected by 138 including payload (if present), certain options, and header fields in 139 a COSE object. The message fields that have been encrypted are 140 removed from the message whereas the Object-Security option and the 141 COSE object are added. We call the result the "protected" CoAP 142 message. Thus OSCOAP is a security protocol based on the exchange of 143 protected CoAP messages (see Figure 1). 145 Client Server 146 | request: | 147 | GET example.com | 148 | [Header, Token, Options:{..., | 149 | Object-Security:COSE object}] | 150 +---------------------------------------------->| 151 | response: | 152 | 2.05 (Content) | 153 | [Header, Token, Options:{..., | 154 | Object-Security:-}, Payload:COSE object] | 155 |<----------------------------------------------+ 156 | | 158 Figure 1: Sketch of OSCOAP 160 OSCOAP provides protection of CoAP payload, certain options, and 161 header fields, as well as a secure binding between CoAP request and 162 response messages, and freshness of requests and responses. It may 163 be used in extremely constrained settings, where DTLS cannot be 164 supported. Alternatively, OSCOAP can be combined with DTLS, thereby 165 enabling end-to-end security of CoAP payload, in combination with 166 hop-by-hop protection of the entire CoAP message, during transport 167 between end-point and intermediary node. Examples of the use of 168 OSCOAP are given in Appendix B. 170 The message protection provided by OSCOAP can alternatively be 171 applied only to the payload of individual messages. We call this 172 object security of content (OSCON) and it is defined in Appendix C. 174 1.1. Terminology 176 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 177 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 178 document are to be interpreted as described in [RFC2119]. These 179 words may also appear in this document in lowercase, absent their 180 normative meanings. 182 Readers are expected to be familiar with the terms and concepts 183 described in [RFC7252] and [RFC7641]. 185 Terminology for constrained environments, such as "constrained 186 device", "constrained-node network", is defined in [RFC7228]. 188 Two different scopes of object security are defined: 190 o OSCOAP = object security of CoAP, signaled with the Object- 191 Security option. 193 o OSCON = object security of content, signaled with Content Format/ 194 Media Type set to application/oscon (defined in Appendix C). 196 2. The Object-Security Option 198 The Object-Security option indicates that OSCOAP is used to protect 199 the CoAP message exchange. The protection is achieved by means of a 200 COSE object included in the protected CoAP message, as detailed in 201 Section 5. 203 The Object-Security option is critical, safe to forward, part of the 204 cache key, and not repeatable. Figure 2 illustrates the structure of 205 the Object-Security option. 207 A CoAP proxy SHOULD NOT cache a response to a request with an Object- 208 Security option, since the response is only applicable to the 209 original client's request. The Object-Security option is included in 210 the cache key for backward compatibility with proxies not recognizing 211 the Object-Security option. The effect of this is that messages with 212 the Object-Security option will never generate cache hits. To 213 further prevent caching, a Max-Age option with value zero SHOULD be 214 added to the protected CoAP responses. 216 +-----+---+---+---+---+-----------------+--------+--------+ 217 | No. | C | U | N | R | Name | Format | Length | 218 +-----+---+---+---+---+-----------------+--------+--------| 219 | TBD | x | | | | Object-Security | opaque | 0- | 220 +-----+---+---+---+---+-----------------+--------+--------+ 221 C=Critical, U=Unsafe, N=NoCacheKey, R=Repeatable 223 Figure 2: The Object-Security Option 225 The length of the Object-Security option depends on whether the 226 unprotected message has payload, on the set of options that are 227 included in the unprotected message, the length of the integrity tag, 228 and the length of the information identifying the security context. 230 o If the unprotected message has payload, then the COSE object is 231 the payload of the protected message (see Section 6.2 and 232 Section 6.4), and the Object-Security option has length zero. An 233 endpoint receiving a CoAP message with payload, that also contains 234 a non-empty Object-Security option SHALL treat it as malformed and 235 reject it. 237 o If the unprotected message does not have payload, then the COSE 238 object is the value of the Object-Security option and the length 239 of the Object-Security option is equal to the size of the COSE 240 object. An endpoint receiving a CoAP message without payload, 241 that also contains an empty Object-Security option SHALL treat it 242 as malformed and reject it. 244 More details about the message overhead caused by the Object-Security 245 option is given in Appendix A. 247 3. The Security Context 249 OSCOAP uses COSE with an Authenticated Encryption with Additional 250 Data (AEAD) algorithm. The specification requires that client and 251 server establish a security context to apply to the COSE objects 252 protecting the CoAP messages. In this section we define the security 253 context, and also specify how to establish a security context in 254 client and server based on common shared secret material and a key 255 derivation function (KDF). 257 The EDHOC protocol [I-D.selander-ace-cose-ecdhe] enables the 258 establishment of secret material with the property of forward 259 secrecy, and negotiation of KDF and AEAD, it thus provides all 260 necessary pre-requisite steps for using OSCOAP as defined here. 262 3.1. Security Context Definition 264 The security context is the set of information elements necessary to 265 carry out the cryptographic operations in OSCOAP. Each security 266 context is identified by a Context Identifier. A Context Identifier 267 that is no longer in use can be reassigned to a new security context. 269 For each endpoint, the security context is composed by a "Common 270 Context", a "Sender Context" and a "Recipient Context". The Common 271 Context includes common security material. The endpoint protects the 272 messages sent using the Sender Context. The endpoint verifies the 273 messages received using the Recipient Context. In communication 274 between two endpoints, the Sender Context of one endpoint matches the 275 Recipient Context of the other endpoint, and vice versa. Note that, 276 because of that, the two security contexts identified by the same 277 Context Identifiers in the two endpoints are not the same, but they 278 are partly mirrored. 280 An example is shown in Figure 3. 282 .-Cid = Cid1-. .-Cid = Cid1-. 283 | context: | | context: | 284 | Alg, | | Alg, | 285 | Sender, | | Recipient,| 286 | Recipient | | Sender | 287 '------------' '------------' 288 Client Server 289 | | 290 Retrieve context for | request: | 291 target resource | [Token = Token1, | 292 Protect request with | Cid=Cid1, ...] | 293 Sender +---------------------->| Retrieve context with 294 | | Cid = Cid1 295 | | Verify request with 296 | | Recipient 297 | response: | Protect response with 298 | [Token = Token1, ...]| Sender 299 Retrieve context with |<----------------------+ 300 Token = Token1 | | 301 Verify request with | | 302 Recipient | | 304 Figure 3: Retrieval and use of the Security Context 306 The Common Context structure contains the following parameters: 308 o Context Identifier (Cid). Variable length byte string that 309 identifies the security context. Its value is immutable once the 310 security context is established. 312 o Algorithm (Alg). Value that identifies the COSE AEAD algorithm to 313 use for encryption. Its value is immutable once the security 314 context is established. 316 o Base Key (base_key). Byte string containing the key used to 317 derive the security context Section 3.2. 319 The Sender Context structure contains the following parameters: 321 o Sender ID. Variable length byte string identifying oneself. Its 322 value is immutable once the security context is established. 324 o Sender Key. Byte string containing the symmetric key to protect 325 messages to send. Length is determined by Algorithm. Its value 326 is immutable once the security context is established. 328 o Sender IV. Byte string containing the fixed portion of IV 329 (context IV in [I-D.ietf-cose-msg]) to protect messages to send. 331 Length is determined by Algorithm. Its value is immutable once 332 the security context is established. 334 o Sender Sequence Number. Non-negative integer enumerating the COSE 335 objects that the endpoint sends, associated to the Context 336 Identifier. It is used for replay protection, and to generate 337 unique IVs for the AEAD. Maximum value is determined by 338 Algorithm. 340 The Recipient Context structure contains the following parameters: 342 o Recipient ID. Variable length byte string identifying the 343 endpoint messages are received from or sent to. Its value is 344 immutable once the security context is established. 346 o Recipient Key. Byte string containing the symmetric key to verify 347 messages received. Length is determined by the Algorithm. Its 348 value is immutable once the security context is established. 350 o Recipient IV. Byte string containing the context IV to verify 351 messages received. Length is determined by Algorithm. Its value 352 is immutable once the security context is established. 354 o Recipient Sequence Number. Non-negative integer enumerating the 355 COSE objects received, associated to the Context Identifier. It 356 is used for replay protection, and to generate unique IVs for the 357 AEAD. Maximum value is determined by Algorithm. 359 o Replay Window. The replay protection window for messages 360 received, equivalent to the functionality described in 361 Section 4.1.2.6 of [RFC6347]. 363 The 3-tuple (Cid, Sender ID, Sender Sequence Number) is called 364 Transaction Identifier (Tid), and SHALL be unique for each COSE 365 object and server. The Tid is used as a unique challenge in the COSE 366 object of the protected CoAP request. The Tid is part of the 367 Additional Authenticated Data (AAD, see Section 5) of the protected 368 CoAP response message, which is how the challenge becomes signed by 369 the server. 371 The client and server may change roles while maintaining the same 372 security context. The former server will then make the request using 373 the Sender Context, the former client will verify the request using 374 its Recipient Context etc. 376 3.2. Security Context Establishment 378 This section aims at describing how to establish the security 379 context, given some input parameters. The input parameters, which 380 are established in a previous phase, are: 382 o Context Identifier (Cid) 384 o Algorithm (Alg) 386 o Base Key (base_key) 388 o Sender ID 390 o Recipient ID 392 o Replay Window (optionally) 394 These are included unchanged in the security context. We give below 395 some indications on how applications should select these parameters. 396 Moreover, the following parameters are established as described 397 below: 399 o Sender Key 401 o Sender IV 403 o Sender Sequence Number 405 o Recipient Key 407 o Recipient IV 409 o Recipient Sequence Number 411 o Replay Window 413 3.2.1. Derivation of Sender Key/IV, Recipient Key/IV 415 Given a common shared secret material and a common key derivation 416 function, the client and server can derive the security context 417 necessary to run OSCOAP. The derivation procedure described here 418 MUST NOT be executed more than once on a set of common secret 419 material. Also, the same base_key SHOULD NOT be used in different 420 security contexts (identified by different Cids). 422 The procedure assumes that the common shared secret material is 423 uniformly random and that the key derivation function is HKDF 425 [RFC5869]. This is for example the case after having used EDHOC 426 [I-D.selander-ace-cose-ecdhe]. 428 Assumptions: 430 o The hash function, denoted HKDF, is the HMAC based key derivation 431 function defined in [RFC5869] with specified hash function 433 o The common shared secret material, denoted base_key, is uniformly 434 pseudo-random of length at least equal to the output of the 435 specified hash function 437 The security context parameters Sender Key/IV, Recipient Key/IV SHALL 438 be derived using the HKDF-Expand primitive [RFC5869]: 440 output parameter = HKDF-Expand(base_key, info, key_length), 442 where: 444 o base_key is defined above 446 o info = Cid || Sender ID/Recipient ID || "IV"/"Key" || Algorithm || 447 key_length 449 o key_length is the key size of the AEAD algorithm 451 The Sender/Recipient Key shall be derived using the Cid concatenated 452 with the Sender/Recipient ID, the label "Key", the Algorithm and the 453 key_length. The Sender/Recipient IV shall be derived using the Cid 454 concatenated with the Sender/Recipient ID, the label "IV", the 455 Algorithm and the key_length. 457 For example, for the algorithm AES-CCM-64-64-128 (see Section 10.2 in 458 [I-D.ietf-cose-msg]), key_length for the keys is 128 bits and 459 key_length for the context IVs is 56 bits. 461 3.2.2. Sequence Numbers and Replay Window 463 The values of the Sequence Numbers are initialized to 0 during 464 establishment of the security context. The default Replay Window 465 size of 64 is used if no input parameter is provided in the set up 466 phase. 468 3.2.3. Context Identifier and Sender/Recipient ID 470 As mentioned, Cid, Sender ID and Recipient ID are established in a 471 previous phase. How this is done is application specific, but some 472 guidelines are given in this section. 474 It is RECOMMENDED that the application uses 64-bits long pseudo- 475 random Cids, in order to have globally unique Context Identifiers. 476 Cid SHOULD be unique in the sets of all security contexts used by all 477 the endpoints. If it is not the case, it is the role of the 478 application to specify how to handle collisions. 480 In the same phase during which the Cid is established in the 481 endpoint, the application informs the endpoint what resource can be 482 accessed using the corresponding security context. The granularity 483 of that is decided by the application (resource, host, etc). The 484 endpoint SHALL save the association resource-Cid, in order to be able 485 to retrieve the correct security context to access a resource. 487 The Sender ID and Recipient ID are also established in the endpoint 488 during the previous set up phase. The application SHOULD make sure 489 that these identifiers are locally unique in the set of all endpoints 490 using the same security context. If it is not the case, it is again 491 the role of the application to specify how to handle collisions. 493 In case of EDHOC [I-D.selander-ace-cose-ecdhe]) the Cid is the hash 494 of the messages exchanged. 496 4. Protected CoAP Message Fields 498 This section defines how the CoAP message fields are protected. 499 OSCOAP protects as much of the unprotected CoAP message as possible, 500 while still allowing forward proxy operations 501 [I-D.hartke-core-e2e-security-reqs]. 503 The CoAP Payload SHALL be encrypted and integrity protected. 505 The CoAP Header fields Version and Code SHALL be integrity protected 506 but not encrypted. The CoAP Message Layer parameters, Type and 507 Message ID, as well as Token and Token Length SHALL neither be 508 integrity protected nor encrypted. 510 Protection of CoAP Options can be summarized as follows: 512 o To prevent information leakage, Uri-Path and Uri-Query SHALL be 513 encrypted. As a consequence, if Proxy-Uri is used, those parts of 514 the URI SHALL be removed from the Proxy-Uri. The CoAP Options Uri- 515 Host, Uri-Port, Proxy-Uri, and Proxy-Scheme SHALL neither be 516 encrypted, nor integrity protected (cf. protection of the 517 effective request URI in Section 5.2). 519 o The other CoAP options SHALL be encrypted and integrity protected. 521 A summary of which options are encrypted or integrity protected is 522 shown in Figure 4. 524 +----+---+---+---+---+----------------+--------+--------+---+---+ 525 | No.| C | U | N | R | Name | Format | Length | E | D | 526 +----+---+---+---+---+----------------+--------+--------+---+---+ 527 | 1 | x | | | x | If-Match | opaque | 0-8 | x | | 528 | 3 | x | x | - | | Uri-Host | string | 1-255 | | | 529 | 4 | | | | x | ETag | opaque | 1-8 | x | | 530 | 5 | x | | | | If-None-Match | empty | 0 | x | | 531 | 6 | | x | - | | Observe | uint | 0-3 | x | x | 532 | 7 | x | x | - | | Uri-Port | uint | 0-2 | | | 533 | 8 | | | | x | Location-Path | string | 0-255 | x | | 534 | 11 | x | x | - | x | Uri-Path | string | 0-255 | x | | 535 | 12 | | | | | Content-Format | uint | 0-2 | x | | 536 | 14 | | x | - | | Max-Age | uint | 0-4 | x | x | 537 | 15 | x | x | - | x | Uri-Query | string | 0-255 | x | | 538 | 17 | x | | | | Accept | uint | 0-2 | x | | 539 | 20 | | | | x | Location-Query | string | 0-255 | x | | 540 | 23 | x | x | - | - | Block2 | uint | 0-3 | x | x | 541 | 27 | x | x | - | - | Block1 | uint | 0-3 | x | x | 542 | 28 | | | x | | Size2 | unit | 0-4 | x | x | 543 | 35 | x | x | - | | Proxy-Uri | string | 1-1034 | | | 544 | 39 | x | x | - | | Proxy-Scheme | string | 1-255 | | | 545 | 60 | | | x | | Size1 | uint | 0-4 | x | x | 546 +----+---+---+---+---+----------------+--------+--------+---+---+ 547 C=Critical, U=Unsafe, N=NoCacheKey, R=Repeatable, 548 E=Encrypt and Integrity Protect, D=Duplicate. 550 Figure 4: Protection of CoAP Options 552 Unless specified otherwise, CoAP options not listed in Figure 4 SHALL 553 be encrypted and integrity protected. 555 The encrypted options are in general omitted from the protected CoAP 556 message and not visible to intermediary nodes (see Section 6.2 and 557 Section 6.4). Hence the actions resulting from the use of 558 corresponding options is analogous to the case of communicating 559 directly with the endpoint. For example, a client using an ETag 560 option will not be served by a proxy. 562 However, some options which are encrypted need to be readable in the 563 protected CoAP message to support certain proxy functions. A CoAP 564 option which may be both encrypted in the COSE object of the 565 protected CoAP message, and also unencrypted as CoAP option in the 566 protected CoAP message, is called "duplicate". The "encrypted" value 567 of a duplicate option is intended for the destination endpoint and 568 the "unencrypted" value is intended for a proxy. The unencrypted 569 value is not integrity protected. 571 o The Max-Age option is duplicate. The unencrypted Max-Age SHOULD 572 have value zero to prevent caching of responses. The encrypted 573 Max-Age is used as defined in [RFC7252] taking into account that 574 it is not accessible to proxies. 576 o The Observe option is duplicate. If Observe is used, then the 577 encrypted Observe and the unencrypted Observe SHALL have the same 578 value. The Observe option as used here targets the requirements 579 on forwarding of [I-D.hartke-core-e2e-security-reqs] 580 (Section 2.2.1.2). 582 o The block options Block1 and Block2 are duplicate. The encrypted 583 block options is used for end-to-end secure fragmentation of 584 payload into blocks and protected information about the 585 fragmentation (block number, last block, etc.). The MAC from each 586 block is included in the calculation of the MAC for the next 587 block's (see Section 5.2). In this way, each block in ordered 588 sequence from the first block can be verified as it arrives. The 589 unencrypted block option allows for arbitrary proxy fragmentation 590 operations which cannot be verified by the endpoints. An 591 intermediary node can generate an arbitrarily long sequence of 592 blocks. However, since it is possible to protect fragmentation of 593 large messages, there SHALL be a security policy defining a 594 maximum unfragmented message size such that messages exceeding 595 this size SHALL be fragmented by the sending endpoint. Hence an 596 endpoint receiving fragments of a message that exceeds maximum 597 message size SHALL discard this message. 599 o The size options Size1 and Size2 are duplicate, analogously to the 600 block options. 602 Specifications of new CoAP options SHOULD specify how they are 603 processed with OSCOAP. New COAP options SHALL be encrypted and 604 integrity protected. New COAP options SHOULD NOT be duplicate unless 605 a forwarding proxy needs to read the option. If an option is 606 registered as duplicate, the duplicate value SHOULD NOT be the same 607 as the end-to-end value, unless the proxy is required by 608 specification to be able to read the end-to-end value. 610 5. The COSE Object 612 This section defines how to use the COSE format [I-D.ietf-cose-msg] 613 to wrap and protect data in the unprotected CoAP message. OSCOAP 614 uses the COSE_Encrypt0 structure with an Authenticated Encryption 615 with Additional Data (AEAD) algorithm. 617 The mandatory to support AEAD algorithm is AES-CCM-64-64-128 defined 618 in Section 10.2 of [I-D.ietf-cose-msg]. For AES-CCM-64-64-128 the 619 length of Sender Key and Recipient Key SHALL be 128 bits, the length 620 of IV, Sender IV, and Recipient IV SHALL be 7 bytes, and the maximum 621 Sender Sequence Number and Recipient Sequence Number SHALL be 2^56-1. 622 The IV is constructed using a Partial IV exactly like in Section 3.1 623 of [I-D.ietf-cose-msg], i.e. by padding the Sender Sequence Number or 624 the Recipient Sequence Number with zeroes and XORing it with the 625 Sender IV or Recipient IV, respectively. 627 Since OSCOAP only makes use of a single COSE structure, there is no 628 need to explicitly specify the structure, and OSCOAP uses the 629 untagged version of the COSE_Encrypt0 structure (Section 2. of 630 [I-D.ietf-cose-msg]). If the COSE object has a different structure, 631 the recipient MUST reject the message, treating it as malformed. 633 We denote by Plaintext the data that is encrypted and integrity 634 protected, and by Additional Authenticated Data (AAD) the data that 635 is integrity protected only, in the COSE object. 637 The fields of COSE_Encrypt0 structure are defined as follows (see 638 example in Appendix C.4). 640 o The "Headers" field is formed by: 642 * The "protected" field, which SHALL include: 644 + The "Partial IV" parameter. The value is set to the Sender 645 Sequence Number. The Partial IV is a byte string (type: 646 bstr), where the length is the minimum length needed to 647 encode the sequence number. An Endpoint that receives a 648 COSE object with a sequence number encoded with leading 649 zeroes (i.e. longer than the minimum needed length) SHALL 650 reject the corresponding message as malformed. 652 + If the message is a CoAP request, the "kid" parameter. The 653 value is set to the Context Identifier (see Section 3). 655 + Optionally, the parameter called "sid", defined below. The 656 value is set to the Sender ID (see Section 3). Note that 657 since this parameter is sent in clear, privacy issues SHOULD 658 be considered by the application defining the Sender ID. 660 * The "unprotected" field, which SHALL be empty. 662 o The "cipher text" field is computed from the Plaintext (see 663 Section 5.1) and the Additional Authenticated Data (AAD) (see 664 Section 5.2) and encoded as a byte string (type: bstr), following 665 Section 5.2 of [I-D.ietf-cose-msg]. 667 sid: This parameter is used to identify the sender of the message. 668 Applications MUST NOT assume that 'sid' values are unique. This 669 is not a security critical field. For this reason, it can be 670 placed in the unprotected headers bucket. 672 +------+-------+------------+----------------+-------------------+ 673 | name | label | value type | value registry | description | 674 +------+-------+------------+----------------+-------------------+ 675 | sid | TBD | bstr | | Sender identifier | 676 +------+-------+------------+----------------+-------------------+ 678 Table 1: Additional COSE Header Parameter 680 5.1. Plaintext 682 The Plaintext is formatted as a CoAP message without Header (see 683 Figure 5) consisting of: 685 o all CoAP Options present in the unprotected message which are 686 encrypted (see Section 4), in the order as given by the Option 687 number (each Option with Option Header including delta to previous 688 included encrypted option); and 690 o the CoAP Payload, if present, and in that case prefixed by the 691 one-byte Payload Marker (0xFF). 693 0 1 2 3 694 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 695 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 696 | Options to Encrypt (if any) ... ~ 697 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 698 |1 1 1 1 1 1 1 1| Payload (if any) ... ~ 699 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 700 (only if there 701 is payload) 703 Figure 5: Plaintext 705 5.2. Additional Authenticated Data 707 The Additional Authenticated Data ("Enc_structure") as described is 708 Section 5.3 of [I-D.ietf-cose-msg] includes: 710 o the "context" parameter, which has value "Encrypted" 711 o the "protected" parameter, which includes the "protected" part of 712 the "Headers" field; 714 o the "external_aad" is a serialized CBOR array (see Figure 8) that 715 contains, in the given order: 717 * ver: uint, contains the CoAP version number of the unprotected 718 CoAP message, as defined in Section 3 of [RFC7252] 720 * code: bstr, contains is the CoAP Code of the unprotected CoAP 721 message, as defined in Section 3 of [RFC7252]. 723 * alg: bstr, contains the serialized Algorithm from the security 724 context used for the exchange (see Section 3.1); 726 * request-uri: tstr, contains the plaintext "effective" request 727 URI composed from the request scheme and Uri-* options 728 according to the method described in Section 6.5 of [RFC7252], 729 if the message is a CoAP request; 731 * transaction-id: bstr, only included if the message to protect 732 or verify is a CoAP response, contains the Transaction 733 Identifier (Tid) of the associated CoAP request (see 734 Section 3). Note that the Tid is the 3-tuple (Cid, Sender ID, 735 Sender Sequence Number) for the endpoint sending the request 736 and verifying the response; which means that for the endpoint 737 sending the response, the Tid has value (Cid, Recipient ID, 738 seq), where seq is the value of the "Partial IV" in the COSE 739 object of the request (see Section 5); and 741 * mac-previous-block: bstr, contains the MAC of the message 742 containing the previous block in the sequence, as enumerated by 743 Block1 in the case of a request and Block2 in the case of a 744 response, if the message is fragmented using a block option 745 [RFC7959]. 747 external_aad_req = [ 748 ver : uint, 749 code : bstr, 750 alg : bstr, 751 request-uri : tstr, 752 ? mac-previous-block : bstr 753 ] 755 Figure 6: external_aad for a request 756 external_aad_resp = [ 757 ver : uint, 758 code : bstr, 759 alg : bstr, 760 transaction-id : bstr, 761 ? mac-previous-block : bstr 762 ] 764 Figure 7: external_aad for a response 766 external_aad = external_aad_req / external_aad_resp 768 Figure 8: external_aad 770 The encryption process is described in Section 5.3 of 771 [I-D.ietf-cose-msg]. 773 6. Protecting CoAP Messages 775 6.1. Replay and Freshness Protection 777 In order to protect from replay of messages and verify freshness, a 778 CoAP endpoint SHALL maintain a Sender Sequence Number, and a 779 Recipient Sequence Number associated to a security context, which is 780 identified with a Context Identifier (Cid). The two sequence numbers 781 are the highest sequence number the endpoint has sent and the highest 782 sequence number the endpoint has received. An endpoint uses the 783 Sender Sequence Number to protect messages to send and the Recipient 784 Sequence Number to verify received messages, as described in 785 Section 3. 787 Depending on use case and ordering of messages provided by underlying 788 layers, an endpoint MAY maintain a sliding replay window for Sequence 789 Numbers of received messages associated to each Cid. In case of 790 reliable transport, the receiving endpoint MAY require that the 791 Sequence Number of a received message equals last Sequence Number + 792 1. 794 A receiving endpoint SHALL verify that the Sequence Number received 795 in the COSE object has not been received before in the security 796 context identified by the Cid. The receiving endpoint SHALL also 797 reject messages with a sequence number greater than 2^56-1. 799 OSCOAP is a challenge-response protocol, where the response is 800 verified to match a prior request, by including the unique 801 transaction identifier (Tid as defined in Section 3) of the request 802 in the Additional Authenticated Data of the response message. 804 If a CoAP server receives a request with the Object-Security option, 805 then the server SHALL include the Tid of the request in the AAD of 806 the response, as described in Section 6.4. 808 If the CoAP client receives a response with the Object-Security 809 option, then the client SHALL verify the integrity of the response, 810 using the Tid of its own associated request in the AAD, as described 811 in Section 6.5. 813 6.2. Protecting the Request 815 Given an unprotected CoAP request, including header, options and 816 payload, the client SHALL perform the following steps to create a 817 protected CoAP request using a security context associated with the 818 target resource (see Section 3.2.3). 820 1. Increment the Sender Sequence Number by one (note that this means 821 that sequence number 0 is never used). If the Sender Sequence 822 Number exceeds the maximum number for the AEAD algorithm, the 823 client MUST NOT process any requests with the given security 824 context. The client SHOULD acquire a new security context (and 825 consequently inform the server about it) before this happens. 826 The latter is out of scope of this memo. 828 2. Compute the COSE object as specified in Section 5 830 * the IV in the AEAD is created by XORing the Sender IV (context 831 IV) with the Sender Sequence Number (partial IV). 833 * If the block option is used, the AAD includes the MAC from the 834 previous fragment sent (from the second fragment and 835 following) Section 5.2. This means that the endpoint MUST 836 store the MAC of each last-sent fragment to compute the 837 following. 839 * Note that the 'sid' field containing the Sender ID is included 840 in the COSE object (Section 5) if the application needs it. 842 3. Format the protected CoAP message as an ordinary CoAP message, 843 with the following Header, Options, and Payload, based on the 844 unprotected CoAP message: 846 * The CoAP header is the same as the unprotected CoAP message. 848 * The CoAP options which are encrypted and not duplicate 849 (Section 4) are removed. Any duplicate option which is 850 present has its unencrypted value. The Object-Security option 851 is added. 853 * If the message type of the unprotected CoAP message does not 854 allow Payload, then the value of the Object-Security option is 855 the COSE object. If the message type of the unprotected CoAP 856 message allows Payload, then the Object-Security option is 857 empty and the Payload of the protected CoAP message is the 858 COSE object. 860 4. Store in memory the association Token - Cid. The Client SHALL be 861 able to find the correct security context used to protect the 862 request and verify the response with use of the Token of the 863 message exchange. 865 6.3. Verifying the Request 867 A CoAP server receiving a message containing the Object-Security 868 option SHALL perform the following steps, using the security context 869 identified by the Context Identifier in the "kid" parameter in the 870 received COSE object: 872 1. Verify the Sequence Number in the Partial IV parameter, as 873 described in Section 6.1. If it cannot be verified that the 874 Sequence Number has not been received before, the server MUST 875 stop processing the request. 877 2. Recreate the Additional Authenticated Data, as described in 878 Section 5. 880 * If the block option is used, the AAD includes the MAC from the 881 previous fragment received (from the second fragment and 882 following) Section 5.2. This means that the endpoint MUST 883 store the MAC of each last-received fragment to compute the 884 following. 886 3. Compose the IV by XORing the Recipient IV (context IV) with the 887 Partial IV parameter, received in the COSE Object. 889 4. Retrieve the Recipient Key. 891 5. Verify and decrypt the message. If the verification fails, the 892 server MUST stop processing the request. 894 6. If the message verifies, update the Recipient Sequence Number or 895 Replay Window, as described in Section 6.1. 897 7. Restore the unprotected request by adding any decrypted options 898 or payload from the plaintext. Any duplicate options (Section 4) 899 are overwritten. The Object-Security option is removed. 901 6.4. Protecting the Response 903 A server receiving a valid request with a protected CoAP message 904 (i.e. containing an Object-Security option) SHALL respond with a 905 protected CoAP message. 907 Given an unprotected CoAP response, including header, options, and 908 payload, the server SHALL perform the following steps to create a 909 protected CoAP response, using the security context identified by the 910 Context Identifier of the received request: 912 1. Increment the Sender Sequence Number by one (note that this means 913 that sequence number 0 is never used). If the Sender Sequence 914 Number exceeds the maximum number for the AEAD algorithm, the 915 server MUST NOT process any more responses with the given 916 security context. The server SHOULD acquire a new security 917 context (and consequently inform the client about it) before this 918 happens. The latter is out of scope of this memo. 920 2. Compute the COSE object as specified in Section Section 5 922 * The IV in the AEAD is created by XORing the Sender IV (context 923 IV) and the Sender Sequence Number. 925 * If the block option is used, the AAD includes the MAC from the 926 previous fragment sent (from the second fragment and 927 following) Section 5.2. This means that the endpoint MUST 928 store the MAC of each last-sent fragment to compute the 929 following. 931 3. Format the protected CoAP message as an ordinary CoAP message, 932 with the following Header, Options, and Payload based on the 933 unprotected CoAP message: 935 * The CoAP header is the same as the unprotected CoAP message. 937 * The CoAP options which are encrypted and not duplicate 938 (Section 4) are removed. Any duplicate option which is 939 present has its unencrypted value. The Object-Security option 940 is added. 942 * If the message type of the unprotected CoAP message does not 943 allow Payload, then the value of the Object-Security option is 944 the COSE object. If the message type of the unprotected CoAP 945 message allows Payload, then the Object-Security option is 946 empty and the Payload of the protected CoAP message is the 947 COSE object. 949 Note the differences between generating a protected request, and a 950 protected response, for example whether "kid" is present in the 951 header, or whether Destination URI or Tid is present in the AAD, of 952 the COSE object. 954 6.5. Verifying the Response 956 A CoAP client receiving a message containing the Object-Security 957 option SHALL perform the following steps, using the security context 958 identified by the Token of the received response: 960 1. Verify the Sequence Number in the Partial IV parameter as 961 described in Section 6.1. If it cannot be verified that the 962 Sequence Number has not been received before, the client MUST 963 stop processing the response. 965 2. Recreate the Additional Authenticated Data as described in 966 Section 5. 968 * If the block option is used, the AAD includes the MAC from the 969 previous fragment received (from the second fragment and 970 following) Section 5.2. This means that the endpoint MUST 971 store the MAC of each last-received fragment to compute the 972 following. 974 3. Compose the IV by XORing the Recipient IV (context IV) with the 975 Partial IV parameter, received in the COSE Object. 977 4. Retrieve the Recipient Key. 979 5. Verify and decrypt the message. If the verification fails, the 980 client MUST stop processing the response. 982 6. If the message verifies, update the Recipient Sequence Number or 983 Replay Window, as described in Section 6.1. 985 7. Restore the unprotected response by adding any decrypted options 986 or payload from the plaintext. Any duplicate options (Section 4) 987 are overwritten. The Object-Security option is removed. 989 7. Security Considerations 991 In scenarios with intermediary nodes such as proxies or brokers, 992 transport layer security such as DTLS only protects data hop-by-hop. 993 As a consequence the intermediary nodes can read and modify 994 information. The trust model where all intermediate nodes are 995 considered trustworthy is problematic, not only from a privacy 996 perspective, but also from a security perspective, as the 997 intermediaries are free to delete resources on sensors and falsify 998 commands to actuators (such as "unlock door", "start fire alarm", 999 "raise bridge"). Even in the rare cases, where all the owners of the 1000 intermediary nodes are fully trusted, attacks and data breaches make 1001 such an architecture brittle. 1003 DTLS protects hop-by-hop the entire CoAP message, including header, 1004 options, and payload. OSCOAP protects end-to-end the payload, and 1005 all information in the options and header, that is not required for 1006 forwarding (see Section 4). DTLS and OSCOAP can be combined, thereby 1007 enabling end-to-end security of CoAP payload, in combination with 1008 hop-by-hop protection of the entire CoAP message, during transport 1009 between end-point and intermediary node. 1011 The CoAP message layer, however, cannot be protected end-to-end 1012 through intermediary devices since the parameters Type and Message 1013 ID, as well as Token and Token Length may be changed by a proxy. 1014 Moreover, messages that are not possible to verify should for 1015 security reasons not always be acknowledged but in some cases be 1016 silently dropped. This would not comply with CoAP message layer, but 1017 does not have an impact on the application layer security solution, 1018 since message layer is excluded from that. 1020 The use of COSE to protect CoAP messages as specified in this 1021 document requires an established security context. The method to 1022 establish the security context described in Section 3.2 is based on a 1023 common shared secret material and key derivation function in client 1024 and server. EDHOC [I-D.selander-ace-cose-ecdhe] describes an 1025 augmented Diffie-Hellman key exchange to produce forward secret 1026 keying material and agree on crypto algorithms necessary for OSCOAP, 1027 authenticated with pre-established credentials. These pre- 1028 established credentials may, in turn, be provisioned using a trusted 1029 third party such as described in the OAuth-based ACE framework 1030 [I-D.ietf-ace-oauth-authz]. An OSCOAP profile of ACE is described in 1031 [I-D.seitz-ace-oscoap-profile]. 1033 For symmetric encryption it is required to have a unique IV for each 1034 message, for which the sequence numbers in the COSE message field 1035 "Partial IV" is used. The context IVs (Sender IV and Recipient IV) 1036 SHOULD be established between sender and recipient before the message 1037 is sent, for example using the method in 1038 [I-D.selander-ace-cose-ecdhe], to avoid the overhead of sending it in 1039 each message. 1041 The MTI AEAD algorithm AES-CCM-64-64-128 is selected for broad 1042 applicability in terms of message size (2^64 blocks) and maximum no. 1043 messages (2^56-1). For 128 bit CCM*, use instead AES-CCM-16-64-128 1044 [I-D.ietf-cose-msg]. 1046 If the recipient accepts any sequence number larger than the one 1047 previously received (less than the maximum sequence number), then the 1048 problem of sequence number synchronization is avoided. With reliable 1049 transport it may be defined that only messages with sequence number 1050 which are equal to previous sequence number + 1 are accepted. The 1051 alternatives to sequence numbers have their issues: very constrained 1052 devices may not be able to support accurate time, or to generate and 1053 store large numbers of random IVs. The requirement to change key at 1054 counter wrap is a complication, but it also forces the user of this 1055 specification to think about implementing key renewal. 1057 The encrypted block options enable the sender to split large messages 1058 into protected fragments such that the receiving node can verify 1059 blocks before having received the complete message. In order to 1060 protect from attacks replacing fragments from a different message 1061 with the same block number between same endpoints and same resource 1062 at roughly the same time, the MAC from the message containing one 1063 block is included in the external_aad of the message containing the 1064 next block. 1066 The unencrypted block options allow for arbitrary proxy fragmentation 1067 operations which cannot be verified by the endpoints, but can by 1068 policy be restricted in size since the encrypted options allow for 1069 secure fragmentation of very large messages. A maximum message size 1070 (above which the sending endpoint fragments the message and the 1071 receiving endpoint discards the message, if complying to the policy) 1072 may be obtained as part of normal resource discovery. 1074 8. Privacy Considerations 1076 Privacy threats executed through intermediate nodes are considerably 1077 reduced by means of OSCOAP. End-to-end integrity protection and 1078 encryption of CoAP payload and all options that are not used for 1079 forwarding, provide mitigation against attacks on sensor and actuator 1080 communication, which may have a direct impact on the personal sphere. 1082 CoAP headers sent in plaintext allow for example matching of CON and 1083 ACK (CoAP Message Identifier), matching of request and responses 1084 (Token) and traffic analysis. 1086 9. IANA Considerations 1088 Note to RFC Editor: Please replace all occurrences of "[[this 1089 document]]" with the RFC number of this specification. 1091 9.1. Sid Registration 1093 IANA is requested to enter a new parameter entitled "sid" to the 1094 registry "COSE Header Parameters". The parameter is defined in 1095 Table 1. 1097 9.2. CoAP Option Number Registration 1099 The Object-Security option is added to the CoAP Option Numbers 1100 registry: 1102 +--------+-----------------+-------------------+ 1103 | Number | Name | Reference | 1104 +--------+-----------------+-------------------+ 1105 | TBD | Object-Security | [[this document]] | 1106 +--------+-----------------+-------------------+ 1108 9.3. Media Type Registrations 1110 The "application/oscon" media type is added to the Media Types 1111 registry: 1113 Type name: application 1115 Subtype name: cose 1117 Required parameters: N/A 1119 Optional parameters: N/A 1121 Encoding considerations: binary 1123 Security considerations: See the Security Considerations section 1124 of [[this document]]. 1126 Interoperability considerations: N/A 1128 Published specification: [[this document]] 1130 Applications that use this media type: To be identified 1132 Fragment identifier considerations: N/A 1134 Additional information: 1136 * Magic number(s): N/A 1138 * File extension(s): N/A 1140 * Macintosh file type code(s): N/A 1142 Person & email address to contact for further information: 1143 iesg@ietf.org 1145 Intended usage: COMMON 1147 Restrictions on usage: N/A 1149 Author: Goeran Selander, goran.selander@ericsson.com 1151 Change Controller: IESG 1153 Provisional registration? No 1155 9.4. CoAP Content Format Registration 1157 The "application/oscon" content format is added to the CoAP Content 1158 Format registry: 1160 +-------------------+----------+----+-------------------+ 1161 | Media type | Encoding | ID | Reference | 1162 +-------------------+----------+----+-------------------+ 1163 | application/oscon | - | 70 | [[this document]] | 1164 +-------------------+----------+----+-------------------+ 1166 10. Acknowledgments 1168 Klaus Hartke has independently been working on the same problem and a 1169 similar solution: establishing end-to-end security across proxies by 1170 adding a CoAP option. We are grateful to Malisa Vucinic and Marco 1171 Tiloca for providing helpful and timely reviews of previous versions 1172 of the draft. We are also grateful to Carsten Bormann and Jim Schaad 1173 for providing input and interesting discussions. 1175 11. References 1177 11.1. Normative References 1179 [I-D.ietf-cose-msg] 1180 Schaad, J., "CBOR Object Signing and Encryption (COSE)", 1181 draft-ietf-cose-msg-20 (work in progress), October 2016. 1183 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1184 Requirement Levels", BCP 14, RFC 2119, 1185 DOI 10.17487/RFC2119, March 1997, 1186 . 1188 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 1189 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 1190 January 2012, . 1192 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1193 Application Protocol (CoAP)", RFC 7252, 1194 DOI 10.17487/RFC7252, June 2014, 1195 . 1197 [RFC7641] Hartke, K., "Observing Resources in the Constrained 1198 Application Protocol (CoAP)", RFC 7641, 1199 DOI 10.17487/RFC7641, September 2015, 1200 . 1202 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 1203 the Constrained Application Protocol (CoAP)", RFC 7959, 1204 DOI 10.17487/RFC7959, August 2016, 1205 . 1207 11.2. Informative References 1209 [I-D.bormann-6lo-coap-802-15-ie] 1210 Bormann, C., "Constrained Application Protocol (CoAP) over 1211 IEEE 802.15.4 Information Element for IETF", draft- 1212 bormann-6lo-coap-802-15-ie-00 (work in progress), April 1213 2016. 1215 [I-D.hartke-core-e2e-security-reqs] 1216 Selander, G., Palombini, F., and K. Hartke, "Requirements 1217 for CoAP End-To-End Security", draft-hartke-core-e2e- 1218 security-reqs-01 (work in progress), July 2016. 1220 [I-D.ietf-ace-oauth-authz] 1221 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 1222 H. Tschofenig, "Authentication and Authorization for 1223 Constrained Environments (ACE)", draft-ietf-ace-oauth- 1224 authz-02 (work in progress), June 2016. 1226 [I-D.ietf-core-coap-tcp-tls] 1227 Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 1228 Silverajan, B., and B. Raymor, "CoAP (Constrained 1229 Application Protocol) over TCP, TLS, and WebSockets", 1230 draft-ietf-core-coap-tcp-tls-04 (work in progress), August 1231 2016. 1233 [I-D.seitz-ace-oscoap-profile] 1234 Seitz, L., "OSCOAP profile of ACE", draft-seitz-ace- 1235 oscoap-profile-00 (work in progress), July 2016. 1237 [I-D.selander-ace-cose-ecdhe] 1238 Selander, G., Mattsson, J., and F. Palombini, "Ephemeral 1239 Diffie-Hellman Over COSE (EDHOC)", draft-selander-ace- 1240 cose-ecdhe-02 (work in progress), July 2016. 1242 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 1243 Key Derivation Function (HKDF)", RFC 5869, 1244 DOI 10.17487/RFC5869, May 2010, 1245 . 1247 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 1248 Constrained-Node Networks", RFC 7228, 1249 DOI 10.17487/RFC7228, May 2014, 1250 . 1252 Appendix A. Overhead 1254 OSCOAP transforms an unprotected CoAP message to a protected CoAP 1255 message, and the protected CoAP message is larger than the 1256 unprotected CoAP message. This appendix illustrates the message 1257 expansion. 1259 A.1. Length of the Object-Security Option 1261 The protected CoAP message contains the COSE object. The COSE object 1262 is included in the payload if the message type of the unprotected 1263 CoAP message allows payload or else in the Object-Security option. 1264 In the former case the Object-Security option is empty. So the 1265 length of the Object-Security option is either zero or the size of 1266 the COSE object, depending on whether the CoAP message allows payload 1267 or not. 1269 Length of Object-Security option = { 0, size of COSE Object } 1271 A.2. Size of the COSE Object 1273 The size of the COSE object is the sum of the sizes of 1275 o the Header parameters, 1277 o the Cipher Text (excluding the Tag), 1279 o the Tag, and 1281 o data incurred by the COSE format itself (including CBOR encoding). 1283 Let's analyse the contributions one at a time: 1285 o The header parameters of the COSE object are the Context 1286 Identifier (Cid) and the Sequence Number (Seq) (also known as the 1287 Transaction Identifier (Tid)) if the message is a request, and Seq 1288 only if the message is a response (see Section 5). 1290 * The size of Cid depends on the number of simultaneous clients, 1291 as discussed in Section 3.2 1293 * The size of Seq is variable, and increases with the number of 1294 messages exchanged. 1296 * As the IV is generated from the padded Sequence Number and a 1297 previously agreed upon context IV it is not required to send 1298 the whole IV in the message. 1300 o The Cipher Text, excluding the Tag, is the encryption of the 1301 payload and the encrypted options Section 4, which are present in 1302 the unprotected CoAP message. 1304 o The size of the Tag depends on the Algorithm. For example, for 1305 the algorithm AES-CCM-64-64-128, the Tag is 8 bytes. 1307 o The overhead from the COSE format itself depends on the sizes of 1308 the previous fields, and is of the order of 10 bytes. 1310 A.3. Message Expansion 1312 The message expansion is not the size of the COSE object. The cipher 1313 text in the COSE object is encrypted payload and options of the 1314 unprotected CoAP message - the plaintext of which is removed from the 1315 protected CoAP message. Since the size of the cipher text is the 1316 same as the corresponding plaintext, there is no message expansion 1317 due to encryption; payload and options are just represented in a 1318 different way in the protected CoAP message: 1320 o The encrypted payload is in the payload of the protected CoAP 1321 message 1323 o The encrypted options are in the Object-Security option or within 1324 the payload. 1326 Therefore the OSCOAP message expansion is due to Cid (if present), 1327 Seq, Tag, and COSE overhead: 1329 Message Overhead = Cid + Seq + Tag + COSE Overhead 1331 Figure 9: OSCOAP message expansion 1333 A.4. Example 1335 This section gives an example of message expansion in a request with 1336 OSCOAP. 1338 In this example we assume an extreme 4-byte Cid, based on the 1339 assumption of an ACE deployment with billions of clients requesting 1340 access to this particular server. (A typical Cid, will be 1-2 byte 1341 as is discussed in Appendix A.2.) 1343 o Cid: 0xa1534e3c 1345 In the example the sequence number is 225, requiring 1 byte to 1346 encode. (The size of Seq could be larger depending on how many 1347 messages that has been sent as is discussed in Appendix A.2.) 1348 o Seq: 225 1350 The example is based on AES-CCM-64-64-128. 1352 o Tag is 8 bytes 1354 The COSE object is represented in Figure 10 using CBOR's diagnostic 1355 notation. 1357 [ 1358 h'a20444a1534e3c0641e2', # protected: 1359 {04:h'a1534e3c', 1360 06:h'e2'} 1361 {}, # unprotected: - 1362 Tag # cipher text + 8 byte authentication tag 1363 ] 1365 Figure 10: Example of message expansion 1367 Note that the encrypted CoAP options and payload are omitted since we 1368 target the message expansion (see Appendix A.3). Therefore the size 1369 of the COSE Cipher Text equals the size of the Tag, which is 8 bytes. 1371 The COSE object encodes to a total size of 22 bytes, which is the 1372 message expansion in this example. The COSE overhead in this example 1373 is 22 - (4 + 1 + 8) = 9 bytes, according to the formula in Figure 9. 1374 Note that in this example two bytes in the COSE overhead are used to 1375 encode the length of Cid and the length of Seq. 1377 Figure 11 summarizes these results. 1379 +---------+---------+----------+------------+ 1380 | Tid | Tag | COSE OH | Message OH | 1381 +---------+---------+----------+------------+ 1382 | 5 bytes | 8 bytes | 9 bytes | 22 bytes | 1383 +---------+---------+----------+------------+ 1385 Figure 11: Message overhead for a 5-byte Tid and 8-byte Tag. 1387 Appendix B. Examples 1389 This section gives examples of OSCOAP. The message exchanges are 1390 made, based on the assumption that there is a security context 1391 established between client and server. For simplicity, these 1392 examples only indicate the content of the messages without going into 1393 detail of the COSE message format. 1395 B.1. Secure Access to Sensor 1397 Here is an example targeting the scenario in the Section 2.2.1. - 1398 Forwarding of [I-D.hartke-core-e2e-security-reqs]. The example 1399 illustrates a client requesting the alarm status from a server. In 1400 the request, CoAP option Uri-Path is encrypted and integrity 1401 protected, and the CoAP header fields Code and Version are integrity 1402 protected (see Section 4). In the response, the CoAP Payload is 1403 encrypted and integrity protected, and the CoAP header fields Code 1404 and Version are integrity protected. 1406 Client Proxy Server 1407 | | | 1408 +----->| | Code: 0.01 (GET) 1409 | GET | | Token: 0x8c 1410 | | | Object-Security: [cid:5fdc, seq:42, 1411 | | | {Uri-Path:"alarm_status"}, 1412 | | | ] 1413 | | | Payload: - 1414 | | | 1415 | +----->| Code: 0.01 (GET) 1416 | | GET | Token: 0x7b 1417 | | | Object-Security: [cid:5fdc, seq:42, 1418 | | | {Uri-Path:"alarm_status"}, 1419 | | | ] 1420 | | | Payload: - 1421 | | | 1422 | |<-----+ Code: 2.05 (Content) 1423 | | 2.05 | Token: 0x7b 1424 | | | Max-Age: 0 1425 | | | Object-Security: - 1426 | | | Payload: [seq:56, {"OFF"}, ] 1427 | | | 1428 |<-----+ | Code: 2.05 (Content) 1429 | 2.05 | | Token: 0x8c 1430 | | | Max-Age: 0 1431 | | | Object-Security: - 1432 | | | Payload: [seq:56, {"OFF"}, ] 1433 | | | 1435 Figure 12: Indication of CoAP GET protected with OSCOAP. The 1436 brackets [ ... ] indicate a COSE object. The brackets { ... } 1437 indicate encrypted data. 1439 Since the unprotected request message (GET) has no payload, the 1440 Object-Security option carries the COSE object as its value. Since 1441 the unprotected response message (Content) has payload ("OFF"), the 1442 COSE object (indicated with [ ... ]) is carried as the CoAP payload. 1444 The COSE header of the request contains a Context Identifier 1445 (cid:5fdc), indicating which security context was used to protect the 1446 message and a Sequence Number (seq:42). 1448 The option Uri-Path (alarm_status) and payload ("OFF") are formatted 1449 as indicated in Section 5, and encrypted in the COSE Cipher Text 1450 (indicated with { ... }). 1452 The server verifies that the Sequence Number has not been received 1453 before (see Section 6.1). The client verifies that the Sequence 1454 Number has not been received before and that the response message is 1455 generated as a response to the sent request message (see 1456 Section 6.1). 1458 B.2. Secure Subscribe to Sensor 1460 Here is an example targeting the scenario in the Forwarding with 1461 observe case of [I-D.hartke-core-e2e-security-reqs]. The example 1462 illustrates a client requesting subscription to a blood sugar 1463 measurement resource (GET /glucose), and first receiving the value 1464 220 mg/dl, and then a second reading with value 180 mg/dl. The CoAP 1465 options Observe, Uri-Path, Content-Format, and Payload are encrypted 1466 and integrity protected, and the CoAP header field Code is integrity 1467 protected (see Section 4). 1469 Client Proxy Server 1470 | | | 1471 +----->| | Code: 0.01 (GET) 1472 | GET | | Token: 0x83 1473 | | | Observe: 0 1474 | | | Object-Security: [cid:ca, seq:15b7, {Observe:0, 1475 | | | Uri-Path:"glucose"}, ] 1476 | | | Payload: - 1477 | | | 1478 | +----->| Code: 0.01 (GET) 1479 | | GET | Token: 0xbe 1480 | | | Observe: 0 1481 | | | Object-Security: [cid:ca, seq:15b7, {Observe:0, 1482 | | | Uri-Path:"glucose"}, ] 1483 | | | Payload: - 1484 | | | 1485 | |<-----+ Code: 2.05 (Content) 1486 | | 2.05 | Token: 0xbe 1487 | | | Max-Age: 0 1488 | | | Observe: 1 1489 | | | Object-Security: - 1490 | | | Payload: [seq:32c2, {Observe:1, 1491 | | | Content-Format:0, "220"}, ] 1492 | | | 1493 |<-----+ | Code: 2.05 (Content) 1494 | 2.05 | | Token: 0x83 1495 | | | Max-Age: 0 1496 | | | Observe: 1 1497 | | | Object-Security: - 1498 | | | Payload: [seq:32c2, {Observe:1, 1499 | | | Content-Format:0, "220"}, ] 1500 ... ... ... 1501 | | | 1502 | |<-----+ Code: 2.05 (Content) 1503 | | 2.05 | Token: 0xbe 1504 | | | Max-Age: 0 1505 | | | Observe: 2 1506 | | | Object-Security: - 1507 | | | Payload: [seq:32c6, {Observe:2, 1508 | | | Content-Format:0, "180"}, ] 1509 | | | 1510 |<-----+ | Code: 2.05 (Content) 1511 | 2.05 | | Token: 0x83 1512 | | | Max-Age: 0 1513 | | | Observe: 2 1514 | | | Object-Security: - 1515 | | | Payload: [seq:32c6, {Observe:2, 1516 | | | Content-Format:0, "180"}, ] 1517 | | | 1519 Figure 13: Indication of CoAP GET protected with OSCOAP. The 1520 brackets [ ... ] indicates COSE object. The bracket { ... } 1521 indicates encrypted data. 1523 Since the unprotected request message (GET) allows no payload, the 1524 COSE object (indicated with [ ... ]) is carried in the Object- 1525 Security option value. Since the unprotected response message 1526 (Content) has payload, the Object-Security option is empty, and the 1527 COSE object is carried as the payload. 1529 The COSE header of the request contains a Context Identifier 1530 (cid:ca), indicating which security context was used to protect the 1531 message and a Sequence Number (seq:15b7). 1533 The options Observe, Content-Format and the payload are formatted as 1534 indicated in Section 5, and encrypted in the COSE cipher text 1535 (indicated with { ... }). 1537 The server verifies that the Sequence Number has not been received 1538 before (see Section 6.1). The client verifies that the Sequence 1539 Number has not been received before and that the response message is 1540 generated as a response to the subscribe request. 1542 Appendix C. Object Security of Content (OSCON) 1544 OSCOAP protects message exchanges end-to-end between a certain client 1545 and a certain server, targeting the security requirements for forward 1546 proxy of [I-D.hartke-core-e2e-security-reqs]. In contrast, many use 1547 cases require one and the same message to be protected for, and 1548 verified by, multiple endpoints, see caching proxy section of 1549 [I-D.hartke-core-e2e-security-reqs]. Those security requirements can 1550 be addressed by protecting essentially the payload/content of 1551 individual messages using the COSE format ([I-D.ietf-cose-msg]), 1552 rather than the entire request/response message exchange. This is 1553 referred to as Object Security of Content (OSCON). 1555 OSCON transforms an unprotected CoAP message into a protected CoAP 1556 message in the following way: the payload of the unprotected CoAP 1557 message is wrapped by a COSE object, which replaces the payload of 1558 the unprotected CoAP message. We call the result the "protected" 1559 CoAP message. 1561 The unprotected payload shall be the plaintext/payload of the COSE 1562 object. The 'protected' field of the COSE object 'Headers' shall 1563 include the context identifier, both for requests and responses. If 1564 the unprotected CoAP message includes a Content-Format option, then 1565 the COSE object shall include a protected 'content type' field, whose 1566 value is set to the unprotected message Content-Format value. The 1567 Content-Format option of the protected CoAP message shall be replaced 1568 with "application/oscon" (Section 9) 1570 The COSE object shall be protected (encrypted) and verified 1571 (decrypted) as described in ([I-D.ietf-cose-msg]). 1573 In the case of symmetric encryption, the same key and IV shall not be 1574 used twice. Sequence numbers for partial IV as specified for OSCOAP 1575 may be used for replay protection as described in Section 6.1. The 1576 use of time stamps in the COSE header parameter 'operation time' 1577 [I-D.ietf-cose-msg] for freshness may be used. 1579 OSCON shall not be used in cases where CoAP header fields (such as 1580 Code or Version) or CoAP options need to be integrity protected or 1581 encrypted. OSCON shall not be used in cases which require a secure 1582 binding between request and response. 1584 The scenarios in Sections 3.3 - 3.5 of 1585 [I-D.hartke-core-e2e-security-reqs] assume multiple recipients for a 1586 particular content. In this case the use of symmetric keys does not 1587 provide data origin authentication. Therefore the COSE object should 1588 in general be protected with a digital signature. 1590 C.1. Overhead OSCON 1592 In general there are four different kinds of ciphersuites that need 1593 to be supported: message authentication code, digital signature, 1594 authenticated encryption, and symmetric encryption + digital 1595 signature. The use of digital signature is necessary for 1596 applications with many legitimate recipients of a given message, and 1597 where data origin authentication is required. 1599 To distinguish between these different cases, the tagged structures 1600 of COSE are used (see Section 2 of [I-D.ietf-cose-msg]). 1602 The size of the COSE message for selected algorithms are detailed in 1603 this section. 1605 The size of the header is shown separately from the size of the MAC/ 1606 signature. A 4-byte Context Identifier and a 1-byte Sequence Number 1607 are used throughout all examples, with these values: 1609 o Cid: 0xa1534e3c 1611 o Seq: 0xa3 1613 For each scheme, we indicate the fixed length of these two parameters 1614 ("Cid+Seq" column) and of the Tag ("MAC"/"SIG"/"TAG"). The "Message 1615 OH" column shows the total expansions of the CoAP message size, while 1616 the "COSE OH" column is calculated from the previous columns 1617 following the formula in Figure 9. 1619 Overhead incurring from CBOR encoding is also included in the COSE 1620 overhead count. 1622 To make it easier to read, COSE objects are represented using CBOR's 1623 diagnostic notation rather than a binary dump. 1625 C.2. MAC Only 1627 This example is based on HMAC-SHA256, with truncation to 8 bytes 1628 (HMAC 256/64). 1630 Since the key is implicitly known by the recipient, the 1631 COSE_Mac0_Tagged structure is used (Section 6.2 of 1632 [I-D.ietf-cose-msg]). 1634 The object in COSE encoding gives: 1636 996( # COSE_Mac0_Tagged 1637 [ 1638 h'a20444a1534e3c0641a3', # protected: 1639 {04:h'a1534e3c', 1640 06:h'a3'} 1641 {}, # unprotected 1642 h'', # payload 1643 MAC # truncated 8-byte MAC 1644 ] 1645 ) 1647 This COSE object encodes to a total size of 26 bytes. 1649 Figure 14 summarizes these results. 1651 +------------------+-----+-----+---------+------------+ 1652 | Structure | Tid | MAC | COSE OH | Message OH | 1653 +------------------+-----+-----+---------+------------+ 1654 | COSE_Mac0_Tagged | 5 B | 8 B | 13 B | 26 B | 1655 +------------------+-----+-----+---------+------------+ 1657 Figure 14: Message overhead for a 5-byte Tid using HMAC 256/64 1659 C.3. Signature Only 1661 This example is based on ECDSA, with a signature of 64 bytes. 1663 Since only one signature is used, the COSE_Sign1_Tagged structure is 1664 used (Section 4.2 of [I-D.ietf-cose-msg]). 1666 The object in COSE encoding gives: 1668 997( # COSE_Sign1_Tagged 1669 [ 1670 h'a20444a1534e3c0641a3', # protected: 1671 {04:h'a1534e3c', 1672 06:h'a3'} 1673 {}, # unprotected 1674 h'', # payload 1675 SIG # 64-byte signature 1676 ] 1677 ) 1679 This COSE object encodes to a total size of 83 bytes. 1681 Figure 15 summarizes these results. 1683 +-------------------+-----+------+---------+------------+ 1684 | Structure | Tid | SIG | COSE OH | Message OH | 1685 +-------------------+-----+------+---------+------------+ 1686 | COSE_Sign1_Tagged | 5 B | 64 B | 14 B | 83 bytes | 1687 +-------------------+-----+------+---------+------------+ 1689 Figure 15: Message overhead for a 5-byte Tid using 64 byte ECDSA 1690 signature. 1692 C.4. Authenticated Encryption with Additional Data (AEAD) 1694 This example is based on AES-CCM with the MAC truncated to 8 bytes. 1696 It is assumed that the IV is generated from the Sequence Number and 1697 some previously agreed upon context IV. This means it is not 1698 required to explicitly send the whole IV in the message. 1700 Since the key is implicitly known by the recipient, the 1701 COSE_Encrypt0_Tagged structure is used (Section 5.2 of 1702 [I-D.ietf-cose-msg]). 1704 The object in COSE encoding gives: 1706 993( # COSE_Encrypt0_Tagged 1707 [ 1708 h'a20444a1534e3c0641a3', # protected: 1709 {04:h'a1534e3c', 1710 06:h'a3'} 1711 {}, # unprotected 1712 TAG # cipher text + truncated 8-byte TAG 1713 ] 1714 ) 1716 This COSE object encodes to a total size of 25 bytes. 1718 Figure 16 summarizes these results. 1720 +----------------------+-----+-----+---------+------------+ 1721 | Structure | Tid | TAG | COSE OH | Message OH | 1722 +----------------------+-----+-----+---------+------------+ 1723 | COSE_Encrypt0_Tagged | 5 B | 8 B | 12 B | 25 bytes | 1724 +----------------------+-----+-----+---------+------------+ 1726 Figure 16: Message overhead for a 5-byte Tid using AES_128_CCM_8. 1728 C.5. Symmetric Encryption with Asymmetric Signature (SEAS) 1730 This example is based on AES-CCM and ECDSA with 64 bytes signature. 1731 The same assumption on the security context as in Appendix C.4. COSE 1732 defines the field 'counter signature w/o headers' that is used here 1733 to sign a COSE_Encrypt0_Tagged message (see Section 3 of 1734 [I-D.ietf-cose-msg]). 1736 The object in COSE encoding gives: 1738 993( # COSE_Encrypt0_Tagged 1739 [ 1740 h'a20444a1534e3c0641a3', # protected: 1741 {04:h'a1534e3c', 1742 06:h'a3'} 1743 {9:SIG}, # unprotected: 1744 09: 64 bytes signature 1745 TAG # cipher text + truncated 8-byte TAG 1746 ] 1747 ) 1749 This COSE object encodes to a total size of 92 bytes. 1751 Figure 17 summarizes these results. 1753 +----------------------+-----+-----+------+---------+------------+ 1754 | Structure | Tid | TAG | SIG | COSE OH | Message OH | 1755 +----------------------+-----+-----+------+---------+------------+ 1756 | COSE_Encrypt0_Tagged | 5 B | 8 B | 64 B | 15 B | 92 B | 1757 +----------------------+-----+-----+------+---------+------------+ 1759 Figure 17: Message overhead for a 5-byte Tid using AES-CCM 1760 countersigned with ECDSA. 1762 Authors' Addresses 1764 Goeran Selander 1765 Ericsson AB 1766 Farogatan 6 1767 Kista SE-16480 Stockholm 1768 Sweden 1770 Email: goran.selander@ericsson.com 1771 John Mattsson 1772 Ericsson AB 1773 Farogatan 6 1774 Kista SE-16480 Stockholm 1775 Sweden 1777 Email: john.mattsson@ericsson.com 1779 Francesca Palombini 1780 Ericsson AB 1781 Farogatan 6 1782 Kista SE-16480 Stockholm 1783 Sweden 1785 Email: francesca.palombini@ericsson.com 1787 Ludwig Seitz 1788 SICS Swedish ICT 1789 Scheelevagen 17 1790 Lund 22370 1791 Sweden 1793 Email: ludwig@sics.se