Arm's Platform Security Architecture (PSA) Attestation TokenArm LimitedHannes.Tschofenig@arm.comArm LimitedSimon.Frost@arm.comArm LimitedMathias.Brossard@arm.comArm LimitedAdrian.Shaw@arm.comArm LimitedThomas.Fossati@arm.com
Security
RATSInternet-DraftThe Platform Security Architecture (PSA) is a family of hardware and firmware
security specifications, as well as open-source reference implementations, to
help device makers and chip manufacturers build best-practice security into
products. Devices that are PSA compliant are able to produce attestation tokens
as described in this memo, which are the basis for a number of different
protocols, including secure provisioning and network access control. This
document specifies the PSA attestation token structure and semantics.At its core, the CWT (COSE Web Token) format is used and populated with a set
of claims in a way similar to EAT (Entity Attestation Token). This
specification describes what claims are used by PSA compliant systems.Note to ReadersSource for this draft and an issue tracker can be found at
https://github.com/thomas-fossati/draft-psa-token.Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Task
Force (IETF). Note that other groups may also distribute working
documents as Internet-Drafts. The list of current Internet-Drafts is
at .
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on 5 August 2021.
Copyright Notice
Copyright (c) 2021 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
() in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with
respect to this document. Code Components extracted from this
document must include Simplified BSD License text as described in
Section 4.e of the Trust Legal Provisions and are provided without
warranty as described in the Simplified BSD License.
Table of Contents
. Introduction
. Conventions and Definitions
. Glossary
. PSA Claims
. Caller Claims
. Nonce
. Client ID
. Target Identification Claims
. Instance ID
. Implementation ID
. Certification Reference
. Target State Claims
. Security Lifecycle
. Boot Seed
. Software Inventory Claims
. Software Components
. No Software Measurements
. Verification Claims
. Verification Service Indicator
. Profile Definition
. Token Encoding and Signing
. Collated CDDL
. Security and Privacy Considerations
. Verification
. IANA Considerations
. CBOR Web Token Claims Registration
. Nonce Claim
. Client ID Claim
. Instance ID Claim
. Implementation ID Claim
. Certification Reference Claim
. Security Lifecycle Claim
. Boot Seed Claim
. Software Components Claim
. No Software Measurements Claim
. Verification Service Indicator Claim
. Profile Definition Claim
. Media Type Registration
. CoAP Content-Formats Registration
. Registry Contents
. References
. Normative References
. Informative References
. Reference Implementation
. Example
Contributors
Acknowledgments
Authors' Addresses
IntroductionTrusted execution environments are now present in many devices, which provide a
safe environment to place security sensitive code such as cryptography, secure
boot, secure storage, and other essential security functions. These security
functions are typically exposed through a narrow and well-defined interface,
and can be used by operating system libraries and applications. Various APIs
have been developed by Arm as part of the Platform Security Architecture
framework. This document focuses on the output provided by PSA's
Initial Attestation API. Since the tokens are also consumed by services outside
the device, there is an actual need to ensure interoperability.
Interoperability needs are addressed here by describing the exact syntax and
semantics of the attestation claims, and defining the way these claims are
encoded and cryptographically protected.Further details on concepts expressed below can be found in the PSA Security
Model documentation .Conventions and DefinitionsThe 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.Glossary
RoT
Root of Trust, the minimal set of software, hardware and data that has to be
implicitly trusted in the platform - there is no software or hardware at a
deeper level that can verify that the Root of Trust is authentic and
unmodified. An example of RoT is an initial bootloader in ROM, which contains
cryptographic functions and credentials, running on a specific hardware
platform.
SPE
Secure Processing Environment, a platform's processing environment for
software that provides confidentiality and integrity for its runtime state,
from software and hardware, outside of the SPE. Contains trusted code and
trusted hardware. (Equivalent to Trusted Execution Environment (TEE), or
"secure world".)
NSPE
Non Secure Processing Environment, the security domain outside of the SPE,
the Application domain, typically containing the application firmware,
operating systems, and general hardware. (Equivalent to Rich Execution
Environment (REE), or "normal world".)
PSA ClaimsThis section describes the claims to be used in a PSA attestation token.CDDL along with text descriptions is used to define each claim
independent of encoding. The following CDDL type(s) are reused by different
claims:
psa-hash-type = bytes .size 32 / bytes .size 48 / bytes .size 64
Caller ClaimsNonceThe Nonce claim is a challenge from the caller. The length must
be 32, 48, or 64 bytes.This claim MUST be present in a PSA attestation token.
psa-nonce = (
psa-nonce-key => psa-hash-type
)
Client IDThe Client ID claim represents the security domain of the caller.In PSA, a security domain is represented by a signed
integer whereby negative values represent callers from the NSPE and where
positive IDs represent callers from the SPE. The value 0 is not permitted.For an example definition of client IDs, see the PSA Firmware Framework .It is essential that this claim is checked in the verification process to
ensure that a security domain, i.e., an attestation endpoint, cannot spoof a
report from another security domain.This claim MUST be present in a PSA attestation token.Note that the CDDL label used to be called arm_psa_partition_id.
psa-client-id-nspe-type = -2147483648...0
psa-client-id-spe-type = 1..2147483647
psa-client-id-type = psa-client-id-nspe-type / psa-client-id-spe-type
psa-client-id = (
psa-client-id-key => psa-client-id-type
)
Target Identification ClaimsInstance IDThe Instance ID claim represents the unique identifier of the device instance.
It is a 32 bytes hash of the public key corresponding to the Initial
Attestation Key (IAK). If the IAK is a symmetric key then the Instance ID is a
hash of the hash of the IAK itself. It is encoded as a Universal Entity ID of
type RAND , i.e., prepending a 0x01 type byte to the key
hash. The full definition is in .This claim MUST be present in a PSA attestation token.
psa-instance-id-type = bytes .size 33
psa-instance-id = (
psa-instance-id-key => psa-instance-id-type
)
Implementation IDThe Implementation ID claim uniquely identifies the underlying immutable PSA
RoT. A verification service can use this claim to locate the details of the
verification process. Such details include the implementation's origin and
associated certification state. The full definition is in .This claim MUST be present in a PSA attestation token.
psa-implementation-id-type = bytes .size 32
psa-implementation-id = (
psa-implementation-id-key => psa-implementation-id-type
)
Certification ReferenceThe Certification Reference claim is used to link the class of chip and PSA RoT
of the attesting device to an associated entry in the PSA Certification
database. It MUST be represented as a thirteen-digit .Linking to the PSA Certification entry can still be achieved if this claim is
not present in the token by making an association at a Verifier between the
reference value and other token claim values - for example, the Implementation
ID.
psa-certification-reference-type = text .regexp "[0-9]{13}"
psa-certification-reference = (
? psa-certification-reference-key =>
psa-certification-reference-type
)
Target State ClaimsSecurity LifecycleThe Security Lifecycle claim represents the current lifecycle state of the PSA
RoT. The state is represented by an integer that is divided to convey a major
state and a minor state. A major state is mandatory and defined by .
A minor state is optional and 'IMPLEMENTATION DEFINED'. The PSA security
lifecycle state and implementation state are encoded as follows:
version[15:8] - PSA security lifecycle state, and
version[7:0] - IMPLEMENTATION DEFINED state.
The PSA lifecycle states are illustrated in . For PSA,
a remote verifier can only trust reports from the PSA RoT when it is in SECURED
or NON_PSA_ROT_DEBUG major states.This claim MUST be present in a PSA attestation token.
psa-lifecycle-unknown-type = 0x0000..0x00ff
psa-lifecycle-assembly-and-test-type = 0x1000..0x10ff
psa-lifecycle-psa-rot-provisioning-type = 0x2000..0x20ff
psa-lifecycle-secured-type = 0x3000..0x30ff
psa-lifecycle-non-psa-rot-debug-type = 0x4000..0x40ff
psa-lifecycle-recoverable-psa-rot-debug-type = 0x5000..0x50ff
psa-lifecycle-decommissioned-type = 0x6000..0x60ff
psa-lifecycle-type =
psa-lifecycle-unknown-type /
psa-lifecycle-assembly-and-test-type /
psa-lifecycle-psa-rot-provisioning-type /
psa-lifecycle-secured-type /
psa-lifecycle-non-psa-rot-debug-type /
psa-lifecycle-recoverable-psa-rot-debug-type /
psa-lifecycle-decommissioned-type
psa-lifecycle = (
psa-lifecycle-key => psa-lifecycle-type
)
Boot SeedThe Boot Seed claim represents a random value created at system boot time that
will allow differentiation of reports from different boot sessions.This claim MUST be present in a PSA attestation token.
psa-boot-seed-type = bytes .size 32
psa-boot-seed = (
psa-boot-seed-key => psa-boot-seed-type
)
Software Inventory ClaimsSoftware ComponentsThe Software Components claim is a list of software components that includes
all the software loaded by the PSA RoT. This claim SHALL be included in
attestation tokens produced by an implementation conformant with .
If the Software Components claim is present, then the No Software Measurement
claim () MUST NOT be present.Each entry in the Software Components list describes one software component
using the attributes described in the following subsections. Unless explicitly
stated, the presence of an attribute is OPTIONAL.Note that, as described in , a relying party
will typically see the result of the verification process from the Verifier in
form of an attestation result, rather than the "naked" PSA token from the
attesting endpoint. Therefore, a relying party is not expected to understand
the Software Components claim. Instead, it is for the Verifier to check this
claim against the available endorsements and provide an answer in form of an
"high level" attestation result, which may or may not include the original
Software Components claim.
psa-software-component = {
? 1 => text, ; measurement type
2 => psa-hash-type, ; measurement value
? 4 => text, ; version
5 => psa-hash-type, ; signer id
? 6 => text, ; measurement description
}
psa-software-components = (
psa-software-components-key => [ + psa-software-component ]
)
Measurement TypeThe Measurement Type attribute (key=1) is short string representing the role of
this software component.The following measurement types MAY be used:
"BL": a Boot Loader
"PRoT": a component of the PSA Root of Trust
"ARoT": a component of the Application Root of Trust
"App": a component of the NSPE application
"TS": a component of a Trusted Subsystem
Measurement ValueThe Measurement Value attribute (key=2) represents a hash of the invariant
software component in memory at startup time. The value MUST be a cryptographic
hash of 256 bits or stronger.This attribute MUST be present in a PSA software component.VersionThe Version attribute (key=4) is the issued software version in the form of a
text string. The value of this attribute will correspond to the entry in the
original signed manifest of the component.Signer IDThe Signer ID attribute (key=5) is the hash of a signing authority public key
for the software component. The value of this attribute will correspond to the
entry in the original manifest for the component. This can be used by a
verifier to ensure the components were signed by an expected trusted source.This attribute MUST be present in a PSA software component to be compliant with
.Measurement DescriptionThe Measurement Description attribute (key=6) is the description of the way in
which the measurement value of the software component is computed. The value
will be a text string containing an abbreviated description (or name) of the
measurement method which can be used to lookup the details of the method in a
profile document. This attribute will normally be excluded, unless there was an
exception to the default measurement described in the profile for a specific
component.No Software MeasurementsIn the event that the implementation does not contain any software measurements
then the Software Components claim can be omitted but
instead the token MUST include this claim to indicate this is a deliberate
state. The value SHOULD be 1. This claim is intended for devices that are not
compliant with .
psa-no-sw-measurements-type = 1
psa-no-sw-measurement = (
psa-no-sw-measurement-key => psa-no-sw-measurements-type
)
Verification ClaimsVerification Service IndicatorThe Verification Service Indicator claim is a hint used by a relying party to
locate a validation service for the token. The value is a text string that can
be used to locate the service or a URL specifying the address of the service. A
verifier may choose to ignore this claim in favor of other information.
psa-verification-service-indicator-type = text
psa-verification-service-indicator = (
? psa-verification-service-indicator-key =>
psa-verification-service-indicator-type
)
Profile DefinitionThe Profile Definition claim contains the name of a document that describes the
"profile" of the report. The document name may include versioning. The value
for this specification MUST be PSA_IOT_PROFILE_1.
psa-profile-type = "PSA_IOT_PROFILE_1"
psa-profile = (
? psa-profile-key => psa-profile-type
)
Token Encoding and SigningThe report is encoded as a COSE Web Token (CWT) , similar to the
Entity Attestation Token (EAT) . The token consists of a
series of claims declaring evidence as to the nature of the instance of
hardware and software. The claims are encoded in CBOR format. For
asymmetric key algorithms, the signature structure MUST be COSE_Sign1. For
symmetric key algorithms, the structure MUST be COSE_Mac0.Collated CDDL
psa-token = {
psa-nonce,
psa-instance-id,
psa-verification-service-indicator,
psa-profile,
psa-implementation-id,
psa-client-id,
psa-lifecycle,
psa-certification-reference,
psa-boot-seed,
( psa-software-components // psa-no-sw-measurement ),
}
psa-profile-key = -75000
psa-client-id-key = -75001
psa-lifecycle-key = -75002
psa-implementation-id-key = -75003
psa-boot-seed-key = -75004
psa-certification-reference-key = -75005
psa-software-components-key = -75006
psa-no-sw-measurement-key = -75007
psa-nonce-key = -75008
psa-instance-id-key = -75009
psa-verification-service-indicator-key = -75010
psa-hash-type = bytes .size 32 / bytes .size 48 / bytes .size 64
psa-boot-seed-type = bytes .size 32
psa-boot-seed = (
psa-boot-seed-key => psa-boot-seed-type
)
psa-client-id-nspe-type = -2147483648...0
psa-client-id-spe-type = 1..2147483647
psa-client-id-type = psa-client-id-nspe-type / psa-client-id-spe-type
psa-client-id = (
psa-client-id-key => psa-client-id-type
)
psa-certification-reference-type = text .regexp "[0-9]{13}"
psa-certification-reference = (
? psa-certification-reference-key =>
psa-certification-reference-type
)
psa-implementation-id-type = bytes .size 32
psa-implementation-id = (
psa-implementation-id-key => psa-implementation-id-type
)
psa-instance-id-type = bytes .size 33
psa-instance-id = (
psa-instance-id-key => psa-instance-id-type
)
psa-no-sw-measurements-type = 1
psa-no-sw-measurement = (
psa-no-sw-measurement-key => psa-no-sw-measurements-type
)
psa-nonce = (
psa-nonce-key => psa-hash-type
)
psa-profile-type = "PSA_IOT_PROFILE_1"
psa-profile = (
? psa-profile-key => psa-profile-type
)
psa-lifecycle-unknown-type = 0x0000..0x00ff
psa-lifecycle-assembly-and-test-type = 0x1000..0x10ff
psa-lifecycle-psa-rot-provisioning-type = 0x2000..0x20ff
psa-lifecycle-secured-type = 0x3000..0x30ff
psa-lifecycle-non-psa-rot-debug-type = 0x4000..0x40ff
psa-lifecycle-recoverable-psa-rot-debug-type = 0x5000..0x50ff
psa-lifecycle-decommissioned-type = 0x6000..0x60ff
psa-lifecycle-type =
psa-lifecycle-unknown-type /
psa-lifecycle-assembly-and-test-type /
psa-lifecycle-psa-rot-provisioning-type /
psa-lifecycle-secured-type /
psa-lifecycle-non-psa-rot-debug-type /
psa-lifecycle-recoverable-psa-rot-debug-type /
psa-lifecycle-decommissioned-type
psa-lifecycle = (
psa-lifecycle-key => psa-lifecycle-type
)
psa-software-component = {
? 1 => text, ; measurement type
2 => psa-hash-type, ; measurement value
? 4 => text, ; version
5 => psa-hash-type, ; signer id
? 6 => text, ; measurement description
}
psa-software-components = (
psa-software-components-key => [ + psa-software-component ]
)
psa-verification-service-indicator-type = text
psa-verification-service-indicator = (
? psa-verification-service-indicator-key =>
psa-verification-service-indicator-type
)
Security and Privacy ConsiderationsThis specification re-uses the CWT and the EAT specification. Hence, the
security and privacy considerations of those specifications apply here as well.Since CWTs offer different ways to protect the token, this specification
profiles those options and allows signatures based on use of public key
cryptography as well as MAC authentication. The token MUST be signed following
the structure of the COSE specification . The COSE type MUST be
COSE_Sign1 for public key signatures or COSE_Mac0 for MAC authentication. Note
however that use of MAC authentication is NOT RECOMMENDED due to the associated
infrastructure costs for key management and protocol complexities. It may also
restrict the ability to interoperate with third parties.Attestation tokens contain information that may be unique to a device and
therefore they may allow to single out an individual device for tracking
purposes. Implementations that have privacy requirements must take appropriate
measures to ensure that the token is only used to provision anonymous/pseudonym
keys.VerificationTo verify the token, the primary need is to check correct formation and signing
as for any CWT token. In addition though, the verifier can operate a policy
where values of some of the claims in this profile can be compared to reference
values, registered with the verifier for a given deployment, in order to
confirm that the device is endorsed by the manufacturer supply chain. The
policy may require that the relevant claims must have a match to a registered
reference value. All claims may be worthy of additional appraisal. It is
likely that most deployments would include a policy with appraisal for the
following claims:
Instance ID - the value of the Instance ID can be used (together with the kid
in the token COSE header, if present) to assist in locating the public key
used to verify the token signature.
Implementation ID - the value of the Implementation ID can be used to
identify the verification requirements of the deployment.
Software Component, Measurement Value - this value can uniquely identify a
firmware release from the supply chain. In some cases, a verifier may
maintain a record for a series of firmware releases, being patches to an
original baseline release. A verification policy may then allow this value to
match any point on that release sequence or expect some minimum level of
maturity related to the sequence.
Software Component, Signer ID - where present in a deployment, this could
allow a verifier to operate a more general policy than that for Measurement
Value as above, by allowing a token to contain any firmware entries signed by
a known Signer ID, without checking for a uniquely registered version.
IANA ConsiderationsCBOR Web Token Claims RegistrationThis specification registers the following claims in the IANA "CBOR Web Token (CWT)
Claims" registry , established by .Nonce Claim
Claim Name: "psa-nonce"
Claim Description: Nonce
JWT Claim Name: "psa-nonce"
Claim Key: [[Proposed: -75008]]
Claim Value Type(s): bytes (32, 48, or 64 bytes in length)
Change Controller: [[Authors of this RFC]]
Specification Document(s): Section 3.1.1 of [[this RFC]]
Client ID Claim
Claim Name: "psa-client-id"
Claim Description: Client ID
JWT Claim Name: "psa-client-id"
Claim Key: [[Proposed: -75001]]
Claim Value Type(s): signed integer
Change Controller: [[Authors of this RFC]]
Specification Document(s): Section 3.1.2 of [[this RFC]]
Instance ID Claim
Claim Name: "psa-instance-id"
Claim Description: Instance ID
JWT Claim Name: "psa-instance-id"
Claim Key: [[Proposed: -75009]]
Claim Value Type(s): bytes (33 bytes in length)
Change Controller: [[Authors of this RFC]]
Specification Document(s): Section 3.2.1 of [[this RFC]]
Implementation ID Claim
Claim Name: "psa-implementation-id"
Claim Description: Implementation ID
JWT Claim Name: "psa-implementation-id"
Claim Key: [[Proposed: -75003]]
Claim Value Type(s): bytes (32 bytes in length)
Change Controller: [[Authors of this RFC]]
Specification Document(s): Section 3.2.2 of [[this RFC]]
Certification Reference Claim
Claim Name: "psa-certification-reference"
Claim Description: Certification Reference
JWT Claim Name: "psa-certification-reference"
Claim Key: [[Proposed: -75005]]
Claim Value Type(s): text
Change Controller: [[Authors of this RFC]]
Specification Document(s): Section 3.2.3 of [[this RFC]]
Security Lifecycle Claim
Claim Name: "psa-lifecycle"
Claim Description: Security Lifecycle
JWT Claim Name: "psa-lifecycle"
Claim Key: [[Proposed: -75002]]
Claim Value Type(s): unsigned integer
Change Controller: [[Authors of this RFC]]
Specification Document(s): Section 3.3.1 of [[this RFC]]
Boot Seed Claim
Claim Name: "psa-boot-seed"
Claim Description: Boot Seed
JWT Claim Name: "psa-boot-seed"
Claim Key: [[Proposed: -75004]]
Claim Value Type(s): bytes (32 bytes in length)
Change Controller: [[Authors of this RFC]]
Specification Document(s): Section 3.3.2 of [[this RFC]]
Software Components Claim
Claim Name: "psa-software-components"
Claim Description: Software Components
JWT Claim Name: "psa-software-components"
Claim Key: [[Proposed: -75006]]
Claim Value Type(s): array
Change Controller: [[Authors of this RFC]]
Specification Document(s): Section 3.4.1 of [[this RFC]]
No Software Measurements Claim
Claim Name: "psa-no-sw-measurement"
Claim Description: No Software Measurements
JWT Claim Name: "psa-no-sw-measurement"
Claim Key: [[Proposed: -75007]]
Claim Value Type(s): unsigned integer
Change Controller: [[Authors of this RFC]]
Specification Document(s): Section 3.4.2 of [[this RFC]]
Specification Document(s): Section 3.5.1 of [[this RFC]]
Profile Definition Claim
Claim Name: "psa-profile"
Claim Description: Profile Definition
JWT Claim Name: "psa-profile"
Claim Key: [[Proposed: -75000]]
Claim Value Type(s): text
Change Controller: [[Authors of this RFC]]
Specification Document(s): Section 3.5.2 of [[this RFC]]
Media Type RegistrationIANA is requested to register the "application/psa-attestation-token" media
type in the "Media Types" registry in the
manner described in RFC 6838 , which can be used to indicate that
the content is a PSA Attestation Token.
Type name: application
Subtype name: psa-attestation-token
Required parameters: n/a
Optional parameters: n/a
Encoding considerations: binary
Security considerations: See the Security Considerations section
of [[this RFC]]
Interoperability considerations: n/a
Published specification: [[this RFC]]
Applications that use this media type: Attesters and Relying Parties sending
PSA attestation tokens over HTTP(S), CoAP(S), and other transports.
Fragment identifier considerations: n/a
Additional information:
Magic number(s): n/a
File extension(s): n/a
Macintosh file type code(s): n/a
Person & email address to contact for further information:
Hannes Tschofenig, Hannes.Tschofenig@arm.com
Intended usage: COMMON
Restrictions on usage: none
Author: Hannes Tschofenig, Hannes.Tschofenig@arm.com
Change controller: IESG
Provisional registration? No
CoAP Content-Formats RegistrationIANA is requested to register the CoAP Content-Format ID for the
"application/psa-attestation-token" media type in the "CoAP Content-Formats"
registry .Registry Contents
Media Type: application/psa-attestation-token
Encoding: -
Id: [[To-be-assigned by IANA]]
Reference: [[this RFC]]
ReferencesNormative ReferencesInternational Article Number - EAN/UPC barcodesGS1Platform Security Architecture Firmware Framework 1.0 (PSA-FF)ArmPlatform Security Architecture Security Model 1.0 (PSA-SM)ArmMultipurpose Internet Mail Extensions (MIME) Part Two: Media TypesThis second document defines the general structure of the MIME media typing system and defines an initial set of media types. [STANDARDS-TRACK]Key words for use in RFCs to Indicate Requirement LevelsIn many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.Media Type Specifications and Registration ProceduresThis document defines procedures for the specification and registration of media types for use in HTTP, MIME, and other Internet protocols. This memo documents an Internet Best Current Practice.Concise Binary Object Representation (CBOR)The Concise Binary Object Representation (CBOR) is a data format whose design goals include the possibility of extremely small code size, fairly small message size, and extensibility without the need for version negotiation. These design goals make it different from earlier binary serializations such as ASN.1 and MessagePack.CBOR Object Signing and Encryption (COSE)Concise Binary Object Representation (CBOR) is a data format designed for small code size and small message size. There is a need for the ability to have basic security services defined for this data format. This document defines the CBOR Object Signing and Encryption (COSE) protocol. This specification describes how to create and process signatures, message authentication codes, and encryption using CBOR for serialization. This specification additionally describes how to represent cryptographic keys using CBOR.Ambiguity of Uppercase vs Lowercase in RFC 2119 Key WordsRFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings.CBOR Web Token (CWT)CBOR Web Token (CWT) is a compact means of representing claims to be transferred between two parties. The claims in a CWT are encoded in the Concise Binary Object Representation (CBOR), and CBOR Object Signing and Encryption (COSE) is used for added application-layer security protection. A claim is a piece of information asserted about a subject and is represented as a name/value pair consisting of a claim name and a claim value. CWT is derived from JSON Web Token (JWT) but uses CBOR rather than JSON.Concise Data Definition Language (CDDL): A Notational Convention to Express Concise Binary Object Representation (CBOR) and JSON Data StructuresThis document proposes a notational convention to express Concise Binary Object Representation (CBOR) data structures (RFC 7049). Its main goal is to provide an easy and unambiguous way to express structures for protocol messages and data formats that use CBOR or JSON.Informative ReferencesRemote Attestation Procedures ArchitectureIn network protocol exchanges it is often the case that one entity requires believable evidence about the operational state of a remote peer. Such evidence is typically conveyed as claims about the peer's software and hardware platform, and is subsequently appraised in order to assess the peer's trustworthiness. The process of generating and appraising this kind of evidence is known as remote attestation. This document describes an architecture for remote attestation procedures that generate, convey, and appraise evidence about a peer's operational state.Work in ProgressThe Entity Attestation Token (EAT)An Entity Attestation Token (EAT) provides a signed (attested) set of claims that describe state and characteristics of an entity, typically a device like a phone or an IoT device. These claims are used by a relying party to determine how much it wishes to trust the entity. An EAT is either a CWT or JWT with some attestation-oriented claims. To a large degree, all this document does is extend CWT and JWT. Contributing TBDWork in ProgressCoAP Content-FormatsIANACBOR Web Token (CWT) ClaimsIANAMedia TypesIANAPlatform Security Architecture ResourcesArmTrusted Firmware-MLinaroReference ImplementationA reference implementation is provided by the Trusted Firmware project .ExampleThe following example shows a PSA attestation token for an hypothetical system
comprising two measured software components (a boot loader and a trusted RTOS).
The attesting device is in a lifecycle state of
SECURED. The attestation has been requested from a client residing in the
SPE:
{
/ psa-profile / -75000: "PSA_IOT_PROFILE_1",
/ psa-client-id / -75001: 1,
/ psa-lifecycle / -75002: 12288,
/ psa-implementation-id / -75003: h'50515253545556575051
52535455565750515253545556575051525354555657',
/ psa-boot-seed / -75004: h'DEADBEEFDEADBEEFDEAD
BEEFDEADBEEFDEADBEEFDEADBEEFDEADBEEFDEADBEEF',
/ psa-certification-reference / -75005: "1234567890123",
/ psa-software-components / -75006: [
{
/ measurement type / 1: "BL",
/ measurement value / 2: h'0001020400010204000102040001020
400010204000102040001020400010204',
/ signer ID / 5: h'519200FF519200FF519200FF519200F
F519200FF519200FF519200FF519200FF'
},
{
/ measurement type / 1: "PRoT",
/ measurement value / 2: h'0506070805060708050607080506070
805060708050607080506070805060708',
/ signer ID / 5: h'519200FF519200FF519200FF519200F
F519200FF519200FF519200FF519200FF'
}
],
/ psa-nonce / -75008: h'00010203000102030001020300010203
00010203000102030001020300010203',
/ psa-instance-id / -75009: h'01A0A1A2A3A0A1A2A3A0A1A2A3A0A1A2
A3A0A1A2A3A0A1A2A3A0A1A2A3A0A1A2A3',
/ psa-verification-service-indicator / -75010: "https://psa-ve
rifier.org"
}
The JWK representation of the IAK used for creating the COSE Sign1 signature
over the PSA token is:
{
"kty": "EC",
"crv": "P-256",
"x": "MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4",
"y": "4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM",
"d": "870MB6gfuTJ4HtUnUvYMyJpr5eUZNP4Bk43bVdj3eAE",
"use": "enc",
"kid": "1"
}
The resulting COSE object is:
18(
[
/ protected / h'A10126',
/ unprotected / {},
/ payload / h'AA3A000124F7715053415F494F545F50524F46494C
455F313A000124F8013A000124F91930003A000124FA58205051525354555657
5051525354555657505152535455565750515253545556573A000124FB5820DE
ADBEEFDEADBEEFDEADBEEFDEADBEEFDEADBEEFDEADBEEFDEADBEEFDEADBEEF3A
000124FC6D313233343536373839303132333A000124FD82A30162424C025820
0001020400010204000102040001020400010204000102040001020400010204
055820519200FF519200FF519200FF519200FF519200FF519200FF519200FF51
9200FFA3016450526F5402582005060708050607080506070805060708050607
08050607080506070805060708055820519200FF519200FF519200FF519200FF
519200FF519200FF519200FF519200FF3A000124FF5820000102030001020300
01020300010203000102030001020300010203000102033A00012500582101A0
A1A2A3A0A1A2A3A0A1A2A3A0A1A2A3A0A1A2A3A0A1A2A3A0A1A2A3A0A1A2A33A
00012501781868747470733A2F2F7073612D76657269666965722E6F7267',
/ signature / h'7C0FA38F80E5EA2A5C710A4BB37ABE63B26B25F17D
B6BE9489587F9B3F8FEB80E0E410D8CDAAFAE5588024CB3E18D60C1F96CED9E0
6743824614019E99BF13FE'
]
)
ContributorsWe would like to thank the following colleagues for their contributions:
* Laurence Lundblade
Security Theory LLC
lgl@securitytheory.com
* Tamas Ban
Arm Limited
Tamas.Ban@arm.com
* Sergei Trofimov
Arm Limited
Sergei.Trofimov@arm.com
AcknowledgmentsThanks to Carsten Bormann for help with the CDDL and Nicholas Wood for ideas
and comments.Authors' AddressesArm LimitedHannes.Tschofenig@arm.comArm LimitedSimon.Frost@arm.comArm LimitedMathias.Brossard@arm.comArm LimitedAdrian.Shaw@arm.comArm LimitedThomas.Fossati@arm.com