idnits 2.17.1 draft-selander-ace-object-security-01.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 -- The document date (March 9, 2015) is 3336 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 (-03) exists of draft-seitz-ace-problem-description-02 == Outdated reference: A later version (-10) exists of draft-ietf-ace-usecases-02 == 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 (~~), 5 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 Ericsson 5 Expires: September 10, 2015 L. Seitz 6 SICS Swedish ICT 8 March 9, 2015 10 Object Security for CoAP 11 draft-selander-ace-object-security-01 12 Abstract 14 This memo presents a scheme for data object security applicable to 15 protection of payload of generic message formats as well as request 16 and response messages of the Constrained Application Protocol (CoAP). 18 Status of this Memo 20 This Internet-Draft is submitted to IETF in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF), its areas, and its working groups. Note that 25 other groups may also distribute working documents as 26 Internet-Drafts. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress". 33 The list of current Internet-Drafts can be accessed at 34 http://www.ietf.org/1id-abstracts.html 36 The list of Internet-Draft Shadow Directories can be accessed at 37 http://www.ietf.org/shadow.html 39 Copyright and License Notice 41 Copyright (c) 2015 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 57 1.1 Terminology . . . . . . . . . . . . . . . . . . . . . . . . 4 58 2. Background . . . . . . . . . . . . . . . . . . . . . . . . . . 5 59 3. End-to-end Security in Presence of Intermediary Nodes . . . . . 6 60 4. Secure Message . . . . . . . . . . . . . . . . . . . . . . . . 7 61 4.1 Secure Message format . . . . . . . . . . . . . . . . . . . 8 62 4.1.1 Secure Message Header . . . . . . . . . . . . . . . . . 8 63 4.1.2 Secure Message Body . . . . . . . . . . . . . . . . . . 9 64 4.1.2.1 Secure Signed Message Body . . . . . . . . . . . . . 9 65 4.1.2.2 Secure Encrypted Message Body . . . . . . . . . . . 9 66 4.1.3 Secure Message Tag . . . . . . . . . . . . . . . . . . . 9 67 5. Message Protection . . . . . . . . . . . . . . . . . . . . . . 9 68 5.1 CoAP Message Protection . . . . . . . . . . . . . . . . . . 10 69 5.1.1 The Sig Option . . . . . . . . . . . . . . . . . . . . . 10 70 5.1.1.1 Option Structure . . . . . . . . . . . . . . . . . . 10 71 5.1.1.2 Integrity Protection and Verification . . . . . . . 11 72 5.1.1.3 SSM Body . . . . . . . . . . . . . . . . . . . . . . 11 73 5.1.2 The Enc Option . . . . . . . . . . . . . . . . . . . . . 12 74 5.1.2.1 Option Structure . . . . . . . . . . . . . . . . . . 12 75 5.1.2.2 Encryption and Decryption . . . . . . . . . . . . . 12 76 5.1.2.3 SEM Body . . . . . . . . . . . . . . . . . . . . . . 13 77 5.1.2.4 CoAP Message with Enc Option . . . . . . . . . . . . 13 78 5.1.3 SM Tag . . . . . . . . . . . . . . . . . . . . . . . . . 14 79 5.2 Application Layer Protection . . . . . . . . . . . . . . . . 14 80 5.3 Replay Protection and Freshness . . . . . . . . . . . . . . 15 81 5.3.1 Replay Protection . . . . . . . . . . . . . . . . . . . 15 82 5.3.2 Freshness . . . . . . . . . . . . . . . . . . . . . . . 15 83 6. Security Considerations . . . . . . . . . . . . . . . . . . . . 16 84 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . . 17 85 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 86 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 18 87 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 19 88 10.1 Normative References . . . . . . . . . . . . . . . . . . . 19 89 10.2 Informative References . . . . . . . . . . . . . . . . . . 19 90 Appendix A. Which CoAP Header Fields and Options to Protect . . . 20 91 A.1 CoAP Header Fields . . . . . . . . . . . . . . . . . . . . . 20 92 A.2 CoAP Options . . . . . . . . . . . . . . . . . . . . . . . . 20 93 A.2.1 Integrity Protection . . . . . . . . . . . . . . . . . . 21 94 A.2.2 Encryption . . . . . . . . . . . . . . . . . . . . . . . 22 95 A.2.3 Summary . . . . . . . . . . . . . . . . . . . . . . . . 22 96 Appendix B. JOSE Objects as Secure Messages . . . . . . . . . . . 23 97 B.1 JWS as Secure Signed Message . . . . . . . . . . . . . . . 23 98 B.2 JWE as Secure Encrypted Message . . . . . . . . . . . . . . 23 99 B.3 "seq" (Sequence Number) Header Parameter . . . . . . . . . . 24 100 B.4 "mod" (Mode) Header Parameter . . . . . . . . . . . . . . . 24 101 B.4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 102 Appendix C. Compact Secure Message . . . . . . . . . . . . . . . 25 103 C.1 CSM Format . . . . . . . . . . . . . . . . . . . . . . . . . 25 104 C.2 Comparison of Secure Message sizes . . . . . . . . . . . . . 27 105 Appendix D. Examples . . . . . . . . . . . . . . . . . . . . . . 29 106 D.1 CoAP Message Protection . . . . . . . . . . . . . . . . . . 29 107 D.1.1 Integrity protection of CoAP Message . . . . . . . . . . 29 108 D.1.2 Encryption of CoAP Message . . . . . . . . . . . . . . . 30 109 D.2 Application Layer Protection . . . . . . . . . . . . . . . . 32 110 D.2.1 Proxy Caching . . . . . . . . . . . . . . . . . . . . . 32 111 D.2.2 Publish-Subscribe . . . . . . . . . . . . . . . . . . . 33 112 D.2.3 Transporting Authorization Information . . . . . . . . . 34 113 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 35 115 1. Introduction 117 The Constrained Application Protocol CoAP [RFC7252] was designed with 118 a constrained RESTful environment in mind. CoAP references DTLS 119 [RFC6347] for securing the message exchanges. Two commonly used 120 features of CoAP are store-and-forward and publish-subscribe 121 exchanges, which are problematic to secure with DTLS and transport 122 layer security. As DTLS offers hop-by-hop security, in case of 123 store-and-forward exchanges it necessitates a trusted intermediary. 124 On the other hand, securing publish-subscribe CoAP exchanges with 125 DTLS requires the use of the keep-alive mechanism which incurs 126 additional overhead and actually takes away most of the benefits of 127 asynchronous communication. 129 The pervasive monitoring debate has illustrated the need to protect 130 data also from trustworthy intermediary nodes as they can be 131 compromised. The community has reacted strongly to the revelations, 132 and new solutions must consider this attack [RFC7258] and include 133 encryption by default. 135 This memo presents an object security approach for secure messaging 136 in constrained environments that may be used as a complement to DTLS 137 for store-and-forward and publish-subscribe CoAP exchanges. Note 138 that the solution sketched in this memo can be combined with DTLS 139 thus enabling, for example, end-to-end security of CoAP payload in 140 combination with hop-by-hop protection of the entire CoAP messages 141 during transport between end-point and intermediary node. 143 This version of the draft focuses on symmetric key based algorithms. 144 Public key based algorithms will be addressed in the next version. 146 1.1 Terminology 148 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 149 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 150 document are to be interpreted as described in [RFC2119]. These 151 words may also appear in this document in lowercase, absent their 152 normative meanings. 154 Certain security-related terms are to be understood in the sense 155 defined in RFC 4949 [RFC4949]. These terms include, but are not 156 limited to, "authentication", "authorization", "confidentiality", 157 "(data) integrity", "message authentication code", "signature", and 158 "verify". 160 RESTful terms, such as "resource" or "representation", are to be 161 understood as used in HTTP [RFC7231] and CoAP. 163 Terminology for constrained environments, such as "constrained 164 device", "constrained-node network", is defined in [RFC7228]. 166 Client, Resource Server, and Authorization Server are defined in [I- 167 D.seitz-ace-problem-description]. The terms "server" and "Resource 168 Server" are used interchangeably. 170 JSON Web Signature (JWS), JOSE Header, JWS Payload, and JWS Signature 171 are defined in [I-D.ietf-jose-json-web-signature]. 173 JSON Web Encryption (JWE), JWE AAD, JWE Ciphertext, and JWE 174 Authentication Tag are defined in [I-D.ietf-jose-json-web- 175 encryption]. 177 Secure Message (SM), Secure Signed Message (SSM), and Secure 178 Encrypted Message (SEM) are message formats defined in this memo. 179 The Compact Secure Message (CSM) format is defined in Appendix C. 180 The Sig and Enc options are CoAP options defined in this memo. 182 Excluded Authenticated Data (EAD) is defined in this memo (see 183 Sections 4.1.2). Transaction Identifier (TID) is defined in this 184 memo (see Section 4.1.1). 186 2. Background 188 The background for this work is provided by the use cases and problem 189 description in [I-D.ietf-ace-usecases] and [I-D.seitz-ace-problem- 190 description]. The overall objective is that (a) only authorized 191 requests are granted, and (b) messages between client and server are 192 protected (according to requirements of the particular use case). 193 The focus of this memo is on end-to-end security in constrained 194 environments in the presence of intermediary nodes, which corresponds 195 to point (b). 197 For constrained-node networks there may be several reasons for 198 messages to be cached or stored in one node and later forwarded. For 199 example, connectivity between the nodes may be intermittent, or some 200 node may be sleeping at the time when the message should have been 201 forwarded (see e.g. [I-D.ietf-ace-usecases] sections 2.1.1, and 202 2.5.1). Also, the architectural model or protocol applied may 203 require an intermediary node which breaks security on transport layer 204 (see e.g. [I-D.ietf-ace-usecases] sections 2.1.1, and 2.5.2). 205 Examples of intermediary nodes include forward proxies, reverse 206 proxies, pub-sub brokers, HTTP-CoAP cross-proxies, and SMS servers. 208 On a high level, end-to-end security in this setting encompasses: 210 1. Protection against eavesdropping and manipulation of resource 211 representations in intermediary nodes; 213 2. Protection against message replay; 215 3. Protection of authorization information ("access tokens") in 216 transport from an Authorization Server to a Resource Server via 217 a Client, or other intermediary nodes which could gain from 218 changing the information; 220 4. Allowing a client to verify that a response comes from a 221 certain server and is the response to a particular request; 223 5. Protection of the RESTful method used by the client, or the 224 response code used by the server. For example if a malicious 225 proxy replaces the client requested GET with a DELETE this must 226 be detected by the server; 228 6. Protection against eavesdropping of meta-data of the request or 229 response, including CoAP options such as for example Uri-Path 230 and Uri-Query, which may reveal some information on what is 231 requested. 233 From the listed examples, there are two main categories of security 234 requirements and corresponding solutions. The first category deals 235 essentially with application layer protection, i.e. protecting the 236 payload of the RESTful protocol (1-3). The second category deals 237 with protecting an entire CoAP message, targeting also CoAP options 238 and header fields (4-6). The next section formulates security 239 requirements for the two categories, which are denoted Mode:APPL and 240 Mode:COAP, respectively. 242 3. End-to-end Security in Presence of Intermediary Nodes 244 For high-level security requirements related to resource access, see 245 section 4.6 of [I-D.seitz-ace-problem-description]. This section 246 defines the specific requirements that address the two categories of 247 examples identified in the previous section, taking into account 248 potential intermediary nodes. 250 In the case of application layer protection (Mode:APPL), the end-to- 251 end security requirements apply to the RESTful protocol payload data, 252 such as Resource Representations: 254 a. The payload shall be integrity protected and should be 255 encrypted end-to-end from sender to receiver. 257 b. It shall be possible for an intended receiver to detect if it 258 has received this message previously, i.e. replay protection. 260 In this case there may be multiple receivers of a given message, for 261 example in the case of a proxy that is caching responses used to 262 serve multiple clients, or in a publish-subscribe setting with 263 multiple subscribers to a given publication. 265 In the case of protecting specific Client-Server CoAP message 266 exchanges (Mode:COAP), potentially passing via intermediary nodes, 267 there are additional end-to-end security requirements: 269 c. The CoAP options which are not intended to be changed by an 270 intermediary node shall be integrity protected between Client 271 and Server. 273 d. The CoAP options which are not intended to be read by an 274 intermediary node shall be encrypted between Client and Server. 276 e. The CoAP header field "Code" shall be integrity protected 277 between Client and Server. 279 f. A Client shall be able to verify that a message is the response 280 to a particular request the Client made. 282 The requirements listed above can be met by encryption, integrity 283 protection and replay protection. What differs is the actual data 284 that is protected, i.e. application layer data or CoAP message data. 285 This memo specifies a common "Secure Message" format that can be used 286 to wrap either payload only or also additional selected CoAP message 287 fields, and be sent as part of the message. 289 4. Secure Message 291 There exist already standardized and draft content formats for 292 cryptographically protected data such as CMS [RFC5652], JWS, JWE, and 293 COSE [I-D.bormann-jose-cose]. None of the listed formats provide 294 support for replay protection, but it is noted in section 10.10 of 295 [I-D.ietf-jose-json-web-signature]) that one way to thwart replay 296 attacks is to include a unique transaction identifier and have the 297 recipient verify that the message has not been previously received or 298 acted upon. 300 The term Secure Message (SM) format refers to a content format for 301 cryptographically protected data which includes a unique transaction 302 identifier and allows customization to support different variants of 303 format and message processing (Modes). 305 This memo uses JOSE content formats as a model to specify format and 306 processing of messages. The terms Secure Signed Message (SSM) format 307 and Secure Encrypted Message (SEM) format to refer to Secure Message 308 formats supporting integrity protection only and additional 309 encryption, analogous to JWS and JWE, respectively. Appendix B shows 310 how JWS and JWE could be extended to become Secure Message formats. 312 It should be noted that the current JOSE objects are undesirably 313 large for very constrained devices. In their current size they can 314 lead to packet fragmentation in constrained-node networks due to 315 limited frame sizes, and to problems with limited storage capacity on 316 constrained devices due to limited RAM. COSE renders more compact 317 objects, and further optimizations are considered. See Appendix C 318 for a discussion of minimum message expansion and message format 319 overhead. 321 4.1 Secure Message format 323 A Secure Message (SM) SHALL consist of Header, Body and Tag. 325 4.1.1 Secure Message Header 327 The following parameters SHALL be included in the SM Header: 329 o Algorithm. This parameter allows the receiver to identify the 330 cryptographic algorithm(s) used to protect the Secure Message. 331 In case of SSM it has the same syntax as the JOSE Header 332 Parameter "alg" defined in Section 4.1.1 of [I-D.ietf-jose-json- 333 web-signature]. In case of SEM, it has the same syntax as the 334 JOSE Header Parameter "enc" defined in Section 4.1.2 of [I- 335 D.ietf-jose-json-web-encryption]. (Assuming direct key 336 agreement, corresponding to the JWE "alg" = "dir" setting.) 338 o Key Identifier. This parameter allows the receiver to uniquely 339 identify the sender and the security context/key(s) used with 340 the Algorithm. It has the same syntax as the JOSE Header 341 Parameter "kid" defined in Section 4.1.4 of [I-D.ietf-jose-json- 342 web-signature]. 344 o Sequence Number. The Sequence Number parameter enumerates the 345 Secure Messages protected using the key(s) identified by the Key 346 Identifier, and is used for replay protection and uniqueness of 347 nonce. The start sequence number SHALL be 0. For a given key, 348 any Sequence Number MUST NOT be used more than once. 350 o Mode. The Mode parameter defines application specific message 351 format, content and processing. This parameter provides means 352 for customization of the Secure Message format, in particular to 353 distinguish between Secure Messages containing application layer 354 data only or CoAP message data. 356 The ordered sequence (Sequence Number, Key Identifier) is called 357 Transaction Identifier (TID), and SHALL be unique for each SM. 359 4.1.2 Secure Message Body 361 Analogously to JWS and JWE, the SM Body contains what is being 362 protected. The SM Body is different for SSM and SEM. 364 In order to obtain a compact representation, certain data is 365 integrity protected but excluded from the Secure Message. Such data 366 is referred to as Excluded Authenticated Data (EAD). To further 367 reduce message size, the unencrypted part of the SM Body may be 368 "detached" from the Secure Message, see sections 4.1.2.1 and 4.1.2.2. 370 The assumption behind excluding integrity protected data from the SM, 371 or detaching integrity protected but not encrypted parts of the SM 372 during transport, is that the data in question is known to the 373 receiver, e.g. because it is exchanged beforehand or because it is 374 transported as part of the CoAP message carrying the Secure Message. 376 4.1.2.1 Secure Signed Message Body 378 For SSM, the Body consists of the payload data which is integrity 379 protected, analogously to the JWS Payload. Detached Content is 380 defined to mean that the Body is removed from the Secure Message, 381 analogously to Appendix F of [I-D.ietf-jose-json-web-signature]. 382 Hence a SSM with Detached Content consists of Header and Tag. 384 4.1.2.2 Secure Encrypted Message Body 386 Analogously to JWE, the terms Plaintext, Ciphertext and Additional 387 Authenticated Data (AAD) are used for the SEM. The Body of a SEM 388 consists of Ciphertext and Additional Authenticated Data (AAD). For 389 SEM Detached Content is defined to mean that the AAD is removed from 390 the Secure Message. Hence a SEM with Detached Content consists of 391 the Header, Ciphertext and Tag. 393 4.1.3 Secure Message Tag 395 The SM Tag consists of the Signature / Authentication Tag value as 396 defined by the Algorithm, calculated over the SM Header, SM Body and 397 EAD (if present). The content of EAD depends on the Mode, see 5.1.3 398 and 5.2 400 5. Message Protection 401 This section describes what is protected in a Secure Message and how 402 it depends on the defined Modes ("CoAP Message Protection" and 403 "Application Layer Protection"). Both formats SSM and SEM defined in 404 the previous section are applicable to both Modes. For examples, see 405 Appendix D. 407 For any Secure Message Mode, the SEM format SHALL be used by default. 409 The SM Header is defined in 4.1.1, indicates the Mode, but is in all 410 other respects handled similarly in both Modes. This section also 411 describes the differences in SM Body and SM Tag. 413 5.1 CoAP Message Protection 415 Referring to examples 4-6 in Section 2 and requirements a-f in 416 Section 3, this section presents how to protect individual CoAP 417 messages including options and header fields, as well as request- 418 response message exchanges, using the Secure Message format. This is 419 called Secure Message Mode:COAP. An endpoint receiving a CoAP 420 request containing a Secure Message with Mode:COAP MUST respond with 421 a CoAP message containing a Secure Message with Mode:COAP. 423 Since slightly different message formats are used for integrity 424 protection only (SSM), and additional encryption (SEM), these cases 425 are treated separately. Two new CoAP security options are 426 introduced: the Enc option and the Sig option. A CoAP message SHALL 427 NOT include both Enc and Sig options. 429 5.1.1 The Sig Option 431 In order to integrity protect CoAP message exchanges, a new CoAP 432 option is introduced: the Sig option, containing a SSM Mode:COAP 433 object. Endpoints supporting this scheme MUST check for the 434 presence of a Sig option, and verify the SSM as described in Section 435 5.1.1.2 before accepting a message as valid. 437 5.1.1.1 Option Structure 439 The Sig option indicates that certain CoAP Header Fields, Options, 440 and Payload (if present) are integrity and replay protected using a 441 Secure Signed Message (SSM). The Sig option SHALL contain a SSM with 442 Detached Content (see Section 4.1.2.1). 444 This option is critical, safe to forward, it is not part of a cache 445 key, and it is not repeatable. Table 1 illustrates the structure of 446 this option. 448 +-----+---+---+---+---+---------+--------+-----------+ 449 | No. | C | U | N | R | Name | Format | Length *) | 450 +-----+---+---+---+---+---------+--------+-----------+ 451 | TBD | x | | x | | Sig | opaque | 12-TBD | 452 +-----+---+---+---+---+---------+--------+-----------+ 454 C=Critical, U=Unsafe, N=NoCacheKey, R=Repeatable 456 Table 1: The Sig Option 458 *) Length is essentially Length(SSM Header) + Length(SSM Tag). The 459 minimum length is estimated in Appendix C. The maximum length 460 depends on actual message format selected and is TBD. 462 5.1.1.2 Integrity Protection and Verification 464 A CoAP endpoint composing a message with the Sig option SHALL process 465 the SSM and produce the SSM Tag, as defined in 5.1.1.3 and 5.1.3, 466 analogously to the specification for producing a JWS object as 467 described in Section 5.1 of [I-D.ietf-jose-json-web-signature] (cf. 468 Appendix B). In addition, the sending endpoint SHALL process the 469 Sequence Number as described in Section 5.3. 471 A CoAP endpoint receiving a message containing the Sig option SHALL 472 first recreate the SSM Body as described in Section 5.1.1.3, and then 473 verify the SSM Tag as described in Section 5.1.3, analogously to the 474 specification for verifying a JWS object as described in Section 5.2 475 of [I-D.ietf-jose-json-web-signature] (cf. Appendix B). In addition, 476 the receiving endpoint SHALL process the Sequence Number as described 477 in Section 5.3. 479 NOTE: The explicit steps of the protection and verification procedure 480 will be included in a future version of this draft. 482 5.1.1.3 SSM Body 484 The SSM Body SHALL consist of the following data, in this order: 486 o the 8-bit CoAP header field Code; 488 o all CoAP options present which are marked as IP in Table 3 489 (Appendix A), in the order as given by the option number (each 490 Option with Option Header including delta to previous IP-marked 491 Option which is present); and 493 o the CoAP Payload (if any). 495 5.1.2 The Enc Option 497 In order to encrypt and integrity protect CoAP messages, a new CoAP 498 option is introduced: the Enc option, indicating the presence of a 499 SEM Mode:COAP object in the CoAP message, containing the encrypted 500 part of the CoAP message. Endpoints supporting this scheme MUST 501 check for the presence of an Enc option, and verify the SEM as 502 described in 5.1.2.2 before accepting a message as valid. 504 NOTE: This version of the draft is only considering AEAD algorithms. 506 5.1.2.1 Option Structure 508 The Enc option indicates that certain CoAP Options and Payload (if 509 present) are encrypted, integrity and replay protected using a Secure 510 Encrypted Message (SEM) with Detached Content (see Section 4.1.2.2). 511 The structure of a CoAP message with an Enc option is described in 512 Section 5.1.2.4. 514 This option is critical, safe to forward, it is not part of a cache 515 key, and it is not repeatable. Table 2 illustrates the structure of 516 this option. 518 +-----+---+---+---+---+---------+--------+-------------+ 519 | No. | C | U | N | R | Name | Format | Length *) | 520 +-----+---+---+---+---+---------+--------+-------------+ 521 | TBD | x | | x | | Enc | opaque | 0 or 12-TBD | 522 +-----+---+---+---+---+---------+--------+-------------+ 524 C=Critical, U=Unsafe, N=NoCacheKey, R=Repeatable 526 Table 2: The Enc Option 528 *) Length indicates in this case the additional length added to the 529 total length of all CoAP options. If the CoAP message has Payload, 530 then the Enc option is empty, otherwise it contains the SEM (see 531 Section 5.1.2.4). In the latter case, the SEM Ciphertext contains 532 the encrypted CoAP Options (see Section 5.1.2.3), which are thus 533 excluded from plaintext part of the message. Hence the additional 534 length is essentially Length(SEM Header) + Length(SEM Tag). The 535 minimum length is estimated in Appendix C. The maximum length 536 depends on actual message format selected and is TBD. 538 5.1.2.2 Encryption and Decryption 540 A CoAP endpoint composing a message with the Enc option SHALL process 541 the SEM and produce the SEM Ciphertext and SEM Tag, as defined in 542 5.1.2.3 and 5.1.3, analogously to the specification for producing a 543 JWE object as described in Section 5.1 of [I-D.ietf-jose-json-web- 544 encryption] (cf. Appendix B). In addition, the sending endpoint 545 SHALL process the Sequence Number as described in Section 5.3. 547 A CoAP endpoint receiving a message containing the Enc option SHALL 548 first recreate the SEM Body as described in Section 5.1.2.3, and then 549 decrypt and verify the SEM analogously to the specification for 550 verifying a JWE object as describe in Section 5.2 of [I-D.ietf-jose- 551 json-web-encryption] (cf. Appendix B). In addition, the receiving 552 endpoint SHALL process the Sequence Number as described in Section 553 5.3. 555 NOTE: The explicit steps of the protection and verification procedure 556 will be included in a future version of this draft. 558 5.1.2.3 SEM Body 560 The SEM Plaintext SHALL consist of the following data, formatted as a 561 CoAP message without Header consisting of: 563 o all CoAP Options present which are marked as E in Table 3 (see 564 Appendix A), in the order as given by the Option number (each 565 Option with Option Header including delta to previous E-marked 566 Option); and 568 o the CoAP Payload, if present, and in that case prefixed by the 569 one-byte Payload Marker (0xFF). 571 The SEM Additional Authenticated Data SHALL consist of the following 572 data, in this order: 574 o the 8-bit CoAP header field Code; 576 o all CoAP options present which are marked as IP and not marked 577 as E in Table 2 (see Appendix A), in the order as given by the 578 Option number (each Option with Option Header including delta to 579 previous such Option). 581 5.1.2.4 CoAP Message with Enc Option 583 An unprotected CoAP message is encrypted and integrity protected by 584 means of an Enc option and a SEM. The structure and format of the 585 protected CoAP message being sent instead of the unprotected CoAP 586 message is now described. 588 The protected CoAP message is formatted as an ordinary CoAP message, 589 with the following Header, Options and Payload: 591 o The CoAP header SHALL be the same as the unprotected CoAP 592 message 594 o The CoAP options SHALL consist of the unencrypted options of the 595 unprotected CoAP message, and the Enc option. The options SHALL 596 be formatted as in a CoAP message (each Option with Options 597 Header including delta to previous unencrypted Option). 599 o If the unprotected CoAP message has no Payload then the Enc 600 option SHALL contain the SEM with Detached Content. If the 601 unprotected CoAP message has Payload, then the SEM option SHALL 602 be empty and the Payload of the CoAP message SHALL be the SEM 603 with Detached Content. The Payload is prefixed by the one-byte 604 Payload Marker (0xFF). 606 5.1.3 SM Tag 608 This section describes the SM Tag for Mode:COAP, which applies 609 both to SEM and SSM. The SM Tag is defined in 4.1.3. If the 610 message is a CoAP Request, then EAD SHALL be empty. If the 611 message is a CoAP Response, then EAD SHALL consist of the TID of 612 the associated CoAP Request. 614 5.2 Application Layer Protection 616 Referring to examples 1-3 in Section 2 and requirements a and b 617 in Section 3, the case of only protecting Payload sent in a 618 RESTful protocol using the Secure Message format is now 619 discussed. This is called Secure Message Mode:APPL. 621 The sending endpoint SHALL wrap the Payload, and the receiving 622 endpoint unwrap the Payload in the relevant SM format (SSM or 623 SEM) Mode:APPL. The SSM (SEM) SHALL be protected (encrypted) 624 and verified (decrypted) as described in 5.1.1.2 (5.1.2.2), 625 including replay protection as described in section 5.3. 627 NOTE: The explicit steps of the protection and verification 628 procedure will be included in a future version of this draft. 630 For Mode:APPL, the EAD SHALL be empty. Hence, the SM Tag is 631 calculated over the SM Header and SM Body. 633 A CoAP message where the Payload is wrapped as a Secure Message 634 Mode:APPL object is indicated by setting the option Content- 635 Format to application/sm. A CoAP client may request a response 636 containing such a payload wrapping by setting the option Accept 637 to application/sm. (See Section 8.) 639 5.3 Replay Protection and Freshness 641 In order to protect from replay of messages and verify freshness 642 of responses, a CoAP endpoint SHALL maintain Transaction 643 Identifiers (TIDs) of sent and received Secure Messages (see 644 section 4.1.1). 646 5.3.1 Replay Protection 648 An endpoint supporting Secure Message SHALL maintain two TIDs 649 and associated security context/key(s) for each other endpoint 650 it communicates with, one TID for protecting sent messages, and 651 one TID for verifying the received messages. Depending on use 652 case, an endpoint MAY maintain a sliding receive window for 653 Sequence Numbers associated to TIDs in received messages, 654 equivalent to the functionality described in section 4.1.2.6 of 655 [RFC6347]. 657 Before composing a new message a sending endpoint supporting 658 Secure Message SHALL step the Sequence Number of the associated 659 send TID and SHALL include it in the SM Header parameter 660 Sequence Number as defined in section 4.1.1. However, if the 661 Sequence Number counter wraps, the client must first acquire a 662 new TID and associated security context/key(s). The latter is 663 out of scope of this memo. 665 A receiving endpoint supporting Secure Message SHALL verify that 666 the Sequence Number received in the SM Header is greater than 667 the Sequence Number in the TID for received messages (or within 668 the sliding window and not previously received) and update the 669 TID (window) accordingly. 671 5.3.2 Freshness 673 If a CoAP server receives a valid Secure Message request in 674 Mode:COAP, then the response SHALL include the TID of the 675 request as EAD, as defined in section 5.1.3. If the CoAP client 676 receives a Secure Message response in Mode:COAP, then the client 677 SHALL verify the signature by reconstructing SM Body and using 678 the TID of its own associated request as EAD, as defined in 679 section 5.1.3. 681 6. Security Considerations 683 In scenarios with proxies, gateways, or caching, DTLS only 684 protects data hop-by-hop meaning that all intermediary nodes can 685 read and modify information. The trust model where all 686 participating nodes are considered trustworthy is problematic 687 not only from a privacy perspective but also from a security 688 perspective as the intermediaries are free to delete resources 689 on sensors and falsify commands to actuators (such as "unlock 690 door", "start fire alarm", "raise bridge"). Even in the rare 691 cases where all the owners of the intermediary nodes are fully 692 trusted, attacks and data breaches make such an architecture 693 weak. 695 DTLS protects the entire CoAP message including Header, Options 696 and Payload, whereas this proposal only protects selected 697 message fields. DTLS, however, also incurs a large overhead 698 cost, e.g. due to the handshake procedure. While that cost can 699 be amortized in scenarios with long lived connections, in cases 700 where a device will have connections with varying clients, using 701 secured objects instead of session security can provide a 702 significant performance gain. 704 Secure Message Mode:COAP addresses point to point encryption, 705 integrity and replay protection, and freshness of response. 706 Payload as well as relevant options and header field Code are 707 protected. It is possible to define unique session keys to 708 enable perfect forward secrecy. 710 Secure Message Mode:APPL only protects payload and only gives 711 replay protection (not freshness), but this allows more use 712 cases such as point to multi-point including publish-subscribe, 713 reverse proxies and proxy caching of responses. In case of 714 symmetric keys the receiver does not get data origin 715 authentication, which requires a digital signature using a 716 private asymmetric key. 718 Using blockwise transfer [I-D.ietf-core-coap-block], the 719 integrity protection as provided by the method described here 720 only covers the individual blocks, not the entire request or 721 response. One way to handle this would to allow the Sig or Enc 722 option to be repeatable, and in one or several of the block 723 transfer carry a MAC or signature that covers the entire request 724 or response. 726 The Version header field is not integrity protected to allow 727 backwards compatibility with future versions of CoAP. 728 Considering this, it may in theory be possible to launch a 729 cross-version attack, e.g. something analogously to a bidding 730 down attack. Future updates of CoAP would need to take this 731 into account. 733 The use of sequence numbers for replay protection introduces the 734 problem related to wrapping of the counter. The alternatives 735 also have issues: very constrained devices may not be able to 736 support accurate time or generate and store large numbers of 737 random nonces. The requirement to change key at counter wrap is 738 a complication, but it also forces the user of this 739 specification to think about implementing key renewal. 741 Independently of message format, and whether the target is 742 application layer protection or CoAP message protection, this 743 specification needs to be complemented with a procedure whereby 744 the client and the server establish the keys used for wrapping 745 and unwrapping the Secure Message. One way to address key 746 establishment is to assume that there is a trusted third party 747 which can support client and server, such as the Authorization 748 Server in [I-D.seitz-ace-problem-description]. The 749 Authorization Server may, for example, authenticate the client 750 on behalf of the server, or provide cryptographic keys or 751 credentials to the client and/or server which can be used in the 752 Secure Message exchange. 754 The security contexts required for SSM and SEM are different. 755 For a SSM, the security context is essentially Algorithm, Key 756 Identifier, Sequence Number and Key. For a SEM it is also 757 required to have a unique AEAD Initialization Vector for each 758 message. The AEAD Initialization Vector SHALL be the 759 concatenation of a Salt (8 bytes unsigned integer) and the 760 Sequence Number. The Salt SHOULD be established between sender 761 and receiver before the message is sent, to avoid the overhead 762 of sending it. For example, the Salt may be established by the 763 same means as the keys used to secure the protocol between the 764 sender and receiver. For a SEM, the security context is 765 essentially Algorithm, Key Identifier, Salt, Sequence Number and 766 Key. 768 NOTE: This last paragraph will be moved into the main document 769 in a future version of this draft. 771 7. Privacy Considerations 773 End-to-end integrity protection provides certain privacy 774 properties, e.g. protection of communication with sensor and 775 actuator from manipulation which may affect the personal sphere. 776 End-to-end encryption of payload and certain options provides 778 additional protection as to the content and nature of the 779 message exchange. 781 The headers sent in plaintext allows for example matching of CON 782 and ACK (CoAP Message Identifier), matching of request and 783 response (Token). Plaintext options could also reveal 784 information, e.g. lifetime of measurement (Max-age), or that 785 this message contains one data point in a sequence (Observe). 787 8. IANA Considerations 789 Note to RFC Editor: Please replace all occurrences of "[this 790 document]" with the RFC number of this specification. 792 The following entry is added to the CoAP Option Numbers 793 registry: 795 +--------+---------+-------------------+ 796 | Number | Name | Reference | 797 +--------+---------+-------------------+ 798 | TBD | Sig | [[this document]] | 799 +--------+---------+-------------------+ 800 | TBD | Enc | [[this document]] | 801 +--------+---------+-------------------+ 803 NOTE: IANA considerations for Mode is TBD 805 This document registers the following value in the CoAP Content 806 Format registry established by [RFC7252]. 808 Media Type: application/sm 810 Encoding: - 812 Id: 70 814 Reference: [this document] 816 9. Acknowledgements 818 Klaus Hartke has independently been working on the same problem 819 and a similar solution: establishing end-to-end security across 820 proxies by adding a CoAP option. The authors would like to 821 thank Francesca Palombini for contributing to the discussion and 822 giving helpful implementation input to the specification. We 823 are grateful to Malisa Vucinic for providing many helpful 824 comments. 826 10. References 828 10.1 Normative References 830 [I-D.ietf-jose-json-web-signature] 831 Jones, M., Bradley, J., and N. Sakimura, "JSON Web Signature 832 (JWS)", draft-ietf-jose-json-web-signature-41 (work in 833 progress), January 2015. 835 [I-D.ietf-jose-json-web-encryption] 836 Jones, M., and J. Hildebrand, "JSON Web Encryption (JWE)", 837 draft-ietf-jose-json-web-encryption-40 (work in progress), 838 January 2015. 840 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 841 Requirement Levels", BCP 14, RFC 2119, March 1997, 842 . 844 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 845 Security Version 1.2", RFC 6347, January 2012, 846 . 848 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 849 Application Protocol (CoAP)", RFC 7252, June 2014, 850 . 852 10.2 Informative References 854 [I-D.seitz-ace-problem-description] 855 Seitz, L., and G. Selander, "Problem Description for 856 Authorization in Constrained Environments", draft-seitz- 857 ace-problem-description-02 (work in progress), May 2015. 859 [I-D.ietf-ace-usecases] 860 Seitz, L., Gerdes, S., Selander, G., Mani, M., and S. 861 Kumar, "ACE use cases", draft-ietf-ace-usecases-02 (work 862 in progress), February 2015. 864 [I-D.bormann-jose-cose] 865 Bormann, C., "Constrained Object Signing and Encryption 866 (COSE)", draft-bormann-jose-cose-00 (work in progress, 867 October 2014 869 [I-D.ietf-core-coap-block] 870 Bormann, C., and Z. Shelby, "Blockwise transfers in CoAP", 871 draft-ietf-core-block-17 (work in progress), March 2015. 873 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", FYI 874 36, RFC 4949, August 2007, . 877 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 878 RFC 5652, September 2009, . 881 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 882 Constrained-Node Networks", RFC 7228, May 2014, 883 . 885 [RFC7231] Fielding, R., Ed., and J. Reschke, Ed., "Hypertext 886 Transfer Protocol (HTTP/1.1): Semantics and Content", 887 RFC 7231, June 2014, . 890 [RFC7258] Farrell, S. and H. Tschofenig, "Pervasive Monitoring Is an 891 Attack", BCP 188, RFC 7258, May 2014, . 894 Appendix A. Which CoAP Header Fields and Options to Protect 896 In the case of CoAP Message Protection (Mode:COAP) as much as 897 possible of the CoAP message is protected. However, not all CoAP 898 header fields or options can be encrypted and integrity protected, 899 because some are intended to be read or changed by an intermediary 900 node. 902 A.1 CoAP Header Fields 904 The CoAP Message Layer parameters, Type and Message ID, as well as 905 Token and Token Length may be changed by a proxy and thus SHALL 906 neither be integrity protected nor encrypted. Example 5 in Section 2 907 shows that the Code SHALL be integrity protected. The Version 908 parameter SHALL neither be integrity protected nor encrypted (see 909 Section 6). 911 A.2 CoAP Options 912 This section describes what options need to be integrity protected 913 and encrypted. On a high level, all CoAP options must be encrypted 914 by default, unless intended to be read by an intermediate node; and 915 integrity protected, unless intended to be changed by an intermediate 916 node. 918 However, some special considerations are necessary because CoAP 919 defines certain legitimate proxy operations, because the security 920 information itself may be transported as an option, and because 921 different processing is performed for SSM and SEM. 923 A.2.1 Integrity Protection 925 As a general rule, CoAP options which are Safe-to-Forward SHALL be 926 integrity protected, with the only exception being Enc and Sig, which 927 are the security-providing options. 929 The Unsafe options are divided in two categories, those that are 930 intended to change in a way that can be reconstructed by the server, 931 and those which are not. The following options are of the latter 932 kind and SHALL NOT be integrity protected: Max-Age, Observe, Proxy- 933 Scheme. These options are intended to be changed by a proxy. 935 For options related to URI of resource (Uri-Host, Uri-Port, Uri-Path, 936 Uri-Query, Proxy-Uri) a Forward Proxy is intended to replace the Uri- 937 * options with the content of the Proxy-Uri option. These options 938 are Unsafe, but the Forward Proxy is intended to perform this precise 939 operation and we can use this predictability to integrity protect the 940 destination endpoint URI, even if the options where the information 941 elements of the URI is located is changed by the Proxy. 943 This memo makes the full URI located in option 35 (Proxy-Uri) into a 944 common denominator for the URI integrity, as described in the 945 following. The following processing applies to a SSM, for SEM see 946 next section: 948 o If there is a Proxy-Uri present, then the client MUST integrity 949 protect the Proxy-Uri option and the Uri-* options MUST NOT be 950 integrity protected. 952 o If there is no Proxy-Uri option present, then the client SHALL 953 compose the full URI from Uri-* options according to the method 954 described in section 6.5 of [RFC7252]. The SM Tag is calculated 955 on the following message, modified compared to what is sent: 957 o All Uri-* options removed 959 o A Proxy-Uri option with the full URI included 961 The server SHALL compose the URI from the Uri-* options according to 962 the method described in section 6.5 of [RFC7252]. The so obtained 963 URI is placed into a Proxy-Uri option (no. 35), which is included in 964 the integrity verification. 966 A.2.2 Encryption 968 All CoAP options MUST be encrypted, except the options below which 969 MUST NOT be encrypted: 971 o Max-Age, Observe: This information is intended to be read by a 972 proxy. 974 o Enc, Sig: These are the security-providing options. 976 o Uri-Host, Uri-Port: This information can be inferred from 977 destination IP address and port. 979 o Proxy-Uri, Proxy-Scheme: This information is intended to be 980 read by a proxy. 982 In the case of a SEM, the Proxy-Uri MUST only contain Uri-Host and 983 Uri-Port and MUST NOT contain Uri-Path and Uri-Query because the 984 latter options are not intended to be revealed to a Forward Proxy. 986 A.2.3 Summary 988 Table 3 summarizes which options are encrypted and integrity 989 protected, if present. 991 In a SSM, options marked with "a" and "b" are composed into a URI as 992 described above and included as the Proxy-Uri option which is part of 993 the SSM Body. In a SEM, options marked "a" are composed into a URI 994 as described above and included as the Proxy-Uri option in the SEM 995 Additional Authenticated Data. 997 +-----+---+---+---+---+----------------+--------+--------+--------+ 998 | No. | C | U | N | R | Name | Format | Length | E | IP | 999 +-----+---+---+---+---+----------------+--------+--------+--------+ 1000 | 1 | x | | | x | If-Match | opaque | 0-8 | x | x | 1001 | 3 | x | x | - | | Uri-Host | string | 1-255 | | a | 1002 | 4 | | | | x | ETag | opaque | 1-8 | x | x | 1003 | 5 | x | | | | If-None-Match | empty | 0 | x | x | 1004 | 6 | | x | - | | Observe | uint | 0-3 | | | 1005 | 7 | x | x | - | | Uri-Port | uint | 0-2 | | a | 1006 | 8 | | | | x | Location-Path | string | 0-255 | x | x | 1007 | 11 | x | x | - | x | Uri-Path | string | 0-255 | x | b | 1008 | 12 | | | | | Content-Format | uint | 0-2 | x | x | 1009 | 14 | | x | - | | Max-Age | uint | 0-4 | | | 1010 | 15 | x | x | - | x | Uri-Query | string | 0-255 | x | b | 1011 | 17 | x | | | | Accept | uint | 0-2 | x | x | 1012 | 20 | | | | x | Location-Query | string | 0-255 | x | x | 1013 | 35 | x | x | - | | Proxy-Uri | string | 1-1034 | | x | 1014 | 39 | x | x | - | | Proxy-Scheme | string | 1-255 | | | 1015 | 60 | | | x | | Size1 | uint | 0-4 | x | x | 1016 +-----+---+---+---+---+----------------+--------+--------+--------+ 1018 C=Critical, U=Unsafe, N=NoCacheKey, R=Repeatable, 1019 E=Encrypt, IP=Integrity Protect. 1021 Table 3: Protected CoAP options in Mode=COAP. 1023 Appendix B. JOSE Objects as Secure Messages 1025 This section shows how to extend JWS and JWE to Secure Message 1026 formats (see Section 4.1). The use of compact serialization is 1027 assumed. 1029 B.1 JWS as Secure Signed Message 1031 The JOSE Header of JWS contains the mandatory parameter "alg", 1032 defined in Section 4.1.1 of [I-D.ietf-jose-json-web-signature], which 1033 corresponds to the parameter Algorithm of the Secure Message. 1035 A JWS is a Secure Message if the JOSE Header includes 1037 o the Parameter "kid" defined in Section 4.1.4 of [I-D.ietf-jose- 1038 json-web-signature]; 1040 o the new Parameter "seq" defined in B.3; and 1042 o the new Parameter "mod" defined in B.4. 1044 In case of JWS, a SSM with Detached Content consists of the JOSE 1045 Header and JWS Signature; i.e. no JWS Payload. 1047 B.2 JWE as Secure Encrypted Message 1049 In case of JWE, the SM Header parameters of a JWE consists of the 1050 JOSE Header Parameters and JWE Initialization Vector (IV). 1052 The JOSE Header of JWE contains the mandatory parameter "enc", 1053 defined in Section 4.1.2 of [I-D.ietf-jose-json-web-encryption], 1054 which corresponds to the parameter Algorithm of the Secure Message. 1055 The JOSE Header also contains the mandatory parameter "alg", the key 1056 encryption algorithm, which in the current version of the draft is 1057 assumed to be equal to "dir" (constant). It is also assumed that 1058 plaintext compression (zip) is not used. 1060 A JWE is a Secure Message if the IV contains the SM Sequence Number, 1061 and the JOSE Header includes 1063 o the Parameter "kid" defined in Section 4.1.4 of [I-D.ietf-jose- 1064 json-web-signature]; and 1066 o the new Parameter "mod" defined in B.4. 1068 The IV also contain a Salt (see Section 6). For JWE it is mandatory 1069 to include the IV and hence the Salt is sent in each message. 1071 In case of JWE, a SEM with Detached Content consists of JOSE Header, 1072 JWE Initialization Vector, JWE Ciphertext and JWE Authentication Tag; 1073 i.e. no JWE AAD. 1075 B.3 "seq" (Sequence Number) Header Parameter 1077 The Sequence Number SHALL be a 64-bit unsigned integer in hexadecimal 1078 representation. Only the significant bytes are sent (initial bytes 1079 with zeros are removed). The start sequence number SHALL be 0. For 1080 a given key, any Sequence Number MUST NOT be used more than once. 1082 The parameter "seq" SHALL be marked as critical using the "crit" 1083 header parameter (see section 4.1.11 of [I-D.ietf-jose-json-web- 1084 signature]), meaning that if a receiver does not understand this 1085 parameter it must reject the message. 1087 B.4 "mod" (Mode) Header Parameter 1089 The Mode parameter SHALL be an 8-byte unsigned integer defining 1090 application specific message format, content and processing. The 1091 parameter "mod" SHALL be marked as critical. "mod":"0" indicates 1092 Mode:APPL which is defined in Section 5.2. "mod":"1" indicates 1093 Mode:COAP which is defined in Section 5.1. 1095 B.4 The TID consists of the concatenation of SEQ and KID, in that order, 1096 formatted as in the JOSE. For "seq" the initial bytes with zeros are 1097 removed. 1099 Appendix C. Compact Secure Message 1101 For constrained environments it is important that the message 1102 expansion due to security overhead is kept at a minimum. As an 1103 attempt to assess what this minimum expansion could be, an optimized 1104 Secure Message format is defined, tailor-made for this setting. This 1105 is intended as a benchmark for generic content formats, to allow an 1106 informed decision about which Secure Message format to mandate in a 1107 future version of this draft. 1109 C.1 CSM Format 1111 This section defines a compact Secure Message format (see Section 1112 4.1) called the Compact Secure Message (CSM) format, see 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 | M | ALG | KL | SL | KID ~ 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, Key Identifier 1130 (KID) and Sequence Number (SEQ). The Header parameters are (compare 1131 Table 5): 1133 o Mode (M). M=0 indicates Mode:APPL as defined in Section 5.2. 1134 M=1 indicates Mode:COAP as defined in Section 5.1. M=2 and M=3 1135 are reserved for future use. 1137 o Algorithm (ALG). This parameter consists of an encoding of the 1138 ciphersuite used in the Secure Message. The encoding is TBD. 1140 o KID Length (KL). This parameter consist of a length indication 1141 of the header parameter Key Identifier. The actual length of 1142 KID is KL + 1 bytes. 1144 o SEQ Length (SL). This parameter consist of a length indication 1145 of the header parameter Sequence Number. The actual length of 1146 SEQ is SL + 1 bytes. 1148 o Key Identifier (KID). This parameter identifies the key(s) used 1149 to protect the Secure Message. Only the significant bytes are 1150 sent (initial bytes with zeros are removed). 1152 o Sequence Number (SEQ). This parameter consists of the sequence 1153 number used by the sender of the Secure Message. Only the 1154 significant bytes are sent (initial bytes with zeros are 1155 removed). 1157 +------+-------------------------+--------------------+ 1158 | Name | Parameter | Length | 1159 +------+-------------------------+--------------------+ 1160 | M | Mode | 2 bits | 1161 +------+-------------------------+--------------------+ 1162 | ALG | Algorithm | 6 bits | 1163 +------+-------------------------+--------------------+ 1164 | KL | Key Identifier Length | 5 bits | 1165 +------+-------------------------+--------------------+ 1166 | SL | Sequence Number Length | 3 bits | 1167 +------+-------------------------+--------------------+ 1168 | KID | Key Identifier | KL + 1: 1-32 bytes | 1169 +------+-------------------------+--------------------+ 1170 | SEQ | Sequence Number | SL + 1: 1-8 bytes | 1171 +------+-------------------------+--------------------+ 1173 Table 5: CSM Header Parameters. 1174 The minimum CSM Header is 4 bytes. 1176 The TID consists of the concatenation of SEQ and KID, in that order, 1177 formatted as in the CSM format (initial bytes with zeros are 1178 removed). 1180 The content of CSM Body depends on whether it is a SSM or a SEM (see 1181 Section 4.1.2) which is determined by the Algorithm. This version of 1182 the draft focuses on Secure Message with Detached Content. Hence, 1183 the SSM Body is empty and the SEM Body consists of the Ciphertext. 1184 In the former case, the length of the CSM Body is 0. In the latter 1185 case, the length of the CSM Body equals the sum of the lengths of the 1186 present CoAP options marked encrypted in Table 3 and the length of 1187 the payload of the unprotected CoAP message. 1189 The CSM Tag contains the MAC/Signature as determined from the 1190 Algorithm. The length is determined by ALG. 1192 C.2 Comparison of Secure Message sizes 1194 This section gives some examples of overhead incurred with JOSE, the 1195 current proposal for COSE at the time of writing (00-draft), and CSM. 1196 The goal is not to give exact measurements, but to help the reader 1197 appreciate the rough order of magnitude of the overhead involved. 1198 COSE seems to be the most promising approach and CSM should be viewed 1199 as an attempt to define a lower bound for COSE. 1201 The comparison is complicated further by the fact that algorithms 1202 suitable for constrained environments are not supported by JOSE, and 1203 thereby not by COSE. This comparison does not consider the 1204 ciphertext or signed payload expansion due to Base64url encoding in 1205 JWS/JWE. This would increase the overhead of JWS and JWE even more. 1207 The size of the header is shown separately from the size of the 1208 authentication tag, since JWS/JWE has no provisions for truncating 1209 it, a feature that could easily be added to the JOSE specifications. 1210 For CSM the encoding of certain additional algorithms is assumed and 1211 this could also easily be added to COSE. An 8-byte kid is used 1212 throughout all examples. Finally compact serialization for both JWS 1213 and JWE is assumed. 1215 SSM uses HMAC-SHA256, with truncation to 16 bytes. 1217 For JWS the following header is used: 1219 {"alg":"HS256", "kid":"a1534e3c5fdc09bd", "seq":"00000142", 1220 "mod":"0"} 1222 which encodes to a size of 90 bytes in Base64url, and the 32 bytes of 1223 HS256 MAC encode to 43 bytes. The concatenation marks add 2 bytes to 1224 that in the total overhead. 1226 The same header in COSE, representing the "kid" as bytes (not as 1227 string) and the "seq" as positive integer encodes to a size of 35 1228 bytes, and the MAC would add to 32 bytes to that. Note that encoding 1229 the header and the MAC together incurs an additional overhead of 3 1230 bytes. 1232 For CSM the same header is represented by 12 bytes. The MAC could in 1233 this case safely be truncated to 16 bytes, and a corresponding 1234 algorithm identifier would need to be defined in the list of 1235 supported algorithms. 1237 Table 6 summarizes these results. 1239 +--------+----------------+----------------+ 1240 | Scheme | Header | MAC | Total Overhead | 1241 +--------+----------------+----------------+ 1242 | JWS | 90 B | 43 B | 135 bytes | 1243 +--------+---------+------+----------------+ 1244 | COSE | 35 B | 32 B | 70 bytes | 1245 +--------+---------------------------------+ 1246 | CSM | 12 B | 16 B | 28 bytes | 1247 +--------+---------------------------------+ 1249 Table 6: Comparison of JWS, COSE, and CSM 1251 For SEM the use of AES-128-CCM-8 would be ideal, but since this is 1252 not supported by JOSE, AES-128-GCM is used there instead. 1254 For JWE it is assumed that the IV is generated from the sequence 1255 number and some previously agreed upon Salt. This means it is not 1256 required to explicitly send the IV in the CSM format, but also that 1257 the JWE and COSE formats can omit the sequence number. 1259 The JWE header 1261 {"alg":"dir", "kid":"a1534e3c5fdc09bd", "enc":"A128GCM", "mod":"0"} 1263 encodes to a size of 86 bytes in Base64url, while the necessary 12 1264 byte IV for GCM mode is expanded to 16 bytes by encoding. The 16 1265 bytes of the authentication tag expand to 22 bytes. The 1266 concatenation marks add 3 bytes to the total overhead. 1268 In COSE the same header encodes to 40 bytes and the IV and 1269 authentication tag could be represented as 12 and 16 bytes 1270 respectively. Note that encoding the header, the IV and the 1271 authentication tag together incurs an additional overhead of 2 bytes. 1273 For CSM this tests uses CCM mode instead of GCM. CCM requires a 16 1274 byte IV, but is better suited for constrained devices, and for CSM 1275 there is no impact since the IV can be deduced from the sequence 1276 number and a previously agreed upon Salt. The corresponding header 1277 for AES-128-CCM-8, including the 8 byte sequence number, is 1278 represented by 12 bytes. 1280 Table 7 summarizes these results. 1282 +--------+----------------+-------+----------------+ 1283 | Scheme | Header | IV | Tag | Total Overhead | 1284 +--------+----------------+-------+----------------+ 1285 | JWE | 86 B | 16 B | 22 B | 127 bytes | 1286 +--------+---------+------+-------+----------------+ 1287 | COSE | 40 B | 12 B | 16 B | 70 bytes | 1288 +--------+------------------------+----------------+ 1289 | CSM | 12 B | 0 B | 8 B | 20 bytes | 1290 +--------+------------------------+----------------+ 1292 Table 7: Comparison of JWE, COSE, and CSM 1294 Appendix D. Examples 1296 This section gives examples of how to use the new options and message 1297 formats defined in this memo. 1299 D.1 CoAP Message Protection 1301 This section illustrates the Secure Message Mode:COAP. The message 1302 exchange assumes there is a security context established between 1303 client and server. One key is used for each direction of the 1304 message transfer. The intermediate node detects that the CoAP 1305 message contains a SM Mode:COAP object (Sig or Enc option is set) and 1306 thus forwards the message as it cannot serve a cached response. 1308 D.1.1 Integrity protection of CoAP Message 1310 Here is an example of a PUT request/response message exchange passing 1311 an intermediate node protected with the Sig option. The example 1312 illustrates a client opening a lock and getting a confirmation that 1313 the lock is opened. Code, Uri-Path and Payload are integrity 1314 protected (see Appendix A). 1316 Client Proxy Server 1317 | | | 1318 | | | 1319 | | | 1320 +----->| | Code: 0.03 (PUT) 1321 | PUT | | Token: 0x8c 1322 | | | Uri-Path: lock 1323 | | | Sig: SSM {"mod"="1","seq":"00000142", 1324 | | | "kid":"a1534e3c5fdc09bd", ...} 1325 | | | Payload: 1 1326 | | | 1327 | +----->| Code: 0.03 (PUT) 1328 | | PUT | Token: 0x7b 1329 | | | Uri-Path: lock 1330 | | | Sig: SSM {"mod"="1","seq":"00000142", 1331 | | | "kid":"a1534e3c5fdc09bd", ...} 1332 | | | Payload: 1 1333 | | | 1334 | | | 1335 | |<-----+ Code: 2.04 (Changed) 1336 | | 2.04 | Token: 0x7b 1337 | | | Sig: SSM {"mod"="1","seq":"000000a6", 1338 | | | "kid":"5fdc09bda1534e3c", ...} 1339 | | | 1340 |<-----+ | Code: 2.04 (Changed) 1341 | 2.04 | | Token: 0x8c 1342 | | | Sig: SSM {"mod"="1","seq":"000000a6", 1343 | | | "kid":"5fdc09bda1534e3c", ...} 1344 | | | 1346 Figure 8: CoAP PUT protected with Sig/SSM (Mode:COAP) 1348 The Key Identifier is a hint to the receiver indicating which 1349 security context was used to integrity protect the message, and may 1350 be used as an identifier for a secret key or a public key. (It may 1351 e.g. be the hash of a public key.) 1353 The server and client can verify that the Sequence Number has not 1354 been received and used with this key before, and since Mode is COAP, 1355 the client can additionally verify the freshness of the response, 1356 i.e. that the response message is generated as an answer to the 1357 received request message (see Section 5.3). 1359 The SSM also contains the Tag as specified in the Algorithm (not 1360 shown). 1362 This example deviates from encryption (SEM) by default (see Section 1363 6) just to illustrate the Sig option. If there is no compelling 1364 reason why the CoAP message should be in plaintext, then the Enc 1365 option must be used. 1367 D.1.2 Encryption of CoAP Message 1369 Here is an example of a GET request/response message exchange passing 1370 an intermediate node protected with the Enc option. The example 1371 illustrates a client requesting a blood sugar measurement resource 1372 (GET /glucose) and receiving the value 220 mg/dl. Uri-Path and 1373 Payload are encrypted and integrity protected. Code is integrity 1374 protected only (see Appendix A). 1376 Client Proxy Server 1377 | | | 1378 | | | 1379 | | | 1380 +----->| | Code: 0.01 (GET) 1381 | GET | | Token: 0x83 1382 | | | Enc: SEM {"mod"="1","seq":"000015b7", 1383 | | | "kid":"34e3c5fdca1509bd", 1384 | | | ["glucose" ... ], ...} 1385 | | | 1386 | +----->| Code: 0.01 (GET) 1387 | | GET | Token: 0xbe 1388 | | | Enc: SEM {"mod"="1","seq":"000015b7", 1389 | | | "kid":"34e3c5fdca1509bd", 1390 | | | ["glucose" ... ], ...} 1391 | | | 1392 | | | 1393 | |<-----+ Code: 2.05 (Content) 1394 | | 2.05 | Token: 0xbe 1395 | | | Enc: 1396 | | | Payload: SEM {"mod"="1","seq":"000015b7", 1397 | | | "kid":"c09bda155fd34e3c", 1398 | | | [... 220], ...} 1399 | | | 1400 |<-----+ | Code: 2.05 (Content) 1401 | 2.05 | | Token: 0x83 1402 | | | Enc: 1403 | | | Payload: SEM {"mod"="1","seq":"000015b7", 1404 | | | "kid":"c09bda155fd34e3c", 1405 | | | [... 220], ...} 1406 | | | 1408 Figure 9: CoAP GET protected with Enc/SEM (Mode:COAP). 1409 The bracket [ ... ] indicates encrypted data. 1411 Since the request message (GET) does not support payload, the SEM is 1412 carried in the Enc option. Since the response message (Content) 1413 supports payload, the Enc option is empty and the SEM is carried in 1414 the payload. 1416 The Key Identifier is a hint to the receiver indicating which 1417 security context was used to encrypt and integrity protect the 1418 message, and may be used as an identifier for the AEAD secret key. 1419 One key is used for each direction of the message transfer. 1421 The server and client can verify that the Sequence Number has not 1422 been received and used with this key before, and since Mode:COAP the 1423 client can additionally verify the freshness of the response, i.e. 1424 that the response message is generated as an answer to the received 1425 request message (see Section 5.3). 1427 The SEM also contains the Tag as specified by the Algorithm (not 1428 shown). 1430 D.2 Application Layer Protection 1432 This section gives examples that illustrate Secure Message Mode:APPL. 1433 This mode assumes that only the intended receiver(s) has the 1434 relevant security context related to the resource. 1436 D.2.1 Proxy Caching 1438 This example outlines how a proxy forwarding request and response of 1439 one client can cache a response whose payload is a SEM object, and 1440 serve this response to another client request, such that both clients 1441 can verify integrity and non-replay. 1443 Client1 Proxy Server 1445 | | | 1446 | | | 1447 +----->| | Code: 0.01 (GET) 1448 | GET | | Token: 0x83 1449 | | | Proxy-Uri: example.com/temp 1450 | | | 1451 | | | 1452 | +----->| Code: 0.01 (GET) 1453 | | GET | Token: 0xbe 1454 | | | Uri-Host: example.com 1455 | | | Uri-Path: temp 1456 | | | 1457 | | | 1458 | |<-----+ Code: 2.05 (Content) 1459 | | 2.05 | Token: 0xbe 1460 | | | Payload: SEM {"mod"="0","seq":"000015b7", 1461 | | | "kid":"c09bda155fd34e3c", 1462 | | | ["471 F"], ...} 1463 | | | 1464 |<-----+ | Code: 2.05 (Content) 1465 | 2.05 | | Token: 0x83 1466 | | | Payload: SEM {"mod"="0","seq":"000015b7", 1467 | | | "kid":"c09bda155fd34e3c", 1468 | | ["471 F"], ...} 1469 Client2 | | 1470 | | 1471 | | | 1472 | | | 1473 +----->| | Code: 0.01 (GET) 1474 | GET | | Token: 0xa1 1475 | | | Proxy-Uri: example.com/temp 1476 | | | 1477 |<-----+ | Code: 2.05 (Content) 1478 | 2.05 | | Token: 0xa1 1479 | | | Payload: SEM {"mod"="0","seq":"000015b7", 1480 | | | "kid":"c09bda155fd34e3c", 1481 | | | ["471 F"], ...} 1483 Figure 10: Proxy caching protected with SEM (Mode:APPL) 1485 D.2.2 Publish-Subscribe 1487 This example outlines a publish-subscribe setting where the payload 1488 is integrity and replay protected end-to-end between Publisher and 1489 Subscriber. The example illustrates a subscription registration and 1490 a new publication of birch pollen count of 300 per cubic meters. The 1491 PubSub Broker can define the Observe count arbitrarily (as could any 1492 intermediary node, even in Mode:COAP), but cannot manipulate the 1493 Sequence Number without being noticed. 1495 Sub- PubSub- Publisher 1496 scriber Broker 1498 | | | 1499 +----->| | Code: 0.01 (GET) 1500 | GET | | Token: 0x72 1501 | | | Uri-Path: ps 1502 | | | Uri-Path: birch-pollen 1503 | | | Observe: 0 (register) 1504 | | | 1505 | | | 1506 |<-----+ | Code: 2.05 (Content) 1507 | 2.05 | | Token: 0x72 1508 | | | Observe: 1 1509 | | | Payload: SSM {"mod"="0","seq":"000015b7", 1510 | | | "kid":"c09bda155fd34e3c", 1511 | | | ["270"], ...} 1512 | | | 1513 | | | 1514 | | | 1515 | |<-----+ Code: 0.03 (PUT) 1516 | | PUT | Token: 0x1f 1517 | | | Uri-Path: ps 1518 | | | Uri-Path: birch-pollen 1519 | | | Payload: SSM {"mod"="0","seq":"000015b8", 1520 | | | "kid":"c09bda155fd34e3c", 1521 | | | ["300"], ...} 1522 | | | 1523 | +----->| Code: 2.04 (Changed) 1524 | | 2.04 | Token: 0x1f 1525 | | | 1526 | | | 1527 |<-----+ | Code: 2.05 (Content) 1528 | 2.05 | | Token: 0x72 1529 | | | Observe: 2 1530 | | | Payload: SSM {"mod"="0","seq":"000015b8", 1531 | | | "kid":"c09bda155fd34e3c", 1532 | | | ["300"], ...} 1534 Figure 11: Publish-subscribe protected with SSM (Mode:APPL) 1536 This example deviates from encryption (SEM) by default (see Section 1537 6) just to illustrate the SSM in Mode:APPL. If there is no 1538 compelling reason why the payload should be in plaintext, then SEM 1539 must be used. 1541 D.2.3 Transporting Authorization Information 1543 This example outlines the transportation of authorization information 1544 from a node producing (Authorization Server, AS) to a node consuming 1545 (Resource Server, RS) such information. Authorization information 1546 may for example be an authorization decision with respect to a Client 1547 (C) accessing a Resource to be enforced by RS. See Section 4.4-4.5 1548 of [I-D.seitz-ace-problem-description]. 1550 Here, C is clearly not trusted with modifying the information, but 1551 may need to be involved with mediating the authorization information 1552 to the RS, for example, because AS and RS does not have direct 1553 connectivity. So end-to-end security is required and object security 1554 is a natural candidate (cf. "Access Tokens"). 1556 This example considers the authorization information to be 1557 encapsulated in a SEM Mode:APPL object, generated by AS. How C 1558 accesses the SSM is out of scope for this example, it may e.g. be 1559 using CoAP. C then requests RS to configure the authorization 1560 information in the SEM by doing PUT to /authorization. This 1561 particular resource has a default access policy that only new 1562 messages signed by AS are authorized. RS thus verifies the integrity 1563 and sequence number by using the existing security context for the 1564 AS, and responds accordingly, a) or b), see Figure 12. 1566 Authz Resource 1567 Server Client Server 1568 | | | 1569 | | | Client access Access Token: 1570 +- - ->| | SEM {"mod"="0","seq":"00000142", 1571 | | | "kid":"c09bda1534e3c5fdc09bd", ...} 1572 | | | 1573 | | | 1574 | +----->| Code: 0.03 (PUT) 1575 | | PUT | Token: 0xac 1576 | | | Uri-Path: authorization 1577 | | | Payload: SEM {"mod"="0","seq":"00000142", 1578 | | | "kid":"c09bda1534e3c5fdc09bd", ...} 1580 a) 1581 | | | 1582 | |<-----+ Code: 2.04 (Changed) 1583 | | 2.04 | Token: 0xac 1584 | | | 1586 b) 1587 | | | 1588 | |<-----+ Code: 4.01 (Unauthorized) 1589 | | 4.01 | Token: 0xac 1590 | | | 1592 Figure 12: Protected Transfer of Access Token = SEM (Mode:APPL) 1594 Authors' Addresses 1596 Goeran Selander 1597 Ericsson 1598 Farogatan 6 1599 16480 Kista 1600 SWEDEN 1601 EMail: goran.selander@ericsson.com 1603 John Mattsson 1604 Ericsson 1605 Farogatan 6 1606 16480 Kista 1607 SWEDEN 1608 EMail: john.mattsson@ericsson.com 1610 Ludwig Seitz 1611 SICS Swedish ICT AB 1612 Scheelevagen 17 1613 22370 Lund 1614 SWEDEN 1615 EMail: ludwig@sics.se