idnits 2.17.1 draft-selander-ace-object-security-04.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 (March 21, 2016) is 2930 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-10 ** Obsolete normative reference: RFC 6347 (Obsoleted by RFC 9147) == Outdated reference: A later version (-03) exists of draft-hartke-core-e2e-security-reqs-00 == Outdated reference: A later version (-46) exists of draft-ietf-ace-oauth-authz-01 == Outdated reference: A later version (-21) exists of draft-ietf-core-block-18 == Outdated reference: A later version (-28) exists of draft-ietf-tls-tls13-11 == Outdated reference: A later version (-14) exists of draft-selander-ace-cose-ecdhe-00 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: September 22, 2016 Ericsson AB 6 L. Seitz 7 SICS Swedish ICT 8 March 21, 2016 10 Object Security of CoAP (OSCOAP) 11 draft-selander-ace-object-security-04 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 Encoded 18 Message Syntax. OSCOAP provides end-to-end encryption, integrity and 19 replay protection to CoAP payload, options, and header fields, as 20 well as a secure binding between CoAP request and response messages. 21 The use of OSCOAP is signaled with the CoAP option Object-Security, 22 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 September 22, 2016. 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 4. Protected CoAP Message Fields . . . . . . . . . . . . . . . . 8 63 5. The COSE Object . . . . . . . . . . . . . . . . . . . . . . . 10 64 5.1. Plaintext . . . . . . . . . . . . . . . . . . . . . . . . 11 65 5.2. Additional Authenticated Data . . . . . . . . . . . . . . 12 66 6. Protecting CoAP Messages . . . . . . . . . . . . . . . . . . 13 67 6.1. Replay and Freshness Protection . . . . . . . . . . . . . 13 68 6.2. Protecting the Request . . . . . . . . . . . . . . . . . 13 69 6.3. Verifying the Request . . . . . . . . . . . . . . . . . . 14 70 6.4. Protecting the Response . . . . . . . . . . . . . . . . . 15 71 6.5. Verifying the Response . . . . . . . . . . . . . . . . . 16 72 7. Security Considerations . . . . . . . . . . . . . . . . . . . 16 73 8. Privacy Considerations . . . . . . . . . . . . . . . . . . . 18 74 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 75 9.1. CoAP Option Number Registration . . . . . . . . . . . . . 18 76 9.2. Media Type Registrations . . . . . . . . . . . . . . . . 19 77 9.3. CoAP Content Format Registration . . . . . . . . . . . . 20 78 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 21 79 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 21 80 11.1. Normative References . . . . . . . . . . . . . . . . . . 21 81 11.2. Informative References . . . . . . . . . . . . . . . . . 21 82 Appendix A. Overhead . . . . . . . . . . . . . . . . . . . . . . 22 83 A.1. Length of the Object-Security Option . . . . . . . . . . 22 84 A.2. Size of the COSE Object . . . . . . . . . . . . . . . . . 23 85 A.3. Message Expansion . . . . . . . . . . . . . . . . . . . . 24 86 A.4. Example . . . . . . . . . . . . . . . . . . . . . . . . . 24 87 Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 25 88 B.1. Secure Access to Actuator . . . . . . . . . . . . . . . . 25 89 B.2. Secure Subscribe to Sensor . . . . . . . . . . . . . . . 27 90 Appendix C. Object Security of Content (OSCON) . . . . . . . . . 28 91 C.1. Overhead OSCON . . . . . . . . . . . . . . . . . . . . . 30 92 C.2. MAC Only . . . . . . . . . . . . . . . . . . . . . . . . 30 93 C.3. Signature Only . . . . . . . . . . . . . . . . . . . . . 31 94 C.4. Authenticated Encryption with Additional Data (AEAD) . . 32 95 C.5. Symmetric Encryption with Asymmetric Signature (SEAS) . . 33 96 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 33 98 1. Introduction 100 The Constrained Application Protocol (CoAP) [RFC7252] is a web 101 application protocol, designed for constrained nodes and networks 102 [RFC7228]. CoAP specifies the use of proxies, to improve 103 scalability, efficiency, and uses. At the same time CoAP references 104 DTLS [RFC6347] for security. Proxy operations on CoAP messages 105 require DTLS to be terminated at the proxy. The proxy therefore not 106 only has access to the data required for performing the intended 107 proxy functionality, but is also able to eavesdrop on, or manipulate 108 any part of the CoAP payload and metadata, in transit between client 109 and server. The proxy can also inject, delete, or reorder packages 110 without being protected or detected by DTLS. 112 This memo defines Object Security of CoAP (OSCOAP), a data object 113 based security protocol, protecting CoAP message exchanges end-to- 114 end, across intermediary nodes. An analysis of end-to-end security 115 for CoAP messages through intermediary nodes is performed in 116 [I-D.hartke-core-e2e-security-reqs]; OSCOAP targets the requirements 117 in Sections 3.1 and 3.2. 119 OSCOAP builds on the CBOR Encoded Message Syntax (COSE) 120 [I-D.ietf-cose-msg], providing end-to-end encryption, integrity, and 121 replay protection. The use of OSCOAP is signaled with the CoAP 122 option Object-Security, also defined in this memo. 124 OSCOAP transforms an unprotected CoAP message into a protected CoAP 125 message in the following way: the unprotected CoAP message is 126 protected by including payload (if present), certain options, and 127 header fields in a COSE object. The message fields that have been 128 encrypted are removed from the message whereas the Object-Security 129 option and the COSE object are added. We call the result the 130 "protected" CoAP message. Thus OSCOAP is a security protocol based 131 on the exchange of protected CoAP messages (see Figure 1). 133 Client Server 134 | request: | 135 | GET example.com | 136 | [Header, Token, Options:{..., | 137 | Object-Security:COSE object}] | 138 +---------------------------------------------->| 139 | response: | 140 | 2.05 (Content) | 141 | [Header, Token, Options:{..., | 142 | Object-Security:-}, Payload:COSE object] | 143 |<----------------------------------------------+ 144 | | 146 Figure 1: Sketch of OSCOAP 148 OSCOAP provides protection of CoAP payload, certain options, and 149 header fields, as well as a secure binding between CoAP request and 150 response messages, and freshness of requests and responses. 152 OSCOAP may be used in constrained settings, where DTLS cannot be 153 supported. Alternatively, OSCOAP can be combined with DTLS, thereby 154 enabling end-to-end security of CoAP payload, in combination with 155 hop-by-hop protection of the entire CoAP message, during transport 156 between end-point and intermediary node. Examples of the use of 157 OSCOAP are given in Appendix B. 159 The message protection provided by OSCOAP can alternatively be 160 applied to payload only of individual messages. We call this object 161 security of content (OSCON) and it is defined in Appendix C. OSCON 162 targets the requirements in Sections 3.3 - 3.5 of 163 [I-D.hartke-core-e2e-security-reqs]. 165 1.1. Terminology 167 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 168 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 169 document are to be interpreted as described in [RFC2119]. These 170 words may also appear in this document in lowercase, absent their 171 normative meanings. 173 Readers are expected to be familiar with the terms and concepts 174 described in [RFC7252] and [RFC7641]. 176 Terminology for constrained environments, such as "constrained 177 device", "constrained-node network", is defined in [RFC7228]. 179 Two different scopes of object security are defined: 181 o OSCOAP = object security of CoAP, signaled with the Object- 182 Security option. 184 o OSCON = object security of content, signaled with Content Format/ 185 Media Type set to application/oscon. 187 OSCON is defined in Appendix C. 189 2. The Object-Security Option 191 The Object-Security option indicates that OSCOAP is used to protect 192 the CoAP message exchange. 194 The Object-Security option is critical, safe to forward, part of the 195 cache key, and not repeatable. Figure 2 illustrates the structure of 196 the Object-Security option. 198 A CoAP proxy SHOULD NOT cache a response to a request with an Object- 199 Security option, since the response is only applicable to the 200 original client's request. The Object-Security option is included in 201 the cache key for backward compatibility with proxies not recognizing 202 the Object-Security option. The effect of this is that messages with 203 the Object-Security option will never generate cache hits. To 204 further prevent caching, a Max-Age option with value zero can be 205 added to the protected CoAP responses. 207 +-----+---+---+---+---+-----------------+--------+--------+ 208 | No. | C | U | N | R | Name | Format | Length | 209 +-----+---+---+---+---+-----------------+--------+--------| 210 | TBD | x | | | | Object-Security | opaque | 0- | 211 +-----+---+---+---+---+-----------------+--------+--------+ 212 C=Critical, U=Unsafe, N=NoCacheKey, R=Repeatable 214 Figure 2: The Object-Security Option 216 The length of the Object-Security option depends on whether the 217 unprotected message has payload, on the set of options that are 218 included in the unprotected message, the length of the integrity tag, 219 and the length of the information identifying the security context. 221 o If the unprotected message has payload, then the COSE object is 222 the payload of the protected message (see Section 6.2 and 223 Section 6.4), and the Object-Security option has length zero. 225 o If the unprotected message does not have payload, then the COSE 226 object is the value of the Object-Security option and the length 227 of the Object-Security option is equal to the size of the COSE 228 object. 230 An example of option length is given in Appendix A. 232 3. The Security Context 234 The security context is the set of information elements necessary to 235 carry out the cryptographic operations in OSCOAP. A security context 236 needs to be pre-established and agreed upon between client and 237 server. How this is done is out of scope of this memo, an example is 238 given in the appendices of [I-D.selander-ace-cose-ecdhe]. Each 239 security context is identified by a Context Identifier, which is 240 unique within a given server. A Context Identifier that is no longer 241 in use can be reassigned to a new security context. 243 The security context has a "Client Write" part and a "Server Write" 244 part. The client initiating a transaction uses the Client Write part 245 of the context to protect the request; the server receiving the 246 request first uses the Client Write part of the context to verify the 247 request, then the Server Write part of the context to protect the 248 response. Finally, the client uses the Server Write part of the 249 context to verify the response. 251 OSCOAP is very similar to TLS and borrows mechanisms such as key 252 derivation, and nonce construction from [I-D.ietf-tls-tls13]. The 253 main differences is that OSCOAP uses COSE [I-D.ietf-cose-msg] instead 254 of the TLS record layer, which allows OSCOAP to use a context 255 identifier, and sequence numbers of variable length. 257 It should be noted that how the context is retrieved within the 258 client and server is linked to the resource discovery, may be 259 implementation specific, and is out of scope of this memo. 261 An example is shown in Figure 3. 263 .---Cid = Cid1---. .---Cid = Cid1---. 264 | context: | | context: | 265 | Alg, | | Alg, | 266 | Client Write, | | Client Write, | 267 | Server Write | | Server Write | 268 '----------------' '----------------' 270 Client Server 271 | | 272 Retrieve context for | request: | 273 target resource | [Token = Token1, | 274 Protect request with | Cid=Cid1, ...] | 275 Client Write +---------------------->| Retrieve context with 276 | | Cid = Cid1 277 | | Verify request with 278 Retrieve context with | response: | Client Write 279 Token = Token1 | [Token = Token1, ...]| Protect response with 280 Verify request with |<----------------------+ Server Write 281 Server Write | | 283 Figure 3: Retrieval and use of the Security Context 285 The security context structure contains the following parameters: 287 o Context Identifier (Cid). Variable length byte string that 288 identifies the security context. Immutable. 290 o Algorithm (Alg). Value that identifies the COSE AEAD algorithm to 291 use for encryption. Immutable. 293 o Client Write Key. Byte string containing the symmetric key to use 294 in client-sent messages. Length is determined by Algorithm. 295 Immutable. 297 o Client Write IV. Byte string containing the static IV to use in 298 cryptographic operations on client-sent messages. Length is 299 determined by Algorithm. Immutable. 301 o Client Write Sequence Number. Non-negative integer enumerating 302 the COSE objects that the client sent, associated to the Context 303 Identifier. It is used for replay protection, and to generate 304 unique nonces. Initiated to 0. Maximum value is determined by 305 Algorithm. 307 o Server Write Key. Byte string containing the symmetric key to use 308 in server-sent messages. Length is determined by the Algorithm. 309 Immutable. 311 o Server Write IV. Byte string containing the static IV to use in 312 cryptographic operations on server-sent messages. Length is 313 determined by Algorithm. Immutable. 315 o Server Write Sequence Number. Non-negative integer enumerating 316 the COSE objects that the server sent, associated to the Context 317 Identifier. It is used for replay protection, and to generate 318 unique nonces. Initiated to 0. Maximum value is determined by 319 Algorithm. 321 o Replay Window. The replay protection window for messages 322 received, equivalent to the functionality described in 323 Section 4.1.2.6 of [RFC6347]. The default window size is 64. 325 The size of Cid depends on the number of simultaneous clients, and 326 must be chosen so that the server can uniquely identify the 327 requesting client. Cids of different lengths can be used by 328 different client. In the case of an ACE-based authentication and 329 authorization model [I-D.ietf-ace-oauth-authz], the Authorization 330 Server can define the context identifier of all clients, interacting 331 with a particular server, in which case the size of Cid can be 332 proportional to the logarithm of the number of authorized clients. 333 It is RECOMMENDED to start assigning Cids of length 1 byte (0x00, 334 0x01, ..., 0xff), and then when all 1 byte Cids are in use, start 335 handling out Cids with a length of two bytes (0x0000, 0x0001, ..., 336 0xffff), and so on. 338 The ordered pair (Cid, Client Write Sequence Number) is called 339 Transaction Identifier (Tid), and SHALL be unique for each COSE 340 object and server. The Tid is used as a unique challenge in the COSE 341 object of the protected CoAP request, and in part of the Additional 342 Authenticated Data (AAD, see Section 5) of the protected CoAP 343 response message. 345 4. Protected CoAP Message Fields 347 This section defines how the CoAP message fields are protected. 348 OSCOAP protects as much of the unprotected CoAP message as possible, 349 while still allowing forward proxy operations 350 [I-D.hartke-core-e2e-security-reqs]. 352 The CoAP Payload SHALL be encrypted and integrity protected. 354 The CoAP Header fields Version and Code SHALL be integrity protected 355 but not encrypted. The CoAP Message Layer parameters, Type and 356 Message ID, as well as Token and Token Length SHALL neither be 357 integrity protected nor encrypted. 359 Protection of CoAP Options can be summarized as follows: 361 o To prevent information leakage, Uri-Path and Uri-Query SHALL be 362 encrypted. As a consequence, if Proxy-Uri is used, those parts of 363 the URI SHALL be removed from the Proxy-Uri. The CoAP Options 364 Uri-Host, Uri-Port, Proxy-Uri, and Proxy-Scheme SHALL neither be 365 encrypted, nor integrity protected (cf. protection of request URI 366 in Section 5.2). 368 o The other CoAP options listed in Figure 4 SHALL be encrypted and 369 integrity protected. 371 +----+---+---+---+---+----------------+--------+--------+---+---+---+ 372 | No.| C | U | N | R | Name | Format | Length | E | I | D | 373 +----+---+---+---+---+----------------+--------+--------+---+---+---+ 374 | 1 | x | | | x | If-Match | opaque | 0-8 | x | x | | 375 | 3 | x | x | - | | Uri-Host | string | 1-255 | | | | 376 | 4 | | | | x | ETag | opaque | 1-8 | x | x | | 377 | 5 | x | | | | If-None-Match | empty | 0 | x | x | | 378 | 6 | | x | - | | Observe | uint | 0-3 | x | x | x | 379 | 7 | x | x | - | | Uri-Port | uint | 0-2 | | | | 380 | 8 | | | | x | Location-Path | string | 0-255 | x | x | | 381 | 11 | x | x | - | x | Uri-Path | string | 0-255 | x | x | | 382 | 12 | | | | | Content-Format | uint | 0-2 | x | x | | 383 | 14 | | x | - | | Max-Age | uint | 0-4 | x | x | x | 384 | 15 | x | x | - | x | Uri-Query | string | 0-255 | x | x | | 385 | 17 | x | | | | Accept | uint | 0-2 | x | x | | 386 | 20 | | | | x | Location-Query | string | 0-255 | x | x | | 387 | 35 | x | x | - | | Proxy-Uri | string | 1-1034 | | | | 388 | 39 | x | x | - | | Proxy-Scheme | string | 1-255 | | | | 389 | 60 | | | x | | Size1 | uint | 0-4 | x | x | | 390 +----+---+---+---+---+----------------+--------+--------+---+---+---+ 391 C=Critical, U=Unsafe, N=NoCacheKey, R=Repeatable, 392 E=Encrypt, I=Integrity Protect, D=Duplicate. 394 Figure 4: Protected CoAP Options 396 Unless specified otherwise, CoAP options not listed in Figure 4 SHALL 397 be encrypted and integrity protected. 399 Specifications of new CoAP options SHOULD specify how they are 400 processed with OSCOAP. New COAP options SHOULD be encrypted and 401 integrity protected. New COAP options SHALL be integrity protected 402 unless a proxy needs to change the option, and SHALL be encrypted 403 unless a proxy needs to read the option. 405 The encrypted options are in general omitted from the protected CoAP 406 message and not visible to intermediary nodes (see Section 6.2 and 407 Section 6.4). Hence the actions resulting from the use of 408 corresponding options is analogous to the case of communicating 409 directly with the endpoint. For example, a client using an ETag 410 option will not be served by a proxy. 412 However, some options which are encrypted need to be present in the 413 protected CoAP message to support certain proxy functions. A CoAP 414 option which may be both encrypted in the COSE object of the 415 protected CoAP message, and also unencrypted as CoAP option in the 416 protected CoAP message, is called "duplicate". The "encrypted" value 417 of a duplicate option is intended for the destination endpoint and 418 the "unecrypted" value is intended for a proxy. The unencrypted 419 value is not integrity protected. 421 o The Max-Age option is duplicate. The unencrypted Max-Age SHOULD 422 have value zero to prevent caching of responses. The encrypted 423 Max-Age is used as defined in [RFC7252] taking into account that 424 it is not accessible proxies. 426 o The Observe option is duplicate. If used, then the encrypted 427 Observe and the unencrypted Observe SHALL have the same value. 428 The Observe option as used here targets the requirements of 429 Section 3.2 of [I-D.hartke-core-e2e-security-reqs]. 431 Specifications of new CoAP options SHOULD specify if the option is 432 duplicate and how it are processed with OSCOAP. New COAP options 433 SHOULD NOT be duplicate. 435 5. The COSE Object 437 This section defines how to use the COSE format [I-D.ietf-cose-msg] 438 to wrap and protect data in the unprotected CoAP message. OSCOAP 439 uses the COSE_Encrypted structure with an Authenticated Encryption 440 with Additional Data (AEAD) algorithm. 442 The mandatory to support AEAD algorithm is AES-CCM-64-64-128 defined 443 in Section 10.2 of [I-D.ietf-cose-msg]. For AES-CCM-64-64-128 the 444 length of Client Write Key and the Server Write Key SHALL be 128 445 bits, the length of the nonce, Client Write IV, and the Server Write 446 IV SHALL be 7 bytes, and the maximum Client Write Sequence Number and 447 Server Write Sequence Number SHALL be 2^56-1. The nonce is 448 constructed exactly like in Section 5.2.2 of [I-D.ietf-tls-tls13], 449 i.e. by padding the Client Write Sequence Number or the Server Write 450 Sequence Number with zeroes and XORing it with the static Client 451 Write IV or Server Write IV, respectively. 453 Since OSCOAP only makes use of a single COSE structure, there is no 454 need to explicitly specify the structure, and OSCOAP uses the 455 untagged version of the COSE_Encrypted structure (Section 2. of 456 [I-D.ietf-cose-msg]). If the COSE object has a different structure, 457 the receiver MUST reject the message, treating it as malformed. 459 We denote by Plaintext the data that is encrypted and integrity 460 protected, and by Additional Authenticated Data (AAD) the data that 461 is integrity protected only, in the COSE object. 463 The fields of COSE_Encrypted structure are defined as follows (see 464 example in Appendix C.4). 466 o The "Headers" field is formed by: 468 * The "protected" field, which SHALL include: 470 + The "Partial Initialization Vector" parameter. The value is 471 set to the Client Write Sequence Number, or the Server Write 472 Sequence Number, depending on whether the client or server 473 is sending the message. The Partial IV is a byte string 474 (type: bstr), where the length is the minimum length needed 475 to encode the sequence number. 477 + If the message is a CoAP request, the "kid" parameter. The 478 value is set to the Context Identifier (see Section 3). 480 * The "unprotected" field, which SHALL be empty. 482 o The "ciphertext" field is computed from the Plaintext and the 483 Additional Authenticated Data (AAD) and encoded as a byte string 484 (type: bstr), following Section 5.2 of [I-D.ietf-cose-msg]. 486 5.1. Plaintext 488 The Plaintext is formatted as a CoAP message without Header (see 489 Figure 5) consisting of: 491 o all CoAP Options present in the unprotected message which are 492 encrypted (see Section 4), in the order as given by the Option 493 number (each Option with Option Header including delta to previous 494 included encrypted option); and 496 o the CoAP Payload, if present, and in that case prefixed by the 497 one-byte Payload Marker (0xFF). 499 0 1 2 3 500 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 501 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 502 | Options to Encrypt (if any) ... ~ 503 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 504 |1 1 1 1 1 1 1 1| Payload (if any) ... ~ 505 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 507 Figure 5: Plaintext 509 5.2. Additional Authenticated Data 511 The Additional Authenticated Data ("Enc_structure") as described is 512 Section 5.3 of [I-D.ietf-cose-msg] includes (see Figure 6): 514 o the "context" parameter, which has value "Encrypted" 516 o the "protected" parameter, which includes the "protected" part of 517 the "Headers" field; 519 o the "external_aad" includes: 521 * the two first bytes of the CoAP header in the unprotected 522 message (including Version and Code) with Type and Token Length 523 bits set to 0; 525 * The Algorithm from the security context used for the exchange; 527 * the plaintext request URI composed from the request scheme and 528 Uri-* options according to the method described in Section 6.5 529 of [RFC7252], if the message is a CoAP request; and 531 * the Transaction Identifier (Tid) of the associated CoAP 532 request, if the message is a CoAP response (see Section 3). 534 0 1 2 3 535 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 536 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 537 |Ver|0 0 0 0 0 0| Code | Alg | ... ~ 538 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 539 ~ request URI (if request) / request Tid (if response) ~ 540 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 542 Figure 6: Additional Authenticated Data 544 The encryption process is described in Section 5.3 of 545 [I-D.ietf-cose-msg]. 547 6. Protecting CoAP Messages 549 6.1. Replay and Freshness Protection 551 In order to protect from replay of messages and verify freshness, a 552 CoAP endpoint SHALL maintain a Client Write Sequence Number, and a 553 Server Write Sequence Number associated to a security context, which 554 is identified with a Context Identifier (Cid). The two sequence 555 numbers are the highest sequence number the endpoint has sent and the 556 highest sequence number the endpoint has received. A client uses the 557 Client Write Sequence Number for protecting sent messages and the 558 Server Write Sequence Number for verifying received messages, and 559 vice versa for the server, as described in Section 3. 561 Depending on use case and ordering of messages provided by underlying 562 layers, an endpoint MAY maintain a sliding replay window for Sequence 563 Numbers of received messages associated to each Cid. 565 A receiving endpoint SHALL verify that the Sequence Number received 566 in the COSE object has not been received before in the security 567 context identified by the Cid. Note that for the server, the relevant 568 Sequence Number here is the Client Write Sequence Number and vice 569 versa for the client. 571 OSCOAP is a challenge-response protocol, where the response is 572 verified to match a prior request, by including the unique 573 transaction identifier (Tid as defined in Section 3) of the request 574 in the Additional Authenticated Data of the response message. 576 If a CoAP server receives a request with the Object-Security option, 577 then the server SHALL include the Tid of the request in the AAD of 578 the response, as described in Section 6.4. 580 If the CoAP client receives a response with the Object-Security 581 option, then the client SHALL verify the integrity of the response, 582 using the Tid of its own associated request in the AAD, as described 583 in Section 6.5. 585 6.2. Protecting the Request 587 Given an unprotected CoAP request, including header, options and 588 payload, the client SHALL perform the following steps to create a 589 protected CoAP request using a security context associated with the 590 target resource: 592 1. Increment the Client Write Sequence Number by one (note that this 593 means that sequence number 0 is never used). If the Client Write 594 Sequence Number exceeds the maximum number for the AEAD 595 algorithm, the client MUST NOT process any requests with the 596 given security context. The client SHOULD acquire a new security 597 context before this happens. The latter is out of scope of this 598 memo. 600 2. Compute the COSE object as specified in Section 5 602 * the nonce in the AEAD is created by XORing the static IV 603 (Client Write IV) with the partial IV (Client Write Sequence 604 Number). 606 3. Format the protected CoAP message as an ordinary CoAP message, 607 with the following Header, Options, and Payload, based on the 608 unprotected CoAP message: 610 * The CoAP header is the same as the unprotected CoAP message. 612 * The CoAP options which are encrypted and not duplicate 613 (Section 4) are removed. Any duplicate option which is 614 present has its unencrypted value. The Object-Security option 615 is added. 617 * If the unprotected CoAP message has no Payload, then the value 618 of the Object-Security option is the COSE object. If the 619 unprotected CoAP message has Payload, then the Object-Security 620 option is empty and the Payload of the protected CoAP message 621 is the COSE object. 623 The Client SHALL be able to find the correct security context with 624 use of the Token of the message exchange. 626 6.3. Verifying the Request 628 A CoAP server receiving a message containing the Object-Security 629 option SHALL perform the following steps, using the security context 630 identified by the Context Identifier in the "kid" parameter in the 631 received COSE object: 633 1. Verify the Sequence Number in the Partial IV parameter, as 634 described in Section 6.1. If it cannot be verified that the 635 Sequence Number has not been received before, the server MUST 636 stop processing the request. 638 2. Recreate the Additional Authenticated Data, as described in 639 Section 5. 641 3. Compose the nonce by XORing the static IV (Client Write IV) with 642 the Partial IV parameter, received in the COSE Object. 644 4. Retrieve the Client Write Key. 646 5. Verify and decrypt the message. If the verification fails, the 647 server MUST stop processing the request. 649 6. If the message verifies, update the Client Write Sequence Number 650 or Replay Window, as described in Section 6.1. 652 7. Restore the unprotected request by adding any decrypted options 653 or payload from the plaintext. Any duplicate options (Section 4) 654 are overwritten. The Object-Security option is removed. 656 6.4. Protecting the Response 658 A server receiving a valid request with a protected CoAP message 659 (i.e. containing an Object-Security option) SHALL respond with a 660 protected CoAP message. 662 Given an unprotected CoAP response, including header, options, and 663 payload, the server SHALL perform the following steps to create a 664 protected CoAP response, using the security context identified by the 665 Context Identifier of the received request: 667 1. Increment the Server Write Sequence Number by one (note that this 668 means that sequence number 0 is never used). If the Server Write 669 Sequence Number exceeds the maximum number for the AEAD 670 algorithm, the server MUST NOT process any more responses with 671 the given security context. The server SHOULD acquire a new 672 security context before this happens. The latter is out of scope 673 of this memo. 675 2. Compute the COSE object as specified in Section Section 5 677 * The nonce in the AEAD is created by XORing the static IV 678 (Server Write IV) and the Server Write Sequence Number. 680 3. Format the protected CoAP message as an ordinary CoAP message, 681 with the following Header, Options, and Payload based on the 682 unprotected CoAP message: 684 * The CoAP header is the same as the unprotected CoAP message. 686 * The CoAP options which are encrypted and not duplicate 687 (Section 4) are removed. Any duplicate option which is 688 present has its unencrypted value. The Object-Security option 689 is added. 691 * If the unprotected CoAP message has no Payload, then the value 692 of the Object-Security option is the COSE object. If the 693 unprotected CoAP message has Payload, then the Object-Security 694 option is empty, and the Payload of the protected CoAP message 695 is the COSE object. 697 Note the differences between generating a protected request, and a 698 protected response, for example whether "kid" is present in the 699 header, or whether Destination URI or Tid is present in the AAD, of 700 the COSE object. 702 6.5. Verifying the Response 704 A CoAP client receiving a message containing the Object-Security 705 option SHALL perform the following steps, using the security context 706 identified by the Token of the received response: 708 1. Verify the Sequence Number in the Partial IV parameter as 709 described in Section 6.1. If it cannot be verified that the 710 Sequence Number has not been received before, the client MUST 711 stop processing the response. 713 2. Recreate the Additional Authenticated Data as described in 714 Section 5. 716 3. Compose the nonce by XORing the static IV (Server Write IV) with 717 the Partial IV parameter, received in the COSE Object. 719 4. Retrieve the Server Write Key. 721 5. Verify and decrypt the message. If the verification fails, the 722 client MUST stop processing the response. 724 6. If the message verifies, update the Client Write Sequence Number 725 or Replay Window, as described in Section 6.1. 727 7. Restore the unprotected response by adding any decrypted options 728 or payload from the plaintext. Any duplicate options (Section 4) 729 are overwritten. The Object-Security option is removed. 731 7. Security Considerations 733 In scenarios with intermediary nodes such as proxies or brokers, 734 transport layer security such as DTLS only protects data hop-by-hop. 735 As a consequence the intermediary nodes can read and modify 736 information. The trust model where all intermediate nodes are 737 considered trustworthy is problematic, not only from a privacy 738 perspective, but also from a security perspective, as the 739 intermediaries are free to delete resources on sensors and falsify 740 commands to actuators (such as "unlock door", "start fire alarm", 741 "raise bridge"). Even in the rare cases, where all the owners of the 742 intermediary nodes are fully trusted, attacks and data breaches make 743 such an architecture brittle. 745 DTLS protects hop-by-hop the entire CoAP message, including header, 746 options, and payload. OSCOAP protects end-to-end the payload, and 747 all information in the options and header, that is not required for 748 forwarding (see Section 4). DTLS and OSCOAP can be combined. 750 The CoAP message layer, however, cannot be protected end-to-end 751 through intermediary devices since the parameters Type and Message 752 ID, as well as Token and Token Length may be changed by a proxy. 753 Moreover, messages that are not possible to verify should for 754 security reasons not always be acknowledged but in some cases be 755 silently dropped. This would not comply with CoAP message layer, but 756 does not have an impact on the application layer security solution, 757 since message layer is excluded from that. 759 The specification in this memo assumes that there is an established 760 security context. [I-D.ietf-ace-oauth-authz] presents a method for a 761 trusted third party (Authorization Server) to enable key 762 establishment between potentially constrained nodes, using OAuth and 763 PoP Tokens. [I-D.selander-ace-cose-ecdhe] describes a Diffie-Hellman 764 key exchange, authenticated with pre-established keys, and a key 765 derivation method for producing a security context, suitable for 766 OSCOAP. The two methods can be combined, enabling a client and 767 server with relation to a trusted third party to establish a security 768 context with forward secrecy. 770 For symmetric encryption it is required to have a unique nonce for 771 each message, for which the sequence numbers in the COSE message 772 field "Partial IV" is used. The nonce SHALL be the XOR of a static 773 IV and the sequence number. The static IVs (Client Write IV and 774 Server Write IV) SHOULD be established between sender and receiver 775 before the message is sent, to avoid the overhead of sending it in 776 each message, for example using the method in 777 [I-D.selander-ace-cose-ecdhe]. 779 As the receiver accepts any sequence number larger than the one 780 previously received, the problem of sequence number synchronization 781 is avoided. The alternatives have issues: very constrained devices 782 may not be able to support accurate time, or to generate and store 783 large numbers of random nonces. The requirement to change key at 784 counter wrap is a complication, but it also forces the user of this 785 specification to think about implementing key renewal. 787 Block-wise transfers as currently defined in [I-D.ietf-core-block] 788 cannot be protected end-to-end because the payload as well as the 789 Block1/Block2 options may be changed in an unpredictable way by a 790 proxy. Since [I-D.ietf-core-block] allows for any proxy to fragment 791 the payload, an endpoint receiving a message fragment with a block 792 option is not able to verify integrity of that fragment. As a 793 consequence, block-wise disables end-to-end security: an adversary 794 may inject an unlimited number of messages with a block option 795 claiming it to be a sequence of message fragments without the 796 receiving endpoint being able to disprove the claim. 798 If instead the payload and block options Block1/Block2 were not 799 allowed to be changed by intermediate devices, then the message 800 fragments could be integrity protected end-to-end. In that case each 801 individual block can be securely verified by the receiver, 802 retransmission securely requested etc. Since the blocks are 803 enumerated sequentially, and carry information about whether this 804 fragment is the last, when all blocks have been securely received is 805 enough to prove that the entire message has been securely 806 transferred. 808 8. Privacy Considerations 810 Privacy threats executed through intermediate nodes are considerably 811 reduced by means of OSCOAP. End-to-end integrity protection and 812 encryption of CoAP payload and all options that are not used for 813 forwarding, provides mitigation against attacks on sensor and 814 actuator communication, which may have a direct impact the personal 815 sphere. 817 CoAP headers sent in plaintext allow for example matching of CON and 818 ACK (CoAP Message Identifier), matching of request and responses 819 (Token) and traffic analysis. 821 9. IANA Considerations 823 Note to RFC Editor: Please replace all occurrences of "[[this 824 document]]" with the RFC number of this specification. 826 9.1. CoAP Option Number Registration 828 The Object-Security option is added to the CoAP Option Numbers 829 registry: 831 +--------+-----------------+-------------------+ 832 | Number | Name | Reference | 833 +--------+-----------------+-------------------+ 834 | TBD | Object-Security | [[this document]] | 835 +--------+-----------------+-------------------+ 837 9.2. Media Type Registrations 839 The "application/oscon" media type is added to the Media Types 840 registry: 842 Type name: application 844 Subtype name: cose 846 Required parameters: N/A 848 Optional parameters: N/A 850 Encoding considerations: binary 852 Security considerations: See the Security Considerations section 853 of [[this document]]. 855 Interoperability considerations: N/A 857 Published specification: [[this document]] 859 Applications that use this media type: To be identified 861 Fragment identifier considerations: N/A 863 Additional information: 865 * Magic number(s): N/A 867 * File extension(s): N/A 869 * Macintosh file type code(s): N/A 871 Person & email address to contact for further information: 872 iesg@ietf.org 874 Intended usage: COMMON 876 Restrictions on usage: N/A 878 Author: Goeran Selander, goran.selander@ericsson.com 880 Change Controller: IESG 882 Provisional registration? No 884 9.3. CoAP Content Format Registration 886 The "application/oscon" content format is added to the CoAP Content 887 Format registry: 889 +-------------------+----------+----+-------------------+ 890 | Media type | Encoding | ID | Reference | 891 +-------------------+----------+----+-------------------+ 892 | application/oscon | - | 70 | [[this document]] | 893 +-------------------+----------+----+-------------------+ 895 10. Acknowledgments 897 Klaus Hartke has independently been working on the same problem and a 898 similar solution: establishing end-to-end security across proxies by 899 adding a CoAP option. We are grateful to Malisa Vucinic for 900 providing helpful and timely reviews of previous versions of the 901 draft. 903 11. References 905 11.1. Normative References 907 [I-D.ietf-cose-msg] 908 Schaad, J., "CBOR Encoded Message Syntax", draft-ietf- 909 cose-msg-10 (work in progress), February 2016. 911 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 912 Requirement Levels", BCP 14, RFC 2119, 913 DOI 10.17487/RFC2119, March 1997, 914 . 916 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 917 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 918 January 2012, . 920 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 921 Application Protocol (CoAP)", RFC 7252, 922 DOI 10.17487/RFC7252, June 2014, 923 . 925 [RFC7641] Hartke, K., "Observing Resources in the Constrained 926 Application Protocol (CoAP)", RFC 7641, 927 DOI 10.17487/RFC7641, September 2015, 928 . 930 11.2. Informative References 932 [I-D.hartke-core-e2e-security-reqs] 933 Selander, G., Palombini, F., Hartke, K., and L. Seitz, 934 "Requirements for CoAP End-To-End Security", draft-hartke- 935 core-e2e-security-reqs-00 (work in progress), March 2016. 937 [I-D.ietf-ace-oauth-authz] 938 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 939 H. Tschofenig, "Authorization for the Internet of Things 940 using OAuth 2.0", draft-ietf-ace-oauth-authz-01 (work in 941 progress), February 2016. 943 [I-D.ietf-core-block] 944 Bormann, C. and Z. Shelby, "Block-wise transfers in CoAP", 945 draft-ietf-core-block-18 (work in progress), September 946 2015. 948 [I-D.ietf-tls-tls13] 949 Rescorla, E., "The Transport Layer Security (TLS) Protocol 950 Version 1.3", draft-ietf-tls-tls13-11 (work in progress), 951 December 2015. 953 [I-D.selander-ace-cose-ecdhe] 954 Selander, G., Mattsson, J., and F. Palombini, "Ephemeral 955 Diffie-Hellman Over COSE (EDHOC)", draft-selander-ace- 956 cose-ecdhe-00 (work in progress), March 2016. 958 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 959 Constrained-Node Networks", RFC 7228, 960 DOI 10.17487/RFC7228, May 2014, 961 . 963 Appendix A. Overhead 965 OSCOAP transforms an unprotected CoAP message to a protected CoAP 966 message, and the protected CoAP message is larger than the 967 unprotected CoAP message. This appendix illustrates the message 968 expansion. 970 A.1. Length of the Object-Security Option 972 The protected CoAP message contains the COSE object. The COSE object 973 is included in the payload if the unprotected CoAP message has 974 payload or else in the Object-Security option. In the former case 975 the Object-Security option is empty. So the length of the Object- 976 Security option is either zero or the size of the COSE object, 977 depending on whether the CoAP message has payload or not. 979 Length of Object-Security option = { 0, size of COSE Object } 981 A.2. Size of the COSE Object 983 The size of the COSE object is the sum of the sizes of 985 o the Header parameters, 987 o the Ciphertext (excluding the Tag), 989 o the Tag, and 991 o data incurred by the COSE format itself (including CBOR encoding). 993 Let's analyse the contributions one at a time: 995 o The header parameters of the COSE object are the Context 996 Identifier (Cid) and the Sequence Number (Seq) (also known as the 997 Transaction Identifier (Tid)) if the message is a request, and Seq 998 only if the message is a response (see Section 5). 1000 * The size of Cid depends on the number of simultaneous clients, 1001 and must be chosen so that the server can uniquely identify the 1002 requesting client. For example, in the case of an ACE-based 1003 authentication and authorization model 1004 [I-D.ietf-ace-oauth-authz], the Authorization Server or the 1005 server itself can define the context identifier of all clients 1006 interacting with a particular server, in which case the size of 1007 Cid can be proportional to the logarithm of number of 1008 authorized clients. 1010 + As Cids of different lengths can be used by different 1011 client, it is RECOMMENDED to start assigning Cids of length 1012 1 byte (0x00, 0x01, ..., 0xff), and then when all 1 byte 1013 Cids are in use, start handling out Cids with a length of 1014 two bytes (0x0000, 0x0001, ..., 0xffff). 1016 * The size of Seq is variable, and increases with the number of 1017 messages exchanged. 1019 * As the nonce is generated from the padded Sequence Number and a 1020 previously agreed upon static IV it is not required to send the 1021 whole nonce in the message. 1023 o The Ciphertext, excluding the Tag, is the encryption of the 1024 payload and the encrypted options Section 4, which are present in 1025 the unprotected CoAP message. 1027 o The size of the Tag depends on the Algorithm. For the OSCOAP 1028 mandatory algorithm AES-CCM-64-64-128, the Tag is 8 bytes. 1030 o The overhead from the COSE format itself depends on the sizes of 1031 the previous fields, and is of the order of 10 bytes. 1033 A.3. Message Expansion 1035 The message expansion is not the size of the COSE object. The 1036 ciphertext in the COSE object is encrypted payload and options of the 1037 unprotected CoAP message - the plaintext of which is removed from the 1038 protected CoAP message. Since the size of the ciphertext is the same 1039 as the corresponding plaintext, there is no message expansion due to 1040 encryption; payload and options are just represented in a different 1041 way in the protected CoAP message: 1043 o The encrypted payload is in the payload of the protected CoAP 1044 message 1046 o The encrypted options are in the Object-Security option or within 1047 the payload. 1049 Therefore the OSCOAP message expansion is due to Cid (if present), 1050 Seq, Tag, and COSE overhead: 1052 Message Overhead = Cid + Seq + Tag + COSE Overhead 1054 Figure 7: OSCOAP message expansion 1056 A.4. Example 1058 This section gives an example of message expansion in a request with 1059 OSCOAP. 1061 In this example we assume an extreme 4-byte Cid, based on the 1062 assumption of an ACE deployment with billions of clients requesting 1063 access to this particular server. (A typical Cid, will be 1-2 byte 1064 as is discussed in Appendix A.2.) 1066 o Cid: 0xa1534e3c 1068 In the example the sequence number is 225, requiring 1 byte to 1069 encode. (The size of Seq could be larger depending on how many 1070 messages that has been sent as is discussed in Appendix A.2.) 1072 o Seq: 225 1074 The example is based on AES-CCM-64-64-128. 1076 o Tag is 8 bytes 1077 The COSE object is represented in Figure 8 using CBOR's diagnostic 1078 notation. 1080 [ 1081 h'a20444a1534e3c0641e2', # protected: 1082 {04:h'a1534e3c', 1083 06:h'e2'} 1084 {}, # unprotected: - 1085 Tag # ciphertext + 8 byte authentication tag 1086 ] 1088 Figure 8: Example of message expansion 1090 Note that the encrypted CoAP options and payload are omitted since we 1091 target the message expansion (see Appendix A.3). Therefore the size 1092 of the COSE Ciphertext equals the size of the Tag, which is 8 bytes. 1094 The COSE object encodes to a total size of 22 bytes, which is the 1095 message expansion in this example. The COSE overhead in this example 1096 is 22 - (4 + 1 + 8) = 9 bytes, according to the formula in Figure 7. 1097 Note that in this example two bytes in the COSE overhead are used to 1098 encode the length of Cid and the length of Seq. 1100 Figure 9 summarizes these results. 1102 +---------+---------+----------+------------+ 1103 | Tid | Tag | COSE OH | Message OH | 1104 +---------+---------+----------+------------+ 1105 | 5 bytes | 8 bytes | 9 bytes | 22 bytes | 1106 +---------+---------+----------+------------+ 1108 Figure 9: Message overhead for a 5-byte Tid and 8-byte Tag. 1110 Appendix B. Examples 1112 This section gives examples of OSCOAP. The message exchanges are 1113 made, based on the assumption that there is a security context 1114 established between client and server. For simplicity, these 1115 examples only indicate the content of the messages without going into 1116 detail of the COSE message format. 1118 B.1. Secure Access to Actuator 1120 Here is an example targeting the scenario in Section 3.1 of 1121 [I-D.hartke-core-e2e-security-reqs]. The example illustrates a 1122 client requesting valve 34 to be turned to position 3 (PUT /valve34 1123 with payload value "3"), and getting a confirmation. The CoAP 1124 options Uri-Path and Payload are encrypted and integrity protected, 1125 and the CoAP header field Code is integrity protected (see 1126 Section 4). 1128 Client Proxy Server 1129 | | | 1130 +----->| | Code: 0.03 (PUT) 1131 | PUT | | Token: 0x8c 1132 | | | Object-Security: - 1133 | | | Payload: [cid:5fdc, seq:42, 1134 | | | {Uri-Path:"valve34", "3"}, 1135 | | | ] 1136 | | | 1137 | +----->| Code: 0.03 (PUT) 1138 | | PUT | Token: 0x7b 1139 | | | Object-Security: - 1140 | | | Payload: [cid:5fdc, seq:42, 1141 | | | {Uri-Path:"valve34", "3"}, 1142 | | | ] 1143 | | | 1144 | |<-----+ Code: 2.04 (Changed) 1145 | | 2.04 | Token: 0x7b 1146 | | | Max-Age: 0 1147 | | | Object-Security: [seq:56, ] 1148 | | | Payload: - 1149 | | | 1150 |<-----+ | Code: 2.04 (Changed) 1151 | 2.04 | | Token: 0x8c 1152 | | | Max-Age: 0 1153 | | | Object-Security: [seq:56, ] 1154 | | | Payload: - 1155 | | | 1157 Figure 10: Indication of CoAP PUT protected with OSCOAP. The 1158 brackets [ ... ] indicate a COSE object. The brackets { ... } 1159 indicate encrypted data. 1161 Since the unprotected request message (PUT) has payload ("3"), the 1162 COSE object (indicated with [ ... ]) is carried as the CoAP payload. 1163 Since the unprotected response message (Changed) has no payload, the 1164 Object-Security option carries the COSE object as its value. 1166 The COSE header of the request contains a Context Identifier 1167 (cid:5fdc), indicating which security context was used to protect the 1168 message and a Sequence Number (seq:42). 1170 The option Uri-Path (valve34) and payload ("3") are formatted as 1171 indicated in Section 5, and encrypted in the COSE Ciphertext 1172 (indicated with { ... }). 1174 The server verifies that the Sequence Number has not been received 1175 before (see Section 6.1). The client verifies that the Sequence 1176 Number has not been received before and that the response message is 1177 generated as a response to the sent request message (see 1178 Section 6.1). 1180 B.2. Secure Subscribe to Sensor 1182 Here is an example targeting the scenario in Section 3.2 of 1183 [I-D.hartke-core-e2e-security-reqs]. The example illustrates a 1184 client requesting subscription to a blood sugar measurement resource 1185 (GET /glucose), and first receiving the value 220 mg/dl, and then a 1186 second reading with value 180 mg/dl. The CoAP options Observe, Uri- 1187 Path, Content-Format, and Payload are encrypted and integrity 1188 protected, and the CoAP header field Code is integrity protected (see 1189 Section 4). 1191 Client Proxy Server 1192 | | | 1193 +----->| | Code: 0.01 (GET) 1194 | GET | | Token: 0x83 1195 | | | Observe: 0 1196 | | | Object-Security: [cid:ca, seq:15b7, {Observe:0, 1197 | | | Uri-Path:"glucose"}, ] 1198 | | | Payload: - 1199 | | | 1200 | +----->| Code: 0.01 (GET) 1201 | | GET | Token: 0xbe 1202 | | | Observe: 0 1203 | | | Object-Security: [cid:ca, seq:15b7, {Observe:0, 1204 | | | Uri-Path:"glucose"}, ] 1205 | | | Payload: - 1206 | | | 1207 | |<-----+ Code: 2.05 (Content) 1208 | | 2.05 | Token: 0xbe 1209 | | | Max-Age: 0 1210 | | | Observe: 1 1211 | | | Object-Security: - 1212 | | | Payload: [seq:32c2, {Observe:1, 1213 | | | Content-Format:0, "220"}, ] 1214 | | | 1215 |<-----+ | Code: 2.05 (Content) 1216 | 2.05 | | Token: 0x83 1217 | | | Max-Age: 0 1218 | | | Observe: 1 1219 | | | Object-Security: - 1220 | | | Payload: [seq:32c2, {Observe:1, 1221 | | | Content-Format:0, "220"}, ] 1223 ... ... ... 1224 | | | 1225 | |<-----+ Code: 2.05 (Content) 1226 | | 2.05 | Token: 0xbe 1227 | | | Max-Age: 0 1228 | | | Observe: 2 1229 | | | Object-Security: - 1230 | | | Payload: [seq:32c6, {Observe:2, 1231 | | | Content-Format:0, "180"}, ] 1232 | | | 1233 |<-----+ | Code: 2.05 (Content) 1234 | 2.05 | | Token: 0x83 1235 | | | Max-Age: 0 1236 | | | Observe: 2 1237 | | | Object-Security: - 1238 | | | Payload: [seq:32c6, {Observe:2, 1239 | | | Content-Format:0, "180"}, ] 1240 | | | 1242 Figure 11: Indication of CoAP GET protected with OSCOAP. The 1243 brackets [ ... ] indicates COSE object. The bracket { ... } 1244 indicates encrypted data. 1246 Since the unprotected request message (GET) has no payload, the COSE 1247 object (indicated with [ ... ]) is carried in the Object-Security 1248 option value. Since the unprotected response message (Content) has 1249 payload, the Object-Security option is empty, and the COSE object is 1250 carried as the payload. 1252 The COSE header of the request contains a Context Identifier 1253 (cid:ca), indicating which security context was used to protect the 1254 message and a Sequence Number (seq:15b7). 1256 The options Observe, Content-Format and the payload are formatted as 1257 indicated in Section 5, and encrypted in the COSE ciphertext 1258 (indicated with { ... }). 1260 The server verifies that the Sequence Number has not been received 1261 before (see Section 6.1). The client verifies that the Sequence 1262 Number has not been received before and that the response message is 1263 generated as a response to the subscribe request. 1265 Appendix C. Object Security of Content (OSCON) 1267 OSCOAP protects message exchanges end-to-end between a certain client 1268 and a certain server, targeting the security requirements in 1269 Section 3.1 and 3.2 of [I-D.hartke-core-e2e-security-reqs]. In 1270 contrast, many use cases require one and the same message to be 1271 protected for, and verified by, multiple endpoints, see Sections 3.3 1272 - 3.5 of [I-D.hartke-core-e2e-security-reqs]. Those security 1273 requirements can be addressed by protecting essentially the payload/ 1274 content of individual messages using the COSE format 1275 ([I-D.ietf-cose-msg]), rather than the entire request/response 1276 message exchange. This is referred to as Object Security of Content 1277 (OSCON). 1279 OSCON transforms an unprotected CoAP message into a protected CoAP 1280 message in the following way: the payload of the unprotected CoAP 1281 message is wrapped by a COSE object, which replaces the payload of 1282 the unprotected CoAP message. We call the result the "protected" 1283 CoAP message. 1285 The unprotected payload SHALL be the plaintext/payload of the COSE 1286 object. The 'protected' field of the COSE object 'Headers' SHALL 1287 include the context identifier, both for requests and responses. If 1288 the unprotected CoAP message includes a Content-Format option, then 1289 the COSE object SHALL include a protected 'content type' field, whose 1290 value is set to the unprotected message Content-Format value. The 1291 Content-Format option of the protected CoAP message SHALL be replaced 1292 with "application/oscon" (Section 9) 1294 The COSE object SHALL be protected (encrypted) and verified 1295 (decrypted) as described in ([I-D.ietf-cose-msg]). 1297 In the case of symmetric encryption, the same key and nonce SHALL NOT 1298 be used twice. The use of sequence numbers for partial IV as 1299 specified for OSCOAP MAY be used. of sequence numbers for replay 1300 protection as described in Section 6.1 MAY be used. The use of time 1301 stamps in the COSE header parameter 'operation time' 1302 [I-D.ietf-cose-msg] for freshness MAY be used. 1304 OSCON SHALL NOT be used in cases where CoAP header fields (such as 1305 Code or Version) or CoAP options need to be integrity protected or 1306 encrypted. OSCON SHALL NOT be used in cases which require a secure 1307 binding between request and response. 1309 The scenarios in Sections 3.3 - 3.5 of 1310 [I-D.hartke-core-e2e-security-reqs] assume multiple receivers for a 1311 particular content. In this case the use of symmetric keys does not 1312 provide data origin authentication. Therefore the COSE object SHOULD 1313 in general be protected with a digital signature. 1315 C.1. Overhead OSCON 1317 In general there are four different kinds of ciphersuites that need 1318 to be supported: message authentication code, digital signature, 1319 authenticated encryption, and symmetric encryption + digital 1320 signature. The use of digital signature is necessary for 1321 applications with many legitimate recipients of a given message, and 1322 where data origin authentication is required. 1324 To distinguish between these different cases, the tagged structures 1325 of COSE are used (see Section 2 of [I-D.ietf-cose-msg]). 1327 The size of the COSE message for selected algorithms are detailed in 1328 this section. 1330 The size of the header is shown separately from the size of the MAC/ 1331 signature. A 4-byte Context Identifier and a 1-byte Sequence Number 1332 are used throughout all examples, with these values: 1334 o Cid: 0xa1534e3c 1336 o Seq: 0xa3 1338 For each scheme, we indicate the fixed length of these two parameters 1339 ("Cid+Seq" column) and of the Tag ("MAC"/"SIG"/"TAG"). The "Message 1340 OH" column shows the total expansions of the CoAP message size, while 1341 the "COSE OH" column is calculated from the previous columns 1342 following the formula in Figure 7. 1344 Overhead incurring from CBOR encoding is also included in the COSE 1345 overhead count. 1347 To make it easier to read, COSE objects are represented using CBOR's 1348 diagnostic notation rather than a binary dump. 1350 C.2. MAC Only 1352 This example is based on HMAC-SHA256, with truncation to 8 bytes 1353 (HMAC 256/64). 1355 Since the key is implicitly known by the recipient, the 1356 COSE_Mac0_Tagged structure is used (Section 6.2 of 1357 [I-D.ietf-cose-msg]). 1359 The object in COSE encoding gives: 1361 996( # COSE_Mac0_Tagged 1362 [ 1363 h'a20444a1534e3c0641a3', # protected: 1364 {04:h'a1534e3c', 1365 06:h'a3'} 1366 {}, # unprotected 1367 h'', # payload 1368 MAC # truncated 8-byte MAC 1369 ] 1370 ) 1372 This COSE object encodes to a total size of 26 bytes. 1374 Figure 12 summarizes these results. 1376 +------------------+-----+-----+---------+------------+ 1377 | Structure | Tid | MAC | COSE OH | Message OH | 1378 +------------------+-----+-----+---------+------------+ 1379 | COSE_Mac0_Tagged | 5 B | 8 B | 13 B | 26 B | 1380 +------------------+-----+-----+---------+------------+ 1382 Figure 12: Message overhead for a 5-byte Tid using HMAC 256/64 1384 C.3. Signature Only 1386 This example is based on ECDSA, with a signature of 64 bytes. 1388 Since only one signature is used, the COSE_Sign1_Tagged structure is 1389 used (Section 4.2 of [I-D.ietf-cose-msg]). 1391 The object in COSE encoding gives: 1393 997( # COSE_Sign1_Tagged 1394 [ 1395 h'a20444a1534e3c0641a3', # protected: 1396 {04:h'a1534e3c', 1397 06:h'a3'} 1398 {}, # unprotected 1399 h'', # payload 1400 SIG # 64-byte signature 1401 ] 1402 ) 1404 This COSE object encodes to a total size of 83 bytes. 1406 Figure 13 summarizes these results. 1408 +-------------------+-----+------+---------+------------+ 1409 | Structure | Tid | SIG | COSE OH | Message OH | 1410 +-------------------+-----+------+---------+------------+ 1411 | COSE_Sign1_Tagged | 5 B | 64 B | 14 B | 83 bytes | 1412 +-------------------+-----+------+---------+------------+ 1414 Figure 13: Message overhead for a 5-byte Tid using 64 byte ECDSA 1415 signature. 1417 C.4. Authenticated Encryption with Additional Data (AEAD) 1419 This example is based on AES-CCM with the MAC truncated to 8 bytes. 1421 It is assumed that the nonce is generated from the Sequence Number 1422 and some previously agreed upon static IV. This means it is not 1423 required to explicitly send the whole nonce in the message. 1425 Since the key is implicitly known by the recipient, the 1426 COSE_Encrypted_Tagged structure is used (Section 5.2 of 1427 [I-D.ietf-cose-msg]). 1429 The object in COSE encoding gives: 1431 993( # COSE_Encrypted_Tagged 1432 [ 1433 h'a20444a1534e3c0641a3', # protected: 1434 {04:h'a1534e3c', 1435 06:h'a3'} 1436 {}, # unprotected 1437 TAG # ciphertext + truncated 8-byte TAG 1438 ] 1439 ) 1441 This COSE object encodes to a total size of 25 bytes. 1443 Figure 14 summarizes these results. 1445 +-----------------------+-----+-----+---------+------------+ 1446 | Structure | Tid | TAG | COSE OH | Message OH | 1447 +-----------------------+-----+-----+---------+------------+ 1448 | COSE_Encrypted_Tagged | 5 B | 8 B | 12 B | 25 bytes | 1449 +-----------------------+-----+-----+---------+------------+ 1451 Figure 14: Message overhead for a 5-byte Tid using AES_128_CCM_8. 1453 C.5. Symmetric Encryption with Asymmetric Signature (SEAS) 1455 This example is based on AES-CCM and ECDSA with 64 bytes signature. 1456 The same assumption on the security context as in Appendix C.4. COSE 1457 defines the field 'counter signature' that is used here to sign a 1458 COSE_Encrypted_Tagged message (see Section 3 of [I-D.ietf-cose-msg]). 1460 The object in COSE encoding gives: 1462 993( # COSE_Encrypted_Tagged 1463 [ 1464 h'a20444a1534e3c0641a3', # protected: 1465 {04:h'a1534e3c', 1466 06:h'a3'} 1467 {7:SIG}, # unprotected: 1468 07: 64 bytes signature 1469 TAG # ciphertext + truncated 8-byte TAG 1470 ] 1471 ) 1473 This COSE object encodes to a total size of 92 bytes. 1475 Figure 15 summarizes these results. 1477 +-----------------------+-----+-----+------+---------+------------+ 1478 | Structure | Tid | TAG | SIG | COSE OH | Message OH | 1479 +-----------------------+-----+-----+------+---------+------------+ 1480 | COSE_Encrypted_Tagged | 5 B | 8 B | 64 B | 15 B | 92 B | 1481 +-----------------------+-----+-----+------+---------+------------+ 1483 Figure 15: Message overhead for a 5-byte Tid using AES-CCM 1484 countersigned with ECDSA. 1486 Authors' Addresses 1488 Goeran Selander 1489 Ericsson AB 1490 Farogatan 6 1491 Kista SE-16480 Stockholm 1492 Sweden 1494 Email: goran.selander@ericsson.com 1495 John Mattsson 1496 Ericsson AB 1497 Farogatan 6 1498 Kista SE-16480 Stockholm 1499 Sweden 1501 Email: john.mattsson@ericsson.com 1503 Francesca Palombini 1504 Ericsson AB 1505 Farogatan 6 1506 Kista SE-16480 Stockholm 1507 Sweden 1509 Email: francesca.palombini@ericsson.com 1511 Ludwig Seitz 1512 SICS Swedish ICT 1513 Scheelevagen 17 1514 Lund 22370 1515 Sweden 1517 Email: ludwig@sics.se