The CDDL fragment that represents the set of headers defined in this section is given below. Each of the headers is tagged as optional because they do not need to be in every map; headers required in specific maps are discussed above.

Generic_Headers = (
    ? 1 => int / tstr,  ; algorithm identifier
    ? 2 => [+label],    ; criticality
    ? 3 => tstr / int,  ; content type
    ? 4 => bstr,        ; key identifier
    ? 5 => bstr,        ; IV
    ? 6 => bstr,        ; Partial IV
    ? 7 => COSE_Signature / [+COSE_Signature] ; Counter signature
)

4. Signing Objects

COSE supports two different signature structures. COSE_Sign allows for one or more signatures to be applied to the same content. COSE_Sign1 is restricted to a single signer. 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.

4.1. Signing with One or More Signers

The COSE_Sign structure allows for one or more signatures to be applied to a message payload. Parameters relating to the content and parameters relating to the signature are carried along with the signature itself. These parameters may be authenticated by the signature, or just present. An example of a parameter about the content is the content type. Examples of parameters about the signature would be the algorithm and key used to create the signature and counter signatures.

When more than one signature is present, the successful validation of one signature associated with a given signer is usually treated as a successful signature by that signer. However, there are some application environments where other rules are needed. An application that employs a rule other than one valid signature for each signer must specify those rules. Also, where simple matching of the signer identifier is not sufficient to determine whether the signatures were generated by the same signer, the application specification must describe how to determine which signatures were generated by the same signer. Support for different communities of recipients is the primary reason that signers choose to include more than one signature. For example, the COSE_Sign structure might include signatures generated with the Edwards Digital Signature Algorithm (EdDSA) [I-D.irtf-cfrg-eddsa] signature algorithm and with the Elliptic Curve Digital Signature Algorithm (ECDSA) [DSS] signature algorithm. This allows recipients to verify the signature associated with one algorithm or the other. (The original source of this text is [RFC5652].) More detailed information on multiple signature evaluation can be found in [RFC5752].

The signature structure can be encoded either as tagged or untagged depending on the context it will be used in. A tagged COSE_Sign structure is identified by the CBOR tag TBD1. The CDDL fragment that represents this is:

COSE_Sign_Tagged = #6.991(COSE_Sign) ; Replace 991 with TBD1

A COSE Signed Message is defined in two parts. The CBOR object that carries the body and information about the body is called the COSE_Sign structure. The CBOR object that carries the signature and information about the signature is called the COSE_Signature structure. Examples of COSE Signed Messages can be found in Appendix C.1.

The COSE_Sign structure is a CBOR array. The fields of the array in order are:

protected

as described in Section 3.

unprotected

as described in Section 3.

payload

contains the serialized content to be signed. If the payload is not present in the message, the application is required to supply the payload separately. The payload is wrapped in a bstr to ensure that it is transported without changes. If the payload is transported separately ("detached content"), then a nil CBOR object is placed in this location and it is the responsibility of the application to ensure that it will be transported without changes.

Note: When a signature with message recovery algorithm is used (Section 8), the maximum number of bytes that can be recovered is the length of the payload. The size of the payload is reduced by the number of bytes that will be recovered. If all of the bytes of the payload are consumed, then the payload is encoded as a zero length binary string rather than as being absent.

signatures

is an array of signatures. Each signature is represented as a COSE_Signature structure.

The CDDL fragment that represents the above text for COSE_Sign follows.

COSE_Sign = [
    Headers,
    payload : bstr / nil,
    signatures : [+ COSE_Signature]
]

The COSE_Signature structure is a CBOR array. The fields of the array in order are:

protected

as described in Section 3.

unprotected

as described in Section 3.

signature

contains the computed signature value. The type of the field is a bstr. Algorithms MUST specify padding if the signature value is not a multiple of 8 bits.

The CDDL fragment that represents the above text for COSE_Signature follows.

COSE_Signature =  [
    Headers,      
    signature : bstr
]

4.2. Signing with One Signer

The COSE_Sign1 signature structure is used when only one signature is going to be placed on a message. The parameters dealing with the content and the signature are placed in the same pair of buckets rather than having the separation of COSE_Sign.

The structure can be encoded either tagged or untagged depending on the context it will be used in. A tagged COSE_Sign1 structure is identified by the CBOR tag TBD7. The CDDL fragment that represents this is:

COSE_Sign1_Tagged = #6.997(COSE_Sign1) ; Replace 997 with TBD7

The CBOR object that carries the body, the signature, and the information about the body and signature is called the COSE_Sign1 structure. Examples of COSE_Sign1 messages can be found in Appendix C.2.

The COSE_Sign1 structure is a CBOR array. The fields of the array in order are:

protected

as described in Section 3.

unprotected

as described in Section 3.

payload

as described in Section 4.1.

signature

contains the computed signature value. The type of the field is a bstr.

The CDDL fragment that represents the above text for COSE_Sign1 follows.

COSE_Sign1 = [
    Headers,
    payload : bstr / nil,
    signature : bstr
]

4.3. Externally Supplied Data

One of the features offered in the COSE document is the ability for applications to provide additional data to be authenticated, but that is not carried as part of the COSE object. The primary reason for supporting this can be seen by looking at the CoAP message structure [RFC7252], where the facility exists for options to be carried before the payload. Examples of data that can be placed in this location would be the CoAP code or CoAP options. If the data is in the header section, then it is available for proxies to help in performing its operations. For example, the Accept Option can be used by a proxy to determine if an appropriate value is in the Proxy's cache. But the sender can prevent a proxy from changing the set of values that it will accept by including that value in the resulting authentication tag. However, it may also be desired to protect these values so that if they are modified in transit, it can be detected.

This document describes the process for using a byte array of externally supplied authenticated data; however, the method of constructing the byte array is a function of the application. Applications that use this feature need to define how the externally supplied authenticated data is to be constructed. Such a construction needs to take into account the following issues:

• If multiple items are included, applications need to ensure that the same byte string is not produced if there are different inputs. This could occur by appending the strings 'AB' and 'CDE' or by appending the strings 'ABC' and 'DE'. This is usually addressed by making fields a fixed width and/or encoding the length of the field as part of the output. Using options from CoAP [RFC7252] as an example, these fields use a TLV structure so they can be concatenated without any problems.
• If multiple items are included, an order for the items needs to be defined. Using options from CoAP as an example, an application could state that the fields are to be ordered by the option number.
• Applications need to ensure that the byte stream is going to be the same on both sides. Using options from CoAP might give a problem if the same relative numbering is kept. An intermediate node could insert or remove an option, changing how the relative number is done. An application would need to specify that the relative number must be re-encoded to be relative only to the options that are in the external data.

4.4. Signing and Verification Process

In order to create a signature, a well-defined byte stream is needed. The Sig_struture is used to create the canonical form. This signing and verification process takes in the body information (COSE_Sign or COSE_Sign1), the signer information (COSE_Signature), and the application data (external source). A Sig_structure is a CBOR array. The fields of the Sig_struture in order are:

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

   "Signature"

   for signatures using the COSE_Signature structure.

   "Signature1"

   for signatures using the COSE_Sign1 structure.

   "CounterSignature"

   for signatures used as counter signature attributes.

2. The protected attributes from the body structure encoded in a bstr type. If there are no protected attributes, a bstr of length zero is used.
3. The protected attributes from the signer structure encoded in a bstr type. If there are no protected attributes, a bstr of length zero is used. This field is omitted for the COSE_Sign1 signature structure.
4. The protected attributes from the application encoded in a bstr type. If this field is not supplied, it defaults to a zero length binary string. (See Section 4.3 for application guidance on constructing this field.)
5. The payload to be signed encoded in a bstr type. The payload is placed here independent of how it is transported.

The CDDL fragment that describes the above text is.

Sig_structure = [
    context : "Signature" / "Signature1" / "CounterSignature",
    body_protected : empty_or_serialized_map,
    ? sign_protected : empty_or_serialized_map,
    external_aad : bstr,
    payload : bstr
]

How to compute a signature:

1. Create a Sig_structure and populate it with the appropriate fields.
2. Create the value ToBeSigned by encoding the Sig_structure to a byte string, using the encoding described in Section 14.
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 'signature' field of the array.

The steps for verifying a signature are:

1. Create a Sig_structure object and populate it with the appropriate fields.
2. Create the value ToBeSigned by encoding the Sig_structure to a byte string, using the encoding described in Section 14.
3. Call the signature verification algorithm passing in K (the key to verify with), alg (the algorithm used sign with), ToBeSigned (the value to sign), and sig (the signature to be verified).

In addition to performing the signature verification, one must also perform 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.5. Computing Counter Signatures

Counter signatures provide a method of associating different signature generated by different signers with some piece of content. This is normally used to provide a signature on a signature allowing for a proof that a signature existed at a given time (i.e., a Timestamp). In this document, we allow for counter signatures to exist in a greater number of environments. As an example, it is possible to place a counter signature in the unprotected attributes of a COSE_Encrypt object. This would allow for an intermediary to either verify that the encrypted byte stream has not been modified, without being able to decrypt it, or for the intermediary to assert that an encrypted byte stream either existed at a given time or passed through it in terms of routing (i.e., a proxy signature).

An example of a counter signature on a signature can be found in Appendix C.1.3. An example of a counter signature in an encryption object can be found in Appendix C.3.3.

The creation and validation of counter signatures over the different items relies on the fact that the structure of the objects have the same structure. The elements are a set of protected attributes, a set of unprotected attributes, and a body, in that order. This means that the Sig_structure can be used in a uniform manner to get the byte stream for processing a signature. If the counter signature is going to be computed over a COSE_Encrypt structure, the body_protected and payload items can be mapped into the Sig_structure in the same manner as from the COSE_Sign structure.

It should be noted that only a signature algorithm with appendix (see Section 8) can be used for counter signatures. This is because the body should be able to be processed without having to evaluate the counter signature, and this is not possible for signature schemes with message recovery.

5. Encryption Objects

COSE supports two different encryption structures. COSE_Encrypt0 is used when a recipient structure is not needed because the key to be used is known implicitly. COSE_Encrypt is used the rest of the time. This includes cases where there are multiple recipients or a recipient algorithm other than direct is used.

5.1. Enveloped COSE Structure

The enveloped structure allows for one or more recipients of a message. There are provisions for parameters about the content and parameters about the recipient information to be carried in the message. The protected parameters associated with the content are authenticated by the content encryption algorithm. The protected parameters associated with the recipient are authenticated by the recipient algorithm (when the algorithm supports it). Examples of parameters about the content are the type of the content and the content encryption algorithm. Examples of parameters about the recipient are the recipient's key identifier and the recipient's encryption algorithm.

The same techniques and structures are used for encrypting both the plain text and the keys. This is different from the approach used by both CMS [RFC5652] and JSON Web Encryption (JWE) [RFC7516] where different structures are used for the content layer and for the recipient layer. Two structures are defined: COSE_Encrypt to hold the encrypted content and COSE_recipient to hold the encrypted keys for recipients. Examples of encrypted messages can be found in Appendix C.3.

The COSE_Encrypt structure can be encoded either tagged or untagged depending on the context it will be used in. A tagged COSE_Encrypt structure is identified by the CBOR tag TBD2. The CDDL fragment that represents this is:

COSE_Encrypt_Tagged = #6.992(COSE_Encrypt) ; Replace 992 with TBD2

The COSE_Encrypt structure is a CBOR array. The fields of the array in order are:

protected

as described in Section 3.

unprotected

as described in Section 3. '

ciphertext

contains the cipher text encoded as a bstr. If the cipher text is to be transported independently of the control information about the encryption process (i.e., detached content) then the field is encoded as a nil value.

recipients

contains an array of recipient information structures. The type for the recipient information structure is a COSE_recipient.

The CDDL fragment that corresponds to the above text is:

COSE_Encrypt = [
    Headers,
    ciphertext : bstr / nil,
    recipients : [+COSE_recipient]
]

The COSE_recipient structure is a CBOR array. The fields of the array in order are:

protected

as described in Section 3.

unprotected

as described in Section 3.

ciphertext

contains the encrypted key encoded as a bstr. All encoded keys are symetric keys, the binary value of the key is the content. If there is not an encrypted key, then this field is encoded as a nil value.

recipients

contains an array of recipient information structures. The type for the recipient information structure is a COSE_recipient. (An example of this can be found in Appendix B.) If there are no recipient information structures, this element is absent.

The CDDL fragment that corresponds to the above text for COSE_recipient is:

COSE_recipient = [    
    Headers,
    ciphertext : bstr / nil,
    ? recipients : [+COSE_recipient]
]

5.1.1. Content Key Distribution Methods

An encrypted message consists of an encrypted content and an encrypted CEK for one or more recipients. The CEK is encrypted for each recipient, using a key specific to that recipient. The details of this encryption depend on which class the recipient algorithm falls into. Specific details on each of the classes can be found in Section 12. A short summary of the five content key distribution methods is:

direct:

The CEK is the same as the identified previously distributed symmetric key or derived from a previously distributed secret. No CEK is transported in the message.

symmetric key-encryption keys:

The CEK is encrypted using a previously distributed symmetric KEK.

key agreement:

The recipient's public key and a sender's private key are used to generate a pairwise secret, a KDF is applied to derive a key, and then the CEK is either the derived key or encrypted by the derived key.

key transport:

The CEK is encrypted with the recipient's public key. No key transport algorithms are defined in this document.

passwords:

The CEK is encrypted in a KEK that is derived from a password. No password algorithms are defined in this document.

5.2. Single Recipient Encrypted

The COSE_Encrypt0 encrypted structure does not have the ability to specify recipients of the message. The structure assumes that the recipient of the object will already know the identity of the key to be used in order to decrypt the message. If a key needs to be identified to the recipient, the enveloped structure ought to be used.

Examples of encrypted messages can be found in Appendix C.3.

The COSE_Encrypt0 structure can be encoded either tagged or untagged depending on the context it will be used in. A tagged COSE_Encrypt0 structure is identified by the CBOR tag TBD3. The CDDL fragment that represents this is:

COSE_Encrypt0_Tagged = #6.993(COSE_Encrypt0) ; Replace 993 with TBD3

The COSE_Encrypt0 structure is a CBOR array. The fields of the array in order are:

protected

as described in Section 3.

unprotected

as described in Section 3.

ciphertext

as described in Section 5.1.

The CDDL fragment for COSE_Encrypt0 that corresponds to the above text is:

COSE_Encrypt0 = [
    Headers,
    ciphertext : bstr / nil,
]

5.3. How to encrypt and decrypt for AEAD Algorithms

The encryption algorithm for AEAD algorithms is fairly simple. The first step is to create a consistent byte stream for the authenticated data structure. For this purpose, we use an Enc_structure. The Enc_structure is a CBOR array. The fields of the Enc_structure in order are:

1. A text string identifying the context of the authenticated data structure. The context string is:

   "Encrypt0"

   for the content encryption of a COSE_Encrypt0 data structure.

   "Encrypt"

   for the first layer of a COSE_Encrypt data structure (i.e., for content encryption).

   "Enc_Recipient"

   for a recipient encoding to be placed in an COSE_Encrypt data structure.

   "Mac_Recipient"

   for a recipient encoding to be placed in a MACed message structure.

   "Rec_Recipient"

   for a recipient encoding to be placed in a recipient structure.

2. The protected attributes from the body structure encoded in a bstr type. If there are no protected attributes, a bstr of length zero is used.
3. The protected attributes from the application encoded in a bstr type. If this field is not supplied, it defaults to a zero length bstr. (See Section 4.3 for application guidance on constructing this field.)

The CDDL fragment that describes the above text is:

Enc_structure = [
    context : "Encrypt" / "Encrypt0" / "Enc_Recipient" /
        "Mac_Recipient" / "Rec_Recipient",
    protected : empty_or_serialized_map,
    external_aad : bstr
]

How to encrypt a message:

1. Create an Enc_structure and populate it with the appropriate fields.
2. Encode the Enc_structure to a byte stream (AAD), using the encoding described in Section 14.
3. Determine the encryption key (K). This step is dependent on the class of recipient algorithm being used. For:

   No Recipients:

   The key to be used is determined by the algorithm and key at the current layer. Examples are key transport keys Section 12.3, key wrap keys Section 12.2.1 or pre-shared secrets.

   Direct Encryption and Direct Key Agreement:

   The key is determined by the key and algorithm in the recipient structure. The encryption algorithm and size of the key to be used are inputs into the KDF used for the recipient. (For direct, the KDF can be thought of as the identity operation.) Examples of these algorithms are found in Section 12.1.2 and Section 12.4.1.

   Other:

   The key is randomly or pseudo-randomly generated.

4. Call the encryption algorithm with K (the encryption key), P (the plain text) and AAD. Place the returned cipher text into the 'ciphertext' field of the structure.
5. For recipients of the message, recursively perform the encryption algorithm for that recipient, using K (the encryption key) as the plain text.

How to decrypt a message:

1. Create a Enc_structure and populate it with the appropriate fields.
2. Encode the Enc_structure to a byte stream (AAD), using the encoding described in Section 14.
3. Determine the decryption key. This step is dependent on the class of recipient algorithm being used. For:

   No Recipients:

   The key to be used is determined by the algorithm and key at the current layer. Examples are key transport keys Section 12.3, key wrap keys Section 12.2.1 or pre-shared secrets.

   Direct Encryption and Direct Key Agreement:

   The key is determined by the key and algorithm in the recipient structure. The encryption algorithm and size of the key to be used are inputs into the KDF used for the recipient. (For direct, the KDF can be thought of as the identity operation.) Examples of these algorithms are found in Section 12.1.2 and Section 12.4.1.

   Other:

   The key is determined by decoding and decrypting one of the recipient structures.

4. Call the decryption algorithm with K (the decryption key to use), C (the cipher text) and AAD.

5.4. How to encrypt and decrypt for AE Algorithms

How to encrypt a message:

1. Verify that the 'protected' field is empty.
2. Verify that there was no external additional authenticated data supplied for this operation.
3. Determine the encryption key. This step is dependent on the class of recipient algorithm being used. For:

   No Recipients:

   The key to be used is determined by the algorithm and key at the current layer. Examples are key transport keys Section 12.3, key wrap keys Section 12.2.1 or pre-shared secrets.

   Direct Encryption and Direct Key Agreement:

   The key is determined by the key and algorithm in the recipient structure. The encryption algorithm and size of the key to be used are inputs into the KDF used for the recipient. (For direct, the KDF can be thought of as the identity operation.) Examples of these algorithms are found in Section 12.1.2 and Section 12.4.1.

   Other:

   The key is randomly generated.

4. Call the encryption algorithm with K (the encryption key to use) and the P (the plain text). Place the returned cipher text into the 'ciphertext' field of the structure.
5. For recipients of the message, recursively perform the encryption algorithm for that recipient, using K (the encryption key) as the plain text.

How to decrypt a message:

1. Verify that the 'protected' field is empty.
2. Verify that there was no external additional authenticated data supplied for this operation.
3. Determine the decryption key. This step is dependent on the class of recipient algorithm being used. For:

   No Recipients:

   The key to be used is determined by the algorithm and key at the current layer. Examples are key transport keys Section 12.3, key wrap keys Section 12.2.1 or pre-shared secrets.

   Direct Encryption and Direct Key Agreement:

   The key is determined by the key and algorithm in the recipient structure. The encryption algorithm and size of the key to be used are inputs into the KDF used for the recipient. (For direct, the KDF can be thought of as the identity operation.) Examples of these algorithms are found in Section 12.1.2 and Section 12.4.1.

   Other:

   The key is determined by decoding and decrypting one of the recipient structures.

4. Call the decryption algorithm with K (the decryption key to use), and C (the cipher text).

6. MAC Objects

COSE supports two different MAC structures. COSE_MAC0 is used when a recipient structure is not needed because the key to be used is implicitly known. COSE_MAC is used for all other cases. These include a requirement for multiple recipients, the key being unknown, and a recipient algorithm of other than direct.

In this section, we describe the structure and methods to be used when doing MAC authentication in COSE. This document allows for the use of all of the same classes of recipient algorithms as are allowed for encryption.

When using MAC operations, there are two modes in which they can be used. The first is just a check that the content has not been changed since the MAC was computed. Any class of recipient algorithm can be used for this purpose. The second mode is to both check that the content has not been changed since the MAC was computed, and to use the recipient algorithm to verify who sent it. The classes of recipient algorithms that support this are those that use a pre-shared secret or do static-static key agreement (without the key wrap step). In both of these cases, the entity that created and sent the message MAC can be validated. (This knowledge of sender assumes that there are only two parties involved and you did not send the message to yourself.) The origination property can be obtained with both of the MAC message structures.

6.1. MACed Message with Recipients

The multiple recipient MACed message uses two structures, the COSE_Mac structure defined in this section for carrying the body and the COSE_recipient structure (Section 5.1) to hold the key used for the MAC computation. Examples of MACed messages can be found in Appendix C.5.

The MAC structure can be encoded either tagged or untagged depending on the context it will be used in. A tagged COSE_Mac structure is identified by the CBOR tag TBD4. The CDDL fragment that represents this is:

COSE_Mac_Tagged = #6.994(COSE_Mac)         ; Replace 994 with TBD4

The COSE_Mac structure is a CBOR array. The fields of the array in order are:

protected

as described in Section 3.

unprotected

as described in Section 3.

payload

contains the serialized content to be MACed. If the payload is not present in the message, the application is required to supply the payload separately. The payload is wrapped in a bstr to ensure that it is transported without changes. If the payload is transported separately (i.e., detached content), then a nil CBOR value is placed in this location and it is the responsibility of the application to ensure that it will be transported without changes.

tag

contains the MAC value.

recipients

as described in Section 5.1.

The CDDL fragment that represents the above text for COSE_Mac follows.

COSE_Mac = [
   Headers,
   payload : bstr / nil,
   tag : bstr,
   recipients :[+COSE_recipient]
]

6.2. MACed Messages with Implicit Key

In this section, we describe the structure and methods to be used when doing MAC authentication for those cases where the recipient is implicitly known.

The MACed message uses the COSE_Mac0 structure defined in this section for carrying the body. Examples of MACed messages with an implicit key can be found in Appendix C.6.

The MAC structure can be encoded either tagged or untagged depending on the context it will be used in. A tagged COSE_Mac0 structure is identified by the CBOR tag TBD6. The CDDL fragment that represents this is:

COSE_Mac0_Tagged = #6.996(COSE_Mac0)    ; Replace 996 with TBD6

The COSE_Mac0 structure is a CBOR array. The fields of the array in order are:

protected

as described in Section 3.

unprotected

as described in Section 3.

payload

as described in Section 6.1.

tag

contains the MAC value.

The CDDL fragment that corresponds to the above text is:

COSE_Mac0 = [
   Headers,
   payload : bstr / nil,
   tag : bstr,
]

6.3. How to compute and verify a MAC

In order to get a consistent encoding of the data to be authenticated, the MAC_structure is used to have a canonical form. The MAC_structure is a CBOR array. The fields of the MAC_structure in order are:

1. A text string that identifies the structure that is being encoded. This string is "MAC" for the COSE_Mac structure. This string is "MAC0" for the COSE_Mac0 structure.
2. The protected attributes from the COSE_MAC structure. If there are no protected attributes, a zero length bstr is used.
3. The protected attributes from the application encoded as a bstr type. If this field is not supplied, it defaults to a zero length binary string. (See Section 4.3 for application guidance on constructing this field.)
4. The payload to be MAC-ed encoded in a bstr type. The payload is placed here independent of how it is transported.

The CDDL fragment that corresponds to the above text is:

MAC_structure = [
     context : "MAC" / "MAC0",
     protected : empty_or_serialized_map,
     external_aad : bstr,
     payload : bstr
]

The steps to compute a MAC are:

1. Create a MAC_structure and populate it with the appropriate fields.
2. Create the value ToBeMaced by encoding the MAC_structure to a byte stream, using the encoding described in Section 14.
3. Call the MAC creation algorithm passing in K (the key to use), alg (the algorithm to MAC with) and ToBeMaced (the value to compute the MAC on).
4. Place the resulting MAC in the 'tag' field of the COSE_Mac or COSE_Mac0 structure.
5. Encrypt and encode the MAC key for each recipient of the message.

The steps to verify a MAC are:

1. Create a MAC_structure object and populate it with the appropriate fields.
2. Create the value ToBeMaced by encoding the MAC_structure to a byte stream, using the encoding described in Section 14.
3. Obtain the cryptographic key from one of the recipients of the message.
4. Call the MAC creation algorithm passing in K (the key to use), alg (the algorithm to MAC with) and ToBeMaced (the value to compute the MAC on).
5. Compare the MAC value to the 'tag' field of the COSE_Mac or COSE_Mac0 structure.

7. Key Objects

A COSE Key structure is built on a CBOR map object. The set of common parameters that can appear in a COSE Key can be found in the IANA "COSE Key Common Parameters" registry (Section 16.5). Additional parameters defined for specific key types can be found in the IANA "COSE Key Type Parameters" registry (Section 16.6).

A COSE Key Set uses a CBOR array object as its underlying type. The values of the array elements are COSE Keys. A Key Set MUST have at least one element in the array. Examples of Key Sets can be found in Appendix C.7.

Each element in a key set MUST be processed independently. If one element in a key set is either malformed or uses a key that is not understood by an application, that key is ignored and the other keys are processed normally.

The element "kty" is a required element in a COSE_Key map.

The CDDL grammar describing COSE_Key and COSE_KeySet is:

COSE_Key = {
    1 => tstr / int,          ; kty
    ? 2 => bstr,              ; kid
    ? 3 => tstr / int,        ; alg
    ? 4 => [+ (tstr / int) ], ; key_ops
    ? 5 => bstr,              ; Base IV
    * label => values
}

COSE_KeySet = [+COSE_Key]

7.1. COSE Key Common Parameters

This document defines a set of common parameters for a COSE Key object. Table 3 provides a summary of the parameters defined in this section. There are also parameters that are defined for specific key types. Key type specific parameters can be found in Section 13.

signature = Sign(message content, key)

valid = Verification(message content, key, signature)

signature, message sent = Sign(message content, key)

valid, message content = Verification(message sent, key, signature)

tag = MAC_Create(message content, key)

valid = MAC_Verify(message content, key, tag)

ciphertext = Encrypt(message content, key, additional data)

valid, message content = Decrypt(cipher text, key, additional data)

PartyInfo = (
    identity : bstr / nil,
    nonce : bstr / int / nil,
    other : bstr / nil,
)

COSE_KDF_Context = [
    AlgorithmID : int / tstr,
    PartyUInfo : [ PartyInfo ],
    PartyVInfo : [ PartyInfo ],
    SuppPubInfo : [
        keyDataLength : uint,
        protected : empty_or_serialized_map,
        ? other : bstr
    ],
    ? SuppPrivInfo : bstr
]

encryptedKey = KeyWrap(KDF(DH-Shared, context), CEK)

992(
  [
    / protected / h'a10101' / {
        \ alg \ 1:1 \ AES-GCM 128 \
      } / , 
    / unprotected / {
      / iv / 5:h'02d1f7e6f26c43d4868d87ce'
    }, 
    / ciphertext / h'64f84d913ba60a76070a9a48f26e97e863e2852948658f0
811139868826e89218a75715b', 
    / recipients / [
      [
        / protected / h'', 
        / unprotected / {
          / alg / 1:-3 / A128KW /
        }, 
        / ciphertext / h'dbd43c4e9d719c27c6275c67d628d493f090593db82
18f11', 
        / recipients / [
          [
            / protected / h'a1013818' / {
                \ alg \ 1:-25 \ ECDH-ES + HKDF-256 \
              } / , 
            / unprotected / {
              / ephemeral / -1:{
                / kty / 1:2, 
                / crv / -1:1, 
                / x / -2:h'b2add44368ea6d641f9ca9af308b4079aeb519f11
e9b8a55a600b21233e86e68', 
                / y / -3:false
              }, 
              / kid / 4:'meriadoc.brandybuck@buckland.example'
            }, 
            / ciphertext / h''
          ]
        ]
      ]
    ]
  ]
)

gem install cbor-diag

diag2cbor.rb < inputfile > outputfile

//artwork[@type='CDDL']/text()

991(
  [
    / protected / h'', 
    / unprotected / {}, 
    / payload / 'This is the content.', 
    / signatures / [
      [
        / protected / h'a10126' / {
            \ alg \ 1:-7 \ ECDSA 256 \
          } / , 
        / unprotected / {
          / kid / 4:'11'
        }, 
        / signature / h'eae868ecc176883766c5dc5ba5b8dca25dab3c2e56a5
51ce5705b793914348e14eea4aee6e0c9f09db4ef3ddeca8f3506cd1a98a8fb64327
be470355c9657ce0'
      ]
    ]
  ]
)

991(
  [
    / protected / h'', 
    / unprotected / {}, 
    / payload / 'This is the content.', 
    / signatures / [
      [
        / protected / h'a10126' / {
            \ alg \ 1:-7 \ ECDSA 256 \
          } / , 
        / unprotected / {
          / kid / 4:'11'
        }, 
        / signature / h'0dc1c5e62719d8f3cce1468b7c881eee6a8088b46bf8
36ae956dd38fe93199199951a6a5e02a24aed5edde3509748366b1c539aaef7dea34
f2cd618fe19fe55d'
      ], 
      [
        / protected / h'a1013823' / {
            \ alg \ 1:-36
          } / , 
        / unprotected / {
          / kid / 4:'bilbo.baggins@hobbiton.example'
        }, 
        / signature / h'012ce5b1dfe8b5aa6eaa09a54c58a84ad0900e4fdf27
59ec22d1c861cccd75c7e1c4025a2da35e512fc2874d6ac8fd862d09ad07ed2deac2
97b897561e04a8d42476017c11a4a34e26c570c9eff22c1dc84d56cdf6e03ed34bc9
e934c5fdf676c7948d79e97dfe161730217c57748aadb364a0207cee811e9dde65ae
37942e8a8348cc91'
      ]
    ]
  ]
)

991(
  [
    / protected / h'', 
    / unprotected / {
      / countersign / 7:[
        / protected / h'a10126' / {
            \ alg \ 1:-7 \ ECDSA 256 \
          } / , 
        / unprotected / {
          / kid / 4:'11'
        }, 
        / signature / h'c9d3402485aa585cee3efc69b14496c0b00714584b26
0f8e05764b7dbc70ae2b23b89812f5895b805f07a792f7ce77ef6d63875dc37d6a78
ef4d175da45c9a51'
      ]
    }, 
    / payload / 'This is the content.', 
    / signatures / [
      [
        / protected / h'a10126' / {
            \ alg \ 1:-7 \ ECDSA 256 \
          } / , 
        / unprotected / {
          / kid / 4:'11'
        }, 
        / signature / h'eae868ecc176883766c5dc5ba5b8dca25dab3c2e56a5
51ce5705b793914348e14eea4aee6e0c9f09db4ef3ddeca8f3506cd1a98a8fb64327
be470355c9657ce0'
      ]
    ]
  ]
)

991(
  [
    / protected / h'a2687265736572766564f40281687265736572766564' / 
{
        "reserved":false, 
        \ crit \ 2:[
          "reserved"
        ]
      } / , 
    / unprotected / {}, 
    / payload / 'This is the content.', 
    / signatures / [
      [
        / protected / h'a10126' / {
            \ alg \ 1:-7 \ ECDSA 256 \
          } / , 
        / unprotected / {
          / kid / 4:'11'
        }, 
        / signature / h'eae868ecc176883766c5dc5ba5b8dca25dab3c2e56a5
51ce5705b793914348e1ff259ead2c38d8a7d8a9c87c2ce534d762dab059773115a6
176fa780e85b6b25'
      ]
    ]
  ]
)

997(
  [
    / protected / h'a10126' / {
        \ alg \ 1:-7 \ ECDSA 256 \
      } / , 
    / unprotected / {
      / kid / 4:'11'
    }, 
    / payload / 'This is the content.', 
    / signature / h'eae868ecc176883766c5dc5ba5b8dca25dab3c2e56a551ce
5705b793914348e19f43d6c6ba654472da301b645b293c9ba939295b97c4bdb84778
2bff384c5794'
  ]
)

992(
  [
    / protected / h'a10101' / {
        \ alg \ 1:1 \ AES-GCM 128 \
      } / , 
    / unprotected / {
      / iv / 5:h'c9cf4df2fe6c632bf7886413'
    }, 
    / 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''
      ]
    ]
  ]
)

992(
  [
    / protected / h'a1010a' / {
        \ alg \ 1:10 \ AES-CCM-16-64-128 \
      } / , 
    / unprotected / {
      / iv / 5:h'89f52f65a1c580933b5261a76c'
    }, 
    / ciphertext / h'753548a19b1307084ca7b2056924ed95f2e3b17006dfe93
1b687b847', 
    / recipients / [
      [
        / protected / h'a10129' / {
            \ alg \ 1:-10
          } / , 
        / unprotected / {
          / salt / -20:'aabbccddeeffgghh', 
          / kid / 4:'our-secret'
        }, 
        / ciphertext / h''
      ]
    ]
  ]
)

992(
  [
    / protected / h'a10101' / {
        \ alg \ 1:1 \ AES-GCM 128 \
      } / , 
    / unprotected / {
      / iv / 5:h'c9cf4df2fe6c632bf7886413', 
      / countersign / 7:[
        / protected / h'a1013823' / {
            \ alg \ 1:-36
          } / , 
        / unprotected / {
          / kid / 4:'bilbo.baggins@hobbiton.example'
        }, 
        / signature / h'00aa98cbfd382610a375d046a275f30266e8d0faacb9
069fde06e37825ae7825419c474f416ded0c8e3e7b55bff68f2a704135bdf99186f6
6659461c8cf929cc7fb300f5e2b33c3b433655042ff719804ff73b0be3e988ecebc0
c70ef6616996809c6eb59a918dbe0a5edb0d15137ece0aba2a0b0f68ad2631cb62f2
ea4d7099804218b0'
      ]
    }, 
    / 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''
      ]
    ]
  ]
)

992(
  [
    / protected / h'a10101' / {
        \ alg \ 1:1 \ AES-GCM 128 \
      } / , 
    / unprotected / {
      / iv / 5:h'02d1f7e6f26c43d4868d87ce'
    }, 
    / ciphertext / h'64f84d913ba60a76070a9a48f26e97e863e28529d8f5335
e5f0165eee976b4a5f6c6f09d', 
    / recipients / [
      [
        / protected / h'a101381f' / {
            \ alg \ 1:-32 \ ECHD-SS+A128KW \
          } / , 
        / unprotected / {
          / static kid / -3:'peregrin.took@tuckborough.example', 
          / kid / 4:'meriadoc.brandybuck@buckland.example', 
          / U nonce / -22:h'0101'
        }, 
        / ciphertext / h'41e0d76f579dbd0d936a662d54d8582037de2e366fd
e1c62'
      ]
    ]
  ]
)

993(
  [
    / protected / h'a1010a' / {
        \ alg \ 1:10 \ AES-CCM-16-64-128 \
      } / , 
    / unprotected / {
      / iv / 5:h'89f52f65a1c580933b5261a78c'
    }, 
    / ciphertext / h'5974e1b99a3a4cc09a659aa2e9e7fff161d38ce7edd5617
388e77baf'
  ]
)

993(
  [
    / protected / h'a1010a' / {
        \ alg \ 1:10 \ AES-CCM-16-64-128 \
      } / , 
    / unprotected / {
      / partial iv / 6:h'61a7'
    }, 
    / ciphertext / h'252a8911d465c125b6764739700f0141ed09192da5c69e5
33abf852b'
  ]
)

994(
  [
    / protected / h'a1010f' / {
        \ alg \ 1:15 \ AES-CBC-MAC-256//64 \
      } / , 
    / unprotected / {}, 
    / payload / 'This is the content.', 
    / tag / h'9e1226ba1f81b848', 
    / recipients / [
      [
        / protected / h'', 
        / unprotected / {
          / alg / 1:-6 / direct /, 
          / kid / 4:'our-secret'
        }, 
        / ciphertext / h''
      ]
    ]
  ]
)

994(
  [
    / protected / h'a10105' / {
        \ alg \ 1:5 \ HMAC 256//256 \
      } / , 
    / unprotected / {}, 
    / payload / 'This is the content.', 
    / tag / h'81a03448acd3d305376eaa11fb3fe416a955be2cbe7ec96f012c99
4bc3f16a41', 
    / recipients / [
      [
        / protected / h'a101381a' / {
            \ alg \ 1:-27 \ ECDH-SS + HKDF-256 \
          } / , 
        / unprotected / {
          / static kid / -3:'peregrin.took@tuckborough.example', 
          / kid / 4:'meriadoc.brandybuck@buckland.example', 
          / U nonce / -22:h'4d8553e7e74f3c6a3a9dd3ef286a8195cbf8a23d
19558ccfec7d34b824f42d92bd06bd2c7f0271f0214e141fb779ae2856abf585a583
68b017e7f2a9e5ce4db5'
        }, 
        / ciphertext / h''
      ]
    ]
  ]
)

994(
  [
    / protected / h'a1010e' / {
        \ alg \ 1:14 \ AES-CBC-MAC-128//64 \
      } / , 
    / unprotected / {}, 
    / payload / 'This is the content.', 
    / tag / h'36f5afaf0bab5d43', 
    / recipients / [
      [
        / protected / h'', 
        / unprotected / {
          / alg / 1:-5 / A256KW /, 
          / kid / 4:'018c0ae5-4d9b-471b-bfd6-eef314bc7037'
        }, 
        / ciphertext / h'711ab0dc2fc4585dce27effa6781c8093eba906f227
b6eb0'
      ]
    ]
  ]
)

994(
  [
    / protected / h'a10105' / {
        \ alg \ 1:5 \ HMAC 256//256 \
      } / , 
    / unprotected / {}, 
    / payload / 'This is the content.', 
    / tag / h'bf48235e809b5c42e995f2b7d5fa13620e7ed834e337f6aa43df16
1e49e9323e', 
    / recipients / [
      [
        / protected / h'a101381c' / {
            \ alg \ 1:-29 \ ECHD-ES+A128KW \
          } / , 
        / unprotected / {
          / ephemeral / -1:{
            / kty / 1:2, 
            / crv / -1:3, 
            / x / -2:h'0043b12669acac3fd27898ffba0bcd2e6c366d53bc4db
71f909a759304acfb5e18cdc7ba0b13ff8c7636271a6924b1ac63c02688075b55ef2
d613574e7dc242f79c3', 
            / y / -3:true
          }, 
          / kid / 4:'bilbo.baggins@hobbiton.example'
        }, 
        / ciphertext / h'339bc4f79984cdc6b3e6ce5f315a4c7d2b0ac466fce
a69e8c07dfbca5bb1f661bc5f8e0df9e3eff5'
      ], 
      [
        / protected / h'', 
        / unprotected / {
          / alg / 1:-5 / A256KW /, 
          / kid / 4:'018c0ae5-4d9b-471b-bfd6-eef314bc7037'
        }, 
        / ciphertext / h'0b2c7cfce04e98276342d6476a7723c090dfdd15f9a
518e7736549e998370695e6d6a83b4ae507bb'
      ]
    ]
  ]
)

996(
  [
    / protected / h'a1010f' / {
        \ alg \ 1:15 \ AES-CBC-MAC-256//64 \
      } / , 
    / unprotected / {}, 
    / payload / 'This is the content.', 
    / tag / h'726043745027214f'
  ]
)

[
  {
    -1:1, 
    -2:h'65eda5a12577c2bae829437fe338701a10aaa375e1bb5b5de108de439c0
8551d', 
    -3:h'1e52ed75701163f7f9e40ddf9f341b3dc9ba860af7e0ca7ca7e9eecd008
4d19c', 
    1:2, 
    2:'meriadoc.brandybuck@buckland.example'
  }, 
  {
    -1:1, 
    -2:h'bac5b11cad8f99f9c72b05cf4b9e26d244dc189f745228255a219a86d6a
09eff', 
    -3:h'20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6ed28bbf
c117e', 
    1:2, 
    2:'11'
  }, 
  {
    -1:3, 
    -2:h'0072992cb3ac08ecf3e5c63dedec0d51a8c1f79ef2f82f94f3c737bf5de
7986671eac625fe8257bbd0394644caaa3aaf8f27a4585fbbcad0f2457620085e5c8
f42ad', 
    -3:h'01dca6947bce88bc5790485ac97427342bc35f887d86d65a089377e247e
60baa55e4e8501e2ada5724ac51d6909008033ebc10ac999b9d7f5cc2519f3fe1ea1
d9475', 
    1:2, 
    2:'bilbo.baggins@hobbiton.example'
  }, 
  {
    -1:1, 
    -2:h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbfbf054e1c7b4d91
d6280', 
    -3:h'f01400b089867804b8e9fc96c3932161f1934f4223069170d924b7e03bf
822bb', 
    1:2, 
    2:'peregrin.took@tuckborough.example'
  }
]

[
  {
    1:2, 
    2:'meriadoc.brandybuck@buckland.example', 
    -1:1, 
    -2:h'65eda5a12577c2bae829437fe338701a10aaa375e1bb5b5de108de439c0
8551d', 
    -3:h'1e52ed75701163f7f9e40ddf9f341b3dc9ba860af7e0ca7ca7e9eecd008
4d19c', 
    -4:h'aff907c99f9ad3aae6c4cdf21122bce2bd68b5283e6907154ad911840fa
208cf'
  }, 
  {
    1:2, 
    2:'11', 
    -1:1, 
    -2:h'bac5b11cad8f99f9c72b05cf4b9e26d244dc189f745228255a219a86d6a
09eff', 
    -3:h'20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6ed28bbf
c117e', 
    -4:h'57c92077664146e876760c9520d054aa93c3afb04e306705db609030850
7b4d3'
  }, 
  {
    1:2, 
    2:'bilbo.baggins@hobbiton.example', 
    -1:3, 
    -2:h'0072992cb3ac08ecf3e5c63dedec0d51a8c1f79ef2f82f94f3c737bf5de
7986671eac625fe8257bbd0394644caaa3aaf8f27a4585fbbcad0f2457620085e5c8
f42ad', 
    -3:h'01dca6947bce88bc5790485ac97427342bc35f887d86d65a089377e247e
60baa55e4e8501e2ada5724ac51d6909008033ebc10ac999b9d7f5cc2519f3fe1ea1
d9475', 
    -4:h'00085138ddabf5ca975f5860f91a08e91d6d5f9a76ad4018766a476680b
55cd339e8ab6c72b5facdb2a2a50ac25bd086647dd3e2e6e99e84ca2c3609fdf177f
eb26d'
  }, 
  {
    1:4, 
    2:'our-secret', 
    -1:h'849b57219dae48de646d07dbb533566e976686457c1491be3a76dcea6c4
27188'
  }, 
  {
    1:2, 
    -1:1, 
    2:'peregrin.took@tuckborough.example', 
    -2:h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbfbf054e1c7b4d91
d6280', 
    -3:h'f01400b089867804b8e9fc96c3932161f1934f4223069170d924b7e03bf
822bb', 
    -4:h'02d1f7e6f26c43d4868d87ceb2353161740aacf1f7163647984b522a848
df1c3'
  }, 
  {
    1:4, 
    2:'our-secret2', 
    -1:h'849b5786457c1491be3a76dcea6c4271'
  }, 
  {
    1:4, 
    2:'018c0ae5-4d9b-471b-bfd6-eef314bc7037', 
    -1:h'849b57219dae48de646d07dbb533566e976686457c1491be3a76dcea6c4
27188'
  }
]