2. Basic COSE Structure

2. Basic COSE Structure

The COSE object structure is designed so that there can be a large amount of common code when parsing and processing the different types of security messages. All of the message structures are built on the CBOR array type. The first three elements of the array always contain the same information:

1. The protected header parameters, encoded and wrapped in a bstr.

2. The unprotected header parameters as a map.

3. The content of the message. The content is either the plaintext or the ciphertext, as appropriate. The content may be detached (i.e., transported separately from the COSE structure), but the location is still used. The content is wrapped in a bstr when present and is a nil value when detached.

Elements after this point are dependent on the specific message type.

COSE messages are built using the concept of layers to separate different types of cryptographic concepts. As an example of how this works, consider the COSE_Encrypt message (Section 5.1). This message type is broken into two layers: the content layer and the recipient layer. The content layer contains the encrypted plaintext and information about the encrypted message. The recipient layer contains the encrypted content encryption key (CEK) and information about how it is encrypted, for each recipient. A single-layer version of the encryption message COSE_Encrypt0 (Section 5.2) is provided for cases where the CEK is preshared.

Identification of which type of message has been presented is done by the following methods:

1. The specific message type is known from the context. This may be defined by a marker in the containing structure or by restrictions specified by the application protocol.

2. The message type is identified by a CBOR tag. Messages with a CBOR tag are known in this specification as tagged messages, while those without the CBOR tag are known as untagged messages. This document defines a CBOR tag for each of the message structures. These tags can be found in Table 1.

3. When a COSE object is carried in a media type of "application/ cose", the optional parameter "cose-type" can be used to identify the embedded object. The parameter is OPTIONAL if the tagged version of the structure is used. The parameter is REQUIRED if the untagged version of the structure is used. The value to use with the parameter for each of the structures can be found in Table 1.

4. When a COSE object is carried as a CoAP payload, the CoAP Content-Format Option can be used to identify the message content. The CoAP Content-Format values can be found in Table 2. The CBOR tag for the message structure is not required, as each security message is uniquely identified.

+==========+===============+===============+=======================+ | CBOR Tag | cose-type | Data Item | Semantics | +==========+===============+===============+=======================+ | 98 | cose-sign | COSE_Sign | COSE Signed Data | | | | | Object | +----------+---------------+---------------+-----------------------+ | 18 | cose-sign1 | COSE_Sign1 | COSE Single Signer | | | | | Data Object | +----------+---------------+---------------+-----------------------+ | 96 | cose-encrypt | COSE_Encrypt | COSE Encrypted Data | | | | | Object | +----------+---------------+---------------+-----------------------+ | 16 | cose-encrypt0 | COSE_Encrypt0 | COSE Single Recipient | | | | | Encrypted Data Object | +----------+---------------+---------------+-----------------------+ | 97 | cose-mac | COSE_Mac | COSE MACed Data | | | | | Object | +----------+---------------+---------------+-----------------------+ | 17 | cose-mac0 | COSE_Mac0 | COSE Mac w/o | | | | | Recipients Object | +----------+---------------+---------------+-----------------------+

               Table 1: COSE Message Identification

    +===========================+==========+=====+===========+
    | Media Type                | Encoding | ID  | Reference |
    +===========================+==========+=====+===========+
    | application/cose; cose-   |          | 98  | RFC 9052  |
    | type="cose-sign"          |          |     |           |
    +---------------------------+----------+-----+-----------+
    | application/cose; cose-   |          | 18  | RFC 9052  |
    | type="cose-sign1"         |          |     |           |
    +---------------------------+----------+-----+-----------+
    | application/cose; cose-   |          | 96  | RFC 9052  |
    | type="cose-encrypt"       |          |     |           |
    +---------------------------+----------+-----+-----------+
    | application/cose; cose-   |          | 16  | RFC 9052  |
    | type="cose-encrypt0"      |          |     |           |
    +---------------------------+----------+-----+-----------+
    | application/cose; cose-   |          | 97  | RFC 9052  |
    | type="cose-mac"           |          |     |           |
    +---------------------------+----------+-----+-----------+
    | application/cose; cose-   |          | 17  | RFC 9052  |
    | type="cose-mac0"          |          |     |           |
    +---------------------------+----------+-----+-----------+
    | application/cose-key      |          | 101 | RFC 9052  |
    +---------------------------+----------+-----+-----------+
    | application/cose-key-set  |          | 102 | RFC 9052  |
    +---------------------------+----------+-----+-----------+

              Table 2: CoAP Content-Formats for COSE

The following CDDL fragment identifies all of the top messages defined in this document. Separate nonterminals are defined for the tagged and untagged versions of the messages.

COSE_Messages = COSE_Untagged_Message / COSE_Tagged_Message

COSE_Untagged_Message = COSE_Sign / COSE_Sign1 / COSE_Encrypt / COSE_Encrypt0 / COSE_Mac / COSE_Mac0

COSE_Tagged_Message = COSE_Sign_Tagged / COSE_Sign1_Tagged / COSE_Encrypt_Tagged / COSE_Encrypt0_Tagged / COSE_Mac_Tagged / COSE_Mac0_Tagged