Concise Selector for Endorsements and Reference Values

1.1. Terminology and Requirements Language

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.¶

This document uses terms and concepts defined by the RATS architecture. For a complete glossary, see Section 4 of [RFC9334].¶

This document uses terms and concepts defined by the CoRIM specification. For a complete glossary, see Section 1.1.1 of [I-D.ietf-rats-corim].¶

This document uses the terms "actual state" and "reference state" as defined in Section 2 of [I-D.ietf-rats-endorsements].¶

The terminology from CBOR [STD94], CDDL [RFC8610] and COSE [STD96] applies; in particular, CBOR diagnostic notation is defined in Section 8 of [STD94] and Appendix G of [RFC8610]. Terms and concepts are always referenced as proper nouns, i.e., with Capital Letters.¶

3.1. Overview

CoSERV is designed to facilitate query-response transactions between a producer and a consumer. In the RATS model, the producer is either an Endorser or a Reference Value Provider, and the consumer is a Verifier. CoSERV defines a single top-level data type that can be used for both queries and result sets. Queries are authored by the consumer (Verifier), while result sets are authored by the producer (Endorser or Reference Value Provider) in response to the query. A CoSERV data object always contains a query. When CoSERV is used to express a result set, the query is retained alongside the result set that was yielded by that query. This allows consumers to verify a match between the query that was sent to the producer, and the query that was subsequently returned with the result set. Such verification is useful because it mitigates security threats arising from any untrusted infrastructure or intermediaries that might reside between the producer and the consumer. An example of this is caching in HTTP [STD98] and CoAP [RFC7252]. It might be expensive to compute the result set for a query, which would make caching desirable. However, if caching is managed by an untrusted intermediary, then there is a risk that such an untrusted intermediary might return incorrect results, either accidentally or maliciously. Pairing the original query with each result set provides an end-to-end contract between the consumer and producer, mitigating such risks. The transactional pattern between the producer and the consumer would be that the consumer begins the transaction by authoring a query and sending it to the producer as a CoSERV object. The producer receives the query, computes results, and returns a new CoSERV object formed from the results along with the original query. Notionally, the producer is "adding" the results to the query before sending it back to the consumer.¶

3.2. Artifacts

Artifacts are what the consumer (Verifier) needs in order to verify and appraise Evidence from the Attester, and therefore they form the bulk of the response payload in a CoSERV transaction. The common CoSERV query language recognises three artifact types. These correspond to the three categories of endorsement artifact that can be identified natively in the RATS architecture:¶

• Trust Anchor: A trust anchor is as defined in [RFC6024]. An example of a trust anchor would be the public part of the asymmetric signing key that is used by the Attester to sign Evidence, such that the Verifier can verify the cryptographic signature.¶

• Endorsed Value: An endorsed value is as defined in Section 1.1.1 of [I-D.ietf-rats-corim]. This represents a characteristic of the Attester that is not directly presented in the Evidence, such as certification data related to a hardware or firmware module.¶

• Reference Value: A reference value is as defined in Section 1.1.1 of [I-D.ietf-rats-corim]. A reference value specifies an individual aspect of the Attester's desired state. Reference values are sometimes informally called "golden values". An example of a reference value would be the expected hash or checksum of a binary firmware or software image running in the Attester's environment. Evidence from the Attester would then include claims about the Attester's actual state, which the Verifier can then compare with the reference values at Evidence appraisal time.¶

When artifacts are produced by an aggregator (see Section 2), the following additional classifications apply:¶

• Collected Artifacts: these refer to artifacts that were derived by the aggregator by collecting and presenting data from original supply chain sources, or from other aggregators. Collected artifacts form a single holistic package, and provide the most ergonomic consumption experience for the Verifier.¶

• Source Arfifacts: these refer to artifacts that were obtained directly from the original supply chain sources, and used as inputs into the aggregation process, allowing the aggregator to derive the collected artifacts.¶

In the shallow trust model of aggregation, only the collected artifacts are used by the consumer. In the deep trust model, both the collected artifacts and the source artifacts are used. The source artifacts allow the consumer to audit the collected artifacts and operate the trust-but-verify principle.¶

3.3. Environments

The environment defines the scope (or scopes) in which the endorsement artifacts are applicable. Given that the consumer of these artifacts is likely to be a Verifier in the RATS model, the typical interpretation of the environment would be that of an Attester that either has produced evidence, or is expected to produce evidence, that the Verifier needs to appraise. The Verifier consequently needs to query the Endorser or Reference Value Provider for artifacts that are applicable in that environment. There are three mutually-exclusive methods for defining the environment within a CoSERV query. Exactly one of these three methods MUST be used for the query to be valid. All three methods correspond to environments that are also defined within CoRIM [I-D.ietf-rats-corim].¶

• Class: A class is an environment that is expected to be common to a group of similarly-constructed Attesters, who might therefore share the same set of endorsed characteristics. An example of this might be a fleet of computing devices of the same model and manufacturer.¶

• Instance: An instance is an environment that is unique to an individual and identifiable Attester, such as a single computing device or component.¶

• Group: A group is a collection of common Attester instances that are collected together based on some defined semantics. For example, Attesters may be put into groups for the purpose of anonymity.¶

3.4. Queries

The purpose of a query is to allow the consumer (Verifier) to specify the artifacts that it needs. The information that is conveyed in a CoSERV query includes the following:¶

• A specification of the required artifact type: Reference Value, Endorsed Value or Trust Anchor. See Section 3.2 for definitions of artifact types. A single CoSERV query can only specify a single artifact type.¶

• A specification of the Attester's environment. Environments can be selected according to Attester instance, group or class. See Section 3.3 for full definitions. To facilitate efficient transactions, a single query can specify either multiple instances, multiple groups or multiple classes. However, it is not possible to mix instance-based selectors, group-based selectors and class-based selectors in a single query.¶

• A timestamp, denoting the time at which the CoSERV query was sent.¶

• A switch to select the desired supply chain depth. A CoSERV query can request collected artifacts, source artifacts, or both. This switch is especially relevant when the CoSERV query is fulfilled by an aggregator. The collected artifacts are intended for convenient consumption (according to the shallow trust model), while the source artifacts are principally useful for auditing (according to the deep trust model). It is possible for a query to select for source artifacts only, without the collected artifacts. This might happen when the consumer needs to inspect or audit artifacts from across the deep supply chain, while not requiring the convenience of the aggregated view. It could also happen when the consumer is acting as an intermediate broker, gathering artifacts for delivery to another aggregator. See Section 2 for details on aggregation, auditing and trust models.¶

3.5. Result Sets

The result set contains the artifacts that the producer collected in response to the query. The top-level structure of the result set consists of the following three items:¶

• A collection of one or more result entries. This will be a collection of either reference values, endorsed values or trust anchors. See Section 3.2 for definitions of artifact types. In the future, it may be possible to support additional artifact types via an extension mechanism. Artifact types are never mixed in any single CoSERV result set. The artifacts in the result collection therefore MUST match the single artifact type specified in the original CoSERV query.¶

• A timestamp indicating the expiry time of the entire result set. Consumers MUST NOT consider any part of the result set to be valid after this expiry time.¶

• A collection of the original source materials from which the producer derived the correct artifacts to include in the result set. These source materials are optional, and their intended purpose is auditing. They are included only when requested by the original CoSERV query. Source materials would typically be requested in cases where the consumer is not willing to place sole trust in the producer, and therefore needs an audit trail to enable additional verifications.¶

Each individual result entry combines a CoMID triple with an authority delegation chain. CoMID triples are exactly as defined in Section 5.1.4 of [I-D.ietf-rats-corim]. Each CoMID triple will demonstrate the association between an environment matching that of the CoSERV query, and a single artifact such as a reference value, trust anchor or endorsed value. The authority delegation chain is composed of one or more authority delegates. Each authority delegate is represented by a public key or key identifier, which the consumer can check against its own set of trusted authorities. The authority delegation chain serves to establish the provenance of the result entry, and enables the Verifier to evaluate the trustworthiness of the associated artifact. The purpose of the authority delegation chain is to allow CoSERV responses to support decentralized trust models, where Verifiers may apply their own policy to determine which authorities are acceptable for different classes of artifact.¶

Because each result entry combines a CoMID triple with an authority delegation chain, the entries are consequently known as quadruples (or "quads" for short).¶

4.1. Common Data Types

CoSERV inherits the following types from the CoRIM data model class-map, $class-id-type-choice, $instance-id-type-choice and $group-id-type-choice.¶

The collated CDDL is in Appendix A.¶

4.2. Profile

In common with EAT and CoRIM, CoSERV supports the notion of profiles. As with EAT and CoRIM, profiles are a way to extend or specialize the structure of a generic CoSERV query in order to cater for a specific use case or environment.¶

In a CoSERV query, the profile can be identified by either a Uniform Resource Identifier (URI) or an Object Identifier (OID). This convention is identical to how EAT profiles are identified using the eat_profile claim as described in Section 4.3.2 of [I-D.ietf-rats-eat].¶

4.3. Query Structure

The CoSERV query language enables Verifiers to specify the desired characteristics of Endorsements and Reference Values based on the environment in which they are applicable.¶

The top-level structure of a CoSERV query is given by the following CDDL:¶

query = {
  &(artifact-type: 0) => artifact-type
  &(environment-selector: 1) => environment-selector-map
  &(timestamp: 2) => tdate ; RFC3339 date
  &(result-type: 3) => result-type
}

artifact-type = &(endorsed-values: 0)
                / &(trust-anchors: 1)
                / &(reference-values: 2)

result-type = &(collected-artifacts: 0)
              / &(source-artifacts: 1)
              / &(both: 2)

The meanings of these fields are detailed in the following subsections.¶

environment-selector-map = { selector }

selector //= ( &(class: 0) => [ + class-map ] )
selector //= ( &(instance: 1) => [ + $instance-id-type-choice ] )
selector //= ( &(group: 2) => [ + $group-id-type-choice ] )

SELECT *
  FROM endorsed_values
 WHERE ( instance-id = "At6tvu/erQ==" ) OR
       ( instance-id = "iZl4ZVY=" )`

SELECT *
  FROM reference_values
 WHERE ( class-id = "iZl4ZVY=" AND class-vendor = "ACME Inc." ) OR
       ( class-id = "31fb5abf-023e-4992-aa4e-95f9c1503bfa" )

4.4. Result Set Structure

The result set structure is given by the following CDDL:¶

results = {
  result-set
  &(expiry: 10) => tdate ; RFC3339 date
  ? &(source-artifacts: 11) => [ + cmw-record ]
}

result-set //= reference-values
result-set //= endorsed-values
result-set //= trust-anchors
result-set //= $$result-set-extensions

refval-quad = {
  &(authorities: 1) => [ + $crypto-key-type-choice ]
  &(rv-triple: 2) => reference-triple-record
}

reference-values = (
  &(rvq: 0) => [ * refval-quad ]
)

endval-quad = {
  &(authorities: 1) => [ + $crypto-key-type-choice ]
  &(ev-triple: 2) => endorsed-triple-record
}

cond-endval-quad = {
  &(authorities: 1) => [ + $crypto-key-type-choice ]
  &(ce-triple: 2) => conditional-endorsement-triple-record
}

endorsed-values = (
  &(evq: 1) => [ * endval-quad ]
  &(ceq: 2) => [ * cond-endval-quad ]
)

ak-quad = {
  &(authorities: 1) => [ + $crypto-key-type-choice ]
  &(ak-triple: 2) => attest-key-triple-record
}

cots-stmt = {
  &(authorities: 1) => [ + $crypto-key-type-choice ]
  &(cots: 2) => cots
}

trust-anchors = (
  &(akq: 3) => [ * ak-quad ]
  &(tas: 4) => [ * cots-stmt ]
)

;
; import CoTS
;
cots = "TODO COTS"
;
; import CMW
;
cmw-record = "TODO CMW"

4.5. Encoding Requirements

Implementations may wish to use serialized CoSERV queries as canonical identifiers for artifact collections. For example, a Reference Value Provider service may wish the cache the results of a CoSERV query to gain efficiency when responding to a future identical query. For these use cases to be effective, it is essential that any given CoSERV query is always serialized to the same fixed sequence of CBOR bytes. Therefore, CoSERV queries MUST always use CBOR deterministic encoding as specified in Section 4.2 of [STD94]. Further, CoSERV queries MUST use CBOR definite-length encoding.¶

4.6. Cryptographic Binding Between Query and Result Set

CoSERV is designed to ensure that any result set passed from a producer to a consumer is precisely the result set that corresponds to the consumer's original query. This is the reason why the original query is always included along with the result set in the data model. However, this measure is only sufficient in cases where the conveyance protocol guarantees that CoSERV result sets are always transacted over an end-to-end secure channel without any intermediaries. Wherever this is not the case, producers MUST create an additional cryptographic binding between the query and the result. This is achieved by transacting the result set within a cryptographic envelope, with a signature added by the producer, which is verified by the consumer. A CoSERV data object can be signed using COSE [STD96]. A signed-coserv is a COSE_Sign1 with the following layout:¶

signed-coserv = [
  protected: bytes .cbor signed-coserv-protected-hdr
  unprotected: signed-coserv-unprotected-hdr
  payload: bytes .cbor coserv
  signature: bytes
]

The payload MUST be the CBOR-encoded CoSERV.¶

signed-coserv-protected-hdr = {
  1 => int                            ; alg
  2 => "application/coserv+cbor" / 10000 ; cty
  * cose.label => cose.values
}

signed-coserv-unprotected-hdr = {
  * cose.label => cose.values
}

cose.label = int / text
cose.values = any

The protected header MUST include the signature algorithm identifier. The protected header MUST include either the content type application/coserv+cbor or the CoAP Content-Format TBD1. Other header parameters MAY be added to the header buckets, for example a kid that identifies the signing key.¶

5.1. Query Data Examples

This section provides some illustrative examples of valid CoSERV query objects.¶

The following example shows a query for Reference Values scoped by a single class. The artifact-type is set to 2 (reference-values), indicating a query for Reference Values. The profile is given the example value of tag:example.com,2025:cc-platform#1.0.0. Finally, the environment-selector uses the key 0 to select for class, and the value contains a single entry with illustrative settings for the identifier, vendor and model.¶

{
  / profile / 0: "tag:example.com,2025:cc-platform#1.0.0",
  / query /   1: {
    / artifact-type /         0: 2, / reference-values /
    / environment-selector /  1: {
      / class / 0: [
        {
          / class-id /  0: 560(h'00112233'),  / tagged-bytes /
          / vendor /    1: "Example Vendor",
          / model /     2: "Example Model"
        }
      ]
    },
    / timestamp /   2: 0("2030-12-01T18:30:01Z"),
    / result-type / 3: 1 / source-material /
  }
}

The next example is similar, but adds a second entry to the set of classes in the environment-map, showing how multiple classes can be queried at the same time.¶

{
  / profile / 0: "tag:example.com,2025:cc-platform#1.0.0",
  / query /   1: {
    / artifact-type /         0: 2, / reference-values /
    / environment-selector /  1: {
      / class / 0: [
        {
          / class-id /  0: 560(h'8999786556'),  / tagged-bytes /
          / vendor /    1: "Example Vendor",
          / model /     2: "Example Model"
        },
        {
          / class-id /  0:
            37(h'31FB5ABF023E4992AA4E95F9C1503BFA')  / UUID /
        }
      ]
    },
    / timestamp /   2: 0("2030-12-01T18:30:01Z"),
    / result-type / 3: 2 / both collected and source material /
  }
}

The following example shows a query for Reference Values scoped by instance. Again, the artifact-type is set to 2, and profile is given a demonstration value. The environment-selector now uses the key 1 to select for instances, and the value contains two entries with example instance identifiers.¶

{
  / profile / 0: "tag:example.com,2025:cc-platform#1.0.0",
  / query /   1: {
    / artifact-type / 0: 2, / reference-values /
    / environment-selector /  1: {
      / instance / 1: [
        550(h'02DEADBEEFDEAD'), / UEID /
        560(h'8999786556')      / tagged-bytes /
      ]
    },
    / timestamp /   2: 0("2030-12-01T18:30:01Z"),
    / result-type / 3: 0 / collected material /
  }
}

5.2. Result Data Examples

This section provides some illustrative examples of valid CoSERV queries with their corresponding result sets.¶

In this next example, the query is a reference value query based on class.¶

The top-level structure is a map with three entries: profile (codepoint 0), query (codepoint 1) and results (codepoint 2).¶

The profile and query structures are the same as in the previous examples. The result structure is a map with two entries: expiry (codepoint 10) and reference-value triples (codepoint 0). A single reference-value triple is shown in this example. Its environment-map, as expected, is the same as the environment-map that was supplied in the query. The rest of the structure is the measurement-map as defined in CoRIM [I-D.ietf-rats-corim].¶

{
  / profile / 0: "tag:example.com,2025:cc-platform#1.0.0",
  / query / 1: {
    0: 2,
    1: {
      0: [
        {
          0: 560(h'8999786556')
        }
      ]
    },
    2: 0("2030-12-01T18:30:01Z"),
    3: 0
  },
  / results / 2: {
    10: 0("2030-12-13T18:30:02Z"),
    0: [
      {
        1: [ 560(h'abcdef') ],
        2: [
          {
            0: {
              0: 560(h'8999786556')
            }
          },
          [
            {
              0: 37(h'31FB5ABF023E4992AA4E95F9C1503BFA'),
              1: {
                / version / 0: {
                  0: "1.2.3",
                  1: 16384
                },
                / svn / 1: 553(2)
              }
            }
          ]
        ]
      }
    ]
  }
}

6.1. Veraison

Responsible Organisation: Veraison (open source project within the Confidential Computing Consortium).¶

Location: https://github.com/veraison¶

Description: Veraison provides components that can be used to build a Verifier, and also exemplifies adjacent RATS roles such as the Relying Party. There is an active effort to extend Veraison so that it can act in the capacity of an Endorser or Reference Value Provider, showing how CoSERV can be used as a query language for such services. This includes library code to assist with the creation, parsing and manipulation of CoSERV queries.¶

Level of Maturity: This is a proof-of-concept prototype implementation.¶

License: Apache-2.0.¶

Coverage: This implementation covers all aspects of the CoSERV query language.¶

Contact: Thomas Fossati, Thomas.Fossati@linaro.org¶

7.1. Forming Native Database Queries from CoSERV

Implementations should take care when transforming CoSERV queries into native query types that are compatible with their underlying storage technology (such as SQL queries). There is a risk of injection attacks arising from poorly-formed or maliciously-formed CoSERV queries. Implementations must ensure that suitable sanitization procedures are in place when performing such translations.¶

9.1. Media Types Registrations

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

9.2. CoAP Content-Formats

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

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

10.1. Normative References

[I-D.ietf-rats-corim]

Birkholz, H., Fossati, T., Deshpande, Y., Smith, N., and W. Pan, "Concise Reference Integrity Manifest", Work in Progress, Internet-Draft, draft-ietf-rats-corim-07, 3 March 2025, <https://datatracker.ietf.org/doc/html/draft-ietf-rats-corim-07>.

[IANA.core-parameters]

IANA, "Constrained RESTful Environments (CoRE) Parameters", <https://www.iana.org/assignments/core-parameters>.

[IANA.media-types]

IANA, "Media Types", <https://www.iana.org/assignments/media-types>.

[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/rfc/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/rfc/rfc8174>.

[RFC8259]

Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017, <https://www.rfc-editor.org/rfc/rfc8259>.

[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/rfc/rfc8610>.

[RFC9334]

Birkholz, H., Thaler, D., Richardson, M., Smith, N., and W. Pan, "Remote ATtestation procedureS (RATS) Architecture", RFC 9334, DOI 10.17487/RFC9334, January 2023, <https://www.rfc-editor.org/rfc/rfc9334>.

[STD94]

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/rfc/rfc8949>.

[STD96]

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/rfc/rfc9052>.

10.2. Informative References

[I-D.ietf-rats-eat]

Lundblade, L., Mandyam, G., O'Donoghue, J., and C. Wallace, "The Entity Attestation Token (EAT)", Work in Progress, Internet-Draft, draft-ietf-rats-eat-31, 6 September 2024, <https://datatracker.ietf.org/doc/html/draft-ietf-rats-eat-31>.

[I-D.ietf-rats-endorsements]

Thaler, D., Birkholz, H., and T. Fossati, "RATS Endorsements", Work in Progress, Internet-Draft, draft-ietf-rats-endorsements-06, 3 March 2025, <https://datatracker.ietf.org/doc/html/draft-ietf-rats-endorsements-06>.

[RFC6024]

Reddy, R. and C. Wallace, "Trust Anchor Management Requirements", RFC 6024, DOI 10.17487/RFC6024, October 2010, <https://www.rfc-editor.org/rfc/rfc6024>.

[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/rfc/rfc7252>.

[RFC7942]

Sheffer, Y. and A. Farrel, "Improving Awareness of Running Code: The Implementation Status Section", BCP 205, RFC 7942, DOI 10.17487/RFC7942, July 2016, <https://www.rfc-editor.org/rfc/rfc7942>.

[STD98]

Internet Standard 98, <https://www.rfc-editor.org/info/std98>.
At the time of writing, this STD comprises the following:

Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Caching", STD 98, RFC 9111, DOI 10.17487/RFC9111, June 2022, <https://www.rfc-editor.org/info/rfc9111>.