path: root/doc/rfc/rfc9338.txt

Internet Engineering Task Force (IETF)                         J. Schaad
Request for Comments: 9338                                August Cellars
STD: 96                                                    December 2022
Updates: 9052                                                           
Category: Standards Track                                               
ISSN: 2070-1721


      CBOR Object Signing and Encryption (COSE): Countersignatures

Abstract

   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.

Status of This Memo

   This is an Internet Standards Track document.

   This document is a product of the Internet Engineering Task Force
   (IETF).  It represents the consensus of the IETF community.  It has
   received public review and has been approved for publication by the
   Internet Engineering Steering Group (IESG).  Further information on
   Internet Standards is available in Section 2 of RFC 7841.

   Information about the current status of this document, any errata,
   and how to provide feedback on it may be obtained at
   https://www.rfc-editor.org/info/rfc9338.

Copyright Notice

   Copyright (c) 2022 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (https://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Revised BSD License text as described in Section 4.e of the
   Trust Legal Provisions and are provided without warranty as described
   in the Revised BSD License.

Table of Contents

   1.  Introduction
     1.1.  Requirements Terminology
     1.2.  CBOR Grammar
     1.3.  Document Terminology
   2.  Countersignature Header Parameters
   3.  Version 2 Countersignatures
     3.1.  Full Countersignatures
     3.2.  Abbreviated Countersignatures
     3.3.  Signing and Verification Process
   4.  CBOR Encoding Restrictions
   5.  IANA Considerations
     5.1.  CBOR Tags Registry
     5.2.  COSE Header Parameters Registry
   6.  Security Considerations
   7.  References
     7.1.  Normative References
     7.2.  Informative References
   Appendix A.  Examples
     A.1.  Examples of Signed Messages
       A.1.1.  Countersignature
     A.2.  Examples of Signed1 Messages
       A.2.1.  Countersignature
     A.3.  Examples of Enveloped Messages
       A.3.1.  Countersignature on Encrypted Content
     A.4.  Examples of Encrypted Messages
       A.4.1.  Countersignature on Encrypted Content
     A.5.  Examples of MACed Messages
       A.5.1.  Countersignature on MAC Content
     A.6.  Examples of MAC0 Messages
       A.6.1.  Countersignature on MAC0 Content
   Acknowledgments
   Author's Address

1.  Introduction

   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)" [RFC8949].  CBOR extended the data model of the JavaScript
   Object Notation (JSON) [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.

   A countersignature is a second signature that confirms the primary
   signature.  During the process of advancing CBOR 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 Section 4.5 of
   [RFC8152].  To remedy this situation, the COSE Working Group decided
   to remove all of the countersignature text from [RFC9052], which
   obsoletes [RFC8152].  This document defines a new countersignature
   with the desired security properties.

   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
   the Message 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
   no cryptographically computed value.

   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.

   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
   [RFC8152], which assumes that all implementations will understand
   "CounterSignature" as header parameter label 7.  Likewise,
   verification of "CounterSignature0" may be supported for further
   compatibility.

1.1.  Requirements Terminology

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
   "OPTIONAL" in this document are to be interpreted as described in
   BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
   capitals, as shown here.

1.2.  CBOR Grammar

   CBOR grammar in this document uses the Concise Data Definition
   Language (CDDL) [RFC8610].

   The collected CDDL can be extracted from the XML version of this
   document via the XPath expression below.  (Depending on the XPath
   evaluator one is using, it may be necessary to deal with > as an
   entity.)

         //sourcecode[@type='cddl']/text()

   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.

         start = COSE_Countersignature_Tagged / Internal_Types

         ; This is defined to make the tool quieter:
         Internal_Types = Countersign_structure / COSE_Countersignature0

   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.

1.3.  Document Terminology

   In this document, we use the following terminology.

   "Byte" is a synonym for "octet".

   The Constrained Application Protocol (CoAP) is a specialized web
   transfer protocol for use in constrained systems.  It is defined in
   [RFC7252].

   "Context" is used throughout this document to represent information
   that is not part of the COSE message.  Information that is part of
   the context can come from different 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 [RFC8613] or a
   protocol-specific identifier.  Context should generally be included
   in the cryptographic construction; for more details, see Section 4.4
   of [RFC9052].

   The term "byte string" is used for sequences of bytes, while the term
   "text string" is used for sequences of characters.

2.  Countersignature Header Parameters

   This section defines a set of common header parameters.  A summary of
   these header parameters can be found in Table 1.  This table should
   be consulted to determine the value of the label and the type of the
   value.

   The set of header parameters defined in this section is:

   V2 countersignature:  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 [RFC9052]: COSE_Sign1,
      COSE_Signature, COSE_Encrypt, COSE_recipient, COSE_Encrypt0,
      COSE_Mac, and COSE_Mac0.  Details of version 2 countersignatures
      are found in Section 3.

   +=================+=====+==========================+================+
   |Name             |Label| Value Type               |Description     |
   +=================+=====+==========================+================+
   |Countersignature |11   | COSE_Countersignature /  |V2              |
   |version 2        |     | [+ COSE_Countersignature |countersignature|
   |                 |     | ]                        |attribute       |
   +-----------------+-----+--------------------------+----------------+
   |Countersignature0|12   | COSE_Countersignature0   |V2 Abbreviated  |
   |version 2        |     |                          |Countersignature|
   +-----------------+-----+--------------------------+----------------+

                     Table 1: Common Header Parameters

   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.

         CountersignatureV2_header = (
             ? 11 => COSE_Countersignature / [+ COSE_Countersignature]
         )

         Countersignature0V2_header = (
             ? 12 => COSE_Countersignature0
         )

3.  Version 2 Countersignatures

   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.  Thus, applying a countersignature to either the
   COSE_Signature or COSE_Sign1 objects matches 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 same user, as is
   done in [GROUP-OSCORE].

   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.

   The version 2 countersignature changes the algorithm used for
   computing the signature from the original version that is specified
   in Section 4.5 of [RFC8152].  The new version now includes the
   cryptographic material generated for all of the structures rather
   than just for a subset.

   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 keys results in
   successful decryption, where the tag check succeeds, but two
   completely different plaintexts are produced.  This situation is not
   detectable by a countersignature on the encrypted data.

3.1.  Full Countersignatures

   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 being countersigned, 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
   [RFC4998].

   The full countersignature structure can be encoded as either tagged
   or untagged, depending on the context.  A tagged
   COSE_Countersignature structure is identified by the CBOR tag 19.
   The countersignature structure is the same as that used for a signer
   on a signed object.  The CDDL fragment for full countersignatures is:

         COSE_Countersignature_Tagged = #6.19(COSE_Countersignature)
         COSE_Countersignature = COSE_Signature

   The details of the fields of a countersignature can be found in
   Section 4.1 of [RFC9052].

   An example of a countersignature on a signature can be found in
   Appendix A.1.1.  An example of a countersignature in an encryption
   object can be found in Appendix A.3.1.

   It should be noted that only a signature algorithm with appendix (see
   Section 8.1 of [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.

3.2.  Abbreviated Countersignatures

   Abbreviated countersignatures support encrypted group messaging where
   identification of the message originator is 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.

   The CDDL fragment for the abbreviated countersignatures is:

         COSE_Countersignature0 = bstr

   The byte string representing the signature value is placed in the
   Countersignature0 attribute.  This attribute is then encoded as an
   unprotected header parameter.

3.3.  Signing and Verification Process

   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 before computing the signature.  The fields of the
   Countersign_structure, in order, are:

   context:  A context text string identifying the context of the
      signature.  The context text string is one of the following:

      *  "CounterSignature" for countersignatures using the
         COSE_Countersignature structure when other_fields is absent.

      *  "CounterSignature0" for countersignatures using the
         COSE_Countersignature0 structure when other_fields is absent.

      *  "CounterSignatureV2" for countersignatures using the
         COSE_Countersignature structure when other_fields is present.

      *  "CounterSignature0V2" for countersignatures using the
         COSE_Countersignature0 structure when other_fields is present.

   body_protected:  The serialized protected attributes from the target
      structure, encoded in a bstr type.  If there are no protected
      attributes, a zero-length byte string is used.

   sign_protected:  The serialized protected attributes from the signer
      structure, 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.

   external_aad:  The externally supplied additional authenticated data
      (AAD) from the application, encoded in a bstr type.  If this field
      is not supplied, it defaults to a zero-length byte string.  (See
      Section 4.4 of [RFC9052] for application guidance on constructing
      this field.)

   payload:  The payload to be signed, encoded in a bstr type.  The
      payload is placed here independently of how it is transported.

   other_fields:  Omitted if there are only two bstr fields in the
      target structure.  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.

   The CDDL fragment that describes the above text is:

         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 ]
         ]

   How to compute a countersignature:

   1.  Create a Countersign_structure and populate it with the
       appropriate fields.

   2.  Create the value ToBeSigned by encoding the Countersign_structure
       to a byte string, using the encoding described in Section 4.

   3.  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).

   4.  Place the resulting signature value in the correct location.
       This is the "signature" field of the COSE_Countersignature
       structure for full countersignatures (see Section 3.1).  This is
       the value of the Countersignature0 attribute for abbreviated
       countersignatures (see Section 3.2).

   The steps for verifying a countersignature:

   1.  Create a Countersign_structure and populate it with the
       appropriate fields.

   2.  Create the value ToBeSigned by encoding the Countersign_structure
       to a byte string, using the encoding described in Section 4.

   3.  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).

   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.

4.  CBOR Encoding Restrictions

   The deterministic encoding rules are defined in Section 4.2 of
   [RFC8949].  These rules are further narrowed in Section 9 of
   [RFC9052].  The narrowed deterministic encoding rules MUST be used to
   ensure that all implementations generate the same byte string for the
   "to be signed" value.

5.  IANA Considerations

   The registries and registrations listed below were created during the
   processing of [RFC8152].  The majority of the actions are to update
   the references to point to this document.

5.1.  CBOR Tags Registry

   IANA created a registry titled "CBOR Tags" registry as part of
   processing RFC 7049, which was subsequently replaced by [RFC8949].

   IANA has assigned a new tag for the CounterSignature type in the
   "CBOR Tags" registry.

   Tag:  19
   Data Item:  COSE_Countersignature
   Semantics:  COSE standalone V2 countersignature
   Reference:  RFC 9338

5.2.  COSE Header Parameters Registry

   IANA created a registry titled "COSE Header Parameters" as part of
   processing [RFC8152].

   IANA has registered the Countersignature version 2 (label 11) and
   Countersignature0 version 2 (label 12) in the "COSE Header
   Parameters" registry.  For these entries, the "Value Type" and
   "Description" are shown in Table 1, the "Value Registry" is blank,
   and the "Reference" is "RFC 9338".

   +=================+=====+==========================+================+
   |Name             |Label| Value Type               |Description     |
   +=================+=====+==========================+================+
   |Countersignature |11   | COSE_Countersignature /  |V2              |
   |version 2        |     | [+ COSE_Countersignature |countersignature|
   |                 |     | ]                        |attribute       |
   +-----------------+-----+--------------------------+----------------+
   |Countersignature0|12   | COSE_Countersignature0   |V2 Abbreviated  |
   |version 2        |     |                          |Countersignature|
   +-----------------+-----+--------------------------+----------------+

                   Table 2: New Common Header Parameters

   IANA has modified the existing "Description" field for "counter
   signature" (7) and "CounterSignature0" (9) to include the words
   "(Deprecated by RFC 9338)".

6.  Security Considerations

   Please review the Security Considerations section in [RFC9052]; these
   considerations apply to this document as well, especially the need
   for implementations to protect private key material.

   When either COSE_Encrypt or 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.

   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 length MUST be at least
   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.

7.  References

7.1.  Normative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/info/rfc2119>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <https://www.rfc-editor.org/info/rfc8174>.

   [RFC9052]  Schaad, J., "CBOR Object Signing and Encryption (COSE):
              Structures and Process", STD 96, RFC 9052,
              DOI 10.17487/RFC9052, August 2022,
              <https://www.rfc-editor.org/info/rfc9052>.

7.2.  Informative References

   [CBORDIAG] Bormann, C., "CBOR diagnostic utilities", commit 1952a04,
              September 2022, <https://github.com/cabo/cbor-diag>.

   [GROUP-OSCORE]
              Tiloca, M., Selander, G., Palombini, F., Mattsson, J., and
              J. Park, "Group OSCORE - Secure Group Communication for
              CoAP", Work in Progress, Internet-Draft, draft-ietf-core-
              oscore-groupcomm-16, 24 October 2022,
              <https://datatracker.ietf.org/doc/html/draft-ietf-core-
              oscore-groupcomm-16>.

   [RFC4998]  Gondrom, T., Brandner, R., and U. Pordesch, "Evidence
              Record Syntax (ERS)", RFC 4998, DOI 10.17487/RFC4998,
              August 2007, <https://www.rfc-editor.org/info/rfc4998>.

   [RFC7252]  Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
              Application Protocol (CoAP)", RFC 7252,
              DOI 10.17487/RFC7252, June 2014,
              <https://www.rfc-editor.org/info/rfc7252>.

   [RFC8152]  Schaad, J., "CBOR Object Signing and Encryption (COSE)",
              RFC 8152, DOI 10.17487/RFC8152, July 2017,
              <https://www.rfc-editor.org/info/rfc8152>.

   [RFC8610]  Birkholz, H., Vigano, C., and C. Bormann, "Concise Data
              Definition Language (CDDL): A Notational Convention to
              Express Concise Binary Object Representation (CBOR) and
              JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610,
              June 2019, <https://www.rfc-editor.org/info/rfc8610>.

   [RFC8613]  Selander, G., Mattsson, J., Palombini, F., and L. Seitz,
              "Object Security for Constrained RESTful Environments
              (OSCORE)", RFC 8613, DOI 10.17487/RFC8613, July 2019,
              <https://www.rfc-editor.org/info/rfc8613>.

   [RFC8949]  Bormann, C. and P. Hoffman, "Concise Binary Object
              Representation (CBOR)", STD 94, RFC 8949,
              DOI 10.17487/RFC8949, December 2020,
              <https://www.rfc-editor.org/info/rfc8949>.

   [STD90]    Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
              Interchange Format", STD 90, RFC 8259, December 2017.

              <https://www.rfc-editor.org/info/std90>

Appendix A.  Examples

   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 [RFC8610]) rather than
   as a binary dump.

   The examples are presented using the CBOR diagnostic notation.  A
   Ruby-based tool exists [CBORDIAG] that can convert between the
   diagnostic notation and binary.  The referenced webpage includes
   installation instructions.

   The diagnostic notation can be converted into binary files using the
   following command line:

   diag2cbor.rb < inputfile > outputfile

   The examples can be extracted from the XML version of this document
   via an XPath expression, as all of the sourcecode is tagged with the
   attribute 'type="cbor-diag"'.  (Depending on the XPath evaluator one
   is using, it may be necessary to deal with &gt; as an entity.)

   //sourcecode[@type='cbor-diag']/text()

   This appendix uses the following terms:

   AES-GCM:  AES Galois/Counter Mode

   CEK:  content-encryption key

   ECDH:  Elliptic Curve Diffie-Hellman

   ECDH-ES:  Elliptic Curve Diffie-Hellman Ephemeral Static

   ECDSA:  Elliptic Curve Digital Signature Algorithm

   EdDSA:  Edwards-curve Digital Signature Algorithm

   HKDF:  HMAC-based Key Derivation Function

   HMAC:  Hashed Message Authentication Code

A.1.  Examples of Signed Messages

A.1.1.  Countersignature

   This example uses the following:

   Signature Algorithm:  ECDSA with SHA-256, Curve P-256

   The same header parameters are used for both the signature and the
   countersignature.

   The size of the binary file is 180 bytes.

   98(
     [
       / protected / h'',
       / unprotected / {
         / countersign / 11:[
           / protected  h'a10126' / << {
               / alg / 1:-7 / ECDSA 256 /
             } >>,
           / unprotected / {
             / kid / 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'
           },
           / signature / h'e2aeafd40d69d19dfe6e52077c5d7ff4e408282cbefb
   5d06cbf414af2e19d982ac45ac98b8544c908b4507de1e90b717c3d34816fe926a2b
   98f53afd2fa0f30a'
         ]
       ]
     ]
   )

A.2.  Examples of Signed1 Messages

A.2.1.  Countersignature

   This example uses the following:

   Signature Algorithm:  ECDSA with SHA-256, Curve P-256

   Countersignature Algorithm:  ECDSA with SHA-512, Curve P-521

   The size of the binary file is 275 bytes.

   18(
     [
       / protected h'A201260300' / << {
         / alg / 1:-7, / ECDSA 256 /
         / ctyp / 3:0
       } >>,
       / unprotected / {
         / kid / 4: '11',
         / countersign / 11: [
           / protected h'A1013823' / << {
             / alg / 1:-36 / ECDSA 512 /
           } >>,
           / unprotected / {
             / kid / 4: 'bilbo.baggins@hobbiton.example'
           },
           / signature / h'01B1291B0E60A79C459A4A9184A0D393E034B34AF069
   A1CCA34F5A913AFFFF698002295FA9F8FCBFB6FDFF59132FC0C406E98754A98F1FBF
   E81C03095F481856BC470170227206FA5BEE3C0431C56A66824E7AAF692985952E31
   271434B2BA2E47A335C658B5E995AEB5D63CF2D0CED367D3E4CC8FFFD53B70D115BA
   A9E86961FBD1A5CF'
         ]
       },
       / payload / 'This is the content.',
       / signature / h'BB587D6B15F47BFD54D2CBFCECEF75451E92B08A514BD439
   FA3AA65C6AC92DF0D7328C4A47529B32ADD3DD1B4E940071C021E9A8F2641F1D8E3B
   053DDD65AE52'
     ]
   )

A.3.  Examples of Enveloped Messages

A.3.1.  Countersignature on Encrypted Content

   This example uses the following:

   CEK:  AES-GCM with 128-bit key

   Recipient Class:  ECDH Ephemeral-Static, Curve P-256

   Countersignature Algorithm:  ECDSA with SHA-512, Curve P-521

   The size of the binary file is 326 bytes.

   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'
           },
           / 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'
           },
           / ciphertext / h''
         ]
       ]
     ]
   )

A.4.  Examples of Encrypted Messages

A.4.1.  Countersignature on Encrypted Content

   This example uses the following:

   CEK:  AES-GCM with 128-bit key

   Countersignature Algorithm:  EdDSA with Curve Ed25519

   The size of the binary file is 136 bytes.

   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'
     ]
   )

A.5.  Examples of MACed Messages

A.5.1.  Countersignature on MAC Content

   This example uses the following:

   MAC Algorithm:  HMAC/SHA-256 with 256-bit key

   Countersignature Algorithm:  EdDSA with Curve Ed25519

   The size of the binary file is 159 bytes.

   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''
         ]
       ]
     ]
   )

A.6.  Examples of MAC0 Messages

A.6.1.  Countersignature on MAC0 Content

   This example uses the following:

   MAC Algorithm:  HMAC/SHA-256 with 256-bit key

   Countersignature Algorithm:  EdDSA with Curve Ed25519

   The size of the binary file is 159 bytes.

   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'
     ]
   )

Acknowledgments

   This document is a product of the COSE Working Group of the IETF.

   The initial draft version of the specification was based to some
   degree on the outputs of the JOSE and S/MIME Working Groups.

   Jim Schaad passed on 3 October 2020.  This document is primarily his
   work.  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.

   Jim Schaad and Jonathan Hammell provided the examples in Appendix A.

   The reviews by Carsten Bormann, Ben Kaduk, and Elwyn Davies greatly
   improved the clarity of the document.

Author's Address

   Jim Schaad
   August Cellars
   United States of America