idnits 2.17.1 draft-selander-ace-object-security-02.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 : ---------------------------------------------------------------------------- == There are 4 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 1851 has weird spacing: '... Broker lishe...' -- The document date (June 29, 2015) is 3223 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 6347 (Obsoleted by RFC 9147) == Outdated reference: A later version (-10) exists of draft-ietf-ace-usecases-04 == Outdated reference: A later version (-01) exists of draft-schaad-cose-msg-00 == Outdated reference: A later version (-21) exists of draft-ietf-core-block-17 -- Obsolete informational reference (is this intentional?): RFC 7231 (Obsoleted by RFC 9110) Summary: 1 error (**), 0 flaws (~~), 6 warnings (==), 2 comments (--). 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: December 31, 2015 Ericsson 6 L. Seitz 7 SICS Swedish ICT 9 June 29, 2015 11 Object Security for CoAP (OSCOAP) 12 draft-selander-ace-object-security-02 13 Abstract 15 This memo presents OSCOAP, a scheme for protection of request and 16 response messages of the Constrained Application Protocol (CoAP), 17 using data object security. 19 Status of this Memo 21 This Internet-Draft is submitted to IETF in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF), its areas, and its working groups. Note that 26 other groups may also distribute working documents as 27 Internet-Drafts. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress". 34 The list of current Internet-Drafts can be accessed at 35 http://www.ietf.org/1id-abstracts.html 37 The list of Internet-Draft Shadow Directories can be accessed at 38 http://www.ietf.org/shadow.html 40 Copyright and License Notice 42 Copyright (c) 2015 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (http://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 58 1.1 Terminology . . . . . . . . . . . . . . . . . . . . . . . . 4 59 2. Background . . . . . . . . . . . . . . . . . . . . . . . . . . 5 60 3. End-to-end Security in Presence of Intermediary Nodes . . . . . 6 61 4. Secure Message . . . . . . . . . . . . . . . . . . . . . . . . 7 62 4.1 Secure Message format . . . . . . . . . . . . . . . . . . . 8 63 4.1.1 Secure Message Header . . . . . . . . . . . . . . . . . 8 64 4.1.2 Secure Message Body . . . . . . . . . . . . . . . . . . 9 65 4.1.2.1 Secure Signed Message Body . . . . . . . . . . . . . 9 66 4.1.2.2 Secure Encrypted Message Body . . . . . . . . . . . 9 67 4.1.3 Secure Message Tag . . . . . . . . . . . . . . . . . . . 9 68 5. Message Protection . . . . . . . . . . . . . . . . . . . . . . 10 69 5.1 CoAP Message Protection (Mode:COAP) . . . . . . . . . . . . 10 70 5.1.1 The Sig Option . . . . . . . . . . . . . . . . . . . . . 10 71 5.1.1.1 Option Structure . . . . . . . . . . . . . . . . . . 10 72 5.1.1.2 Integrity Protection and Verification . . . . . . . 11 73 5.1.1.3 SSM Body . . . . . . . . . . . . . . . . . . . . . . 11 74 5.1.2 The Enc Option . . . . . . . . . . . . . . . . . . . . . 12 75 5.1.2.1 Option Structure . . . . . . . . . . . . . . . . . . 12 76 5.1.2.2 Encryption and Decryption . . . . . . . . . . . . . 13 77 5.1.2.3 SEM Body . . . . . . . . . . . . . . . . . . . . . . 13 78 5.1.2.4 CoAP Message with Enc Option . . . . . . . . . . . . 13 79 5.1.3 SM Tag . . . . . . . . . . . . . . . . . . . . . . . . . 14 80 5.2 Payload Only Protection (Mode:PAYL) . . . . . . . . . . . . 14 81 5.3 Replay Protection and Freshness . . . . . . . . . . . . . . 15 82 5.3.1 Replay Protection . . . . . . . . . . . . . . . . . . . 15 83 5.3.2 Freshness . . . . . . . . . . . . . . . . . . . . . . . 15 84 6. Security Considerations . . . . . . . . . . . . . . . . . . . . 15 85 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . . 17 86 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 87 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 18 88 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 19 89 10.1 Normative References . . . . . . . . . . . . . . . . . . . 19 90 10.2 Informative References . . . . . . . . . . . . . . . . . . 19 91 Appendix A. Which CoAP Header Fields and Options to Protect . . . 20 92 A.1 CoAP Header Fields . . . . . . . . . . . . . . . . . . . . . 20 93 A.2 CoAP Options . . . . . . . . . . . . . . . . . . . . . . . . 20 94 A.2.1 Integrity Protection . . . . . . . . . . . . . . . . . . 20 95 A.2.1.1 Proxy-Scheme . . . . . . . . . . . . . . . . . . . . 21 96 A.2.1.2 Uri-* . . . . . . . . . . . . . . . . . . . . . . . 21 97 A.2.2 Encryption . . . . . . . . . . . . . . . . . . . . . . . 22 98 A.2.3 Summary . . . . . . . . . . . . . . . . . . . . . . . . 22 99 Appendix B. JOSE Profile of SM . . . . . . . . . . . . . . . . . 23 100 B.1 JWS as Secure Signed Message . . . . . . . . . . . . . . . 23 101 B.2 JWE as Secure Encrypted Message . . . . . . . . . . . . . . 24 102 B.3 "seq" (Sequence Number) Header Parameter . . . . . . . . . . 24 103 B.4 "cid" (Context Identifier) Header Parameter . . . . . . . . 24 104 Appendix C. Compact Secure Message . . . . . . . . . . . . . . . 24 105 Appendix D. COSE Profile of SM . . . . . . . . . . . . . . . . . 26 106 D.1 COSE_Sign or COSE_mac as Secure Signed Message . . . . . . 26 107 D.1.1 COSE_Sign as Secure Signed Message . . . . . . . . . . 27 108 D.1.2 COSE_mac as Secure Signed Message . . . . . . . . . . . 27 109 D.2 COSE_encrypt as Secure Encrypted Message . . . . . . . . . 28 110 D.3 COSE optimizations . . . . . . . . . . . . . . . . . . . . . 29 111 Appendix E. Comparison of message sizes . . . . . . . . . . . . . 30 112 E.1 SSM: Message Authentication Code . . . . . . . . . . . . . . 30 113 E.2 SSM: Digital Signature . . . . . . . . . . . . . . . . . . . 31 114 E.3 SEM: Authenticated Encryption . . . . . . . . . . . . . . . 32 115 E.4 SEM: Symmetric Encryption + Digital Signature . . . . . . . 34 116 Appendix F. Examples . . . . . . . . . . . . . . . . . . . . . . 36 117 F.1 CoAP Message Protection . . . . . . . . . . . . . . . . . . 36 118 F.1.1 Integrity Protection of CoAP Message Exchange . . . . . 36 119 F.1.2 Additional Encryption of CoAP Message . . . . . . . . . 38 120 F.2 Payload Protection . . . . . . . . . . . . . . . . . . . . . 39 121 F.2.1 Proxy Caching . . . . . . . . . . . . . . . . . . . . . 39 122 F.2.2 Publish-Subscribe . . . . . . . . . . . . . . . . . . . 40 123 F.2.3 Transporting Authorization Information . . . . . . . . . 41 124 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 42 126 1. Introduction 128 The Constrained Application Protocol CoAP [RFC7252] was designed with 129 a constrained RESTful environment in mind. CoAP references DTLS 130 [RFC6347] for securing the message exchanges. Two commonly used 131 features of CoAP are store-and-forward and publish-subscribe 132 exchanges, which are problematic to secure with DTLS and transport 133 layer security. As DTLS offers hop-by-hop security, in case of 134 store-and-forward exchanges it necessitates a trusted intermediary. 135 On the other hand, securing publish-subscribe CoAP exchanges with 136 DTLS requires the use of the keep-alive mechanism which incurs 137 additional overhead and actually takes away most of the benefits of 138 asynchronous communication. 140 The pervasive monitoring debate has illustrated the need to protect 141 data also from trustworthy intermediary nodes as they can be 142 compromised. The community has reacted strongly to the revelations, 143 and new solutions must consider this attack [RFC7258] and include 144 encryption by default. 146 This memo presents OSCOAP, a data object based communication security 147 solution complementing DTLS and supporting secure messaging end-to- 148 end across intermediary nodes. OSCOAP may be used in very 149 constrained settings where DTLS cannot be supported. OSCOAP can also 150 be combined with DTLS thus enabling, for example, end-to-end security 151 of CoAP payload in combination with hop-by-hop protection of the 152 entire CoAP message during transport between end-point and 153 intermediary node. 155 1.1 Terminology 157 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 158 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 159 document are to be interpreted as described in [RFC2119]. These 160 words may also appear in this document in lowercase, absent their 161 normative meanings. 163 Certain security-related terms are to be understood in the sense 164 defined in RFC 4949 [RFC4949]. These terms include, but are not 165 limited to, "authentication", "authorization", "confidentiality", 166 "(data) integrity", "message authentication code", and "verify". For 167 "signature", see below. 169 RESTful terms, such as "resource" or "representation", are to be 170 understood as used in HTTP [RFC7231] and CoAP. 172 Terminology for constrained environments, such as "constrained 173 device", "constrained-node network", is defined in [RFC7228]. 175 JSON Web Signature (JWS), JOSE Header, JWS Payload, and JWS Signature 176 are defined in [RFC7515]. JSON Web Encryption (JWE), JWE AAD, JWE 177 Ciphertext, and JWE Authentication Tag are defined in [RFC7516]. 179 Secure Message (SM), Secure Signed Message (SSM), and Secure 180 Encrypted Message (SEM) are message formats defined in this memo. 181 The Compact Secure Message (CSM) format is defined in Appendix C. 182 The Sig and Enc options are CoAP options defined in this memo. 184 Note that "signature" as in "JSON Web Signature" and the derived 185 terms "Secure Signed Message" and "Sig" option may refer either to 186 digital signature using private key of an asymmetric key pair, or 187 Message Authentication Code using a shared key. In other occurrences 188 we use the term as defined in [RFC4949], meaning digital signature. 190 Excluded Authenticated Data (EAD) is defined in this memo (see 191 Sections 4.1.2). Transaction Identifier (TID) is defined in this 192 memo (see Section 4.1.1). 194 COSE is defined in [I-D.schaad-cose-msg]. 196 2. Background 198 The background for this work is provided by the use cases and problem 199 description in [I-D.ietf-ace-usecases] and [I-D.gerdes-ace-actors]. 200 The focus of this memo is on end-to-end security in constrained 201 environments in the presence of intermediary nodes. 203 For constrained-node networks there may be several reasons for 204 messages to be cached or stored in one node and later forwarded. For 205 example, connectivity between the nodes may be intermittent, or some 206 node may be sleeping at the time when the message should have been 207 forwarded (see e.g. [I-D.ietf-ace-usecases] sections 2.1.1, and 208 2.5.1). Also, the architectural model or protocol applied may 209 require an intermediary node which breaks security on transport layer 210 (see e.g. [I-D.ietf-ace-usecases] sections 2.1.1, and 2.5.2). 211 Examples of intermediary nodes include forward proxies, reverse 212 proxies, pub-sub brokers, HTTP-CoAP cross-proxies, and SMS servers. 214 On a high level, end-to-end security in this setting encompasses: 216 1. Protection against eavesdropping and manipulation of resource 217 representations in intermediary nodes; 219 2. Protection against message replay; 221 3. Protection of authorization information ("access tokens") in 222 transport from an Authorization Server to a Resource Server via 223 a Client, or other intermediary nodes which could gain from 224 changing the information; 226 4. Allowing a client to verify that a response comes from a 227 certain server and is the response to a particular request; 229 5. Protection of the RESTful method used by the client, or the 230 response code used by the server. For example if a malicious 231 proxy replaces the client requested GET with a DELETE this must 232 be detected by the server; 234 6. Protection against eavesdropping of meta-data of the request or 235 response, including CoAP options such as for example Uri-Path 236 and Uri-Query, which may reveal some information on what is 237 requested. 239 From the listed examples, there are two main categories of security 240 requirements and corresponding solutions. The first category deals 241 essentially with protecting the CoAP payload (1-3). 243 The second category deals with protecting an entire CoAP message, 244 targeting also CoAP options and header fields (4-6). The next 245 section formulates security requirements for the two categories, 246 which correspond to two modes of OSCOAP denoted Mode:PAYL and 247 Mode:COAP, respectively. 249 3. End-to-end Security in Presence of Intermediary Nodes 251 For high-level security requirements related to resource access, see 252 section 8.7 of [I-D.gerdes-ace-actors]. This section defines the 253 specific requirements that address the two categories of examples 254 identified in the previous section, taking into account potential 255 intermediary nodes. 257 In the case of CoAP payload only protection (Mode:PAYL), the end-to- 258 end security requirements apply to payload data, such as Resource 259 Representations: 261 a. The payload shall be integrity protected and should be 262 encrypted end-to-end from sender to receiver. 264 b. It shall be possible for an intended receiver to detect if it 265 has received this message previously, i.e. replay protection. 267 Note that a Mode:PAYL message may have multiple recipients. For 268 example, in the case of a proxy that is caching responses used to 269 serve multiple clients, or in a publish-subscribe setting with 270 multiple subscribers to a given publication. 272 In the case of protecting specific Client-Server CoAP message 273 exchanges (Mode:COAP), potentially passing via intermediary nodes, 274 there are additional end-to-end security requirements: 276 c. The CoAP options which are not intended to be changed by an 277 intermediary node shall be integrity protected between Client 278 and Server. 280 d. The CoAP options which are not intended to be read by an 281 intermediary node shall be encrypted between Client and Server. 283 e. The CoAP header field "Code" shall be integrity protected 284 between Client and Server. 286 f. A Client shall be able to verify that a message is the response 287 to a particular request the Client made. 289 The requirements listed above can be met by encryption, integrity 290 protection and replay protection. What differs between the modes is 291 the actual data that is protected, i.e. CoAP payload data only or 292 also other CoAP message data. This memo specifies a common "Secure 293 Message" format that can be used to wrap either payload only 294 (Mode:PAYL) or also additional selected CoAP message fields 295 (Mode:COAP), and be sent as part of the message. 297 4. Secure Message 299 There exist already standardized and draft content formats for 300 cryptographically protected data such as CMS [RFC5652], JWS 301 [RFC7515], JWE [RFC7516], and COSE [I-D.schaad-cose-msg]. 303 Current CMS and JWx objects are undesirably large for very 304 constrained devices, and can lead to packet fragmentation in 305 constrained-node networks due to limited frame sizes, and to problems 306 with limited storage capacity on constrained devices due to limited 307 RAM. First estimates with COSE render more compact objects, see 308 Appendix E for a discussion of message format overhead and minimum 309 message expansion. For example, COSE header for a Message 310 Authentication Code object encodes to 37 bytes, while the same header 311 with JWS results in 74 bytes. 313 Thus, the candidate message format for use in OSCOAP is COSE [I- 314 D.schaad-cose-msg]. Pending a stable version of COSE this draft uses 315 multiple formats and their terminology to illustrate how the message 316 format is applied and processed. It is the intention to replace 317 these with a profile of one single compact secure message format in a 318 future version of this draft. 320 None of the message formats listed about provide support for replay 321 protection, but it is noted section 10.10 of [RFC7515] that one way 322 to thwart replay attacks is to include a unique transaction 323 identifier and have the recipient verify that the message has not 324 been previously received or acted upon. 326 We use the term Secure Message (SM) format to refer to a content 327 format for cryptographically protected data which includes a unique 328 transaction identifier, and some other common data as specified in 329 Section 4.1.1. 331 This memo uses JOSE content formats as a model to specify format and 332 processing of messages. The terms Secure Signed Message (SSM) format 333 and Secure Encrypted Message (SEM) format to refer to Secure Message 334 formats supporting integrity protection only and additional 335 encryption, analogous to JWS and JWE, respectively. Appendix B shows 336 how to profile JOSE objects to become Secure Message formats. 337 Appendix C shows how to profile COSE objects to become Secure Message 338 formats. 340 4.1 Secure Message format 342 A Secure Message (SM) SHALL consist of Header, Body and Tag. 344 4.1.1 Secure Message Header 346 The following parameters SHALL be included in the SM Header: 348 o Algorithm. This parameter identifies the cryptographic 349 algorithm(s) used to protect the Secure Message. In case of SSM 350 it has the same semantics as the JOSE Header Parameter "alg" 351 defined in Section 4.1.1 of [RFC7515]. In case of SEM, "direct 352 key agreement" (corresponding to the JWE "alg" = "dir") is 353 assumed, and the encryption algorithm corresponds to the JOSE 354 Header Parameter "enc" (Section 4.1.2 of [RFC7516]). However, 355 the cipher suites are not limited to AEAD algorithms but also 356 include symmetric key encryption combined with private key 357 signature. 359 o Context Identifier. This parameter identifies the sender and 360 the security context/key(s) used together with the Algorithm to 361 protect the message. For Mode:COAP, the Context Identifier 362 typically identifies the sending party and different resources 363 are identified by their Uri-Path. For Mode:PAYL, the Context 364 Identifier may identify the resource itself. The structure of 365 this identifier is unspecified. 367 o Sequence Number. The Sequence Number parameter enumerates the 368 Secure Messages protected using the security context identified 369 by the Context Identifier, and is used for replay protection and 370 uniqueness of nonce. The start sequence number SHALL be 0. For 371 a given key, any Sequence Number MUST NOT be used more than 372 once. 374 The ordered sequence (Sequence Number, Context Identifier) is called 375 Transaction Identifier (TID), and SHALL be unique for each SM. 377 4.1.2 Secure Message Body 379 Analogously to JWS and JWE, the SM Body contains what is being 380 protected. The SM Body is different for SSM and SEM. 382 In order to obtain a compact representation, certain data is 383 integrity protected but excluded from the Secure Message. Such data 384 is referred to as Excluded Authenticated Data (EAD). To further 385 reduce message size, the unencrypted part of the SM Body may be 386 "detached" from the Secure Message, see sections 4.1.2.1 and 4.1.2.2. 388 The assumption behind excluding integrity protected data from the SM, 389 or detaching integrity protected but not encrypted parts of the SM 390 during transport, is that the data in question is known to the 391 receiver, e.g. because it is established beforehand or because it is 392 transported as part of the CoAP message carrying the Secure Message. 394 4.1.2.1 Secure Signed Message Body 396 For SSM, the Body consists of the payload data which is integrity 397 protected, analogously to the JWS Payload. Detached Content is 398 defined to mean that the Body is removed from the Secure Message, 399 analogously to Appendix F of [RFC7515]. Hence a SSM with Detached 400 Content consists of Header and Tag. 402 4.1.2.2 Secure Encrypted Message Body 404 Analogously to JWE, the terms Plaintext, Ciphertext and Additional 405 Authenticated Data (AAD) are used for the SEM. The Body of a SEM 406 consists of Ciphertext, the encrypted Plaintext as defined by the 407 Algorithm, and Additional Authenticated Data (AAD) which is integrity 408 protected by the Algorithm as defined by the Cipher Suite. For SEM 409 Detached Content is defined to mean that the AAD is removed from the 410 Secure Message. Hence a SEM with Detached Content consists of the 411 Header, Ciphertext and Tag. 413 4.1.3 Secure Message Tag 414 The SM Tag consists of the Signature / Message Authentication Code 415 value as defined by the Algorithm, calculated over the SM Header, SM 416 Body and EAD (if present). The content of EAD depends on the Mode, 417 see 5.1.3 and 5.2 419 5. Message Protection 421 This section describes what is protected in a Secure Message and how 422 it depends on the defined Modes "COAP" and "PAYL". The use of 423 Mode:COAP is signaled with the presence of the options Sig or Enc 424 defined in this section. The differences in SM Body and SM Tag as a 425 function of Mode are described below. 427 Both formats SSM and SEM defined in the previous section are 428 applicable to both Modes. For any Secure Message Mode, the SEM 429 format SHALL be used by default. Examples of SSM and SEM are given 430 in Appendix F. 432 5.1 CoAP Message Protection (Mode:COAP) 434 Referring to examples 4-6 in Section 2 and requirements a-f in 435 Section 3, this section presents how to protect individual CoAP 436 messages including options and header fields, as well as request- 437 response message exchanges, using the Secure Message format. This is 438 called Mode:COAP. An endpoint receiving a CoAP request containing a 439 Secure Message with Mode:COAP MUST respond with a CoAP message 440 containing a Secure Message with Mode:COAP. 442 Since slightly different message formats are used for integrity 443 protection only (SSM), and additional encryption (SEM), these cases 444 are treated separately. 446 5.1.1 The Sig Option 448 In order to integrity protect CoAP message exchanges including 449 options and headers, a new CoAP option is introduced: the Sig option, 450 containing a SSM Mode:COAP object. Endpoints supporting this scheme 451 MUST check for the presence of a Sig option, and verify the SSM as 452 described in Section 5.1.1.2 before accepting a message as valid. 454 5.1.1.1 Option Structure 456 The Sig option indicates that certain CoAP Header Fields, Options, 457 and Payload (if present) are integrity and replay protected using a 458 Secure Signed Message (SSM). The Sig option SHALL contain a SSM with 459 Detached Content (see Section 4.1.2.1). 461 This option is critical, safe to forward, it is not part of a cache 462 key, and it is not repeatable. Table 1 illustrates the structure of 463 this option. 465 +-----+---+---+---+---+---------+--------+-----------+ 466 | No. | C | U | N | R | Name | Format | Length *) | 467 +-----+---+---+---+---+---------+--------+-----------+ 468 | TBD | x | | x | | Sig | opaque | 12-TBD | 469 +-----+---+---+---+---+---------+--------+-----------+ 471 C=Critical, U=Unsafe, N=NoCacheKey, R=Repeatable 473 Table 1: The Sig Option 475 *) Length is essentially Length(SSM Header) + Length(SSM Tag). The 476 minimum length is estimated in Appendix E. The maximum length 477 depends on actual message format selected and is TBD. 479 5.1.1.2 Integrity Protection and Verification 481 A CoAP endpoint composing a message with the Sig option SHALL process 482 the SSM and produce the SSM Tag, as defined in 5.1.1.3 and 5.1.3, 483 analogously to the specification for producing a JWS object as 484 described in Section 5.1 of [RFC7515] (cf. Appendix B). In addition, 485 the sending endpoint SHALL process the Sequence Number as described 486 in Section 5.3. 488 A CoAP endpoint receiving a message containing the Sig option SHALL 489 first recreate the SSM Body as described in Section 5.1.1.3, and then 490 verify the SSM Tag as described in Section 5.1.3, analogously to the 491 specification for verifying a JWS object as described in Section 5.2 492 of [RFC7515] (cf. Appendix B). In addition, the receiving endpoint 493 SHALL process the Sequence Number as described in Section 5.3. 495 NOTE: The explicit steps of the protection and verification procedure 496 will be included in a future version of this draft. 498 5.1.1.3 SSM Body 500 The SSM Body of SHALL consist of the following data, in this order: 502 o the 8-bit CoAP header field Code; 504 o all CoAP options present which are marked as IP in Table 3 505 (Appendix A), in the order as given by the option number (each 506 Option with Option Header including delta to previous IP-marked 507 Option which is present); and 509 o the CoAP Payload (if any). 511 5.1.2 The Enc Option 513 In order to encrypt and integrity protect CoAP messages, a new CoAP 514 option is introduced: the Enc option, indicating the presence of a 515 SEM Mode:COAP object in the CoAP message, containing the encrypted 516 part of the CoAP message. Endpoints supporting this scheme MUST 517 check for the presence of an Enc option, and verify the SEM as 518 described in 5.1.2.2 before accepting a message as valid. 520 5.1.2.1 Option Structure 522 The Enc option indicates that certain CoAP Options and Payload (if 523 present) are encrypted, integrity and replay protected using a Secure 524 Encrypted Message (SEM) with Detached Content (see Section 4.1.2.2). 525 The structure of a CoAP message with an Enc option is described in 526 Section 5.1.2.4. 528 This option is critical, safe to forward, it is not part of a cache 529 key, and it is not repeatable. Table 2 illustrates the structure of 530 this option. 532 +-----+---+---+---+---+---------+--------+-------------+ 533 | No. | C | U | N | R | Name | Format | Length *) | 534 +-----+---+---+---+---+---------+--------+-------------+ 535 | TBD | x | | x | | Enc | opaque | 0 or 12-TBD | 536 +-----+---+---+---+---+---------+--------+-------------+ 538 C=Critical, U=Unsafe, N=NoCacheKey, R=Repeatable 540 Table 2: The Enc Option 542 *) Length indicates in this case the additional length added to the 543 total length of all CoAP options. If the CoAP message has Payload, 544 then the Enc option is empty, otherwise it contains the SEM (see 545 Section 5.1.2.4). In the latter case, the SEM Ciphertext contains 546 the encrypted CoAP Options (see Section 5.1.2.3), which are thus 547 excluded from plaintext part of the message. Hence the additional 548 length is essentially Length(SEM Header) + Length(SEM Tag). The 549 minimum length is estimated in Appendix E. The maximum length 550 depends on actual message format selected and is TBD. 552 5.1.2.2 Encryption and Decryption 554 A CoAP endpoint composing a message with the Enc option SHALL process 555 the SEM and produce the SEM Ciphertext and SEM Tag, as defined in 556 5.1.2.3 and 5.1.3, analogously to the specification for producing a 557 JWE object as described in Section 5.1 of [RFC7516] (cf. Appendix B). 558 In addition, the sending endpoint SHALL process the Sequence Number 559 as described in Section 5.3. 561 A CoAP endpoint receiving a message containing the Enc option SHALL 562 first recreate the SEM Body as described in Section 5.1.2.3, and then 563 decrypt and verify the SEM analogously to the specification for 564 verifying a JWE object as describe in Section 5.2 of [RFC7516] (cf. 565 Appendix B). In addition, the receiving endpoint SHALL process the 566 Sequence Number as described in Section 5.3. 568 NOTE: The explicit steps of the protection and verification procedure 569 will be included in a future version of this draft. 571 5.1.2.3 SEM Body 573 The SEM Plaintext SHALL consist of the following data, formatted as a 574 CoAP message without Header consisting of: 576 o all CoAP Options present which are marked as E in Table 3 (see 577 Appendix A), in the order as given by the Option number (each 578 Option with Option Header including delta to previous E-marked 579 Option); and 581 o the CoAP Payload, if present, and in that case prefixed by the 582 one-byte Payload Marker (0xFF). 584 The SEM Additional Authenticated Data SHALL consist of the following 585 data, in this order: 587 o the 8-bit CoAP header field Code; 589 o all CoAP options present which are marked as IP and not marked 590 as E in Table 2 (see Appendix A), in the order as given by the 591 Option number (each Option with Option Header including delta to 592 previous such Option). 594 5.1.2.4 CoAP Message with Enc Option 596 An unprotected CoAP message is encrypted and integrity protected by 597 means of an Enc option and a SEM. The structure and format of the 598 protected CoAP message being sent instead of the unprotected CoAP 599 message is now described. 601 The protected CoAP message is formatted as an ordinary CoAP message, 602 with the following Header, Options and Payload: 604 o The CoAP header SHALL be the same as the unprotected CoAP 605 message. 607 o The CoAP options SHALL consist of the unencrypted options of the 608 unprotected CoAP message, and the Enc option. The options shall 609 be formatted as in a CoAP message (each Option with Options 610 Header including delta to previous unencrypted Option). 612 o If the unprotected CoAP message has no Payload then the Enc 613 option SHALL contain the SEM with Detached Content. If the 614 unprotected CoAP message has Payload, then the SEM option SHALL 615 be empty and the Payload of the CoAP message SHALL be the SEM 616 with Detached Content. The Payload is prefixed by the one-byte 617 Payload Marker (0xFF). 619 5.1.3 SM Tag 621 This section describes the SM Tag for Mode:COAP, which applies both 622 to SEM and SSM. The SM Tag is defined in 4.1.3. If the message is a 623 CoAP Request, then EAD SHALL be empty. If the message is a CoAP 624 Response, then EAD SHALL consist of the TID of the associated CoAP 625 Request. 627 5.2 Payload Only Protection (Mode:PAYL) 629 Referring to examples 1-3 in Section 2 and requirements a and b in 630 Section 3, the case of only protecting CoAP payload using the Secure 631 Message format is now discussed. This is called Mode:PAYL. 633 The sending endpoint SHALL wrap the Payload, and the receiving 634 endpoint unwrap the Payload in the relevant SM format (SSM or SEM) 635 Mode:PAYL. The SSM (SEM) SHALL be protected (encrypted) and verified 636 (decrypted) as described in 5.1.1.2 (5.1.2.2), including replay 637 protection as described in section 5.3. 639 NOTE: The explicit steps of the protection and verification procedure 640 will be included in a future version of this draft. 642 For Mode:PAYL, the EAD SHALL be empty. Hence, the SM Tag is 643 calculated over the SM Header and SM Body. 645 A CoAP message where the Payload is wrapped as a Mode:PAYL object is 646 indicated by setting the option Content-Format to application/smpayl. 647 A CoAP client may request a response containing such a payload 648 wrapping by setting the option Accept to application/smpayl. (See 649 Section 8.) 651 5.3 Replay Protection and Freshness 653 In order to protect from replay of messages and verify freshness of 654 responses, a CoAP endpoint supporting OSCOAP SHALL maintain 655 Transaction Identifiers (TIDs) of sent and received Secure Messages 656 (see section 4.1.1). 658 5.3.1 Replay Protection 660 An endpoint SHALL maintain a TID and associated security 661 context/key(s) for each other endpoint it receives messages from, and 662 one TID and associated security context/key(s) for protecting sent 663 messages. Depending on use case, an endpoint MAY maintain a sliding 664 receive window for Sequence Numbers associated to TIDs in received 665 messages, equivalent to the functionality described in section 666 4.1.2.6 of [RFC6347]. 668 Before composing a new message a sending endpoint SHALL step the 669 Sequence Number of the associated send TID and SHALL include it in 670 the SM Header parameter Sequence Number as defined in section 4.1.1. 671 However, if the Sequence Number counter wraps, the client must first 672 acquire a new TID and associated security context/key(s). The latter 673 is out of scope of this memo. 675 A receiving endpoint SHALL verify that the Sequence Number received 676 in the SM Header is greater than the Sequence Number in the TID for 677 received messages (or within the sliding window and not previously 678 received) and update the TID (window) accordingly. 680 5.3.2 Freshness 682 If a CoAP server receives a valid Secure Message request in 683 Mode:COAP, then the response SHALL include the TID of the request as 684 EAD, as defined in section 5.1.3. If the CoAP client receives a 685 Secure Message response in Mode:COAP, then the client SHALL verify 686 the signature by reconstructing SM Body and using the TID of its own 687 associated request as EAD, as defined in section 5.1.3. 689 6. Security Considerations 690 In scenarios with proxies, gateways, or caching, DTLS only protects 691 data hop-by-hop meaning that these intermediary nodes can read and 692 modify information. The trust model where all participating nodes 693 are considered trustworthy is problematic not only from a privacy 694 perspective but also from a security perspective as the 695 intermediaries are free to delete resources on sensors and falsify 696 commands to actuators (such as "unlock door", "start fire alarm", 697 "raise bridge"). Even in the rare cases where all the owners of the 698 intermediary nodes are fully trusted, attacks and data breaches make 699 such an architecture weak. 701 DTLS protects the entire CoAP message including Header, Options and 702 Payload, whereas Mode:COAP protects the message fields described in 703 Appendix A. The cost for DTLS providing this protection is the 704 overhead in e.g. additional messages, processing, memory incurred by 705 the DTLS Handshake protocol, which can be omitted in use cases where 706 key establishment can be provided by other means. 708 Mode:COAP provides point to point encryption, integrity and replay 709 protection, and freshness of response. Payload as well as relevant 710 options and header field Code are protected. 712 Mode:PAYL only protects payload and only gives replay protection (not 713 freshness), but allows additional use cases such as point to multi- 714 point interactions including publish-subscribe, reverse proxies and 715 proxy caching of responses. In case of symmetric keys the receiver 716 does not get data origin authentication, which requires a digital 717 signature using a private asymmetric key. Mode:PAYL SHALL NOT be 718 used in cases where the CoAP header field Code needs to be integrity 719 protected. 721 Blockwise transfers in CoAP [I-D.ietf-core-coap-block] can be applied 722 both to Mode:COAP and Mode:PAYL. With Mode:COAP each block and the 723 Block options are integrity protected. Hence each individual block 724 can be securely verified by the receiver, retransmission securely 725 requested etc. With Mode:PAYL the entire payload is encapsulated in 726 a Secure Message which is partitioned into blocks which are sent with 727 unprotected CoAP. The receiver is able to verify the integrity of 728 the payload but only after the last block containing the 729 signature/MAC is received, and if the verification fails the entire 730 message needs to be resent. However, if the verification succeeds, 731 then the transmission in Mode:PAYL has less computational and packet 732 overhead since only one signature/MAC was generated and sent. As 733 CoAP blockwise transfer with Mode:PAYL is prone to Denial of Service 734 attacks, it should only be used for exchanges where this threat can 735 be mitigated, for example within a local area network where link- 736 layer security is activated. 738 The Version header field is not integrity protected to allow 739 backwards compatibility with future versions of CoAP. Considering 740 this, it may in theory be possible to launch a cross-version attack, 741 e.g. something analogous to a bidding down attack. Future updates of 742 CoAP would need to take this into account. 744 The use of sequence numbers for replay protection introduces the 745 problem related to wrapping of the counter. The alternatives also 746 have issues: very constrained devices may not be able to support 747 accurate time or generate and store large numbers of random nonces. 748 The requirement to change key at counter wrap is a complication, but 749 it also forces the user of this specification to think about 750 implementing key renewal. 752 Independently of message format, and whether the target is CoAP 753 message protection or payload only protection, this specification 754 needs to be complemented with a procedure whereby the client and the 755 server establish the keys used for wrapping and unwrapping the Secure 756 Message. One way to address key establishment is to assume that 757 there is a trusted third party which can support client and server, 758 such as the Authorization Server in [I-D.gerdes-ace-actors]. The 759 Authorization Server may, for example, authenticate the client on 760 behalf of the server, or provide cryptographic keys or credentials to 761 the client and/or server which can be used in the Secure Message 762 exchange. Similarly, the Authorization Server may, on behalf of the 763 server, notify the client of server supported ciphers, in order to 764 facilitate the usage of OSCOAP in deployments with multiple supported 765 cryptographic algorithms. 767 The security contexts required for SSM and SEM are different. For a 768 SSM, the security context is essentially Algorithm, Context 769 Identifier, Sequence Number and Key. For a SEM it is also required 770 to have a unique Initialization Vector for each message. The 771 Initialization Vector SHALL be the concatenation of a Salt (4 bytes 772 unsigned integer) and the Sequence Number. The Salt SHOULD be 773 established between sender and receiver before the message is sent, 774 to avoid the overhead of sending it in each message. For example, 775 the Salt may be established by the same means as keys are 776 established. For a SEM, the security context is essentially 777 Algorithm, Context Identifier, Salt, Sequence Number and Key. 779 7. Privacy Considerations 781 End-to-end integrity protection provides certain privacy properties, 782 e.g. protection of communication with sensor and actuator from 783 manipulation which may affect the personal sphere. End-to-end 784 encryption of payload and certain CoAP options provides additional 785 protection as to the content and nature of the message exchange. 787 The headers sent in plaintext allow for example matching of CON and 788 ACK (CoAP Message Identifier), matching of request and response 789 (Token). Plaintext options could also reveal information, e.g. 790 lifetime of measurement (Max-age), or that this message contains one 791 data point in a sequence (Observe). 793 8. IANA Considerations 795 Note to RFC Editor: Please replace all occurrences of "[this 796 document]" with the RFC number of this specification. 798 The following entry is added to the CoAP Option Numbers registry: 800 +--------+---------+-------------------+ 801 | Number | Name | Reference | 802 +--------+---------+-------------------+ 803 | TBD | Sig | [[this document]] | 804 +--------+---------+-------------------+ 805 | TBD | Enc | [[this document]] | 806 +--------+---------+-------------------+ 808 This document registers the following value in the CoAP Content 809 Format registry established by [RFC7252]. 811 Media Type: application/smpayl 813 Encoding: - 815 Id: 70 817 Reference: [this document] 819 9. Acknowledgements 821 Klaus Hartke has independently been working on the same problem and a 822 similar solution: establishing end-to-end security across proxies by 823 adding a CoAP option. We are grateful to Malisa Vucinic for 824 providing helpful and timely comments. 826 10. References 828 10.1 Normative References 830 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 831 Requirement Levels", BCP 14, RFC 2119, March 1997. 833 [RFC6347] Rescorla, E., and N. Modadugu, "Datagram Transport Layer 834 Security Version 1.2", RFC 6347, January 2012. 836 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 837 Application Protocol (CoAP)", RFC 7252, June 2014. 839 [RFC7258] Farrell, S., and H. Tschofenig, "Pervasive Monitoring Is 840 an Attack", RFC 7258, May 2014. 842 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 843 Signature (JWS)", RFC 7515, May 2015. 845 [RFC7516] Jones, M., and J. Hildebrand, "JSON Web Encryption (JWE)", 846 RFC 7516, May 2015. 848 10.2 Informative References 850 [I-D.gerdes-ace-actors] 851 Gerdes, S., Seitz, L., G. Selander, Bormann, C. "An 852 Arhitecture for Authorization in Constrained 853 Environments", draft-gerdes-ace-actors-05 (work in 854 progress), April 2015. 856 [I-D.ietf-ace-usecases] 857 Seitz, L., Gerdes, S., Selander, G., Mani, M., and S. 858 Kumar, "ACE use cases", draft-ietf-ace-usecases-04 (work 859 in progress), March 2015. 861 [I-D.schaad-cose-msg] 862 Schaad, J., "CBOR Encoded Message Syntax", draft-schaad- 863 cose-msg-00 (work in progress), June 2015. 865 [I-D.ietf-core-coap-block] 866 Bormann, C., and Z. Shelby, "Blockwise transfers in CoAP", 867 draft-ietf-core-block-17 (work in progress), July 2014. 869 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", FYI 870 36, RFC 4949, August 2007. 872 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 873 RFC 5652, September 2009. 875 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 876 Constrained-Node Networks", RFC 7228, May 2014. 878 [RFC7231] Fielding, R., and J. Reschke, "Hypertext Transfer Protocol 879 (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. 881 Appendix A. Which CoAP Header Fields and Options to Protect 883 In the case of CoAP Message Protection (Mode:COAP) as much as 884 possible of the CoAP message is protected. However, not all CoAP 885 header fields or options can be encrypted and integrity protected, 886 because some are intended to be read or changed by an intermediary 887 node. 889 A.1 CoAP Header Fields 891 The CoAP Message Layer parameters, Type and Message ID, as well as 892 Token and Token Length may be changed by a proxy and thus SHALL 893 neither be integrity protected nor encrypted. Example 5 in Section 2 894 shows that the Code SHALL be integrity protected. The Version 895 parameter SHALL neither be integrity protected nor encrypted (see 896 Section 6). 898 A.2 CoAP Options 900 This section describes what options need to be integrity protected 901 and encrypted. On a high level, all CoAP options must be encrypted 902 by default, unless intended to be read by an intermediate node; and 903 integrity protected, unless intended to be changed by an intermediate 904 node. 906 However, some special considerations are necessary because CoAP 907 defines certain legitimate proxy operations, because the security 908 information itself may be transported as an option, and because 909 different processing is performed for SSM and SEM. 911 A.2.1 Integrity Protection 913 CoAP options which are not intended to be changed by an intermediate 914 node MUST be integrity protected: 916 o CoAP options which are Safe-to-Forward SHALL be integrity 917 protected, the only exception being the security options Enc and 918 Sig. See Table 3. 920 o Block1, Block2 are Unsafe but not intended to be modified by 921 intermediaries and hence SHALL be integrity protected. 923 CoAP options which are intended to be modified by a proxy can be 924 divided into two categories, those that are intended to change in a 925 predictable way, and those which are not. The following options are 926 of the latter kind and SHALL NOT be integrity protected: 928 o Max-Age, Observe: These options may be modified by a proxy in a 929 way that is not predictable for client and server. 931 The remaining options may be modified by a proxy, but when they are, 932 the change is predictable. Therefore it is possible to define 933 "invariants" which can be integrity protected. 935 A.2.1.1 Proxy-Scheme 937 A Forward Proxy is intended to replace the URI scheme with the 938 content of the Proxy-Scheme option. The Proxy-Scheme option is 939 defined to be an invariant with respect to the following processing: 941 o If there is a Proxy-Scheme present, then the client MUST 942 integrity protect the Proxy-Scheme option. 944 o If there is no Proxy-Scheme option present the client SHALL 945 integrity protect the Proxy-Scheme option set to the URI scheme 946 used in the message sent. 948 o The server SHALL insert the Proxy-Scheme option with the name of 949 the URI scheme the message was received with before verifying 950 the integrity. 952 A.2.1.2 Uri-* 954 For options related to URI of resource (Uri-Host, Uri-Port, Uri-Path, 955 Uri-Query, Proxy-Uri) a Forward Proxy is intended to replace the Uri- 956 * options with the content of the Proxy-Uri option. 958 The Proxy-Uri option is defined to be an invariant with respect to 959 the following processing (applying to a SSM, for SEM see next 960 section): 962 o If there is a Proxy-Uri present, then the client MUST integrity 963 protect the Proxy-Uri option and the Uri-* options MUST NOT be 964 integrity protected. 966 o If there is no Proxy-Uri option present, then the client SHALL 967 compose the full URI from Uri-* options according to the method 968 described in section 6.5 of [RFC7252]. The SM Tag is calculated 969 on the following message, modified compared to what is sent: 971 o All Uri-* options removed 973 o A Proxy-Uri option with the full URI included 975 o The server SHALL compose the URI from the Uri-* options 976 according to the method described in section 6.5 of [RFC7252]. 977 The so obtained URI is placed into a Proxy-Uri option, which is 978 included in the integrity verification. 980 A.2.2 Encryption 982 All CoAP options MUST be encrypted, except the options below which 983 MUST NOT be encrypted: 985 o Max-Age, Observe: This information is intended to be read by a 986 proxy. 988 o Enc, Sig: These are the security-providing options. 990 o Uri-Host, Uri-Port: This information can be inferred from 991 destination IP address and port. 993 o Proxy-Uri, Proxy-Scheme: This information is intended to be 994 read by a proxy. 996 In the case of a SEM, the Proxy-Uri MUST only contain Uri-Host and 997 Uri-Port and MUST NOT contain Uri-Path and Uri-Query because the 998 latter options are not intended to be revealed to a Forward Proxy. 1000 A.2.3 Summary 1002 Table 3 summarizes which options are encrypted and integrity 1003 protected, if present. 1005 In a SSM, options marked with "a" and "b" are composed into a URI as 1006 described above and included as the Proxy-Uri option which is part of 1007 the SSM Body. In a SEM, options marked "a" are composed into a URI 1008 as described above and included as the Proxy-Uri option in the SEM 1009 Additional Authenticated Data. 1011 +-----+---+---+---+---+----------------+--------+--------+--------+ 1012 | No. | C | U | N | R | Name | Format | Length | E | IP | 1013 +-----+---+---+---+---+----------------+--------+--------+--------+ 1014 | 1 | x | | | x | If-Match | opaque | 0-8 | x | x | 1015 | 3 | x | x | - | | Uri-Host | string | 1-255 | | a | 1016 | 4 | | | | x | ETag | opaque | 1-8 | x | x | 1017 | 5 | x | | | | If-None-Match | empty | 0 | x | x | 1018 | 6 | | x | - | | Observe | uint | 0-3 | | | 1019 | 7 | x | x | - | | Uri-Port | uint | 0-2 | | a | 1020 | 8 | | | | x | Location-Path | string | 0-255 | x | x | 1021 | 11 | x | x | - | x | Uri-Path | string | 0-255 | x | b | 1022 | 12 | | | | | Content-Format | uint | 0-2 | x | x | 1023 | 14 | | x | - | | Max-Age | uint | 0-4 | | | 1024 | 15 | x | x | - | x | Uri-Query | string | 0-255 | x | b | 1025 | 17 | x | | | | Accept | uint | 0-2 | x | x | 1026 | 20 | | | | x | Location-Query | string | 0-255 | x | x | 1027 | 23 | x | x | - | | Block2 | uint | 0-3 | x | x | 1028 | 27 | x | x | - | | Block1 | uint | 0-3 | x | x | 1029 | 28 | | | x | | Size2 | uint | 0-4 | x | x | 1030 | 35 | x | x | - | | Proxy-Uri | string | 1-1034 | | x | 1031 | 39 | x | x | - | | Proxy-Scheme | string | 1-255 | | x | 1032 | 60 | | | x | | Size1 | uint | 0-4 | x | x | 1033 +-----+---+---+---+---+----------------+--------+--------+--------+ 1035 C=Critical, U=Unsafe, N=NoCacheKey, R=Repeatable, 1036 E=Encrypt, IP=Integrity Protect. 1038 Table 3: Protected CoAP options in Mode=COAP. 1040 Appendix B. JOSE Profile of SM 1042 This section defines profiles of JWS and JWE complying with the 1043 Secure Message format (see Section 4.1). The use of compact 1044 serialization is assumed. 1046 B.1 JWS as Secure Signed Message 1048 The JOSE Header of JWS contains the mandatory parameter "alg", 1049 defined in Section 4.1.1 of [RFC7515], which corresponds to the 1050 parameter Algorithm of the Secure Message. 1052 A JWS is a Secure Message if the JOSE Header includes 1054 o the new parameter "cid" defined in B.4, and 1056 o the new parameter "seq" defined in B.3. 1058 An SSM with Detached Content corresponds to a JWS with JOSE Header 1059 and JWS Signature; i.e. no JWS Payload. 1061 B.2 JWE as Secure Encrypted Message 1063 In case of JWE, the SM Header parameters of a JWE consists of the 1064 JOSE Header Parameters and JWE Initialization Vector (IV). 1066 The JOSE Header of JWE contains the mandatory parameter "enc", 1067 defined in Section 4.1.2 of [RFC7516], which corresponds to the 1068 parameter Algorithm of the Secure Message. The JOSE Header also 1069 contains the mandatory parameter "alg", the key encryption algorithm, 1070 which in the current version of the draft is assumed to be equal to 1071 "dir" (constant). It is also assumed that plaintext compression 1072 (zip) is not used. 1074 A JWE is a Secure Message if the JOSE Header includes 1076 o the new parameter "cid" defined in B.4, and 1078 o the IV contains the Sequence Number and a Salt (see Section 6). 1080 An SEM with Detached Content corresponds to a JWE with JOSE Header, 1081 JWE Initialization Vector, JWE Ciphertext and JWE Authentication Tag; 1082 i.e. no JWE AAD. 1084 B.3 "seq" (Sequence Number) Header Parameter 1086 The Sequence Number, corresponding to the Secure Message parameter 1087 with the same name (Section 4.1.1), SHALL be an integer represented 1088 as a byte string. Only the significant bytes are sent (initial bytes 1089 with zeros are removed). The start sequence number SHALL be 0. For 1090 a given key, "seq" MUST NOT be used more than once. 1092 The parameter "seq" SHALL be marked as critical using the "crit" 1093 header parameter (see section 4.1.11 of [RFC7515]), meaning that if 1094 a receiver does not understand this parameter it must reject the 1095 message. 1097 B.4 "cid" (Context Identifier) Header Parameter 1099 The Context Identifier, corresponding to the Secure Message parameter 1100 with the same name (Section 4.1.1), SHALL be a unique byte string 1101 identifying the security context of the sending party. The parameter 1102 "cid" SHALL be marked as critical. 1104 Appendix C. Compact Secure Message 1105 For constrained environments it is important that the message 1106 expansion due to security overhead is kept at a minimum. As an 1107 attempt to assess what this minimum expansion could be, this section 1108 defines an optimized bespoke Secure Message format (Section 4.1) 1109 called the Compact Secure Message (CSM) format. This is intended as 1110 a benchmark for COSE [I-D.schaad-cose-msg]. 1112 The Compact Secure Message (CSM) format is depicted in Figure 4. 1114 0 1 2 3 1115 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 1116 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1117 | ALG | CL | SL | CID ~ 1118 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1119 ~ SEQ ~ 1120 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1121 ~ Body ~ 1122 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1123 ~ Tag ~ 1124 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1126 Figure 4: Compact Secure Message format 1128 The CSM Header (see Section 4.1.1.) consists of 2 bytes of fixed 1129 length parameters and two variable length parameters, Context 1130 Identifier (CID) and Sequence Number (SEQ). The Header parameters 1131 are (compare Table 5): 1133 o Algorithm (ALG). This parameter consists of an encoding of the 1134 ciphersuite used in the Secure Message. The encoding is TBD. 1136 o CID Length (CL). This parameter consist of a length indication 1137 of the header parameter Context Identifier. The actual length 1138 of CID is CL + 1 bytes. 1140 o SEQ Length (SL). This parameter consist of a length indication 1141 of the header parameter Sequence Number. The actual length of 1142 SEQ is SL + 1 bytes. 1144 o Context Identifier (CID). This parameter identifies the 1145 security context/key(s) used to protect the Secure Message. 1146 Only the significant bytes are sent (initial bytes with zeros 1147 are removed). 1149 o Sequence Number (SEQ). This parameter consists of the sequence 1150 number used by the sender of the Secure Message. Only the 1151 significant bytes are sent (initial bytes with zeros are 1152 removed). 1154 +------+---------------------------+--------------------+ 1155 | Name | Parameter | Length | 1156 +------+---------------------------+--------------------+ 1157 | ALG | Algorithm | 8 bits | 1158 +------+---------------------------+--------------------+ 1159 | CL | Context Identifier Length | 5 bits | 1160 +------+---------------------------+--------------------+ 1161 | SL | Sequence Number Length | 3 bits | 1162 +------+---------------------------+--------------------+ 1163 | CID | Context Identifier | CL + 1: 1-32 bytes | 1164 +------+---------------------------+--------------------+ 1165 | SEQ | Sequence Number | SL + 1: 1-8 bytes | 1166 +------+---------------------------+--------------------+ 1168 Table 5: CSM Header Parameters. 1169 The minimum CSM Header is 4 bytes. 1171 The TID consists of the concatenation of SEQ and CID, in that order, 1172 formatted as in the CSM format (initial bytes with zeros are 1173 removed). 1175 The content of CSM Body depends on whether it is a SSM or a SEM (see 1176 Section 4.1.2) which is determined by the Algorithm. This version of 1177 the draft focuses on Secure Message with Detached Content. Hence, 1178 the SSM Body is empty and the SEM Body consists of the Ciphertext. 1179 In the former case, the length of the CSM Body is 0. In the latter 1180 case, the length of the CSM Body equals the sum of the lengths of the 1181 present CoAP options marked encrypted in Table 3 and the length of 1182 the payload of the unprotected CoAP message. 1184 The CSM Tag contains the MAC/Signature as determined from the 1185 Algorithm. The length is determined by ALG. 1187 Appendix D. COSE Profile of SM 1189 This section defines a profile of the 00-version of COSE [I-D.schaad- 1190 cose-msg] complying with the Secure Message format (see Section 4.1) 1191 and supporting the two modes of operation Mode:COAP and Mode:PAYL. 1192 In the last subsection we elaborate on possible optimizations. 1194 D.1 COSE_Sign or COSE_mac as Secure Signed Message 1196 SSM corresponds to COSE_MSG msg_type 1 (COSE_Sign) or 3 (COSE_mac). 1198 D.1.1 COSE_Sign as Secure Signed Message 1200 A COSE_MSG of type COSE_Sign is a Secure Message if its fields are 1201 defined as follows (see example in Appendix E.2). 1203 The "Headers" field of COSE_Sign MUST contain the field "protected" 1204 and this field MUST include the new "seq" parameter corresponding to 1205 the parameter Sequence Number of the Secure Message (see section 1206 4.1.1). 1208 The mandatory "signatures" array contains one "COSE_signature" item 1209 which contains a "protected" field and the mandatory "signature" 1210 field. The "protected" field includes: 1212 o the "alg" parameter which corresponds to the parameter Algorithm 1213 of the Secure Message (see section 4.1.1); 1215 o the new "cid" parameter which corresponds to the parameter 1216 Context Identifier of the Secure Message (see section 4.1.1); 1218 The mandatory "signature" field contains the computed signature 1219 value. 1221 A SSM with digital signature and Detached Content corresponds to 1222 COSE_sign with "Headers" and "signatures" fields; i.e. no "payload" 1223 field. 1225 D.1.2 COSE_mac as Secure Signed Message 1227 A COSE_MSG of type COSE_mac is a Secure Message if its fields are 1228 defined as follows (see example in Appendix E.1). 1230 The "Headers" field of COSE_mac object MUST contain the "protected" 1231 field, the "recipient" field and the mandatory "tag" field. The 1232 "protected" field MUST include: 1234 o the "alg" parameter which corresponds to the parameter Algorithm 1235 of the Secure Message (see section 4.1.1); 1237 o the new "seq" parameter corresponding to the parameter Sequence 1238 Number of the Secure Message (see section 4.1.1). 1240 The "recipients" array contains one "COSE_encrypt_a" item (section 5 1241 of [I-D.schaad-cose-msg]), which contains an "unprotected" field that 1242 includes: 1244 o the "alg" parameter corresponding to the key encryption 1245 algorithm, which in the current version of the draft is assumed 1246 to be equal to "dir" (constant). (Appendix A of [I-D.schaad- 1247 cose-msg]); 1249 o the new "cid" parameter which corresponds to the parameter 1250 Context Identifier of the Secure Message (see section 4.1.1); 1252 The mandatory "tag" field contains the MAC value. 1254 A SSM with MAC and Detached Content corresponds to a COSE_sign with 1255 "Headers", "recipients" and "tag" fields; i.e. no "payload" field. 1257 D.2 COSE_encrypt as Secure Encrypted Message 1259 SEM with AEAD algorithm corresponds to COSE_MSG msg_type 2 1260 (COSE_encrypt). A COSE_MSG of type COSE_encrypt [I-D.schaad-cose- 1261 msg] is a Secure Message if its fields are defined as follows (see 1262 example in Appendix E.3). 1264 The "Headers" field of COSE_encrypt MUST contain the "protected" 1265 field, the "recipient" field, the "cipherText" field and depending on 1266 the algorithm used, the "iv" field. 1268 The "iv" corresponds to the Initialization Vector, which contains a 1269 Salt (see Section 6) and Sequence Number as defined in section 4.1.1. 1270 For some algorithms, it is mandatory to include the "iv" field and 1271 hence the Salt is sent in each message. 1273 The "protected" field includes: 1275 o the "alg" parameter which corresponds to the parameter Algorithm 1276 of the Secure Message (see section 4.1.1); 1278 o the new "seq" parameter corresponding to the parameter Sequence 1279 Number of the Secure Message (see section 4.1.1). This parameter 1280 is present only if the "iv" field is not present in the 1281 COSE_encrypt structure. 1283 The "recipients" array contains one "COSE_encrypt_a" item as defined 1284 in section 5 of [I-D.schaad-cose-msg], which contains an 1285 "unprotected" field that includes: 1287 o the "alg" parameter corresponding to the key encryption 1288 algorithm, which in the current version of the draft is assumed 1289 to be equal to "dir" (constant). (Appendix A of [I-D.schaad- 1290 cose-msg]); 1292 o the new "cid" parameter which corresponds to the parameter 1293 Context Identifier of the Secure Message (see section 4.1.1); 1295 The "cipherText" field contains the encrypted plain text, as defined 1296 in section 5 of [I-D.schaad-cose-msg]. 1298 A SEM with Detached Content corresponds to a COSE_encrypt with 1299 "Headers", "recipients", optionally "iv" and "cipherText" fields; 1300 i.e. no "aad" field. 1302 D.3 COSE optimizations 1304 This section lists potential optimizations of COSE [I-D.schaad-cose- 1305 msg] for the purpose of reducing message size and improving 1306 performance in constrained node networks. The message sizes 1307 resulting from the first two optimizations are presented in Appendix 1308 E (as "modified COSE"). 1310 1. For COSE_encrypt and COSE_mac, there is a 'recipient' field 1311 (see section 6 of [I-D.schaad-cose-msg]). This field is 1312 intended for a setting when the sender is aware of the 1313 recipients of the message, and can wrap keys for these 1314 recipients. This is not necessarily true in the use cases 1315 targeting constrained devices and thus one possible 1316 optimization is to remove the 'recipient' field. The Context 1317 Identifier "cid" can be carried in the Header, preferably in 1318 the protected field, to avoid both protected and unprotected 1319 fields causing additional overhead. (An alternative is to 1320 define "tid", Transaction Identifier, as an array consisting of 1321 "seq" and "cid".) 1323 2. Analogous to other key values, one-byte keys/labels can be 1324 assigned to the new parameters defined in this document and 1325 cipher suites adapted to constrained device processing. For 1326 example: "cid" = 11, "seq" = 12, and "AES-CCM" = 14. 1328 3. The combination of secret key encryption and digital signature 1329 is well founded in the use cases. A solution based on wrapping 1330 one COSE message into another creates substantial overhead (see 1331 difference between modified COSE and CSM in Table 11 of 1332 Appendix E.4). A valuable optimization would be to define 1333 combined cipher suites and security contexts, and corresponding 1334 "alg" and "cid" parameters. An example would be 128-bit AES 1335 and particular curve parameters for a 64 bytes ECDSA signature. 1337 4. Digitally signed messages have the largest absolute overhead 1338 due to the size of the signature (see Appendices E.2 and E.4). 1340 Whereas certain MACs can be securely truncated, signatures 1341 cannot. Signature schemes with message recovery allow some 1342 remedy since they allow part of the message to be recovered 1343 from the signature itself and thus need not be sent. The 1344 effective size of the signature could in this way be 1345 considerably reduced, which would have a large impact on the 1346 message size (compare size of signature and total overhead in 1347 Tables 9 and 11). A valuable optimization is thus to support 1348 signature schemes with message recovery. 1350 Appendix E. Comparison of message sizes 1352 This section gives some examples of overhead incurred with JOSE, with 1353 the current proposal for COSE at the time of writing [I-D.schaad- 1354 cose-msg], and with CSM. CSM should be viewed as a lower bound for 1355 COSE. Message sizes are also listed for a modified version of COSE 1356 implementing some of the optimizations described in Appendix D.3. 1358 Motivated by the use cases, there are four different kinds of 1359 protected messages that need to be supported: message authentication 1360 code, digital signature, authenticated encryption, and symmetric 1361 encryption + digital signature. The latter is relevant e.g. for 1362 proxy-caching and publish-subscribe with untrusted intermediary (see 1363 Appendix F.2). The sizes estimated for selected algorithms are 1364 detailed in the subsections. 1366 The size of the header is shown separately from the size of the 1367 MAC/signature, since JWS/JWE has no provisions for truncating it. 1368 Compact serialization for both JWS and JWE is assumed. For CSM the 1369 encoding of algorithms is assumed as in COSE. An 8-byte Context 1370 Identifier and a 3-byte Sequence Number are used throughout all 1371 examples. To make it easier to read, COSE objects are represented 1372 using CBOR's diagnostic notation rather than a binary dump. 1374 E.1 SSM: Message Authentication Code 1376 This example is based on HMAC-SHA256, with truncation to 16 bytes. 1377 For JWS the following header is used: 1379 {"alg":"HS256","cid":0xa1534e3c5fdc09bd,"seq":0x112233} 1381 which encodes to a size of 74 bytes in Base64url, and the 32 bytes of 1382 HS256 MAC encode to 43 bytes. The concatenation marks add 2 bytes to 1383 that in the total overhead. 1385 The same object in COSE gives: 1387 {1:3, 2:{1:4, "seq":h'112233'}, 9:[{3:{"cid":h'a1534e3c5fdc09bd', 1:- 1388 6}}], 10:MAC}, where MAC is the truncated 16-byte MAC. 1390 The COSE object encodes to a total size of 53 bytes. 1392 In a modified version of COSE, with no 'recipient' field (see section 1393 6 of [I-D.schaad-cose-msg])and protected "cid" in the header, 1-byte 1394 key values are assigned to "cid" and "seq", for exemple: "cid" = 11 1395 and "seq" = 12. The equivalent COSE object would be: 1397 {1:3, 2:{1:4, 12:h'112233', 11:h'a1534e3c5fdc09bd'}, 10:MAC}, where 1398 MAC is the truncated 16-byte MAC. 1400 This modified COSE object encodes to a total size of 40 bytes. 1402 For CSM the same header is represented by 13 bytes. 1404 Table 6 summarizes these results. 1406 +--------+----------------+----------------+ 1407 | Scheme | Header | MAC | Total Overhead | 1408 +--------+----------------+----------------+ 1409 | JWS | 74 B | 43 B | 119 bytes | 1410 +--------+---------+------+----------------+ 1411 | COSE | 37 B | 16 B | 53 bytes | 1412 +--------+---------------------------------+ 1413 |mod-COSE| 24 B | 16 B | 40 bytes | 1414 +--------+---------------------------------+ 1415 | CSM | 13 B | 16 B | 29 bytes | 1416 +--------+---------------------------------+ 1418 Table 6: Comparison of JWS, COSE, modified COSE and CSM 1419 for HMAC-SHA256. 1421 E.2 SSM: Digital Signature 1423 This example is based on ECDSA, with a signature of 64 bytes. 1425 For JWS the following header is used: 1427 {"alg":"ECDSA","cid":0xa1534e3c5fdc09bd,"seq":0x112233} 1429 which encodes to a size of 74 bytes in Base64url, and the 64 bytes of 1430 signature encode to 86 bytes. The concatenation marks add 2 bytes to 1431 that in the total overhead. 1433 The same object in COSE gives: 1435 {1:1, 2:{"seq":h'112233'}, 5:[{2:{1:-7,"cid":h'a1534e3c5fdc09bd'}, 1436 6:SIG}]}, where SIG is the 64-byte signature. 1438 The COSE object encodes to a total size of 100 bytes. 1440 In a modified version of COSE, 1-byte key values are assigned to 1441 "cid" and "seq", for exemple: "cid" = 11 and "seq" = 12. The 1442 equivalent COSE object would be: 1444 {1:1, 2:{12:h'112233'}, 5:[{2:{1:-7,11:h'a1534e3c5fdc09bd'}, 6:SIG}, 1445 where SIG is the 64-byte signature. 1447 The COSE object encodes to a total size of 94 bytes. 1449 For CSM the same header is represented by 13 bytes. 1451 Table 7 summarizes these results. 1453 +--------+----------------+----------------+ 1454 | Scheme | Header | Tag | Total Overhead | 1455 +--------+----------------+----------------+ 1456 | JWS | 74 B | 86 B | 162 bytes | 1457 +--------+---------+------+----------------+ 1458 | COSE | 36 B | 64 B | 100 bytes | 1459 +--------+---------------------------------+ 1460 |mod-COSE| 30 B | 64 B | 94 bytes | 1461 +--------+---------------------------------+ 1462 | CSM | 13 B | 64 B | 77 bytes | 1463 +--------+---------------------------------+ 1465 Table 7: Comparison of JWS, COSE, modified COSE and CSM 1466 for 64 byte ECDSA signature. 1468 E.3 SEM: Authenticated Encryption 1470 This example is based on both AES-128-CCM-8 and AES-128-GCM. Since 1471 the former is not supported by JOSE, we use the latter for comparison 1472 between JOSE and COSE. 1474 For JWE it is assumed that the IV is generated from the Sequence 1475 Number and some previously agreed upon Salt. This means it is not 1476 required to explicitly send the whole IV in the CSM format, but also 1477 that the JWE and COSE formats may omit the Sequence Number. 1479 The JWE header 1480 {"alg":"dir","cid":0xa1534e3c5fdc09bd,"enc":"A128GCM"} 1482 encodes to a size of 72 bytes in Base64url, while the necessary 12 1483 byte IV for GCM mode is expanded to 16 bytes by encoding. The 16 1484 bytes of the authentication tag expand to 22 bytes. The 1485 concatenation marks add 3 bytes to the total overhead. 1487 The corresponding COSE object is: 1489 {1:2, 2:{1:1}, 7:IV, 4:TAG, 9:[{3:{"cid":h'a1534e3c5fdc09bd', 1:- 1490 6}}]}, where IV is the 12-byte IV and TAG the 16-byte authentication 1491 tag 1493 The COSE object encodes to a total size of 59 bytes. 1495 Table 8 summarizes these results. 1497 +--------+----------------+-------+----------------+ 1498 | Scheme | Header | IV | Tag | Total Overhead | 1499 +--------+----------------+-------+----------------+ 1500 | JWE | 72 B | 16 B | 22 B | 113 bytes | 1501 +--------+---------+------+-------+----------------+ 1502 | COSE | 31 B | 12 B | 16 B | 59 bytes | 1503 +--------+------------------------+----------------+ 1505 Table 8: Comparison of JWE and COSE 1506 for AES-GCM. 1508 The same calculation have been done using CCM mode instead of GCM, 1509 and adding a 3-byte "seq". The COSE object is represented as 1510 follows: 1512 {1:2, 2:{1:"AES-CCM","seq":h'112233'}, 4:TAG, 1513 9:[{3:{"cid":h'a1534e3c5fdc09bd', 1:-6}}]}, where TAG is the 16-byte 1514 authentication tag. 1516 The COSE object encodes to a total size of 52 bytes. 1518 In a modified version of COSE, the 'recipient' field is removed (see 1519 section 6 of [I-D.schaad-cose-msg])and "cid" is protected in the 1520 header. 1-byte key values are assigned to "cid", "seq" and "AES-CCM", 1521 for exemple: "cid" = 11, "seq" = 12 and "AES-CCM" = 14. The 1522 equivalent COSE object would be: 1524 {1:2, 2:{1:14,12:h'112233'}, 4:TAG, 9:[{3:{11:h'a1534e3c5fdc09bd', 1525 1:-6}}]}, where TAG is the truncated 8-byte authentication tag. 1527 This modified COSE object encodes to a total size of 39 bytes. 1529 For CSM, the corresponding header for AES-128-CCM-8, including the 8 1530 byte Sequence Number, is represented by 13 bytes and the tag is 1531 truncated to 8 Bytes. 1533 Table 9 summarizes these results. 1535 +--------+---------+-------+----------------+ 1536 | Scheme | Header | Tag | Total Overhead | 1537 +--------+---------+-------+----------------+ 1538 | COSE | 44 B | 16 B | 60 bytes | 1539 +--------+---------+-------+----------------+ 1540 |mod-COSE| 31 B | 8 B | 39 bytes | 1541 +--------+-----------------+----------------+ 1542 | CSM | 13 B | 8 B | 21 bytes | 1543 +--------+-----------------+----------------+ 1545 Table 9: Comparison of COSE, modified COSE and CSM 1546 for AES-CCM. 1548 E.4 SEM: Symmetric Encryption + Digital Signature 1550 This example is based on AES-128 and ECDSA with 64 bytes signature. 1551 JOSE and COSE require this to be a nested encapsulation of one object 1552 into another, here illustrated with a digitally signed AEAD protected 1553 object. 1555 For JWS the following header is used: 1557 {"alg":"ECDSA","cid":0xa1534e3c5fdc09bd,"seq":0x112233} 1559 which encodes to a size of 74 bytes in Base64url, and the 64 bytes of 1560 signature encode to 86 bytes. The concatenation marks add 2 bytes to 1561 that in the total overhead. 1563 The payload of the JWS object is a JWE object with the following 1564 header: 1566 {"alg":"dir","cid":0xa1534e3c5fdc09bd,"enc":"A128GCM"} 1568 which encodes to a size of 72 bytes in Base64url, while the necessary 1569 12 byte IV for GCM mode is expanded to 16 bytes by encoding. The 16 1570 bytes of the authentication tag expand to 22 bytes. The 1571 concatenation marks add 3 bytes to the total overhead. 1573 The total size of the JWS object is 275 bytes. 1575 The same object in COSE gives: 1577 {1:1, 2:{"seq":h'112233'}, 4:{1:2, 2:{1:1}, 7:IV, 4:TAG, 1578 9:[{3:{"cid":h'a1534e3c5fdc09bd', 1:-6}}]}, 5:[{2:{1:- 1579 7,"cid":h'a1534e3c5fdc09bd'}, 6:SIG}]}, where SIG is the 64-byte 1580 signature, IV is the 12-byte IV and TAG the 16-byte authentication 1581 tag. 1583 The COSE object encodes to a total size of 160 bytes. 1585 Table 10 summarizes these results. 1587 +--------+---------+-------+---------+----------------+ 1588 | Scheme | Header | Sig | Payload | Total Overhead | 1589 +--------+---------+-------+---------+----------------+ 1590 | JWS | 74 B | 86 B | 113 B | 275 bytes | 1591 +--------+---------+-------+---------+----------------+ 1592 | COSE | 37 B | 64 B | 59 B | 160 bytes | 1593 +--------+---------+-------+---------+----------------+ 1595 Table 10: Comparison of JWS and COSE 1596 for nested AES-GCM within ECDSA. 1598 The same calculation have been done using CCM mode instead of GCM, 1599 and adding a 3-byte "seq" in the protected header. 1601 The COSE object is represented as follows: 1603 {1:1, 2:{"seq":h'112233'}, 4:{1:2, 2:{1:"AES-CCM","seq":h'112233'}, 1604 4:TAG, 9:[{3:{"cid":h'a1534e3c5fdc09bd', 1:-6}}]}, 5:[{2:{1:- 1605 7,"cid":h'a1534e3c5fdc09bd'}, 6:SIG}]}, where SIG is the 64-byte 1606 signature and TAG is the 16-byte authentication tag. 1608 The COSE object encodes to a total size of 153 bytes. 1610 In a modified version of COSE, the 'recipient' field is removed (see 1611 section 6 of [I-D.schaad-cose-msg])and "cid" is protected in the 1612 header. 1-byte key values are assigned to "cid", "seq" and "AES-CCM", 1613 for exemple: "cid" = 11, "seq" = 12 and "AES-CCM" = 14. The 1614 equivalent COSE object would be: 1616 {1:1, 2:{12:h'112233'}, 4:{1:2, 2:{1:14,12:h'112233'}, 4:TAG, 1617 9:[{3:{11:h'a1534e3c5fdc09bd', 1:-6}}]}, 5:[{2:{1:- 1618 7,11:h'a1534e3c5fdc09bd'}, 6:SIG}]}, where SIG is the 64-byte 1619 signature and TAG is the 8-byte truncated authentication tag. 1621 This modified COSE object encodes to a total size of 134 bytes. 1623 For CSM we assume that an (AES, ECDSA) cipher suite has been defined, 1624 and that the "cid" identifies the context used by both the 1625 algorithms. Then the corresponding header is represented by 13 1626 bytes, and the signature by 64 bytes. 1628 Table 11 summarizes these results. 1630 +--------+---------+-------+---------+----------------+ 1631 | Scheme | Header | Sig | Payload | Total Overhead | 1632 +--------+---------+-------+---------+----------------+ 1633 | COSE | 36 B | 64 B | 52 B | 153 bytes | 1634 +--------+---------+-------+---------+----------------+ 1635 |mod-COSE| 30 B | 64 B | 39 B | 134 bytes | 1636 +--------+-----------------+---------+----------------+ 1637 | CSM | 13 B | 64 B | 0 B | 77 bytes | 1638 +--------+-----------------+---------+----------------+ 1640 Table 11: Comparison of nested AES-CCM within 1641 ECDSA (COSE, modified COSE) and combined 1642 AES-ECDSA (CSM). 1644 Appendix F. Examples 1646 This section gives examples of how to use the new options and message 1647 formats defined in this memo. 1649 F.1 CoAP Message Protection 1651 This section illustrates Mode:COAP. The message exchange assumes 1652 there is a security context established between client and server. 1653 One key is used for each direction of the message transfer. The 1654 intermediate node detects that the CoAP message contains a SM 1655 Mode:COAP object (Sig or Enc option is set) and thus forwards the 1656 message as it cannot serve a cached response. 1658 F.1.1 Integrity Protection of CoAP Message Exchange 1660 Here is an example of a PUT request/response message exchange passing 1661 an intermediate node protected with the Sig option. The example 1662 illustrates a client closing a lock and getting a confirmation that 1663 the lock is closed. Code, Uri-Path and Payload of the request and 1664 Code of the response are integrity protected (and other message 1665 fields, see Appendix A). 1667 Client Proxy Server 1668 | | | 1669 | | | 1670 | | | 1671 +----->| | Code: 0.03 (PUT) 1672 | PUT | | Token: 0x8c 1673 | | | Uri-Path: lock 1674 | | | Sig: SSM {"seq":"00000142", 1675 | | | "cid":"a1534e3c5fdc09bd", ...} 1676 | | | Payload: 1 1677 | | | 1678 | +----->| Code: 0.03 (PUT) 1679 | | PUT | Token: 0x7b 1680 | | | Uri-Path: lock 1681 | | | Sig: SSM {"seq":"00000142", 1682 | | | "cid":"a1534e3c5fdc09bd", ...} 1683 | | | Payload: 1 1684 | | | 1685 | | | 1686 | |<-----+ Code: 2.04 (Changed) 1687 | | 2.04 | Token: 0x7b 1688 | | | Sig: SSM {"seq":"000000a6", 1689 | | | "cid":"5fdc09bda1534e3c", ...} 1690 | | | 1691 |<-----+ | Code: 2.04 (Changed) 1692 | 2.04 | | Token: 0x8c 1693 | | | Sig: SSM {"seq":"000000a6", 1694 | | | "cid":"5fdc09bda1534e3c", ...} 1695 | | | 1697 Figure 8: CoAP PUT protected with Sig/SSM (Mode:COAP) 1699 The Context Identifier is an identifier indicating which security 1700 context was used to integrity protect the message, and may be used as 1701 an identifier for a secret key or a public key. (It may e.g. be the 1702 hash of a public key.) 1704 The server and client can verify that the Sequence Number has not 1705 been received and used with this key before, and since Mode is COAP, 1706 the client can additionally verify the freshness of the response, 1707 i.e. that the response message is generated as an answer to the 1708 received request message (see Section 5.3). 1710 The SSM also contains the Tag as specified in the Algorithm (not 1711 shown in the Figure). 1713 This example deviates from encryption (SEM) by default (see Section 1714 6) just to illustrate the Sig option. If there is no compelling 1715 reason why the CoAP message should be in plaintext, then the Enc 1716 option MUST be used. 1718 F.1.2 Additional Encryption of CoAP Message 1720 Here is an example of a GET request/response message exchange passing 1721 an intermediate node protected with the Enc option. The example 1722 illustrates a client requesting a blood sugar measurement resource 1723 (GET /glucose) and receiving the value 220 mg/dl. Uri-Path and 1724 Payload are encrypted and integrity protected. Code is integrity 1725 protected only (see Appendix A). 1727 Client Proxy Server 1728 | | | 1729 | | | 1730 | | | 1731 +----->| | Code: 0.01 (GET) 1732 | GET | | Token: 0x83 1733 | | | Enc: SEM {"seq":"000015b7", 1734 | | | "cid":"34e3c5fdca1509bd", 1735 | | | ["glucose" ... ], ...} 1736 | | | 1737 | +----->| Code: 0.01 (GET) 1738 | | GET | Token: 0xbe 1739 | | | Enc: SEM {"seq":"000015b7", 1740 | | | "cid":"34e3c5fdca1509bd", 1741 | | | ["glucose" ... ], ...} 1742 | | | 1743 | | | 1744 | |<-----+ Code: 2.05 (Content) 1745 | | 2.05 | Token: 0xbe 1746 | | | Enc: 1747 | | | Payload: SEM {"seq":"000015b7", 1748 | | | "cid":"c09bda155fd34e3c", 1749 | | | [... 220], ...} 1750 | | | 1751 |<-----+ | Code: 2.05 (Content) 1752 | 2.05 | | Token: 0x83 1753 | | | Enc: 1754 | | | Payload: SEM {"seq":"000015b7", 1755 | | | "cid":"c09bda155fd34e3c", 1756 | | | [... 220], ...} 1757 | | | 1759 Figure 9: CoAP GET protected with Enc/SEM (Mode:COAP). 1760 The bracket [ ... ] indicates encrypted data. 1762 Since the request message (GET) does not support payload, the SEM is 1763 carried in the Enc option. Since the response message (Content) 1764 supports payload, the Enc option is empty and the SEM is carried in 1765 the payload. 1767 The Context Identifier is a hint to the receiver indicating which 1768 security context was used to encrypt and integrity protect the 1769 message, and may be used as an identifier for the AEAD secret key. 1770 One key is used for each direction of the message transfer. 1772 The server and client can verify that the Sequence Number has not 1773 been received and used with this key before, and since Mode:COAP the 1774 client can additionally verify the freshness of the response, i.e. 1775 that the response message is generated as an answer to the received 1776 request message (see Section 5.3). 1778 The SEM also contains the Tag as specified by the Algorithm (not 1779 shown in the Figure). 1781 F.2 Payload Protection 1783 This section gives examples that illustrate Mode:PAYL. This mode 1784 assumes that only the intended receiver(s) has the relevant security 1785 context related to the resource. In case of a closed group of 1786 recipients of the same object, e.g. in Information-Centric Networking 1787 or firmware update distribution, it may be necessary to support 1788 symmetric key encryption in combination with digital signature. 1790 F.2.1 Proxy Caching 1792 This examples applies e.g. to closed user groups of a single data 1793 source. The example outlines how a proxy forwarding request and 1794 response of one client can cache a response whose payload is a SEM 1795 object, and serve this response to another client request, such that 1796 both clients can verify integrity and non-replay. 1798 Client1 Proxy Server 1800 | | | 1801 | | | 1802 +----->| | Code: 0.01 (GET) 1803 | GET | | Token: 0x83 1804 | | | Proxy-Uri: example.com/temp 1805 | | | 1806 | | | 1807 | +----->| Code: 0.01 (GET) 1808 | | GET | Token: 0xbe 1809 | | | Uri-Host: example.com 1810 | | | Uri-Path: temp 1811 | | | 1812 | | | 1813 | |<-----+ Code: 2.05 (Content) 1814 | | 2.05 | Token: 0xbe 1815 | | | Payload: SEM {"seq":"000015b7", 1816 | | | "cid":"c09bda155fd34e3c", 1817 | | | ["471 F"], ...} 1818 | | | 1819 |<-----+ | Code: 2.05 (Content) 1820 | 2.05 | | Token: 0x83 1821 | | | Payload: SEM {"seq":"000015b7", 1822 | | | "cid":"c09bda155fd34e3c", 1823 | | ["471 F"], ...} 1824 Client2 | | 1825 | | 1826 | | | 1827 | | | 1828 +----->| | Code: 0.01 (GET) 1829 | GET | | Token: 0xa1 1830 | | | Proxy-Uri: example.com/temp 1831 | | | 1832 |<-----+ | Code: 2.05 (Content) 1833 | 2.05 | | Token: 0xa1 1834 | | | Payload: SEM {"seq":"000015b7", 1835 | | | "cid":"c09bda155fd34e3c", 1836 | | | ["471 F"], ...} 1838 Figure 10: Proxy caching protected with SEM (Mode:PAYL) 1840 F.2.2 Publish-Subscribe 1842 This example outlines a publish-subscribe setting where the payload 1843 is integrity and replay protected end-to-end between Publisher and 1844 Subscriber. The example illustrates a subscription registration and 1845 a new publication of birch pollen count of 300 per cubic meters. The 1846 PubSub Broker can define the Observe count arbitrarily (as could any 1847 intermediary node, even in Mode:COAP), but cannot manipulate the 1848 Sequence Number without being noticed. 1850 Sub- PubSub- Pub- 1851 scriber Broker lisher 1853 | | | 1854 +----->| | Code: 0.01 (GET) 1855 | GET | | Token: 0x72 1856 | | | Uri-Path: ps 1857 | | | Uri-Path: birch-pollen 1858 | | | Observe: 0 (register) 1859 | | | 1860 | | | 1861 |<-----+ | Code: 2.05 (Content) 1862 | 2.05 | | Token: 0x72 1863 | | | Observe: 1 1864 | | | Payload: SSM {"seq":"000015b7", 1865 | | | "cid":"c09bda155fd34e3c", 1866 | | | ["270"], ...} 1867 | | | 1868 | | | 1869 | | | 1870 | |<-----+ Code: 0.03 (PUT) 1871 | | PUT | Token: 0x1f 1872 | | | Uri-Path: ps 1873 | | | Uri-Path: birch-pollen 1874 | | | Payload: SSM {"seq":"000015b8", 1875 | | | "cid":"c09bda155fd34e3c", 1876 | | | ["300"], ...} 1877 | | | 1878 | +----->| Code: 2.04 (Changed) 1879 | | 2.04 | Token: 0x1f 1880 | | | 1881 | | | 1882 |<-----+ | Code: 2.05 (Content) 1883 | 2.05 | | Token: 0x72 1884 | | | Observe: 2 1885 | | | Payload: SSM {"seq":"000015b8", 1886 | | | "cid":"c09bda155fd34e3c", 1887 | | | ["300"], ...} 1889 Figure 11: Publish-subscribe protected with SSM (Mode:PAYL) 1891 This example deviates from encryption (SEM) by default (see Section 1892 6) just to illustrate the SSM in Mode:PAYL. If there is no 1893 compelling reason why the payload should be in plaintext, then SEM 1894 MUST be used. 1896 F.2.3 Transporting Authorization Information 1898 This example outlines the transportation of authorization information 1899 from a node producing (Authorization Server, AS) to a node consuming 1900 (Resource Server, RS) such information. Authorization information 1901 may for example be an authorization decision with respect to a Client 1902 (C) accessing a Resource to be enforced by RS. See [I-D.seitz-ace- 1903 core-authz] and Section 8.4-8.6 of [I-D.gerdes-ace-actors]. 1905 Here, C is clearly not trusted with modifying the information, but 1906 may need to be involved in mediating the authorization information to 1907 the RS, for example, because AS and RS does not have direct 1908 connectivity. So end-to-end security is required and object security 1909 ("access tokens") is the natural candidate. 1911 This example considers the authorization information to be 1912 encapsulated in a SEM Mode:PAYL object, generated by AS. How C 1913 accesses the SEM is out of scope for this example, it may e.g. be 1914 using CoAP. C then requests RS to configure the authorization 1915 information in the SEM by doing POST to /authorize. This particular 1916 resource has a default access policy that only new messages signed by 1917 AS are authorized. RS thus verifies the integrity and sequence 1918 number by using the existing security context for the AS, and 1919 responds accordingly, a) or b), see Figure 12. 1921 Authz Resource 1922 Server Client Server 1923 | | | 1924 | | | Client access Access Token: 1925 +- - ->| | SEM {"seq":"00000142", 1926 | | | "cid":"c09bda1534e3c5fdc09bd", ...} 1927 | | | 1928 | | | 1929 | +----->| Code: 0.02 (POST) 1930 | | POST | Token: 0xac 1931 | | | Uri-Path: authorize 1932 | | | Payload: SEM {"seq":"00000142", 1933 | | | "cid":"c09bda1534e3c5fdc09bd", ...} 1935 a) 1936 | | | 1937 | |<-----+ Code: 2.04 (Changed) 1938 | | 2.04 | Token: 0xac 1939 | | | 1941 b) 1942 | | | 1943 | |<-----+ Code: 4.01 (Unauthorized) 1944 | | 4.01 | Token: 0xac 1945 | | | 1947 Figure 12: Protected Transfer of Access Token = SEM (Mode:PAYL) 1949 Authors' Addresses 1950 Goeran Selander 1951 Ericsson 1952 Farogatan 6 1953 16480 Kista 1954 SWEDEN 1955 EMail: goran.selander@ericsson.com 1957 John Mattsson 1958 Ericsson 1959 Farogatan 6 1960 16480 Kista 1961 SWEDEN 1962 EMail: john.mattsson@ericsson.com 1964 Francesca Palombini 1965 Ericsson 1966 Farogatan 6 1967 16480 Kista 1968 SWEDEN 1969 EMail: francesca.palombini@ericsson.com 1971 Ludwig Seitz 1972 SICS Swedish ICT AB 1973 Scheelevagen 17 1974 22370 Lund 1975 SWEDEN 1976 EMail: ludwig@sics.se