<?xmlversion='1.0' encoding='utf-8'?> <?xml-stylesheet type="text/xsl" href="rfc2629.xslt" ?>version="1.0" encoding="UTF-8"?> <!-- draft submitted in xml v3 --> <!DOCTYPE rfc [ <!ENTITY nbsp " "> <!ENTITY zwsp "​"> <!ENTITY nbhy "‑"> <!ENTITY wj "⁠"> ]><!-- RFC EDITOR Issue has been raised about countersign vs counter sign. The dictionaries seem to favor a single word, but when you did RFC 8152 you left it as a double word. I have switched to the single word version except for tables 3 and 4 where it causes the text file to have long lines. --> <?rfc toc="true"?> <?rfc symRefs="true"?> <?rfc sortRefs="true"?> <?rfc comments="true"?><rfc xmlns:xi="http://www.w3.org/2001/XInclude"ipr="trust200902" docName="draft-ietf-cose-countersign-10" category="std"submissionType="IETF" category="std" consensus="true" docName="draft-ietf-cose-countersign-10" number="9338" ipr="trust200902" xml:lang="en" tocInclude="true" symRefs="true" sortRefs="true" version="3"consensus="true" updates="9052">updates="9052" obsoletes=""> <front> <title abbrev="COSE Countersignatures"> CBOR Object Signing and Encryption (COSE): Countersignatures</title> <seriesInfo name="RFC" value="9338"/> <seriesInfo name="STD" value="96"/> <author initials="J." surname="Schaad" fullname="Jim Schaad"> <organization>August Cellars</organization> <address> <postal><country>USA</country> </postal> <email>ietf@augustcellars.com</email> </address> </author> <author initials="R." surname="Housley" fullname="Russ Housley" role="editor"> <organization abbrev="Vigil Security">Vigil Security, LLC</organization> <address> <postal> <country>USA</country><country>United States of America</country> </postal><email>housley@vigilsec.com</email><email></email> </address> </author><date/> <area>Security</area> <workgroup>COSE Working Group</workgroup><date year="2022" month="December" /> <area>sec</area> <workgroup>cose</workgroup> <keyword>digital signature</keyword> <abstract> <t> Concise Binary Object Representation (CBOR) is a data format designed for small code size and small message size. CBOR Object Signing and Encryption (COSE) defines a set of security services for CBOR. This document defines a countersignature algorithm along with the needed header parameters and CBOR tags for COSE. This document updates RFC 9052. </t> </abstract> </front> <middle> <section anchor="introduction"> <name>Introduction</name> <t> There has been an increased focus on small, constrained devices that make up the Internet of Things (IoT). One of the standards that has come out of this process is"Concise Binary Object Representation (CBOR)""<xref target="RFC8949" format="title"/>" <xreftarget="RFC8949"/>.target="RFC8949" format="default"/>. CBOR extended the data model of the JavaScript Object Notation (JSON) <xref target="STD90"/> by allowing for binary data, among other changes. CBOR has been adopted by several of the IETF working groups dealing with the IoT world as their method of encoding data structures. CBOR was designed specifically to be small in terms of both messages transported and implementation size and to have a schema-free decoder. A need exists to provide message security services for IoT, and using CBOR as the message-encoding format makes sense. </t> <t> A countersignature is a second signature that confirms the primary signature. During the process of advancingCOSECBOR Object Signing and Encryption (COSE) to Internet Standard, it was noticed that the description of the security properties of countersignatures was incorrect for the COSE_Sign1 structure mentioned in<relref<xref section="4.5" target="RFC8152"/>. To remedy this situation, theworking groupCOSE Working Group decided to remove all of the countersignature text from <xref target="RFC9052"/>, which obsoletes <xref target="RFC8152"/>. This document defines a new countersignature with the desired security properties. </t> <t> The problem with the previous countersignature algorithm was that the cryptographically computed value was not always included. The initial assumption that the cryptographic value was in the third slot of the array was known not to be true at the time, but in the case of theMACMessage Authentication Code (MAC) structures this was not deemed to be an issue. The new algorithm defined in this document requires the inclusion of more values for the countersignature computation. The exception to this is the COSE_Signature structure where there is nocryptographiccryptographically computed value. </t> <t> The new algorithm defined in this document is designed to produce the same countersignature value in those cases where the computed cryptographic value was already included. This means that for those structures the only thing that would need to be done is to change the value of the header parameter. </t> <t> With the publication of this document, implementers are encouraged to migrate uses of the previous countersignature algorithm to the one specified in this document. In particular, uses of "CounterSignature" will migrate to "CounterSignatureV2", and uses of "CounterSignature0" will migrate to "CounterSignature0V2". In addition, verification of "CounterSignature" must be supported by new implementations to remain compatible with senders that adhere to <xref target="RFC8152"/>, which assumes that all implementations will understand "CounterSignature" as header parameter label 7. Likewise, verification of "CounterSignature0" may be supported for further compatibility. </t> <section anchor="requirements-terminology"> <name>Requirements Terminology</name><t> The<t>The key words"MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY","<bcp14>MUST</bcp14>", "<bcp14>MUST NOT</bcp14>", "<bcp14>REQUIRED</bcp14>", "<bcp14>SHALL</bcp14>", "<bcp14>SHALL NOT</bcp14>", "<bcp14>SHOULD</bcp14>", "<bcp14>SHOULD NOT</bcp14>", "<bcp14>RECOMMENDED</bcp14>", "<bcp14>NOT RECOMMENDED</bcp14>", "<bcp14>MAY</bcp14>", and"OPTIONAL""<bcp14>OPTIONAL</bcp14>" in this document are to be interpreted as described in BCP 14 <xref target="RFC2119"/> <xref target="RFC8174"/> when, and only when, they appear in all capitals, as shownhere. </t>here.</t> </section> <section anchor="cbor-grammar"> <name>CBOR Grammar</name> <t> CBOR grammar in this document uses theCBORConcise Data Definition Language (CDDL) <xref target="RFC8610"/>. </t> <t> The collected CDDL can be extracted from the XML version of this document via thefollowingXPath expression below. (Depending on the XPath evaluator one is using, it may be necessary to deal with &gt; as an entity.) </t> <sourcecodetype="XPATH"><![CDATA[type="xpath"><![CDATA[ //sourcecode[@type='cddl']/text() ]]></sourcecode> <t>CDDL expects the initial non-terminal symbol to be the first symbol in the file. For this reason, the first fragment of CDDL is presented here.</t> <sourcecodetype="CDDL"><![CDATA[type="cddl"><![CDATA[ start = COSE_Countersignature_Tagged / Internal_Types ; This is defined to make the tool quieter: Internal_Types = Countersign_structure / COSE_Countersignature0 ]]></sourcecode> <t>The non-terminal Internal_Types is defined for dealing with the automated validation tools used during the writing of this document. It references those non-terminals that are used for security computations but are not emitted for transport. </t> </section> <section> <name>Document Terminology</name> <t> In this document, we use the followingterminology:terminology. </t> <t> "Byte" is a synonym for "octet". </t> <t> The Constrained Application Protocol (CoAP) is a specialized web transfer protocol for use in constrained systems. It is defined in <xref target="RFC7252"/>. </t> <t> "Context" is used throughoutthethis document to represent information that is not part of the COSE message. Informationwhichthat is part of the context can come from differentsources including:sources, including protocol interactions, associated key structures, and application configuration. The context to use can be implicit, identified using either the "kid context" header parameter defined in <xreftarget="RFC8613"/>,target="RFC8613"/> oridentified bya protocol-specific identifier. Context should generally be included in the cryptographic construction; for moredetailsdetails, see<relref section="4.3"<xref section="4.4" target="RFC9052"/>. </t> <t> The term "byte string" is used for sequences of bytes, while the term "text string" is used for sequences of characters. </t> </section> </section> <section> <name>Countersignature Header Parameters</name> <t>This section defines a set of common header parameters. A summary of these header parameters can be found in <xref target="Header-Table"/>. This table should be consulted to determine the value of the label and the type of the value.</t> <t>The set of header parameters defined in this sectionare:</t>is:</t> <dl newline="false"> <dt>V2 countersignature:</dt> <dd> This header parameter holds one or more countersignature values. Countersignatures provide a method of having a second party sign some data. The countersignature header parameter can occur as an unprotected attribute in any of the following structures that are defined in <xref target="RFC9052"/>: COSE_Sign1, COSE_Signature, COSE_Encrypt, COSE_recipient, COSE_Encrypt0, COSE_Mac, and COSE_Mac0. Details of version 2 countersignatures are found in <xref target="counter_signatureV2"/>. </dd> </dl> <table anchor="Header-Table" align="center"> <name>Common Header Parameters</name> <thead> <tr> <th>Name</th> <th>Label</th> <th>Value Type</th><th>Value Registry</th><th>Description</th> </tr> </thead> <tbody> <tr><td>counter signature<td>Countersignature version 2</td><td>TBD10</td><td>11</td> <td>COSE_Countersignature /[+ COSE_Countersignature[+ COSE_Countersignature ]</td><td/><td>V2counter signaturecountersignature attribute</td> </tr> <tr><td>counter signature 0<td>Countersignature0 version 2</td><td>TBD11</td><td>12</td> <td>COSE_Countersignature0</td><td/> <td>Abbreviated Counter signature vesion 2</td><td>V2 Abbreviated Countersignature</td> </tr> </tbody> </table> <t> The CDDL fragment that represents the set of header parameters defined in this section is given below. Each of the header parameters is tagged as optional because they do not need to be in every map; however, the header parameters required in specific maps are discussed above. </t> <sourcecodetype="CDDL"><![CDATA[type="cddl"><![CDATA[ CountersignatureV2_header = (TBD10? 11 => COSE_Countersignature /[+COSE_Countersignature][+ COSE_Countersignature] ) Countersignature0V2_header = (TBD11? 12 => COSE_Countersignature0 ) ]]></sourcecode> </section> <section anchor="counter_signatureV2"> <name>Version 2 Countersignatures</name> <t> A countersignature is normally defined as a second signature that confirms a primary signature. A normal example of a countersignature is the signature that a notary public places on a document as witnessing that you have signed the document. A notary typically includes a timestamp to indicate when notarization occurs; however, such a timestamp has not yet been defined for COSE. A timestamp, once defined in a future document, might be included as a protected header parameter.ThusThus, applying a countersignature to either the COSE_Signature or COSE_Sign1 objectsmatchmatches this traditional definition. This document extends the context of a countersignature to allow it to be applied to all of the security structures defined. The countersignature needs to be treated as a separate operation from the initial operation even if it is applied by the sameuseruser, as is done in <xreftarget="I-D.ietf-core-oscore-groupcomm"/>.target="GROUP-OSCORE"/>. </t> <t> COSE supports two different forms for countersignatures. Full countersignatures use the structure COSE_Countersignature, which has the same structure as COSE_Signature. Thus, full countersignatures can have protected and unprotected attributes, including chained countersignatures. Abbreviated countersignatures use the structure COSE_Countersignature0. This structure only contains the signature value and nothing else. The structures cannot be converted between each other; as the signature computation includes a parameter identifying which structure is being used, the converted structure will fail signature validation. </t> <t> The version 2 countersignature changes the algorithm used for computing the signature from the original version that is specified<relrefin <xref section="4.5" target="RFC8152"/>. The new version now includes the cryptographic material generated for all of the structures rather than just for a subset. </t> <t> COSE was designed for uniformity in how the data structures are specified. One result of this is that for COSE one can expand the concept of countersignatures beyond just the idea of signing a signature to being able to sign most of the structures without having to create a new signing layer. When creating a countersignature, one needs to be clear about the security properties that result. When done on a COSE_Signature or COSE_Sign1, the normal countersignature semantics are preserved. That is, the countersignature makes a statement about the existence of a signature and, when used with a yet-to-be-specified timestamp, a point in time at which the signature exists. When done on a COSE_Mac or COSE_Mac0, the payload is included as well as the MAC value. When done on a COSE_Encrypt or COSE_Encrypt0, the existence of the encrypted data is attested to. It should be noted that there is a distinction between attesting to the encrypted data as opposed to attesting to the unencrypted data. If the latter is what is desired, then one needs to apply a signature to the data and then encrypt that. It is always possible to construct cases where the use of two different keyswill appear to resultresults inasuccessfuldecryption (thedecryption, where the tag checksuccess),succeeds, butwhich producetwo completely differentplaintexts.plaintexts are produced. This situation is not detectable by a countersignature on the encrypted data. </t> <section anchor="Full_Countersig"> <name>Full Countersignatures</name> <t> The COSE_Countersignature structure allows for the same set of capabilities as a COSE_Signature. This means that all of the capabilities of a signature are duplicated with this structure. Specifically, the countersigner does not need to be related to the producer of what is beingcountersignedcountersigned, as key and algorithm identification can be placed in the countersignature attributes. This also means that the countersignature can itself be countersigned. This is a feature required by protocols such as long-term archiving services. More information on how countersignatures are used can be found in the evidence record syntax described in <xref target="RFC4998"/>. </t> <t> The full countersignature structure can be encoded as either tagged oruntaggeduntagged, depending on the context. A tagged COSE_Countersignature structure is identified by the CBOR tagTBD0.19. The countersignature structure is the same as that used for a signer on a signed object. The CDDL fragment for full countersignatures is: </t> <sourcecodetype="CDDL"><![CDATA[type="cddl"><![CDATA[ COSE_Countersignature_Tagged =#6.TBD0(COSE_Countersignature)#6.19(COSE_Countersignature) COSE_Countersignature = COSE_Signature ]]></sourcecode> <t> The details of the fields of a countersignature can be found in<relref<xref section="4.1" target="RFC9052"/>. </t> <t> An example of a countersignature on a signature can be found in <xref target="Appendix_A_1_1"/>. An example of a countersignature in an encryption object can be found in <xref target="Appendix_A_2_1"/>. </t> <t> It should be noted that only a signature algorithm with appendix (see<relref<xref section="8.1" target="RFC9052"/>) can be used for countersignatures. This is because the body should be able to be processed without having to evaluate the countersignature, and this is not possible for signature schemes with message recovery. </t> </section> <section anchor="Abbrev_Countersig"> <name>Abbreviated Countersignatures</name> <t> Abbreviated countersignatures support encrypted groupmessaging,messaging where identification of the message originator isrequired,required but there is a desire to keep the countersignature as small as possible. For abbreviated countersignatures, there is no provision for any protected attributes related to the signing operation. That is, the parameters for computing or verifying the abbreviated countersignature are provided by the same context used to describe the encryption, signature, or MAC processing. </t> <t> The CDDL fragment for the abbreviated countersignatures is: </t> <sourcecodetype="CDDL"><![CDATA[type="cddl"><![CDATA[ COSE_Countersignature0 = bstr ]]></sourcecode> <t> The byte string representing the signature value is placed in the Countersignature0 attribute. This attribute is then encoded as an unprotected header parameter. </t> </section> <section anchor="CountersignV2_verify"> <name>Signing and Verification Process</name> <t> In order to create a signature, a well-defined byte string is needed. The Countersign_structure is used to create the canonical form. This signing and verification process takes in the countersignature target structure (COSE_Signature, COSE_Sign1, COSE_Sign, COSE_Mac, COSE_Mac0, COSE_Encrypt, or COSE_Encrypt0), the signer information (COSE_Signature), and the application data (external source). A Countersign_structure is a CBOR array. The target structure of the countersignature needs to have all of its cryptographic functions finalized beforethecomputing the signature. The fields of theCountersign_structureCountersign_structure, inorderorder, are: </t> <dl> <dt>context:</dt><dd><dd><t> A context text string identifying the context of the signature. The context text string is one of thefollowing: </dd> </dl> <ul empty="true"> <li> "CounterSignature"following:</t> <ul> <li>"CounterSignature" for countersignatures using the COSE_Countersignature structure when other_fields isabsent. </li> <li> "CounterSignature0"absent.</li> <li>"CounterSignature0" for countersignatures using the COSE_Countersignature0 structure when other_fields isabsent. </li> <li> "CounterSignatureV2"absent.</li> <li>"CounterSignatureV2" for countersignatures using the COSE_Countersignature structure when other_fields ispresent. </li> <li> "CounterSignature0V2"present.</li> <li>"CounterSignature0V2" for countersignatures using the COSE_Countersignature0 structure when other_fields ispresent. </li>present.</li> </ul><dl></dd> <dt>body_protected:</dt> <dd> The serialized protected attributes from the targetstructurestructure, encoded in a bstr type. If there are no protected attributes, a zero-length byte string is used. </dd> <dt>sign_protected:</dt> <dd> The serialized protected attributes from the signerstructurestructure, encoded in a bstr type. If there are no protected attributes, a zero-length byte string is used. This field is omitted for the Countersignature0V2 attribute. </dd> <dt>external_aad:</dt> <dd> The externally supplied additional authenticated data (AAD) from theapplication isapplication, encoded in a bstr type. If this field is not supplied, it defaults to a zero-length byte string. (See<relref section="4.3"<xref section="4.4" target="RFC9052"/> for application guidance on constructing this field.) </dd> <dt>payload:</dt> <dd> The payload to besignedsigned, encoded in a bstr type. The payload is placed hereindependentindependently of how it is transported. </dd> <dt>other_fields:</dt> <dd>IfOmitted if there are only two bstr fields in the targetstructure, this field is omitted. Thestructure. This field is an array of all bstr fields after the second. As an example, this would be an array of one element for the COSE_Sign1 structure containing the signature value. </dd> </dl> <t>The CDDL fragment that describes the above text is: </t> <sourcecodetype="CDDL"><![CDATA[type="cddl"><![CDATA[ Countersign_structure = [ context : "CounterSignature" / "CounterSignature0" / "CounterSignatureV2" / "CounterSignature0V2" /, body_protected : empty_or_serialized_map, ? sign_protected : empty_or_serialized_map, external_aad : bstr, payload : bstr, ? other_fields :[ +[+ bstr ] ] ]]></sourcecode> <t>How to compute a countersignature: </t> <ol type="1"> <li>Create a Countersign_structure and populate it with the appropriate fields. </li> <li>Create the value ToBeSigned by encoding the Countersign_structure to a byte string, using the encoding described in <xref target="CBOR-Canonical"/>. </li> <li>Call the signature creation algorithm passing in K (the key to sign with), alg (the algorithm to sign with), and ToBeSigned (the value to sign). </li> <li> Place the resulting signature value in the correct location. This is the "signature" field of the COSE_Countersignature structure for full countersignatures (see <xref target="Full_Countersig"/>). This is the value of the Countersignature0 attribute for abbreviated countersignatures (see <xref target="Abbrev_Countersig"/>). </li> </ol> <t>The steps for verifying acountersignature are:countersignature: </t> <ol type="1"> <li>Create a Countersign_structure and populate it with the appropriate fields. </li> <li>Create the value ToBeSigned by encoding the Countersign_structure to a byte string, using the encoding described in <xref target="CBOR-Canonical"/>. </li> <li>Call the signature verification algorithm passing in K (the key to verify with), alg (the algorithm used to sign with), ToBeSigned (the value to sign), and sig (the signature to be verified). </li> </ol> <t> In addition to performing the signature verification, the application performs the appropriate checks to ensure that the key is correctly paired with the signing identity and that the signing identity is authorized before performing actions. </t> </section> </section> <section anchor="CBOR-Canonical"> <name>CBOR Encoding Restrictions</name> <t> The deterministic encoding rules are defined in<relref<xref section="4.2" target="RFC8949"/>. These rules are further narrowed in<relref<xref section="9" target="RFC9052"/>. The narrowed deterministic encoding rulesMUST<bcp14>MUST</bcp14> be used to ensure that all implementations generate the same byte string for the "to be signed" value. </t> </section> <section anchor="iana-considerations"> <name>IANA Considerations</name> <t> The registries and registrations listed below were created during the processing of <xref target="RFC8152"/>. The majority of the actions are to update the references to point to this document. </t> <section anchor="cbor-tag-assignment"> <name>CBORTag Assignment</name>Tags Registry</name> <t>IANA created a registry titled "CBOR Tags" registry as part of processing RFC 7049, which was subsequently replaced by <xref target="RFC8949"/>.</t> <t> IANAis requested to assignhas assigned a new tag for the CounterSignature type in the "CBOR Tags" registry. </t><ul> <li>Tag: TBD0</li> <li>Data Item: COSE_Countersignature</li> <li>Semantics: COSE<dl newline="false" spacing="compact"> <dt>Tag:</dt><dd>19</dd> <dt>Data Item:</dt><dd> COSE_Countersignature</dd> <dt>Semantics:</dt><dd>COSE standalone V2countersignature </li> <li>Reference: [[this document]]</li> </ul>countersignature</dd> <dt>Reference:</dt><dd>RFC 9338</dd> </dl> </section> <section anchor="cose-header-key-table"> <name>COSE Header Parameters Registry</name> <t> IANA created a registry titled "COSE Header Parameters" as part of processing <xref target="RFC8152"/>. </t> <t> IANAis requested to registerhas registered thefollowing new itemsCountersignature version 2 (label 11) and Countersignature0 version 2 (label 12) in the "COSE Header Parameters" registry. For these entries, theValue Registry column will be blank"Value Type" and "Description" are shown in Table 1, the "Value Registry" is blank, and theReference column will be [[This Document]]."Reference" is "RFC 9338". </t> <table> <name>New Common Header Parameters</name> <thead> <tr> <th>Name</th> <th>Label</th> <th>Value Type</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td>Countersignature version 2</td><td>TBD10</td><td>11</td> <td>COSE_Countersignature /[+ COSE_Countersignature[+ COSE_Countersignature ]</td> <td>V2 countersignature attribute</td> </tr> <tr> <td>Countersignature0 version 2</td><td>TBD11</td><td>12</td> <td>COSE_Countersignature0</td> <td>V2 Abbreviated Countersignature</td> </tr> </tbody> </table> <t> IANAis requested to modifyhas modified theDescriptionexisting "Description" field for "counter signature" (7) and "CounterSignature0" (9) to include the words "(Deprecated by[[This Document]])".RFC 9338)". </t> </section> </section> <section anchor="security-considerations"> <name>Security Considerations</name> <t> Please review the SecurityConsiderationConsiderations section in <xref target="RFC9052"/>; these considerations apply to this document as well, especially the need for implementations to protect private key material. </t> <t> When either COSE_Encryptandor COSE_Mac is used and more than two parties share the key, data origin authentication is not provided. Any party that knows the message-authentication key can compute a valid authentication tag; therefore, the contents could originate from any one of the parties that share the key. </t> <t> Countersignatures of COSE_Encrypt and COSE_Mac with short authentication tags do not provide the security properties associated with the same algorithm used in COSE_Sign. To provide 128-bit security against collision attacks, the tag lengthMUST<bcp14>MUST</bcp14> be at least256-bits.256 bits. A countersignature of a COSE_Mac with AES-MAC (using a 128-bit key or larger) provides at most 64 bits of integrity protection. Similarly, a countersignature of a COSE_Encrypt with AES-CCM-16-64-128 provides at most 32 bits of integrity protection. </t> </section><section removeInRFC="true"> <name>Implementation Status</name> <!-- RFC Editor - Please remove this section and reference RFC7942 prior to publication --> <t> This section records the status of known implementations of the protocol defined by this specification at the time of posting of this Internet-Draft, and is based on a proposal described in <xref target="RFC7942"/>. The description of implementations in this section is intended to assist the IETF in its decision processes in progressing drafts to RFCs. Please note that the listing of any individual implementation here does not imply endorsement by the IETF. Furthermore, no effort has been spent to verify the information presented here that was supplied by IETF contributors. This is not intended as, and must not be construed to be, a catalog of available implementations or their features. Readers are advised to note that other implementations may exist. </t> <t> According to <xref target="RFC7942"/>, "this will allow reviewers and working groups to assign due consideration to documents that have the benefit of running code, which may serve as evidence of valuable experimentation and feedback that have made the implemented protocols more mature. It is up to the individual working groups to use this information as they see fit". </t> <section> <name>Author's Versions</name> <t> There are three different implementations that have been created by the author of the document both to create the examples that are included in the document and to validate the structures and methodology used in the design of COSE. </t> <ul> <li>Implementation Location: https://github.com/cose-wg</li> <li>Primary Maintainer: Jim Schaad</li> <li> Languages: There are two different languages that are currently supported: Java and C#. </li> <li> Cryptography: The Java and C# libraries use Bouncy Castle to provide the required cryptography. </li> <li> Coverage: Both implementations can produce and consume both the old and new countersignatures. </li> <li> Testing: All of the examples in the example library are generated by the C# library and then validated using the Java and C libraries. Both libraries have tests to allow for the creating of the same messages that are in the example library followed by validating them. These are not compared against the example library. The Java and C# libraries have unit testing included. Not all of the <bcp14>MUST</bcp14> statements in the document have been implemented as part of the libraries. One such statement is the requirement that unique labels be present. </li> <li>Licensing: Revised BSD License </li> </ul> </section> <section> <name>COSE Testing Library</name> <ul> <li>Implementation Location: https://github.com/cose-wg/Examples</li> <li>Primary Maintainer: Jim Schaad</li> <li> Description: A set of tests for the COSE library is provided as part of the implementation effort. Both success and fail tests have been provided. All of the examples in this document are part of this example set. </li> <li> Coverage: An attempt has been made to have test cases for every message type and algorithm in the document. However, examples dealing with countersignatures, and ECDH with Curve25519 and Goldilocks are missing. </li> <li>Licensing: Public Domain</li> </ul> </section> </section></middle> <back> <references> <name>References</name> <references> <name>Normative References</name> <xi:includehref="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml"/>href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml"/> <xi:includehref="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.8174.xml"/>href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8174.xml"/> <xi:includehref="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.9052.xml"/>href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.9052.xml"/> </references> <references> <name>Informative References</name> <xi:includehref="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.8610.xml"/>href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8610.xml"/> <xi:includehref="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.8152.xml"/>href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8152.xml"/> <referencegroup anchor="STD90" target="https://www.rfc-editor.org/info/std90"> <xi:includehref="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.8295.xml"/>href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8259.xml"/> </referencegroup> <xi:includehref="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.8949.xml"/> <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.7252.xml"/>href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8949.xml"/> <xi:includehref="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.7942.xml"/>href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7252.xml"/> <xi:includehref="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.4998.xml"/> <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml3/reference.I-D.ietf-core-oscore-groupcomm.xml"/>href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.4998.xml"/> <!-- draft-ietf-core-oscore-groupcomm (Waiting for writeup) "Long way", to fix John Preuss Mattsson's initial (shouldn't include "P") --> <reference anchor="GROUP-OSCORE"> <front> <title>Group OSCORE - Secure Group Communication for CoAP</title> <author initials="M" surname="Tiloca" fullname="Marco Tiloca"> <organization>RISE AB</organization> </author> <author initials="G" surname="Selander" fullname="Göran Selander"> <organization>Ericsson AB</organization> </author> <author initials="F" surname="Palombini" fullname="Francesca Palombini"> <organization>Ericsson AB</organization> </author> <author initials="J" surname="Mattsson" fullname="John Preuss Mattsson"> <organization>Ericsson AB</organization> </author> <author initials="J" surname="Park" fullname="Jiye Park"> <organization>Universitaet Duisburg-Essen</organization> </author> <date day="24" month="October" year="2022"/> </front> <seriesInfo name="Internet-Draft" value="draft-ietf-core-oscore-groupcomm-16"/> </reference> <xi:includehref="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.8613.xml"/>href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8613.xml"/> <reference anchor="CBORDIAG" target="https://github.com/cabo/cbor-diag"> <front> <title>CBOR diagnostic utilities</title> <author fullname="C. Bormann" initials="C." surname="Bormann"/> <date month="September" year="2022"/> </front> <refcontent> commit 1952a04</refcontent> </reference> </references> </references> <section anchor="examples"> <name>Examples</name> <t>This appendix includes a set of examples that show the different features and message types that have been defined in this document. To make the examples easier to read, they are presented using the extended CBOR diagnostic notation (defined in <xref target="RFC8610"/>) rather than as a binary dump. </t> <t>The examples are presented using theCBOR'sCBOR diagnostic notation. A Ruby-based tool exists <xref target="CBORDIAG"/> that can convert between the diagnostic notation and binary. The referenced webpage includes installation instructions. </t> <t>The diagnostic notation can be converted into binary files using the following command line: </t> <sourcecode type=""><![CDATA[diag2cbor.rb < inputfile > outputfile ]]></sourcecode> <t>The examples can be extracted from the XML version of this document via an XPathexpressionexpression, as all of the sourcecode is tagged with the attributetype="CBORdiag".'type="cbor-diag"'. (Depending on the XPath evaluator one is using, it may be necessary to deal with &gt; as anentity.) </t>entity.)</t> <sourcecodetype="XPATH"><![CDATA[//sourcecode[@type='CDDL']/text()]]></sourcecode> <section removeInRFC="true"> <name>Use of Early Code Points</name> <!-- RFC Editor - Please remove this section prior to publication --> <t>The examples in this Appendix use code points proposed for early allocation by IANA. When IANA makestype="xpath"><![CDATA[//sourcecode[@type='cbor-diag']/text() ]]></sourcecode> <t>This appendix uses theallocation, these examples will be updated as needed.</t> </section>following terms:</t> <dl newline="false"> <dt>AES-GCM:</dt><dd>AES Galois/Counter Mode</dd> <dt>CEK:</dt><dd>content-encryption key</dd> <dt>ECDH:</dt><dd>Elliptic Curve Diffie-Hellman</dd> <dt>ECDH-ES:</dt><dd>Elliptic Curve Diffie-Hellman Ephemeral Static</dd> <dt>ECDSA:</dt><dd>Elliptic Curve Digital Signature Algorithm</dd> <dt>EdDSA:</dt><dd>Edwards-curve Digital Signature Algorithm</dd> <dt>HKDF:</dt><dd>HMAC-based Key Derivation Function</dd> <dt>HMAC:</dt><dd>Hashed Message Authentication Code</dd> </dl> <section anchor="SignedExamples"> <name>Examples of Signed Messages</name> <section anchor="Appendix_A_1_1"> <name>Countersignature</name> <t>This example uses the following: </t><ul> <li>Signature Algorithm: ECDSA w/<dl newline="false"> <dt>Signature Algorithm:</dt><dd>ECDSA with SHA-256, CurveP-256</li> <li>TheP-256</dd> </dl> <t>The same header parameters are used for both the signature and thecountersignature.</li> </ul> <t>Sizecountersignature.</t> <t>The size of the binary file is 180bytes</t>bytes.</t> <sourcecodetype="CBORdiag"><![CDATA[type="cbor-diag"><![CDATA[ 98( [ / protected / h'', / unprotected / { / countersign / 11:[ / protected h'a10126' / << { / alg / 1:-7 / ECDSA 256 / } >>, / unprotected / { / kid /4:'11'4: '11' }, / signature / h'5ac05e289d5d0e1b0a7f048a5d2b643813ded50bc9e4 9220f4f7278f85f19d4a77d655c9d3b51e805a74b099e1e085aacd97fc29d72f887e 8802bb6650cceb2c' ] }, / payload / 'This is the content.', / signatures / [ [ / protected h'a10126' / << { / alg / 1:-7 / ECDSA 256 / } >>, / unprotected / { / kid /4:'11'4: '11' }, / signature / h'e2aeafd40d69d19dfe6e52077c5d7ff4e408282cbefb 5d06cbf414af2e19d982ac45ac98b8544c908b4507de1e90b717c3d34816fe926a2b 98f53afd2fa0f30a' ] ] ] ) ]]> </sourcecode> </section> </section> <section anchor="Signed1Examples"> <name>Examples of Signed1 Messages</name> <section anchor="Appendix_B_2_3"> <name>Countersignature</name> <t>This example uses the following: </t><ul> <li>Signature Algorithm: ECDSA w/<dl newline="false"> <dt>Signature Algorithm:</dt><dd>ECDSA with SHA-256, CurveP-256</li> <li>Countersignature Algorithm: ECDSA w/P-256</dd> <dt>Countersignature Algorithm:</dt><dd>ECDSA with SHA-512, CurveP-521</li> </ul> <t>SizeP-521</dd> </dl> <t>The size of the binary file is 275bytes</t>bytes.</t> <sourcecodetype="CBORdiag"><![CDATA[type="cbor-diag"><![CDATA[ 18( [ / protected h'A201260300' / << { / alg / 1:-7, / ECDSA 256 / / ctyp / 3:0 } >>, / unprotected / { / kid / 4:"11",'11', / countersign / 11: [ / protected h'A1013823' / << { / alg / 1:-36 / ECDSA 512 / } >>, / unprotected / { / kid / 4:"bilbo.baggins@hobbiton.example"'bilbo.baggins@hobbiton.example' }, / signature / h'01B1291B0E60A79C459A4A9184A0D393E034B34AF069 A1CCA34F5A913AFFFF698002295FA9F8FCBFB6FDFF59132FC0C406E98754A98F1FBF E81C03095F481856BC470170227206FA5BEE3C0431C56A66824E7AAF692985952E31 271434B2BA2E47A335C658B5E995AEB5D63CF2D0CED367D3E4CC8FFFD53B70D115BA A9E86961FBD1A5CF' ] }, / payload / 'This is the content.', / signature / h'BB587D6B15F47BFD54D2CBFCECEF75451E92B08A514BD439 FA3AA65C6AC92DF0D7328C4A47529B32ADD3DD1B4E940071C021E9A8F2641F1D8E3B 053DDD65AE52' ] ) ]]></sourcecode> </section> </section> <section anchor="EnvelopedExamples"> <name>Examples of Enveloped Messages</name> <section anchor="Appendix_A_2_1"> <name>Countersignature on Encrypted Content</name> <t>This example uses the following: </t><ul> <li>CEK: AES-GCM w/<dl newline="false"> <dt>CEK:</dt><dd>AES-GCM with 128-bitkey</li> <li>Recipient class: ECDHkey</dd> <dt>Recipient Class:</dt><dd>ECDH Ephemeral-Static, CurveP-256</li> <li>Countersignature Algorithm: ECDSA w/P-256</dd> <dt>Countersignature Algorithm:</dt><dd>ECDSA with SHA-512, CurveP-521</li> </ul> <t>SizeP-521</dd> </dl> <t>The size of the binary file is 326bytes</t>bytes.</t> <sourcecodetype="CBORdiag"><![CDATA[type="cbor-diag"><![CDATA[ 96( [ / protected h'a10101' / << { / alg / 1:1 / AES-GCM 128 / } >>, / unprotected / { / iv / 5:h'c9cf4df2fe6c632bf7886413', / countersign / 11:[ / protected h'a1013823' / << { / alg / 1:-36 / ES512 / }>> ,>>, / unprotected / { / kid /4:'bilbo.baggins@hobbiton.example'4: 'bilbo.baggins@hobbiton.example' }, / signature / h'00929663c8789bb28177ae28467e66377da12302d7f9 594d2999afa5dfa531294f8896f2b6cdf1740014f4c7f1a358e3a6cf57f4ed6fb02f cf8f7aa989f5dfd07f0700a3a7d8f3c604ba70fa9411bd10c2591b483e1d2c31de00 3183e434d8fba18f17a4c7e3dfa003ac1cf3d30d44d2533c4989d3ac38c38b71481c c3430c9d65e7ddff' ] }, / ciphertext / h'7adbe2709ca818fb415f1e5df66f4e1a51053ba6d65a1a0 c52a357da7a644b8070a151b0', / recipients / [ [ / protected h'a1013818' / << { / alg / 1:-25 / ECDH-ES + HKDF-256 / }>> ,>>, / unprotected / { / ephemeral / -1:{ / kty / 1:2, / crv / -1:1, / x / -2:h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbf bf054e1c7b4d91d6280', / y / -3:true }, / kid /4:'meriadoc.brandybuck@buckland.example'4: 'meriadoc.brandybuck@buckland.example' }, / ciphertext / h'' ] ] ] ) ]]> </sourcecode> </section> </section> <section anchor="EncryptExamples"> <name>Examples of Encrypted Messages</name> <section anchor="Appendix_B_4_3"> <name>Countersignature on Encrypted Content</name> <t>This example uses the following: </t><ul> <li>CEK: AES-GCM w/<dl newline="false"> <dt>CEK:</dt><dd>AES-GCM with 128-bitkey</li> <li>Countersignature algorithm: EdDSAkey</dd> <dt>Countersignature Algorithm:</dt><dd>EdDSA with CurveEd25519</li> </ul> <t>SizeEd25519</dd> </dl> <t>The size of the binary file is 136bytes</t>bytes.</t> <sourcecodetype="CBORdiag"><![CDATA[type="cbor-diag"><![CDATA[ 16( [ / protected h'A10101' / << { / alg / 1:1 / AES-GCM 128 / } >>, / unprotected / { / iv / 5: h'02D1F7E6F26C43D4868D87CE', / countersign / 11: [ / protected h'A10127' / << { / alg / 1:-8 / EdDSA with Ed25519 / } >>, / unprotected / { / kid / 4: '11' }, / signature / h'E10439154CC75C7A3A5391491F88651E0292FD0FE0E0 2CF740547EAF6677B4A4040B8ECA16DB592881262F77B14C1A086C02268B17171CA1 6BE4B8595F8C0A08' ] }, / ciphertext / h'60973A94BB2898009EE52ECFD9AB1DD25867374B162E2C0 3568B41F57C3CC16F9166250A' ] ) ]]></sourcecode> </section> </section> <section anchor="MacExamples"> <name>Examples of MACed Messages</name> <section anchor="Appendix_B_5_3"> <name>Countersignature on MAC Content</name> <t>This example uses the following: </t><ul> <li>MAC algorithm: HMAC/SHA-256<dl newline="false"> <dt>MAC Algorithm:</dt><dd>HMAC/SHA-256 with 256-bitkey</li> <li>Countersignature algorithm: EdDSAkey</dd> <dt>Countersignature Algorithm:</dt><dd>EdDSA with CurveEd25519</li> </ul> <t>SizeEd25519</dd> </dl> <t>The size of the binary file is 159bytes</t>bytes.</t> <sourcecodetype="CBORdiag"><![CDATA[type="cbor-diag"><![CDATA[ 97( [ / protected h'A10105' / << { / alg / 1:5 / HS256 / } >>, / unprotected / { / countersign / 11: [ / protected h'A10127' / << { / alg / 1:-8 / EdDSA / } >>, / unprotected / { / kid / 4: '11' }, / signature / h'602566F4A311DC860740D2DF54D4864555E85BC036EA 5A6CF7905B96E499C5F66B01C4997F6A20C37C37543ADEA1D705347D38A5B13594B2 9583DD741F455101' ] }, / payload / 'This is the content.', / tag / h'2BDCC89F058216B8A208DDC6D8B54AA91F48BD63484986565105C9 AD5A6682F6', / recipients / [ [ / protected / h'', / unprotected / { / alg / 1: -6, / direct / / kid / 4: 'our-secret' }, / ciphertext / h'' ] ] ] ) ]]></sourcecode> </section> </section> <section anchor="Mac0Examples"> <name>Examples of MAC0 Messages</name> <section anchor="Appendix_B_6_3"> <name>Countersignature on MAC0 Content</name> <t>This example uses the following: </t><ul> <li>MAC algorithm: HMAC/SHA-256<dl newline="false"> <dt>MAC Algorithm:</dt><dd>HMAC/SHA-256 with 256-bitkey</li> <li>Countersignature algorithm: EdDSAkey</dd> <dt>Countersignature Algorithm:</dt><dd>EdDSA with CurveEd25519</li> </ul> <t>SizeEd25519</dd> </dl> <t>The size of the binary file is 159bytes</t>bytes.</t> <sourcecodetype="CBORdiag"><![CDATA[type="cbor-diag"><![CDATA[ 17( [ / protected h'A10105' / << { / alg / 1:5 / HS256 / } >>, / unprotected / { / countersign / 11: [ / protected h'A10127' / << { / alg / 1:-8 / EdDSA / } >>, / unprotected / { / kid / 4: '11' }, / signature / h'968A315DF6B4F26362E11F4CFD2F2F4E76232F39657B F1598837FF9332CDDD7581E248116549451F81EF823DA5974F885B681D3D6E38FC41 42D8F8E9E7DC8F0D' ] }, / payload / 'This is the content.', / tag / h'A1A848D3471F9D61EE49018D244C824772F223AD4F935293F1789F C3A08D8C58' ] ) ]]></sourcecode> </section> </section> </section> <section numbered="false"> <name>Acknowledgments</name> <t>This document is a product of the COSEworking groupWorking Group of the IETF.</t> <t>The initial draft version of the specification was based to some degree on the outputs of the JOSE and S/MIMEworking groups.</t> <t>Jim SchaadWorking Groups.</t> <t><contact fullname="Jim Schaad"/> passed on 3 October 2020. This document is primarily his work.Russ Housley<contact fullname="Russ Housley"/> served as the document editor after Jim's untimely death, mostly helping with the approval and publication processes. Jim deserves all credit for the technical content.</t><t>Jim Schaad<t><contact fullname="Jim Schaad"/> andJonathan Hammell<contact fullname="Jonathan Hammell"/> provided the examples inthe Appendix.</t><xref target="examples"/>.</t> <t>The reviews byCarsten Borman, Ben Kaduk, and Elwyn Davies<contact fullname="Carsten Bormann"/>, <contact fullname="Ben Kaduk"/>, and <contact fullname="Elwyn Davies"/> greatly improved the clarity of the document.</t><!-- RFC EDITOR - Please remove this note before publishing --> <t>{{{ RFC EDITOR: Please remove Russ Housley as an author of this document at publication. Jim Schaad should be listed as the sole author. }}}</t> <!-- <t> The following individuals provided input into the final form of the document: Carsten Bormann. </t> --></section> </back> </rfc>