RATS Conceptual Messages Wrapper (CMW)

3.1. CMW Record

The format of the CMW record is shown in Figure 1. The JSON [STD90] and CBOR [STD94] representations are provided separately. Both the json-record and cbor-record have the same fields except for slight differences in the types discussed below.¶

json-record = [
  type: media-type
  value: base64url-string
  ? ind: uint .bits cm-type
]

cbor-record = [
  type: coap-content-format-type / media-type
  value: bytes
  ? ind: uint .bits cm-type
]

Each contains two or three members:¶

type:

Either a text string representing a Content-Type (e.g., an EAT media type [I-D.ietf-rats-eat-media-type]) or an unsigned integer corresponding to a CoAP Content-Format number (Section 12.3 of [RFC7252]). The latter MUST NOT be used in the JSON serialization.¶

value:

The RATS conceptual message serialized according to the value defined in the type member. When using JSON, the value field MUST be encoded as Base64 using the URL and filename safe alphabet (Section 5 of [RFC4648]) without padding. This always applies, even if the conceptual message format is already textual (e.g., a JWT EAT). When using CBOR, the value field MUST be encoded as a CBOR byte string.¶

ind:

An optional bitmap that indicates which conceptual message types are carried in the value field. Any combination (i.e., any value between 1 and 15, included) is allowed. This is useful only if the type is potentially ambiguous and there is no further context available to the CMW consumer to decide. For example, this might be the case if the base media type is not profiled (e.g., application/eat+cwt), if the value field contains multiple conceptual messages with different types (e.g., both Reference Values and Endorsements within the same application/signed-corim+cbor), or if the same profile identifier is shared by different conceptual messages. Future specifications may add new values to the ind field; see Section 10.4.¶

3.2. CMW CBOR Tags

CBOR Tags used as CMW may be derived from CoAP Content-Format numbers. If a CoAP content format exists for a RATS conceptual message, the TN() transform defined in Appendix B of [RFC9277] can be used to derive a corresponding CBOR tag in range [1668546817, 1668612095].¶

The RATS conceptual message is first serialized according to the Content-Format number associated with the CBOR tag and then encoded as a CBOR byte string, to which the tag is prepended.¶

The CMW CBOR Tag is defined in Figure 2 as a macro with two parameters:¶

• tn, the CBOR tag number¶

• $fmt, the definition of the associated conceptual message¶

cbor-tag<tn, $fmt> = #6.<tn>(bytes .cbor $fmt)

To add a new CMW, the $cbor-tag type socket is extended with a new instance of the CMW CBOR Tag macro. For example, to associate conceptual messages of type my-evidence with CBOR Tag 1668576819, one would extend $cbor-tag as follows:¶

$cbor-tag /= cbor-tag<1668576819, my-evidence>

my-evidence = {
  &(eat_nonce: 10) => bstr .size (8..64)
}

3.3. CMW Collections

Layered Attesters and composite devices (Sections 3.2 and 3.3 of [RFC9334]) generate Evidence that consists of multiple parts. For example, in data center servers, it is not uncommon for separate attesting environments (AE) to serve a subsection of the entire machine. One AE might measure and attest to what was booted on the main CPU, while another AE might measure and attest to what was booted on a SmartNIC plugged into a PCIe slot, and a third AE might measure and attest to what was booted on the machine's GPU. To allow aggregation of multiple, potentially non-homogeneous evidence formats collected from different AEs, this document defines a CMW "collection" as a container that holds several CMW items, each with a label that is unique within the scope of the collection.¶

Although originally designed to support layered Attester and composite device use cases, the CMW collection can be adapted for other scenarios that require the aggregation of RATS conceptual messages. For instance, collections may be used to group Endorsements, Reference Values, Attestation Results, and more. A single CMW collection can contain a mix of different message types, and it can also be used to carry messages related to multiple devices simultaneously.¶

The CMW collection (Figure 3) is defined as a CBOR map or JSON object with CMW values, either native or "tunnelled" (Section 3.3.3). The position of a cmw entry in the cmw-collection is not significant. Labels can be strings (or integers in the CBOR serialization) that serve as a mnemonic for different conceptual messages in the collection.¶

The "__cmwc_t" key is reserved for associating an optional type to the overall collection and MUST NOT be used for a label. The collection type is either a Uniform Resource Identifier (URI) or an object identifier (OID). The OID is always absolute and never relative.¶

Since the collection type is recursive, implementations may limit the allowed depth of nesting.¶

json-collection = {
  ? "__cmwc_t": ~uri / oid
  + &(label: text) => json-CMW / c2j-tunnel
}

cbor-collection = {
  ? "__cmwc_t": ~uri / oid
  + &(label: (int / text)) => cbor-CMW / j2c-tunnel
}

CMW itself provides no facilities for authenticity, integrity protection, or confidentiality. It is the responsibility of the designer for each use case to determine the necessary security properties and implement them accordingly. A secure channel (e.g., via TLS) or object-level security (e.g., using JWT) may suffice in some scenarios, but not in all.¶

When a CMW is used to carry the Evidence for composite or layered attestation for a single device, the security properties needed are that of attestation. In particular, all the members in a CMW must be bound together so that an attacker can not replace one Evidence message showing compromise with that from a non-compromised device. The authenticity and integrity protection MUST be attestation-oriented. For further security considerations about collections, see Section 9.2.¶

c2j-tunnel = [ "#cmw-c2j-tunnel", base64url-string ]
j2c-tunnel = [ "#cmw-j2c-tunnel", bytes ]

3.4. Decapsulation Algorithm

Once any external framing is removed (for example, if the CMW is carried in a certificate extension), the CMW decoder performs a 1-byte lookahead to determine how to decode the remaining byte buffer. The following pseudo-code illustrates this process:¶

func CMWTypeDemux(b []byte) (CMW, error) {
  if len(b) == 0 {
    return Unknown
  }

  if b[0] == 0x82 || b[0] == 0x83 {
    return CBORRecord
  } else if b[0] >= 0xc0 && b[0] <= 0xdb {
    return CBORTag
  } else if b[0] == 0x5b {
    return JSONRecord
  } else if b[0] == 0x7b {
    return JSONCollection
  } else if (b[0] >= 0xa0 && b[0] <= 0xbb) || b[0] == 0xbf {
    return CBORCollection
  }

  return Unknown
}

4.1. Encoding Requirements

A CMW collection carried in a "cmw" JWT claim MUST be a json-collection. A CMW collection carried in a "cmw" CWT claim MUST be a cbor-collection.¶

A CMW record carried in a "cmw" JWT claim MUST be a json-record. A CMW record carried in a "cmw" CWT claim MUST be a cbor-record.¶

5.1. ASN.1 Module

This section provides an ASN.1 module [X.680] for the CMW extension, following the conventions established in [RFC5912] and [RFC6268].¶

CMWExtn
  { iso(1) identified-organization(3) dod(6) internet(1)
    security(5) mechanisms(5) pkix(7) id-mod(0)
    id-mod-cmw-collection-extn(TBD) }

DEFINITIONS IMPLICIT TAGS ::=
BEGIN

IMPORTS
  EXTENSION
  FROM PKIX-CommonTypes-2009  -- RFC 5912
    { iso(1) identified-organization(3) dod(6) internet(1)
      security(5) mechanisms(5) pkix(7) id-mod(0)
      id-mod-pkixCommon-02(57) } ;

-- CMW Extension

ext-CMW EXTENSION ::= {
  SYNTAX CMW
  IDENTIFIED BY id-pe-cmw }

-- CMW Extension OID

id-pe-cmw  OBJECT IDENTIFIER  ::=
   { iso(1) identified-organization(3) dod(6) internet(1)
     security(5) mechanisms(5) pkix(7) id-pe(1) TBD }

-- CMW Extension Syntax

CMW ::= CHOICE {
    json UTF8String,
    cbor OCTET STRING
}

END

5.2. Compatibility with DICE ConceptualMessageWrapper

Section 6.1.8 of [DICE-arch] specifies the ConceptualMessageWrapper (CMW) format and its corresponding object identifier. The CMW format outlined in [DICE-arch] permits only a subset of the CMW grammar defined in this document. In particular, the tunnel and collection formats cannot be encoded using DICE CMWs.¶

7.1. JSON Record

[
  "application/vnd.example.rats-conceptual-msg",
  "q82rzQ"
]

Note that a CoAP Content-Format number can also be used with the JSON record form. That may be the case when it is known that the receiver can handle CoAP Content-Formats and it is crucial to save bytes.¶

7.2. CBOR Record

[
  30001,
  h'2347da55'
]

with the following wire representation:¶

82             # array(2)
   19 7531     # unsigned(30001)
   44          # bytes(4)
      2347da55 # "#G\xDAU"

Note that a Media-Type-Name can also be used with the CBOR record form, for example if it is known that the receiver cannot handle CoAP Content-Formats, or (unlike the case in point) if a CoAP Content-Format number has not been registrered.¶

[
  "application/vnd.example.rats-conceptual-msg",
  h'2347da55'
]

7.3. CBOR Tag

1668576818(h'2347da55')

with the following wire representation:¶

da 63747632    # tag(1668576818)
   44          # bytes(4)
      2347da55 # "#G\xDAU"

7.4. CBOR Record with explicit CM indicator

[
  "application/signed-corim+cbor",
  h'd28443a10126a1',
  3
]

with the following wire representation:¶

83                                    # array(3)
   78 1d                              # text(29)
      6170706c69636174696f6e2f7369676e65642d636f72696d2b63626f72
                                      # "application/signed-corim+cbor"
   47                                 # bytes(7)
      d28443a10126a1                  # "҄C\xA1\u0001&\xA1"
   03                                 # unsigned(3)

7.5. CBOR Collection

The following example is a CBOR collection that assembles conceptual messages from three attesters: Evidence for attesters A and B and Attestation Results for attester C. It is given an explicit collection type using the URI form.¶

{
  "attester A": [
    30001,
    h'2347da55',
    4
  ],
  "attester B": 1668576818(h'2347da55'),
  "attester C": [
    "application/eat+jwt",
    h'4c693475',
    8
  ]
}

with the following wire representation:¶

a3                                      # map(3)
   6a                                   # text(10)
      61747465737465722041              # "attester A"
   83                                   # array(3)
      19 7531                           # unsigned(30001)
      44                                # bytes(4)
         2347da55                       # "#G\xDAU"
      04                                # unsigned(4)
   6a                                   # text(10)
      61747465737465722042              # "attester B"
   da 63747632                          # tag(1668576818)
      44                                # bytes(4)
         2347da55                       # "#G\xDAU"
   6a                                   # text(10)
      61747465737465722043              # "attester C"
   83                                   # array(3)
      73                                # text(19)
         6170706c69636174696f6e2f6561742b6a7774 # "application/eat+jwt"
      44                                # bytes(4)
         4c693475                       # "Li4u"
      08                                # unsigned(8)

The following example shows the use of a tunnelled type to move a JSON record to a CBOR collection:¶

{
  "__cmwc_t": "tag:example.com,2024:composite-attester",
  0: [
    30001,
    h'2347da55',
    4
  ],
  1: 1668576818(h'2347da55'),
  2: [
    "#cmw-j2c-tunnel",
    '[ "application/eat+jwt", "Li4u", 8 ]'
  ]
}

7.6. JSON Collection

The following example is a JSON collection that assembles Evidence from two attesters.¶

{
  "attester A": [
    "application/eat-ucs+json",
    "e30K",
    4
  ],
  "attester B": [
    "application/eat-ucs+cbor",
    "oA",
    4
  ]
}

The following example shows the use of a tunnelled type to move a CBOR record to a JSON collection:¶

{
  "attester A": [
    "application/eat-ucs+json",
    "e30K",
    4
  ],
  "attester B (tunnelled)": [
    "#cmw-c2j-tunnel",
    "g3gYYXBwbGljYXRpb24vZWF0LXVjcytjYm9yQaAE"
  ]
}

7.7. Use in JWT

The following example shows the use of the "cmw" JWT claim to transport a CMW collection in a JWT [RFC7519]:¶

{
  "cmw": {
    "attester A": [
      "application/eat-ucs+json",
      "e30K",
      4
    ],
    "attester B (tunnelled)": [
      "#cmw-c2j-tunnel",
      "g3gYYXBwbGljYXRpb24vZWF0LXVjcytjYm9yQaAE"
    ]
  },
  "iss": "evidence collection daemon",
  "exp": 1300819380
}

8.1. Project Veraison

The organization responsible for this implementation is Project Veraison, a Linux Foundation project hosted at the Confidential Computing Consortium.¶

The software, hosted at https://github.com/veraison/cmw, provides a Golang package that allows encoding and decoding of CMW payloads. The implementation covers all the features presented in this draft. The maturity level is alpha. The license is Apache 2.0. The developers can be contacted on the Zulip channel: https://veraison.zulipchat.com/#narrow/stream/383526-CMW/.¶

9.1. Records and CBOR Tags

RATS conceptual messages are typically secured using cryptography. If the messages are already protected, then there are no additional security requirements imposed by the introduction of this encapsulation. If an adversary tries to modify the payload encapsulation, it will result in incorrect processing of the encapsulated message and lead to an error. If the messages are not protected, additional security must be added at a different layer. As an example, a cbor-record containing an UCCS (Unprotected CWT Claims Sets) [I-D.ietf-rats-uccs] can be signed using COSE Sign1 [STD96].¶

9.2. Collections

If the collection is not protected from tampering by external security measures (such as object security primitives) or internal mechanisms (such as intra-item binding), an attacker could easily manipulate the collection's contents. It is the responsibility of the Attester who creates the CMW collection to ensure that the contents of the collection are integrity-protected. The designer of the attestation technology is typically in charge of ensuring that the security properties are met, not the user of the conceptual message wrapper. In particular, when a CMW is used to carry multiple Evidence messages for a composite device or layered attestation, there should be strong binding between the Evidence messages within the collection. This binding is needed to prevent attacks where Evidence from a subverted part of the device is replaced by Evidence from a separate non-subverted device. The binding of Evidence messages should be some form of attestation. For example, key material used to sign/bind an entire CMW collection should be an attestation key, handled as described in Section 12.1 of [RFC9334]. The binding does not necessarily have to be a signature over the CMW collection, it might also be achieved through identifiers, cross-linking, signing or hashing between the members of the collection. Client-authenticated TLS may be used to bind a CMW collection of Evidence messages. However, the client key used with TLS should not be that of the end-user or owner of the device. Instead, it should be attestation-oriented key material from the device or the attester manufacturer.¶

10.1. CWT cmw Claim Registration

IANA is requested to add a new cmw claim to the "CBOR Web Token (CWT) Claims" registry [IANA.cwt] as follows:¶

• Claim Name: cmw¶

• Claim Description: A RATS Conceptual Message Wrapper¶

• Claim Key: TBD¶

• Claim Value Type(s): CBOR Map, CBOR Array, or CBOR Tag¶

• Change Controller: IETF¶

• Specification Document(s): Section 3.1, Section 3.3 and Section 3.2 of RFCthis¶

The suggested value for the Claim Key is 299.¶

10.2. JWT cmw Claim Registration

IANA is requested to add a new cmw claim to the "JSON Web Token Claims" sub-registry of the "JSON Web Token (JWT)" registry [IANA.jwt] as follows:¶

• Claim Name: cmw¶

• Claim Description: A RATS Conceptual Message Wrapper¶

• Change Controller: IETF¶

• Specification Document(s): Section 3.1 and Section 3.3 of RFCthis¶

10.3. CBOR Tag Registration

IANA is requested to add the following tag to the "CBOR Tags" [IANA.cbor-tags] registry.¶

10.4. RATS Conceptual Message Wrapper (CMW) Indicators Registry

This specification defines a new "RATS Conceptual Message Wrapper (CMW) Indicators" registry, with the policy "Expert Review" (Section 4.5 of [BCP26]).¶

The objective is to have CMW Indicators values registered for all RATS Conceptual Messages (Section 8 of [RFC9334]).¶

10.5. Media Types

IANA is requested to add the following media types to the "Media Types" registry [IANA.media-types].¶

10.6. CoAP Content Formats

IANA is requested to register the following Content-Format numbers in the "CoAP Content-Formats" sub-registry, within the "Constrained RESTful Environments (CoRE) Parameters" Registry [IANA.core-parameters]:¶

If possible, TBD1 and TBD2 should be assigned in the 256..999 range.¶

10.7. New SMI Numbers Registrations

IANA is requested to assign an object identifier (OID) for the CMW extension defined in Section 5 in the "Certificate Extension" sub-registry of the "SMI Numbers" [IANA.smi-numbers] registry.¶

IANA is requested to assign an object identifier (OID) for the ASN.1 Module defined in Section 5.1 in the "Module Identifier" sub-registry of the "SMI Numbers" [IANA.smi-numbers] registry.¶