Skip to main content

6. MAC Objects

  1. 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, or a recipient algorithm 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.

There are two modes in which MAC operations 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 use the recipient algorithm to verify who sent it. The classes of recipient algorithms that support this are those that use a preshared secret or do Static- Static (SS) 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 the sender assumes that there are only two parties involved and that 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

A 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 as either tagged or untagged depending on the context it will be used in. A tagged COSE_Mac structure is identified by the CBOR tag 97. The CDDL fragment that represents this is:

COSE_Mac_Tagged = #6.97(COSE_Mac)

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

protected: This is as described in Section 3.

unprotected: This is as described in Section 3.

payload: This field 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: This field contains the MAC value.

recipients: This is 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 as either tagged or untagged, depending on the context it will be used in. A tagged COSE_Mac0 structure is identified by the CBOR tag 17. The CDDL fragment that represents this is:

COSE_Mac0_Tagged = #6.17(COSE_Mac0)

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

protected: This is as described in Section 3.

unprotected: This is as described in Section 3.

payload: This is as described in Section 6.1.

tag: This field 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 create the canonical form. The MAC_structure is a CBOR array. The fields of the MAC_structure, in order, are:

  1. A context text string that identifies the structure that is being encoded. This context text string is "MAC" for the COSE_Mac structure. This context text string is "MAC0" for the COSE_Mac0 structure.

  2. The protected attributes from the body structure. If there are no protected attributes, a zero-length bstr is used.

  3. The externally supplied data from the application, encoded as a bstr type. If this field is not supplied, it defaults to a zero- length byte string. (See Section 4.3 for application guidance on constructing this field.)

  4. The payload to be MACed, encoded in a bstr type. The full payload is used 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 string, using the encoding described in Section 9.

  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. For COSE_Mac structures, encrypt and encode the MAC key for each recipient of the message.

The steps to verify 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 string, using the encoding described in Section 9.

  3. For COSE_Mac structures, obtain the cryptographic key by decoding and decrypting one of the recipient structures.

  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.

Last updated on