idnits 2.17.1 draft-ietf-cose-countersign-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 14 instances of too long lines in the document, the longest one being 5 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 786 has weird spacing: '...otected h'a10...' -- The document date (7 October 2020) is 1289 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 (-10) exists of draft-ietf-core-groupcomm-bis-01 == Outdated reference: A later version (-15) exists of draft-ietf-cose-rfc8152bis-struct-13 Summary: 2 errors (**), 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: 10 April 2021 Vigil Security 6 7 October 2020 8 CBOR Object Signing and Encryption (COSE): Countersignatures 9 draft-ietf-cose-countersign-01 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 10 April 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 . . . . . . . . . . . . . . . . 3 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 . . . . . . . . . . . . . . . . . . . . 14 78 7.2. COSE Testing Library . . . . . . . . . . . . . . . . . . 14 79 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 15 80 8.1. Normative References . . . . . . . . . . . . . . . . . . 15 81 8.2. Informative References . . . . . . . . . . . . . . . . . 15 82 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 16 83 A.1. Examples of Signed Messages . . . . . . . . . . . . . . . 17 84 A.1.1. Countersignature . . . . . . . . . . . . . . . . . . 17 85 A.2. Examples of Enveloped Messages . . . . . . . . . . . . . 18 86 A.2.1. Countersignature on Encrypted Content . . . . . . . . 18 87 A.3. Examples of Encrypted Messages . . . . . . . . . . . . . 19 88 A.4. Examples of MACed Messages . . . . . . . . . . . . . . . 19 89 A.5. Examples of MAC0 Messages . . . . . . . . . . . . . . . . 20 90 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 20 91 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 20 93 1. Introduction 95 There has been an increased focus on small, constrained devices that 96 make up the Internet of Things (IoT). One of the standards that has 97 come out of this process is "Concise Binary Object Representation 98 (CBOR)" [I-D.ietf-cbor-7049bis]. CBOR extended the data model of the 99 JavaScript Object Notation (JSON) [STD90] by allowing for binary 100 data, among other changes. CBOR has been adopted by several of the 101 IETF working groups dealing with the IoT world as their encoding of 102 data structures. CBOR was designed specifically both to be small in 103 terms of messages transported and implementation size and to be a 104 schema-free decoder. A need exists to provide message security 105 services for IoT, and using CBOR as the message-encoding format makes 106 sense. 108 During the process of advancing COSE to an Internet Standard, it was 109 noticed the description of the security properties of 110 countersignatures was incorrect for the COSE_Sign1 structure. Since 111 the security properties that were described, those of a true 112 countersignature, were those that the working group desired, the 113 decision was made to remove all of the countersignature text from 114 [I-D.ietf-cose-rfc8152bis-struct] and create a new document to both 115 deprecate the old countersignature algorithm and to define a new one 116 with the desired security properties. 118 The problem with the previous countersignature algorithm was that the 119 cryptographically computed value was not always included. The 120 initial assumption that the cryptographic value was in the third slot 121 of the array was known not to be true at the time, but in the case of 122 the MAC structures this was not deemed to be an issue. The new 123 algorithm is more aggressive about the set of values included in the 124 countersignature computation so that the cryptographic computed 125 values is included. The exception to this is the COSE_Signature 126 structure where there is no cryptographic computed value. 128 The new algorithm is designed to produce the same countersignature 129 value in those cases where the cryptographic computed value was 130 already included. This means that for those structures the only 131 thing that would need to be done is to change the value of the header 132 parameter. 134 1.1. Requirements Terminology 136 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 137 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 138 "OPTIONAL" in this document are to be interpreted as described in BCP 139 14 [RFC2119] [RFC8174] when, and only when, they appear in all 140 capitals, as shown here. 142 1.2. CBOR Grammar 144 CBOR grammar in the document is presented using CBOR Data Definition 145 Language (CDDL) [RFC8610]. 147 The collected CDDL can be extracted from the XML version of this 148 document via the following XPath expression below. (Depending on the 149 XPath evaluator one is using, it may be necessary to deal with > 150 as an entity.) 152 //sourcecode[@type='CDDL']/text() 154 CDDL expects the initial non-terminal symbol to be the first symbol 155 in the file. For this reason, the first fragment of CDDL is 156 presented here. 158 start = COSE_Countersignature_Tagged / Internal_Types 160 ; This is defined to make the tool quieter: 161 Internal_Types = Countersign_structure / COSE_Countersignature0 163 The non-terminal Internal_Types is defined for dealing with the 164 automated validation tools used during the writing of this document. 165 It references those non-terminals that are used for security 166 computations but are not emitted for transport. 168 1.3. Document Terminology 170 In this document, we use the following terminology: 172 Byte is a synonym for octet. 174 Constrained Application Protocol (CoAP) is a specialized web transfer 175 protocol for use in constrained systems. It is defined in [RFC7252]. 177 Context is used throughout the document to represent information that 178 is not part of the COSE message. Information which is part of the 179 context can come from several different sources including: Protocol 180 interactions, associated key structures, and program configuration. 181 The context to use can be implicit, identified using the 'kid 182 context' header parameter defined in [RFC8613], or identified by a 183 protocol-specific identifier. Context should generally be included 184 in the cryptographic construction; for more details see Section 4.3 185 of [I-D.ietf-cose-rfc8152bis-struct]. 187 The term 'byte string' is used for sequences of bytes, while the term 188 'text string' is used for sequences of characters. 190 2. Countersignature Header Parameters 192 This section defines a set of common header parameters. A summary of 193 these header parameters can be found in Table 1. This table should 194 be consulted to determine the value of label and the type of the 195 value. 197 The set of header parameters defined in this section are: 199 V2 countersignature: This header parameter holds one or more 200 countersignature values. Countersignatures provide a method of 201 having a second party sign some data. The countersignature header 202 parameter can occur as an unprotected attribute in any of the 203 following structures: COSE_Sign1, COSE_Signature, COSE_Encrypt, 204 COSE_recipient, COSE_Encrypt0, COSE_Mac, and COSE_Mac0. Details 205 on version 2 countersignatures are found in Section 3. 207 +===========+=====+========================+==========+=============+ 208 |Name |Label|Value Type | Value | Description | 209 | | | | Registry | | 210 +===========+=====+========================+==========+=============+ 211 |counter |TBD10|COSE_Countersignature / | | V2 counter | 212 |signature | |[+ COSE_Countersignature| | signature | 213 |version 2 | |] | | attribute | 214 +-----------+-----+------------------------+----------+-------------+ 215 |counter |TBD11|COSE_Countersignature0 | | Abbreviated | 216 |signature 0| | | | Counter | 217 |version 2 | | | | signature | 218 | | | | | vesion 2 | 219 +-----------+-----+------------------------+----------+-------------+ 221 Table 1: Common Header Parameters 223 The CDDL fragment that represents the set of header parameters 224 defined in this section is given below. Each of the header 225 parameters is tagged as optional because they do not need to be in 226 every map; header parameters required in specific maps are discussed 227 above. 229 Generic_Headers /= ( 230 ? TBD10 => COSE_Countersignature / [+COSE_Countersignature] 231 ; V2 Countersignature 232 ? TBD11 => COSE_Countersignature0 ; V2 Countersignature0 233 ) 235 3. Version 2 Countersignatures 237 A countersignature is normally defined as a second signature that 238 confirms a primary signature. A normal example of a countersignature 239 is the signature that a notary public places on a document as 240 witnessing that you have signed the document. Thus applying a 241 countersignature to either the COSE_Signature or COSE_Sign1 objects 242 match this traditional definition. This document extends the context 243 of a countersignature to allow it to be applied to all of the 244 security structures defined. It needs to be noted that the 245 countersignature needs to be treated as a separate operation from the 246 initial operation even if it is applied by the same user as is done 247 in [I-D.ietf-core-groupcomm-bis]. 249 COSE supports two different forms for countersignatures. Full 250 countersignatures use the structure COSE_Countersignature. This is 251 same structure as COSE_Signature and thus it can have protected and 252 unprotected attributes, including chained countersignatures. 253 Abbreviated countersignatures use the structure 254 COSE_Countersignature0. This structure only contains the signature 255 value and nothing else. The structures cannot be converted between 256 each other; as the signature computation includes a parameter 257 identifying which structure is being used, the converted structure 258 will fail signature validation. 260 The version 2 countersignature changes the algorithm used for 261 computing the signature from the original version Section 4.5 of 262 [RFC8152]. The new version now includes the cryptographic material 263 generated for all of the structures rather than just for a subset. 265 COSE was designed for uniformity in how the data structures are 266 specified. One result of this is that for COSE one can expand the 267 concept of countersignatures beyond just the idea of signing a 268 signature to being able to sign most of the structures without having 269 to create a new signing layer. When creating a countersignature, one 270 needs to be clear about the security properties that result. When 271 done on a COSE_Signature or COSE_Sign1, the normal countersignature 272 semantics are preserved. That is the countersignature makes a 273 statement about the existence of a signature and, when used as a 274 timestamp, a time point at which the signature exists. When done on 275 a COSE_Sign, this is the same as applying a second signature to the 276 payload and adding a parallel signature as a new COSE_Signature is 277 the preferred method. When done on a COSE_Mac or COSE_Mac0, the 278 payload is included as well as the MAC value. When done on a 279 COSE_Encrypt or COSE_Encrypt0, the existence of the encrypted data is 280 attested to. It should be noted that there is a big difference 281 between attesting to the encrypted data as opposed to attesting to 282 the unencrypted data. If the latter is what is desired, then one 283 needs to apply a signature to the data and then encrypt that. It is 284 always possible to construct cases where the use of two different 285 keys will appear to result in a successful decryption (the tag check 286 success), but which produce two completely different plaintexts. 287 This situation is not detectable by a countersignature on the 288 encrypted data. 290 3.1. Full Countersignatures 292 The COSE_Countersignature structure allows for the same set of 293 capabilities as a COSE_Signature. This means that all of the 294 capabilities of a signature are duplicated with this structure. 295 Specifically, the countersigner does not need to be related to the 296 producer of what is being countersigned as key and algorithm 297 identification can be placed in the countersignature attributes. 298 This also means that the countersignature can itself be 299 countersigned. This is a feature required by protocols such as long- 300 term archiving services. More information on how countersignatures 301 is used can be found in the evidence record syntax described in 302 [RFC4998]. 304 The full countersignature structure can be encoded as either tagged 305 or untagged depending on the context it is used in. A tagged 306 COSE_Countersignature structure is identified by the CBOR tag TBD0. 307 The countersignature structure is the same as that used for a signer 308 on a signed object. The CDDL fragment for full countersignatures is: 310 COSE_Countersignature_Tagged = #6.9999(COSE_Countersignature) 311 COSE_Countersignature = COSE_Signature 313 The details of the fields of a countersignature can be found in 314 Section 4.1 of [I-D.ietf-cose-rfc8152bis-struct]. 316 An example of a countersignature on a signature can be found in 317 Appendix A.1.1. An example of a countersignature in an encryption 318 object can be found in Appendix A.2.1. 320 It should be noted that only a signature algorithm with appendix (see 321 Section 8 of [I-D.ietf-cose-rfc8152bis-struct]) can be used for 322 countersignatures. This is because the body should be able to be 323 processed without having to evaluate the countersignature, and this 324 is not possible for signature schemes with message recovery. 326 3.2. Abbreviated Countersignatures 328 Abbreviated countersignatures were designed primarily to deal with 329 the problem of encrypted group messaging, but where it is required to 330 know who originated the message. The objective was to keep the 331 countersignature as small as possible while still providing the 332 needed security. For abbreviated countersignatures, there is no 333 provision for any protected attributes related to the signing 334 operation. Instead, the parameters for computing or verifying the 335 abbreviated countersignature are provided by the same context used to 336 describe the encryption, signature, or MAC processing. 338 The CDDL fragment for the abbreviated countersignatures is: 340 COSE_Countersignature0 = bstr 342 The byte string representing the signature value is placed in the 343 Countersignature0 attribute. This attribute is then encoded as an 344 unprotected header parameter. The attribute is defined below. 346 3.3. Signing and Verification Process 348 In order to create a signature, a well-defined byte string is needed. 349 The Countersign_structure is used to create the canonical form. This 350 signing and verification process takes in countersignature target 351 structure, the signer information (COSE_Signature), and the 352 application data (external source). A Countersign_structure is a 353 CBOR array. The target structure of the countersignature needs to 354 have all of it's cryptographic functions finalized before the 355 computing the signature. The fields of the Countersign_structure in 356 order are: 358 1. A context text string identifying the context of the signature. 359 The context text string is: 361 "CounterSignature" for signatures using the 362 COSE_Countersignature structure when other_fields is absent. 364 "CounterSignature0" for signatures using the 365 COSE_Countersignature0 structure when other_fields is absent. 367 "CounterSignatureV2" for signatures using the 368 COSE_Countersignature structure when other_fields is present. 370 "CounterSignature0V2" for signatures using the 371 COSE_Countersignature0 structure when other_fields is present. 373 2. The protected attributes from the target structure encoded in a 374 bstr type. If there are no protected attributes, a zero-length 375 byte string is used. 377 3. The protected attributes from the signer structure encoded in a 378 bstr type. If there are no protected attributes, a zero-length 379 byte string is used. This field is omitted for the 380 Countersignature0V2 attribute. 382 4. The externally supplied data from the application encoded in a 383 bstr type. If this field is not supplied, it defaults to a zero- 384 length byte string. (See Section 4.3 of 385 [I-D.ietf-cose-rfc8152bis-struct] for application guidance on 386 constructing this field.) 388 5. The payload to be signed encoded in a bstr type. The payload is 389 placed here independent of how it is transported. 391 6. If there are only two bstr fields in the target structure, this 392 field is omitted. The field is an array of all bstr fields after 393 the second. As an example, this would be an array of one element 394 for the COSE_Sign1 structure containing the signature value. 396 The CDDL fragment that describes the above text is: 398 Countersign_structure = [ 399 context : "CounterSignature" / "CounterSignature0" / 400 "CounterSignatureV2" / "CounterSignature0V2" /, 401 body_protected : empty_or_serialized_map, 402 ? sign_protected : empty_or_serialized_map, 403 external_aad : bstr, 404 payload : bstr, 405 ? other_fields : [ + bstr ] 406 ] 408 How to compute a countersignature: 410 1. Create a Countersign_structure and populate it with the 411 appropriate fields. 413 2. Create the value ToBeSigned by encoding the Countersign_structure 414 to a byte string, using the encoding described in Section 4. 416 3. Call the signature creation algorithm passing in K (the key to 417 sign with), alg (the algorithm to sign with), and ToBeSigned (the 418 value to sign). 420 4. Place the resulting signature value in the correct location. 421 This is the 'signature' field of the COSE_Countersignature 422 structure. This is the value of the Countersignature0 attribute. 424 The steps for verifying a countersignature are: 426 1. Create a Countersign_structure and populate it with the 427 appropriate fields. 429 2. Create the value ToBeSigned by encoding the Countersign_structure 430 to a byte string, using the encoding described in Section 4. 432 3. Call the signature verification algorithm passing in K (the key 433 to verify with), alg (the algorithm used sign with), ToBeSigned 434 (the value to sign), and sig (the signature to be verified). 436 In addition to performing the signature verification, the application 437 performs the appropriate checks to ensure that the key is correctly 438 paired with the signing identity and that the signing identity is 439 authorized before performing actions. 441 4. CBOR Encoding Restrictions 443 In order to always regenerate the same byte string for the "to be 444 signed" value, the deterministic encoding rules defined in 445 Section 4.2 of [I-D.ietf-cbor-7049bis]. These rules match the ones 446 laid out in Section 11 of [I-D.ietf-cose-rfc8152bis-struct]. 448 5. IANA Considerations 450 The registries and registrations listed below were created during 451 processing of RFC 8152 [RFC8152]. The majority of the actions are to 452 update the references to point to this document. 454 5.1. CBOR Tag Assignment 456 IANA is requested to register a new tag for the CounterSignature 457 type. 459 * Tag: TBD0 461 * Data Item: COSE_Countersignature 463 * Semantics: COSE standalone V2 countersignature 465 * Reference: [[this document]] 467 5.2. COSE Header Parameters Registry 469 IANA created a registry titled "COSE Header Parameters" as part of 470 processing [RFC8152]. 472 IANA is requested to register the following new items in the 473 registry. 475 +=================+=====+======================+========+================+ 476 |Name |Label|Value Type |Value |Description | 477 | | | |Registry| | 478 +=================+=====+======================+========+================+ 479 |counter signature|TBD10|COSE_Countersignature | |V2 | 480 |version 2 | |/ [+ | |countersignature| 481 | | |COSE_Countersignature | |attribute | 482 | | |] | | | 483 +-----------------+-----+----------------------+--------+----------------+ 484 |Countersignature0|TBD11|COSE_Countersignature0| |Abbreviated | 485 |version 2 | | | |Counter | 486 | | | | |signature vesion| 487 | | | | |2 | 488 +-----------------+-----+----------------------+--------+----------------+ 490 Table 2: New Common Header Parameters 492 IANA is requested to modify the Description field for "counter 493 signature" and "CounterSignature0" to include the words "(Deprecated 494 by [[This Document]]". 496 6. Security Considerations 498 TODO - review and trim as needed. 500 There are a number of security considerations that need to be taken 501 into account by implementers of this specification. While some 502 considerations have been highlighted here, additional considerations 503 may be found in the documents listed in the references. 505 Implementations need to protect the private key material for any 506 individuals. There are some cases that need to be highlighted on 507 this issue. 509 * Using the same key for two different algorithms can leak 510 information about the key. It is therefore recommended that keys 511 be restricted to a single algorithm. 513 * Use of 'direct' as a recipient algorithm combined with a second 514 recipient algorithm exposes the direct key to the second 515 recipient. 517 * Several of the algorithms in [I-D.ietf-cose-rfc8152bis-algs] have 518 limits on the number of times that a key can be used without 519 leaking information about the key. 521 The use of ECDH and direct plus KDF (with no key wrap) will not 522 directly lead to the private key being leaked; the one way function 523 of the KDF will prevent that. There is, however, a different issue 524 that needs to be addressed. Having two recipients requires that the 525 CEK be shared between two recipients. The second recipient therefore 526 has a CEK that was derived from material that can be used for the 527 weak proof of origin. The second recipient could create a message 528 using the same CEK and send it to the first recipient; the first 529 recipient would, for either static-static ECDH or direct plus KDF, 530 make an assumption that the CEK could be used for proof of origin 531 even though it is from the wrong entity. If the key wrap step is 532 added, then no proof of origin is implied and this is not an issue. 534 Although it has been mentioned before, the use of a single key for 535 multiple algorithms has been demonstrated in some cases to leak 536 information about that key, provide the opportunity for attackers to 537 forge integrity tags, or gain information about encrypted content. 538 Binding a key to a single algorithm prevents these problems. Key 539 creators and key consumers are strongly encouraged not only to create 540 new keys for each different algorithm, but to include that selection 541 of algorithm in any distribution of key material and strictly enforce 542 the matching of algorithms in the key structure to algorithms in the 543 message structure. In addition to checking that algorithms are 544 correct, the key form needs to be checked as well. Do not use an 545 'EC2' key where an 'OKP' key is expected. 547 Before using a key for transmission, or before acting on information 548 received, a trust decision on a key needs to be made. Is the data or 549 action something that the entity associated with the key has a right 550 to see or a right to request? A number of factors are associated 551 with this trust decision. Some of the ones that are highlighted here 552 are: 554 * What are the permissions associated with the key owner? 556 * Is the cryptographic algorithm acceptable in the current context? 558 * Have the restrictions associated with the key, such as algorithm 559 or freshness, been checked and are they correct? 561 * Is the request something that is reasonable, given the current 562 state of the application? 564 * Have any security considerations that are part of the message been 565 enforced (as specified by the application or 'crit' header 566 parameter)? 568 One area that has been getting exposure is traffic analysis of 569 encrypted messages based on the length of the message. This 570 specification does not provide for a uniform method of providing 571 padding as part of the message structure. An observer can 572 distinguish between two different messages (for example, 'YES' and 573 'NO') based on the length for all of the content encryption 574 algorithms that are defined in [I-D.ietf-cose-rfc8152bis-algs] 575 document. This means that it is up to the applications to document 576 how content padding is to be done in order to prevent or discourage 577 such analysis. (For example, the text strings could be defined as 578 'YES' and 'NO '.) 580 7. Implementation Status 582 This section is to be removed before publishing as an RFC. 584 This section records the status of known implementations of the 585 protocol defined by this specification at the time of posting of this 586 Internet-Draft, and is based on a proposal described in [RFC7942]. 587 The description of implementations in this section is intended to 588 assist the IETF in its decision processes in progressing drafts to 589 RFCs. Please note that the listing of any individual implementation 590 here does not imply endorsement by the IETF. Furthermore, no effort 591 has been spent to verify the information presented here that was 592 supplied by IETF contributors. This is not intended as, and must not 593 be construed to be, a catalog of available implementations or their 594 features. Readers are advised to note that other implementations may 595 exist. 597 According to [RFC7942], "this will allow reviewers and working groups 598 to assign due consideration to documents that have the benefit of 599 running code, which may serve as evidence of valuable experimentation 600 and feedback that have made the implemented protocols more mature. 601 It is up to the individual working groups to use this information as 602 they see fit". 604 7.1. Author's Versions 606 There are three different implementations that have been created by 607 the author of the document both to create the examples that are 608 included in the document and to validate the structures and 609 methodology used in the design of COSE. 611 * Implementation Location: https://github.com/cose-wg 613 * Primary Maintainer: Jim Schaad 615 * Languages: There are three different languages that are currently 616 supported: Java and C#. 618 * Cryptography: The Java and C# libraries use Bouncy Castle to 619 provide the required cryptography. 621 * Coverage: Both implementations can produce and consume both the 622 old and new countersignatures. 624 * Testing: All of the examples in the example library are generated 625 by the C# library and then validated using the Java and C 626 libraries. Both libraries have tests to allow for the creating of 627 the same messages that are in the example library followed by 628 validating them. These are not compared against the example 629 library. The Java and C# libraries have unit testing included. 630 Not all of the MUST statements in the document have been 631 implemented as part of the libraries. One such statement is the 632 requirement that unique labels be present. 634 * Licensing: Revised BSD License 636 7.2. COSE Testing Library 638 * Implementation Location: https://github.com/cose-wg/Examples 640 * Primary Maintainer: Jim Schaad 642 * Description: A set of tests for the COSE library is provided as 643 part of the implementation effort. Both success and fail tests 644 have been provided. All of the examples in this document are part 645 of this example set. 647 * Coverage: An attempt has been made to have test cases for every 648 message type and algorithm in the document. Currently examples 649 dealing with countersignatures, and ECDH with Curve25519 and 650 Goldilocks are missing. 652 * Licensing: Public Domain 654 8. References 656 8.1. Normative References 658 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 659 Requirement Levels", BCP 14, RFC 2119, 660 DOI 10.17487/RFC2119, March 1997, 661 . 663 [I-D.ietf-cbor-7049bis] 664 Bormann, C. and P. Hoffman, "Concise Binary Object 665 Representation (CBOR)", Work in Progress, Internet-Draft, 666 draft-ietf-cbor-7049bis-16, 30 September 2020, 667 . 669 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 670 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 671 May 2017, . 673 [I-D.ietf-cose-rfc8152bis-algs] 674 Schaad, J., "CBOR Object Signing and Encryption (COSE): 675 Initial Algorithms", Work in Progress, Internet-Draft, 676 draft-ietf-cose-rfc8152bis-algs-12, 24 September 2020, 677 . 680 8.2. Informative References 682 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 683 Definition Language (CDDL): A Notational Convention to 684 Express Concise Binary Object Representation (CBOR) and 685 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 686 June 2019, . 688 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 689 RFC 8152, DOI 10.17487/RFC8152, July 2017, 690 . 692 [STD90] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 693 Interchange Format", STD 90, RFC 8259, December 2017. 695 697 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 698 Application Protocol (CoAP)", RFC 7252, 699 DOI 10.17487/RFC7252, June 2014, 700 . 702 [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 703 Code: The Implementation Status Section", BCP 205, 704 RFC 7942, DOI 10.17487/RFC7942, July 2016, 705 . 707 [RFC4998] Gondrom, T., Brandner, R., and U. Pordesch, "Evidence 708 Record Syntax (ERS)", RFC 4998, DOI 10.17487/RFC4998, 709 August 2007, . 711 [I-D.ietf-core-groupcomm-bis] 712 Dijk, E., Wang, C., and M. Tiloca, "Group Communication 713 for the Constrained Application Protocol (CoAP)", Work in 714 Progress, Internet-Draft, draft-ietf-core-groupcomm-bis- 715 01, 13 July 2020, . 718 [I-D.ietf-cose-rfc8152bis-struct] 719 Schaad, J., "CBOR Object Signing and Encryption (COSE): 720 Structures and Process", Work in Progress, Internet-Draft, 721 draft-ietf-cose-rfc8152bis-struct-13, 4 September 2020, 722 . 725 [RFC8613] Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 726 "Object Security for Constrained RESTful Environments 727 (OSCORE)", RFC 8613, DOI 10.17487/RFC8613, July 2019, 728 . 730 Appendix A. Examples 732 This appendix includes a set of examples that show the different 733 features and message types that have been defined in this document. 734 To make the examples easier to read, they are presented using the 735 extended CBOR diagnostic notation (defined in [RFC8610]) rather than 736 as a binary dump. 738 A GitHub project has been created at that contains not only the examples presented in this 740 document, but a more complete set of testing examples as well. Each 741 example is found in a JSON file that contains the inputs used to 742 create the example, some of the intermediate values that can be used 743 in debugging the example and the output of the example presented both 744 as a hex dump and in CBOR diagnostic notation format. Some of the 745 examples at the site are designed failure testing cases; these are 746 clearly marked as such in the JSON file. If errors in the examples 747 in this document are found, the examples on GitHub will be updated, 748 and a note to that effect will be placed in the JSON file. 750 As noted, the examples are presented using the CBOR's diagnostic 751 notation. A Ruby-based tool exists that can convert between the 752 diagnostic notation and binary. This tool can be installed with the 753 command line: 755 gem install cbor-diag 757 The diagnostic notation can be converted into binary files using the 758 following command line: 760 diag2cbor.rb < inputfile > outputfile 762 The examples can be extracted from the XML version of this document 763 via an XPath expression as all of the sourcecode is tagged with the 764 attribute type='CBORdiag'. (Depending on the XPath evaluator one is 765 using, it may be necessary to deal with > as an entity.) 767 //sourcecode[@type='CDDL']/text() 769 A.1. Examples of Signed Messages 771 A.1.1. Countersignature 773 This example uses the following: 775 * Signature Algorithm: ECDSA w/ SHA-256, Curve P-256 777 * The same header parameters are used for both the signature and the 778 countersignature. 780 Size of binary file is 180 bytes 781 98( 782 [ 783 / protected / h'', 784 / unprotected / { 785 / countersign / 7:[ 786 / protected h'a10126' / << { 787 / alg / 1:-7 / ECDSA 256 / 788 } >>, 789 / unprotected / { 790 / kid / 4:'11' 791 }, 792 / signature / h'5ac05e289d5d0e1b0a7f048a5d2b643813ded50bc9e4 793 9220f4f7278f85f19d4a77d655c9d3b51e805a74b099e1e085aacd97fc29d72f887e 794 8802bb6650cceb2c' 795 ] 796 }, 797 / payload / 'This is the content.', 798 / signatures / [ 799 [ 800 / protected h'a10126' / << { 801 / alg / 1:-7 / ECDSA 256 / 802 } >>, 803 / unprotected / { 804 / kid / 4:'11' 805 }, 806 / signature / h'e2aeafd40d69d19dfe6e52077c5d7ff4e408282cbefb 807 5d06cbf414af2e19d982ac45ac98b8544c908b4507de1e90b717c3d34816fe926a2b 808 98f53afd2fa0f30a' 809 ] 810 ] 811 ] 812 ) 814 A.2. Examples of Enveloped Messages 816 A.2.1. Countersignature on Encrypted Content 818 This example uses the following: 820 * CEK: AES-GCM w/ 128-bit key 822 * Recipient class: ECDH Ephemeral-Static, Curve P-256 824 Size of binary file is 326 bytes 825 96( 826 [ 827 / protected h'a10101' / << { 828 / alg / 1:1 / AES-GCM 128 / 829 } >>, 830 / unprotected / { 831 / iv / 5:h'c9cf4df2fe6c632bf7886413', 832 / countersign / 7:[ 833 / protected / h'a1013823' / { 834 \ alg \ 1:-36 835 } / , 836 / unprotected / { 837 / kid / 4:'bilbo.baggins@hobbiton.example' 838 }, 839 / signature / h'00929663c8789bb28177ae28467e66377da12302d7f9 840 594d2999afa5dfa531294f8896f2b6cdf1740014f4c7f1a358e3a6cf57f4ed6fb02f 841 cf8f7aa989f5dfd07f0700a3a7d8f3c604ba70fa9411bd10c2591b483e1d2c31de00 842 3183e434d8fba18f17a4c7e3dfa003ac1cf3d30d44d2533c4989d3ac38c38b71481c 843 c3430c9d65e7ddff' 844 ] 845 }, 846 / ciphertext / h'7adbe2709ca818fb415f1e5df66f4e1a51053ba6d65a1a0 847 c52a357da7a644b8070a151b0', 848 / recipients / [ 849 [ 850 / protected h'a1013818' / << { 851 / alg / 1:-25 / ECDH-ES + HKDF-256 / 852 } >> , 853 / unprotected / { 854 / ephemeral / -1:{ 855 / kty / 1:2, 856 / crv / -1:1, 857 / x / -2:h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbf 858 bf054e1c7b4d91d6280', 859 / y / -3:true 860 }, 861 / kid / 4:'meriadoc.brandybuck@buckland.example' 862 }, 863 / ciphertext / h'' 864 ] 865 ] 866 ] 867 ) 869 A.3. Examples of Encrypted Messages 871 A.4. Examples of MACed Messages 872 A.5. Examples of MAC0 Messages 874 Acknowledgments 876 This document is a product of the COSE working group of the IETF. 878 The initial version of the specification was based to some degree on 879 the outputs of the JOSE and S/MIME working groups. 881 Jim Schaad passed on 3 October 2020. This document is primarily his 882 work. Russ Housley served as the document editor after Jim's 883 untimely death, mostly helping with the approval and publication 884 processes. Jim deserves all credit for the technical content. 886 {{{ RFC EDITOR: Please remove Russ Housley as an author of this 887 document at publication. Jim Schaad should be listed as the sole 888 author. }}} 890 Authors' Addresses 892 Jim Schaad 893 August Cellars 895 Email: ietf@augustcellars.com 897 Russ Housley (editor) 898 Vigil Security, LLC 900 Email: housley@vigilsec.com