idnits 2.17.1 draft-ietf-cose-countersign-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 784 has weird spacing: '...otected h'a10...' -- The document date (16 December 2020) is 1226 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) -- Possible downref: Normative reference to a draft: ref. 'I-D.ietf-cbor-7049bis' ** Downref: Normative reference to an Informational draft: draft-ietf-cose-rfc8152bis-algs (ref. 'I-D.ietf-cose-rfc8152bis-algs') -- Obsolete informational reference (is this intentional?): RFC 8152 (Obsoleted by RFC 9052, RFC 9053) == Outdated reference: A later version (-11) exists of draft-ietf-core-groupcomm-bis-02 == Outdated reference: A later version (-15) exists of draft-ietf-cose-rfc8152bis-struct-14 Summary: 1 error (**), 0 flaws (~~), 4 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 COSE Working Group J. Schaad 3 Internet-Draft August Cellars 4 Intended status: Standards Track R. Housley, Ed. 5 Expires: 19 June 2021 Vigil Security 6 16 December 2020 8 CBOR Object Signing and Encryption (COSE): Countersignatures 9 draft-ietf-cose-countersign-02 11 Abstract 13 Concise Binary Object Representation (CBOR) is a data format designed 14 for small code size and small message size. CBOR Object Signing and 15 Encryption (COSE) defines a set of security services for CBOR. This 16 document defines a countersignature algorithm along with the needed 17 header parameters and CBOR tags for COSE. 19 Contributing to this document 21 This note is to be removed before publishing as an RFC. 23 The source for this draft is being maintained in GitHub. Suggested 24 changes should be submitted as pull requests at https://github.com/ 25 cose-wg/countersign. Instructions are on that page as well. 26 Editorial changes can be managed in GitHub, but any substantial 27 issues need to be discussed on the COSE mailing list. 29 Status of This Memo 31 This Internet-Draft is submitted in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF). Note that other groups may also distribute 36 working documents as Internet-Drafts. The list of current Internet- 37 Drafts is at https://datatracker.ietf.org/drafts/current/. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 This Internet-Draft will expire on 19 June 2021. 46 Copyright Notice 48 Copyright (c) 2020 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 53 license-info) in effect on the date of publication of this document. 54 Please review these documents carefully, as they describe your rights 55 and restrictions with respect to this document. Code Components 56 extracted from this document must include Simplified BSD License text 57 as described in Section 4.e of the Trust Legal Provisions and are 58 provided without warranty as described in the Simplified BSD License. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 63 1.1. Requirements Terminology . . . . . . . . . . . . . . . . 4 64 1.2. CBOR Grammar . . . . . . . . . . . . . . . . . . . . . . 4 65 1.3. Document Terminology . . . . . . . . . . . . . . . . . . 4 66 2. Countersignature Header Parameters . . . . . . . . . . . . . 5 67 3. Version 2 Countersignatures . . . . . . . . . . . . . . . . . 6 68 3.1. Full Countersignatures . . . . . . . . . . . . . . . . . 7 69 3.2. Abbreviated Countersignatures . . . . . . . . . . . . . . 8 70 3.3. Signing and Verification Process . . . . . . . . . . . . 8 71 4. CBOR Encoding Restrictions . . . . . . . . . . . . . . . . . 10 72 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 73 5.1. CBOR Tag Assignment . . . . . . . . . . . . . . . . . . . 10 74 5.2. COSE Header Parameters Registry . . . . . . . . . . . . . 11 75 6. Security Considerations . . . . . . . . . . . . . . . . . . . 11 76 7. Implementation Status . . . . . . . . . . . . . . . . . . . . 13 77 7.1. Author's Versions . . . . . . . . . . . . . . . . . . . . 13 78 7.2. COSE Testing Library . . . . . . . . . . . . . . . . . . 14 79 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 80 8.1. Normative References . . . . . . . . . . . . . . . . . . 14 81 8.2. Informative References . . . . . . . . . . . . . . . . . 15 82 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 16 83 A.1. Use of Early Code Points . . . . . . . . . . . . . . . . 17 84 A.2. Examples of Signed Messages . . . . . . . . . . . . . . . 17 85 A.2.1. Countersignature . . . . . . . . . . . . . . . . . . 17 86 A.3. Examples of Signed1 Messages . . . . . . . . . . . . . . 18 87 A.3.1. Countersignature . . . . . . . . . . . . . . . . . . 18 88 A.4. Examples of Enveloped Messages . . . . . . . . . . . . . 19 89 A.4.1. Countersignature on Encrypted Content . . . . . . . . 19 90 A.5. Examples of Encrypted Messages . . . . . . . . . . . . . 20 91 A.5.1. Countersignature on Encrypted Content . . . . . . . . 21 92 A.6. Examples of MACed Messages . . . . . . . . . . . . . . . 21 93 A.6.1. Countersignature on MAC Content . . . . . . . . . . . 21 95 A.7. Examples of MAC0 Messages . . . . . . . . . . . . . . . . 22 96 A.7.1. Countersignature on MAC0 Content . . . . . . . . . . 22 97 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 23 98 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 23 100 1. Introduction 102 There has been an increased focus on small, constrained devices that 103 make up the Internet of Things (IoT). One of the standards that has 104 come out of this process is "Concise Binary Object Representation 105 (CBOR)" [I-D.ietf-cbor-7049bis]. CBOR extended the data model of the 106 JavaScript Object Notation (JSON) [STD90] by allowing for binary 107 data, among other changes. CBOR has been adopted by several of the 108 IETF working groups dealing with the IoT world as their encoding of 109 data structures. CBOR was designed specifically both to be small in 110 terms of messages transported and implementation size and to be a 111 schema-free decoder. A need exists to provide message security 112 services for IoT, and using CBOR as the message-encoding format makes 113 sense. 115 During the process of advancing COSE to an Internet Standard, it was 116 noticed the description of the security properties of 117 countersignatures was incorrect for the COSE_Sign1 structure. Since 118 the security properties that were described, those of a true 119 countersignature, were those that the working group desired, the 120 decision was made to remove all of the countersignature text from 121 [I-D.ietf-cose-rfc8152bis-struct] and create a new document to both 122 deprecate the old countersignature algorithm and to define a new one 123 with the desired security properties. 125 The problem with the previous countersignature algorithm was that the 126 cryptographically computed value was not always included. The 127 initial assumption that the cryptographic value was in the third slot 128 of the array was known not to be true at the time, but in the case of 129 the MAC structures this was not deemed to be an issue. The new 130 algorithm is more aggressive about the set of values included in the 131 countersignature computation so that the cryptographic computed 132 values is included. The exception to this is the COSE_Signature 133 structure where there is no cryptographic computed value. 135 The new algorithm is designed to produce the same countersignature 136 value in those cases where the cryptographic computed value was 137 already included. This means that for those structures the only 138 thing that would need to be done is to change the value of the header 139 parameter. 141 1.1. Requirements Terminology 143 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 144 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 145 "OPTIONAL" in this document are to be interpreted as described in BCP 146 14 [RFC2119] [RFC8174] when, and only when, they appear in all 147 capitals, as shown here. 149 1.2. CBOR Grammar 151 CBOR grammar in the document is presented using CBOR Data Definition 152 Language (CDDL) [RFC8610]. 154 The collected CDDL can be extracted from the XML version of this 155 document via the following XPath expression below. (Depending on the 156 XPath evaluator one is using, it may be necessary to deal with > 157 as an entity.) 159 //sourcecode[@type='CDDL']/text() 161 CDDL expects the initial non-terminal symbol to be the first symbol 162 in the file. For this reason, the first fragment of CDDL is 163 presented here. 165 start = COSE_Countersignature_Tagged / Internal_Types 167 ; This is defined to make the tool quieter: 168 Internal_Types = Countersign_structure / COSE_Countersignature0 170 The non-terminal Internal_Types is defined for dealing with the 171 automated validation tools used during the writing of this document. 172 It references those non-terminals that are used for security 173 computations but are not emitted for transport. 175 1.3. Document Terminology 177 In this document, we use the following terminology: 179 Byte is a synonym for octet. 181 Constrained Application Protocol (CoAP) is a specialized web transfer 182 protocol for use in constrained systems. It is defined in [RFC7252]. 184 Context is used throughout the document to represent information that 185 is not part of the COSE message. Information which is part of the 186 context can come from several different sources including: Protocol 187 interactions, associated key structures, and program configuration. 188 The context to use can be implicit, identified using the 'kid 189 context' header parameter defined in [RFC8613], or identified by a 190 protocol-specific identifier. Context should generally be included 191 in the cryptographic construction; for more details see Section 4.3 192 of [I-D.ietf-cose-rfc8152bis-struct]. 194 The term 'byte string' is used for sequences of bytes, while the term 195 'text string' is used for sequences of characters. 197 2. Countersignature Header Parameters 199 This section defines a set of common header parameters. A summary of 200 these header parameters can be found in Table 1. This table should 201 be consulted to determine the value of label and the type of the 202 value. 204 The set of header parameters defined in this section are: 206 V2 countersignature: This header parameter holds one or more 207 countersignature values. Countersignatures provide a method of 208 having a second party sign some data. The countersignature header 209 parameter can occur as an unprotected attribute in any of the 210 following structures: COSE_Sign1, COSE_Signature, COSE_Encrypt, 211 COSE_recipient, COSE_Encrypt0, COSE_Mac, and COSE_Mac0. Details 212 on version 2 countersignatures are found in Section 3. 214 +===========+=====+========================+==========+=============+ 215 |Name |Label|Value Type | Value | Description | 216 | | | | Registry | | 217 +===========+=====+========================+==========+=============+ 218 |counter |TBD10|COSE_Countersignature / | | V2 counter | 219 |signature | |[+ COSE_Countersignature| | signature | 220 |version 2 | |] | | attribute | 221 +-----------+-----+------------------------+----------+-------------+ 222 |counter |TBD11|COSE_Countersignature0 | | Abbreviated | 223 |signature 0| | | | Counter | 224 |version 2 | | | | signature | 225 | | | | | vesion 2 | 226 +-----------+-----+------------------------+----------+-------------+ 228 Table 1: Common Header Parameters 230 The CDDL fragment that represents the set of header parameters 231 defined in this section is given below. Each of the header 232 parameters is tagged as optional because they do not need to be in 233 every map; header parameters required in specific maps are discussed 234 above. 236 Generic_Headers /= ( 237 ? TBD10 => COSE_Countersignature / [+COSE_Countersignature] 238 ; V2 Countersignature 239 ? TBD11 => COSE_Countersignature0 ; V2 Countersignature0 240 ) 242 3. Version 2 Countersignatures 244 A countersignature is normally defined as a second signature that 245 confirms a primary signature. A normal example of a countersignature 246 is the signature that a notary public places on a document as 247 witnessing that you have signed the document. Thus applying a 248 countersignature to either the COSE_Signature or COSE_Sign1 objects 249 match this traditional definition. This document extends the context 250 of a countersignature to allow it to be applied to all of the 251 security structures defined. It needs to be noted that the 252 countersignature needs to be treated as a separate operation from the 253 initial operation even if it is applied by the same user as is done 254 in [I-D.ietf-core-groupcomm-bis]. 256 COSE supports two different forms for countersignatures. Full 257 countersignatures use the structure COSE_Countersignature. This is 258 same structure as COSE_Signature and thus it can have protected and 259 unprotected attributes, including chained countersignatures. 260 Abbreviated countersignatures use the structure 261 COSE_Countersignature0. This structure only contains the signature 262 value and nothing else. The structures cannot be converted between 263 each other; as the signature computation includes a parameter 264 identifying which structure is being used, the converted structure 265 will fail signature validation. 267 The version 2 countersignature changes the algorithm used for 268 computing the signature from the original version Section 4.5 of 269 [RFC8152]. The new version now includes the cryptographic material 270 generated for all of the structures rather than just for a subset. 272 COSE was designed for uniformity in how the data structures are 273 specified. One result of this is that for COSE one can expand the 274 concept of countersignatures beyond just the idea of signing a 275 signature to being able to sign most of the structures without having 276 to create a new signing layer. When creating a countersignature, one 277 needs to be clear about the security properties that result. When 278 done on a COSE_Signature or COSE_Sign1, the normal countersignature 279 semantics are preserved. That is the countersignature makes a 280 statement about the existence of a signature and, when used as a 281 timestamp, a time point at which the signature exists. When done on 282 a COSE_Sign, this is the same as applying a second signature to the 283 payload and adding a parallel signature as a new COSE_Signature is 284 the preferred method. When done on a COSE_Mac or COSE_Mac0, the 285 payload is included as well as the MAC value. When done on a 286 COSE_Encrypt or COSE_Encrypt0, the existence of the encrypted data is 287 attested to. It should be noted that there is a big difference 288 between attesting to the encrypted data as opposed to attesting to 289 the unencrypted data. If the latter is what is desired, then one 290 needs to apply a signature to the data and then encrypt that. It is 291 always possible to construct cases where the use of two different 292 keys will appear to result in a successful decryption (the tag check 293 success), but which produce two completely different plaintexts. 294 This situation is not detectable by a countersignature on the 295 encrypted data. 297 3.1. Full Countersignatures 299 The COSE_Countersignature structure allows for the same set of 300 capabilities as a COSE_Signature. This means that all of the 301 capabilities of a signature are duplicated with this structure. 302 Specifically, the countersigner does not need to be related to the 303 producer of what is being countersigned as key and algorithm 304 identification can be placed in the countersignature attributes. 305 This also means that the countersignature can itself be 306 countersigned. This is a feature required by protocols such as long- 307 term archiving services. More information on how countersignatures 308 is used can be found in the evidence record syntax described in 309 [RFC4998]. 311 The full countersignature structure can be encoded as either tagged 312 or untagged depending on the context it is used in. A tagged 313 COSE_Countersignature structure is identified by the CBOR tag TBD0. 314 The countersignature structure is the same as that used for a signer 315 on a signed object. The CDDL fragment for full countersignatures is: 317 COSE_Countersignature_Tagged = #6.9999(COSE_Countersignature) 318 COSE_Countersignature = COSE_Signature 320 The details of the fields of a countersignature can be found in 321 Section 4.1 of [I-D.ietf-cose-rfc8152bis-struct]. 323 An example of a countersignature on a signature can be found in 324 Appendix A.2.1. An example of a countersignature in an encryption 325 object can be found in Appendix A.4.1. 327 It should be noted that only a signature algorithm with appendix (see 328 Section 8 of [I-D.ietf-cose-rfc8152bis-struct]) can be used for 329 countersignatures. This is because the body should be able to be 330 processed without having to evaluate the countersignature, and this 331 is not possible for signature schemes with message recovery. 333 3.2. Abbreviated Countersignatures 335 Abbreviated countersignatures were designed primarily to deal with 336 the problem of encrypted group messaging, but where it is required to 337 know who originated the message. The objective was to keep the 338 countersignature as small as possible while still providing the 339 needed security. For abbreviated countersignatures, there is no 340 provision for any protected attributes related to the signing 341 operation. Instead, the parameters for computing or verifying the 342 abbreviated countersignature are provided by the same context used to 343 describe the encryption, signature, or MAC processing. 345 The CDDL fragment for the abbreviated countersignatures is: 347 COSE_Countersignature0 = bstr 349 The byte string representing the signature value is placed in the 350 Countersignature0 attribute. This attribute is then encoded as an 351 unprotected header parameter. The attribute is defined below. 353 3.3. Signing and Verification Process 355 In order to create a signature, a well-defined byte string is needed. 356 The Countersign_structure is used to create the canonical form. This 357 signing and verification process takes in countersignature target 358 structure, the signer information (COSE_Signature), and the 359 application data (external source). A Countersign_structure is a 360 CBOR array. The target structure of the countersignature needs to 361 have all of it's cryptographic functions finalized before the 362 computing the signature. The fields of the Countersign_structure in 363 order are: 365 1. A context text string identifying the context of the signature. 366 The context text string is: 368 "CounterSignature" for signatures using the 369 COSE_Countersignature structure when other_fields is absent. 371 "CounterSignature0" for signatures using the 372 COSE_Countersignature0 structure when other_fields is absent. 374 "CounterSignatureV2" for signatures using the 375 COSE_Countersignature structure when other_fields is present. 377 "CounterSignature0V2" for signatures using the 378 COSE_Countersignature0 structure when other_fields is present. 380 2. The protected attributes from the target structure encoded in a 381 bstr type. If there are no protected attributes, a zero-length 382 byte string is used. 384 3. The protected attributes from the signer structure encoded in a 385 bstr type. If there are no protected attributes, a zero-length 386 byte string is used. This field is omitted for the 387 Countersignature0V2 attribute. 389 4. The externally supplied data from the application encoded in a 390 bstr type. If this field is not supplied, it defaults to a zero- 391 length byte string. (See Section 4.3 of 392 [I-D.ietf-cose-rfc8152bis-struct] for application guidance on 393 constructing this field.) 395 5. The payload to be signed encoded in a bstr type. The payload is 396 placed here independent of how it is transported. 398 6. If there are only two bstr fields in the target structure, this 399 field is omitted. The field is an array of all bstr fields after 400 the second. As an example, this would be an array of one element 401 for the COSE_Sign1 structure containing the signature value. 403 The CDDL fragment that describes the above text is: 405 Countersign_structure = [ 406 context : "CounterSignature" / "CounterSignature0" / 407 "CounterSignatureV2" / "CounterSignature0V2" /, 408 body_protected : empty_or_serialized_map, 409 ? sign_protected : empty_or_serialized_map, 410 external_aad : bstr, 411 payload : bstr, 412 ? other_fields : [ + bstr ] 413 ] 415 How to compute a countersignature: 417 1. Create a Countersign_structure and populate it with the 418 appropriate fields. 420 2. Create the value ToBeSigned by encoding the Countersign_structure 421 to a byte string, using the encoding described in Section 4. 423 3. Call the signature creation algorithm passing in K (the key to 424 sign with), alg (the algorithm to sign with), and ToBeSigned (the 425 value to sign). 427 4. Place the resulting signature value in the correct location. 428 This is the 'signature' field of the COSE_Countersignature 429 structure. This is the value of the Countersignature0 attribute. 431 The steps for verifying a countersignature are: 433 1. Create a Countersign_structure and populate it with the 434 appropriate fields. 436 2. Create the value ToBeSigned by encoding the Countersign_structure 437 to a byte string, using the encoding described in Section 4. 439 3. Call the signature verification algorithm passing in K (the key 440 to verify with), alg (the algorithm used sign with), ToBeSigned 441 (the value to sign), and sig (the signature to be verified). 443 In addition to performing the signature verification, the application 444 performs the appropriate checks to ensure that the key is correctly 445 paired with the signing identity and that the signing identity is 446 authorized before performing actions. 448 4. CBOR Encoding Restrictions 450 In order to always regenerate the same byte string for the "to be 451 signed" value, the deterministic encoding rules defined in 452 Section 4.2 of [I-D.ietf-cbor-7049bis]. These rules match the ones 453 laid out in Section 11 of [I-D.ietf-cose-rfc8152bis-struct]. 455 5. IANA Considerations 457 The registries and registrations listed below were created during 458 processing of RFC 8152 [RFC8152]. The majority of the actions are to 459 update the references to point to this document. 461 5.1. CBOR Tag Assignment 463 IANA is requested to register a new tag for the CounterSignature 464 type. 466 * Tag: TBD0 468 * Data Item: COSE_Countersignature 470 * Semantics: COSE standalone V2 countersignature 472 * Reference: [[this document]] 474 5.2. COSE Header Parameters Registry 476 IANA created a registry titled "COSE Header Parameters" as part of 477 processing [RFC8152]. 479 IANA is requested to register the following new items in the 480 registry. For these entries, the Value Registry column will be blank 481 and the Reference column will be [[This Document]]. 483 +===================+=====+========================+================+ 484 | Name |Label|Value Type |Description | 485 +===================+=====+========================+================+ 486 | counter signature |TBD10|COSE_Countersignature / |V2 | 487 | version 2 | |[+ COSE_Countersignature|countersignature| 488 | | |] |attribute | 489 +-------------------+-----+------------------------+----------------+ 490 | Countersignature0 |TBD11|COSE_Countersignature0 |Abbreviated | 491 | version 2 | | |Counter | 492 | | | |signature vesion| 493 | | | |2 | 494 +-------------------+-----+------------------------+----------------+ 496 Table 2: New Common Header Parameters 498 IANA is requested to modify the Description field for "counter 499 signature" and "CounterSignature0" to include the words "(Deprecated 500 by [[This Document]]". 502 6. Security Considerations 504 There are a number of security considerations that need to be taken 505 into account by implementers of this specification. While some 506 considerations have been highlighted here, additional considerations 507 may be found in the documents listed in the references. 509 Implementations need to protect the private key material for any 510 individuals. There are some cases that need to be highlighted on 511 this issue. 513 * Using the same key for two different algorithms can leak 514 information about the key. It is therefore recommended that keys 515 be restricted to a single algorithm. 517 * Use of 'direct' as a recipient algorithm combined with a second 518 recipient algorithm exposes the direct key to the second 519 recipient. 521 * Several of the algorithms in [I-D.ietf-cose-rfc8152bis-algs] have 522 limits on the number of times that a key can be used without 523 leaking information about the key. 525 The use of ECDH and direct plus KDF (with no key wrap) will not 526 directly lead to the private key being leaked; the one way function 527 of the KDF will prevent that. There is, however, a different issue 528 that needs to be addressed. Having two recipients requires that the 529 CEK be shared between two recipients. The second recipient therefore 530 has a CEK that was derived from material that can be used for the 531 weak proof of origin. The second recipient could create a message 532 using the same CEK and send it to the first recipient; the first 533 recipient would, for either static-static ECDH or direct plus KDF, 534 make an assumption that the CEK could be used for proof of origin 535 even though it is from the wrong entity. If the key wrap step is 536 added, then no proof of origin is implied and this is not an issue. 538 Although it has been mentioned before, the use of a single key for 539 multiple algorithms has been demonstrated in some cases to leak 540 information about that key, provide the opportunity for attackers to 541 forge integrity tags, or gain information about encrypted content. 542 Binding a key to a single algorithm prevents these problems. 544 Key creators and key consumers are strongly encouraged not only to 545 create new keys for each different algorithm, but to include that 546 selection of algorithm in any distribution of key material and 547 strictly enforce the matching of algorithms in the key structure to 548 algorithms in the message structure. In addition to checking that 549 algorithms are correct, the key form needs to be checked as well. Do 550 not use an 'EC2' key where an 'OKP' key is expected. 552 Before using a key for transmission, or before acting on information 553 received, a trust decision on a key needs to be made. Is the data or 554 action something that the entity associated with the key has a right 555 to see or a right to request? A number of factors are associated 556 with this trust decision. Some of the ones that are highlighted here 557 are: 559 * What are the permissions associated with the key owner? 561 * Is the cryptographic algorithm acceptable in the current context? 563 * Have the restrictions associated with the key, such as algorithm 564 or freshness, been checked and are they correct? 566 * Is the request something that is reasonable, given the current 567 state of the application? 569 * Have any security considerations that are part of the message been 570 enforced (as specified by the application or 'crit' header 571 parameter)? 573 Analysis of the size of encrypted messages can provide information 574 about the plaintext messages. This specification does not provide a 575 uniform method for padding messages prior to encryption. An observer 576 can distinguish between two different messages (for example, 'YES' 577 and 'NO') based on the length for all of the content encryption 578 algorithms that are defined in [I-D.ietf-cose-rfc8152bis-algs]. This 579 means that it is up to the applications to specify how content 580 padding is to be done to prevent or discourage such analysis. (For 581 example, the text strings could be defined as 'YES' and 'NO '.) 583 7. Implementation Status 585 This section is to be removed before publishing as an RFC. 587 This section records the status of known implementations of the 588 protocol defined by this specification at the time of posting of this 589 Internet-Draft, and is based on a proposal described in [RFC7942]. 590 The description of implementations in this section is intended to 591 assist the IETF in its decision processes in progressing drafts to 592 RFCs. Please note that the listing of any individual implementation 593 here does not imply endorsement by the IETF. Furthermore, no effort 594 has been spent to verify the information presented here that was 595 supplied by IETF contributors. This is not intended as, and must not 596 be construed to be, a catalog of available implementations or their 597 features. Readers are advised to note that other implementations may 598 exist. 600 According to [RFC7942], "this will allow reviewers and working groups 601 to assign due consideration to documents that have the benefit of 602 running code, which may serve as evidence of valuable experimentation 603 and feedback that have made the implemented protocols more mature. 604 It is up to the individual working groups to use this information as 605 they see fit". 607 7.1. Author's Versions 609 There are three different implementations that have been created by 610 the author of the document both to create the examples that are 611 included in the document and to validate the structures and 612 methodology used in the design of COSE. 614 * Implementation Location: https://github.com/cose-wg 616 * Primary Maintainer: Jim Schaad 617 * Languages: There are three different languages that are currently 618 supported: Java and C#. 620 * Cryptography: The Java and C# libraries use Bouncy Castle to 621 provide the required cryptography. 623 * Coverage: Both implementations can produce and consume both the 624 old and new countersignatures. 626 * Testing: All of the examples in the example library are generated 627 by the C# library and then validated using the Java and C 628 libraries. Both libraries have tests to allow for the creating of 629 the same messages that are in the example library followed by 630 validating them. These are not compared against the example 631 library. The Java and C# libraries have unit testing included. 632 Not all of the MUST statements in the document have been 633 implemented as part of the libraries. One such statement is the 634 requirement that unique labels be present. 636 * Licensing: Revised BSD License 638 7.2. COSE Testing Library 640 * Implementation Location: https://github.com/cose-wg/Examples 642 * Primary Maintainer: Jim Schaad 644 * Description: A set of tests for the COSE library is provided as 645 part of the implementation effort. Both success and fail tests 646 have been provided. All of the examples in this document are part 647 of this example set. 649 * Coverage: An attempt has been made to have test cases for every 650 message type and algorithm in the document. Currently examples 651 dealing with countersignatures, and ECDH with Curve25519 and 652 Goldilocks are missing. 654 * Licensing: Public Domain 656 8. References 658 8.1. Normative References 660 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 661 Requirement Levels", BCP 14, RFC 2119, 662 DOI 10.17487/RFC2119, March 1997, 663 . 665 [I-D.ietf-cbor-7049bis] 666 Bormann, C. and P. Hoffman, "Concise Binary Object 667 Representation (CBOR)", Work in Progress, Internet-Draft, 668 draft-ietf-cbor-7049bis-16, 30 September 2020, 669 . 671 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 672 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 673 May 2017, . 675 [I-D.ietf-cose-rfc8152bis-algs] 676 Schaad, J., "CBOR Object Signing and Encryption (COSE): 677 Initial Algorithms", Work in Progress, Internet-Draft, 678 draft-ietf-cose-rfc8152bis-algs-12, 24 September 2020, 679 . 682 8.2. Informative References 684 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 685 Definition Language (CDDL): A Notational Convention to 686 Express Concise Binary Object Representation (CBOR) and 687 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 688 June 2019, . 690 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 691 RFC 8152, DOI 10.17487/RFC8152, July 2017, 692 . 694 [STD90] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 695 Interchange Format", STD 90, RFC 8259, December 2017. 697 699 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 700 Application Protocol (CoAP)", RFC 7252, 701 DOI 10.17487/RFC7252, June 2014, 702 . 704 [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 705 Code: The Implementation Status Section", BCP 205, 706 RFC 7942, DOI 10.17487/RFC7942, July 2016, 707 . 709 [RFC4998] Gondrom, T., Brandner, R., and U. Pordesch, "Evidence 710 Record Syntax (ERS)", RFC 4998, DOI 10.17487/RFC4998, 711 August 2007, . 713 [I-D.ietf-core-groupcomm-bis] 714 Dijk, E., Wang, C., and M. Tiloca, "Group Communication 715 for the Constrained Application Protocol (CoAP)", Work in 716 Progress, Internet-Draft, draft-ietf-core-groupcomm-bis- 717 02, 2 November 2020, . 720 [I-D.ietf-cose-rfc8152bis-struct] 721 Schaad, J., "CBOR Object Signing and Encryption (COSE): 722 Structures and Process", Work in Progress, Internet-Draft, 723 draft-ietf-cose-rfc8152bis-struct-14, 24 September 2020, 724 . 727 [RFC8613] Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 728 "Object Security for Constrained RESTful Environments 729 (OSCORE)", RFC 8613, DOI 10.17487/RFC8613, July 2019, 730 . 732 Appendix A. Examples 734 This appendix includes a set of examples that show the different 735 features and message types that have been defined in this document. 736 To make the examples easier to read, they are presented using the 737 extended CBOR diagnostic notation (defined in [RFC8610]) rather than 738 as a binary dump. 740 The examples are presented using the CBOR's diagnostic notation. A 741 Ruby-based tool exists that can convert between the diagnostic 742 notation and binary. This tool can be installed with the command 743 line: 745 gem install cbor-diag 747 The diagnostic notation can be converted into binary files using the 748 following command line: 750 diag2cbor.rb < inputfile > outputfile 752 The examples can be extracted from the XML version of this document 753 via an XPath expression as all of the sourcecode is tagged with the 754 attribute type='CBORdiag'. (Depending on the XPath evaluator one is 755 using, it may be necessary to deal with > as an entity.) 757 //sourcecode[@type='CDDL']/text() 759 A.1. Use of Early Code Points 761 This section is to be removed before publishing as an RFC. 763 The examples in this Appendix use code points proposed for early 764 allocation by IANA. When IANA makes the allocation, these examples 765 will be updated as needed. 767 A.2. Examples of Signed Messages 769 A.2.1. Countersignature 771 This example uses the following: 773 * Signature Algorithm: ECDSA w/ SHA-256, Curve P-256 775 * The same header parameters are used for both the signature and the 776 countersignature. 778 Size of binary file is 180 bytes 779 98( 780 [ 781 / protected / h'', 782 / unprotected / { 783 / countersign / 11:[ 784 / protected h'a10126' / << { 785 / alg / 1:-7 / ECDSA 256 / 786 } >>, 787 / unprotected / { 788 / kid / 4:'11' 789 }, 790 / signature / h'5ac05e289d5d0e1b0a7f048a5d2b643813ded50bc9e4 791 9220f4f7278f85f19d4a77d655c9d3b51e805a74b099e1e085aacd97fc29d72f887e 792 8802bb6650cceb2c' 793 ] 794 }, 795 / payload / 'This is the content.', 796 / signatures / [ 797 [ 798 / protected h'a10126' / << { 799 / alg / 1:-7 / ECDSA 256 / 800 } >>, 801 / unprotected / { 802 / kid / 4:'11' 803 }, 804 / signature / h'e2aeafd40d69d19dfe6e52077c5d7ff4e408282cbefb 805 5d06cbf414af2e19d982ac45ac98b8544c908b4507de1e90b717c3d34816fe926a2b 806 98f53afd2fa0f30a' 807 ] 808 ] 809 ] 810 ) 812 A.3. Examples of Signed1 Messages 814 A.3.1. Countersignature 816 This example uses the following: 818 * Signature Algorithm: ECDSA w/ SHA-256, Curve P-256 820 * Countersignature Algorithm: ECDSA w/ SHA-512, Curve P-521 822 Size of binary file is 275 bytes 823 18( 824 [ 825 / protected h'A201260300' / << { 826 / alg / 1:-7, / ECDSA 256 / 827 / ctyp / 3:0 828 } >>, 829 / unprotected / { 830 / kid / 4: "11", 831 / countersign / 11: [ 832 / protected h'A1013823' / << { 833 / alg / 1:-36 / ECDSA 512 / 834 } >>, 835 / unprotected / { 836 / kid / 4: "bilbo.baggins@hobbiton.example" 837 }, 838 / signature / h'01B1291B0E60A79C459A4A9184A0D393E034B34AF069 839 A1CCA34F5A913AFFFF698002295FA9F8FCBFB6FDFF59132FC0C406E98754A98F1FBF 840 E81C03095F481856BC470170227206FA5BEE3C0431C56A66824E7AAF692985952E31 841 271434B2BA2E47A335C658B5E995AEB5D63CF2D0CED367D3E4CC8FFFD53B70D115BA 842 A9E86961FBD1A5CF' 843 ] 844 }, 845 / payload / 'This is the content.', 846 / signature / h'BB587D6B15F47BFD54D2CBFCECEF75451E92B08A514BD439 847 FA3AA65C6AC92DF0D7328C4A47529B32ADD3DD1B4E940071C021E9A8F2641F1D8E3B 848 053DDD65AE52' 849 ] 850 ) 852 A.4. Examples of Enveloped Messages 854 A.4.1. Countersignature on Encrypted Content 856 This example uses the following: 858 * CEK: AES-GCM w/ 128-bit key 860 * Recipient class: ECDH Ephemeral-Static, Curve P-256 862 * Countersignature Algorithm: ECDSA w/ SHA-512, Curve P-521 864 Size of binary file is 326 bytes 865 96( 866 [ 867 / protected h'a10101' / << { 868 / alg / 1:1 / AES-GCM 128 / 869 } >>, 870 / unprotected / { 871 / iv / 5:h'c9cf4df2fe6c632bf7886413', 872 / countersign / 11:[ 873 / protected h'a1013823' / << { 874 / alg / 1:-36 / ES512 / 875 } >> , 876 / unprotected / { 877 / kid / 4:'bilbo.baggins@hobbiton.example' 878 }, 879 / signature / h'00929663c8789bb28177ae28467e66377da12302d7f9 880 594d2999afa5dfa531294f8896f2b6cdf1740014f4c7f1a358e3a6cf57f4ed6fb02f 881 cf8f7aa989f5dfd07f0700a3a7d8f3c604ba70fa9411bd10c2591b483e1d2c31de00 882 3183e434d8fba18f17a4c7e3dfa003ac1cf3d30d44d2533c4989d3ac38c38b71481c 883 c3430c9d65e7ddff' 884 ] 885 }, 886 / ciphertext / h'7adbe2709ca818fb415f1e5df66f4e1a51053ba6d65a1a0 887 c52a357da7a644b8070a151b0', 888 / recipients / [ 889 [ 890 / protected h'a1013818' / << { 891 / alg / 1:-25 / ECDH-ES + HKDF-256 / 892 } >> , 893 / unprotected / { 894 / ephemeral / -1:{ 895 / kty / 1:2, 896 / crv / -1:1, 897 / x / -2:h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbf 898 bf054e1c7b4d91d6280', 899 / y / -3:true 900 }, 901 / kid / 4:'meriadoc.brandybuck@buckland.example' 902 }, 903 / ciphertext / h'' 904 ] 905 ] 906 ] 907 ) 909 A.5. Examples of Encrypted Messages 910 A.5.1. Countersignature on Encrypted Content 912 This example uses the following: 914 * CEK: AES-GCM w/ 128-bit key 916 * Countersignature algorithm: EdDSA with Curve Ed25519 918 Size of binary file is 136 bytes 920 16( 921 [ 922 / protected h'A10101' / << { 923 / alg / 1:1 / AES-GCM 128 / 924 } >>, 925 / unprotected / { 926 / iv / 5: h'02D1F7E6F26C43D4868D87CE', 927 / countersign / 11: [ 928 / protected h'A10127' / << { 929 / alg / 1:-8 / EdDSA with Ed25519 / 930 } >>, 931 / unprotected / { 932 / kid / 4: '11' 933 }, 934 / signature / h'E10439154CC75C7A3A5391491F88651E0292FD0FE0E0 935 2CF740547EAF6677B4A4040B8ECA16DB592881262F77B14C1A086C02268B17171CA1 936 6BE4B8595F8C0A08' 937 ] 938 }, 939 / ciphertext / h'60973A94BB2898009EE52ECFD9AB1DD25867374B162E2C0 940 3568B41F57C3CC16F9166250A' 941 ] 942 ) 944 A.6. Examples of MACed Messages 946 A.6.1. Countersignature on MAC Content 948 This example uses the following: 950 * MAC algorithm: HMAC/SHA-256 with 256-bit key 952 * Countersignature algorithm: EdDSA with Curve Ed25519 954 Size of binary file is 159 bytes 955 97( 956 [ 957 / protected h'A10105' / << { 958 / alg / 1:5 / HS256 / 959 } >>, 960 / unprotected / { 961 / countersign / 11: [ 962 / protected h'A10127' / << { 963 / alg / 1:-8 / EdDSA / 964 } >>, 965 / unprotected / { 966 / kid / 4: '11' 967 }, 968 / signature / h'602566F4A311DC860740D2DF54D4864555E85BC036EA 969 5A6CF7905B96E499C5F66B01C4997F6A20C37C37543ADEA1D705347D38A5B13594B2 970 9583DD741F455101' 971 ] 972 }, 973 / payload / 'This is the content.', 974 / tag / h'2BDCC89F058216B8A208DDC6D8B54AA91F48BD63484986565105C9 975 AD5A6682F6', 976 / recipients / [ 977 [ 978 / protected / h'', 979 / unprotected / { 980 / alg / 1: -6, / direct / 981 / kid / 4: 'our-secret' 982 }, 983 / ciphertext / h'' 984 ] 985 ] 986 ] 987 ) 989 A.7. Examples of MAC0 Messages 991 A.7.1. Countersignature on MAC0 Content 993 This example uses the following: 995 * MAC algorithm: HMAC/SHA-256 with 256-bit key 997 * Countersignature algorithm: EdDSA with Curve Ed25519 999 Size of binary file is 159 bytes 1000 17( 1001 [ 1002 / protected h'A10105' / << { 1003 / alg / 1:5 / HS256 / 1004 } >>, 1005 / unprotected / { 1006 / countersign / 11: [ 1007 / protected h'A10127' / << { 1008 / alg / 1:-8 / EdDSA / 1009 } >>, 1010 / unprotected / { 1011 / kid / 4: '11' 1012 }, 1013 / signature / h'968A315DF6B4F26362E11F4CFD2F2F4E76232F39657B 1014 F1598837FF9332CDDD7581E248116549451F81EF823DA5974F885B681D3D6E38FC41 1015 42D8F8E9E7DC8F0D' 1016 ] 1017 }, 1018 / payload / 'This is the content.', 1019 / tag / h'A1A848D3471F9D61EE49018D244C824772F223AD4F935293F1789F 1020 C3A08D8C58' 1021 ] 1022 ) 1024 Acknowledgments 1026 This document is a product of the COSE working group of the IETF. 1028 The initial version of the specification was based to some degree on 1029 the outputs of the JOSE and S/MIME working groups. 1031 Jim Schaad passed on 3 October 2020. This document is primarily his 1032 work. Russ Housley served as the document editor after Jim's 1033 untimely death, mostly helping with the approval and publication 1034 processes. Jim deserves all credit for the technical content. 1036 Jim Schaad and Jonathan Hammell provided the examples in the 1037 Appendix. 1039 {{{ RFC EDITOR: Please remove Russ Housley as an author of this 1040 document at publication. Jim Schaad should be listed as the sole 1041 author. }}} 1043 Authors' Addresses 1045 Jim Schaad 1046 August Cellars 1047 Email: ietf@augustcellars.com 1049 Russ Housley (editor) 1050 Vigil Security, LLC 1052 Email: housley@vigilsec.com