idnits 2.17.1 draft-selander-ace-object-security-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (October 27, 2014) is 3440 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) == Unused Reference: 'I-D.seitz-ace-problem-description' is defined on line 615, but no explicit reference was found in the text == Outdated reference: A later version (-41) exists of draft-ietf-jose-json-web-signature-36 ** Obsolete normative reference: RFC 6347 (Obsoleted by RFC 9147) == Outdated reference: A later version (-03) exists of draft-seitz-ace-problem-description-01 == Outdated reference: A later version (-02) exists of draft-seitz-ace-usecases-01 == Outdated reference: A later version (-17) exists of draft-ietf-core-http-mapping-05 == Outdated reference: A later version (-21) exists of draft-ietf-core-block-15 == Outdated reference: A later version (-08) exists of draft-ietf-jose-cookbook-05 == Outdated reference: A later version (-16) exists of draft-ietf-core-observe-14 -- Obsolete informational reference (is this intentional?): RFC 7231 (Obsoleted by RFC 9110) Summary: 1 error (**), 0 flaws (~~), 9 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: April 30, 2015 L. Seitz 6 SICS Swedish ICT 8 October 27, 2014 10 Object Security for CoAP 11 draft-selander-ace-object-security-00 12 Abstract 14 We present a format for data object security in Constrained 15 Application Protocol CoAP, i.e. protection of individual request and 16 response messages between client and server. 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) 2014 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. The JWS Option . . . . . . . . . . . . . . . . . . . . . . . . 6 60 3.1 Option Structure . . . . . . . . . . . . . . . . . . . . . . 6 61 3.2 Integrity Protection and Verification . . . . . . . . . . . 7 62 3.3 JOSE Header . . . . . . . . . . . . . . . . . . . . . . . . 7 63 3.3.1 "seq" (Sequence Number) Header Parameter . . . . . . . . 8 64 3.3.2 Message Sequence Numbers . . . . . . . . . . . . . . . . 8 65 3.4 JWS Payload . . . . . . . . . . . . . . . . . . . . . . . . 9 66 4. Proxy Behavior . . . . . . . . . . . . . . . . . . . . . . . . 10 67 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 68 5.1 GET . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 69 5.2 POST . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 70 6. Security Considerations . . . . . . . . . . . . . . . . . . . . 13 71 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . . 14 72 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 73 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 14 74 9.1 Normative References . . . . . . . . . . . . . . . . . . . 14 75 9.2 Informative References . . . . . . . . . . . . . . . . . . 15 76 Appendix A. Design Considerations . . . . . . . . . . . . . . . . 16 77 A.1 Reducing Message Size . . . . . . . . . . . . . . . . . . . 16 78 A.2 REST Considerations . . . . . . . . . . . . . . . . . . . . 17 79 A.3 Protection of CoAP Message Fields . . . . . . . . . . . . . 17 80 A.3.1 CoAP Header . . . . . . . . . . . . . . . . . . . . . . 18 81 A.3.2 CoAP Options . . . . . . . . . . . . . . . . . . . . . . 18 82 Appendix B. Replay Protection - Special Cases . . . . . . . . . . 20 83 B.1 "isi" (Integrity Scope Indication) Header Parameter . . . . 21 84 B.1.1 "isi":"01" . . . . . . . . . . . . . . . . . . . . . . . 21 85 B.1.2 "isi":"10" . . . . . . . . . . . . . . . . . . . . . . . 21 86 B.1.3 "isi":"11" . . . . . . . . . . . . . . . . . . . . . . . 21 87 B.1.4 "isi":"00" . . . . . . . . . . . . . . . . . . . . . . . 22 88 B.2 Advance Caching . . . . . . . . . . . . . . . . . . . . . . 22 89 B.2.1 Acquiring server sequence numbers . . . . . . . . . . . 22 90 B.2.2 Proxy caching . . . . . . . . . . . . . . . . . . . . . 23 91 B.3 Observe . . . . . . . . . . . . . . . . . . . . . . . . . . 24 92 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 25 94 1. Introduction 96 The Constrained Application Protocol CoAP [RFC7252] was designed with 97 a constrained RESTful environment in mind. CoAP references DTLS 98 [RFC6347] for securing the message exchange. However, transport 99 layer security is problematic in use cases built on store-and-forward 100 or publish-subscribe, which require end-to-end security. DTLS offers 101 only hop-by-hop security and requires trusted intermediaries. 102 Moreover DTLS incurs a noticeable overhead in constrained devices due 103 to the handshake procedure. 105 This memo presents an object security approach for secure messaging 106 in constrained environments based on the protection of individual 107 request and response messages. 109 In this version of the draft we focus on end-to-end integrity 110 protection, which addresses some of the use cases e.g. where it is 111 necessary for endpoints or proxies to verify that the message is 112 authentic. We plan to add encryption in a later version since this 113 is essential for other use cases. 115 1.1 Terminology 117 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 118 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 119 document are to be interpreted as described in [RFC2119]. These 120 words may also appear in this document in lowercase, absent their 121 normative meanings. 123 Certain security-related terms are to be understood in the sense 124 defined in RFC 4949 [RFC4949]. These terms include, but are not 125 limited to, "authentication", "authorization", "confidentiality", 126 "(data) integrity", "message authentication code", "signature", and 127 "verify". 129 RESTful terms including "resource", "representation", etc. are to be 130 understood as used in HTTP [RFC7231] and CoAP [RFC7252]. 132 Terminology for constrained environments including "constrained 133 device", "constrained-node network", "class 1", etc. are defined in 134 [RFC7228]. 136 Client, Resource Server, and Authorization Server are defined in [I- 137 D.seitz-ace-problem-description]. When we just use the term server, 138 we refer to the Resource Server. 140 JSON Web Signature (JWS), JOSE Header, JWS Payload, and JWS Signature 141 are defined in [I-D.ietf-jose-json-web-signature]. 143 NOTE: A CoAP message has header, options and payload. A JWS object 144 has header, payload, and signature. Hence the unqualified terms 145 "header" and "payload" have two meanings. 147 The JWS option is a CoAP option defined in this memo. 149 2. Background 151 The background for this work is provided by the use cases and problem 152 description in [I-D.seitz-ace-usecases] and [I-D.seitz-ace-problem- 153 description]. The specific part of the problem statement we address 154 in this memo relates to sections 4.6 - 4.7 of [I-D.seitz-ace-problem- 155 description]. 157 The overall objective in securing access requests is that only 158 authorized requests are granted and that the message content is 159 protected (according to requirements of the particular use case) 160 between client and server. As explained in the introduction, we are 161 focusing on an efficient solution to protect requests and response 162 end-to-end in constrained environments supporting e.g. store-and- 163 forward use cases. To give a few examples, end-to-end integrity 164 protection can be used to: 166 o prevent manipulation and allow multiple clients to verify sensor 167 readings stored in un-trusted intermediary nodes; 169 o protect configuration data or firmware updates stored in an 170 intermediate node, e.g. because the device was not connected at 171 the time of the update request; 173 o protect transport of authorization information ("access tokens") 174 to sleepy devices. 176 The IETF has defined standardized content formats for 177 cryptographically protected data (e.g. CMS [RFC5652], JWS [I-D.ietf- 178 jose-json-web-signature]). Other more compact representations are in 179 discussion in the IETF, see section 5 of [JoseWgIetf90]. One 180 potential approach for defining data object security for constrained 181 environments is to wrap application layer data using such a format 182 and sending it as payload in a CoAP message. An alternative approach 183 is to instead build data object security into the CoAP message 184 format. The second approach is the one we propose in this memo. 186 As is explained in Appendix A and B this approach enables some 187 attractive features compared to transport of protected data on top of 188 CoAP, including: 190 o Protection of certain CoAP header and option fields 192 o Compliance with REST 194 o Reduction of message size, by avoiding unnecessary duplication 195 of data in payload and header/options 197 o Reuse of CoAP specific mechanisms for caching and forwarding 199 Independently of approach, the format needs to be complemented with a 200 description how the client and the server establish the keys, and how 201 the keys are used for wrapping and unwrapping the secured data 202 object. One way to address key establishment is to assume that there 203 is a trusted third party which can support client and server, such as 204 the Authorization Server in [I-D.draft-seitz-ace-problem- 205 description]. The Authorization Server may, for example, 206 authenticate the client on behalf of the server, or provide 207 cryptographic keys or credentials to the client and/or server to 208 secure the request/response procedure. 210 We emphasize that the solution sketched in this memo can be combined 211 with DTLS [RFC6347], thus enabling end-to-end integrity protection of 212 CoAP payload, certain CoAP headers and options, in combination with 213 hop-by-hop protection of the entire CoAP messages during transport 214 between end-points and intermediary devices. 216 3. The JWS Option 218 In order to integrity protect individual request and responses, as 219 well as request-response message exchanges, we introduce a new CoAP 220 option, the JWS option, essentially containing a digital signature or 221 Message Authentication Code (MAC) of the CoAP message. Endpoints 222 supporting this scheme MUST check for the presence of this option, 223 and that the signature/MAC is valid before accepting a message as 224 valid. The design considerations leading up to this solution are 225 presented in Appendix A. 227 3.1 Option Structure 229 The JWS option indicates that certain CoAP header fields, options, 230 and payload (if present) are integrity protected using JWS [I-D.ietf- 231 jose-json-web-signature]. The JWS option SHALL contain a detached 232 signature (JOSE Header and JWS Signature) as described in [I-D.ietf- 233 jose-json-web-signature] Appendix F, using JWS Compact Serialization 234 (see section 3.1 of [I-D.ietf-jose-json-web-signature]). 236 This option is critical, safe to forward, it is not part of a cache 237 key, and it is not repeatable. Table 1 illustrates the structure of 238 this option. 240 +-----+---+---+---+---+---------+--------+-----------+ 241 | No. | C | U | N | R | Name | Format | Length | 242 +-----+---+---+---+---+---------+--------+-----------+ 243 | TBD | x | | x | | JWS | opaque | 125-256 B | 244 +-----+---+---+---+---+---------+--------+-----------+ 246 C=Critical, U=Unsafe, N=NoCacheKey, R=Repeatable 248 Table 1: The JWS Option 250 3.2 Integrity Protection and Verification 252 A CoAP endpoint composing a message using the JWS option SHALL 253 process the JWS Payload and JOSE Header, defined in the following 254 sections, according to the specification for producing the 255 signature/MAC of a JWS object as described in Section 5.1 of the JWS 256 specification [I-D.ietf-jose-json-web-signature]. 258 A CoAP endpoint receiving a message containing the JWS option SHALL 259 first recreate the JWS Payload as described in Section 3.4, and then 260 verify the signature/MAC as defined in Section 5.2 of the JWS 261 specification [I-D.ietf-jose-json-web-signature]. 263 3.3 JOSE Header 265 Even if a signature/MAC of a received message can be verified, the 266 message may still be old, e.g. a replay of a previous message. As is 267 noted in section 10.10 of [I-D.ietf-jose-json-web-signature]), one 268 way to thwart replay attacks is to include a unique message 269 identifier and having the recipient verify that the message has not 270 been previously received or acted upon. 272 As unique JWS message identifier we propose to use the combination of 273 a unique key identifier and a sequence number. The JOSE Header of a 274 JWS option SHALL contain either one of the "kid", "x5t", or 275 "x5t#S256" header parameters to uniquely identify the key. In this 276 section we define a new JOSE Header parameter "seq" (Sequence Number) 277 enumerating the JWS objects/CoAP messages generated using the key 278 referenced in the JOSE Header. In addition to replay protection, we 279 want to be able to verify that a CoAP response is associated to a 280 previously made CoAP request in order to ensure the freshness of a 281 received response. For this purpose we require the responder to 282 include the sender's sequence number and key identifier in the JWS 283 Payload. 285 The header field and procedures described in this section could have 286 been replaced by similar procedures based on time-stamps, if the 287 devices in question had reliable and synchronized clocks. 289 3.3.1 "seq" (Sequence Number) Header Parameter 291 The "seq" header parameter contains the sequence number associated to 292 the key used to integrity protect the JWS object. The sequence 293 number SHALL be a 32-bit number in hexadecimal representation 294 including leading zeroes. The start sequence number SHALL be 0. For 295 a given key, any sequence number MUST NOT be used in "seq" more than 296 once. 298 The "seq" header parameter SHALL be marked as critical using the 299 "crit" header parameter of JWS (see section 4.1.11 of [I-D.ietf- 300 jose-json-web-signature]), meaning that if a receiver does not 301 understand this parameter it must reject the JWS. 303 3.3.2 Message Sequence Numbers 305 In order to protect from replay and verify freshness of responses, a 306 CoAP endpoint maintains sequence numbers. 308 A CoAP client supporting the JWS option SHALL store one sequence 309 number per key it uses to protect the integrity of a message. A CoAP 310 server supporting the JWS option SHALL store on sequence number per 311 key it uses to verify the integrity of a message. Depending on use 312 case, the endpoints MAY maintain a sliding receive window for 313 sequence numbers associated to key identifiers in received messages, 314 equivalent to the functionality described in section 4.1.2.6 of 315 [RFC6347]. 317 Before composing a new message with a JWS option, a CoAP client SHALL 318 step the associated sequence number and SHALL include it in the "seq" 319 header parameter as defined in 3.3.1. However, if the sequence 320 number counter wraps, the client must first acquire a new key. (The 321 latter is out of scope of this memo.) 323 A CoAP server supporting the JWS option SHALL verify the sequence 324 number received in "seq" by comparing with the stored associated 325 sequence number (or sliding window). If a CoAP server receives a 326 valid request with a JWS option, then the response SHALL include the 327 sequence number and key identifier of the request in the JWS Payload 328 as defined in section 3.4. 330 If the CoAP client receives a response message with a JWS option, 331 then the client SHALL generate the JWS Payload using the key 332 identifier and the sequence number of its own associated request as 333 defined in section 3.4 335 In Appendix B, we show how this can be extended to account for proxy 336 caching functionality as well as the CoAP Observe option. 338 3.4 JWS Payload 340 The JWS Payload is type-value-length encoded and consists of: 342 o the CoAP header field Code; 344 o all CoAP options present which are marked as signed in Table 2 345 (see Appendix A); and 347 o the CoAP payload (if any). 349 o if the message is a response, the sequence number "seq" from the 350 request (see section 3.3.1); 352 o if the message is a response, the key identifier from the 353 request ("kid", "x5t" or "x5t#256", see section 3.3.2) 355 To integrity protect the CoAP options requires the generation of a 356 standalone representation of each option (without the option delta, 357 see section 3.1 of [RFC7252]). The following procedure SHALL be 358 applied to generate an option representation: Calculate the option 359 number and represent it as a 8-bit unsigned integer. Then 360 concatenate the 8-bit option value with a 16-bit unsigned integer in 361 network byte order indicating the length of the Option Value, in 362 bytes. Finally concatenate the option value (if any is present) with 363 that bit-string. 365 For a request, the JWS Payload SHALL be the concatenation of the 8- 366 bit CoAP header field Code, the CoAP option representations (as 367 described in the previous paragraph) which are marked signed in Table 368 2 (see Appendix A) in the same order as given in the request, and 369 finally a 16-bit unsigned integer in network byte order indicating 370 the length of the CoAP payload, in bytes, and the CoAP payload of the 371 message (if any present) as represented in the request. 373 For a reply, the JWS Payload SHALL be generated as above, but 374 additionally the server SHALL append the concatenation of the 32-bit 375 sequence number from the request, an 8-bit unsigned integer in 376 network byte order indicating the length of the key identifier, in 377 bytes, and the key identifier from the request. 379 4. Proxy Behavior 381 As we target end-to-end security, we must ensure that the solution is 382 compliant with message handling in intermediary nodes. 384 CoAP distinguishes between two types of proxies; forward-proxies, 385 which are explicitly selected by clients, and reverse-proxies, which 386 handle requests transparently to the client. Since the client is not 387 aware of any nodes behind a reverse-proxy, it perceives the reverse- 388 proxy as an origin server which terminates the end-to-end security. 390 Forward-proxies are in scope and we cover two cases here: the CoAP- 391 CoAP forward proxy and the HTTP-CoAP cross-proxy. For CoAP-CoAP 392 forward proxies, the JWS option SHALL be forwarded. 394 Using an HTTP-CoAP proxy requires that the client understands how to 395 formulate a CoAP request. In the "Default Mapping", the Target CoAP 396 URI is appended as-is to a base URI [I-D.ietf-core-http-mapping]. 397 Analogously to a CoAP-CoAP forward proxy, the relevant options are 398 copied from the HTTP URI. The JWS option SHALL be transported in the 399 HTTP URI as a Query: 401 ?JWS=... 403 where the dots "..." should be replaced by the JWS option. 405 Proxies not supporting the JWS option handle messages containing a 406 JWS option according to the CoAP option processing rules, i.e. they 407 will not process such messages themselves (since the option is marked 408 "critical") but they will forward such messages (since the option is 409 marked as "safe-to-forward"). 411 5. Examples 413 In this section we give examples in order to illustrate and clarify 414 the intended use of the JWS option. 416 5.1 GET 418 This example outlines a GET message exchange forwarded by a proxy. 419 Integrity protection applies to Code, Uri-Path, Payload and other 420 message fields. 422 Client Proxy Server 423 | | | 424 | | | 425 +----->| | Header: GET (Code=0.01) Token: 0x8c 426 | GET | | Uri-Path: "temperature" 427 | | | JWS: (JOSE Header: { "seq":"00000142" } ...) 428 | | | 429 | | | 430 | +----->| Header: GET (Code=0.01) Token: 0x7b 431 | | GET | Uri-Path: "temperature" 432 | | | JWS: (JOSE Header: { "seq":"00000142" } ...) 433 | | | 434 | | | 435 | |<-----+ Header: 2.05 Content (Code=2.05) Token: 0x7b 436 | | 2.05 | JWS: (...) 437 | | | Payload: "23.1 C" 438 | | | 439 | | | 440 |<-----+ | Header: 2.05 Content (Code=2.05) Token: 0x8c 441 | 2.05 | | JWS: (...) 442 | | | Payload: "23.1 C" 443 | | | 445 where the signature and other details are omitted. The complete JOSE 446 header for the request is: 448 {"alg":"HS256", 449 "kid":"a1534e3c5fdc09bd", 450 "crit":["seq"], 451 "seq":"00000142" 452 } 454 and the JWS Payload consists of: 456 * 000 00001 (the header field code GET) 458 * 0x0B (option number 11, Uri-Path) 460 * 0x000B (length of the option value: 11) 462 * "temperature" (the option value) 464 * (Other options are omitted for brevity.) 466 and for the response is: 468 {"alg":"HS256", 469 "kid":"c1a6fa909502dd82" 470 } 472 The "kid" is a hint to the receiver indicating which key was used to 473 secure the JWS, and may be used as an identifier for a secret key or 474 a public key. It may e.g. be the hash of a public key. Even if "kid" 475 are different in request and response, it may reference the same 476 symmetric key. 478 The JWS Payload for the response consists of: 480 * 010 00101 (the header field code 2.05 Content) 482 * 0x0006 (length of the payload: 6) 484 * "23.1 C" (the payload value) 486 * "a1534e3c5fdc09bd" (the key identifier from the request) 488 * 0x00000142 (the sequence number from the request 490 5.2 POST 492 This example outlines a POST message exchange forwarded by a proxy. 493 Integrity protection applies to Code, Uri-Path, Payload and other 494 message fields. 496 Client Proxy Server 497 | | | 498 | | | 499 | | | 500 +----->| | Header: POST (T=CON, Code=0.02, MID=0xf124) 501 | POST | | Token: 0x8c 502 | | | Uri-Path: "lock" 503 | | | JWS: (JOSE Header: { "x5t":"a9095...a32a7b", 504 | | | "seq":"0000036f", ...} ...) 505 | | | Payload: "open" 506 | | | 507 | +----->| Header: POST (T=CON, Code=0.02, MID=0xf124) 508 | | POST | Token: 0x8c 509 | | | Uri-Path: "lock" 510 | | | JWS: (JOSE Header: { "x5t":"a9095...a32a7b", 511 | | | "seq":"0000036f", ...} ...) 512 | | | Payload: "open" 513 | | | 514 | |<-----+ Header: 2.04 Changed (T=ACK, Code=2.04, 515 | | 2.04 | MID=0xf124) Token: 0x8c 516 | | | JWS: (JOSE Header: { "x5t":"9f2a...8520", 517 | | | ...} ...) 518 | | | 519 |<-----+ | Header: 2.04 Changed (T=ACK, Code=2.04, 520 | 2.04 | | MID=0xf124) Token: 0x8c 521 | | | JWS: (JOSE Header: { "x5t":"9f2a...8520", 522 | | | ...} ...) 523 | | | 525 Note that in this case the client and the server are using X.509 526 certificates, which need to be available to both participants, so 527 that they can look up the right public key using the thumbprint. If 528 the proxy also has the public keys available, it can perform 529 signature verification and discard invalid messages, in order to 530 offload work from the client and server. 532 6. Security Considerations 534 In scenarios with proxies, gateways, or caching, DTLS only protects 535 data hop-by-hop meaning that all intermediary nodes can modify 536 information. The trust model where all participating nodes are 537 considered trustworthy is problematic not only from a privacy 538 perspective but also from a security perspective as the 539 intermediaries are free to delete resources on sensors and falsify 540 commands to actuators (such as "unlock door", "start fire alarm", 541 "raise bridge"). Even in the rare cases where all the owners of the 542 intermediary nodes are fully trusted, attacks and data breaches makes 543 such an architecture weak. 545 DTLS protects the entire CoAP message including header, options and 546 payload, whereas this proposal only protects selected message fields. 547 DTLS, however, also incurs a large overhead cost, due to the 548 handshake procedure. While that cost can be amortized in scenarios 549 with long lived connections, in cases where a device will have 550 connections with varying clients, using secured objects instead of 551 session security can provide a significant performance gain. 553 Using blockwise transfer [I-D.ietf-core-coap-block], the integrity 554 protection as provided by the method described here only covers the 555 individual blocks, not the entire request or response. One way to 556 handle this would to allow the JWS option to be repeatable, and in 557 one or several of the block transfer carry a MAC or signature that 558 covers the entire request or response. 560 Since the Version header field is not integrity protected, in case of 561 future versions of CoAP it may in theory be possible to launch a 562 cross-version attack, e.g. something analogously to a bidding down 563 attack. Future updates of CoAP should take this into account. 565 7. Privacy Considerations 567 End-to-end integrity protection provides certain privacy properties, 568 e.g. protects communication with sensor and actuator from 569 manipulation which may affect the personal sphere. 571 As a next step we plan to extend this scheme by add encryption for 572 addressing other privacy concerns, such as confidentiality of 573 personal data and prevention of pervasive monitoring. 575 8. IANA Considerations 577 The following entry is added to the CoAP Option Numbers registry: 579 +--------+---------+-------------------+ 580 | Number | Name | Reference | 581 +--------+---------+-------------------+ 582 | TBD | JWS | [[this document]] | 583 +--------+---------+-------------------+ 585 The following entries are added to the JSON Web Signature and 586 Encryption Header Parameters registry for Header Parameter names: 588 o Header Parameter Name: "seq" 589 o Header Parameter Description: Message sequence number 590 o Header Parameter Usage Location(s): JWS 591 o Change Controller: IESG 592 o Specification Document(s): Section 3.3.1 of 593 [[ this document ]]] 595 9. References 597 9.1 Normative References 599 [I-D.ietf-jose-json-web-signature] 600 Jones, M., Bradley, J., and Sakimura N., "JSON Web Signature (JWS)", 601 draft-ietf-jose-json-web-signature-36 (work in progress), October 602 2014. 604 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 605 Requirement Levels", BCP 14, RFC 2119, March 1997. 607 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 608 Security Version 1.2", RFC 6347, January 2012. 610 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 611 Application Protocol (CoAP)", RFC 7252, June 2014. 613 9.2 Informative References 615 [I-D.seitz-ace-problem-description] 616 Seitz, L., and G. Selander, "Problem Description for 617 Authorization in Constrained Environments", draft-seitz- 618 ace-problem-description-01 (work in progress), July 2014. 620 [I-D.seitz-ace-usecases] 621 Seitz, L., Gerdes, S., Selander, G., Mani, M., and S. 622 Kumar, "ACE use cases", draft-seitz-ace-usecases-01 (work 623 in progress), July 2014. 625 [JoseWgIetf90] 626 Minutes of the JOSE WG meeting at IETF 90, 627 http://www.ietf.org/proceedings/90/minutes/minutes-90-jose 629 [I-D.ietf-core-http-mapping] 630 Castellani, A., Loreto, S., Rahman, A., Fossati, T., and 631 E. Dijk, "Guidelines for HTTP-CoAP Mapping 632 Implementations", draft-ietf-core-http-mapping-05 (work in 633 progress), October 2014. 635 [I-D.ietf-core-coap-block] 636 Bormann, C., and Z. Shelby, "Blockwise transfers in CoAP", 637 draft-ietf-core-block-15 (work in progress), July 2014. 639 [I-D.ietf-jose-cookbook] 640 M. Miller, "Examples of Protecting Content using 641 JavaScript Object Signing and Encryption (JOSE)", draft- 642 ietf-jose-cookbook-05 (work in progress), October 2014. 644 [I-D.ietf-core-observe] 645 K. Hartke, "Observing Resources in CoAP", draft-ietf- 646 core-observe-14 (work in progress), June 2014. 648 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", FYI 649 36, RFC 4949, August 2007. 651 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 652 RFC 5652, September 2009. 654 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 655 Constrained-Node Networks", RFC 7228, May 2014. 657 [RFC7231] Fielding, R., Ed., and J. Reschke, Ed., "Hypertext 658 Transfer Protocol (HTTP/1.1): Semantics and Content", 659 RFC 7231, June 2014. 661 Appendix A. Design Considerations 663 In this section we provide some motivation for the chosen solution. 664 The pedagogical attempt of this section is by means of iterative 665 modifications of the trivial solution consisting of a secure object 666 carried in the payload. 668 A.1 Reducing Message Size 670 We noted in Section 2 that end-to-end security may be provided on 671 application layer on top of CoAP by including, say, a JWS object [I- 672 D.ietf-jose-json-web-signature] in the CoAP payload. The JWS 673 represents content secured with digital signatures or Message 674 Authentication Codes (MACs) using JavaScript Object Notation (JSON) 675 based data structures. 677 However, if the content of the JWS object is independent from the 678 CoAP message, it does not integrity protect CoAP header fields or 679 options. To address this, one solution is to repeat certain 680 information, contained within CoAP header fields and options, in the 681 JWS object. However, this would not be optimal since some data would 682 be duplicated in header/options and payload. For example, a resource 683 identifier would be transported both as a CoAP URI-Path/URI-Query 684 option (to comply with the CoAP message format), and in the payload 685 (to integrity protect the intended resource which the request is 686 targeting). 688 Fortunately, there is a solution to this problem known as "detached 689 content" (Appendix F, [I-D.ietf-jose-json-web-signature]) a.k.a. 690 "detached signature" ([I-D.ietf-jose-cookbook]). As is described in 691 these references, the detached signature is constructed from "a JWS 692 object in the normal fashion using a representation of the content as 693 the payload, but then delete the payload representation from the 694 JWS". With the outcome that "the resulting JWS object do not include 695 the integrity protected content. Instead, the application is expected 696 to locate it elsewhere." 698 Using JWS detached signature together with a specification for what 699 message fields should be included in the digital signature or MAC, we 700 can get integrity protection of relevant CoAP message fields without 701 unnecessary duplication of message fields. 703 A.2 REST Considerations 705 As we saw in the previous section, a JWS detached signature in the 706 CoAP payload would provide integrity protection and optimized message 707 format. However, not all CoAP request and response messages support 708 payload. E.g. GET and DELETE requests may not have defined body 709 semantics and that could to some extent violate RESTful design. 710 Furthermore, some CoAP response messages are not allowed to have 711 payload or are only intended to carry resource representations. 713 We therefore propose to pass a JWS detached signature as a new CoAP 714 option, as described in section 3. 716 NOTE: The choice of JWS is based on its relative compactness. Even 717 compacter formats, as recently has been discussed [JoseWgIetf90], 718 would be favorable. 720 A.3 Protection of CoAP Message Fields 722 Having motivated how a signature or MAC should be carried, we now 723 turn to the question what information should be integrity protected. 725 Integrity protection should cover relevant message fields that are 726 not supposed to change between client and server. This must also 727 take into account that there may be intermediary devices caching 728 and/or forwarding requests or responses. 730 In this section we study the message format (see Figure 1) and list 731 the fields that need to be integrity protected as well as describe 732 the procedure. Clearly the payload should be protected, but not all 733 headers fields or options. 735 0 1 2 3 736 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 737 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 738 |Ver| T | TKL | Code | Message ID | 739 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 740 | Token (if any, TKL bytes) ... 741 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 742 | Options (if any) ... 743 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 744 |1 1 1 1 1 1 1 1| Payload (if any) ... 745 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 747 Figure 1: CoAP message Format 749 A.3.1 CoAP Header 751 We now describe which fields in the CoAP header that needs to be 752 protected. 754 o Version (Ver): This field is fixed for a given implementation. 755 However, to allow backward compatibility with future versions of 756 CoAP, Version SHALL NOT be integrity protected. 758 o Type (T) and Message ID: These fields are only relevant on CoAP 759 messaging layer. Different Types (CON, NON, ACK, RST) or 760 Message IDs may be used to transport the same request/response 761 and hence SHALL NOT be integrity protected. 763 o Token Length (TKL) and Token: CoAP is using the Token as a 764 request identifier to match responses against requests. In the 765 case of multi-hop using intermediaries, the Token may be 766 different between the hops and is not preserved end-to-end. 767 These fields SHALL NOT be integrity protected. 769 o Code: This field is an 8-bit unsigned integer, identifying 770 request method or response code which should not change and 771 hence SHALL be integrity protected. 773 Summarizing: Only the Code header field is included in the JWS 774 Payload of the JWS option. 776 A.3.2 CoAP Options 778 The options need to be integrity protected as follows: 780 o ETag: This option defines resource local identifier of 781 representation and hence SHALL be integrity protected. 783 o If-Match, If-None-Match: These options are conditional control 784 logic for requests which thus SHALL be integrity protected. 786 o Observe: This option is elective and unsafe so may be discarded 787 by a proxy. Hence it SHALL NOT be integrity protected. 789 o Location-Path, Location-Query: These options are essentially 790 the identifier of a new resource and hence SHALL be integrity 791 protected. 793 o Accept, Content-Format: These options indicates representation 794 format of payload and hence SHALL be integrity protected. 796 o Max-Age: The Max-Age option in the response is intended to be 797 decreased by an intermediary device caching the response. 798 Moreover it is elective and unsafe to forward. It SHALL NOT be 799 integrity protected. 801 o Size1: This option provides size information about the resource 802 representation in a request and SHALL be integrity protected. 804 o Proxy-Uri: This option contains the request URI, which 805 identifies the requested resource, and hence it SHALL be 806 integrity protected, see last item in this list. 808 o Proxy-Scheme: This option contains the intended scheme to be 809 used by a proxy, and hence it SHALL be integrity protected, see 810 also last item in this list. 812 o Uri-Host, Uri-Port, Uri-Path and Uri-Query: In a request to an 813 origin server the request URI is decomposed into these options. 814 In the case of requests made to an origin server, these options 815 contain the complete information about the request URI. On the 816 other hand in a proxy request, the request URI is specified by 817 the client as a string in the Proxy-Uri option. The proxy which 818 makes this a request to the origin server decomposes the Proxy- 819 Uri into Uri-Host, Uri-Port, Uri-Path, and Uri-Query options. 820 However, the full URI can be reconstructed at any involved 821 endpoint. 823 To allow integrity verification of the request URI, the client 824 and forward proxies SHALL use explicit Uri-Host and Uri-Port 825 options. The server SHALL compose the URI from options 826 according to the method described in section 6.5 of the CoAP 827 specification [RFC7252]. The so obtained URI is put into a 828 Proxy-Uri option (no. 35), which is included in the integrity 829 calculation. 831 Table 2 summarizes which options to include in the integrity 832 calculation. Options marked with "x" are included. Options marked 833 with "d" are composed into a URI as described above and included as 834 the Proxy-Uri option for the purpose of calculating the signature. 835 (Proxy-Uri and the options marked with "d" are mutually exclusive.) 837 +-----+---+---+---+---+----------------+--------+--------+--------+ 838 | No. | C | U | N | R | Name | Format | Length | Signed | 839 +-----+---+---+---+---+----------------+--------+--------+--------+ 840 | 1 | x | | | x | If-Match | opaque | 0-8 | x | 841 | 3 | x | x | - | | Uri-Host | string | 1-255 | d | 842 | 4 | | | | x | ETag | opaque | 1-8 | x | 843 | 5 | x | | | | If-None-Match | empty | 0 | x | 844 | 6 | | x | - | | Observe | uint | 0-3 | | 845 | 7 | x | x | - | | Uri-Port | uint | 0-2 | d | 846 | 8 | | | | x | Location-Path | string | 0-255 | x | 847 | 11 | x | x | - | x | Uri-Path | string | 0-255 | d | 848 | 12 | | | | | Content-Format | uint | 0-2 | x | 849 | 14 | | x | - | | Max-Age | uint | 0-4 | | 850 | 15 | x | x | - | x | Uri-Query | string | 0-255 | d | 851 | 17 | x | | | | Accept | uint | 0-2 | x | 852 | 20 | | | | x | Location-Query | string | 0-255 | x | 853 | 35 | x | x | - | | Proxy-Uri | string | 1-1034 | x | 854 | 39 | x | x | - | | Proxy-Scheme | string | 1-255 | x | 855 | 60 | | | x | | Size1 | uint | 0-4 | x | 856 +-----+---+---+---+---+----------------+--------+--------+--------+ 857 | TBD | x | | x | | JWS | opaque | 125-256| | 858 +-----+---+---+---+---+----------------+--------+--------+--------+ 860 C=Critical, U=Unsafe, N=NoCacheKey, R=Repeatable 862 Table 2: Which options to integrity protect. 864 Appendix B. Replay Protection - Special Cases 866 In this section we show how one can use the JWS option to handle 867 advance caching and subscribe (CoAP Observe) responses to GET 868 requests. Please note that this is work in progress. 870 The general problem introduced in these settings is that there is no 871 longer an end-to-end challenge-response protocol: 873 o An intermediary forward proxies may cache a response to a 874 corresponding GET request, and serve that response to another 875 client's GET request. 877 o A server may produce multiple responses to one GET Observe 878 request, i.e. there is no unique matching request for each 879 response. 881 This induces a number of changes: 883 o In general, we can't hope to prove freshness, but can still 884 protect from replayed responses using server sequence numbers, 885 indicated with the "seq" header parameter. 887 o However, to define an initial server sequence number we propose 888 to rely on an end-to-end challenge-response protocol. 890 o A response message containing a challenge, is neither available 891 nor meaningful to other clients. Since we are using both server 892 sequence numbers and challenge-response, we need to indicate 893 which of these freshness/replay protection parameter is used in 894 a given response. We introduce an indicator in section B.1. 896 o Since the resource identifier cannot be inferred from a default 897 CoAP response message when there is no associated integrity 898 protected challenge, we need to add this explicitly when we rely 899 on server sequence numbers. 901 o Note that since there may be multiple receivers of a response, 902 this scenario makes most sense with asymmetric crypto, i.e. that 903 the signature of the response can verified using the public key 904 of the server. 906 B.1 "isi" (Integrity Scope Indication) Header Parameter 908 We introduce a new JOSE Header parameter indicating in requests, what 909 freshness/replay parameter to integrity protect, and in responses, 910 what freshness/replay protection parameter is integrity protected. 912 The "isi" header parameter is a 2-bit indication of what value shall 913 be or is integrity protected in the response. The "isi" header 914 parameter SHALL be marked as critical. 916 B.1.1 "isi":"01" 918 This indicates that the key identifier and sequence number of the 919 request is placed in the JWS Payload of the response, and thus 920 integrity protected. There is no server sequence number in the 921 response. This the same procedure described in section 3. 923 B.1.2 "isi":"10" 925 This indicates that the server sequence number is in the "seq" header 926 parameter of the response, and thus integrity protected. The key 927 identifier and sequence number of the request is not included in the 928 JWS payload. The response SHALL contain the request URI in the 929 proxy-URI option. 931 B.1.3 "isi":"11" 933 This is a combination of the previous two. This indicates that the 934 key identifier and sequence number of the request is placed in the 935 JWS Payload, and the server sequence number is placed in the "seq" 936 header parameter of the response. Thus both parameters are integrity 937 protected. 939 B.1.4 "isi":"00" 941 This value is reserved for future use. 943 B.2 Advance Caching 945 B.2.1 Acquiring server sequence numbers 947 Client Proxy Server 948 | | | 949 | | | 950 | | | 951 +----->| | Header: GET (Code=0.01) Token: 0x8c 952 | GET | | Uri-Path: "temperature" 953 | | | JWS: (JOSE Header: { "kid":"b00d4272ae41433e", 954 | | | "seq":"00000142", 955 | | | "isi":"11", 956 | | | ...} ...) 957 | | | 958 | +----->| Header: GET (Code=0.01) Token: 0x4b 959 | | GET | Uri-Path: "temperature" 960 | | | JWS: (JOSE Header: { "kid":"b00d4272ae41433e", 961 | | | "seq":"00000142", 962 | | | "isi":"11", 963 | | | ...} ...) 964 | | | 965 | | | 966 | |<-----+ Header: 2.05 Content (Code=2.05) Token: 0x4b 967 | | 2.05 | JWS: (JOSE Header: { "kid":"c1a6fa909502dd82", 968 | | | "seq":"000000D7", 969 | | | "isi":"11", 970 | | | ...} ...) 971 | | | Payload: "23.1 C" 972 | | | 973 | | | 974 |<-----+ | Header: 2.05 Content (Code=2.05) Token: 0x8c 975 | 2.05 | | JWS: (JOSE Header: { "kid":"c1a6fa909502dd82", 976 | | | "seq":"000000D7", 977 | | | "isi":"11", 978 | | | ...} ...) 979 | | | Payload: "23.1 C" 980 | | | 982 In this case, the proxy recognizes that it cannot serve a verifiably 983 fresh cached answer to the client and therefore obtains a new one by 984 forwarding the client's request. 986 The CoAP server SHALL step the associated sequence number and SHALL 987 include it in the "seq" header parameter. However, if the sequence 988 number counter wraps, the server must first acquire a new key. (The 989 latter is out of scope of this memo.) 991 The server includes the key identifier and sequence number of the 992 request in the JWS payload as described in section 3. The client can 993 thus verify the freshness of the response and conclude the sequence 994 number is fresh. Here either symmetric and asymmetric keys may be 995 used. 997 B.2.2 Proxy caching 999 Client Proxy Server 1000 | | | 1001 | | | 1002 | +----->| Header: GET (Code=0.01) Token: 0x4c 1003 | | GET | Uri-Path: "temperature" 1004 | | | JWS: (JOSE Header: { "kid":"a1534e3c5fdc09bd", 1005 | | | "seq":"00000070", 1006 | | | "isi":"10", 1007 | | | ...} ...) 1008 | | | 1009 | |<-----+ Header: 2.05 Content (Code=2.05) Token: 0x4c 1010 | | 2.05 | JWS: (JOSE Header: { "kid":"c1a6fa909502dd82", 1011 | | | "seq":"000000DA", 1012 | | | "isi":"10", 1013 | | | ...} ...) 1014 | | | Payload: "22.7 C" 1015 | | | 1016 | | | 1017 | | | 1018 +----->| | Header: GET (Code=0.01) Token: 0x8d 1019 | GET | | Uri-Path: "temperature" 1020 | | | JWS: (JOSE Header: { "kid":"b00d4272ae41433e", 1021 | | | "seq":"00000044", 1022 | | | "isi":"10", 1023 | | | ...} ...) 1024 | | | 1025 |<-----+ | Header: 2.05 Content (Code=2.05) Token: 0x8d 1026 | 2.05 | | JWS: (JOSE Header: { "kid":"c1a6fa909502dd82", 1027 | | | "seq":"000000DA", 1028 | | | "isi":"10", 1029 | | | ...} ...) 1030 | | | Payload: "22.7 C" 1031 | | | 1033 In this case the proxy requests a response which includes the server 1034 sequence number but not the key identifier and the sequence number of 1035 the request. The response also contains the resource URI for 1036 identification of resource. 1038 When the proxy gets a request with an "isi" header parameter that is 1039 not required to be forwarded it is matched against the cached 1040 responses, and since a corresponding response is present, it is 1041 forwarded to the client. 1043 This setting makes most sense in the case of response "kid" 1044 identifies a public key of the server. 1046 B.3 Observe 1048 In certain cases, there may be more than one response associated to a 1049 request, e.g. in the case of the CoAP option Observe ([I-D.ietf-core- 1050 observe]). To securely distinguish between multiple responses and 1051 protect from replay of responses we propose the following approach: 1053 Client Server 1054 | | 1055 | | 1056 +----->| Header: GET (Code=0.02) Token: 0x4a 1057 | GET | Uri-Path: "temperature" 1058 | | Observe: register 1059 | | JWS: (JOSE Header: { "kid":"a1534e3c5fdc09bd", 1060 | | "seq":"0000006F", 1061 | | "isi":"11", ...} ...) 1062 | | 1063 | | 1064 |<-----+ Header: 2.05 Content (Code=2.05) Token: 0x4a 1065 | 2.05 | Observe: 12 1066 | | JWS: (JOSE Header: { "kid":"c1a6fa909502dd82", 1067 | | "seq":"000001D6", 1068 | | "isi":"11", ...} ...) 1069 | | Payload: "22.9 C" 1070 | | 1071 |<-----+ Header: 2.05 Content (Code=2.05) Token: 0x4a 1072 | 2.05 | Observe: 44 1073 | | JWS: (JOSE Header: { "kid":"c1a6fa909502dd82", 1074 | | "seq":"000001D7", 1075 | | "isi":"10", ...} ...) 1076 | | Payload: "22.8 C" 1077 | | 1078 |<-----+ Header: 2.05 Content (Code=2.05) Token: 0x4a 1079 | 2.05 | Observe: 60 1080 | | JWS: (JOSE Header: { "kid":"c1a6fa909502dd82", 1081 | | "seq":"000001D8", 1082 | | "isi":"10", ...} ...) 1083 | | Payload: "23.1 C" 1084 | | 1086 The "GET Observe: register" request SHALL contain the "isi" header 1087 parameter with value "11". The response to the "GET Observe: 1088 register" shall contain the the "isi" header parameter with value 1089 "11". This response SHALL NOT be cached. GET Observe responses 1090 without a matching request SHALL contain the the "isi" header 1091 parameter with value "10", i.e. the response SHALL contain server 1092 sequence value "seq" in JOSE Header and no request key identifier and 1093 sequence number in the JWS payload. 1095 This procedure for replay protection of Observe also works in the 1096 presence of proxies by combining the procedures in section B.1 and 1097 B.2. This applies both to the cases of a client observing a resource 1098 through a proxy, and a proxy observing a resource to keep its cache 1099 up to date (section A.2 of [I-D.ietf-core-observe]). 1101 Authors' Addresses 1103 Goeran Selander 1104 Ericsson 1105 Farogatan 6 1106 16480 Kista 1107 SWEDEN 1108 EMail: goran.selander@ericsson.com 1110 Ludwig Seitz 1111 SICS Swedish ICT AB 1112 Scheelevagen 17 1113 22370 Lund 1114 SWEDEN 1115 EMail: ludwig@sics.se 1117 John Mattsson 1118 Ericsson 1119 Farogatan 6 1120 16480 Kista 1121 SWEDEN 1122 EMail: john.mattsson@ericsson.com