idnits 2.17.1 draft-selander-ace-object-security-03.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 == Line 1764 has weird spacing: '... Broker lishe...' -- The document date (October 19, 2015) is 3111 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 (-07) exists of draft-ietf-ace-actors-02 == Outdated reference: A later version (-10) exists of draft-ietf-ace-usecases-09 == Outdated reference: A later version (-21) exists of draft-ietf-core-block-18 == Outdated reference: A later version (-24) exists of draft-ietf-cose-msg-05 -- Obsolete informational reference (is this intentional?): RFC 7231 (Obsoleted by RFC 9110) Summary: 1 error (**), 0 flaws (~~), 6 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 ACE Working Group G. Selander 3 Internet-Draft J. Mattsson 4 Intended status: Standards Track F. Palombini 5 Expires: April 21, 2016 Ericsson 6 L. Seitz 7 SICS Swedish ICT 8 October 19, 2015 10 Object Security of CoAP (OSCOAP) 11 draft-selander-ace-object-security-03 13 Abstract 15 This memo defines Object Security of CoAP (OSCOAP), a method for 16 protection of request and response message exchanges of the 17 Constrained Application Protocol (CoAP) using data object security. 18 OSCOAP provides end-to-end encryption, integrity and replay 19 protection to CoAP payload, options and header fields, and a secure 20 binding between CoAP request and response messages. The use of 21 OSCOAP is signaled with the Object-Security option, also defined in 22 this memo. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at http://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on April 21, 2016. 41 Copyright Notice 43 Copyright (c) 2015 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (http://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 59 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 60 2. Background . . . . . . . . . . . . . . . . . . . . . . . . . 5 61 3. The Object-Security Option . . . . . . . . . . . . . . . . . 6 62 4. Secure Message Format . . . . . . . . . . . . . . . . . . . . 7 63 4.1. Secure Message Header . . . . . . . . . . . . . . . . . . 7 64 4.2. Secure Message Body and Tag . . . . . . . . . . . . . . . 8 65 4.2.1. Integrity Protection Only . . . . . . . . . . . . . . 8 66 4.2.2. Encryption and Integrity Protection . . . . . . . . . 8 67 5. CoAP Message Protection . . . . . . . . . . . . . . . . . . . 9 68 5.1. Integrity Protection Only . . . . . . . . . . . . . . . . 9 69 5.1.1. Protected CoAP message formatting . . . . . . . . . . 9 70 5.1.2. Secure Message formatting . . . . . . . . . . . . . . 10 71 5.1.3. Integrity Protection and Verification . . . . . . . . 10 72 5.2. Encryption and Integrity Protection . . . . . . . . . . . 10 73 5.2.1. Protected CoAP message formatting . . . . . . . . . . 10 74 5.2.2. Secure Message formatting . . . . . . . . . . . . . . 11 75 6. Protected CoAP Message Fields . . . . . . . . . . . . . . . . 12 76 6.1. Protected CoAP Header Fields . . . . . . . . . . . . . . 12 77 6.2. Protected CoAP Options . . . . . . . . . . . . . . . . . 12 78 6.2.1. Integrity Protection . . . . . . . . . . . . . . . . 13 79 6.2.2. Encryption . . . . . . . . . . . . . . . . . . . . . 15 80 7. Replay Protection and Freshness . . . . . . . . . . . . . . . 15 81 7.1. Replay Protection . . . . . . . . . . . . . . . . . . . . 15 82 7.2. Freshness . . . . . . . . . . . . . . . . . . . . . . . . 16 83 8. Security Considerations . . . . . . . . . . . . . . . . . . . 16 84 9. Privacy Considerations . . . . . . . . . . . . . . . . . . . 18 85 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 86 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 19 87 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 19 88 12.1. Normative References . . . . . . . . . . . . . . . . . . 19 89 12.2. Informative References . . . . . . . . . . . . . . . . . 20 90 Appendix A. COSE Profile of SM . . . . . . . . . . . . . . . . . 21 91 A.1. Integrity Protection Only . . . . . . . . . . . . . . . . 21 92 A.1.1. COSE_Sign . . . . . . . . . . . . . . . . . . . . . . 21 93 A.1.2. COSE_mac . . . . . . . . . . . . . . . . . . . . . . 22 94 A.2. Encryption and Integrity Protection: COSE_enveloped . . . 22 95 A.3. COSE Optimizations . . . . . . . . . . . . . . . . . . . 23 96 Appendix B. Comparison of message sizes . . . . . . . . . . . . 25 97 B.1. MAC Only . . . . . . . . . . . . . . . . . . . . . . . . 26 98 B.2. Signature Only . . . . . . . . . . . . . . . . . . . . . 27 99 B.3. Authenticated Encryption with Additional Data (AEAD) . . 29 100 B.4. Symmetric Encryption with Asymmetric Signature (SEAS) . . 30 101 Appendix C. Object Security of Content (OSCON) . . . . . . . . . 32 102 C.1. Security Considerations of OSCON . . . . . . . . . . . . 33 103 Appendix D. Examples . . . . . . . . . . . . . . . . . . . . . . 34 104 D.1. CoAP Message Protection . . . . . . . . . . . . . . . . . 34 105 D.1.1. Integrity Protection of CoAP Message Exchange . . . . 34 106 D.1.2. Additional Encryption of CoAP Message . . . . . . . . 36 107 D.2. Payload Protection . . . . . . . . . . . . . . . . . . . 37 108 D.2.1. Proxy Caching . . . . . . . . . . . . . . . . . . . . 37 109 D.2.2. Publish-Subscribe . . . . . . . . . . . . . . . . . . 38 110 D.2.3. Transporting Authorization Information . . . . . . . 40 111 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 41 113 1. Introduction 115 The Constrained Application Protocol CoAP [RFC7252] was designed with 116 a constrained RESTful environment in mind. CoAP references DTLS 117 [RFC6347] for securing the message exchanges. Two prominent features 118 of CoAP, store-and-forward and publish-subscribe exchanges, are 119 problematic to secure with DTLS and transport layer security. As 120 DTLS offers hop-by-hop security, in case of store-and-forward 121 exchanges it necessitates a trusted intermediary. Securing publish- 122 subscribe CoAP exchanges with DTLS requires the use of the keep-alive 123 mechanism which incurs additional overhead and actually takes away 124 most of the benefits of asynchronous communication. 126 The pervasive monitoring debate has illustrated the need to protect 127 data also from trustworthy intermediary nodes as they can be 128 compromised. The community has reacted strongly to the revelations, 129 and new solutions must consider this attack [RFC7258] and include 130 encryption by default. 132 This memo defines Object Security of CoAP (OSCOAP) a data object 133 based communication security solution complementing DTLS and 134 supporting secure messaging end-to-end across intermediary nodes. 135 OSCOAP may be used in very constrained settings where DTLS cannot be 136 supported. OSCOAP can also be combined with DTLS thus enabling, for 137 example, end-to-end security of CoAP payload in combination with hop- 138 by-hop protection of the entire CoAP message during transport between 139 end-point and intermediary node. 141 OSCOAP provides end-to-end encryption, integrity and replay 142 protection to CoAP payload, options and header fields, and a secure 143 binding between CoAP request and response messages. Using this 144 method the unprotected CoAP message is transformed into a protected 145 CoAP message, which contains a secure data object protecting the 146 unprotected message, and which is sent instead of the unprotected 147 message. The use of OSCOAP is signaled with the Object-Security 148 option, also defined in this memo. 150 1.1. Terminology 152 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 153 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 154 document are to be interpreted as described in [RFC2119].These words 155 may also appear in this document in lowercase, absent their normative 156 meanings. 158 Certain security-related terms are to be understood in the sense 159 defined in [RFC4949]. These terms include, but are not limited to, 160 "authentication", "authorization", "confidentiality", "(data) 161 integrity", "message authentication code", and "verify". For 162 "signature", see below. 164 RESTful terms, such as "resource" or "representation", are to be 165 understood as used in HTTP [RFC7231] and CoAP. 167 Terminology for constrained environments, such as "constrained 168 device", "constrained-node network", is defined in [RFC7228]. 170 Terminology for authentication and authorization in constrained 171 environments, such as "Authorization Server", "Resource Server", etc, 172 is defined in [I-D.ietf-ace-actors]. 174 The CoAP option Object-Security and the Secure Message (SM) format 175 are defined in this memo. 177 Two different scopes of object security are defined: 179 o OSCOAP = object security of CoAP, signaled with the Object- 180 Security option 182 o OSCON = object security of content, signaled with Content Format/ 183 Media Type set to application/oscon. 185 OSCON is defined in Appendix C and included for comparison with 186 OSCOAP. 188 The COSE message format is defined in [I-D.ietf-cose-msg]. 190 2. Background 192 The background for this work is provided by the use cases and 193 architecture in [I-D.ietf-ace-usecases] and [I-D.ietf-ace-actors]. 194 The focus of this memo is on end-to-end security in constrained 195 environments in the presence of intermediary nodes. 197 For constrained-node networks there may be several reasons for 198 messages to be cached or stored in one node and later forwarded. 200 For example, connectivity between the nodes may be intermittent, or 201 some node may be sleeping at the time when the message should have 202 been forwarded (see e.g. [I-D.ietf-ace-usecases] sections 2.1.1, and 203 2.5.1). Also, the architectural model or protocol applied may 204 require an intermediary node which breaks security on transport layer 205 (see e.g. [I-D.ietf-ace-usecases] sections 2.1.1, and 2.5.2). 206 Examples of intermediary nodes include forward proxies, reverse 207 proxies, pub-sub brokers, HTTP-CoAP cross-proxies, and SMS servers. 209 Based on these examples the following security requirements have been 210 identified: 212 1. The payload shall be integrity protected and should be encrypted 213 end-to-end from sender to receiver. 215 2. It shall be possible for an intended receiver to detect if it has 216 received this message previously, i.e. replay protection. 218 3. The CoAP options which are not intended to be changed by an 219 intermediary node shall be integrity protected between Client and 220 Server. 222 4. The CoAP options which are not intended to be read by an 223 intermediary node shall be encrypted between Client and Server. 225 5. The CoAP header fields "Code" and "Version" shall be integrity 226 protected between Client and Server. 228 6. A Client shall be able to verify that a message is the response 229 to a particular request the Client made. 231 In this list above, requirements 1-2 deals essentially with 232 protecting the CoAP payload only, whereas 3-6 deals with protecting 233 an entire CoAP request-response exchange, including also CoAP options 234 and header fields. 236 Object Security of CoAP (OSCOAP), which is the main focus of this 237 memo, addresses all requirements above by defining a method for 238 encryption, integrity protection and replay protection of CoAP 239 payload, options and header fields, and a secure binding between CoAP 240 request and response messages. OSCOAP consists of: 242 o the Object-Security option, indicating that OSCOAP is being used; 244 o a compact cryptographic message format called "Secure Message", 245 based on the COSE message format ([I-D.ietf-cose-msg]); and 247 o a scheme for transforming an unprotected CoAP message into a 248 protected CoAP message, which contains the Object-Security option 249 and a Secure Message protecting CoAP payload, options and header 250 fields. 252 The same method can be applied to payload only of individual 253 messages, targeting only requirements 1-2 above. We call this object 254 security of content (OSCON) and it is defined in Appendix C. 256 Examples of the use of OSCOAP and OSCON are given in Appendix D. 258 3. The Object-Security Option 260 In order to end-to-end protect CoAP message exchanges including 261 options and headers, a new CoAP option is introduced: the Object- 262 Security option. The Object-Security option indicates that OSCOAP is 263 used, i.e. that certain CoAP Header fields, Options and Payload (if 264 present) are integrity and replay protected and potentially 265 encrypted, using a cryptographic message format called the Secure 266 Message format Section 4. 268 This option is critical, safe to forward, it is not part of a cache 269 key, and it is not repeatable. Figure 1 illustrates the structure of 270 this option. 272 +-----+---+---+---+---+-----------------+--------+--------+ 273 | No. | C | U | N | R | Name | Format | Length | 274 +-----+---+---+---+---+-----------------+--------+--------| 275 | TBD | x | | x | | Object-Security | opaque | 0, TBD | 276 +-----+---+---+---+---+-----------------+--------+--------+ 277 C=Critical, U=Unsafe, N=NoCacheKey, R=Repeatable 279 Figure 1: The Object-Security Option 281 The length of the option depends on the specific choice of the Secure 282 Message format. Length 0 indicates that the Secure Message is the 283 CoAP Payload of the message, and is used when the CoAP message type 284 used supports payload. 286 4. Secure Message Format 288 There exist already standardized and draft content formats for 289 encryption and integrity protection of data such as CMS [RFC5652], 290 JWS [RFC7515], JWE [RFC7516], and COSE [I-D.ietf-cose-msg]. 292 Current CMS and JWx objects are undesirably large for very 293 constrained devices. Large messages has a negative impact on memory 294 and storage in constrained devices, packet fragmentation in 295 constrained-node networks due to limited frame sizes, and increased 296 energy consumption due to more data transmission and reception. The 297 candidate for use with object security of CoAP messages is the COSE 298 message format [I-D.ietf-cose-msg]. 300 Pending an optimized and stable version of the COSE message format 301 this memo defines the SM format to refer to a content format for 302 encrypted and integrity protected data, and also includes a unique 303 transaction identifier for replay protection. Appendix A shows a 304 profile of the COSE message format which complies with the Secure 305 Message format. 307 A Secure Message (SM) SHALL consist of Header, Body and Tag. 309 4.1. Secure Message Header 311 The following parameters SHALL be included in the SM Header: 313 o Context Identifier (CID). This parameter identifies the sender 314 security context including the cipher suite, key(s) and additional 315 algorithm specific parameters used to protect the message. Each 316 client and server communicating using OSCOAP has two contexts, one 317 for sending and one for receiving. 319 o Sequence Number (SEQ). The Sequence Number parameter enumerates 320 the Secure Messages sent associated to a Context Identifier, and 321 is used for replay protection and uniqueness of nonce. The start 322 sequence number SHALL be 0. For a given key, any Sequence Number 323 MUST NOT be used more than once. 325 The granularity of "sender" - what is being identified with the 326 Context Identifier - is defined by the application. With OSCOAP the 327 Context Identifier typically identifies the sending party and 328 different resources may be identified by the Uri-Path in the request. 329 (Compare Appendix C.) 331 The ordered sequence (SEQ, CID) is called Transaction Identifier 332 (TID), and SHALL be unique for each SM. 334 4.2. Secure Message Body and Tag 336 The use cases require support for two message types, one for 337 Encryption and Integrity Protection, and another for integrity 338 protection only. The SM Body and the SM Tag are different depending 339 on message type. 341 For Integrity Protection Only we denote by Authenticated Data (AD) 342 the data which is integrity protected in the Secure Message. For 343 Encryption and Integrity Protection we denote by Plaintext and 344 Additional Authenticated Data (AAD), the data which is encrypted and 345 integrity protected, and integrity protected only, respectively, in 346 the Secure Message. 348 The message type SHALL be explicit to allow an intermediate node to 349 distinguish between the two types and read the SM Body of an 350 Integrity Protected Only message. 352 4.2.1. Integrity Protection Only 354 In the case of integrity protection only, the SM Body SHALL consist 355 of the payload of the CoAP message. 357 The SM Tag SHALL consist of the Signature / Message Authentication 358 Code (MAC) as defined by the cipher suite calculated over the 359 Authenticated Data (AD). The AD for OSCOAP is defined in 360 Section 5.1.2. 362 4.2.2. Encryption and Integrity Protection 364 The use cases require support for two kinds of cipher suites: 365 Authenticated Encryption with Additional Data (AEAD) as well as 366 Symmetric Encryption and Asymmetric Signature (SEAS). 368 In case of AEAD, the SM Body and SM Tag SHALL consist of the 369 Ciphertext as defined by the cipher suite calculated over the 370 Plaintext and the Additional Authenticated Data (AAD). 372 In case of SEAS, the SM Body SHALL be the Ciphertext as defined by 373 the symmetric encryption algorithm, given by the cipher suite, 374 calculated over the Plaintext. The SM Tag SHALL be the Signature 375 defined by the cipher suite calculated over Ciphertext and AAD. 377 The Plaintext and the AAD for OSCOAP are defined in Section 5.2.2. 379 5. CoAP Message Protection 381 This section presents how OSCOAP protects individual CoAP messages 382 including payload, options and header fields, as well as request- 383 response message exchanges, using the Object-Security option 384 (Section 3) and the Secure Message format (Section 4). 386 The basic idea is that the significant parts of an unprotected CoAP 387 message - including payload, certain header field and options - are 388 protected using the Secure Message format and sent in a CoAP message 389 with the Object-Security option, in what we then call a "protected" 390 CoAP message. As much a possible of the CoAP message should be 391 protected, but not all CoAP header fields or options can be encrypted 392 and integrity protected, because some are intended to be read or 393 changed by an intermediary node, see Section 6.1 and Section 6.2. 395 The use of OSCOAP is signaled with the Object-Security option. 396 Endpoints supporting the Object-Security option MUST verify the SM as 397 described in this section before accepting a message as valid. An 398 endpoint receiving a CoAP request with the Object-Security option 399 MUST respond with a CoAP message with the Object-Security option. 401 The differences between Encryption and Integrity Protection vs 402 Integrity Protection Only is described below. Encryption and 403 Integrity Protection SHALL be used by default. 405 5.1. Integrity Protection Only 407 5.1.1. Protected CoAP message formatting 409 The protected CoAP message is formatted as an ordinary CoAP message, 410 with the following Header, Options and Payload based on the 411 unprotected CoAP message: 413 o The CoAP header SHALL be the same as the unprotected CoAP message. 415 o The CoAP options SHALL consist of the same options as the 416 unprotected CoAP message, and the Object-Security option. 418 o If the unprotected CoAP message has no Payload then the Object- 419 Security option SHALL contain the SM. If the unprotected CoAP 420 message has Payload, then the Object-Security option SHALL be 421 empty and the Payload of the CoAP message SHALL be the SM. 423 5.1.2. Secure Message formatting 425 The SM Header, Body and Tag are specified in Section 4.1 and 426 Section 4.2. 428 The Authenticated Data SHALL consist of the following data, in this 429 order: 431 o the SM Header; 433 o the two first bytes of the CoAP header (including Version and 434 Code) with Type and Token Length bits set to 0; 436 o all CoAP options present which are marked as IP in Figure 2 437 (Section 6.2), in the order as given by the option number (each 438 Option with Option Header including delta to previous IP-marked 439 Option which is present); 441 o the CoAP Payload (if any); and 443 o the Transaction Identifier of the associated CoAP Request, if the 444 message is a CoAP Response (see Section 4.1). 446 5.1.3. Integrity Protection and Verification 448 A CoAP endpoint protecting a CoAP message with the Object-Security 449 option using a cipher suite for integrity protection only SHALL 450 generate a protected CoAP message and SM based on the unprotected 451 CoAP message as described in Section 5.1.1 and Section 5.1.2. In 452 addition, the sending endpoint SHALL process the Sequence Number as 453 described in Section 7. 455 A CoAP endpoint receiving a message containing the Object-Security 456 option SHALL first recreate the Authenticated Data as described in 457 Section 5.1.2, and then verify the SM Tag as defined by the cipher 458 suite associated to the Context Identifier. In addition, the 459 receiving endpoint SHALL process the Sequence Number as described in 460 Section 7. 462 5.2. Encryption and Integrity Protection 464 5.2.1. Protected CoAP message formatting 466 The protected CoAP message is formatted as an ordinary CoAP message, 467 with the following Header, Options and Payload based on the 468 unprotected CoAP message: 470 o The CoAP header SHALL be the same as the unprotected CoAP message. 472 o The CoAP options SHALL consist of the unencrypted options of the 473 unprotected CoAP message (those not marked as E in Figure 2 474 (Section 6.2)), and the Object-Security option. The options shall 475 be formatted as in a CoAP message (each Option with Options Header 476 including delta to previous unencrypted Option). 478 o If the unprotected CoAP message has no Payload then the Object- 479 Security option SHALL contain the SM. If the unprotected CoAP 480 message has Payload, then the Object-Security option SHALL be 481 empty and the Payload of the CoAP message SHALL be the SM. 483 5.2.2. Secure Message formatting 485 The SM Header, Body and Tag are specified in Section 4.1 and 486 Section 4.2. 488 The Additional Authenticated Data SHALL consist of the following 489 data, in this order: 491 o the SM Header; 493 o the two first bytes of the CoAP header (including Version and 494 Code) with Type and Token Length bits set to 0; 496 o all CoAP options present which are marked as IP but not marked as 497 E in Figure 2 (Section 6.2), in the order as given by the option 498 number (each Option with Option Header including delta to previous 499 IP-marked Option which is present); and 501 o the Transaction Identifier of the associated CoAP Request, if the 502 message is a CoAP Response (see Section 4.1). 504 The Plaintext SHALL consist of the following data, formatted as a 505 CoAP message without Header consisting of: 507 o all CoAP Options present which are marked as E in Figure 2 (see 508 Section 6.2), in the order as given by the Option number (each 509 Option with Option Header including delta to previous E-marked 510 Option); and 512 o the CoAP Payload, if present, and in that case prefixed by the 513 one-byte Payload Marker (0xFF). 515 5.2.2.1. Encryption and Decryption 517 A CoAP endpoint protecting a CoAP message with the Object-Security 518 option using a cipher suite for encryption and integrity protection 519 SHALL generate a protected CoAP message and SM based on the 520 unprotected CoAP message as described in Section 5.2.1 and 521 Section 5.2.2. In addition, the sending endpoint SHALL process the 522 Sequence Number as described in Section 7. 524 A CoAP endpoint receiving a message containing the Object-Security 525 option SHALL recreate the Additional Authenticated Data as described 526 in Section 5.1.2 and verify the integrity of, and decrypt the message 527 as defined by the cipher suite associated to the Context Identifier. 528 In addition, the receiving endpoint SHALL process the Sequence Number 529 as described in Section 7. 531 6. Protected CoAP Message Fields 533 The CoAP payload SHALL be integrity protected. The CoAP payload 534 SHOULD be encrypted by default. 536 How CoAP Options and Header Fields shall be protected is described in 537 the remainder of this section. 539 6.1. Protected CoAP Header Fields 541 This section describes which CoAP header fields are encrypted or 542 integrity protected end-to-end in OSCOAP. 544 The CoAP Message Layer parameters, Type and Message ID, as well as 545 Token and Token Length may be changed by a proxy and thus SHALL 546 neither be integrity protected nor encrypted. 548 The Version and Code fields SHALL be integrity protected, see 549 security considerations. 551 6.2. Protected CoAP Options 553 This section describes which CoAP options are encrypted and integrity 554 protected, if present in the unprotected CoAP message. 556 All CoAP options SHALL be encrypted by default, unless intended to be 557 read by an intermediate node; and SHALL be integrity protected, 558 unless intended to be changed by an intermediate node. 560 However, some special considerations are necessary because CoAP 561 defines certain legitimate proxy operations, because the security 562 information itself may be transported as an option, and because 563 different processing is performed depending on whether encryption is 564 applied or not. 566 The details are presented in Section 6.2.1 and Section 6.2.2, and 567 summarized in Figure 2. 569 +-----+---+---+---+---+----------------+--------+--------+---+----+ 570 | No. | C | U | N | R | Name | Format | Length | E | IP | 571 +-----+---+---+---+---+----------------+--------+--------+---+----| 572 | 1 | x | | | x | If-Match | opaque | 0-8 | x | x | 573 | 3 | x | x | - | | Uri-Host | string | 1-255 | | a | 574 | 4 | | | | x | ETag | opaque | 1-8 | x | x | 575 | 5 | x | | | | If-None-Match | empty | 0 | x | x | 576 | 6 | | x | - | | Observe | uint | 0-3 | | | 577 | 7 | x | x | - | | Uri-Port | uint | 0-2 | | a | 578 | 8 | | | | x | Location-Path | string | 0-255 | x | x | 579 | 11 | x | x | - | x | Uri-Path | string | 0-255 | x | b | 580 | 12 | | | | | Content-Format | uint | 0-2 | x | x | 581 | 14 | | x | - | | Max-Age | uint | 0-4 | | | 582 | 15 | x | x | - | x | Uri-Query | string | 0-255 | x | b | 583 | 17 | x | | | | Accept | uint | 0-2 | x | x | 584 | 20 | | | | x | Location-Query | string | 0-255 | x | x | 585 | 23 | x | x | - | | Block2 | uint | 0-3 | | | 586 | 27 | x | x | - | | Block1 | uint | 0-3 | | | 587 | 28 | | | x | | Size2 | uint | 0-4 | x | x | 588 | 35 | x | x | - | | Proxy-Uri | string | 1-1034 | | i | 589 | 39 | x | x | - | | Proxy-Scheme | string | 1-255 | | i | 590 | 60 | | | x | | Size1 | uint | 0-4 | x | x | 591 +-----+---+---+---+---+----------------+--------+--------+---+----+ 592 C=Critical, U=Unsafe, N=NoCacheKey, R=Repeatable, 593 E=Encrypt, IP=Integrity Protect. 595 Figure 2: Protected CoAP options in OSCOAP 597 CoAP options marked "i" indicate that they are used as invariants in 598 the authenticated data (AD/AAD) as described in Section 6.2.1.1 and 599 Section 6.2.1.2. 601 In case of Integrity Protection Only, options marked with "a" and "b" 602 are composed into a URI as described in Section 6.2.1.2 and included 603 as invariant in the Proxy-Uri option in the Authenticated Data. 605 In case of Encryption and Integrity Protection, options marked "a" 606 are composed into a URI as described in Section 6.2.2 and included as 607 the Proxy-Uri option in the Additional Authenticated Data. (Options 608 marked "b" are included in the Plaintext.) 610 6.2.1. Integrity Protection 612 CoAP options which are not intended to be changed by an intermediate 613 node MUST be integrity protected. 615 o CoAP options of the unprotected message which are Safe-to-Forward 616 SHALL be integrity protected. See Figure 2. 618 Note: The Object-Security option in itself is Safe-to-Forward but is 619 added to the protected message. 621 CoAP options which are intended to be modified by a proxy can be 622 divided into two categories, those that are intended to change in a 623 predictable way, and those which are not. The following options are 624 of the latter kind and SHALL NOT be integrity protected: 626 o Max-Age, Observe, Block1, Block2: These options may be modified by 627 a proxy in a way that is not predictable for client and server. 629 The remaining options may be modified by a proxy, but when they are, 630 the change is predictable. Therefore it is possible to define 631 "invariants" which can be integrity protected. 633 6.2.1.1. Proxy-Scheme 635 A Forward Proxy is intended to replace the URI scheme with the 636 content of the Proxy-Scheme option. The Proxy-Scheme option is 637 defined in this memo to be an invariant with respect to the following 638 processing 640 o If there is a Proxy-Scheme present in the unprotected message, 641 then the client SHALL integrity protect the Proxy-Scheme option. 643 o If there is no Proxy-Scheme option present the client SHALL 644 include the Proxy-Scheme option in the authenticated data (AD/AAD) 645 set to the URI scheme. (The sent message does not include the 646 Proxy-Scheme option.) 648 o The server SHALL insert the Proxy-Scheme option with the name of 649 the URI scheme the message was received in the authenticated data 650 (AD/AAD). 652 6.2.1.2. Uri-* 654 For options related to URI of resource (Uri-Host, Uri-Port, Uri-Path, 655 Uri-Query, Proxy-Uri) a Forward Proxy is intended to replace the Uri- 656 * options with the content of the Proxy-Uri option. 658 The Proxy-Uri option is defined in this memo to be an invariant with 659 respect to the following processing (applied to Integrity Protection 660 only, for Encryption see next section): 662 o If there is a Proxy-Uri present, then the client MUST integrity 663 protect the Proxy-Uri option and the Uri-* options MUST NOT be 664 integrity protected. 666 o If there is no Proxy-Uri option present, then the client SHALL 667 compose the full URI from Uri-* options according to the method 668 described in section 6.5 of [RFC7252]. The Authenticated Data 669 contains the following options, modified compared to what is sent: 671 o All Uri-* options removed 673 o A Proxy-Uri option with the full URI included 675 o The server SHALL compose the URI from the Uri-* options according 676 to the method described in section 6.5 of [RFC7252]. The so 677 obtained URI is placed into a Proxy-Uri option, which is included 678 in the Authenticated Data. 680 6.2.2. Encryption 682 All CoAP options MUST be encrypted, except the options below which 683 MUST NOT be encrypted: 685 o Max-Age, Observe, Block1, Block2, Proxy-Uri, Proxy-Scheme: This 686 information is intended to be read by a proxy. 688 o Uri-Host, Uri-Port: This information can be inferred from 689 destination IP address and port. 691 o Object-Security: This is the security-providing option. 693 In the case of encryption, the Proxy-Uri of the Additional 694 Authenticated Data MUST only contain Uri-Host and Uri-Port and MUST 695 NOT contain Uri-Path and Uri-Query because the latter options are not 696 necessarily available to a Forward Proxy. 698 7. Replay Protection and Freshness 700 In order to protect from replay of messages and verify freshness of 701 responses, a CoAP endpoint using object security SHALL maintain 702 Sequence Numbers (SEQs) of sent and received Secure Messages (see 703 Section 4.1), associated to the respective security context 704 identified with the Context Identifier (CID). 706 7.1. Replay Protection 708 An endpoint SHALL maintain a SEQ for each security context it uses to 709 receive messages, and one SEQ for each security context for 710 protecting sent messages. Depending on use case, an endpoint MAY 711 maintain a sliding receive window for Sequence Numbers in received 712 messages associated to each CID, equivalent to the functionality 713 described in section 4.1.2.6 of [RFC6347]. 715 Before composing a new message a sending endpoint SHALL step the SEQ 716 of the associated CID. However, if the Sequence Number counter 717 wraps, the endpoint must first acquire a new CID and associated 718 security context/key(s). The latter is out of scope of this memo. 720 A receiving endpoint SHALL verify that the Sequence Number received 721 in the SM Header is greater than the Sequence Number of the 722 associated CID (or within the sliding window and not previously 723 received) and update the SEQ (window) accordingly. 725 7.2. Freshness 727 OSCOAP is a challenge-response protocol, where the response is 728 verified to match a prior request by including the unique transaction 729 identifier TID (concatenation of SEQ and CID) of the request in the 730 integrity calculation of the response message. 732 If a CoAP server receives a request with the Object-Security option, 733 then the authenticated data (AD or AAD) of the response SHALL include 734 the TID of the request as described in Section 5.1.2 and 735 Section 5.2.2. 737 If the CoAP client receives a response with the Object-Security 738 option, then the client SHALL verify the integrity of the response 739 using the TID of its own associated request in the authenticated data 740 (AD or AAD) as described in Section 5.1.2 and Section 5.2.2. 742 8. Security Considerations 744 In scenarios with proxies, gateways, or caching, DTLS only protects 745 data hop-by-hop meaning that these intermediary nodes can read and 746 modify information. The trust model where all participating nodes 747 are considered trustworthy is problematic not only from a privacy 748 perspective but also from a security perspective as the 749 intermediaries are free to delete resources on sensors and falsify 750 commands to actuators (such as "unlock door", "start fire alarm", 751 "raise bridge"). Even in the rare cases where all the owners of the 752 intermediary nodes are fully trusted, attacks and data breaches make 753 such an architecture weak. 755 DTLS protects the entire CoAP message including Header, Options and 756 Payload, whereas OSCOAP protects the payload and message fields 757 described in Section 6.1 and Section 6.2. The cost for DTLS 758 providing this protection is the overhead in e.g. additional 759 messages, processing, memory incurred by the DTLS Handshake protocol, 760 which can be omitted in use cases where key establishment can be 761 provided by other means. 763 CoAP specifies how messages should be acknowledged on message layer. 764 The CoAP message layer, however, cannot be protected by application 765 layer security end-to-end since the parameters Type and Message ID, 766 as well as Token and Token Length may be changed by a proxy. 767 Moreover, messages that are not possible to verify should for 768 security reasons not always be acknowledged but in some cases be 769 silently dropped. This would not comply with CoAP message layer, but 770 does not have an impact on the object security solution, since 771 message layer is excluded from that. 773 The CoAP Header field Code needs to be integrity protected end-to- 774 end. For example, if a malicous man-in-the-middle would replace the 775 client requested GET with a DELETE, this must be detected by the 776 server. The CoAP Header field Version needs also to be integrity 777 protected to prevent from potential cross-version attacks, such as 778 bidding-down. 780 Blockwise transfers as defined [I-D.ietf-core-block] cannot be 781 protected with application layer security end-to-end because the 782 Block1/Block2 options may be changed in an unpredictable way by an 783 intermediate node. 785 However, it is possible to define end-to-end block options analogous 786 to Block1 and Block2 which are safe-to-forward, integrity protected 787 and not supposed to be changed by intermediate devices. With such an 788 option each individual block can be securely verified by the 789 receiver, retransmission securely requested etc. Since the blocks 790 are enumerated sequentially and carry information about last block, 791 when all blocks have been securely received, this proves that the 792 entire message has been securely transferred. 794 The Observe option cannot be integrity protected since it is allowed 795 to change in an unpredictable way. But since message sequence 796 numbers are integrity protected a client 797 can verifies that a GET response has not been received before. 799 The use of sequence numbers for replay protection introduces the 800 problem related to wrapping of the counter. The alternatives also 801 have issues: very constrained devices may not be able to support 802 accurate time or generate and store large numbers of random nonces. 803 The requirement to change key at counter wrap is a complication, but 804 it also forces the user of this specification to think about 805 implementing key renewal. 807 This specification needs to be complemented with a procedure whereby 808 the client and the server establish the keys used for wrapping and 809 unwrapping the Secure Message. One way to address key establishment 810 is to assume that there is a trusted third party which can support 811 client and server, such as the Authorization Server in 812 [I-D.ietf-ace-actors]. The Authorization Server may, for example, 813 authenticate the client on behalf of the server, or provide 814 cryptographic keys or credentials to the client and/or server which 815 can be use to derive the keys used in the Secure Message exchange. 816 Similarly, the Authorization Server may, on behalf of the server, 817 notify the client of server supported ciphers, in order to facilitate 818 the usage of OSCOAP in deployments with multiple supported 819 cryptographic algorithms. 821 The security contexts required are different for different cipher 822 suites. For an AEAD or SEAS it is required to have a unique 823 Initialization Vector for each message, for which the Sequence Number 824 is used. The Initialization Vector SHALL be the concatenation of a 825 Salt (4 bytes unsigned integer) and the Sequence Number. The Salt 826 SHOULD be established between sender and receiver before the message 827 is sent, to avoid the overhead of sending it in each message. For 828 example, the Salt may be established by the same means as keys are 829 established. 831 9. Privacy Considerations 833 End-to-end integrity protection provides certain privacy properties, 834 e.g. protection of communication with sensor and actuator from 835 manipulation which may affect the personal sphere. End-to-end 836 encryption of payload and certain CoAP options provides additional 837 protection as to the content and nature of the message exchange. 839 The headers sent in plaintext allow for example matching of CON and 840 ACK (CoAP Message Identifier), matching of request and response 841 (Token). Plaintext options could also reveal information, e.g. 842 lifetime of measurement (Max-age), or that this message contains one 843 data point in a sequence (Observe). 845 10. IANA Considerations 847 Note to RFC Editor: Please replace all occurrences of "[this 848 document]" with the RFC number of this specification. 850 The following entry is added to the CoAP Option Numbers registry: 852 +--------+-----------------+-------------------+ 853 | Number | Name | Reference | 854 +--------+-----------------+-------------------+ 855 | TBD | Object-Security | [[this document]] | 856 +--------+-----------------+-------------------+ 857 This document registers the following value in the CoAP Content 858 Format registry established by [RFC7252]. 860 Media Type: application/oscon 862 Encoding: - 864 Id: 70 866 Reference: [this document] 868 11. Acknowledgments 870 Klaus Hartke has independently been working on the same problem and a 871 similar solution: establishing end-to-end security across proxies by 872 adding a CoAP option. We are grateful to Malisa Vucinic for 873 providing helpful and timely reviews of new versions of the draft. 875 12. References 877 12.1. Normative References 879 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 880 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 881 RFC2119, March 1997, 882 . 884 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 885 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 886 January 2012, . 888 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 889 Application Protocol (CoAP)", RFC 7252, DOI 10.17487/ 890 RFC7252, June 2014, 891 . 893 [RFC7258] Farrell, S. and H. Tschofenig, "Pervasive Monitoring Is an 894 Attack", BCP 188, RFC 7258, DOI 10.17487/RFC7258, May 895 2014, . 897 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 898 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 899 2015, . 901 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 902 RFC 7516, DOI 10.17487/RFC7516, May 2015, 903 . 905 12.2. Informative References 907 [I-D.ietf-ace-actors] 908 Gerdes, S., Seitz, L., Selander, G., and C. Bormann, "An 909 architecture for authorization in constrained 910 environments", draft-ietf-ace-actors-02 (work in 911 progress), September 2015. 913 [I-D.ietf-ace-usecases] 914 Seitz, L., Gerdes, S., Selander, G., Mani, M., and S. 915 Kumar, "ACE use cases", draft-ietf-ace-usecases-09 (work 916 in progress), October 2015. 918 [I-D.ietf-core-block] 919 Bormann, C. and Z. Shelby, "Block-wise transfers in CoAP", 920 draft-ietf-core-block-18 (work in progress), September 921 2015. 923 [I-D.ietf-cose-msg] 924 Schaad, J. and B. Campbell, "CBOR Encoded Message Syntax", 925 draft-ietf-cose-msg-05 (work in progress), September 2015. 927 [I-D.seitz-ace-core-authz] 928 Seitz, L., Selander, G., and M. Vucinic, "Authorization 929 for Constrained RESTful Environments", draft-seitz-ace- 930 core-authz-00 (work in progress), June 2015. 932 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", FYI 933 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 934 . 936 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 937 RFC 5652, DOI 10.17487/RFC5652, September 2009, 938 . 940 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 941 Constrained-Node Networks", RFC 7228, DOI 10.17487/ 942 RFC7228, May 2014, 943 . 945 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 946 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, DOI 947 10.17487/RFC7231, June 2014, 948 . 950 Appendix A. COSE Profile of SM 952 This section defines a profile of the 05-version of COSE 953 [I-D.ietf-cose-msg] complying with the Secure Message format (see 954 Section 4) and supporting the two scopes of object security OSCOAP 955 and OSCON (Appendix C). In the last subsection we elaborate on 956 possible optimizations. 958 o The "COSE_MSG" top level object as defined in COSE corresponds to 959 the Secure Message object. 961 o The "msg_type" parameter corresponds to the Secure Message type, 962 as defined in Section 4.2. Depending on the use case, this field 963 can take the values msg_type_mac, msg_type_signed or 964 msg_type_encryptData. 966 o The "Header" field of the COSE object corresponds to the Header 967 field of the Secure Message. 969 * The "protected" field includes: 971 + the new "seq" parameter corresponding to the parameter 972 Sequence Number of the Secure Message (see Section 4.1). 974 * The "unprotected" field is empty. 976 A.1. Integrity Protection Only 978 When Integrity Protection only needs to be provided, the Secure 979 Message object corresponds to a COSE_MSG with msg_type equal to 980 msg_type_signed (COSE_Sign) or msg_type_mac (COSE_mac). 982 The Externally Supplied Data ("external_aad" field), as defined in 983 Section 4.1 of [I-D.ietf-cose-msg] include the Authenticated Data as 984 defined in Section 5.1.2 with the exception of SM Header and CoAP 985 Payload. 987 A.1.1. COSE_Sign 989 A COSE_MSG of type COSE_Sign is a Secure Message if its fields are 990 defined as follows (see example in Appendix B.2). 992 The "Headers" field of COSE_Sign as defined in Appendix A. 994 The "payload" field contains the CoAP Payload (if any). 996 The "signatures" array contains one "COSE_signature" item. The 997 "Headers" field of the COSE_signature object is defined as follows: 999 o The "protected" field includes: 1001 * the new "cid" parameter which corresponds to the parameter 1002 Context Identifier of the Secure Message (see Section 4.1); 1004 o The "unprotected" field is empty. 1006 The "signature" field contains the computed signature value as 1007 described in Section 4.2 of [I-D.ietf-cose-msg]. 1009 A Secure Message with digital signature and Detached Content 1010 corresponds to COSE_sign with "Headers" and "signatures" fields; i.e. 1011 no "payload" field. 1013 A.1.2. COSE_mac 1015 A COSE_MSG of type COSE_mac is a Secure Message if its fields are 1016 defined as follows (see example in Appendix B.1). 1018 The "Headers" field of COSE_mac as defined in Appendix A. 1020 The "payload" field contains the CoAP Payload (if any). 1022 The "tag" field contains the MAC value, computed as defined in 1023 Section 6.1 of [I-D.ietf-cose-msg]. 1025 The "recipients" array contains one "COSE_recipient" item (section 5 1026 of [I-D.ietf-cose-msg]). The "COSE_recipient" item contains one 1027 "COSE_encrypt_fields" object. The "Headers" field of the 1028 COSE_encrypt_fields object is defined as follows: 1030 o The "protected" field includes: 1032 * the new "cid" parameter which corresponds to the parameter 1033 Context Identifier of the Secure Message (see Section 4.1); 1035 o The "unprotected" field is empty. 1037 A Secure Message with MAC and Detached Content corresponds to a 1038 COSE_sign with "Headers", "recipients" and "tag" fields; i.e. no 1039 "payload" field. 1041 A.2. Encryption and Integrity Protection: COSE_enveloped 1043 When Encryption and Integrity Protection need to be provided, the 1044 Secure Message object corresponds to a COSE_MSG with msg_type equal 1045 to msg_type_enveloped (COSE_enveloped). 1047 The Additional Authenticated Data ("Enc_structure") as described is 1048 Section 5.3 of [I-D.ietf-cose-msg] is defined in Section 5.2.2: * the 1049 "protected" parameters includes the SM Header; * the "external_aad" 1050 includes the other fields (CoAP Version, Code, Options to integrity 1051 protect and TID). 1053 The plain text, as mentioned in Sections 5.3 and 5.4 of 1054 [I-D.ietf-cose-msg] is defined in Section 5.2.2 and contains CoAP 1055 Options to encrypt and the CoAP Payload. 1057 A COSE_MSG of type COSE_enveloped [I-D.ietf-cose-msg] is a Secure 1058 Message if its fields are defined as follows (see example in 1059 Appendix B.3). 1061 The "Headers" field of COSE_encrypt_fields item as defined in 1062 Appendix A. 1064 The "ciphertext" field is encoded as a nil type, following the 1065 specifications in Section 5.1 of [I-D.ietf-cose-msg]. 1067 The "recipients" array contains one "COSE_recipient" item 1068 (Section 5.1 of [I-D.ietf-cose-msg]). The "COSE_recipient" item 1069 contains one "COSE_encrypt_fields" object. The "Headers" field of 1070 the COSE_encrypt_fields object is defined as follows: 1072 o The "protected" field includes: 1074 * the new "cid" parameter which corresponds to the parameter 1075 Context Identifier of the Secure Message (see Section 4.1); 1077 o The "unprotected" field is empty. 1079 The "ciphertext" field of the COSE_encrypt_fields object contains the 1080 encrypted plain text, as defined in section 5 of [I-D.ietf-cose-msg]. 1082 A.3. COSE Optimizations 1084 For constrained environments it is important that the message 1085 expansion due to security overhead is kept at a minimum. 1087 This section lists potential optimizations of COSE 1088 [I-D.ietf-cose-msg] for the purpose of reducing message size and 1089 improving performance in constrained node networks. The message 1090 sizes resulting from the first four optimizations are presented in 1091 Appendix B (as "modified COSE"). 1093 1. The first improvement proposed is to flatten the structure of the 1094 COSE_msg, following the Encrypted COSE structure defined in 1095 Section 5.2 of [I-D.ietf-cose-msg]. In fact, there is little 1096 need to support multiple signatures or recipients in the use 1097 cases targeting the most constrained devices. Two different 1098 structures inspired by the COSE_encryptData are defined: COSE_ip 1099 and COSE_en. COSE_ip is used for the Integrity Protection Only 1100 use case (Section 5.1), COSE_en is used for Encryption 1101 (Section 5.2). 1103 2. In general, the security context defines uniquely the cipher 1104 suite, and hence the "alg" parameter of COSE_msg can be removed. 1106 3. The "unprotected" field is not used since it is assumed that all 1107 parameters should be protected when possible. Thus the "Headers" 1108 structure can be flattened into a "protectedHeader" field, 1109 containing the "cid" parameter and the "seq" parameter. 1111 4. Analogous to other key values, one-byte keys/labels can be 1112 assigned to the new parameters defined in this document and 1113 cipher suites adapted to constrained device processing. For 1114 example: "cid" = 11 and "seq" = 12. 1116 5. Digitally signed messages have the largest absolute overhead due 1117 to the size of the signature (see Appendix B.2 and Appendix B.4). 1118 Whereas certain MACs can be securely truncated, signatures 1119 cannot. Signature schemes with message recovery allow some 1120 remedy since they allow part of the message to be recovered from 1121 the signature itself and thus need not be sent. The effective 1122 size of the signature could in this way be considerably reduced, 1123 which would have a large impact on the message size (compare size 1124 of signature and total overhead in Figure 5 and Figure 6). A 1125 valuable optimization would thus be to support signature schemes 1126 with message recovery. 1128 Combining the first 4 points, the resulting structures and their 1129 fields are defined as follows: COSE_ip top level object corresponds 1130 to the Secure Message object. 1132 o The "msg_type" parameter takes a new value, 1133 msg_type_integrityprotection=5. 1135 o The "protectedHeader" field, analogous to the "protected" field of 1136 the "Headers", includes: 1138 * the new "cid" parameter which corresponds to the parameter 1139 Context Identifier of the Secure Message (see Section 4.1); 1141 * the new "seq" parameter corresponding to the parameter Sequence 1142 Number of the Secure Message (see Section 4.1). 1144 o The "payload" field (as described in Appendix A.1.1 and 1145 Appendix A.1.2). 1147 o The "tag" field (as described in Appendix A.1.1 and 1148 Appendix A.1.2). 1150 COSE_en top level object corresponds to the Secure Message object. 1152 o The "msg_type" parameter takes a new value, msg_type_encryption=6. 1154 o The "protectedHeader" field, analogous to the "protected" field of 1155 the "Headers", includes: 1157 * the new "cid" parameter which corresponds to the parameter 1158 Context Identifier of the Secure Message (see Section 4.1); 1160 * the new "seq" parameter corresponding to the parameter Sequence 1161 Number of the Secure Message (see Section 4.1). 1163 o The "ciphertext" field (as described in Appendix A.2). 1165 o The "tag" field contains the tag value in case Integrity 1166 Protection is also provided. 1168 Appendix B. Comparison of message sizes 1170 This section gives some examples of overhead incurred with the 1171 current proposal for COSE at the time of writing [I-D.ietf-cose-msg]. 1172 Message sizes are also listed for a modified version of COSE 1173 implementing some of the optimizations described in Appendix A.3 and 1174 for a lower bound CBOR encoding of the Secure Message with structure 1175 [seq, cid, body, tag]. 1177 Motivated by the use cases, there are four different kinds of 1178 protected messages that need to be supported: message authentication 1179 code, digital signature, authenticated encryption, and symmetric 1180 encryption + digital signature. The latter is relevant e.g. for 1181 proxy-caching and publish-subscribe with untrusted intermediary (see 1182 Appendix D.2). The sizes estimated for selected algorithms are 1183 detailed in the subsections. 1185 The size of the header is shown separately from the size of the MAC/ 1186 signature. An 8-byte Context Identifier and a 3-byte Sequence Number 1187 are used throughout all examples, with these value: 1189 o cid: 0xa1534e3c5fdc09bd 1191 o seq: 0x112233 1192 For each scheme, we indicate the fixed length of these two parameters 1193 ("seq+cid" column) and of the tag ("MAC"/"SIG"/"TAG"). The "Total 1194 Size" column shows the total Secure Message size, while the 1195 "Overhead" column is calculated from the previous columns following 1196 this equation: 1198 Overhead = Total Size - (MAC + seq+cid) 1200 This means that overhead incurring from CBOR encoding is also 1201 included in the Overhead count. 1203 To make it easier to read, COSE objects are represented using CBOR's 1204 diagnostic notation rather than a binary dump. 1206 B.1. MAC Only 1208 This example is based on HMAC-SHA256, with truncation to 16 bytes. 1210 The object in COSE encoding gives: 1212 [ 1213 3, # msg_type 1214 h'a201046373657143112233', # protected: 1215 {1: 4, 1216 "seq": h'112233'} 1217 {}, # unprotected 1218 h'', # payload 1219 MAC, # truncated 16-byte MAC 1220 [ # recipients 1221 [ # recipient structure 1222 h'', # protected 1223 {1:-6, "cid":h'a1534e3c5fdc09bd'}, # unprotected 1224 h'' # ciphertext 1225 ] 1226 ] 1227 ] 1229 The COSE object encodes to a total size of 53 bytes. 1231 In the modified version of COSE defined in Appendix A.3, the 1232 equivalent COSE object would be: 1234 [ 1235 5, # msg_type 1236 h'a20b48a1534e3c5fdc09bd0c43112233', # protected: 1237 {11:h'a1534e3c5fdc09bd', 1238 12:h'112233'} 1239 h'', # payload 1240 MAC # truncated 16-byte MAC 1241 ] 1243 This modified COSE object encodes to a total size of 37 bytes. 1245 The low-bound CBOR encoding of this same object is encoded by: 1247 [ 1248 h'112233', # seq 1249 h'a1534e3c5fdc09bd', # cid 1250 h'', # payload 1251 MAC # truncated 16-byte MAC 1252 ] 1254 This object encodes to a total size of 32 bytes. 1256 Figure 3 summarizes these results. 1258 +--------+---------+------+------------+----------+ 1259 | Scheme | seq+cid | MAC | Total Size | Overhead | 1260 +--------+---------+------+------------+----------+ 1261 | COSE | 11 B | 16 B | 53 bytes | 26 bytes | 1262 +--------+---------+------+------------+----------+ 1263 |mod-COSE| 11 B | 16 B | 37 bytes | 10 bytes | 1264 +--------+---------+------+------------+----------+ 1265 | bound | 11 B | 16 B | 32 bytes | 5 bytes | 1266 +--------+---------+------+------------+----------+ 1268 Figure 3: Comparison of COSE, modified COSE and CBOR lower bound for 1269 HMAC-SHA256. 1271 B.2. Signature Only 1273 This example is based on ECDSA, with a signature of 64 bytes. 1275 The object in COSE encoding gives: 1277 [ 1278 1, # msg_type 1279 h'a16373657143112233', # protected: 1280 {"seq": h'112233'} 1281 {}, # unprotected 1282 h'', # payload 1283 [ # signatures 1284 [ # signature structure 1285 h'a201266363696448a1534e3c5fdc09bd', # protected: 1286 {1: -7, 1287 "cid":h'a1534e3c5fdc09bd'} 1288 {}, # unprotected 1289 SIG # 64-byte signature 1290 ] 1291 ] 1292 ] 1294 The COSE object encodes to a total size of 100 bytes. 1296 In the modified version of COSE defined in Appendix A.3, the 1297 equivalent COSE object would be: 1299 [ 1300 5, # msg_type 1301 h'a20b48a1534e3c5fdc09bd0c43112233', # protected: 1302 {11:h'a1534e3c5fdc09bd', 1303 12:h'112233'} 1304 h'', # payload 1305 SIG # 64-byte signature 1306 ] 1308 The COSE object encodes to a total size of 86 bytes. 1310 The low-bound CBOR encoding of this same object is encoded by: 1312 [ 1313 h'112233', # seq 1314 h'a1534e3c5fdc09bd', # cid 1315 h'', # payload 1316 SIG # 64-byte signature 1317 ] 1319 This object encodes to a total size of 81 bytes. 1321 Figure 4 summarizes these results. 1323 +--------+---------+------+------------+----------+ 1324 | Scheme | seq+cid | SIG | Total Size | Overhead | 1325 +--------+---------+------+------------+----------+ 1326 | COSE | 11 B | 64 B | 100 bytes | 25 bytes | 1327 +--------+---------+------+------------+----------+ 1328 |mod-COSE| 11 B | 64 B | 86 bytes | 11 bytes | 1329 +--------+---------+------+------------+----------+ 1330 | bound | 11 B | 64 B | 81 bytes | 6 bytes | 1331 +--------+---------+------+------------+----------+ 1333 Figure 4: Comparison of COSE, modified COSE and CBOR lower bound for 1334 64 byte ECDSA signature. 1336 B.3. Authenticated Encryption with Additional Data (AEAD) 1338 This example is based on AES-128-CCM-8. 1340 It is assumed that the IV is generated from the Sequence Number and 1341 some previously agreed upon Salt. This means it is not required to 1342 explicitly send the whole IV in the message. 1344 The object in COSE encoding gives: 1346 [ 1347 2, # msg_type 1348 h'a201046373657143112233', # protected: 1349 {1: 4, 1350 "seq": h'112233'} 1351 {}, # unprotected 1352 TAG, # 8byte authentication tag 1353 [ # recipients 1354 [ # recipient structure 1355 h'', # protected 1356 {1:-6, "cid":h'a1534e3c5fdc09bd'}, # unprotected 1357 h'' # ciphertext 1358 ] 1359 ] 1360 ] 1362 The COSE object encodes to a total size of 44 bytes. 1364 In the modified version of COSE defined in Appendix A.3, the 1365 equivalent COSE object would be: 1367 [ 1368 6, # msg_type 1369 h'a20b48a1534e3c5fdc09bd0c43112233', # protected: 1370 {11:h'a1534e3c5fdc09bd', 1371 12:h'112233'} 1372 h'', # ciphertext 1373 TAG # 8byte authentication tag 1374 ] 1376 The modified COSE object encodes to a total size of 29 bytes. 1378 The low-bound CBOR encoding of this same object is encoded by: 1380 [ 1381 h'112233', # seq 1382 h'a1534e3c5fdc09bd', # cid 1383 h'', # ciphertext 1384 TAG # 8byte authentication tag 1385 ] 1387 This object encodes to a total size of 24 bytes. 1389 Figure 5 summarizes these results. 1391 +--------+---------+-----+------------+----------+ 1392 | Scheme | seq+cid | TAG | Total Size | Overhead | 1393 +--------+---------+-----+------------+----------+ 1394 | COSE | 11 B | 8 B | 44 bytes | 25 bytes | 1395 +--------+---------+-----+------------+----------+ 1396 |mod-COSE| 11 B | 8 B | 29 bytes | 10 bytes | 1397 +--------+---------+-----+------------+----------+ 1398 | bound | 11 B | 8 B | 24 bytes | 5 bytes | 1399 +--------+---------+-----+------------+----------+ 1401 Figure 5: Comparison of COSE, modified COSE and CBOR lower bound for 1402 AES-CCM. 1404 B.4. Symmetric Encryption with Asymmetric Signature (SEAS) 1406 This example is based on AES-128-CTR and ECDSA with 64 bytes 1407 signature. COSE requires this to be a nested encapsulation of one 1408 object into another, here illustrated with a digitally signed AEAD 1409 protected object. 1411 The object in COSE encoding gives: 1413 [ 1414 1, # msg_type 1415 h'a16373657143112233', # protected: 1416 {"seq": h'112233'} 1417 {}, # unprotected 1418 h'85024ba2010a6373657143112233a04081834 1419 0a201256363696448a1534e3c5fdc09bd40', # payload: 1420 [2, 1421 h'a2010a6373657143112233', 1422 {}, h', [[h'', 1423 {1: -6, 1424 "cid": h'a1534e3c5fdc09bd' 1425 }, h'']]] 1426 [ # signatures 1427 [ # signature structure 1428 h'a201266363696448a1534e3c5fdc09bd', # protected: 1429 {1: -7, 1430 "cid":h'a1534e3c5fdc09bd'} 1431 {}, # unprotected 1432 SIG # 64-byte signature 1433 ] 1434 ] 1435 ] 1437 The COSE object encodes to a total size of 134 bytes. 1439 In the modified version of COSE defined in Appendix A.3, the 1440 equivalent COSE object would be: 1442 [ 1443 6, # msg_type 1444 h'a20b48a1534e3c5fdc09bd0c43112233', # protected: 1445 {11:h'a1534e3c5fdc09bd', 1446 12:h'112233'} 1447 h'', # ciphertext 1448 SIG # 64-byte signature 1449 ] 1451 This modified COSE object encodes to a total size of 86 bytes. 1453 The low-bound CBOR encoding of this same object is encoded by: 1455 [ 1456 h'112233', # seq 1457 h'a1534e3c5fdc09bd', # cid 1458 h'', # ciphertext 1459 SIG # 64-byte signature 1460 ] 1461 This object encodes to a total size of 81 bytes. 1463 Figure 6 summarizes these results. 1465 +--------+---------+------+------------+----------+ 1466 | Scheme | seq+cid | SIG | Total Size | Overhead | 1467 +--------+---------+------+------------+----------+ 1468 | COSE | 11 B | 64 B | 134 bytes | 59 bytes | 1469 +--------+---------+------+------------+----------+ 1470 |mod-COSE| 11 B | 64 B | 86 bytes | 11 bytes | 1471 +--------+---------+------+------------+----------+ 1472 | bound | 11 B | 64 B | 81 bytes | 6 bytes | 1473 +--------+---------+------+------------+----------+ 1475 Figure 6: Comparison of nested AES-CCM within ECDSA (COSE) and 1476 combined AES-ECDSA (modified COSE and CBOR lower bound). 1478 Appendix C. Object Security of Content (OSCON) 1480 In this section we define how to only protect the payload/content of 1481 individual messages using the Secure Message format (Section 4) to 1482 comply with the requirements 1 and 2 in Section 2. This is referred 1483 to as Object Security of Content (OSCON). 1485 Note that by only protecting the content of a message it may be 1486 verified by multiple recipients. For example, in the case of a proxy 1487 that supports caching, a recent response for a certain resource can 1488 be cached and used to serve multiple clients. Or, in a publish- 1489 subscribe setting, multiple subscribers can be served the same 1490 publication. The use of content protection also decouples the 1491 binding to the underlying transfer protocol, so the same protected 1492 content object can be freely move between CoAP, HTTP, BlueTooth or 1493 whatever application layer protocol. 1495 The use of OSCON is signaled with the Content-Format/Media Type set 1496 to application/oscon (Section 10). Since the actual format of the 1497 content which is protected is lost, that information needs to be 1498 added to the message header or known to the recipient. 1500 The sending endpoint SHALL wrap the Payload, and the receiving 1501 endpoint unwrap the Payload in the SM format as described in this 1502 section. A CoAP client MAY request a response in the OSCON format by 1503 setting the option Accept to application/oscon. 1505 In case of cipher suite for integrity protection only, the 1506 Authenticated Data SHALL be the concatenation of the SM Header and 1507 the CoAP Payload. If case of cipher suite for both encryption and 1508 integrity protection, then the AAD SHALL be the SM Header and the 1509 Plaintext SHALL be the CoAP Payload. By default, cipher suites for 1510 encryption and integrity protection SHALL be used. 1512 The SM SHALL be protected (encrypted) and verified (decrypted) as 1513 described in Section 5.1.3 (Section 5.2.2.1), including replay 1514 protection as described in Section 7.1. 1516 Whereas in OSCOAP, the Context Identifier of the SM Header 1517 (Section 4.1) typically identifies the sending party, with OSCON 1518 (Appendix C) the Context Identifier may well identify the sender and 1519 resource. 1521 C.1. Security Considerations of OSCON 1523 OSCON (Appendix C) only protects payload and only gives replay 1524 protection (not freshness of response), but allows additional use 1525 cases such as point to multi-point interactions including publish- 1526 subscribe, reverse proxies and proxy caching of responses. In case 1527 of symmetric keys the receiver does not get data origin 1528 authentication, which requires a digital signature using a private 1529 asymmetric key. 1531 OSCON SHALL NOT be used in cases where CoAP header fields (such as 1532 Code or Version) or CoAP options need to be integrity protected. The 1533 request for a response in OSCON using the CoAP option Accept set to 1534 "application/oscon" is not secured since OSCON does not integrity 1535 protect any options. Hence the exchange of OSCON request-response 1536 messages is vulnerable to a man-in-the-middle attack where response 1537 is exchanged for another response, but since there is replay 1538 protection only messages with higher sequence numbers will be 1539 accepted. 1541 Blockwise transfers in CoAP as defined in [I-D.ietf-core-block] can 1542 be applied with OSCON, i.e. the entire payload is encapsulated in a 1543 Secure Message which is partitioned into blocks which are sent with 1544 unprotected CoAP. The receiver is able to verify the integrity of 1545 the payload but only after the last block containing the signature/ 1546 MAC is received, and if the verification fails the entire message 1547 needs to be resent. However, if the verification succeeds, then the 1548 transmission in OSCON has less computational and packet overhead 1549 since only one signature/MAC was generated and sent. As CoAP 1550 blockwise transfer with OSCON is prone to Denial of Service attacks, 1551 it should only be used for exchanges where this threat can be 1552 mitigated, for example within a local area network where link-layer 1553 security is activated. 1555 Appendix D. Examples 1557 This section gives examples of how to use the Object-Security option 1558 and the message formats defined in this memo. 1560 D.1. CoAP Message Protection 1562 This section illustrates Object Security of CoAP (OSCOAP). The 1563 message exchange assumes there is a security context established 1564 between client and server. One key is used for each direction of the 1565 message transfer. The intermediate node detects that the CoAP 1566 message contains an OSCOAP object (Object-Security option is set) and 1567 thus forwards the message as it cannot serve a cached response. 1569 D.1.1. Integrity Protection of CoAP Message Exchange 1571 Here is an example of a PUT request/response message exchange passing 1572 an intermediate node protected with the Object-Security option. The 1573 example illustrates a client closing a lock (PUT 1) and getting a 1574 confirmation that the lock is closed. Code, Uri-Path and Payload of 1575 the request and Code of the response are integrity protected (and 1576 other message fields, see Section 6.1 and Section 6.2). 1578 Client Proxy Server 1579 | | | 1580 | | | 1581 | | | 1582 +----->| | Code: 0.03 (PUT) 1583 | PUT | | Token: 0x8c 1584 | | | Uri-Path: lock 1585 | | | Object-Security: 1586 | | | Payload: ["seq":"142", 1587 | | | "cid":"a1534e3c5fdc09bd", 1, ] 1588 | | | 1589 | +----->| Code: 0.03 (PUT) 1590 | | PUT | Token: 0x7b 1591 | | | Uri-Path: lock 1592 | | | Object-Security: 1593 | | | Payload: ["seq":"142", 1594 | | | "cid":"a1534e3c5fdc09bd", 1, ] 1595 | | | 1596 | |<-----+ Code: 2.04 (Changed) 1597 | | 2.04 | Token: 0x7b 1598 | | | Object-Security: ["seq":"a6", 1599 | | | "cid":"5fdc09bda1534e3c", , ] 1600 | | | 1601 |<-----+ | Code: 2.04 (Changed) 1602 | 2.04 | | Token: 0x8c 1603 | | | Object-Security: ["seq":"a6", 1604 | | | "cid":"5fdc09bda1534e3c", , ] 1605 | | | 1607 Figure 7: CoAP PUT protected with OSCOAP 1609 Since the request message (PUT) supports payload, the OSCOAP object 1610 is carried in the CoAP payload. Since the response message (Changed) 1611 does not supports payload the Object-Security option carries the 1612 OSCOAP object. 1614 The Header contains Sequence Number ("seq":"a6") and Context 1615 Identifier ("cid":"5fdc09bda1534e3c"), the latter is an identifier 1616 indicating which security context was used to integrity protect the 1617 message, and may be used as an identifier for a secret key or a 1618 public key. (It may e.g. be the hash of a public key.) 1620 The server and client can verify that the Sequence Number has not 1621 been received and used with this key before. With OSCOAP, the client 1622 additionally verifies the freshness of the response, i.e. that the 1623 response message is generated as an answer to the received request 1624 message (see Section 7). 1626 This example deviates from encryption by default (see Section 8) just 1627 to illustrate the case of Integrity Protection only. If there is no 1628 compelling reason why the CoAP message should be in plaintext, then 1629 it MUST be encrypted. 1631 D.1.2. Additional Encryption of CoAP Message 1633 Here is an example of a GET request/response message exchange passing 1634 an intermediate node protected with the Enc option. The example 1635 illustrates a client requesting a blood sugar measurement resource 1636 (GET /glucose) and receiving the value 220 mg/dl. Uri-Path and 1637 Payload are encrypted and integrity protected. Code is integrity 1638 protected only (see Section 6.1 and Section 6.2). 1640 Client Proxy Server 1641 | | | 1642 | | | 1643 | | | 1644 +----->| | Code: 0.01 (GET) 1645 | GET | | Token: 0x83 1646 | | | Object-Security: ["seq":"15b7", 1647 | | | "cid":"34e3c5fdca1509bd", 1648 | | | {"glucose"}, ] 1649 | | | 1650 | +----->| Code: 0.01 (GET) 1651 | | GET | Token: 0xbe 1652 | | | Object-Security: ["seq":"15b7", 1653 | | | "cid":"34e3c5fdca1509bd", 1654 | | | {"glucose"}, ] 1655 | | | 1656 | | | 1657 | |<-----+ Code: 2.05 (Content) 1658 | | 2.05 | Token: 0xbe 1659 | | | Object-Security: 1660 | | | Payload: ["seq":"32c9", 1661 | | | "cid":"c09bda155fd34e3c", 1662 | | | {220}, ] 1663 | | | 1664 |<-----+ | Code: 2.05 (Content) 1665 | 2.05 | | Token: 0x83 1666 | | | Object-Security: 1667 | | | Payload: ["seq":"32c9", 1668 | | | "cid":"c09bda155fd34e3c", 1669 | | | {220}, ] 1670 | | | 1672 Figure 8: CoAP GET protected with OSCOAP. The bracket { ... } 1673 indicates encrypted data. 1675 Since the request message (GET) does not support payload, the OSCOAP 1676 object is carried in the Object-Security option. Since the response 1677 message (Content) supports payload, the Object-Security option is 1678 empty and the OSCOAP object is carried in the payload. 1680 The Context Identifier is a hint to the receiver indicating which 1681 security context was used to encrypt and integrity protect the 1682 message, and may be used as an identifier for the AEAD secret key. 1683 One key is used for each direction of the message transfer. 1685 The server and client can verify that the Sequence Number has not 1686 been received and used with this key before, and the client 1687 additionally verifies the freshness of the response, i.e. that the 1688 response message is generated as an answer to the received request 1689 message (see Section 7). 1691 D.2. Payload Protection 1693 This section gives examples that illustrate Object Security of 1694 Content (OSCON), see Appendix C). The assumption here is that only 1695 the intended receiver(s) has the relevant security context related to 1696 the resource. In case of a closed group of recipients of the same 1697 object, e.g. in Information-Centric Networking or firmware update 1698 distribution, it may be necessary to support symmetric key encryption 1699 in combination with digital signature. 1701 D.2.1. Proxy Caching 1703 This example outlines how a proxy forwarding request and response of 1704 one client can cache a response whose payload is a OSCON object, and 1705 serve this response to another client request, such that both clients 1706 can verify integrity and non-replay. 1708 Client1 Proxy Server 1710 | | | 1711 | | | 1712 +----->| | Code: 0.01 (GET) 1713 | GET | | Token: 0x83 1714 | | | Proxy-Uri: example.com/temp 1715 | | | 1716 | | | 1717 | +----->| Code: 0.01 (GET) 1718 | | GET | Token: 0xbe 1719 | | | Uri-Host: example.com 1720 | | | Uri-Path: temp 1721 | | | 1722 | | | 1723 | |<-----+ Code: 2.05 (Content) 1724 | | 2.05 | Token: 0xbe 1725 | | | Payload: ["seq":"15b7", 1726 | | | "cid":"c09bda155fd34e3c", 1727 | | | "471 F", ] 1728 | | | 1729 |<-----+ | Code: 2.05 (Content) 1730 | 2.05 | | Token: 0x83 1731 | | | Payload: ["seq":"15b7", 1732 | | | "cid":"c09bda155fd34e3c", 1733 | | "471 F", ] 1734 Client2 | | 1735 | | 1736 | | | 1737 | | | 1738 +----->| | Code: 0.01 (GET) 1739 | GET | | Token: 0xa1 1740 | | | Proxy-Uri: example.com/temp 1741 | | | 1742 |<-----+ | Code: 2.05 (Content) 1743 | 2.05 | | Token: 0xa1 1744 | | | Payload: ["seq":"15b7", 1745 | | | "cid":"c09bda155fd34e3c", 1746 | | | "471 F", ] 1748 Figure 9: Proxy caching protected with Object Security of Content 1749 (OSCON) 1751 D.2.2. Publish-Subscribe 1753 This example outlines a publish-subscribe setting where the payload 1754 is encrypted, integrity and replay protected end-to-end between 1755 Publisher and Subscriber. The example applies for example to closed 1756 user groups of a single data source and illustrates a subscription 1757 registration and a later publication of birch pollen count of 300 per 1758 cubic meters. The PubSub Broker can define the Observe count 1759 arbitrarily (as could any intermediary node, even in OSCOAP), but 1760 cannot manipulate the Sequence Number without being possible to 1761 detect. 1763 Sub- PubSub- Pub- 1764 scriber Broker lisher 1766 | | | 1767 +----->| | Code: 0.01 (GET) 1768 | GET | | Token: 0x72 1769 | | | Uri-Path: ps 1770 | | | Uri-Path: birch-pollen 1771 | | | Observe: 0 (register) 1772 | | | 1773 | | | 1774 |<-----+ | Code: 2.05 (Content) 1775 | 2.05 | | Token: 0x72 1776 | | | Observe: 1 1777 | | | Payload: ["seq":"15b7", 1778 | | | "cid":"c09bda155fd34e3c", 1779 | | | {"270"}, ] 1780 | | | 1781 | | | 1782 | | | 1783 | |<-----+ Code: 0.03 (PUT) 1784 | | PUT | Token: 0x1f 1785 | | | Uri-Path: ps 1786 | | | Uri-Path: birch-pollen 1787 | | | Payload: ["seq":"15b8", 1788 | | | "cid":"c09bda155fd34e3c", 1789 | | | {"300"}, ] 1790 | | | 1791 | +----->| Code: 2.04 (Changed) 1792 | | 2.04 | Token: 0x1f 1793 | | | 1794 | | | 1795 |<-----+ | Code: 2.05 (Content) 1796 | 2.05 | | Token: 0x72 1797 | | | Observe: 2 1798 | | | Payload: ["seq":"15b8", 1799 | | | "cid":"c09bda155fd34e3c", 1800 | | | {"300"}, ] 1802 Figure 10: Publish-subscribe protected with OSCON. The bracket { ... 1803 } indicates encrypted data. 1805 This example deviates from encryption by default (see Section 8) just 1806 to illustrate Integrity Protection only in the case of OSCON. If 1807 there is no compelling reason why the payload should be in plaintext, 1808 then encryption MUST be used. 1810 D.2.3. Transporting Authorization Information 1812 This example outlines the transportation of authorization information 1813 from a node producing (Authorization Server, AS) to a node consuming 1814 (Resource Server, RS) such information. Authorization information 1815 may for example be an authorization decision with respect to a Client 1816 (C) accessing a Resource to be enforced by RS, see e.g. 1817 [I-D.ietf-ace-actors] or [I-D.seitz-ace-core-authz]. Here, C is 1818 clearly not trusted with modifying the information, but may need to 1819 be involved in mediating the authorization information to the RS, for 1820 example, because AS and RS does not have direct connectivity. So 1821 end-to-end security is required and object security ("access tokens") 1822 is the natural candidate. 1824 This example considers the authorization information to be 1825 encapsulated in a OSCON object, generated by AS. How C accesses the 1826 OSCON object is out of scope for this example, it may e.g. be using 1827 CoAP. C then requests RS to configure the authorization information 1828 in the OSCON object by doing POST to /authz-info. This particular 1829 resource has a default access policy that only new messages signed by 1830 AS are authorized. RS thus verifies the integrity and sequence 1831 number by using the existing security context for the AS, and 1832 responds accordingly, a) or b), see Figure 11. 1834 Authz Resource 1835 Server Client Server 1836 | | | 1837 | | | Client accesses Access Token: 1838 +- - ->| | ["seq":"142", 1839 | | | "cid":"c09bda1534e3c5fdc09bd", 1840 | | | , ] 1841 | | | 1842 | +----->| Code: 0.02 (POST) 1843 | | POST | Token: 0xac 1844 | | | Uri-Path: authz-info 1845 | | | Payload: ["seq":"142", 1846 | | | "cid":"c09bda1534e3c5fdc09bd", 1847 | | | , ] 1849 a) 1850 | | | 1851 | |<-----+ Code: 2.04 (Changed) 1852 | | 2.04 | Token: 0xac 1853 | | | 1855 b) 1856 | | | 1857 | |<-----+ Code: 4.01 (Unauthorized) 1858 | | 4.01 | Token: 0xac 1859 | | | 1861 Figure 11: Protected Transfer of Access Token using OSCON 1863 Authors' Addresses 1865 Goeran Selander 1866 Ericsson 1867 Farogatan 6 1868 Kista 16480 1869 Sweden 1871 Email: goran.selander@ericsson.com 1873 John Mattsson 1874 Ericsson 1875 Farogatan 6 1876 Kista 16480 1877 Sweden 1879 Email: john.mattsson@ericsson.com 1880 Francesca Palombini 1881 Ericsson 1882 Farogatan 6 1883 Kista 16480 1884 Sweden 1886 Email: francesca.palombini@ericsson.com 1888 Ludwig Seitz 1889 SICS Swedish ICT 1890 Scheelevagen 17 1891 Lund 22370 1892 Sweden 1894 Email: ludwig@sics.se