idnits 2.17.1 draft-ietf-rats-eat-13.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 9 instances of too long lines in the document, the longest one being 182 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 3431 has weird spacing: '... / the name ...' == Line 3530 has weird spacing: '...he rest eithe...' == Line 3562 has weird spacing: '... / the name ...' == Line 3661 has weird spacing: '...he rest eithe...' == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: A claim named "nonce" is previously defined and registered with IANA for JWT, but MUST not be used in an EAT. It does not support multiple nonces. No previous nonce claim was defined for CWT. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: This claim must be unique so as to differentiate the models and products for the OEM ID. This claim does not have to be globally unique, but it can be. A receiver of this claim MUST not assume it is globally unique. To globally identify a particular product, the receiver should concatenate the OEM ID and this claim. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: There is no inheritance of claims from a submodule to a superior module or vice versa. There is no assumption, requirement or guarantee that the target of a superior module encompasses the targets of submodules. Thus, every submodule must explicitly describe its own debug state. The receiver of an EAT MUST not assume that debug is turned off in a submodule because there is a claim indicating it is turned off in a superior module. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'SHOULD not' in this paragraph: They may appear in Attestation Evidence or Attestation Results. When these claims appear in Attestation Evidence, they SHOULD not be passed through the Verifier into Attestation Results. -- The document date (May 20, 2022) is 704 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'FIPS-140' is defined on line 3325, but no explicit reference was found in the text == Outdated reference: A later version (-24) exists of draft-ietf-sacm-coswid-21 -- Possible downref: Non-RFC (?) normative reference: ref. 'DLOA' -- Possible downref: Non-RFC (?) normative reference: ref. 'EAN-13' -- Possible downref: Non-RFC (?) normative reference: ref. 'OpenIDConnectCore' -- Possible downref: Non-RFC (?) normative reference: ref. 'PEN' ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) ** Obsolete normative reference: RFC 8152 (Obsoleted by RFC 9052, RFC 9053) -- Possible downref: Non-RFC (?) normative reference: ref. 'WGS84' Summary: 3 errors (**), 0 flaws (~~), 11 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 RATS Working Group L. Lundblade 3 Internet-Draft Security Theory LLC 4 Intended status: Standards Track G. Mandyam 5 Expires: November 21, 2022 J. O'Donoghue 6 Qualcomm Technologies Inc. 7 May 20, 2022 9 The Entity Attestation Token (EAT) 10 draft-ietf-rats-eat-13 12 Abstract 14 An Entity Attestation Token (EAT) provides an attested claims set 15 that describes state and characteristics of an entity, a device like 16 a phone, IoT device, network equipment or such. This claims set is 17 used by a relying party, server or service to determine how much it 18 wishes to trust the entity. 20 An EAT is either a CBOR Web Token (CWT) or JSON Web Token (JWT) with 21 attestation-oriented claims. To a large degree, all this document 22 does is extend CWT and JWT. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at https://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on November 21, 2022. 41 Copyright Notice 43 Copyright (c) 2022 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (https://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5 59 1.1. Entity Overview . . . . . . . . . . . . . . . . . . . . . 6 60 1.2. CWT, JWT and DEB . . . . . . . . . . . . . . . . . . . . 7 61 1.3. CDDL, CBOR and JSON . . . . . . . . . . . . . . . . . . . 8 62 1.4. Operating Model and RATS Architecture . . . . . . . . . . 9 63 1.4.1. Relationship between Attestation Evidence and 64 Attestation Results . . . . . . . . . . . . . . . . . 9 65 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 10 66 3. Top-Level Token Definition . . . . . . . . . . . . . . . . . 11 67 4. The Claims . . . . . . . . . . . . . . . . . . . . . . . . . 12 68 4.1. Nonce Claim (nonce) . . . . . . . . . . . . . . . . . . . 12 69 4.2. Claims Describing the Entity . . . . . . . . . . . . . . 13 70 4.2.1. Universal Entity ID Claim (ueid) . . . . . . . . . . 13 71 4.2.2. Semi-permanent UEIDs (SUEIDs) . . . . . . . . . . . . 16 72 4.2.3. Hardware OEM Identification (oemid) . . . . . . . . . 17 73 4.2.3.1. Random Number Based OEMID . . . . . . . . . . . . 17 74 4.2.3.2. IEEE Based OEMID . . . . . . . . . . . . . . . . 17 75 4.2.3.3. IANA Private Enterprise Number Based OEMID . . . 18 76 4.2.4. Hardware Model Claim (hardware-model) . . . . . . . . 18 77 4.2.5. Hardware Version Claims (hardware-version-claims) . . 19 78 4.2.6. Software Name Claim . . . . . . . . . . . . . . . . . 20 79 4.2.7. Software Version Claim . . . . . . . . . . . . . . . 20 80 4.2.8. The Security Level Claim (security-level) . . . . . . 20 81 4.2.9. Secure Boot Claim (secure-boot) . . . . . . . . . . . 21 82 4.2.10. Debug Status Claim (debug-status) . . . . . . . . . . 22 83 4.2.10.1. Enabled . . . . . . . . . . . . . . . . . . . . 23 84 4.2.10.2. Disabled . . . . . . . . . . . . . . . . . . . . 23 85 4.2.10.3. Disabled Since Boot . . . . . . . . . . . . . . 23 86 4.2.10.4. Disabled Permanently . . . . . . . . . . . . . . 23 87 4.2.10.5. Disabled Fully and Permanently . . . . . . . . . 23 88 4.2.11. The Location Claim (location) . . . . . . . . . . . . 24 89 4.2.12. The Uptime Claim (uptime) . . . . . . . . . . . . . . 25 90 4.2.13. The Boot Odometer Claim (odometer) . . . . . . . . . 25 91 4.2.14. The Boot Seed Claim (boot-seed) . . . . . . . . . . . 25 92 4.2.15. The DLOA (Digital Letter of Approval) Claim (dloas) . 26 93 4.2.16. The Software Manifests Claim (manifests) . . . . . . 26 94 4.2.17. The Software Evidence Claim (swevidence) . . . . . . 28 95 4.2.18. The Measurement Results Claim (measurement-results) . 29 96 4.2.19. Submodules (submods) . . . . . . . . . . . . . . . . 31 97 4.2.19.1. Submodule Types . . . . . . . . . . . . . . . . 32 98 4.2.19.2. No Inheritance . . . . . . . . . . . . . . . . . 36 99 4.2.19.3. Security Levels . . . . . . . . . . . . . . . . 36 100 4.2.19.4. Submodule Names . . . . . . . . . . . . . . . . 36 101 4.3. Claims Describing the Token . . . . . . . . . . . . . . . 36 102 4.3.1. Token ID Claim (cti and jti) . . . . . . . . . . . . 36 103 4.3.2. Timestamp claim (iat) . . . . . . . . . . . . . . . . 37 104 4.3.3. The Profile Claim (profile) . . . . . . . . . . . . . 37 105 4.3.4. The Intended Use Claim (intended-use) . . . . . . . . 37 106 4.4. Including Keys . . . . . . . . . . . . . . . . . . . . . 38 107 5. Detached EAT Bundles . . . . . . . . . . . . . . . . . . . . 39 108 6. Endorsements and Verification Keys . . . . . . . . . . . . . 40 109 6.1. Identification Methods . . . . . . . . . . . . . . . . . 41 110 6.1.1. COSE/JWS Key ID . . . . . . . . . . . . . . . . . . . 41 111 6.1.2. JWS and COSE X.509 Header Parameters . . . . . . . . 42 112 6.1.3. CBOR Certificate COSE Header Parameters . . . . . . . 42 113 6.1.4. Claim-Based Key Identification . . . . . . . . . . . 42 114 6.2. Other Considerations . . . . . . . . . . . . . . . . . . 42 115 7. Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . 43 116 7.1. Format of a Profile Document . . . . . . . . . . . . . . 43 117 7.2. List of Profile Issues . . . . . . . . . . . . . . . . . 43 118 7.2.1. Use of JSON, CBOR or both . . . . . . . . . . . . . . 43 119 7.2.2. CBOR Map and Array Encoding . . . . . . . . . . . . . 44 120 7.2.3. CBOR String Encoding . . . . . . . . . . . . . . . . 44 121 7.2.4. CBOR Preferred Serialization . . . . . . . . . . . . 44 122 7.2.5. COSE/JOSE Protection . . . . . . . . . . . . . . . . 44 123 7.2.6. COSE/JOSE Algorithms . . . . . . . . . . . . . . . . 45 124 7.2.7. DEB Support . . . . . . . . . . . . . . . . . . . . . 45 125 7.2.8. Verification Key Identification . . . . . . . . . . . 45 126 7.2.9. Endorsement Identification . . . . . . . . . . . . . 45 127 7.2.10. Freshness . . . . . . . . . . . . . . . . . . . . . . 45 128 7.2.11. Required Claims . . . . . . . . . . . . . . . . . . . 45 129 7.2.12. Prohibited Claims . . . . . . . . . . . . . . . . . . 45 130 7.2.13. Additional Claims . . . . . . . . . . . . . . . . . . 46 131 7.2.14. Refined Claim Definition . . . . . . . . . . . . . . 46 132 7.2.15. CBOR Tags . . . . . . . . . . . . . . . . . . . . . . 46 133 7.2.16. Manifests and Software Evidence Claims . . . . . . . 46 134 8. Encoding and Collected CDDL . . . . . . . . . . . . . . . . . 46 135 8.1. Claims-Set and CDDL for CWT and JWT . . . . . . . . . . . 46 136 8.2. Encoding Data Types . . . . . . . . . . . . . . . . . . . 47 137 8.2.1. Common Data Types . . . . . . . . . . . . . . . . . . 47 138 8.2.2. JSON Interoperability . . . . . . . . . . . . . . . . 47 139 8.2.3. Labels . . . . . . . . . . . . . . . . . . . . . . . 48 140 8.3. CBOR Interoperability . . . . . . . . . . . . . . . . . . 48 141 8.3.1. EAT Constrained Device Serialization . . . . . . . . 49 142 8.4. Collected CDDL . . . . . . . . . . . . . . . . . . . . . 49 143 8.4.1. Payload CDDL . . . . . . . . . . . . . . . . . . . . 49 144 8.4.2. CBOR-Specific CDDL . . . . . . . . . . . . . . . . . 55 145 8.4.3. JSON-Specific CDDL . . . . . . . . . . . . . . . . . 56 146 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 56 147 9.1. Reuse of CBOR and JSON Web Token (CWT and JWT) Claims 148 Registries . . . . . . . . . . . . . . . . . . . . . . . 56 149 9.2. Claim Characteristics . . . . . . . . . . . . . . . . . . 56 150 9.2.1. Interoperability and Relying Party Orientation . . . 56 151 9.2.2. Operating System and Technology Neutral . . . . . . . 57 152 9.2.3. Security Level Neutral . . . . . . . . . . . . . . . 57 153 9.2.4. Reuse of Extant Data Formats . . . . . . . . . . . . 57 154 9.2.5. Proprietary Claims . . . . . . . . . . . . . . . . . 58 155 9.3. Claims Registered by This Document . . . . . . . . . . . 58 156 9.3.1. Claims for Early Assignment . . . . . . . . . . . . . 58 157 9.3.2. To be Assigned Claims . . . . . . . . . . . . . . . . 62 158 9.3.3. Version Schemes Registered by this Document . . . . . 65 159 9.3.4. UEID URN Registered by this Document . . . . . . . . 65 160 9.3.5. Tag for Detached EAT Bundle . . . . . . . . . . . . . 66 161 10. Privacy Considerations . . . . . . . . . . . . . . . . . . . 66 162 10.1. UEID and SUEID Privacy Considerations . . . . . . . . . 66 163 10.2. Location Privacy Considerations . . . . . . . . . . . . 67 164 10.3. Replay Protection and Privacy . . . . . . . . . . . . . 67 165 11. Security Considerations . . . . . . . . . . . . . . . . . . . 68 166 11.1. Key Provisioning . . . . . . . . . . . . . . . . . . . . 68 167 11.1.1. Transmission of Key Material . . . . . . . . . . . . 68 168 11.2. Transport Security . . . . . . . . . . . . . . . . . . . 68 169 11.3. Multiple EAT Consumers . . . . . . . . . . . . . . . . . 69 170 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 69 171 12.1. Normative References . . . . . . . . . . . . . . . . . . 69 172 12.2. Informative References . . . . . . . . . . . . . . . . . 72 173 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 75 174 A.1. Payload Examples . . . . . . . . . . . . . . . . . . . . 75 175 A.1.1. Simple TEE Attestation . . . . . . . . . . . . . . . 75 176 A.1.2. Submodules for Board and Device . . . . . . . . . . . 77 177 A.1.3. EAT Produced by Attestation Hardware Block . . . . . 79 178 A.1.4. Key / Key Store Attestation . . . . . . . . . . . . . 79 179 A.1.5. Submodules for Board and Device . . . . . . . . . . . 81 180 A.1.6. EAT Produced by Attestation Hardware Block . . . . . 83 181 A.1.7. Key / Key Store Attestation . . . . . . . . . . . . . 83 182 A.1.8. SW Measurements of an IoT Device . . . . . . . . . . 85 183 A.1.9. Attestation Results in JSON format . . . . . . . . . 87 184 A.1.10. JSON-encoded Token with Sumodules . . . . . . . . . . 88 185 A.2. Full Token Examples . . . . . . . . . . . . . . . . . . . 89 186 A.2.1. Basic CWT Example . . . . . . . . . . . . . . . . . . 89 187 A.2.2. Detached EAT Bundle . . . . . . . . . . . . . . . . . 90 188 A.2.3. JSON-encoded Detached EAT Bundle . . . . . . . . . . 92 189 Appendix B. UEID Design Rationale . . . . . . . . . . . . . . . 92 190 B.1. Collision Probability . . . . . . . . . . . . . . . . . . 93 191 B.2. No Use of UUID . . . . . . . . . . . . . . . . . . . . . 95 192 Appendix C. EAT Relation to IEEE.802.1AR Secure Device Identity 193 (DevID) . . . . . . . . . . . . . . . . . . . . . . 96 194 C.1. DevID Used With EAT . . . . . . . . . . . . . . . . . . . 96 195 C.2. How EAT Provides an Equivalent Secure Device Identity . . 97 196 C.3. An X.509 Format EAT . . . . . . . . . . . . . . . . . . . 97 197 C.4. Device Identifier Permanence . . . . . . . . . . . . . . 98 198 Appendix D. CDDL for CWT and JWT . . . . . . . . . . . . . . . . 98 199 Appendix E. Changes from Previous Drafts . . . . . . . . . . . . 100 200 E.1. From draft-rats-eat-01 . . . . . . . . . . . . . . . . . 100 201 E.2. From draft-mandyam-rats-eat-00 . . . . . . . . . . . . . 100 202 E.3. From draft-ietf-rats-eat-01 . . . . . . . . . . . . . . . 100 203 E.4. From draft-ietf-rats-eat-02 . . . . . . . . . . . . . . . 100 204 E.5. From draft-ietf-rats-eat-03 . . . . . . . . . . . . . . . 101 205 E.6. From draft-ietf-rats-eat-04 . . . . . . . . . . . . . . . 101 206 E.7. From draft-ietf-rats-eat-05 . . . . . . . . . . . . . . . 102 207 E.8. From draft-ietf-rats-eat-06 . . . . . . . . . . . . . . . 102 208 E.9. From draft-ietf-rats-eat-07 . . . . . . . . . . . . . . . 102 209 E.10. From draft-ietf-rats-eat-08 . . . . . . . . . . . . . . . 102 210 E.11. From draft-ietf-rats-eat-09 . . . . . . . . . . . . . . . 102 211 E.12. From draft-ietf-rats-eat-10 . . . . . . . . . . . . . . . 103 212 E.13. From draft-ietf-rats-eat-11 . . . . . . . . . . . . . . . 104 213 E.14. From draft-ietf-rats-eat-12 . . . . . . . . . . . . . . . 104 214 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 105 216 1. Introduction 218 EAT provides the definition of a base set of claims that can be made 219 about an entity, a device, some software and/or some hardware. This 220 claims set is received by a relying party who uses it to decide if 221 and how it will interact with the remote entity. It may choose to 222 not trust the entity and not interact with it. It may choose to 223 trust it. It may partially trust it, for example allowing monetary 224 transactions only up to a limit. 226 EAT defines the encoding of the claims set in CBOR [RFC8949] and JSON 227 [RFC7159]. EAT is an extension to CBOR Web Token (CWT) [RFC8392] and 228 JSON Web Token (JWT) [RFC7519]. 230 The claims set is secured in transit with the same mechanisms used by 231 CWT and JWT, in particular CBOR Object Signing and Encryption (COSE) 232 [RFC8152] and JSON Object Signing and Encryption (JOSE) [RFC7515] 233 [RFC7516]. Authenticity and integrity protection must always be 234 provided. Privacy (encryption) may additionally be provided. The 235 key material used to sign and encrypt is specifically created and 236 provisioned for the purpose of attestation. It is the use of this 237 key material that make the claims set "attested" rather than just 238 some parameters sent to the relying party by the device. 240 EAT is focused on authenticating, identifying and characterizing 241 implementations where implementations are devices, chips, hardware, 242 software and such. This is distinct from protocols like TLS 243 [RFC8446] that authenticate and identify servers and services. It is 244 equally distinct from protocols like SASL [RFC4422] that authenticate 245 and identify persons. 247 The notion of attestation is large, ranging over a broad variety of 248 use cases and security levels. Here are a few examples of claims: 250 o Make and model of manufactured consumer device 252 o Make and model of a chip or processor, particularly for a 253 security-oriented chip 255 o Identification and measurement of the software running on a device 257 o Configuration and state of a device 259 o Environmental characteristics of a device like its GPS location 261 o Formal certifications received 263 EAT also supports nesting of sets of claims and EAT tokens for use 264 with complex composite devices. 266 This document uses the terminology and main operational model defined 267 in [RATS.Architecture]. In particular, it can be used for RATS 268 Attestation Evidence and Attestation Results. 270 1.1. Entity Overview 272 The document uses the term "entity" to refer to the target of the 273 attestation token. The claims defined in this document are claims 274 about an entity. 276 An entity is an implementation in hardware, software or both. 278 An entity is the same as the Attester Target Environment defined in 279 RATS Architecture. 281 An entity also corresponds to a "system component" as defined in the 282 Internet Security Glossary [RFC4949]. That glossary also defines 283 "entity" and "system entity" as something that may be a person or 284 organization as well as a system component. Here "entity" never 285 refers to a person or organization. 287 An entity is never a server or a service. 289 An entity may be the whole device or it may be a subsystem, a 290 subsystem of a subsystem and so on. EAT allows claims to be 291 organized into submodules, nested EATs and so on. See 292 Section 4.2.19. The entity to which a claim applies is the submodule 293 in which it appears, or to the top-level entity if it doesn't appear 294 in a submodule. 296 Some examples of entities: 298 o A Secure Element 300 o A TEE 302 o A card in a network router 304 o A network router, perhaps with each card in the router a submodule 306 o An IoT device 308 o An individual process 310 o An app on a smartphone 312 o A smartphone with many submodules for its many subsystems 314 o A subsystem in a smartphone like the modem or the camera 316 An entity may have strong security like defenses against hardware 317 invasive attacks. It may also have low security, having no special 318 security defenses. There is no minimum security requirement to be an 319 entity. 321 1.2. CWT, JWT and DEB 323 An EAT is primarily a claims set about an entity based on one of the 324 following: 326 o CBOR Web Token (CWT) [RFC8392] 328 o JSON Web Token (JWT) [RFC7519] 330 All definitions, requirements, creation and validation procedures, 331 security considerations, IANA registrations and so on from these 332 carry over to EAT. 334 This specification extends those specifications by defining 335 additional claims for attestation. This specification also describes 336 the notion of a "profile" that can narrow the definition of an EAT, 337 ensure interoperability and fill in details for specific usage 338 scenarios. This specification also adds some considerations for 339 registration of future EAT-related claims. 341 The identification of a protocol element as an EAT, whether CBOR or 342 JSON encoded, follows the general conventions used by CWT, JWT. 343 Largely this depends on the protocol carrying the EAT. In some cases 344 it may be by content type (e.g., MIME type). In other cases it may 345 be through use of CBOR tags. There is no fixed mechanism across all 346 use cases. 348 This specification adds one more top-level token type: 350 o Detached EAT Bundle (DEB), Section 5 352 A DEB is structure to hold a collection of detached claims sets and 353 the EAT that separately provides integrity and authenticity 354 protection for them. It can be either CBOR or JSON encoded. 356 Last, the definition of other token types is allowed. Of particular 357 use may be a token type that provides no authenticity or integrity 358 protection at all for use with transports like TLS that do provide 359 that. 361 1.3. CDDL, CBOR and JSON 363 This document defines Concise Binary Object Representation (CBOR) 364 [RFC8949] and Javascript Object Notation (JSON) [RFC7159] encoding 365 for an EAT. All claims in an EAT MUST use the same encoding except 366 where explicitly allowed. It is explicitly allowed for a nested 367 token to be of a different encoding. Some claims explicitly contain 368 objects and messages that may use a different encoding than the 369 enclosing EAT. 371 This specification uses Concise Data Definition Language (CDDL) 372 [RFC8610] for all definitions. The implementor interprets the CDDL 373 to come to either the CBOR or JSON encoding. In the case of JSON, 374 Appendix E of [RFC8610] is followed. Additional rules are given in 375 Section 8.2.2 where Appendix E is insufficient. 377 In most cases where the CDDL for CBOR is different than JSON a CDDL 378 Generic named "JC<>" is used. It is described in Appendix D. 380 The CWT and JWT specifications were authored before CDDL was 381 available and did not use CDDL. This specification includes a CDDL 382 definition of most of what is defined in [RFC8392]. Similarly, this 383 specification includes CDDL for most of what is defined in [RFC7519]. 384 These definitions are in Appendix D and are not normative. 386 1.4. Operating Model and RATS Architecture 388 While it is not required that EAT be used with the RATS operational 389 model described in Figure 1 in [RATS.Architecture], or even that it 390 be used for attestation, this document is oriented around that model. 392 To summarize, an Attester generates Attestation Evidence. 393 Attestation Evidence is a claims set describing various 394 characteristics of an entity. Attestation Evidence also is usually 395 signed by a key that proves the entity and the evidence it produces 396 are authentic. The claims set includes a nonce or some other means 397 to provide freshness. EAT is designed to carry Attestation Evidence. 398 The Attestation Evidence goes to a Verifier where the signature is 399 verified. Some of the claims may also be checked against Reference 400 Values. The Verifier then produces Attestation Results which is also 401 usually a claims set. EAT is also designed to carry Attestation 402 Results. The Attestation Results go to the Relying Party which is 403 the ultimate consumer of the Remote Attestation Procedure. The 404 Relying Party uses the Attestation Results as needed for the use 405 case, perhaps allowing an entity on the network, allowing a financial 406 transaction or such. 408 Note that sometimes the Verifier and Relying Party are not separate 409 and thus there is no need for a protocol to carry Attestation 410 Results. 412 1.4.1. Relationship between Attestation Evidence and Attestation 413 Results 415 Any claim defined in this document or in the IANA CWT or JWT registry 416 may be used in Attestation Evidence or Attestation Results. 418 The relationship of claims in Attestation Results to Attestation 419 Evidence is fundamentally governed by the Verifier and the Verifier's 420 Policy. 422 A common use case is for the Verifier and its Policy to perform 423 checks, calculations and processing with Attestation Evidence as the 424 input to produce a summary result in Attestation Results that 425 indicates the overall health and status of the entity. For example, 426 measurements in Attestation Evidence may be compared to Reference 427 Values the results of which are represented as a simple pass/fail in 428 Attestation Results. 430 It is also possible that some claims in the Attestation Evidence will 431 be forwarded unmodified to the Relying Party in Attestation Results. 432 This forwarding is subject to the Verifier's implementation and 433 Policy. The Relying Party should be aware of the Verifier's Policy 434 to know what checks it has performed on claims it forwards. 436 The Verifier may also modify or transform claims it forwards. This 437 may be to implement some privacy preservation functionality. 439 It is also possible the Verifier will put claims in the Attestation 440 Results that give details about the entity that it has computed or 441 looked up in a database. For example, the Verifier may be able to 442 put a HW OEM ID Claim in the Attestation Results by performing a look 443 up based on a UEID (serial number) it received in Attestation 444 Evidence. 446 There are no fixed rules for how a Verifier processes Attestation 447 Evidence to produce Attestation Results. What is important is the 448 Relying Party understand what the Verifier does and what its policies 449 are. 451 2. Terminology 453 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 454 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 455 "OPTIONAL" in this document are to be interpreted as described in BCP 456 14 [RFC2119] [RFC8174] when, and only when, they appear in all 457 capitals, as shown here. 459 This document reuses terminology from JWT [RFC7519] and CWT 460 [RFC8392]. 462 Claim: A piece of information asserted about a subject. A claim is 463 represented as pair with a value and either a name or key to 464 identify it. 466 Claim Name: A unique text string that identifies the claim. It is 467 used as the claim name for JSON encoding. 469 Claim Key: The CBOR map key used to identify a claim. 471 Claim Value: The value portion of the claim. A claim value can be 472 any CBOR data item or JSON value. 474 CWT/JWT Claims Set: The CBOR map or JSON object that contains the 475 claims conveyed by the CWT or JWT. 477 This document reuses terminology from RATS Architecure 478 [RATS.Architecture] 479 Attester: A role performed by an entity (typically a device) whose 480 Evidence must be appraised in order to infer the extent to which 481 the Attester is considered trustworthy, such as when deciding 482 whether it is authorized to perform some operation. 484 Verifier: A role that appraises the validity of Attestation Evidence 485 about an Attester and produces Attestation Results to be used by a 486 Relying Party. 488 Relying Party: A role that depends on the validity of information 489 about an Attester, for purposes of reliably applying application 490 specific actions. Compare /relying party/ in [RFC4949]. 492 Attestation Evidence: A Claims Set generated by an Attester to be 493 appraised by a Verifier. Attestation Evidence may include 494 configuration data, measurements, telemetry, or inferences. 496 Attestation Results: The output generated by a Verifier, typically 497 including information about an Attester, where the Verifier 498 vouches for the validity of the results 500 Reference Values: A set of values against which values of Claims can 501 be compared as part of applying an Appraisal Policy for 502 Attestation Evidence. Reference Values are sometimes referred to 503 in other documents as known-good values, golden measurements, or 504 nominal values, although those terms typically assume comparison 505 for equality, whereas here Reference Values might be more general 506 and be used in any sort of comparison. 508 3. Top-Level Token Definition 510 An EAT is a "message", a "token", or such whose content is a Claims- 511 Set about an entity or some number of entities. An EAT MUST always 512 contains a Claims-Set. 514 An EAT may be encoded in CBOR or JSON as defined here. While not 515 encouraged, other documents may define EAT encoding in other formats. 517 EAT as defined here is always integrity and authenticity protected 518 through use of CWT or JWT. Other token formats using other methods 519 of protection may be defined outside this document. 521 This document also defines the Detatched EAT Bundle Section 5, a 522 bundle of some detached Claims-Sets and CWTs or JWTs that provide 523 protection for the detached Claims-Set. 525 The following CDDL defines the top-levels of an EAT token as a socket 526 indicating future token formats may be defined. See Appendix D for 527 the CDDL definitions of a CWT and JWT. 529 Nesting of EATs is allowed and defined in Section 4.2.19.1.2. This 530 nesting includes nesting of a token that is a different format than 531 the enclosing token. The definition of Nested-Token references the 532 CDDL defined in this section. When new token formats are defined, 533 the means for identification in a nested token MUST also be defined. 535 EAT-CBOR-Token = $$EAT-CBOR-Tagged-Token / $$EAT-CBOR-Untagged-Token 537 $$EAT-CBOR-Tagged-Token /= CWT-Tagged-Message 538 $$EAT-CBOR-Tagged-Token /= DEB-Tagged-Message 540 $$EAT-CBOR-Untagged-Token /= CWT-Untagged-Message 541 $$EAT-CBOR-Untagged-Token /= DEB-Untagged-Message 543 EAT-JSON-Token = $$EAT-JSON-Token-Formats 545 $$EAT-JSON-Token-Formats /= JWT-Message 546 $$EAT-JSON-Token-Formats /= DEB-Untagged-Message 548 4. The Claims 550 This section describes new claims defined for attestation that are to 551 be added to the CWT [IANA.CWT.Claims] and JWT [IANA.JWT.Claims] IANA 552 registries. 554 This section also describes how several extant CWT and JWT claims 555 apply in EAT. 557 CDDL, along with a text description, is used to define each claim 558 independent of encoding. Each claim is defined as a CDDL group. In 559 Section 8 on encoding, the CDDL groups turn into CBOR map entries and 560 JSON name/value pairs. 562 Each claim described has a unique text string and integer that 563 identifies it. CBOR encoded tokens MUST use only the integer for 564 Claim Keys. JSON encoded tokens MUST use only the text string for 565 Claim Names. 567 4.1. Nonce Claim (nonce) 569 All EATs MUST have a nonce to prevent replay attacks. 571 This claim is either a single byte or text string or an array of byte 572 or text strings. The array is to accommodate multistage EAT 573 verification and consumption. See the extensive discussion on 574 attestation freshness in Appendix A of RATS Architecture 575 [RATS.Architecture]. 577 A claim named "nonce" is previously defined and registered with IANA 578 for JWT, but MUST not be used in an EAT. It does not support 579 multiple nonces. No previous nonce claim was defined for CWT. 581 The nonce MUST have 64 bits of entropy as fewer bits are unlikely to 582 be secure. A maximum nonce size is set to limit the memory required 583 for an implementation. All receivers MUST be able to accommodate the 584 maximum size. 586 In CBOR, the nonce is a byte string and every bit in the byte string 587 contributes to entropy. The minimum size is 8 bytes. The maximum 588 size is 64 bytes. 590 In JSON the nonce is a text string. It is assumed that the only 591 characters represented by the lower 7 bits will be used so the text 592 string must be one-seventh longer. The minimum size is 10 bytes. 593 The maximum size is 74 bytes. 595 $$Claims-Set-Claims //= 596 (nonce-label => nonce-type / [ 2* nonce-type ]) 598 nonce-type = JC< tstr .size (10..74), bstr .size (8..64)> 600 4.2. Claims Describing the Entity 602 The claims in this section describe the entity itself. They describe 603 the entity whether they occur in Attestation Evidence or occur in 604 Attestation Results. See Section 1.4.1 for discussion on how 605 Attestation Results relate to Attestation Evidence. 607 4.2.1. Universal Entity ID Claim (ueid) 609 A UEID identifies an individual manufactured entity like a mobile 610 phone, a water meter, a Bluetooth speaker or a networked security 611 camera. It may identify the entire entity or a submodule. It does 612 not identify types, models or classes of entities. It is akin to a 613 serial number, though it does not have to be sequential. 615 UEIDs MUST be universally and globally unique across manufacturers 616 and countries. UEIDs MUST also be unique across protocols and 617 systems, as tokens are intended to be embedded in many different 618 protocols and systems. No two products anywhere, even in completely 619 different industries made by two different manufacturers in two 620 different countries should have the same UEID (if they are not global 621 and universal in this way, then Relying Parties receiving them will 622 have to track other characteristics of the entity to keep entities 623 distinct between manufacturers). 625 There are privacy considerations for UEIDs. See Section 10.1. 627 The UEID is permanent. It MUST never change for a given entity. 629 A UEID is constructed of a single type byte followed by the bytes 630 that are the identifier. Several types are allowed to accommodate 631 different industries, different manufacturing processes and to have 632 an alternative that doesn't require paying a registration fee. 634 Creation of new types requires a Standards Action [RFC8126]. 636 UEIDs are variable length. All implementations MUST be able to 637 receive UEIDs that are 33 bytes long (1 type byte and 256 bits). No 638 UEID longer than 33 bytes SHOULD be sent. 640 +------+------+-----------------------------------------------------+ 641 | Type | Type | Specification | 642 | Byte | Name | | 643 +------+------+-----------------------------------------------------+ 644 | 0x01 | RAND | This is a 128, 192 or 256-bit random number | 645 | | | generated once and stored in the entity. This may | 646 | | | be constructed by concatenating enough identifiers | 647 | | | to make up an equivalent number of random bits and | 648 | | | then feeding the concatenation through a | 649 | | | cryptographic hash function. It may also be a | 650 | | | cryptographic quality random number generated once | 651 | | | at the beginning of the life of the entity and | 652 | | | stored. It MUST NOT be smaller than 128 bits. See | 653 | | | the length analysis in Appendix B. | 654 | 0x02 | IEEE | This uses the IEEE company identification registry. | 655 | | EUI | An EUI is either an EUI-48, EUI-60 or EUI-64 and | 656 | | | made up of an OUI, OUI-36 or a CID, different | 657 | | | registered company identifiers, and some unique | 658 | | | per-entity identifier. EUIs are often the same as | 659 | | | or similar to MAC addresses. This type includes | 660 | | | MAC-48, an obsolete name for EUI-48. (Note that | 661 | | | while entities with multiple network interfaces may | 662 | | | have multiple MAC addresses, there is only one UEID | 663 | | | for an entity) [IEEE.802-2001], [OUI.Guide]. | 664 | 0x03 | IMEI | This is a 14-digit identifier consisting of an | 665 | | | 8-digit Type Allocation Code and a 6-digit serial | 666 | | | number allocated by the manufacturer, which SHALL | 667 | | | be encoded as byte string of length 14 with each | 668 | | | byte as the digit's value (not the ASCII encoding | 669 | | | of the digit; the digit 3 encodes as 0x03, not | 670 | | | 0x33). The IMEI value encoded SHALL NOT include | 671 | | | Luhn checksum or SVN information. See | 672 | | | [ThreeGPP.IMEI]. | 673 +------+------+-----------------------------------------------------+ 675 Table 1: UEID Composition Types 677 UEIDs are not designed for direct use by humans (e.g., printing on 678 the case of a device), so no textual representation is defined. 680 The consumer of a UEID MUST treat a UEID as a completely opaque 681 string of bytes and not make any use of its internal structure. For 682 example, they should not use the OUI part of a type 0x02 UEID to 683 identify the manufacturer of the entity. Instead, they should use 684 the OEMID claim. See Section 4.2.3. The reasons for this are: 686 o UEIDs types may vary freely from one manufacturer to the next. 688 o New types of UEIDs may be created. For example, a type 0x07 UEID 689 may be created based on some other manufacturer registration 690 scheme. 692 o The manufacturing process for an entity is allowed to change from 693 using one type of UEID to another. For example, a manufacturer 694 may find they can optimize their process by switching from type 695 0x01 to type 0x02 or vice versa. 697 A Device Identifier URN is registered for UEIDs. See Section 9.3.4. 699 $$Claims-Set-Claims //= (ueid-label => ueid-type) 701 ueid-type = JC 703 4.2.2. Semi-permanent UEIDs (SUEIDs) 705 An SEUID is of the same format as a UEID, but it MAY change to a 706 different value on device life-cycle events. Examples of these 707 events are change of ownership, factory reset and on-boarding into an 708 IoT device management system. An entity MAY have both a UEID and 709 SUEIDs, neither, one or the other. 711 There MAY be multiple SUEIDs. Each one has a text string label the 712 purpose of which is to distinguish it from others in the token. The 713 label MAY name the purpose, application or type of the SUEID. 714 Typically, there will be few SUEDs so there is no need for a formal 715 labeling mechanism like a registry. The EAT profile MAY describe how 716 SUEIDs should be labeled. If there is only one SUEID, the claim 717 remains a map and there still must be a label. For example, the 718 label for the SUEID used by FIDO Onboarding Protocol could simply be 719 "FDO". 721 There are privacy considerations for SUEIDs. See Section 10.1. 723 A Device Indentifier URN is registered for SUEIDs. See 724 Section 9.3.4. 726 $$Claims-Set-Claims //= (sueids-label => sueids-type) 728 sueids-type = { 729 + tstr => ueid-type 730 } 732 4.2.3. Hardware OEM Identification (oemid) 734 This claim identifies the Original Equipment Manufacturer (OEM) of 735 the hardware. Any of the three forms described below MAY be used at 736 the convenience of the claim sender. The receiver of this claim MUST 737 be able to handle all three forms. 739 4.2.3.1. Random Number Based OEMID 741 The random number based OEMID MUST always 16 bytes (128 bits). 743 The OEM MAY create their own ID by using a cryptographic-quality 744 random number generator. They would perform this only once in the 745 life of the company to generate the single ID for said company. They 746 would use that same ID in every entity they make. This uniquely 747 identifies the OEM on a statistical basis and is large enough should 748 there be ten billion companies. 750 The OEM MAY also use a hash function like SHA-256 and truncate the 751 output to 128 bits. The input to the hash should be somethings that 752 have at least 96 bits of entropy, but preferably 128 bits of entropy. 753 The input to the hash MAY be something whose uniqueness is managed by 754 a central registry like a domain name. 756 In JSON format tokens this MUST be base64url encoded. 758 4.2.3.2. IEEE Based OEMID 760 The IEEE operates a global registry for MAC addresses and company 761 IDs. This claim uses that database to identify OEMs. The contents 762 of the claim may be either an IEEE MA-L, MA-M, MA-S or an IEEE CID 763 [IEEE.RA]. An MA-L, formerly known as an OUI, is a 24-bit value used 764 as the first half of a MAC address. MA-M similarly is a 28-bit value 765 uses as the first part of a MAC address, and MA-S, formerly known as 766 OUI-36, a 36-bit value. Many companies already have purchased one of 767 these. A CID is also a 24-bit value from the same space as an MA-L, 768 but not for use as a MAC address. IEEE has published Guidelines for 769 Use of EUI, OUI, and CID [OUI.Guide] and provides a lookup service 770 [OUI.Lookup]. 772 Companies that have more than one of these IDs or MAC address blocks 773 SHOULD select one and prefer that for all their entities. 775 Commonly, these are expressed in Hexadecimal Representation as 776 described in [IEEE.802-2001]. It is also called the Canonical 777 format. When this claim is encoded the order of bytes in the bstr 778 are the same as the order in the Hexadecimal Representation. For 779 example, an MA-L like "AC-DE-48" would be encoded in 3 bytes with 780 values 0xAC, 0xDE, 0x48. 782 This format is always 3 bytes in size in CBOR. 784 In JSON format tokens, this MUST be base64url encoded and always 4 785 bytes. 787 4.2.3.3. IANA Private Enterprise Number Based OEMID 789 IANA maintains a integer-based company registry called the Private 790 Enterprise Number (PEN) [PEN]. 792 PENs are often used to create an OID. That is not the case here. 793 They are used only as an integer. 795 In CBOR this value MUST be encoded as a major type 0 integer and is 796 typically 3 bytes. In JSON, this value MUST be encoded as a number. 798 $$Claims-Set-Claims //= ( 799 oemid-label => oemid-pen / oemid-ieee / oemid-random 800 ) 802 oemid-pen = int 804 oemid-ieee = JC 805 oemid-ieee-cbor = bstr .size 3 806 oemid-ieee-json = base64-url-text .size 4 808 oemid-random = JC 809 oemid-random-cbor = bstr .size 16 810 oemid-random-json = base64-url-text .size 24 812 4.2.4. Hardware Model Claim (hardware-model) 814 This claim differentiates hardware models, products and variants 815 manufactured by a particular OEM, the one identified by OEM ID in 816 Section 4.2.3. 818 This claim must be unique so as to differentiate the models and 819 products for the OEM ID. This claim does not have to be globally 820 unique, but it can be. A receiver of this claim MUST not assume it 821 is globally unique. To globally identify a particular product, the 822 receiver should concatenate the OEM ID and this claim. 824 The granularity of the model identification is for each OEM to 825 decide. It may be very granular, perhaps including some version 826 information. It may be very general, perhaps only indicating top- 827 level products. 829 The purpose of this claim is to identify models within protocols, not 830 for human-readable descriptions. The format and encoding of this 831 claim should not be human-readable to discourage use other than in 832 protocols. If this claim is to be derived from an already-in-use 833 human-readable identifier, it can be run through a hash function. 835 There is no minimum length so that an OEM with a very small number of 836 models can use a one-byte encoding. The maximum length is 32 bytes. 837 All receivers of this claim MUST be able to receive this maximum 838 size. 840 The receiver of this claim MUST treat it as a completely opaque 841 string of bytes, even if there is some apparent naming or structure. 842 The OEM is free to alter the internal structure of these bytes as 843 long as the claim continues to uniquely identify its models. 845 $$Claims-Set-Claims //= ( 846 hardware-model-label => hardware-model-type 847 ) 849 hardware-model-type = JC 852 4.2.5. Hardware Version Claims (hardware-version-claims) 854 The hardware version is a text string the format of which is set by 855 each manufacturer. The structure and sorting order of this text 856 string can be specified using the version-scheme item from CoSWID 857 [CoSWID]. It is useful to know how to sort versions so the newer can 858 be distinguished from the older. 860 The hardware version can also be given by a 13-digit [EAN-13]. A new 861 CoSWID version scheme is registered with IANA by this document in 862 Section 9.3.3. An EAN-13 is also known as an International Article 863 Number or most commonly as a bar code. 865 $$Claims-Set-Claims //= ( 866 hardware-version-label => hardware-version-type 867 ) 869 hardware-version-type = [ 870 version: tstr, 871 ? scheme: $version-scheme 872 ] 874 4.2.6. Software Name Claim 876 This is a free-form text claim for the name of the software for the 877 entity or submodule. A CoSWID manifest or other type of manifest can 878 be used instead if this claim is to limited to correctly characterize 879 the SW for the entity or submodule. 881 $$Claims-Set-Claims //= ( sw-name-label => tstr ) 883 4.2.7. Software Version Claim 885 This makes use of the CoSWID version scheme data type to give a 886 simple version for the software. A full CoSWID manifest or other 887 type of manifest can be instead if this is too simple. 889 $$Claims-Set-Claims //= (sw-version-label => sw-version-type) 891 sw-version-type = [ 892 version: tstr 893 ? scheme: $version-scheme 894 ] 896 4.2.8. The Security Level Claim (security-level) 898 This claim characterizes the entity's ability to defend against 899 attacks aimed at capturing the signing key, forging claims and 900 forging EATs. 902 The intent of this claim is only to give the recipient a rough idea 903 of the security the entity is aiming for. This is via a simple, non- 904 extensible set of three levels. 906 This takes a broad view of the range of defenses because EAT is 907 targeted at a broad range of use cases. The least secure level 908 involves minimal SW defenses. The most secure level involves 909 specialized hardware to defend against hardware-based attacks. 911 Only through expansive certification programs like Common Criteria 912 and FIDO certification is it possible to sharply define security 913 levels. Sharp definition of security levels is not possible here 914 because the IETF doesn't define and operate certification programs. 915 It is also not possible here because any sharp definition of security 916 levels would be a document larger than the EAT specification. Thus, 917 this definition takes the view that the security level definition 918 possible here is a simple, modest, rough characterization. 920 1 - Unrestricted: An entity is categorized as unrestricted when it 921 doesn't meet the criteria for any of the higher levels. This 922 level does not indicate there is no protection at all, just that 923 the entity doesn't qualify for the higher levels. 925 2 - Restricted: Entities at this level MUST meet the criteria 926 defined in Section 4 of FIDO Allowed Restricted Operating 927 Environments [FIDO.AROE]. Examples include TEE's and schemes 928 using virtualization-based security. Security at this level is 929 aimed at defending against large-scale network/remote attacks by 930 having a reduced attack surface. 932 3 - Hardware: Entities at this level are indicating they have some 933 countermeasures to defend against physical or electrical attacks 934 against the entity. Security at this level is aimed at defending 935 against attackers that physically capture the entity to attack it. 936 Examples include TPMs and Secure Elements. 938 The security level claimed should be for the weakest point in the 939 entity, not the strongest. For example, if attestation key is 940 protected by hardware, but the rest of the attester is in a TEE, the 941 claim must be for restriced. 943 This set of three is not extensible so this remains a broad 944 interoperable description of security level. 946 In particular use cases, alternate claims may be defined that give 947 finer grained information than this claim. 949 See also the DLOAs claim in Section 4.2.15, a claim that specifically 950 provides information about certifications received. 952 $$Claims-Set-Claims //= 953 ( security-level-label => security-level-type ) 955 security-level-type = unrestricted / 956 restricted / 957 hardware 959 unrestricted = JC< "unrestricted", 1> 960 restricted = JC< "restricted", 2> 961 hardware = JC< "hardware", 3> 963 4.2.9. Secure Boot Claim (secure-boot) 965 The value of true indicates secure boot is enabled. Secure boot is 966 considered enabled when the firmware and operating system, are under 967 control of the manufacturer of the entity identified in the OEMID 968 claim described in Section 4.2.3. Control by the manufacturer of the 969 firmware and the operating system may be by it being in ROM, being 970 cryptographically authenticated, a combination of the two or similar. 972 $$Claims-Set-Claims //= (secure-boot-label => bool) 974 4.2.10. Debug Status Claim (debug-status) 976 This applies to entity-wide or submodule-wide debug facilities of the 977 entity like JTAG and diagnostic hardware built into chips. It 978 applies to any software debug facilities related to root, operating 979 system or privileged software that allow system-wide memory 980 inspection, tracing or modification of non-system software like user 981 mode applications. 983 This characterization assumes that debug facilities can be enabled 984 and disabled in a dynamic way or be disabled in some permanent way 985 such that no enabling is possible. An example of dynamic enabling is 986 one where some authentication is required to enable debugging. An 987 example of permanent disabling is blowing a hardware fuse in a chip. 988 The specific type of the mechanism is not taken into account. For 989 example, it does not matter if authentication is by a global password 990 or by per-entity public keys. 992 As with all claims, the absence of the debug level claim means it is 993 not reported. A conservative interpretation might assume the enabled 994 state. 996 This claim is not extensible so as to provide a common interoperable 997 description of debug status. If a particular implementation 998 considers this claim to be inadequate, it can define its own 999 proprietary claim. It may consider including both this claim as a 1000 coarse indication of debug status and its own proprietary claim as a 1001 refined indication. 1003 The higher levels of debug disabling requires that all debug 1004 disabling of the levels below it be in effect. Since the lowest 1005 level requires that all of the target's debug be currently disabled, 1006 all other levels require that too. 1008 There is no inheritance of claims from a submodule to a superior 1009 module or vice versa. There is no assumption, requirement or 1010 guarantee that the target of a superior module encompasses the 1011 targets of submodules. Thus, every submodule must explicitly 1012 describe its own debug state. The receiver of an EAT MUST not assume 1013 that debug is turned off in a submodule because there is a claim 1014 indicating it is turned off in a superior module. 1016 An entity may have multiple debug facilities. The use of plural in 1017 the description of the states refers to that, not to any aggregation 1018 or inheritance. 1020 The architecture of some chips or devices may be such that a debug 1021 facility operates for the whole chip or device. If the EAT for such 1022 a chip includes submodules, then each submodule should independently 1023 report the status of the whole-chip or whole-device debug facility. 1024 This is the only way the receiver can know the debug status of the 1025 submodules since there is no inheritance. 1027 4.2.10.1. Enabled 1029 If any debug facility, even manufacturer hardware diagnostics, is 1030 currently enabled, then this level must be indicated. 1032 4.2.10.2. Disabled 1034 This level indicates all debug facilities are currently disabled. It 1035 may be possible to enable them in the future. It may also be that 1036 they were enabled in the past, but they are currently disabled. 1038 4.2.10.3. Disabled Since Boot 1040 This level indicates all debug facilities are currently disabled and 1041 have been so since the entity booted/started. 1043 4.2.10.4. Disabled Permanently 1045 This level indicates all non-manufacturer facilities are permanently 1046 disabled such that no end user or developer can enable them. Only 1047 the manufacturer indicated in the OEMID claim can enable them. This 1048 also indicates that all debug facilities are currently disabled and 1049 have been so since boot/start. 1051 4.2.10.5. Disabled Fully and Permanently 1053 This level indicates that all debug facilities for the entity are 1054 permanently disabled. 1056 $$Claims-Set-Claims //= ( debug-status-label => debug-status-type ) 1058 debug-status-type = ds-enabled / 1059 disabled / 1060 disabled-since-boot / 1061 disabled-permanently / 1062 disabled-fully-and-permanently 1064 ds-enabled = JC< "enabled", 0 > 1065 disabled = JC< "disabled", 1 > 1066 disabled-since-boot = JC< "disabled-since-boot", 2 > 1067 disabled-permanently = JC< "disabled-permanently", 3 > 1068 disabled-fully-and-permanently = JC< "disabled-fully-and-permanently", 1069 4 > 1071 4.2.11. The Location Claim (location) 1073 The location claim gives the location of the entity from which the 1074 attestation originates. It is derived from the W3C Geolocation API 1075 [W3C.GeoLoc]. The latitude, longitude, altitude and accuracy must 1076 conform to [WGS84]. The altitude is in meters above the [WGS84] 1077 ellipsoid. The two accuracy values are positive numbers in meters. 1078 The heading is in degrees relative to true north. If the entity is 1079 stationary, the heading is NaN (floating-point not-a-number). The 1080 speed is the horizontal component of the entity velocity in meters 1081 per second. 1083 The location may have been cached for a period of time before token 1084 creation. For example, it might have been minutes or hours or more 1085 since the last contact with a GPS satellite. Either the timestamp or 1086 age data item can be used to quantify the cached period. The 1087 timestamp data item is preferred as it a non-relative time. 1089 The age data item can be used when the entity doesn't know what time 1090 it is either because it doesn't have a clock or it isn't set. The 1091 entity MUST still have a "ticker" that can measure a time interval. 1092 The age is the interval between acquisition of the location data and 1093 token creation. 1095 See location-related privacy considerations in Section 10.2. 1097 $$Claims-Set-Claims //= (location-label => location-type) 1099 location-type = { 1100 latitude => number, 1101 longitude => number, 1102 ? altitude => number, 1103 ? accuracy => number, 1104 ? altitude-accuracy => number, 1105 ? heading => number, 1106 ? speed => number, 1107 ? timestamp => ~time-int, 1108 ? age => uint 1109 } 1111 latitude = JC< "latitude", 1 > 1112 longitude = JC< "longitude", 2 > 1113 altitude = JC< "altitude", 3 > 1114 accuracy = JC< "accuracy", 4 > 1115 altitude-accuracy = JC< "altitude-accuracy", 5 > 1116 heading = JC< "heading", 6 > 1117 speed = JC< "speed", 7 > 1118 timestamp = JC< "timestamp", 8 > 1119 age = JC< "age", 9 > 1121 4.2.12. The Uptime Claim (uptime) 1123 The "uptime" claim MUST contain a value that represents the number of 1124 seconds that have elapsed since the entity or submod was last booted. 1126 $$Claims-Set-Claims //= (uptime-label => uint) 1128 4.2.13. The Boot Odometer Claim (odometer) 1130 The "odometer" claim contains a value that represents the number of 1131 times the entity or submod has been booted. Support for this claim 1132 requires a persistent storage on the device. 1134 $$Claims-Set-Claims //= (odometer-label => uint) 1136 4.2.14. The Boot Seed Claim (boot-seed) 1138 The Boot Seed claim MUST contain a random value created at system 1139 boot time that will allow differentiation of reports from different 1140 boot sessions. 1142 This value is usually public. It is not a secret and MUST NOT be 1143 used for any purpose that a secret seed is needed, such as seeding a 1144 random number generator. 1146 $$Claims-Set-Claims //= (boot-seed-label => binary-data) 1148 4.2.15. The DLOA (Digital Letter of Approval) Claim (dloas) 1150 A DLOA (Digital Letter of Approval) [DLOA] is an XML document that 1151 describes a certification that an entity has received. Examples of 1152 certifications represented by a DLOA include those issued by Global 1153 Platform and those based on Common Criteria. The DLOA is unspecific 1154 to any particular certification type or those issued by any 1155 particular organization. 1157 This claim is typically issued by a Verifier, not an Attester. When 1158 this claim is issued by a Verifier, it MUST be because the entity has 1159 received the certification in the DLOA. 1161 This claim MAY contain more than one DLOA. If multiple DLOAs are 1162 present, it MUST be because the entity received all of the 1163 certifications. 1165 DLOA XML documents are always fetched from a registrar that stores 1166 them. This claim contains several data items used to construct a URL 1167 for fetching the DLOA from the particular registrar. 1169 This claim MUST be encoded as an array with either two or three 1170 elements. The first element MUST be the URI for the registrar. The 1171 second element MUST be a platform label indicating which platform was 1172 certified. If the DLOA applies to an application, then the third 1173 element is added which MUST be an application label. The method of 1174 constructing the registrar URI, platform label and possibly 1175 application label is specified in [DLOA]. 1177 $$Claims-Set-Claims //= ( 1178 dloas-label => [ + dloa-type ] 1179 ) 1181 dloa-type = [ 1182 dloa_registrar: general-uri 1183 dloa_platform_label: text 1184 ? dloa_application_label: text 1185 ] 1187 4.2.16. The Software Manifests Claim (manifests) 1189 This claim contains descriptions of software present on the entity. 1190 These manifests are installed on the entity when the software is 1191 installed or are created as part of the installation process. 1192 Installation is anything that adds software to the entity, possibly 1193 factory installation, the user installing elective applications and 1194 so on. The defining characteristic is they are created by the 1195 software manufacturer. The purpose of these claims in an EAT is to 1196 relay them without modification to the Verifier and possibly to the 1197 Relying Party. 1199 Some manifests may be signed by their software manufacturer before 1200 they are put into this EAT claim. When such manifests are put into 1201 this claim, the manufacturer's signature SHOULD be included. For 1202 example, the manifest might be a CoSWID signed by the software 1203 manufacturer, in which case the full signed CoSWID should be put in 1204 this claim. 1206 This claim allows multiple formats for the manifest. For example, 1207 the manifest may be a CBOR-format CoSWID, an XML-format SWID or 1208 other. Identification of the type of manifest is always by a CoAP 1209 Content-Format integer [RFC7252]. If there is no CoAP identifier 1210 registered for the manifest format, one should be registered, perhaps 1211 in the experimental or first-come-first-served range. 1213 This claim MUST be an array of one or more manifests. Each manifest 1214 in the claim MUST be an array of two. The first item in the array of 1215 two MUST be an integer CoAP Content-Format identifier. The second 1216 item is MUST be the actual manifest. 1218 In CBOR-encoded EATs the manifest, whatever format it is, MUST be 1219 placed in a byte string. 1221 In JSON-format tokens the manifest, whatever format it is, MUST be 1222 placed in a text string. When a non-text format manifest like a 1223 CBOR-encoded CoSWID is put in a JSON-encoded token, the manifest MUST 1224 be base-64 encoded. 1226 This claim allows for multiple manifests in one token since multiple 1227 software packages are likely to be present. The multiple manifests 1228 MAY be of different formats. In some cases EAT submodules may be 1229 used instead of the array structure in this claim for multiple 1230 manifests. 1232 When the [CoSWID] format is used, it MUST be a payload CoSWID, not an 1233 evidence CoSWID. 1235 $$Claims-Set-Claims //= ( 1236 manifests-label => manifests-type 1237 ) 1239 manifests-type = [+ manifest-format] 1241 manifest-format = [ 1242 content-type: uint, 1243 content-format: JC< $$manifest-body-json, 1244 $$manifest-body-cbor > 1245 ] 1247 $$manifest-body-cbor /= bytes .cbor untagged-coswid 1248 $$manifest-body-json /= base64-url-text 1250 $$manifest-body-cbor /= bytes .cbor SUIT_Envelope 1251 $$manifest-body-json /= base64-url-text 1253 suit-directive-process-dependency = 19 1255 4.2.17. The Software Evidence Claim (swevidence) 1257 This claim contains descriptions, lists, evidence or measurements of 1258 the software that exists on the entity. The defining characteristic 1259 of this claim is that its contents are created by processes on the 1260 entity that inventory, measure or otherwise characterize the software 1261 on the entity. The contents of this claim do not originate from the 1262 software manufacturer. 1264 This claim can be a [CoSWID]. When the CoSWID format is used, it 1265 MUST be evidence CoSWIDs, not payload CoSWIDS. 1267 Formats other than CoSWID can be used. The identification of format 1268 is by CoAP Content Format, the same as the manifests claim in 1269 Section 4.2.16. 1271 $$Claims-Set-Claims //= ( 1272 swevidence-label => swevidence-type 1273 ) 1275 swevidence-type = [+ swevidence-format] 1277 swevidence-format = [ 1278 content-type: uint, 1279 content-format: JC< $$swevidence-body-json, 1280 $$swevidence-body-cbor > 1281 ] 1283 $$swevidence-body-cbor /= bytes .cbor untagged-coswid 1284 $$swevidence-body-json /= base64-url-text 1286 4.2.18. The Measurement Results Claim (measurement-results) 1288 This claim is a general-purpose structure for reporting comparison of 1289 measurements to expected Reference Values. This claim provides a 1290 simple standard way to report the result of a comparison as success, 1291 failure, fail to run, ... 1293 It is the nature of measurement systems that they are specific to the 1294 operating system, software and hardware of the entity that is being 1295 measured. It is not possible to standardize what is measured and how 1296 it is measured across platforms, OS's, software and hardware. The 1297 recipient must obtain the information about what was measured and 1298 what it indicates for the characterization of the security of the 1299 entity from the provider of the measurement system. What this claim 1300 provides is a standard way to report basic success or failure of the 1301 measurement. In some use cases it is valuable to know if 1302 measurements succeeded or failed in a general way even if the details 1303 of what was measured is not characterized. 1305 This claim MAY be generated by the Verifier and sent to the Relying 1306 Party. For example, it could be the results of the Verifier 1307 comparing the contents of the swevidence claim, {#swevidence}, to 1308 Reference Values. 1310 This claim MAY also be generated on the entity if the entity has the 1311 ability for one subsystem to measure and evaluate another subsystem. 1312 For example, a TEE might have the ability to measure the software of 1313 the rich OS and may have the Reference Values for the rich OS. 1315 Within an entity, attestation target or submodule, multiple results 1316 can be reported. For example, it may be desirable to report the 1317 results for measurements of the file system, chip configuration, 1318 installed software, running software and so on. 1320 Note that this claim is not for reporting the overall result of a 1321 Verifier. It is solely for reporting the result of comparison to 1322 reference values. 1324 An individual measurement result is an array of two, an identifier of 1325 the measurement and an enumerated type that is the result. The range 1326 and values of the measurement identifier varies from one measurement 1327 scheme to another. 1329 Each individual measurement result is part of a group that may 1330 contain many individual results. Each group has a text string that 1331 names it, typically the name of the measurement scheme or system. 1333 The claim itself consists of one or more groups. 1335 The values for the results enumerated type are as follows: 1337 1 - comparison successful Indicates successful comparison to 1338 reference values. 1340 2 - comparison fail The comparison was completed and did not compare 1341 correctly to the Reference Values. 1343 3 - comparison not run The comparison was not run. This includes 1344 error conditions such as running out of memory. 1346 4 - measurement absent The particular measurement was not available 1347 for comparison. 1349 $$Claims-Set-Claims //= ( 1350 measurement-results-label => 1351 [ + measurement-results-group ] ) 1353 measurement-results-group = [ 1354 measurement-system: tstr, 1355 measruement-results: [ + individual-result ] 1356 ] 1358 individual-result = [ 1359 results-id: tstr / binary-data, 1360 result: result-type, 1361 ] 1363 result-type = comparison-successful / 1364 comparison-fail / 1365 comparison-not-run / 1366 measurement-absent 1368 comparison-successful = JC< "success", 1 > 1369 comparison-fail = JC< "fail", 2 > 1370 comparison-not-run = JC< "not-run", 3 > 1371 measurement-absent = JC< "absent", 4 > 1373 4.2.19. Submodules (submods) 1375 Some devices are complex, having many subsystems. A mobile phone is 1376 a good example. It may have several connectivity subsystems for 1377 communications (e.g., Wi-Fi and cellular). It may have subsystems 1378 for low-power audio and video playback. It may have multiple 1379 security-oriented subsystems like a TEE and a Secure Element. 1381 The claims for a subsystem can be grouped together in a submodule or 1382 submod. 1384 The submods are in a single map/object, one entry per submodule. 1385 There is only one submods map/object in a token. It is identified by 1386 its specific label. It is a peer to other claims, but it is not 1387 called a claim because it is a container for a claims set rather than 1388 an individual claim. This submods part of a token allows what might 1389 be called recursion. It allows claims sets inside of claims sets 1390 inside of claims sets... 1392 4.2.19.1. Submodule Types 1394 The following sections define the three types of submodules: 1396 o A submodule Claims-Set 1398 o A nested token, which can be any valid EAT token, CBOR or JSON 1400 o The digest of a detached Claims-Set 1402 $$Claims-Set-Claims //= (submods-label => { + text => Submodule }) 1404 Submodule = Claims-Set / Nested-Token / Detached-Submodule-Digest 1406 4.2.19.1.1. Submodule Claims-Set 1408 This is a subordinate Claims-Set containing claims about the 1409 submodule. 1411 The submodule Claims-Set is produced by the same Attester as the 1412 surrounding token. It is secured using the same mechanism as the 1413 enclosing token (e.g., it is signed by the same attestation key). It 1414 roughly corresponds to an Attester Target Environment, as described 1415 in the RATS architecture. 1417 It may contain claims that are the same as its surrounding token or 1418 superior submodules. For example, the top-level of the token may 1419 have a UEID, a submod may have a different UEID and a further 1420 subordinate submodule may also have a UEID. 1422 The encoding of a submodule Claims-Set MUST be the same as the 1423 encoding as the token it is part of. 1425 This data type for this type of submodule is a map/object. It is 1426 identified when decoding by it's type being a map/object. 1428 4.2.19.1.2. Nested Token 1430 This type of submodule is a fully formed complete token. It is 1431 typically produced by a separate Attester. It is typically used by a 1432 Composite Device as described in RATS Architecture 1433 [RATS.Architecture] In being a submodule of the surrounding token, it 1434 is cryptographically bound to the surrounding token. If it was 1435 conveyed in parallel with the surrounding token, there would be no 1436 such binding and attackers could substitute a good attestation from 1437 another device for the attestation of an errant subsystem. 1439 A nested token does not need to use the same encoding as the 1440 enclosing token. This is to allow Composite Devices to be built 1441 without regards to the encoding supported by their Attesters. Thus, 1442 a CBOR-encoded token like a CWT can have a JWT as a nested token 1443 submodule and vice versa. 1445 4.2.19.1.2.1. Surrounding EAT is CBOR-Encoded 1447 This describes the encoding and decoding of CBOR or JSON-encoded 1448 tokens nested inside a CBOR-encoded token. 1450 If the nested token is CBOR-encoded, then it MUST be a CBOR tag and 1451 MUST be wrapped in a byte string. The tag identifies whether the 1452 nested token is a CWT, a CBOR-encoded DEB, or some other CBOR-format 1453 token defined in the future. A nested CBOR-encoded token that is not 1454 a CBOR tag is NOT allowed. 1456 If the nested token is JSON-encoded, then the data item MUST be a 1457 text string containing JSON. The JSON is defined in CDDL by JSON- 1458 Nested-Token in the next section. 1460 When decoding, if a byte string is encountered, it is known to be a 1461 nested CBOR-encoded token. The byte string wrapping is removed. The 1462 type of the token is determined by the CBOR tag. 1464 When decoding, if a text string is encountered, it is known to be a 1465 JSON-encoded token. The two-item array is decoded and tells the type 1466 of the JSON-encoded token. 1468 Nested-Token = CBOR-Nested-Token 1470 CBOR-Nested-Token = 1471 JSON-Token-Inside-CBOR-Token / 1472 CBOR-Token-Inside-CBOR-Token 1474 CBOR-Token-Inside-CBOR-Token = bstr .cbor $$EAT-CBOR-Tagged-Token 1476 JSON-Token-Inside-CBOR-Token = tstr 1478 4.2.19.1.2.2. Surrounding EAT is JSON-Encoded 1480 This describes the encoding and decoding of CBOR or JSON-encoded 1481 tokens nested inside a JSON-encoded token. 1483 The nested token MUST be an array of two, a text string type 1484 indicator and the actual token. 1486 The string identifying the JSON-encoded token MUST be one of the 1487 following: 1489 "JWT": The second array item MUST be a JWT formatted according to 1490 [RFC7519] 1492 "CBOR": The second array item must be some base64url-encoded CBOR 1493 that is a tag, typically a CWT or CBOR-encoded DEB 1495 "DEB": The second array item MUST be a JSON-encoded Detached EAT 1496 Bundle as defined in this document. 1498 Additional types may be defined by a standards action. 1500 When decoding, the array of two is decoded. The first item indicates 1501 the type and encoding of the nested token. If the type string is not 1502 "CBOR", then the token is JSON-encoded and of the type indicated by 1503 the string. 1505 If the type string is "CBOR", then the token is CBOR-encoded. The 1506 base64url encoding is removed. The CBOR-encoded data is then 1507 decoded. The type of nested token is determined by the CBOR-tag. It 1508 is an error if the CBOR is not a tag. 1510 Nested-Token = JSON-Nested-Token 1512 JSON-Nested-Token = [ 1513 type : "JWT" / "CBOR" / "DEB", 1514 nested-token : JWT-Message / 1515 CBOR-Token-Inside-JSON-Token / 1516 Detached-EAT-Bundle 1517 ] 1519 CBOR-Token-Inside-JSON-Token = base64-url-text 1521 4.2.19.1.3. Detached Submodule Digest 1523 This is type of submodule equivalent to a Claims-Set submodule, 1524 except the Claims-Set is conveyed separately outside of the token. 1526 This type of submodule consists of a digest made using a 1527 cryptographic hash of a Claims-Set. The Claims-Set is not included 1528 in the token. It is conveyed to the Verifier outside of the token. 1529 The submodule containing the digest is called a detached digest. The 1530 separately conveyed Claims-Set is called a detached claims set. 1532 The input to the digest is exactly the byte-string wrapped encoded 1533 form of the Claims-Set for the submodule. That Claims-Set can 1534 include other submodules including nested tokens and detached 1535 digests. 1537 The primary use for this is to facilitate the implementation of a 1538 small and secure attester, perhaps purely in hardware. This small, 1539 secure attester implements COSE signing and only a few claims, 1540 perhaps just UEID and hardware identification. It has inputs for 1541 digests of submodules, perhaps 32-byte hardware registers. Software 1542 running on the device constructs larger claim sets, perhaps very 1543 large, encodes them and digests them. The digests are written into 1544 the small secure attesters registers. The EAT produced by the small 1545 secure attester only contains the UEID, hardware identification and 1546 digests and is thus simple enough to be implemented in hardware. 1547 Probably, every data item in it is of fixed length. 1549 The integrity protection for the larger Claims Sets will not be as 1550 secure as those originating in hardware block, but the key material 1551 and hardware-based claims will be. It is possible for the hardware 1552 to enforce hardware access control (memory protection) on the digest 1553 registers so that some of the larger claims can be more secure. For 1554 example, one register may be writable only by the TEE, so the 1555 detached claims from the TEE will have TEE-level security. 1557 The data type for this type of submodule MUST be an array It contains 1558 two data items, an algorithm identifier and a byte string containing 1559 the digest. 1561 When decoding a CBOR format token the detached digest type is 1562 distringuished from the other types by it being an array. In CBOR 1563 the none of other submodule types are arrays. 1565 When decoding a JSON format token, a little more work is required 1566 because both the nested token and detached digest types are an array. 1567 To distinguish the nested token from the detached digest, the first 1568 element in the array is examined. If it is "JWT" or "DEB", then the 1569 submodule is a nested token. Otherwise it will contain an algorithm 1570 identifier and is a detached digest. 1572 A DEB, described in Section 5, may be used to convey detached claims 1573 sets and the token with their detached digests. EAT, however, 1574 doesn't require use of a DEB. Any other protocols may be used to 1575 convey detached claims sets and the token with their detached 1576 digests. Note that since detached Claims-Sets are signed, protocols 1577 conveying them must make sure they are not modified in transit. 1579 Detached-Submodule-Digest = [ 1580 algorithm : JC< text, int > 1581 digest : binary-data 1582 ] 1584 4.2.19.2. No Inheritance 1586 The subordinate modules do not inherit anything from the containing 1587 token. The subordinate modules must explicitly include all of their 1588 claims. This is the case even for claims like the nonce. 1590 This rule is in place for simplicity. It avoids complex inheritance 1591 rules that might vary from one type of claim to another. 1593 4.2.19.3. Security Levels 1595 The security level of the non-token subordinate modules should always 1596 be less than or equal to that of the containing modules in the case 1597 of non-token submodules. It makes no sense for a module of lesser 1598 security to be signing claims of a module of higher security. An 1599 example of this is a TEE signing claims made by the non-TEE parts 1600 (e.g. the high-level OS) of the device. 1602 The opposite may be true for the nested tokens. They usually have 1603 their own more secure key material. An example of this is an 1604 embedded secure element. 1606 4.2.19.4. Submodule Names 1608 The label or name for each submodule in the submods map is a text 1609 string naming the submodule. No submodules may have the same name. 1611 4.3. Claims Describing the Token 1613 The claims in this section provide meta data about the token they 1614 occur in. They do not describe the entity. 1616 They may appear in Attestation Evidence or Attestation Results. When 1617 these claims appear in Attestation Evidence, they SHOULD not be 1618 passed through the Verifier into Attestation Results. 1620 4.3.1. Token ID Claim (cti and jti) 1622 CWT defines the "cti" claim. JWT defines the "jti" claim. These are 1623 equivalent to each other in EAT and carry a unique token identifier 1624 as they do in JWT and CWT. They may be used to defend against re use 1625 of the token but are distinct from the nonce that is used by the 1626 Relying Party to guarantee freshness and defend against replay. 1628 4.3.2. Timestamp claim (iat) 1630 The "iat" claim defined in CWT and JWT is used to indicate the date- 1631 of-creation of the token, the time at which the claims are collected 1632 and the token is composed and signed. 1634 The data for some claims may be held or cached for some period of 1635 time before the token is created. This period may be long, even 1636 days. Examples are measurements taken at boot or a geographic 1637 position fix taken the last time a satellite signal was received. 1638 There are individual timestamps associated with these claims to 1639 indicate their age is older than the "iat" timestamp. 1641 CWT allows the use floating-point for this claim. EAT disallows the 1642 use of floating-point. An EAT token MUST NOT contain an iat claim in 1643 float-point format. Any recipient of a token with a floating-point 1644 format iat claim MUST consider it an error. A 64-bit integer 1645 representation of epoch time can represent a range of +/- 500 billion 1646 years, so the only point of a floating-point timestamp is to have 1647 precession greater than one second. This is not needed for EAT. 1649 4.3.3. The Profile Claim (profile) 1651 See Section 7 for the detailed description of a profile. 1653 A profile is identified by either a URL or an OID. Typically, the 1654 URI will reference a document describing the profile. An OID is just 1655 a unique identifier for the profile. It may exist anywhere in the 1656 OID tree. There is no requirement that the named document be 1657 publicly accessible. The primary purpose of the profile claim is to 1658 uniquely identify the profile even if it is a private profile. 1660 The OID is always absolute and never relative. 1662 See Section 8.2.1 for OID and URI encoding. 1664 Note that this is named "eat_profile" for JWT and is distinct from 1665 the already registered "profile" claim in the JWT claims registry. 1667 $$Claims-Set-Claims //= (profile-label => general-uri / general-oid) 1669 4.3.4. The Intended Use Claim (intended-use) 1671 EAT's may be used in the context of several different applications. 1672 The intended-use claim provides an indication to an EAT consumer 1673 about the intended usage of the token. This claim can be used as a 1674 way for an application using EAT to internally distinguish between 1675 different ways it uses EAT. 1677 1 - Generic: Generic attestation describes an application where the 1678 EAT consumer requires the most up-to-date security assessment of 1679 the attesting entity. It is expected that this is the most 1680 commonly-used application of EAT. 1682 2- Registration: Entities that are registering for a new service may 1683 be expected to provide an attestation as part of the registration 1684 process. This intended-use setting indicates that the attestation 1685 is not intended for any use but registration. 1687 3 - Provisioning: Entities may be provisioned with different values 1688 or settings by an EAT consumer. Examples include key material or 1689 device management trees. The consumer may require an EAT to 1690 assess entity security state of the entity prior to provisioning. 1692 4 - Certificate Issuance Certification Authorities (CA's) may 1693 require attestations prior to the issuance of certificates related 1694 to keypairs hosted at the entity. An EAT may be used as part of 1695 the certificate signing request (CSR). 1697 5 - Proof-of-Possession: An EAT consumer may require an attestation 1698 as part of an accompanying proof-of-possession (PoP) application. 1699 More precisely, a PoP transaction is intended to provide to the 1700 recipient cryptographically-verifiable proof that the sender has 1701 possession of a key. This kind of attestation may be necceesary 1702 to verify the security state of the entity storing the private key 1703 used in a PoP application. 1705 $$Claims-Set-Claims //= ( intended-use-label => intended-use-type ) 1707 intended-use-type = generic / 1708 registration / 1709 provisioning / 1710 csr / 1711 pop 1713 generic = JC< "generic", 1 > 1714 registration = JC< "registration", 2 > 1715 provisioning = JC< "provisioning", 3 > 1716 csr = JC< "csr", 4 > 1717 pop = JC< "pop", 5 > 1719 4.4. Including Keys 1721 An EAT may include a cryptographic key such as a public key. The 1722 signing of the EAT binds the key to all the other claims in the 1723 token. 1725 The purpose for inclusion of the key may vary by use case. For 1726 example, the key may be included as part of an IoT device onboarding 1727 protocol. When the FIDO protocol includes a public key in its 1728 attestation message, the key represents the binding of a user, device 1729 and Relying Party. This document describes how claims containing 1730 keys should be defined for the various use cases. It does not define 1731 specific claims for specific use cases. 1733 Keys in CBOR format tokens SHOULD be the COSE_Key format [RFC8152] 1734 and keys in JSON format tokens SHOULD be the JSON Web Key format 1735 [RFC7517]. These two formats support many common key types. Their 1736 use avoids the need to decode other serialization formats. These two 1737 formats can be extended to support further key types through their 1738 IANA registries. 1740 The general confirmation claim format [RFC8747], [RFC7800] may also 1741 be used. It provides key encryption. It also allows for inclusion 1742 by reference through a key ID. The confirmation claim format may 1743 employed in the definition of some new claim for a a particular use 1744 case. 1746 When the actual confirmation claim is included in an EAT, this 1747 document associates no use case semantics other than proof of 1748 possession. Different EAT use cases may choose to associate further 1749 semantics. The key in the confirmation claim MUST be protected in 1750 the same way as the key used to sign the EAT. That is, the same, 1751 equivalent or better hardware defenses, access controls, key 1752 generation and such must be used. 1754 5. Detached EAT Bundles 1756 A detached EAT bundle is a structure to convey a fully-formed and 1757 signed token plus detached claims set that relate to that token. It 1758 is a top-level EAT message like a CWT or JWT. It can be occur any 1759 place that CWT or JWT messages occur. It may also be sent as a 1760 submodule. 1762 A DEB has two main parts. 1764 The first part is a full top-level token. This top-level token must 1765 have at least one submodule that is a detached digest. This top- 1766 level token may be either CBOR or JSON-encoded. It may be a CWT, or 1767 JWT but not a DEB. It may also be some future-defined token type. 1768 The same mechanism for distinguishing the type for nested token 1769 submodules is used here. 1771 The second part is a map/object containing the detached Claims-Sets 1772 corresponding to the detached digests in the full token. When the 1773 DEB is CBOR-encoded, each Claims-Set is wrapped in a byte string. 1774 When the DEB is JSON-encoded, each Claims-Set is base64url encoded. 1775 All the detached Claims-Sets MUST be encoded in the same format as 1776 the DEB. No mixing of encoding formats is allowed for the Claims- 1777 Sets in a DEB. 1779 For CBOR-encoded DEBs, tag TBD602 can be used to identify it. The 1780 normal rules apply for use or non-use of a tag. When it is sent as a 1781 submodule, it is always sent as a tag to distinguish it from the 1782 other types of nested tokens. 1784 The digests of the detached claims sets are associated with detached 1785 Claims-Sets by label/name. It is up to the constructor of the 1786 detached EAT bundle to ensure the names uniquely identify the 1787 detachedclaims sets. Since the names are used only in the detached 1788 EAT bundle, they can be very short, perhaps one byte. 1790 DEB-Messages = DEB-Tagged-Message / DEB-Untagged-Message 1792 DEB-Tagged-Message = #6.TBD(DEB-Untagged-Message) 1793 DEB-Untagged-Message = Detached-EAT-Bundle 1795 Detached-EAT-Bundle = [ 1796 main-token : Nested-Token, 1797 detached-claims-sets: { 1798 + tstr => JC 1800 } 1801 ] 1803 json-wrapped-claims-set = base64-url-text 1805 cbor-wrapped-claims-set = bstr .cbor Claims-Set 1807 6. Endorsements and Verification Keys 1809 The Verifier must possess the correct key when it performs the 1810 cryptographic part of an EAT verification (e.g., verifying the COSE/ 1811 JOSE signature). This section describes several ways to identify the 1812 verification key. There is not one standard method. 1814 The verification key itself may be a public key, a symmetric key or 1815 something complicated in the case of a scheme like Direct Anonymous 1816 Attestation (DAA). 1818 RATS Architecture [RATS.Architecture] describes what is called an 1819 Endorsement. This is an input to the Verifier that is usually the 1820 basis of the trust placed in an EAT and the Attester that generated 1821 it. It may contain the public key for verification of the signature 1822 on the EAT. It may contain Reference Values to which EAT claims are 1823 compared as part of the verification process. It may contain implied 1824 claims, those that are passed on to the Relying Party in Attestation 1825 Results. 1827 There is not yet any standard format(s) for an Endorsement. One 1828 format that may be used for an Endorsement is an X.509 certificate. 1829 Endorsement data like Reference Values and implied claims can be 1830 carried in X.509 v3 extensions. In this use, the public key in the 1831 X.509 certificate becomes the verification key, so identification of 1832 the Endorsement is also identification of the verification key. 1834 The verification key identification and establishment of trust in the 1835 EAT and the attester may also be by some other means than an 1836 Endorsement. 1838 For the components (Attester, Verifier, Relying Party,...) of a 1839 particular end-end attestation system to reliably interoperate, its 1840 definition should specify how the verification key is identified. 1841 Usually, this will be in the profile document for a particular 1842 attestation system. 1844 6.1. Identification Methods 1846 Following is a list of possible methods of key identification. A 1847 specific attestation system may employ any one of these or one not 1848 listed here. 1850 The following assumes Endorsements are X.509 certificates or 1851 equivalent and thus does not mention or define any identifier for 1852 Endorsements in other formats. If such an Endorsement format is 1853 created, new identifiers for them will also need to be created. 1855 6.1.1. COSE/JWS Key ID 1857 The COSE standard header parameter for Key ID (kid) may be used. See 1858 [RFC8152] and [RFC7515] 1860 COSE leaves the semantics of the key ID open-ended. It could be a 1861 record locator in a database, a hash of a public key, an input to a 1862 KDF, an authority key identifier (AKI) for an X.509 certificate or 1863 other. The profile document should specify what the key ID's 1864 semantics are. 1866 6.1.2. JWS and COSE X.509 Header Parameters 1868 COSE X.509 [COSE.X509.Draft] and JSON Web Siganture [RFC7515] define 1869 several header parameters (x5t, x5u,...) for referencing or carrying 1870 X.509 certificates any of which may be used. 1872 The X.509 certificate may be an Endorsement and thus carrying 1873 additional input to the Verifier. It may be just an X.509 1874 certificate, not an Endorsement. The same header parameters are used 1875 in both cases. It is up to the attestation system design and the 1876 Verifier to determine which. 1878 6.1.3. CBOR Certificate COSE Header Parameters 1880 Compressed X.509 and CBOR Native certificates are defined by CBOR 1881 Certificates [CBOR.Cert.Draft]. These are semantically compatible 1882 with X.509 and therefore can be used as an equivalent to X.509 as 1883 described above. 1885 These are identified by their own header parameters (c5t, c5u,...). 1887 6.1.4. Claim-Based Key Identification 1889 For some attestation systems, a claim may be re-used as a key 1890 identifier. For example, the UEID uniquely identifies the entity and 1891 therefore can work well as a key identifier or Endorsement 1892 identifier. 1894 This has the advantage that key identification requires no additional 1895 bytes in the EAT and makes the EAT smaller. 1897 This has the disadvantage that the unverified EAT must be 1898 substantially decoded to obtain the identifier since the identifier 1899 is in the COSE/JOSE payload, not in the headers. 1901 6.2. Other Considerations 1903 In all cases there must be some way that the verification key is 1904 itself verified or determined to be trustworthy. The key 1905 identification itself is never enough. This will always be by some 1906 out-of-band mechanism that is not described here. For example, the 1907 Verifier may be configured with a root certificate or a master key by 1908 the Verifier system administrator. 1910 Often an X.509 certificate or an Endorsement carries more than just 1911 the verification key. For example, an X.509 certificate might have 1912 key usage constraints and an Endorsement might have Reference Values. 1913 When this is the case, the key identifier must be either a protected 1914 header or in the payload such that it is cryptographically bound to 1915 the EAT. This is in line with the requirements in section 6 on Key 1916 Identification in JSON Web Signature [RFC7515]. 1918 7. Profiles 1920 This EAT specification does not gaurantee that implementations of it 1921 will interoperate. The variability in this specification is 1922 necessary to accommodate the widely varying use cases. An EAT 1923 profile narrows the specification for a specific use case. An ideal 1924 EAT profile will guarantee interoperability. 1926 The profile can be named in the token using the profile claim 1927 described in Section 4.3.3. 1929 A profile can apply to Attestation Evidence or to Attestation Results 1930 or both. 1932 7.1. Format of a Profile Document 1934 A profile document doesn't have to be in any particular format. It 1935 may be simple text, something more formal or a combination. 1937 In some cases CDDL may be created that replaces CDDL in this or other 1938 document to express some profile requirements. For example, to 1939 require the altitude data item in the location claim, CDDL can be 1940 written that replicates the location claim with the altitude no 1941 longer optional. 1943 7.2. List of Profile Issues 1945 The following is a list of EAT, CWT, JWS, COSE, JOSE and CBOR options 1946 that a profile should address. 1948 7.2.1. Use of JSON, CBOR or both 1950 The profile should indicate whether the token format should be CBOR, 1951 JSON, both or even some other encoding. If some other encoding, a 1952 specification for how the CDDL described here is serialized in that 1953 encoding is necessary. 1955 This should be addressed for the top-level token and for any nested 1956 tokens. For example, a profile might require all nested tokens to be 1957 of the same encoding of the top level token. 1959 7.2.2. CBOR Map and Array Encoding 1961 The profile should indicate whether definite-length arrays/maps, 1962 indefinite-length arrays/maps or both are allowed. A good default is 1963 to allow only definite-length arrays/maps. 1965 An alternate is to allow both definite and indefinite-length arrays/ 1966 maps. The decoder should accept either. Encoders that need to fit 1967 on very small hardware or be actually implement in hardware can use 1968 indefinite-length encoding. 1970 This applies to individual EAT claims, CWT and COSE parts of the 1971 implementation. 1973 7.2.3. CBOR String Encoding 1975 The profile should indicate whether definite-length strings, 1976 indefinite-length strings or both are allowed. A good default is to 1977 allow only definite-length strings. As with map and array encoding, 1978 allowing indefinite-length strings can be beneficial for some smaller 1979 implementations. 1981 7.2.4. CBOR Preferred Serialization 1983 The profile should indicate whether encoders must use preferred 1984 serialization. The profile should indicate whether decoders must 1985 accept non-preferred serialization. 1987 7.2.5. COSE/JOSE Protection 1989 COSE and JOSE have several options for signed, MACed and encrypted 1990 messages. JWT may use the JOSE NULL protection option. It is 1991 possible to implement no protection, sign only, MAC only, sign then 1992 encrypt and so on. All combinations allowed by COSE, JOSE, JWT, and 1993 CWT are allowed by EAT. 1995 The profile should list the protections that must be supported by all 1996 decoders implementing the profile. The encoders them must implement 1997 a subset of what is listed for the decoders, perhaps only one. 1999 Implementations may choose to sign or MAC before encryption so that 2000 the implementation layer doing the signing or MACing can be the 2001 smallest. It is often easier to make smaller implementations more 2002 secure, perhaps even implementing in solely in hardware. The key 2003 material for a signature or MAC is a private key, while for 2004 encryption it is likely to be a public key. The key for encryption 2005 requires less protection. 2007 7.2.6. COSE/JOSE Algorithms 2009 The profile document should list the COSE algorithms that a Verifier 2010 must implement. The Attester will select one of them. Since there 2011 is no negotiation, the Verifier should implement all algorithms 2012 listed in the profile. If detached submodules are used, the COSE 2013 algorithms allowed for their digests should also be in the profile. 2015 7.2.7. DEB Support 2017 A Detatched EAT Bundle Section 5 is a special case message that will 2018 not often be used. A profile may prohibit its use. 2020 7.2.8. Verification Key Identification 2022 Section Section 6 describes a number of methods for identifying a 2023 verification key. The profile document should specify one of these 2024 or one that is not described. The ones described in this document 2025 are only roughly described. The profile document should go into the 2026 full detail. 2028 7.2.9. Endorsement Identification 2030 Similar to, or perhaps the same as Verification Key Identification, 2031 the profile may wish to specify how Endorsements are to be 2032 identified. However note that Endorsement Identification is 2033 optional, where as key identification is not. 2035 7.2.10. Freshness 2037 Just about every use case will require some means of knowing the EAT 2038 is recent enough and not a replay of an old token. The profile 2039 should describe how freshness is achieved. The section on Freshness 2040 in [RATS.Architecture] describes some of the possible solutions to 2041 achieve this. 2043 7.2.11. Required Claims 2045 The profile can list claims whose absence results in Verification 2046 failure. 2048 7.2.12. Prohibited Claims 2050 The profile can list claims whose presence results in Verification 2051 failure. 2053 7.2.13. Additional Claims 2055 The profile may describe entirely new claims. These claims can be 2056 required or optional. 2058 7.2.14. Refined Claim Definition 2060 The profile may lock down optional aspects of individual claims. For 2061 example, it may require altitude in the location claim, or it may 2062 require that HW Versions always be described using EAN-13. 2064 7.2.15. CBOR Tags 2066 The profile should specify whether the token should be a CWT Tag or 2067 not. 2069 When COSE protection is used, the profile should specify whether COSE 2070 tags are used or not. Note that RFC 8392 requires COSE tags be used 2071 in a CWT tag. 2073 Often a tag is unncessary because the surrounding or carrying 2074 protocol identifies the object as an EAT. 2076 7.2.16. Manifests and Software Evidence Claims 2078 The profile should specify which formats are allowed for the 2079 manifests and software evidence claims. The profile may also go on 2080 to say which parts and options of these formats are used, allowed and 2081 prohibited. 2083 8. Encoding and Collected CDDL 2085 An EAT is fundamentally defined using CDDL. This document specifies 2086 how to encode the CDDL in CBOR or JSON. Since CBOR can express some 2087 things that JSON can't (e.g., tags) or that are expressed differently 2088 (e.g., labels) there is some CDDL that is specific to the encoding 2089 format. 2091 8.1. Claims-Set and CDDL for CWT and JWT 2093 CDDL was not used to define CWT or JWT. It was not available at the 2094 time. 2096 This document defines CDDL for both CWT and JWT. This document does 2097 not change the encoding or semantics of anything in a CWT or JWT. 2099 A Claims-Set is the central data structure for EAT, CWT and JWT. It 2100 holds all the claims and is the structure that is secured by signing 2101 or other means. It is not possible to define EAT, CWT, or JWT in 2102 CDDL without it. The CDDL definition of Claims-Set here is 2103 applicable to EAT, CWT and JWT. 2105 This document specifies how to encode a Claims-Set in CBOR or JSON. 2107 With the exception of nested tokens and some other externally defined 2108 structures (e.g., SWIDs) an entire Claims-Set must be in encoded in 2109 either CBOR or JSON, never a mixture. 2111 CDDL for the seven claims defined by [RFC8392] and [RFC7519] is 2112 included here. 2114 8.2. Encoding Data Types 2116 This makes use of the types defined in [RFC8610] Appendix D, Standard 2117 Prelude. 2119 8.2.1. Common Data Types 2121 time-int is identical to the epoch-based time, but disallows 2122 floating-point representation. 2124 The OID encoding from [RFC9090] is used without the tag number in 2125 CBOR-encoded tokens. In JSON tokens OIDs are a text string in the 2126 common form of "nn.nn.nn...". 2128 Unless expliclity indicated, URIs are not the URI tag defined in 2129 [RFC8949]. They are just text strings that contain a URI. 2131 time-int = #6.1(int) 2133 binary-data = JC< base64-url-text, bstr> 2135 base64-url-text = tstr .regexp "[A-Za-z0-9_=-]+" 2137 general-oid = JC< json-oid, ~oid > 2139 json-oid = tstr .regexp "[0-9\.]+" 2141 general-uri = JC< text, ~uri > 2143 8.2.2. JSON Interoperability 2145 JSON should be encoded per [RFC8610] Appendix E. In addition, the 2146 following CDDL types are encoded in JSON as follows: 2148 o bstr - must be base64url encoded 2149 o time - must be encoded as NumericDate as described section 2 of 2150 [RFC7519]. 2152 o string-or-uri - must be encoded as StringOrURI as described 2153 section 2 of [RFC7519]. 2155 o uri - must be a URI [RFC3986]. 2157 o oid - encoded as a string using the well established dotted- 2158 decimal notation (e.g., the text "1.2.250.1"). 2160 The CDDL generic "JC< >" is used in most places where there is a 2161 variance between CBOR and JSON. The first argument is the CDDL for 2162 JSON and the second is CDDL for CBOR. 2164 8.2.3. Labels 2166 Map labels, including Claims-Keys and Claim-Names, and enumerated- 2167 type values are always integers when encoding in CBOR and strings 2168 when encoding in JSON. There is an exception to this for naming 2169 submodules and detached claims sets in a DEB. These are strings in 2170 CBOR. 2172 The CDDL in most cases gives both the integer label and the string 2173 label as it is not convenient to have conditional CDDL for such. 2175 8.3. CBOR Interoperability 2177 CBOR allows data items to be serialized in more than one form. If 2178 the sender uses a form that the receiver can't decode, there will not 2179 be interoperability. 2181 This specification gives no blanket requirements to narrow CBOR 2182 serialization for all uses of EAT. This allows individual uses to 2183 tailor serialization to the environment. It also may result in EAT 2184 implementations that don't interoperate. 2186 One way to guarantee interoperability is to clearly specify CBOR 2187 serialization in a profile document. See Section 7 for a list of 2188 serialization issues that should be addressed. 2190 EAT will be commonly used where the entity generating the attestation 2191 is constrained and the receiver/Verifier of the attestation is a 2192 capacious server. Following is a set of serialization requirements 2193 that work well for that use case and are guaranteed to interoperate. 2194 Use of this serialization is recommended where possible, but not 2195 required. An EAT profile may just reference the following section 2196 rather than spell out serialization details. 2198 8.3.1. EAT Constrained Device Serialization 2200 o Preferred serialization described in section 4.1 of [RFC8949] is 2201 not required. The EAT decoder must accept all forms of number 2202 serialization. The EAT encoder may use any form it wishes. 2204 o The EAT decoder must accept indefinite length arrays and maps as 2205 described in section 3.2.2 of [RFC8949]. The EAT encoder may use 2206 indefinite length arrays and maps if it wishes. 2208 o The EAT decoder must accept indefinite length strings as described 2209 in section 3.2.3 of [RFC8949]. The EAT encoder may use indefinite 2210 length strings if it wishes. 2212 o Sorting of maps by key is not required. The EAT decoder must not 2213 rely on sorting. 2215 o Deterministic encoding described in Section 4.2 of [RFC8949] is 2216 not required. 2218 o Basic validity described in section 5.3.1 of [RFC8949] must be 2219 followed. The EAT encoder must not send duplicate map keys/labels 2220 or invalid UTF-8 strings. 2222 8.4. Collected CDDL 2224 8.4.1. Payload CDDL 2226 This CDDL defines all the EAT Claims that are added to the main 2227 definition of a Claim-Set in Appendix D. Claims-Set is the payload 2228 for CWT, JWT and potentially other token types. This is for both 2229 CBOR and JSON. When there is variation between CBOR and JSON, the 2230 JC<> CDDL generic defined in Appendix D. 2232 This CDDL uses, but doesn't define Nested-Token because its 2233 definition varies between CBOR and JSON and the JC<> generic can't be 2234 used to define it. Nested-Token is the one place that that a CBOR 2235 token can be nested inside a JSON token and vice versa. Nested-Token 2236 is defined in the following sections. 2238 time-int = #6.1(int) 2240 binary-data = JC< base64-url-text, bstr> 2242 base64-url-text = tstr .regexp "[A-Za-z0-9_=-]+" 2244 general-oid = JC< json-oid, ~oid > 2245 json-oid = tstr .regexp "[0-9\.]+" 2247 general-uri = JC< text, ~uri > 2249 $$Claims-Set-Claims //= 2250 (nonce-label => nonce-type / [ 2* nonce-type ]) 2252 nonce-type = JC< tstr .size (10..74), bstr .size (8..64)> 2254 $$Claims-Set-Claims //= (ueid-label => ueid-type) 2256 ueid-type = JC 2258 $$Claims-Set-Claims //= (sueids-label => sueids-type) 2260 sueids-type = { 2261 + tstr => ueid-type 2262 } 2264 $$Claims-Set-Claims //= ( 2265 oemid-label => oemid-pen / oemid-ieee / oemid-random 2266 ) 2268 oemid-pen = int 2270 oemid-ieee = JC 2271 oemid-ieee-cbor = bstr .size 3 2272 oemid-ieee-json = base64-url-text .size 4 2274 oemid-random = JC 2275 oemid-random-cbor = bstr .size 16 2276 oemid-random-json = base64-url-text .size 24 2278 $$Claims-Set-Claims //= ( 2279 hardware-version-label => hardware-version-type 2280 ) 2282 hardware-version-type = [ 2283 version: tstr, 2284 ? scheme: $version-scheme 2285 ] 2287 $$Claims-Set-Claims //= ( 2288 hardware-model-label => hardware-model-type 2289 ) 2290 hardware-model-type = JC 2293 $$Claims-Set-Claims //= ( sw-name-label => tstr ) 2295 $$Claims-Set-Claims //= (sw-version-label => sw-version-type) 2297 sw-version-type = [ 2298 version: tstr 2299 ? scheme: $version-scheme 2300 ] 2302 $$Claims-Set-Claims //= 2303 ( security-level-label => security-level-type ) 2305 security-level-type = unrestricted / 2306 restricted / 2307 hardware 2309 unrestricted = JC< "unrestricted", 1> 2310 restricted = JC< "restricted", 2> 2311 hardware = JC< "hardware", 3> 2313 $$Claims-Set-Claims //= (secure-boot-label => bool) 2315 $$Claims-Set-Claims //= ( debug-status-label => debug-status-type ) 2317 debug-status-type = ds-enabled / 2318 disabled / 2319 disabled-since-boot / 2320 disabled-permanently / 2321 disabled-fully-and-permanently 2323 ds-enabled = JC< "enabled", 0 > 2324 disabled = JC< "disabled", 1 > 2325 disabled-since-boot = JC< "disabled-since-boot", 2 > 2326 disabled-permanently = JC< "disabled-permanently", 3 > 2327 disabled-fully-and-permanently = JC< "disabled-fully-and-permanently", 2328 4 > 2330 $$Claims-Set-Claims //= (location-label => location-type) 2332 location-type = { 2333 latitude => number, 2334 longitude => number, 2335 ? altitude => number, 2336 ? accuracy => number, 2337 ? altitude-accuracy => number, 2338 ? heading => number, 2339 ? speed => number, 2340 ? timestamp => ~time-int, 2341 ? age => uint 2342 } 2344 latitude = JC< "latitude", 1 > 2345 longitude = JC< "longitude", 2 > 2346 altitude = JC< "altitude", 3 > 2347 accuracy = JC< "accuracy", 4 > 2348 altitude-accuracy = JC< "altitude-accuracy", 5 > 2349 heading = JC< "heading", 6 > 2350 speed = JC< "speed", 7 > 2351 timestamp = JC< "timestamp", 8 > 2352 age = JC< "age", 9 > 2354 $$Claims-Set-Claims //= (uptime-label => uint) 2356 $$Claims-Set-Claims //= (boot-seed-label => binary-data) 2358 $$Claims-Set-Claims //= (odometer-label => uint) 2360 $$Claims-Set-Claims //= ( intended-use-label => intended-use-type ) 2362 intended-use-type = generic / 2363 registration / 2364 provisioning / 2365 csr / 2366 pop 2368 generic = JC< "generic", 1 > 2369 registration = JC< "registration", 2 > 2370 provisioning = JC< "provisioning", 3 > 2371 csr = JC< "csr", 4 > 2372 pop = JC< "pop", 5 > 2374 $$Claims-Set-Claims //= ( 2375 dloas-label => [ + dloa-type ] 2376 ) 2378 dloa-type = [ 2379 dloa_registrar: general-uri 2380 dloa_platform_label: text 2381 ? dloa_application_label: text 2382 ] 2384 $$Claims-Set-Claims //= (profile-label => general-uri / general-oid) 2385 $$Claims-Set-Claims //= ( 2386 manifests-label => manifests-type 2387 ) 2389 manifests-type = [+ manifest-format] 2391 manifest-format = [ 2392 content-type: uint, 2393 content-format: JC< $$manifest-body-json, 2394 $$manifest-body-cbor > 2395 ] 2397 $$manifest-body-cbor /= bytes .cbor untagged-coswid 2398 $$manifest-body-json /= base64-url-text 2400 $$manifest-body-cbor /= bytes .cbor SUIT_Envelope 2401 $$manifest-body-json /= base64-url-text 2403 suit-directive-process-dependency = 19 2405 $$Claims-Set-Claims //= ( 2406 swevidence-label => swevidence-type 2407 ) 2409 swevidence-type = [+ swevidence-format] 2411 swevidence-format = [ 2412 content-type: uint, 2413 content-format: JC< $$swevidence-body-json, 2414 $$swevidence-body-cbor > 2415 ] 2417 $$swevidence-body-cbor /= bytes .cbor untagged-coswid 2418 $$swevidence-body-json /= base64-url-text 2420 $$Claims-Set-Claims //= ( 2421 measurement-results-label => 2422 [ + measurement-results-group ] ) 2424 measurement-results-group = [ 2425 measurement-system: tstr, 2426 measruement-results: [ + individual-result ] 2427 ] 2429 individual-result = [ 2430 results-id: tstr / binary-data, 2431 result: result-type, 2433 ] 2435 result-type = comparison-successful / 2436 comparison-fail / 2437 comparison-not-run / 2438 measurement-absent 2440 comparison-successful = JC< "success", 1 > 2441 comparison-fail = JC< "fail", 2 > 2442 comparison-not-run = JC< "not-run", 3 > 2443 measurement-absent = JC< "absent", 4 > 2445 $$Claims-Set-Claims //= (submods-label => { + text => Submodule }) 2447 Submodule = Claims-Set / Nested-Token / Detached-Submodule-Digest 2449 Detached-Submodule-Digest = [ 2450 algorithm : JC< text, int > 2451 digest : binary-data 2452 ] 2454 DEB-Messages = DEB-Tagged-Message / DEB-Untagged-Message 2456 DEB-Tagged-Message = #6.TBD(DEB-Untagged-Message) 2457 DEB-Untagged-Message = Detached-EAT-Bundle 2459 Detached-EAT-Bundle = [ 2460 main-token : Nested-Token, 2461 detached-claims-sets: { 2462 + tstr => JC 2464 } 2465 ] 2467 json-wrapped-claims-set = base64-url-text 2469 cbor-wrapped-claims-set = bstr .cbor Claims-Set 2471 nonce-label = JC< "eat_nonce", 10 > 2472 ueid-label = JC< "ueid", 256 > 2473 sueids-label = JC< "sueids", 257 > 2474 oemid-label = JC< "oemid", 258 > 2475 hardware-model-label = JC< "hwmodel", 259 > 2476 hardware-version-label = JC< "hwvers", 260 > 2477 secure-boot-label = JC< "secboot", 262 > 2478 debug-status-label = JC< "dbgstat", 263 > 2479 location-label = JC< "location", 264 > 2480 profile-label = JC< "eat_profile",265 > 2481 submods-label = JC< "submods", 266 > 2483 security-level-label = JC< "seclevel", TBD > 2484 uptime-label = JC< "uptime", TBD > 2485 boot-seed-label = JC< "bootseed", TBD > 2486 intended-use-label = JC< "intuse", TBD > 2487 dloas-label = JC< "dloas", TBD > 2488 sw-name-label = JC< "swname", TBD > 2489 sw-version-label = JC< "swversion", TBD > 2490 manifests-label = JC< "manifests", TBD > 2491 swevidence-label = JC< "swevidence", TBD > 2492 measurement-results-label = JC< "measres" , TBD > 2493 odometer-label = JC< "odometer", TBD > 2495 8.4.2. CBOR-Specific CDDL 2497 EAT-CBOR-Token = $$EAT-CBOR-Tagged-Token / $$EAT-CBOR-Untagged-Token 2499 $$EAT-CBOR-Tagged-Token /= CWT-Tagged-Message 2500 $$EAT-CBOR-Tagged-Token /= DEB-Tagged-Message 2502 $$EAT-CBOR-Untagged-Token /= CWT-Untagged-Message 2503 $$EAT-CBOR-Untagged-Token /= DEB-Untagged-Message 2505 Nested-Token = CBOR-Nested-Token 2507 CBOR-Nested-Token = 2508 JSON-Token-Inside-CBOR-Token / 2509 CBOR-Token-Inside-CBOR-Token 2511 CBOR-Token-Inside-CBOR-Token = bstr .cbor $$EAT-CBOR-Tagged-Token 2513 JSON-Token-Inside-CBOR-Token = tstr 2515 8.4.3. JSON-Specific CDDL 2517 EAT-JSON-Token = $$EAT-JSON-Token-Formats 2519 $$EAT-JSON-Token-Formats /= JWT-Message 2520 $$EAT-JSON-Token-Formats /= DEB-Untagged-Message 2522 Nested-Token = JSON-Nested-Token 2524 JSON-Nested-Token = [ 2525 type : "JWT" / "CBOR" / "DEB", 2526 nested-token : JWT-Message / 2527 CBOR-Token-Inside-JSON-Token / 2528 Detached-EAT-Bundle 2529 ] 2531 CBOR-Token-Inside-JSON-Token = base64-url-text 2533 9. IANA Considerations 2535 9.1. Reuse of CBOR and JSON Web Token (CWT and JWT) Claims Registries 2537 Claims defined for EAT are compatible with those of CWT and JWT so 2538 the CWT and JWT Claims Registries, [IANA.CWT.Claims] and 2539 [IANA.JWT.Claims], are re used. No new IANA registry is created. 2541 All EAT claims defined in this document are placed in both 2542 registries. All new EAT claims defined subsequently should be placed 2543 in both registries. 2545 9.2. Claim Characteristics 2547 The following is design guidance for creating new EAT claims, 2548 particularly those to be registered with IANA. 2550 Much of this guidance is generic and could also be considered when 2551 designing new CWT or JWT claims. 2553 9.2.1. Interoperability and Relying Party Orientation 2555 It is a broad goal that EATs can be processed by Relying Parties in a 2556 general way regardless of the type, manufacturer or technology of the 2557 device from which they originate. It is a goal that there be 2558 general-purpose verification implementations that can verify tokens 2559 for large numbers of use cases with special cases and configurations 2560 for different device types. This is a goal of interoperability of 2561 the semantics of claims themselves, not just of the signing, encoding 2562 and serialization formats. 2564 This is a lofty goal and difficult to achieve broadly requiring 2565 careful definition of claims in a technology neutral way. Sometimes 2566 it will be difficult to design a claim that can represent the 2567 semantics of data from very different device types. However, the 2568 goal remains even when difficult. 2570 9.2.2. Operating System and Technology Neutral 2572 Claims should be defined such that they are not specific to an 2573 operating system. They should be applicable to multiple large high- 2574 level operating systems from different vendors. They should also be 2575 applicable to multiple small embedded operating systems from multiple 2576 vendors and everything in between. 2578 Claims should not be defined such that they are specific to a SW 2579 environment or programming language. 2581 Claims should not be defined such that they are specific to a chip or 2582 particular hardware. For example, they should not just be the 2583 contents of some HW status register as it is unlikely that the same 2584 HW status register with the same bits exists on a chip of a different 2585 manufacturer. 2587 The boot and debug state claims in this document are an example of a 2588 claim that has been defined in this neutral way. 2590 9.2.3. Security Level Neutral 2592 Many use cases will have EATs generated by some of the most secure 2593 hardware and software that exists. Secure Elements and smart cards 2594 are examples of this. However, EAT is intended for use in low- 2595 security use cases the same as high-security use case. For example, 2596 an app on a mobile device may generate EATs on its own. 2598 Claims should be defined and registered on the basis of whether they 2599 are useful and interoperable, not based on security level. In 2600 particular, there should be no exclusion of claims because they are 2601 just used only in low-security environments. 2603 9.2.4. Reuse of Extant Data Formats 2605 Where possible, claims should use already standardized data items, 2606 identifiers and formats. This takes advantage of the expertise put 2607 into creating those formats and improves interoperability. 2609 Often extant claims will not be defined in an encoding or 2610 serialization format used by EAT. It is preferred to define a CBOR 2611 and JSON format for them so that EAT implementations do not require a 2612 plethora of encoders and decoders for serialization formats. 2614 In some cases, it may be better to use the encoding and serialization 2615 as is. For example, signed X.509 certificates and CRLs can be 2616 carried as-is in a byte string. This retains interoperability with 2617 the extensive infrastructure for creating and processing X.509 2618 certificates and CRLs. 2620 9.2.5. Proprietary Claims 2622 EAT allows the definition and use of proprietary claims. 2624 For example, a device manufacturer may generate a token with 2625 proprietary claims intended only for verification by a service 2626 offered by that device manufacturer. This is a supported use case. 2628 In many cases proprietary claims will be the easiest and most obvious 2629 way to proceed, however for better interoperability, use of general 2630 standardized claims is preferred. 2632 9.3. Claims Registered by This Document 2634 This specification adds the following values to the "JSON Web Token 2635 Claims" registry established by [RFC7519] and the "CBOR Web Token 2636 Claims Registry" established by [RFC8392]. Each entry below is an 2637 addition to both registries (except for the nonce claim which is 2638 already registered for JWT, but not registered for CWT). 2640 The "Claim Description", "Change Controller" and "Specification 2641 Documents" are common and equivalent for the JWT and CWT registries. 2642 The "Claim Key" and "Claim Value Types(s)" are for the CWT registry 2643 only. The "Claim Name" is as defined for the CWT registry, not the 2644 JWT registry. The "JWT Claim Name" is equivalent to the "Claim Name" 2645 in the JWT registry. 2647 9.3.1. Claims for Early Assignment 2649 RFC Editor: in the final publication this section should be combined 2650 with the following section as it will no longer be necessary to 2651 distinguish claims with early assignment. Also, the following 2652 paragraph should be removed. 2654 The claims in this section have been (requested for / given) early 2655 assignment according to [RFC7120]. They have been assigned values 2656 and registered before final publication of this document. While 2657 their semantics is not expected to change in final publication, it is 2658 possible that they will. The JWT Claim Names and CWT Claim Keys are 2659 not expected to change. 2661 In draft -06 an early allocation was described. The processing of 2662 that early allocation was never correctly completed. This early 2663 allocation assigns different numbers for the CBOR claim labels. This 2664 early allocation will presumably complete correctly 2666 o Claim Name: Nonce 2668 o Claim Description: Nonce 2670 o JWT Claim Name: "nonce" (already registered for JWT) 2672 o Claim Key: TBD (requested value 10) 2674 o Claim Value Type(s): byte string 2676 o Change Controller: IESG 2678 o Specification Document(s): [OpenIDConnectCore], *this document* 2680 o Claim Name: UEID 2682 o Claim Description: The Universal Entity ID 2684 o JWT Claim Name: "ueid" 2686 o CWT Claim Key: TBD (requested value 256) 2688 o Claim Value Type(s): byte string 2690 o Change Controller: IESG 2692 o Specification Document(s): *this document* 2694 o Claim Name: SUEIDs 2696 o Claim Description: Semi-permanent UEIDs 2698 o JWT Claim Name: "sueids" 2700 o CWT Claim Key: TBD (requested value 257) 2702 o Claim Value Type(s): map 2704 o Change Controller: IESG 2705 o Specification Document(s): *this document* 2707 o Claim Name: Hardware OEMID 2709 o Claim Description: Hardware OEM ID 2711 o JWT Claim Name: "oemid" 2713 o Claim Key: TBD (requeste value 258) 2715 o Claim Value Type(s): byte string or integer 2717 o Change Controller: IESG 2719 o Specification Document(s): *this document* 2721 o Claim Name: Hardware Model 2723 o Claim Description: Model identifier for hardware 2725 o JWT Claim Name: "hwmodel" 2727 o Claim Key: TBD (requested value 259) 2729 o Claim Value Type(s): byte string 2731 o Change Controller: IESG 2733 o Specification Document(s): *this document* 2735 o Claim Name: Hardware Version 2737 o Claim Description: Hardware Version Identifier 2739 o JWT Claim Name: "hwversion" 2741 o Claim Key: TBD (requested value 260) 2743 o Claim Value Type(s): array 2745 o Change Controller: IESG 2747 o Specification Document(s): *this document* 2749 o Claim Name: Secure Boot 2751 o Claim Description: Indicate whether the boot was secure 2752 o JWT Claim Name: "secboot" 2754 o Claim Key: 262 2756 o Claim Value Type(s): Boolean 2758 o Change Controller: IESG 2760 o Specification Document(s): *this document* 2762 o Claim Name: Debug Status 2764 o Claim Description: Indicate status of debug facilities 2766 o JWT Claim Name: "dbgstat" 2768 o Claim Key: 263 2770 o Claim Value Type(s): integer or string 2772 o Change Controller: IESG 2774 o Specification Document(s): *this document* 2776 o Claim Name: Location 2778 o Claim Description: The geographic location 2780 o JWT Claim Name: "location" 2782 o Claim Key: TBD (requested value 264) 2784 o Claim Value Type(s): map 2786 o Change Controller: IESG 2788 o Specification Document(s): *this document* 2790 o Claim Name: Profile 2792 o Claim Description: Indicates the EAT profile followed 2794 o JWT Claim Name: "eat_profile" 2796 o Claim Key: TBD (requested value 265) 2798 o Claim Value Type(s): URI or OID 2799 o Change Controller: IESG 2801 o Specification Document(s): *this document* 2803 o Claim Name: Submodules Section 2805 o Claim Description: The section containing submodules 2807 o JWT Claim Name: "submods" 2809 o Claim Key: TBD (requested value 266) 2811 o Claim Value Type(s): map 2813 o Change Controller: IESG 2815 o Specification Document(s): *this document* 2817 9.3.2. To be Assigned Claims 2819 (Early assignment is NOT requested for these claims. Implementers 2820 should be aware they may change) 2822 o Claim Name: Security Level 2824 o Claim Description: Characterization of the security of an Attester 2825 or submodule 2827 o JWT Claim Name: "seclevel" 2829 o Claim Key: TBD 2831 o Claim Value Type(s): integer or string 2833 o Change Controller: IESG 2835 o Specification Document(s): *this document* 2837 o Claim Name: Uptime 2839 o Claim Description: Uptime 2841 o JWT Claim Name: "uptime" 2843 o Claim Key: TBD 2845 o Claim Value Type(s): unsigned integer 2846 o Change Controller: IESG 2848 o Specification Document(s): *this document* 2850 o Claim Name: Boot Seed 2852 o Claim Description: Identifies a boot cycle 2854 o JWT Claim Name: "bootseed" 2856 o Claim Key: TBD 2858 o Claim Value Type(s): bytes 2860 o Change Controller: IESG 2862 o Specification Document(s): *this document* 2864 o Claim Name: Intended Use 2866 o Claim Description: Indicates intended use of the EAT 2868 o JWT Claim Name: "intuse" 2870 o Claim Key: TBD 2872 o Claim Value Type(s): integer or string 2874 o Change Controller: IESG 2876 o Specification Document(s): *this document* 2878 o Claim Name: DLOAs 2880 o Claim Description: Certifications received as Digital Letters of 2881 Approval 2883 o JWT Claim Name: "dloas" 2885 o Claim Key: TBD 2887 o Claim Value Type(s): array 2889 o Change Controller: IESG 2891 o Specification Document(s): *this document* 2893 o Claim Name: SW Name 2894 o Claim Description: The name of the SW running in the entity 2896 o JWT Claim Name: "swname" 2898 o Claim Key: TBD 2900 o Claim Value Type(s): map 2902 o Change Controller: IESG 2904 o Specification Document(s): *this document* 2906 o Claim Name: SW Version 2908 o Claim Description: The version of SW running in the entity 2910 o JWT Claim Name: "swversion" 2912 o Claim Key: TBD 2914 o Claim Value Type(s): map 2916 o Change Controller: IESG 2918 o Specification Document(s): *this document* 2920 o Claim Name: SW Manifests 2922 o Claim Description: Manifests describing the SW installed on the 2923 entity 2925 o JWT Claim Name: "manifests" 2927 o Claim Key: TBD 2929 o Claim Value Type(s): array 2931 o Change Controller: IESG 2933 o Specification Document(s): *this document* 2935 o Claim Name: SW Evidence 2937 o Claim Description: Measurements of the SW, memory configuration 2938 and such on the entity 2940 o JWT Claim Name: "swevidence" 2941 o Claim Key: TBD 2943 o Claim Value Type(s): array 2945 o Change Controller: IESG 2947 o Specification Document(s): *this document* 2949 o Claim Name: SW Measurment Results 2951 o Claim Description: The results of comparing SW measurements to 2952 reference values 2954 o JWT Claim Name: "swresults" 2956 o Claim Key: TBD 2958 o Claim Value Type(s): array 2960 o Change Controller: IESG 2962 o Specification Document(s): *this document* 2964 9.3.3. Version Schemes Registered by this Document 2966 IANA is requested to register a new value in the "Software Tag 2967 Version Scheme Values" established by [CoSWID]. 2969 The new value is a version scheme a 13-digit European Article Number 2970 [EAN-13]. An EAN-13 is also known as an International Article Number 2971 or most commonly as a bar code. This version scheme is the ASCII 2972 text representation of EAN-13 digits, the same ones often printed 2973 with a bar code. This version scheme must comply with the EAN 2974 allocation and assignment rules. For example, this requires the 2975 manufacturer to obtain a manufacture code from GS1. 2977 +-------+---------------------+---------------+ 2978 | Index | Version Scheme Name | Specification | 2979 +-------+---------------------+---------------+ 2980 | 5 | ean-13 | This document | 2981 +-------+---------------------+---------------+ 2983 9.3.4. UEID URN Registered by this Document 2985 IANA is requested to register the following new subtypes in the "DEV 2986 URN Subtypes" registry under "Device Identification". See [RFC9039]. 2988 +---------+-----------------------------------------+---------------+ 2989 | Subtype | Description | Reference | 2990 +---------+-----------------------------------------+---------------+ 2991 | ueid | Universal Entity Identifier | This document | 2992 | sueid | Semi-permanent Universal Entity | This document | 2993 | | Identifier | | 2994 +---------+-----------------------------------------+---------------+ 2996 9.3.5. Tag for Detached EAT Bundle 2998 In the registry [IANA.cbor-tags], IANA is requested to allocate the 2999 following tag from the FCFS space, with the present document as the 3000 specification reference. 3002 +--------+------------+-------------------------------+ 3003 | Tag | Data Items | Semantics | 3004 +--------+------------+-------------------------------+ 3005 | TBD602 | array | Detached EAT Bundle Section 5 | 3006 +--------+------------+-------------------------------+ 3008 10. Privacy Considerations 3010 Certain EAT claims can be used to track the owner of an entity and 3011 therefore, implementations should consider providing privacy- 3012 preserving options dependent on the intended usage of the EAT. 3013 Examples would include suppression of location claims for EAT's 3014 provided to unauthenticated consumers. 3016 10.1. UEID and SUEID Privacy Considerations 3018 A UEID is usually not privacy-preserving. Any set of Relying Parties 3019 that receives tokens that happen to be from a particular entity will 3020 be able to know the tokens are all from the same entity and be able 3021 to track it. 3023 Thus, in many usage situations UEID violates governmental privacy 3024 regulation. In other usage situations a UEID will not be allowed for 3025 certain products like browsers that give privacy for the end user. 3026 It will often be the case that tokens will not have a UEID for these 3027 reasons. 3029 An SUEID is also usually not privacy-preserving. In some cases it 3030 may have fewer privacy issues than a UEID depending on when and how 3031 and when it is generated. 3033 There are several strategies that can be used to still be able to put 3034 UEIDs and SUEIDs in tokens: 3036 o The entity obtains explicit permission from the user of the entity 3037 to use the UEID/SUEID. This may be through a prompt. It may also 3038 be through a license agreement. For example, agreements for some 3039 online banking and brokerage services might already cover use of a 3040 UEID/SUEID. 3042 o The UEID/SUEID is used only in a particular context or particular 3043 use case. It is used only by one Relying Party. 3045 o The entity authenticates the Relying Party and generates a derived 3046 UEID/SUEID just for that particular Relying Party. For example, 3047 the Relying Party could prove their identity cryptographically to 3048 the entity, then the entity generates a UEID just for that Relying 3049 Party by hashing a proofed Relying Party ID with the main entity 3050 UEID/SUEID. 3052 Note that some of these privacy preservation strategies result in 3053 multiple UEIDs and SUEIDs per entity. Each UEID/SUEID is used in a 3054 different context, use case or system on the entity. However, from 3055 the view of the Relying Party, there is just one UEID and it is still 3056 globally universal across manufacturers. 3058 10.2. Location Privacy Considerations 3060 Geographic location is most always considered personally identifiable 3061 information. Implementers should consider laws and regulations 3062 governing the transmission of location data from end user devices to 3063 servers and services. Implementers should consider using location 3064 management facilities offered by the operating system on the entity 3065 generating the attestation. For example, many mobile phones prompt 3066 the user for permission when before sending location data. 3068 10.3. Replay Protection and Privacy 3070 EAT offers 2 primary mechanisms for token replay protection (also 3071 sometimes known as token "freshness"): the cti/jti claim and the 3072 nonce claim. The cti/jti claim in a CWT/JWT is a field that may be 3073 optionally included in the EAT and is in general derived on the same 3074 device in which the entity is instantiated. The nonce claim is based 3075 on a value that is usually derived remotely (outside of the entity). 3076 These claims can be used to extract and convey personally-identifying 3077 information either inadvertently or by intention. For instance, an 3078 implementor may choose a cti that is equivalent to a username 3079 associated with the device (e.g., account login). If the token is 3080 inspected by a 3rd-party then this information could be used to 3081 identify the source of the token or an account associated with the 3082 token (e.g., if the account name is used to derive the nonce). In 3083 order to avoid the conveyance of privacy-related information in 3084 either the cti/jti or nonce claims, these fields should be derived 3085 using a salt that originates from a true and reliable random number 3086 generator or any other source of randomness that would still meet the 3087 target system requirements for replay protection. 3089 11. Security Considerations 3091 The security considerations provided in Section 8 of [RFC8392] and 3092 Section 11 of [RFC7519] apply to EAT in its CWT and JWT form, 3093 respectively. In addition, implementors should consider the 3094 following. 3096 11.1. Key Provisioning 3098 Private key material can be used to sign and/or encrypt the EAT, or 3099 can be used to derive the keys used for signing and/or encryption. 3100 In some instances, the manufacturer of the entity may create the key 3101 material separately and provision the key material in the entity 3102 itself. The manfuacturer of any entity that is capable of producing 3103 an EAT should take care to ensure that any private key material be 3104 suitably protected prior to provisioning the key material in the 3105 entity itself. This can require creation of key material in an 3106 enclave (see [RFC4949] for definition of "enclave"), secure 3107 transmission of the key material from the enclave to the entity using 3108 an appropriate protocol, and persistence of the private key material 3109 in some form of secure storage to which (preferably) only the entity 3110 has access. 3112 11.1.1. Transmission of Key Material 3114 Regarding transmission of key material from the enclave to the 3115 entity, the key material may pass through one or more intermediaries. 3116 Therefore some form of protection ("key wrapping") may be necessary. 3117 The transmission itself may be performed electronically, but can also 3118 be done by human courier. In the latter case, there should be 3119 minimal to no exposure of the key material to the human (e.g. 3120 encrypted portable memory). Moreover, the human should transport the 3121 key material directly from the secure enclave where it was created to 3122 a destination secure enclave where it can be provisioned. 3124 11.2. Transport Security 3126 As stated in Section 8 of [RFC8392], "The security of the CWT relies 3127 upon on the protections offered by COSE". Similar considerations 3128 apply to EAT when sent as a CWT. However, EAT introduces the concept 3129 of a nonce to protect against replay. Since an EAT may be created by 3130 an entity that may not support the same type of transport security as 3131 the consumer of the EAT, intermediaries may be required to bridge 3132 communications between the entity and consumer. As a result, it is 3133 RECOMMENDED that both the consumer create a nonce, and the entity 3134 leverage the nonce along with COSE mechanisms for encryption and/or 3135 signing to create the EAT. 3137 Similar considerations apply to the use of EAT as a JWT. Although 3138 the security of a JWT leverages the JSON Web Encryption (JWE) and 3139 JSON Web Signature (JWS) specifications, it is still recommended to 3140 make use of the EAT nonce. 3142 11.3. Multiple EAT Consumers 3144 In many cases, more than one EAT consumer may be required to fully 3145 verify the entity attestation. Examples include individual consumers 3146 for nested EATs, or consumers for individual claims with an EAT. 3147 When multiple consumers are required for verification of an EAT, it 3148 is important to minimize information exposure to each consumer. In 3149 addition, the communication between multiple consumers should be 3150 secure. 3152 For instance, consider the example of an encrypted and signed EAT 3153 with multiple claims. A consumer may receive the EAT (denoted as the 3154 "receiving consumer"), decrypt its payload, verify its signature, but 3155 then pass specific subsets of claims to other consumers for 3156 evaluation ("downstream consumers"). Since any COSE encryption will 3157 be removed by the receiving consumer, the communication of claim 3158 subsets to any downstream consumer should leverage a secure protocol 3159 (e.g.one that uses transport-layer security, i.e. TLS), 3161 However, assume the EAT of the previous example is hierarchical and 3162 each claim subset for a downstream consumer is created in the form of 3163 a nested EAT. Then transport security between the receiving and 3164 downstream consumers is not strictly required. Nevertheless, 3165 downstream consumers of a nested EAT should provide a nonce unique to 3166 the EAT they are consuming. 3168 12. References 3170 12.1. Normative References 3172 [CoSWID] Birkholz, H., Fitzgerald-McKay, J., Schmidt, C., and D. 3173 Waltermire, "Concise Software Identification Tags", draft- 3174 ietf-sacm-coswid-21 (work in progress), March 2022. 3176 [DLOA] "Digital Letter of Approval", November 2015, 3177 . 3180 [EAN-13] GS1, "International Article Number - EAN/UPC barcodes", 3181 2019, . 3183 [FIDO.AROE] 3184 The FIDO Alliance, "FIDO Authenticator Allowed Restricted 3185 Operating Environments List", November 2020, 3186 . 3190 [IANA.cbor-tags] 3191 "IANA CBOR Tags Registry", n.d., 3192 . 3195 [IANA.CWT.Claims] 3196 IANA, "CBOR Web Token (CWT) Claims", 3197 . 3199 [IANA.JWT.Claims] 3200 IANA, "JSON Web Token (JWT) Claims", 3201 . 3203 [OpenIDConnectCore] 3204 Sakimura, N., Bradley, J., Jones, M., Medeiros, B. D., and 3205 C. Mortimore, "OpenID Connect Core 1.0 incorporating 3206 errata set 1", November 2014, 3207 . 3209 [PEN] "Private Enterprise Number (PEN) Request", n.d., 3210 . 3212 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3213 Requirement Levels", BCP 14, RFC 2119, 3214 DOI 10.17487/RFC2119, March 1997, 3215 . 3217 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3218 Resource Identifier (URI): Generic Syntax", STD 66, 3219 RFC 3986, DOI 10.17487/RFC3986, January 2005, 3220 . 3222 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 3223 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 3224 2014, . 3226 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 3227 Application Protocol (CoAP)", RFC 7252, 3228 DOI 10.17487/RFC7252, June 2014, 3229 . 3231 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 3232 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 3233 2015, . 3235 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 3236 RFC 7516, DOI 10.17487/RFC7516, May 2015, 3237 . 3239 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 3240 DOI 10.17487/RFC7517, May 2015, 3241 . 3243 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 3244 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 3245 . 3247 [RFC7800] Jones, M., Bradley, J., and H. Tschofenig, "Proof-of- 3248 Possession Key Semantics for JSON Web Tokens (JWTs)", 3249 RFC 7800, DOI 10.17487/RFC7800, April 2016, 3250 . 3252 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 3253 Writing an IANA Considerations Section in RFCs", BCP 26, 3254 RFC 8126, DOI 10.17487/RFC8126, June 2017, 3255 . 3257 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 3258 RFC 8152, DOI 10.17487/RFC8152, July 2017, 3259 . 3261 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 3262 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 3263 May 2017, . 3265 [RFC8392] Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, 3266 "CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392, 3267 May 2018, . 3269 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 3270 Definition Language (CDDL): A Notational Convention to 3271 Express Concise Binary Object Representation (CBOR) and 3272 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 3273 June 2019, . 3275 [RFC8747] Jones, M., Seitz, L., Selander, G., Erdtman, S., and H. 3276 Tschofenig, "Proof-of-Possession Key Semantics for CBOR 3277 Web Tokens (CWTs)", RFC 8747, DOI 10.17487/RFC8747, March 3278 2020, . 3280 [RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object 3281 Representation (CBOR)", STD 94, RFC 8949, 3282 DOI 10.17487/RFC8949, December 2020, 3283 . 3285 [RFC9090] Bormann, C., "Concise Binary Object Representation (CBOR) 3286 Tags for Object Identifiers", RFC 9090, 3287 DOI 10.17487/RFC9090, July 2021, 3288 . 3290 [ThreeGPP.IMEI] 3291 3GPP, "3rd Generation Partnership Project; Technical 3292 Specification Group Core Network and Terminals; Numbering, 3293 addressing and identification", 2019, 3294 . 3297 [WGS84] National Geospatial-Intelligence Agency (NGA), "WORLD 3298 GEODETIC SYSTEM 1984, NGA.STND.0036_1.0.0_WGS84", July 3299 2014, . 3302 12.2. Informative References 3304 [BirthdayAttack] 3305 "Birthday attack", 3306 . 3308 [CBOR.Cert.Draft] 3309 Mattsson, J. P., Selander, G., Raza, S., Hoeglund, J., and 3310 M. Furuhed, "CBOR Encoded X.509 Certificates (C509 3311 Certificates)", draft-ietf-cose-cbor-encoded-cert-03 (work 3312 in progress), January 2022. 3314 [Common.Criteria] 3315 "Common Criteria for Information Technology Security 3316 Evaluation", April 2017, 3317 . 3319 [COSE.X509.Draft] 3320 Schaad, J., "CBOR Object Signing and Encryption (COSE): 3321 Header parameters for carrying and referencing X.509 3322 certificates", draft-ietf-cose-x509-08 (work in progress), 3323 December 2020. 3325 [FIPS-140] 3326 National Institue of Standards, "Security Requirements for 3327 Cryptographic Modules", May 2001, 3328 . 3331 [IEEE.802-2001] 3332 "IEEE Standard For Local And Metropolitan Area Networks 3333 Overview And Architecture", 2007, 3334 . 3337 [IEEE.802.1AR] 3338 "IEEE Standard, "IEEE 802.1AR Secure Device Identifier"", 3339 December 2009, . 3342 [IEEE.RA] "IEEE Registration Authority", 3343 . 3346 [OUI.Guide] 3347 "Guidelines for Use of Extended Unique Identifier (EUI), 3348 Organizationally Unique Identifier (OUI), and Company ID 3349 (CID)", August 2017, 3350 . 3353 [OUI.Lookup] 3354 "IEEE Registration Authority Assignments", 3355 . 3358 [RATS.Architecture] 3359 Birkholz, H., Thaler, D., Richardson, M., Smith, N., and 3360 W. Pan, "Remote Attestation Procedures Architecture", 3361 draft-ietf-rats-architecture-15 (work in progress), 3362 February 2022. 3364 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 3365 Unique IDentifier (UUID) URN Namespace", RFC 4122, 3366 DOI 10.17487/RFC4122, July 2005, 3367 . 3369 [RFC4422] Melnikov, A., Ed. and K. Zeilenga, Ed., "Simple 3370 Authentication and Security Layer (SASL)", RFC 4422, 3371 DOI 10.17487/RFC4422, June 2006, 3372 . 3374 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 3375 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 3376 . 3378 [RFC7120] Cotton, M., "Early IANA Allocation of Standards Track Code 3379 Points", BCP 100, RFC 7120, DOI 10.17487/RFC7120, January 3380 2014, . 3382 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 3383 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 3384 . 3386 [RFC9039] Arkko, J., Jennings, C., and Z. Shelby, "Uniform Resource 3387 Names for Device Identifiers", RFC 9039, 3388 DOI 10.17487/RFC9039, June 2021, 3389 . 3391 [W3C.GeoLoc] 3392 Worldwide Web Consortium, "Geolocation API Specification 3393 2nd Edition", January 2018, . 3396 Appendix A. Examples 3398 Most examples are shown as just a Claims-Set that would be a payload 3399 for a CWT, JWT, DEB or future token types. It is shown this way 3400 because the payload is all the claims, the most interesting part and 3401 showing full tokens makes it harder to show the claims. 3403 Some examples of full tokens are also given. 3405 WARNING: These examples use tag and label numbers not yet assigned by 3406 IANA. 3408 A.1. Payload Examples 3410 A.1.1. Simple TEE Attestation 3412 This is a simple attestation of a TEE that includes a manifest that 3413 is a payload CoSWID to describe the TEE's software. 3415 / This is an EAT payload that describes a simple TEE. / 3417 { 3418 / nonce / 10: h'948f8860d13a463e', 3419 / security-level / 261: 2, / restricted / 3420 / secure-boot / 262: true, 3421 / debug-status / 263: 2, / disabled-since-boot / 3422 / manfests / 273: [ 3423 [ 3424 121, / CoAP Content ID. A / 3425 / made up one until one / 3426 / is assigned for CoSWID / 3428 / This is byte-string wrapped / 3429 / payload CoSWID. It gives the TEE / 3430 / software name, the version and / 3431 / the name of the file it is in. / 3432 / {0: "3a24", / 3433 / 12: 1, / 3434 / 1: "Acme TEE OS", / 3435 / 13: "3.1.4", / 3436 / 2: [{31: "Acme TEE OS", 33: 1}, / 3437 / {31: "Acme TEE OS", 33: 2}], / 3438 / 6: { / 3439 / 17: { / 3440 / 24: "acme_tee_3.exe" / 3441 / } / 3442 / } / 3443 / } / 3444 h' a60064336132340c01016b 3445 41636d6520544545204f530d65332e31 3446 2e340282a2181f6b41636d6520544545 3447 204f53182101a2181f6b41636d652054 3448 4545204f5318210206a111a118186e61 3449 636d655f7465655f332e657865' 3450 ] 3451 ] 3452 } 3453 / A payload CoSWID created by the SW vendor. All this really does / 3454 / is name the TEE SW, its version and lists the one file that / 3455 / makes up the TEE. / 3457 1398229316({ 3458 / Unique CoSWID ID / 0: "3a24", 3459 / tag-version / 12: 1, 3460 / software-name / 1: "Acme TEE OS", 3461 / software-version / 13: "3.1.4", 3462 / entity / 2: [ 3463 { 3464 / entity-name / 31: "Acme TEE OS", 3465 / role / 33: 1 / tag-creator / 3466 }, 3467 { 3468 / entity-name / 31: "Acme TEE OS", 3469 / role / 33: 2 / software-creator / 3470 } 3471 ], 3472 / payload / 6: { 3473 / ...file / 17: { 3474 / ...fs-name / 24: "acme_tee_3.exe" 3475 } 3476 } 3477 }) 3479 A.1.2. Submodules for Board and Device 3480 / This example shows use of submodules to give information / 3481 / about the chip, board and overall device. / 3482 / / 3483 / The main attestation is associated with the chip with the / 3484 / CPU and running the main OS. It is what has the keys and / 3485 / produces the token. / 3486 / / 3487 / The board is made by a different vendor than the chip. / 3488 / Perhaps it is some generic IoT board. / 3489 / / 3490 / The device is some specific appliance that is made by a / 3491 / different vendor than either the chip or the board. / 3492 / / 3493 / Here the board and device submodules aren't the typical / 3494 / target environments as described by the RATS architecture / 3495 / document, but they are a valid use of submodules. / 3497 { 3498 / nonce / 10: h'948f8860d13a463e8e', 3499 / UEID / 256: h'0198f50a4ff6c05861c8860d13a638ea', 3500 / HW OEM ID / 258: h'894823', / IEEE OUI format OEM ID / 3501 / HW Model ID / 259: h'549dcecc8b987c737b44e40f7c635ce8' 3502 / Hash of chip model name /, 3503 / HW Version / 260: ["1.3.4", 1], / Multipartnumeric version / 3504 / SW Name / 271: "Acme OS", 3505 / SW Version / 272: ["3.5.5", 1], 3506 / secure-boot / 262: true, 3507 / debug-status / 263: 3, / permanent-disable / 3508 / timestamp (iat) / 6: 1526542894, 3509 / security-level / 261: 2, / restricted OS / 3510 / submods / 266: { 3511 / A submodule to hold some claims about the circuit board / 3512 "board" : { 3513 / HW OEM ID / 258: h'9bef8787eba13e2c8f6e7cb4b1f4619a', 3514 / HW Model ID / 259: h'ee80f5a66c1fb9742999a8fdab930893' 3515 / Hash of board module name /, 3516 / HW Version / 260: ["2.0a", 2] / multipartnumeric+suffix / 3517 }, 3519 / A submodule to hold claims about the overall device / 3520 "device" : { 3521 / HW OEM ID / 258: 61234, / PEN Format OEM ID / 3522 / HW Version / 260: ["4012345123456", 5] / EAN-13 format (barcode) / 3523 } 3524 } 3525 } 3526 A.1.3. EAT Produced by Attestation Hardware Block 3528 / This is an example of a token produced by a HW block / 3529 / purpose-built for attestation. Only the nonce claim changes / 3530 / from one attestation to the next as the rest either come / 3531 / directly from the hardware or from one-time-programmable memory / 3532 / (e.g. a fuse). 47 bytes encoded in CBOR (8 byte nonce, 16 byte / 3533 / UEID). / 3535 { 3536 / nonce / 10: h'948f8860d13a463e', 3537 / UEID / 256: h'0198f50a4ff6c05861c8860d13a638ea', 3538 / OEMID / 258: 64242, / Private Enterprise Number / 3539 / security-level / 261: 3, / hardware level security / 3540 / secure-boot / 262: true, 3541 / debug-status / 263: 3, / disabled-permanently / 3542 / HW version / 260: [ "3.1", 1 ] / Type is multipartnumeric / 3543 } 3545 A.1.4. Key / Key Store Attestation 3546 / This is an EAT payload that describes a simple TEE. / 3548 { 3549 / nonce / 10: h'948f8860d13a463e', 3550 / security-level / 261: 2, / restricted / 3551 / secure-boot / 262: true, 3552 / debug-status / 263: 2, / disabled-since-boot / 3553 / manfests / 273: [ 3554 [ 3555 121, / CoAP Content ID. A / 3556 / made up one until one / 3557 / is assigned for CoSWID / 3559 / This is byte-string wrapped / 3560 / payload CoSWID. It gives the TEE / 3561 / software name, the version and / 3562 / the name of the file it is in. / 3563 / {0: "3a24", / 3564 / 12: 1, / 3565 / 1: "Acme TEE OS", / 3566 / 13: "3.1.4", / 3567 / 2: [{31: "Acme TEE OS", 33: 1}, / 3568 / {31: "Acme TEE OS", 33: 2}], / 3569 / 6: { / 3570 / 17: { / 3571 / 24: "acme_tee_3.exe" / 3572 / } / 3573 / } / 3574 / } / 3575 h' a60064336132340c01016b 3576 41636d6520544545204f530d65332e31 3577 2e340282a2181f6b41636d6520544545 3578 204f53182101a2181f6b41636d652054 3579 4545204f5318210206a111a118186e61 3580 636d655f7465655f332e657865' 3581 ] 3582 ] 3583 } 3584 / A payload CoSWID created by the SW vendor. All this really does / 3585 / is name the TEE SW, its version and lists the one file that / 3586 / makes up the TEE. / 3588 1398229316({ 3589 / Unique CoSWID ID / 0: "3a24", 3590 / tag-version / 12: 1, 3591 / software-name / 1: "Acme TEE OS", 3592 / software-version / 13: "3.1.4", 3593 / entity / 2: [ 3594 { 3595 / entity-name / 31: "Acme TEE OS", 3596 / role / 33: 1 / tag-creator / 3597 }, 3598 { 3599 / entity-name / 31: "Acme TEE OS", 3600 / role / 33: 2 / software-creator / 3601 } 3602 ], 3603 / payload / 6: { 3604 / ...file / 17: { 3605 / ...fs-name / 24: "acme_tee_3.exe" 3606 } 3607 } 3608 }) 3610 A.1.5. Submodules for Board and Device 3611 / This example shows use of submodules to give information / 3612 / about the chip, board and overall device. / 3613 / / 3614 / The main attestation is associated with the chip with the / 3615 / CPU and running the main OS. It is what has the keys and / 3616 / produces the token. / 3617 / / 3618 / The board is made by a different vendor than the chip. / 3619 / Perhaps it is some generic IoT board. / 3620 / / 3621 / The device is some specific appliance that is made by a / 3622 / different vendor than either the chip or the board. / 3623 / / 3624 / Here the board and device submodules aren't the typical / 3625 / target environments as described by the RATS architecture / 3626 / document, but they are a valid use of submodules. / 3628 { 3629 / nonce / 10: h'948f8860d13a463e8e', 3630 / UEID / 256: h'0198f50a4ff6c05861c8860d13a638ea', 3631 / HW OEM ID / 258: h'894823', / IEEE OUI format OEM ID / 3632 / HW Model ID / 259: h'549dcecc8b987c737b44e40f7c635ce8' 3633 / Hash of chip model name /, 3634 / HW Version / 260: ["1.3.4", 1], / Multipartnumeric version / 3635 / SW Name / 271: "Acme OS", 3636 / SW Version / 272: ["3.5.5", 1], 3637 / secure-boot / 262: true, 3638 / debug-status / 263: 3, / permanent-disable / 3639 / timestamp (iat) / 6: 1526542894, 3640 / security-level / 261: 2, / restricted OS / 3641 / submods / 266: { 3642 / A submodule to hold some claims about the circuit board / 3643 "board" : { 3644 / HW OEM ID / 258: h'9bef8787eba13e2c8f6e7cb4b1f4619a', 3645 / HW Model ID / 259: h'ee80f5a66c1fb9742999a8fdab930893' 3646 / Hash of board module name /, 3647 / HW Version / 260: ["2.0a", 2] / multipartnumeric+suffix / 3648 }, 3650 / A submodule to hold claims about the overall device / 3651 "device" : { 3652 / HW OEM ID / 258: 61234, / PEN Format OEM ID / 3653 / HW Version / 260: ["4012345123456", 5] / EAN-13 format (barcode) / 3654 } 3655 } 3656 } 3657 A.1.6. EAT Produced by Attestation Hardware Block 3659 / This is an example of a token produced by a HW block / 3660 / purpose-built for attestation. Only the nonce claim changes / 3661 / from one attestation to the next as the rest either come / 3662 / directly from the hardware or from one-time-programmable memory / 3663 / (e.g. a fuse). 47 bytes encoded in CBOR (8 byte nonce, 16 byte / 3664 / UEID). / 3666 { 3667 / nonce / 10: h'948f8860d13a463e', 3668 / UEID / 256: h'0198f50a4ff6c05861c8860d13a638ea', 3669 / OEMID / 258: 64242, / Private Enterprise Number / 3670 / security-level / 261: 3, / hardware level security / 3671 / secure-boot / 262: true, 3672 / debug-status / 263: 3, / disabled-permanently / 3673 / HW version / 260: [ "3.1", 1 ] / Type is multipartnumeric / 3674 } 3676 A.1.7. Key / Key Store Attestation 3678 / This is an attestation of a public key and the key store / 3679 / implementation that protects and manages it. The key store / 3680 / implementation is in a security-oriented execution / 3681 / environment separate from the high-level OS, for example a / 3682 / TEE. The key store is the Attester. / 3683 / / 3684 / There is some attestation of the high-level OS, just version / 3685 / and boot & debug status. It is a Claims-Set submodule because/ 3686 / it has lower security level than the key store. The key / 3687 / store's implementation has access to info about the HLOS, so / 3688 / it is able to include it. / 3689 / / 3690 / A key and an indication of the user authentication given to / 3691 / allow access to the key is given. The labels for these are / 3692 / in the private space since this is just a hypothetical / 3693 / example, not part of a standard protocol. / 3694 / / 3695 / This is similar to Android Key Attestation. / 3697 { 3698 / nonce / 10: h'948f8860d13a463e', 3699 / security-level / 261: 2, / restricted / 3700 / secure-boot / 262: true, 3701 / debug-status / 263: 2, / disabled-since-boot / 3702 / manifests / 273: [ 3704 [ 121, / CoAP Content ID. A / 3705 / made up one until one / 3706 / is assigned for CoSWID / 3707 h'a600683762623334383766 3708 0c000169436172626f6e6974650d6331 3709 2e320e0102a2181f75496e6475737472 3710 69616c204175746f6d6174696f6e1821 3711 02' 3712 ] 3713 / Above is an encoded CoSWID / 3714 / with the following data / 3715 / SW Name: "Carbonite" / 3716 / SW Vers: "1.2" / 3717 / SW Creator: / 3718 / "Industrial Automation" / 3719 ], 3720 / expiration / 4: 1634324274, / 2021-10-15T18:57:54Z / 3721 / creation time / 6: 1634317080, / 2021-10-15T16:58:00Z / 3722 -80000 : "fingerprint", 3723 -80001 : { / The key -- A COSE_Key / 3724 / kty / 1: 2, / EC2, eliptic curve with x & y / 3725 / kid / 2: h'36675c206f96236c3f51f54637b94ced', 3726 / curve / -1: 2, / curve is P-256 / 3727 / x-coord / -2: h'65eda5a12577c2bae829437fe338701a 3728 10aaa375e1bb5b5de108de439c08551d', 3729 / y-coord / -3: h'1e52ed75701163f7f9e40ddf9f341b3d 3730 c9ba860af7e0ca7ca7e9eecd0084d19c' 3731 }, 3733 / submods / 266 : { 3734 "HLOS" : { / submod for high-level OS / 3735 / nonce / 10: h'948f8860d13a463e', 3736 / security-level / 261: 1, / unrestricted / 3737 / secure-boot / 262: true, 3738 / manifests / 273: [ 3739 [ 121, / CoAP Content ID. A / 3740 / made up one until one / 3741 / is assigned for CoSWID / 3742 h'a600687337 3743 6537346b78380c000168 3744 44726f6964204f530d65 3745 52322e44320e0302a218 3746 1F75496E647573747269 3747 616c204175746f6d6174 3748 696f6e182102' 3749 ] 3750 / Above is an encoded CoSWID / 3751 / with the following data: / 3752 / SW Name: "Droid OS" / 3753 / SW Vers: "R2.D2" / 3754 / SW Creator: / 3755 / "Industrial Automation"/ 3756 ] 3757 } 3758 } 3759 } 3761 A.1.8. SW Measurements of an IoT Device 3763 This is a simple token that might be for and IoT device. It includes 3764 CoSWID format measurments of the SW. The CoSWID is in byte-string 3765 wrapped in the token and also shown in diagnostic form. 3767 / This EAT payload is for an IoT device with a TEE. The attestation / 3768 / is produced by the TEE. There is a submodule for the IoT OS (the / 3769 / main OS of the IoT device that is not as secure as the TEE). The / 3770 / submodule contains claims for the IoT OS. The TEE also measures / 3771 / the IoT OS and puts the measurements in the submodule. / 3773 { 3774 / nonce / 10: h'948f8860d13a463e', 3775 / security-level / 261: 2, / restricted / 3776 / secure-boot / 262: true, 3777 / debug-status / 263: 2, / disabled-since-boot / 3778 / OEMID / 258: h'8945ad', / IEEE CID based / 3779 / UEID / 256: h'0198f50a4ff6c05861c8860d13a638ea', 3780 / sumods / 266: { 3781 "OS" : { 3782 / security-level / 261: 2, / restricted / 3783 / secure-boot / 262: true, 3784 / debug-status / 263: 2, / disabled-since-boot / 3785 / swevidence / 274: [ 3786 [ 3787 121, / CoAP Content ID. A / 3788 / made up one until one / 3789 / is assigned for CoSWID / 3791 / This is a byte-string wrapped / 3792 / evidence CoSWID. It has / 3793 / hashes of the main files of / 3794 / the IoT OS. / 3795 h'a600663463613234350c 3796 17016d41636d6520522d496f542d4f 3797 530d65332e312e3402a2181f724163 3798 6d6520426173652041747465737465 3799 7218210103a11183a318187161636d 3800 655f725f696f745f6f732e65786514 3801 1a0044b349078201582005f6b327c1 3802 73b4192bd2c3ec248a292215eab456 3803 611bf7a783e25c1782479905a31818 3804 6d7265736f75726365732e72736314 3805 1a000c38b10782015820c142b9aba4 3806 280c4bb8c75f716a43c99526694caa 3807 be529571f5569bb7dc542f98a31818 3808 6a636f6d6d6f6e2e6c6962141a0023 3809 3d3b0782015820a6a9dcdfb3884da5 3810 f884e4e1e8e8629958c2dbc7027414 3811 43a913e34de9333be6' 3812 ] 3813 ] 3814 } 3815 } 3816 } 3818 / An evidence CoSWID created for the "Acme R-IoT-OS" created by / 3819 / the "Acme Base Attester" (both fictious names). It provides / 3820 / measurements of the SW (other than the attester SW) on the / 3821 / device. / 3823 1398229316({ 3824 / Unique CoSWID ID / 0: "4ca245", 3825 / tag-version / 12: 23, / Attester-maintained counter / 3826 / software-name / 1: "Acme R-IoT-OS", 3827 / software-version / 13: "3.1.4", 3828 / entity / 2: { 3829 / entity-name / 31: "Acme Base Attester", 3830 / role / 33: 1 / tag-creator / 3831 }, 3832 / evidence / 3: { 3833 / ...file / 17: [ 3834 { 3835 / ...fs-name / 24: "acme_r_iot_os.exe", 3836 / ...size / 20: 4502345, 3837 / ...hash / 7: [ 3838 1, / SHA-256 / 3839 h'05f6b327c173b419 3840 2bd2c3ec248a2922 3841 15eab456611bf7a7 3842 83e25c1782479905' 3843 ] 3844 }, 3845 { 3846 / ...fs-name / 24: "resources.rsc", 3847 / ...size / 20: 800945, 3848 / ...hash / 7: [ 3849 1, / SHA-256 / 3850 h'c142b9aba4280c4b 3851 b8c75f716a43c995 3852 26694caabe529571 3853 f5569bb7dc542f98' 3854 ] 3855 }, 3856 { 3857 / ...fs-name / 24: "common.lib", 3858 / ...size / 20: 2309435, 3859 / ...hash / 7: [ 3860 1, / SHA-256 / 3861 h'a6a9dcdfb3884da5 3862 f884e4e1e8e86299 3863 58c2dbc702741443 3864 a913e34de9333be6' 3865 ] 3866 } 3867 ] 3868 } 3869 }) 3871 A.1.9. Attestation Results in JSON format 3873 This is a JSON-format payload that might be the output of a Verifier 3874 that evaluated the IoT Attestation example immediately above. 3876 This particular Verifier knows enough about the TEE Attester to be 3877 able to pass claims like security level directly through to the 3878 Relying Party. The Verifier also knows the Reference Values for the 3879 measured SW components and is able to check them. It informs the 3880 Relying Party that they were correct in the swresults claim. 3881 "Trustus Verifications" is the name of the services that verifies the 3882 SW component measurements. 3884 { 3885 "eat_nonce" : "jkd8KL-8=Qlzg4", 3886 "seclevel" : "restricted", 3887 "secboot" : true, 3888 "dbgstat" : "disabled-since-boot", 3889 "oemid" : "iUWt", 3890 "ueid" : "AZj1Ck_2wFhhyIYNE6Y4", 3891 "swname" : "Acme R-IoT-OS", 3892 "swversion" : [ 3893 "3.1.4" 3894 ], 3895 "measres" : [ 3896 [ 3897 "Trustus Measurements", 3898 [ 3899 [ "all" , "success" ] 3900 ] 3901 ] 3902 ] 3903 } 3905 A.1.10. JSON-encoded Token with Sumodules 3906 { 3907 "eat_nonce": "lI-IYNE6Rj6O", 3908 "ueid": "AJj1Ck_2wFhhyIYNE6Y46g==", 3909 "secboot": true, 3910 "dbgstat": "disabled-permanently", 3911 "iat": 1526542894, 3912 "seclevel": "restricted", 3913 "submods": { 3914 "Android App Foo" : { 3915 "seclevel": "unrestricted" 3916 }, 3918 "Secure Element Eat" : [ 3919 "CBOR", 3920 "2D3ShEOhASagWGaoCkiUj4hg0TpGPhkBAFABmPUKT_bAWGHIhg0TpjjqGQECGfryGQEFBBkBBvUZAQcDGQEEgmMzLjEBGQEKoWNURUWCL1gg5c-V_ST6txRGdC3VjUPa4XjlX-K5QpGpKRCC_8JjWgtYQPaQywOIZ3-mJKN3X9fLxOhAnsmBa-MvpHRzOw-Ywn-67bvJljuctezAPD41s6_At7NbSV3qwJlxIuqGfwe41es=" 3921 ], 3923 "Linux Android": { 3924 "seclevel": "unrestricted" 3925 }, 3927 "Subsystem J": [ 3928 "JWT", 3929 "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJKLUF0dGVzdGVyIiwiaWF0IjoxNjUxNzc0ODY4LCJleHAiOm51bGwsImF1ZCI6IiIsInN1YiI6IiJ9.gjw4nFMhLpJUuPXvMPzK1GMjhyJq2vWXg1416XKszwQ" 3930 ] 3931 } 3932 } 3934 A.2. Full Token Examples 3936 A.2.1. Basic CWT Example 3938 This is a simple ECDSA signed CWT-format token. 3940 / This is a full CWT-format token with a very simple payloal. / 3941 / The main structure visible here is that of the COSE_Sign1. / 3943 61( 18( [ 3944 h'A10126', / protected headers / 3945 {}, / empty unprotected headers / 3946 h'A20B46024A6B0978DE0A49000102030405060708', / payload / 3947 h'9B9B2F5E470000F6A20C8A4157B5763FC45BE759 3948 9A5334028517768C21AFFB845A56AB557E0C8973 3949 A07417391243A79C478562D285612E292C622162 3950 AB233787' / signature / 3951 ] ) ) 3953 A.2.2. Detached EAT Bundle 3955 In this DEB main token is produced by a HW attestation block. The 3956 detached Claims-Set is produced by a TEE and is largely identical to 3957 the Simple TEE examples above. The TEE digests its Claims-Set and 3958 feeds that digest to the HW block. 3960 In a better example the attestation produced by the HW block would be 3961 a CWT and thus signed and secured by the HW block. Since the 3962 signature covers the digest from the TEE that Claims-Set is also 3963 secured. 3965 The DEB itself can be assembled by untrusted SW. 3967 / This is a detached EAT bundle (DEB) tag. / 3968 / Note that 602, the tag identifying a DEB is not yet registered with IANA / 3970 602([ 3972 / First part is a full EAT token with claims like nonce and / 3973 / UEID. Most importantly, it includes a submodule that is a / 3974 / detached digest which is the hash of the "TEE" claims set / 3975 / in the next section. The COSE payload follows: / 3976 / { / 3977 / 10: h'948F8860D13A463E', / 3978 / 256: h'0198F50A4FF6C05861C8860D13A638EA', / 3979 / 258: 64242, / 3980 / 261: 4, / 3981 / 262: true, / 3982 / 263: 3, / 3983 / 260: ["3.1", 1], / 3984 / 266: { / 3985 / "TEE": [ / 3986 / -16, / 3987 / h'E5CF95FD24FAB71446742DD58D43DAE1 / 3988 / 78E55FE2B94291A9291082FFC2635A0B' / 3989 / ] / 3990 / } / 3991 / } / 3992 h'D83DD28443A10126A05866A80A48948F8860D13A463E1901 3993 00500198F50A4FF6C05861C8860D13A638EA19010219FAF2 3994 19010504190106F5190107031901048263332E310119010A 3995 A163544545822F5820E5CF95FD24FAB71446742DD58D43DA 3996 E178E55FE2B94291A9291082FFC2635A0B5840F690CB0388 3997 677FA624A3775FD7CBC4E8409EC9816BE32FA474733B0F98 3998 C27FBAEDBBC9963B9CB5ECC03C3E35B3AFC0B7B35B495DEA 3999 C0997122EA867F07B8D5EB', 4000 { 4001 / A CBOR-encoded byte-string wrapped EAT claims-set. It / 4002 / contains claims suitable for a TEE / 4003 "TEE" : h'a50a48948f8860d13a463e19010503190106 4004 f519010702190111818218795858a6006433 4005 6132340c01016b41636d6520544545204f53 4006 0d65332e312e340282a2181f6b41636d6520 4007 544545204f53182101a2181f6b41636d6520 4008 544545204f5318210206a111a118186e6163 4009 6d655f7465655f332e657865' 4010 } 4011 ]) 4012 / This example contains submodule that is a detached digest, / 4013 / which is the hash of a Claims-Set convey outside this token. / 4014 / Other than that is is the other example of a token from an / 4015 / attestation HW block / 4017 { 4018 / nonce / 10: h'948f8860d13a463e', 4019 / UEID / 256: h'0198f50a4ff6c05861c8860d13a638ea', 4020 / OEMID / 258: 64242, / Private Enterprise Number / 4021 / security-level / 261: 3, / hardware level security / 4022 / secure-boot / 262: true, 4023 / debug-status / 263: 3, / disabled-permanently / 4024 / hw version / 260: [ "3.1", 1 ], / multipartnumeric / 4025 / submods/ 266: { 4026 "TEE": [ / detached digest submod / 4027 -16, / SHA-256 / 4028 h'e5cf95fd24fab7144674 4029 2dd58d43dae178e55fe2 4030 b94291a9291082ffc2635 4031 a0b' 4032 ] 4033 } 4034 } 4036 A.2.3. JSON-encoded Detached EAT Bundle 4038 In this bundle there are two detached Claims-Sets, "CS1" and "CS2". 4039 The JWT at the start of the bundle has detached signature submodules 4040 with hashes of "CS1" and "CS2". TODO: make the JWT actually be 4041 correct verifiable JWT. 4043 [ 4044 [ "JWT", 4045 "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJKLUF0dGVzdGVyIiwiaWF0IjoxNjUxNzc0ODY4LCJleHAiOm51bGwsImF1ZCI6IiIsInN1YiI6IiJ9.gjw4nFMhLpJUuPXvMPzK1GMjhyJq2vWXg1416XKszwQ" 4046 ], 4047 { 4048 "Audio Subsystem Claims": "ewogICAgICAgICAgICAibm9uY2UiOiAgICAgImxJK0lZTkU2Umo2TyIsCiAgICAgICAgICAgICJpYXQiOiAgICAgIDE1MjY1NDI4OTQKICAgICAgICAgfQo=", 4049 "Graphics Subsystem Claims": "ewogICAgICAgICAgICAibm9uY2UiOiAgICJsSStJWU5FNlJqNk8iLAogICAgICAgICAgICAiaWF0IjogICAgIDE1MjY1NDI4OTQKICAgICAgICB9" 4050 } 4051 ] 4053 Appendix B. UEID Design Rationale 4054 B.1. Collision Probability 4056 This calculation is to determine the probability of a collision of 4057 UEIDs given the total possible entity population and the number of 4058 entities in a particular entity management database. 4060 Three different sized databases are considered. The number of 4061 devices per person roughly models non-personal devices such as 4062 traffic lights, devices in stores they shop in, facilities they work 4063 in and so on, even considering individual light bulbs. A device may 4064 have individually attested subsystems, for example parts of a car or 4065 a mobile phone. It is assumed that the largest database will have at 4066 most 10% of the world's population of devices. Note that databases 4067 that handle more than a trillion records exist today. 4069 The trillion-record database size models an easy-to-imagine reality 4070 over the next decades. The quadrillion-record database is roughly at 4071 the limit of what is imaginable and should probably be accommodated. 4072 The 100 quadrillion datadbase is highly speculative perhaps involving 4073 nanorobots for every person, livestock animal and domesticated bird. 4074 It is included to round out the analysis. 4076 Note that the items counted here certainly do not have IP address and 4077 are not individually connected to the network. They may be connected 4078 to internal buses, via serial links, Bluetooth and so on. This is 4079 not the same problem as sizing IP addresses. 4081 +---------+------------+--------------+------------+----------------+ 4082 | People | Devices / | Subsystems / | Database | Database Size | 4083 | | Person | Device | Portion | | 4084 +---------+------------+--------------+------------+----------------+ 4085 | 10 | 100 | 10 | 10% | trillion | 4086 | billion | | | | (10^12) | 4087 | 10 | 100,000 | 10 | 10% | quadrillion | 4088 | billion | | | | (10^15) | 4089 | 100 | 1,000,000 | 10 | 10% | 100 | 4090 | billion | | | | quadrillion | 4091 | | | | | (10^17) | 4092 +---------+------------+--------------+------------+----------------+ 4094 This is conceptually similar to the Birthday Problem where m is the 4095 number of possible birthdays, always 365, and k is the number of 4096 people. It is also conceptually similar to the Birthday Attack where 4097 collisions of the output of hash functions are considered. 4099 The proper formula for the collision calculation is 4100 p = 1 - e^{-k^2/(2n)} 4102 p Collision Probability 4103 n Total possible population 4104 k Actual population 4106 However, for the very large values involved here, this formula 4107 requires floating point precision higher than commonly available in 4108 calculators and SW so this simple approximation is used. See 4109 [BirthdayAttack]. 4111 p = k^2 / 2n 4113 For this calculation: 4115 p Collision Probability 4116 n Total population based on number of bits in UEID 4117 k Population in a database 4119 +----------------------+--------------+--------------+--------------+ 4120 | Database Size | 128-bit UEID | 192-bit UEID | 256-bit UEID | 4121 +----------------------+--------------+--------------+--------------+ 4122 | trillion (10^12) | 2 * 10^-15 | 8 * 10^-35 | 5 * 10^-55 | 4123 | quadrillion (10^15) | 2 * 10^-09 | 8 * 10^-29 | 5 * 10^-49 | 4124 | 100 quadrillion | 2 * 10^-05 | 8 * 10^-25 | 5 * 10^-45 | 4125 | (10^17) | | | | 4126 +----------------------+--------------+--------------+--------------+ 4128 Next, to calculate the probability of a collision occurring in one 4129 year's operation of a database, it is assumed that the database size 4130 is in a steady state and that 10% of the database changes per year. 4131 For example, a trillion record database would have 100 billion states 4132 per year. Each of those states has the above calculated probability 4133 of a collision. 4135 This assumption is a worst-case since it assumes that each state of 4136 the database is completely independent from the previous state. In 4137 reality this is unlikely as state changes will be the addition or 4138 deletion of a few records. 4140 The following tables gives the time interval until there is a 4141 probability of a collision based on there being one tenth the number 4142 of states per year as the number of records in the database. 4144 t = 1 / ((k / 10) * p) 4146 t Time until a collision 4147 p Collision probability for UEID size 4148 k Database size 4150 +---------------------+---------------+--------------+--------------+ 4151 | Database Size | 128-bit UEID | 192-bit UEID | 256-bit UEID | 4152 +---------------------+---------------+--------------+--------------+ 4153 | trillion (10^12) | 60,000 years | 10^24 years | 10^44 years | 4154 | quadrillion (10^15) | 8 seconds | 10^14 years | 10^34 years | 4155 | 100 quadrillion | 8 | 10^11 years | 10^31 years | 4156 | (10^17) | microseconds | | | 4157 +---------------------+---------------+--------------+--------------+ 4159 Clearly, 128 bits is enough for the near future thus the requirement 4160 that UEIDs be a minimum of 128 bits. 4162 There is no requirement for 256 bits today as quadrillion-record 4163 databases are not expected in the near future and because this time- 4164 to-collision calculation is a very worst case. A future update of 4165 the standard may increase the requirement to 256 bits, so there is a 4166 requirement that implementations be able to receive 256-bit UEIDs. 4168 B.2. No Use of UUID 4170 A UEID is not a UUID [RFC4122] by conscious choice for the following 4171 reasons. 4173 UUIDs are limited to 128 bits which may not be enough for some future 4174 use cases. 4176 Today, cryptographic-quality random numbers are available from common 4177 CPUs and hardware. This hardware was introduced between 2010 and 4178 2015. Operating systems and cryptographic libraries give access to 4179 this hardware. Consequently, there is little need for 4180 implementations to construct such random values from multiple sources 4181 on their own. 4183 Version 4 UUIDs do allow for use of such cryptographic-quality random 4184 numbers, but do so by mapping into the overall UUID structure of time 4185 and clock values. This structure is of no value here yet adds 4186 complexity. It also slightly reduces the number of actual bits with 4187 entropy. 4189 UUIDs seem to have been designed for scenarios where the implementor 4190 does not have full control over the environment and uniqueness has to 4191 be constructed from identifiers at hand. UEID takes the view that 4192 hardware, software and/or manufacturing process directly implement 4193 UEID in a simple and direct way. It takes the view that 4194 cryptographic quality random number generators are readily available 4195 as they are implemented in commonly used CPU hardware. 4197 Appendix C. EAT Relation to IEEE.802.1AR Secure Device Identity (DevID) 4199 This section describes several distinct ways in which an IEEE IDevID 4200 [IEEE.802.1AR] relates to EAT, particularly to UEID and SUEID. 4202 [IEEE.802.1AR] orients around the definition of an implementation 4203 called a "DevID Module." It describes how IDevIDs and LDevIDs are 4204 stored, protected and accessed using a DevID Module. A particular 4205 level of defense against attack that should be achieved to be a DevID 4206 is defined. The intent is that IDevIDs and LDevIDs are used with an 4207 open set of network protocols for authentication and such. In these 4208 protocols the DevID secret is used to sign a nonce or similar to 4209 proof the association of the DevID certificates with the device. 4211 By contrast, EAT defines network protocol for proving trustworthiness 4212 to a Relying Party, the very thing that is not defined in 4213 [IEEE.802.1AR]. Nor does not give details on how keys, data and such 4214 are stored protected and accessed. EAT is intended to work with a 4215 variety of different on-device implementations ranging from minimal 4216 protection of assets to the highest levels of asset protection. It 4217 does not define any particular level of defense against attack, 4218 instead providing a set of security considerations. 4220 EAT and DevID can be viewed as complimentary when used together or as 4221 competing to provide a device identity service. 4223 C.1. DevID Used With EAT 4225 As just described, EAT defines a network protocol and [IEEE.802.1AR] 4226 doesn't. Vice versa, EAT doesn't define a an device implementation 4227 and DevID does. 4229 Hence, EAT can be the network protocol that a DevID is used with. 4230 The DevID secret becomes the attestation key used to sign EATs. The 4231 DevID and its certificate chain become the Endorsement sent to the 4232 Verifier. 4234 In this case the EAT and the DevID are likely to both provide a 4235 device identifier (e.g. a serial number). In the EAT it is the UEID 4236 (or SUEID). In the DevID (used as an endorsement), it is a device 4237 serial number included in the subject field of the DevID certificate. 4238 It is probably a good idea in this use for them to be the same serial 4239 number or for the UEID to be a hash of the DevID serial number. 4241 C.2. How EAT Provides an Equivalent Secure Device Identity 4243 The UEID, SUEID and other claims like OEM ID are equivalent to the 4244 secure device identity put into the subject field of a DevID 4245 certificate. These EAT claims can represent all the same fields and 4246 values that can be put in a DevID certificate subject. EAT 4247 explicitly and carefully defines a variety of useful claims. 4249 EAT secures the conveyance of these claims by having them signed on 4250 the device by the attestation key when the EAT is generated. EAT 4251 also signs the nonce that gives freshness at this time. Since these 4252 claims are signed for every EAT generated, they can include things 4253 that vary over time like GPS location. 4255 DevID secures the device identity fields by having them signed by the 4256 manufacturer of the device sign them into a certificate. That 4257 certificate is created once during the manufacturing of the device 4258 and never changes so the fields cannot change. 4260 So in one case the signing of the identity happens on the device and 4261 the other in a manufacturing facility, but in both cases the signing 4262 of the nonce that proves the binding to the actual device happens on 4263 the device. 4265 While EAT does not specify how the signing keys, signature process 4266 and storage of the identity values should be secured against attack, 4267 an EAT implementation may have equal defenses against attack. One 4268 reason EAT uses CBOR is because it is simple enough that a basic EAT 4269 implementation can be constructed entirely in hardware. This allows 4270 EAT to be implemented with the strongest defenses possible. 4272 C.3. An X.509 Format EAT 4274 It is possible to define a way to encode EAT claims in an X.509 4275 certificate. For example, the EAT claims might be mapped to X.509 v3 4276 extensions. It is even possible to stuff a whole CBOR-encoded 4277 unsigned EAT token into a X.509 certificate. 4279 If that X.509 certificate is an IDevID or LDevID, this becomes 4280 another way to use EAT and DevID together. 4282 Note that the DevID must still be used with an authentication 4283 protocol that has a nonce or equivalent. The EAT here is not being 4284 used as the protocol to interact with the rely party. 4286 C.4. Device Identifier Permanence 4288 In terms of permanence, an IDevID is similar to a UEID in that they 4289 do not change over the life of the device. They cease to exist only 4290 when the device is destroyed. 4292 An SUEID is similar to an LDevID. They change on device life-cycle 4293 events. 4295 [IEEE.802.1AR] describes much of this permanence as resistant to 4296 attacks that seek to change the ID. IDevID permanence can be 4297 described this way because [IEEE.802.1AR] is oriented around the 4298 definition of an implementation with a particular level of defense 4299 against attack. 4301 EAT is not defined around a particular implementation and must work 4302 on a range of devices that have a range of defenses against attack. 4303 EAT thus can't be defined permanence in terms of defense against 4304 attack. EAT's definition of permanence is in terms of operations and 4305 device lifecycle. 4307 Appendix D. CDDL for CWT and JWT 4309 [RFC8392] was published before CDDL was available and thus is 4310 specified in prose, not CDDL. Following is CDDL specifying CWT as it 4311 is needed to complete this specification. This CDDL also covers the 4312 Claims-Set for JWT. 4314 This however is NOT a normative or standard definition of CWT or JWT 4315 in CDDL. The prose in CWT and JWT remain the normative definition. 4317 ; This is replicated from draft-ietf-rats-uccs 4319 Claims-Set = { 4320 * $$Claims-Set-Claims 4321 * Claim-Label .feature "extended-claims-label" => any 4322 } 4323 Claim-Label = int / text 4324 string-or-uri = text 4326 $$Claims-Set-Claims //= ( iss-claim-label => string-or-uri ) 4327 $$Claims-Set-Claims //= ( sub-claim-label => string-or-uri ) 4328 $$Claims-Set-Claims //= ( aud-claim-label => string-or-uri ) 4329 $$Claims-Set-Claims //= ( exp-claim-label => ~time ) 4330 $$Claims-Set-Claims //= ( nbf-claim-label => ~time ) 4331 $$Claims-Set-Claims //= ( iat-claim-label => ~time ) 4332 $$Claims-Set-Claims //= ( cti-claim-label => bytes ) 4334 iss-claim-label = JC<"iss", 1> 4335 sub-claim-label = JC<"sub", 2> 4336 aud-claim-label = JC<"aud", 3> 4337 exp-claim-label = JC<"exp", 4> 4338 nbf-claim-label = JC<"nbf", 5> 4339 iat-claim-label = JC<"iat", 6> 4340 cti-claim-label = CBOR-ONLY<7> ; jti in JWT: different name and text 4342 JSON-ONLY = J .feature "json" 4343 CBOR-ONLY = C .feature "cbor" 4345 ; Be sure to have cddl 0.8.29 or higher for this to work 4346 JC = JSON-ONLY / CBOR-ONLY 4348 ; A JWT message is either a JWS or JWE in compact serialization form 4349 ; with the payload a Claims-Set. Compact serialization is the 4350 ; protected headers, payload and signature, each b64url encoded and 4351 ; separated by a ".". This CDDL simply matches top-level syntax of of 4352 ; a JWS or JWE since it is not possible to do more in CDDL. 4354 JWT-Message = text .regexp "[A-Za-z0-9_=-]+\.[A-Za-z0-9_=-]+\.[A-Za-z0-9_=-]+" 4356 ; Note that the payload of a JWT is defined in claims-set.cddl. That 4357 ; definition is common to CBOR and JSON. 4359 ; This is some CDDL describing a CWT at the top level This is 4360 ; not normative. RFC 8392 is the normative definition of CWT. 4362 CWT-Messages = CWT-Tagged-Message / CWT-Untagged-Message 4364 ; The payload of the COSE_Message is always a Claims-Set 4366 ; The contents of a CWT Tag must always be a COSE tag 4367 CWT-Tagged-Message = #6.61(COSE_Tagged_Message) 4369 ; An untagged CWT may be a COSE tag or not 4370 CWT-Untagged-Message = COSE_Messages 4372 Appendix E. Changes from Previous Drafts 4374 The following is a list of known changes from the previous drafts. 4375 This list is non-authoritative. It is meant to help reviewers see 4376 the significant differences. 4378 E.1. From draft-rats-eat-01 4380 o Added UEID design rationale appendix 4382 E.2. From draft-mandyam-rats-eat-00 4384 This is a fairly large change in the orientation of the document, but 4385 no new claims have been added. 4387 o Separate information and data model using CDDL. 4389 o Say an EAT is a CWT or JWT 4391 o Use a map to structure the boot_state and location claims 4393 E.3. From draft-ietf-rats-eat-01 4395 o Clarifications and corrections for OEMID claim 4397 o Minor spelling and other fixes 4399 o Add the nonce claim, clarify jti claim 4401 E.4. From draft-ietf-rats-eat-02 4403 o Roll all EUIs back into one UEID type 4405 o UEIDs can be one of three lengths, 128, 192 and 256. 4407 o Added appendix justifying UEID design and size. 4409 o Submods part now includes nested eat tokens so they can be named 4410 and there can be more tha one of them 4412 o Lots of fixes to the CDDL 4414 o Added security considerations 4416 E.5. From draft-ietf-rats-eat-03 4418 o Split boot_state into secure-boot and debug-disable claims 4420 o Debug disable is an enumerated type rather than Booleans 4422 E.6. From draft-ietf-rats-eat-04 4424 o Change IMEI-based UEIDs to be encoded as a 14-byte string 4426 o CDDL cleaned up some more 4428 o CDDL allows for JWTs and UCCSs 4430 o CWT format submodules are byte string wrapped 4432 o Allows for JWT nested in CWT and vice versa 4434 o Allows UCCS (unsigned CWTs) and JWT unsecured tokens 4436 o Clarify tag usage when nesting tokens 4438 o Add section on key inclusion 4440 o Add hardware version claims 4442 o Collected CDDL is now filled in. Other CDDL corrections. 4444 o Rename debug-disable to debug-status; clarify that it is not 4445 extensible 4447 o Security level claim is not extensible 4449 o Improve specification of location claim and added a location 4450 privacy section 4452 o Add intended use claim 4454 E.7. From draft-ietf-rats-eat-05 4456 o CDDL format issues resolved 4458 o Corrected reference to Location Privacy section 4460 E.8. From draft-ietf-rats-eat-06 4462 o Added boot-seed claim 4464 o Rework CBOR interoperability section 4466 o Added profiles claim and section 4468 E.9. From draft-ietf-rats-eat-07 4470 o Filled in IANA and other sections for possible preassignment of 4471 Claim Keys for well understood claims 4473 E.10. From draft-ietf-rats-eat-08 4475 o Change profile claim to be either a URL or an OID rather than a 4476 test string 4478 E.11. From draft-ietf-rats-eat-09 4480 o Add SUEIDs 4482 o Add appendix comparing IDevID to EAT 4484 o Added section on use for Evidence and Attestation Results 4486 o Fill in the key ID and endorsements identificaiton section 4488 o Remove origination claim as it is replaced by key IDs and 4489 endorsements 4491 o Added manifests and software evidence claims 4493 o Add string labels non-claim labels for use with JSON (e.g. labels 4494 for members of location claim) 4496 o EAN-13 HW versions are no longer a separate claim. Now they are 4497 folded in as a CoSWID version scheme. 4499 E.12. From draft-ietf-rats-eat-10 4501 o Hardware version is made into an array of two rather than two 4502 claims 4504 o Corrections and wording improvements for security levels claim 4506 o Add swresults claim 4508 o Add dloas claim - Digitial Letter of Approvals, a list of 4509 certifications 4511 o CDDL for each claim no longer in a separate sub section 4513 o Consistent use of terminology from RATS architecture document 4515 o Consistent use of terminology from CWT and JWT documents 4517 o Remove operating model and procedures; refer to CWT, JWT and RATS 4518 architecture instead 4520 o Some reorganization of Section 1 4522 o Moved a few references, including RATS Architecture, to 4523 informative. 4525 o Add detached submodule digests and detached eat bundles (DEBs) 4527 o New simpler and more universal scheme for identifying the encoding 4528 of a nested token 4530 o Made clear that CBOR and JSON are only mixed when nesting a token 4531 in another token 4533 o Clearly separate CDDL for JSON and CBOR-specific data items 4535 o Define UJCS (unsigned JWTs) 4537 o Add CDDL for a general Claims-Set used by UCCS, UJCS, CWT, JWT and 4538 EAT 4540 o Top level CDDL for CWT correctly refers to COSE 4542 o OEM ID is specifically for HW, not for SW 4544 o HW OEM ID can now be a PEN 4546 o HW OEM ID can now be a 128-bit random number 4547 o Expand the examples section 4549 o Add software and version claims as easy / JSON alternative to 4550 CoSWID 4552 E.13. From draft-ietf-rats-eat-11 4554 o Add HW model claim 4556 o Change reference for CBOR OID draft to RFC 9090 4558 o Correct the iat claim in some examples 4560 o Make HW Version just one claim rather than 3 (device, board and 4561 chip) 4563 o Remove CDDL comments from CDDL blocks 4565 o More clearly define "entity" and use it more broadly, particularly 4566 instead of "device" 4568 o Re do early allocation of CBOR labels since last one didn't 4569 complete correctly 4571 o Lots of rewording and tightening up of section 1 4573 o Lots of wording improvements in section 3, particularly better use 4574 of normative language 4576 o Improve wording in submodules section, particularly how to 4577 distinguish types when decoding 4579 o Remove security-level from early allocation 4581 o Add boot odometer claim 4583 o Add privacy considerations for replay protection 4585 E.14. From draft-ietf-rats-eat-12 4587 o Make use of the JC<> generic to express CDDL for both JSON and 4588 CBOR 4590 o Reorganize claims into 4 sections, particularly claims about the 4591 entity and about the token 4593 o Nonce wording - say nonce is required and other improvements 4594 o Clarify relationship of claims in evidence to results when 4595 forwarding 4597 o Clarify manufacturer switching UEID types 4599 o Add new section on the top-level token type that has CBOR-specific 4600 and JSON-specific CDDL since the top-level can't be handled with 4601 JC<> 4603 o Remove definition of UCCS and UJCS, replacing it with a CDDL 4604 socket and mention of future token types 4606 o Split the examples into payload and top level tokens since UCCS 4607 can't be used for examples any more (It was nice because you could 4608 see the payload claims in it easily, where you can't with CWT) 4610 o DEB tag number is TBD rather than hard coded 4612 o Add appendix with non-normative CDDL for a Claims-Set, CWT and JWT 4614 o (Large reorganization of the document build and example 4615 verification makefile) 4617 o Use CoAP content format ID to distinguish manifest and evidence 4618 formats instead of CBOR tag 4620 o Added more examples, both CBOR and JSON 4622 o All CDDL is validating against all examples 4624 o Unassigned IANA requests are clearly TBD in the document (and have 4625 real values as is necessary in the example validation process) 4627 o Improve security-level claim 4629 o swresults claim is now measurement results claim 4631 o substantial redesign of measurement results claim 4633 Authors' Addresses 4635 Laurence Lundblade 4636 Security Theory LLC 4638 EMail: lgl@securitytheory.com 4639 Giridhar Mandyam 4640 Qualcomm Technologies Inc. 4641 5775 Morehouse Drive 4642 San Diego, California 4643 USA 4645 Phone: +1 858 651 7200 4646 EMail: mandyam@qti.qualcomm.com 4648 Jeremy O'Donoghue 4649 Qualcomm Technologies Inc. 4650 279 Farnborough Road 4651 Farnborough GU14 7LS 4652 United Kingdom 4654 Phone: +44 1252 363189 4655 EMail: jodonogh@qti.qualcomm.com