]> Entity Attestation Token (EAT) Measured Component Arm
Simon.Frost@arm.com
Linaro
Thomas.Fossati@linaro.org
University of the Bundeswehr Munich
Werner-Heisenberg-Weg 39 Institute of Distributed Intelligent Systems Neubiberg 85577 Germany Hannes.Tschofenig@gmx.net
Fraunhofer SIT
henk.birkholz@ietf.contact
SEC rats EAT measurements claim measured component The term "measured component" refers to an object within the attester's target environment whose state can be sampled and typically digested using a cryptographic hash function. Examples of measured components include firmware stored in flash memory, software loaded into memory at start time, data stored in a file system, or values in a CPU register. This document provides the information model for the measured component and two associated data models. This separation is intentional: The JSON and Concise Binary Object Representation (CBOR) serializations, coupled with the media types and associated Constrained Application Protocol (CoAP) Content-Formats, enable the immediate use of the semantics within the Entity Attestation Token (EAT) framework. Meanwhile, the information model can be reused in future specifications to provide additional serializations, for example, using ASN.1.
Introduction defines a Measurement claim that:
[c]ontains descriptions, lists, evidence, or measurements of the software that exists on the entity or on any other measurable subsystem of the entity
This claim allows for different measurement formats, each identified by a different CoAP Content-Format (). Currently, the only specified format is Concise Software Identification (CoSWID) Tags of type "evidence", as per . However, CoSWID is not suitable for measurements that cannot be anchored to a file system, such as those in early boot environments. To address this gap, this document introduces a measured component format that can be used with the EAT Measurement claim alongside or instead of CoSWID. The term "measured component" refers to an object within the attester's target environment whose state can be sampled and typically digested using a cryptographic hash function. For example, this includes the invariant part of a firmware component that is loaded in memory at startup time, a Run-Time Integrity Check (RTIC), a file system object, or a CPU register. This document provides the information model for the measured component and two associated data models . This separation is intentional: The JSON and CBOR serializations, coupled with the media types and associated CoAP Content-Formats, enable the immediate use of the semantics within the EAT framework. Meanwhile, the information model can be reused in future specifications to provide additional serializations, for example, using ASN.1. This approach is consistent with the guidance in .
Conventions and Definitions 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 when, and only when, they appear in all capitals, as shown here. In this document, Concise Data Definition Language (CDDL) is used to describe the data formats. This specification uses the following CDDL control operators: .b64u defined in , .json defined in , and .cbor defined in . Examples are folded following the conventions in .
Information Model This section presents the information model of a measured component. A measured component Information Element (IE) includes the component's sampled state (in digested or raw form) along with metadata that helps in identifying the component. Optionally, any entities responsible for signing the installed component can also be specified. The IEs that constitute a measured component are described in . Measured Component Information Elements
IE Description Requirement Level
Component Name The name given to the measured component. It is important that this name remains consistent across different releases to allow for better tracking of the same measured item across updates. When combined with a consistent versioning scheme, it enables better signaling from the appraisal procedure to the relying parties. REQUIRED
Component Version A value representing the specific release or development version of the measured component. Using Semantic Versioning is RECOMMENDED. OPTIONAL
Digested or Raw Value Either the raw value or the digested value of the measured component. REQUIRED
Digest Algorithm Hash algorithm used to compute the Digest Value. REQUIRED only if the value is in the digested form
Authorities One or more entities that can authoritatively identify the component being measured. OPTIONAL
A data model implementing this information model SHOULD allow a limited amount of extensibility to accommodate profile-specific semantics.
Data Models This section presents coordinated JSON and CBOR data models, each of which implements the information model outlined in . The data model is inspired by the "PSA software component" claim (), which has been refactored to take into account the recommendations about the design of new EAT claims described in . CDDL is used to express rules and constraints of the data model for both JSON and CBOR. These rules must be strictly followed when creating or validating measured component data items. When there is variation between CBOR and JSON, the CDDL generic JC<>, defined in , is used.
Common Types The following three basic types are used at various places within the measured component data model:
The digest Type A digest represents the result of a hashing operation together with the hash algorithm used. The type of the digest algorithm identifier can be either int or text and is interpreted according to the "Named Information Hash Algorithm Registry" IANA registry . Specifically, int values are matched against "ID" entries and text values are matched against "Hash Name String" entries. Whenever possible, using the int encoding is RECOMMENDED. ]]>
The measured-component Data Item The measured-component data item is as follows: component-id measurement ? authorities-label => [ + authority-id-type ] ? flags-label => flags-type } measurement //= ( digested-measurement-label => digest ) measurement //= ( raw-measurement-label => bytes ) authority-id-type = eat.JC flags-type = eat.JC component-id-label = eat.JC<"id", 1> digested-measurement-label = eat.JC<"digested-measurement", 2> raw-measurement-label = eat.JC<"raw-measurement", 5> authorities-label = eat.JC<"authorities", 3> flags-label = eat.JC<"flags", 4>]]> The members of the measured-component CBOR map / JSON object are:
id (index 1):
The measured component identifier encoded according to the format described in .
measurements:
Either a digest value and digest algorithm (index 2), encoded using the digest format (), or the "raw" measurement (index 5), encoded as a byte string. Note that, while the size of the digested form is constrained by the digest function, the size of the raw form can vary greatly depending on what is being measured (it could be a CPU register or an entire configuration blob, for example). Therefore, a decoder implementation may decide to limit the amount of memory it allocates to this specific field.
authorities (index 3):
One or more authorities, see .
flags (index 4):
A 64-bit field with profile-defined semantics, see .
Component Identifier The component-id data item is as follows:
name:
A string that provides a human-readable identifier for the component in question. Format and adopted conventions depend on the component type.
version:
A compound version data item that reuses the encoding and semantics of sw-version-type from , extending it to non-software components.
Authority Identifier An authority is an entity that can authoritatively identify a given component by digitally signing it. This signature is typically verified during installation () or when the measured component is executed by the boot firmware, operating system, or application launcher, as in the case of Unified Extensible Firmware Interface (UEFI) Secure Boot and Arm Trusted Board Boot . Another example may be the controlling entity in an app store. Note that this signature is in no way related to the attester's signature on the EAT-formatted evidence. By extension, an authority identifier does not, by itself, indicate the signer of the enclosing EAT-formatted evidence. An authority is identified by its signing public key. It could be an X.509 certificate, a raw public key, a public key thumbprint, or some other identifier that can be uniquely associated with the signing entity. In some cases, multiple parties may need to sign a component to indicate their endorsement or approval. This could include roles such as a firmware update system, fleet owner, or third-party auditor. The specific purpose of each signature may depend on the deployment, and the order of authorities within the array could indicate meaning. If an EAT profile () uses measured components, it MUST specify whether the authorities field is used. If it is used, the profile MUST also specify what each of the entries in the authorities array represents and how to interpret the corresponding authority-id-type. The authority-id-type is defined as follows: ]]>
Profile-Specific Flags This optional field can contain up to 64 bits of profile-defined semantics, enabling a profile of this specification to encode additional information and extend the base type. It can be used to carry information in fixed-size chunks, such as a bit mask or a single value within a predetermined set of codepoints. Regardless of its internal structure, the size of this field is exactly 8 bytes. The flags-type is defined as follows: ]]> If an EAT profile () uses measured components, it MUST specify whether the flags field is used. If it is used, the profile MUST also specify how to interpret the 64 bits.
EAT measurements-format Extensions The CDDL in extends the $measurements-body-cbor and $measurements-body-json EAT sockets to add support for measured-components to the Measurement claim.
EAT measurements-format Extensions
Each socket is extended with two new types: a "homogeneous" representation that is used when measured-component and the EAT have the same serialization (e.g., they are both CBOR) and a "tunnel" representation that is used when the serializations differ.
measurements-format for CBOR EAT The entries in are the allowed content-type/content-format pairs when the measured-component is carried in a CBOR EAT. Note the use of the "homogeneous" and "tunnel" formats from and how the associated CoAP Content-Format is used to describe the original serialization. measurements-format for EAT CBOR Web Token (CWT)
content-type (CoAP C-F equivalent) content-format
application/measured-component+cbor mc-cbor
application/measured-component+json mc-json
measurements-format for JSON EAT is the equivalent of for JSON-serialized EAT. measurements-format for EAT JSON Web Token (JWT)
content-type (CoAP C-F equivalent) content-format
application/measured-component+json mc-json
application/measured-component+cbor tstr .b64u mc-cbor
EAT Profiles and Measured Components The semantics of the authorities and profile flags fields are defined by the applicable EAT profile, i.e., the profile of the wrapping EAT. If the profile of the EAT is not known to the consumer and one or more measured components within that EAT include authorities and/or profile flags, the consumer MUST reject the EAT.
Examples The example in is a digested measured component with all the fields populated.
Complete Measured Component
The example depicted in is the same measured component as above but used as the format of a Measurement claim in an EAT claims-set. This example uses 295 as the content-type value of the measurements-format entry. Note that the array contains only one measured component, but additional entries could be added if the measured Trusted Computing Base (TCB) is made of multiple individually measured components.
EAT Measurements Claim Using a Measured Component (CBOR) > ] ] }]]>
The example in illustrates the inclusion of a JSON measured component inside a JSON EAT. This example uses 296 as the content-type value of the measurements-format entry.
EAT Measurements Claim Using a Measured Component (JSON)
The example shown in is a measured component representing a boot loader identified by its path name:
Digested Measured Component Using a File Path as an Identifier
The example in is a raw measured component.
Raw Measured Component
Security Considerations The considerations discussed in Sections Claim Trustworthiness, Multiple EAT Consumers, and Detached EAT Bundle Digest Security Considerations of apply to this document as well. Note that similar security considerations may apply when the measured component information model is serialized using different data models than the ones specified in this document. The Component Name and Component Version can give an attacker detailed information about the software running on a device and its configuration settings. This information could offer an attacker valuable insight. Any textual fields (e.g., Component Name and Component Version) that are stored in a file, inserted into a database, or displayed to humans must be properly sanitized to prevent attacks and undesirable behavior. Further discussion and references on this topic can be found in . If the component measurement is digested, the digest must be computed using a strong cryptographic hash function.
Privacy Considerations The differential encryption considerations discussed in Section Multiple EAT Consumers of also apply to this document. The Component Name and Component Version may reveal private information about a device and its owner. Additionally, the stability requirement of the Component Name may enable tracking.
IANA Considerations
Media Type Registrations IANA has added the following media types to the "Media Types" registry . Measured Component Media Types
Name Template Reference
measured-component+cbor application/measured-component+cbor RFC 10013
measured-component+json application/measured-component+json RFC 10013
application/measured-component+cbor
Type name:
application
Subtype name:
measured-component+cbor
Required parameters:
N/A
Optional parameters:
N/A
Encoding considerations:
binary (CBOR)
Security considerations:
of RFC 10013
Interoperability considerations:
N/A
Published specification:
RFC 10013
Applications that use this media type:
Attesters, Verifiers, and Relying Parties
Fragment identifier considerations:
The syntax and semantics of fragment identifiers are as specified for "application/cbor". (No fragment identification syntax is currently defined for "application/cbor".)
Person & email address to contact for further information:
RATS WG mailing list (rats@ietf.org)
Intended usage:
COMMON
Restrictions on usage:
none
Author/Change controller:
IETF
application/measured-component+json
Type name:
application
Subtype name:
measured-component+json
Required parameters:
N/A
Optional parameters:
N/A
Encoding considerations:
binary (JSON is UTF-8-encoded text)
Security considerations:
of RFC 10013
Interoperability considerations:
N/A
Published specification:
RFC 10013
Applications that use this media type:
Attesters, Verifiers, and Relying Parties
Fragment identifier considerations:
The syntax and semantics of fragment identifiers are as specified for "application/json". (No fragment identification syntax is currently defined for "application/json".)
Person & email address to contact for further information:
RATS WG mailing list (rats@ietf.org)
Intended usage:
COMMON
Restrictions on usage:
none
Author/Change controller:
IETF
Measured Component Content-Format Registrations IANA has registered these two Content-Format numbers in the "CoAP Content-Formats" registry within the "Constrained RESTful Environments (CoRE) Parameters" registry group as follows: Content-Format Number Registrations
Content Type Content Coding ID Reference
application/measured-component+cbor - 295 RFC 10013
application/measured-component+json - 296 RFC 10013
References Normative References Semantic Versioning 2.0.0 Named Information Hash Algorithm Registry IANA Informative References Unified Extensible Firmware Interface (UEFI) Specification UEFI Forum, Inc. Release 2.10 Trusted Board Boot Requirements Client (TBBR-CLIENT) Armv8-A Arm Ltd Media Types IANA Constrained RESTful Environments (CoRE) Parameters IANA
Collated CDDL This appendix contains all the CDDL definitions included in this specification. component-id, measurement, ? authorities-label => [+ authority-id-type], ? flags-label => flags-type, } measurement //= (digested-measurement-label => digest // raw-\ measurement-label => bytes) authority-id-type = eat.JC flags-type = eat.JC component-id = [ name: text, ? version: version, ] version = [ val: text, ? scheme: coswid.$version-scheme, ] digest = [ alg: int / text, val: digest-value-type, ] digest-value-type = eat.JC bytes-b64u = text .b64u bytes bytes8 = bytes .size 8 bytes8-b64u = text .b64u bytes8 component-id-label = eat.JC<"id", 1> digested-measurement-label = eat.JC<"digested-measurement", 2> raw-measurement-label = eat.JC<"raw-measurement", 5> authorities-label = eat.JC<"authorities", 3> flags-label = eat.JC<"flags", 4> mc-cbor = bytes .cbor measured-component mc-json = text .json measured-component $measurements-body-cbor /= mc-cbor / mc-json $measurements-body-json /= mc-json / text .b64u mc-cbor eat.JSON-ONLY = J .feature "json" eat.CBOR-ONLY = C .feature "cbor" eat.JC = eat.JSON-ONLY / eat.CBOR-ONLY coswid.$version-scheme /= coswid.multipartnumeric / coswid.\ multipartnumeric-suffix / coswid.alphanumeric / coswid.decimal / \ coswid.semver / int / text coswid.multipartnumeric = 1 coswid.multipartnumeric-suffix = 2 coswid.alphanumeric = 3 coswid.decimal = 4 coswid.semver = 16384]]>
Acknowledgments The authors would like to thank , , , , , , , , , , , , , , , , , , and for providing comments, reviews, and suggestions that greatly improved this document. The authors would also like to thank for providing an implementation of this specification in the veraison/eat package.