idnits 2.17.1 draft-ietf-rats-eat-12.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 3 instances of too long lines in the document, the longest one being 15 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 3437 has weird spacing: '... / the name ...' == Line 3523 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: 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. -- The document date (February 23, 2022) is 790 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) == Outdated reference: A later version (-24) exists of draft-ietf-sacm-coswid-20 -- 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 (~~), 6 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: August 27, 2022 J. O'Donoghue 6 Qualcomm Technologies Inc. 7 February 23, 2022 9 The Entity Attestation Token (EAT) 10 draft-ietf-rats-eat-12 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 August 27, 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, UCCS, UJCS and DEB . . . . . . . . . . . . . . 7 61 1.3. CDDL, CBOR and JSON . . . . . . . . . . . . . . . . . . . 8 62 1.4. Operating Model and RATS Architecture . . . . . . . . . . 8 63 1.4.1. Relationship between Attestation Evidence and 64 Attestation Results . . . . . . . . . . . . . . . . . 9 65 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 10 66 3. The Claims . . . . . . . . . . . . . . . . . . . . . . . . . 11 67 3.1. Token ID Claim (cti and jti) . . . . . . . . . . . . . . 11 68 3.2. Timestamp claim (iat) . . . . . . . . . . . . . . . . . . 11 69 3.3. Nonce Claim (nonce) . . . . . . . . . . . . . . . . . . . 12 70 3.4. Universal Entity ID Claim (ueid) . . . . . . . . . . . . 12 71 3.5. Semi-permanent UEIDs (SUEIDs) . . . . . . . . . . . . . . 15 72 3.6. Hardware OEM Identification (oemid) . . . . . . . . . . . 16 73 3.6.1. Random Number Based OEMID . . . . . . . . . . . . . . 16 74 3.6.2. IEEE Based OEMID . . . . . . . . . . . . . . . . . . 16 75 3.6.3. IANA Private Enterprise Number Based OEMID . . . . . 17 76 3.7. Hardware Model Claim (hardware-model) . . . . . . . . . . 17 77 3.8. Hardware Version Claims (hardware-version-claims) . . . . 18 78 3.9. Software Name Claim . . . . . . . . . . . . . . . . . . . 19 79 3.10. Software Version Claim . . . . . . . . . . . . . . . . . 19 80 3.11. The Security Level Claim (security-level) . . . . . . . . 19 81 3.12. Secure Boot Claim (secure-boot) . . . . . . . . . . . . . 21 82 3.13. Debug Status Claim (debug-status) . . . . . . . . . . . . 21 83 3.13.1. Enabled . . . . . . . . . . . . . . . . . . . . . . 22 84 3.13.2. Disabled . . . . . . . . . . . . . . . . . . . . . . 22 85 3.13.3. Disabled Since Boot . . . . . . . . . . . . . . . . 22 86 3.13.4. Disabled Permanently . . . . . . . . . . . . . . . . 22 87 3.13.5. Disabled Fully and Permanently . . . . . . . . . . . 22 88 3.14. Including Keys . . . . . . . . . . . . . . . . . . . . . 23 89 3.15. The Location Claim (location) . . . . . . . . . . . . . . 24 90 3.16. The Uptime Claim (uptime) . . . . . . . . . . . . . . . . 25 91 3.17. The Boot Odometer Claim (odometer) . . . . . . . . . . . 25 92 3.18. The Boot Seed Claim (boot-seed) . . . . . . . . . . . . . 25 93 3.19. The Intended Use Claim (intended-use) . . . . . . . . . . 26 94 3.20. The Profile Claim (profile) . . . . . . . . . . . . . . . 27 95 3.21. The DLOA (Digital Letter or Approval) Claim (dloas) . . . 27 96 3.22. The Software Manifests Claim (manifests) . . . . . . . . 28 97 3.23. The Software Evidence Claim (swevidence) . . . . . . . . 30 98 3.24. The SW Measurement Results Claim (swresults) . . . . . . 30 99 3.24.1. Scheme . . . . . . . . . . . . . . . . . . . . . . . 31 100 3.24.2. Objective . . . . . . . . . . . . . . . . . . . . . 31 101 3.24.3. Results . . . . . . . . . . . . . . . . . . . . . . 31 102 3.24.4. Objective Name . . . . . . . . . . . . . . . . . . . 32 103 3.25. Submodules (submods) . . . . . . . . . . . . . . . . . . 34 104 3.25.1. Submodule Types . . . . . . . . . . . . . . . . . . 34 105 3.25.1.1. Submodule Claims-Set . . . . . . . . . . . . . . 34 106 3.25.1.2. Nested Token . . . . . . . . . . . . . . . . . . 35 107 3.25.1.3. Detached Submodule Digest . . . . . . . . . . . 37 108 3.25.2. No Inheritance . . . . . . . . . . . . . . . . . . . 38 109 3.25.3. Security Levels . . . . . . . . . . . . . . . . . . 38 110 3.25.4. Submodule Names . . . . . . . . . . . . . . . . . . 39 111 3.25.5. CDDL for submods . . . . . . . . . . . . . . . . . . 39 112 4. Unprotected JWT Claims-Sets . . . . . . . . . . . . . . . . . 39 113 5. Detached EAT Bundles . . . . . . . . . . . . . . . . . . . . 39 114 6. Endorsements and Verification Keys . . . . . . . . . . . . . 40 115 6.1. Identification Methods . . . . . . . . . . . . . . . . . 41 116 6.1.1. COSE/JWS Key ID . . . . . . . . . . . . . . . . . . . 41 117 6.1.2. JWS and COSE X.509 Header Parameters . . . . . . . . 42 118 6.1.3. CBOR Certificate COSE Header Parameters . . . . . . . 42 119 6.1.4. Claim-Based Key Identification . . . . . . . . . . . 42 120 6.2. Other Considerations . . . . . . . . . . . . . . . . . . 42 121 7. Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . 43 122 7.1. Format of a Profile Document . . . . . . . . . . . . . . 43 123 7.2. List of Profile Issues . . . . . . . . . . . . . . . . . 43 124 7.2.1. Use of JSON, CBOR or both . . . . . . . . . . . . . . 43 125 7.2.2. CBOR Map and Array Encoding . . . . . . . . . . . . . 44 126 7.2.3. CBOR String Encoding . . . . . . . . . . . . . . . . 44 127 7.2.4. CBOR Preferred Serialization . . . . . . . . . . . . 44 128 7.2.5. COSE/JOSE Protection . . . . . . . . . . . . . . . . 44 129 7.2.6. COSE/JOSE Algorithms . . . . . . . . . . . . . . . . 45 130 7.2.7. DEB Support . . . . . . . . . . . . . . . . . . . . . 45 131 7.2.8. Verification Key Identification . . . . . . . . . . . 45 132 7.2.9. Endorsement Identification . . . . . . . . . . . . . 45 133 7.2.10. Freshness . . . . . . . . . . . . . . . . . . . . . . 45 134 7.2.11. Required Claims . . . . . . . . . . . . . . . . . . . 45 135 7.2.12. Prohibited Claims . . . . . . . . . . . . . . . . . . 45 136 7.2.13. Additional Claims . . . . . . . . . . . . . . . . . . 46 137 7.2.14. Refined Claim Definition . . . . . . . . . . . . . . 46 138 7.2.15. CBOR Tags . . . . . . . . . . . . . . . . . . . . . . 46 139 7.2.16. Manifests and Software Evidence Claims . . . . . . . 46 140 8. Encoding and Collected CDDL . . . . . . . . . . . . . . . . . 46 141 8.1. Claims-Set and CDDL for CWT and JWT . . . . . . . . . . . 46 142 8.2. Encoding Data Types . . . . . . . . . . . . . . . . . . . 47 143 8.2.1. Common Data Types . . . . . . . . . . . . . . . . . . 47 144 8.2.2. JSON Interoperability . . . . . . . . . . . . . . . . 47 145 8.2.3. Labels . . . . . . . . . . . . . . . . . . . . . . . 48 146 8.3. CBOR Interoperability . . . . . . . . . . . . . . . . . . 48 147 8.3.1. EAT Constrained Device Serialization . . . . . . . . 48 148 8.4. Collected Common CDDL . . . . . . . . . . . . . . . . . . 49 149 8.5. Collected CDDL for CBOR . . . . . . . . . . . . . . . . . 54 150 8.6. Collected CDDL for JSON . . . . . . . . . . . . . . . . . 55 151 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 56 152 9.1. Reuse of CBOR and JSON Web Token (CWT and JWT) Claims 153 Registries . . . . . . . . . . . . . . . . . . . . . . . 56 154 9.2. Claim Characteristics . . . . . . . . . . . . . . . . . . 57 155 9.2.1. Interoperability and Relying Party Orientation . . . 57 156 9.2.2. Operating System and Technology Neutral . . . . . . . 57 157 9.2.3. Security Level Neutral . . . . . . . . . . . . . . . 58 158 9.2.4. Reuse of Extant Data Formats . . . . . . . . . . . . 58 159 9.2.5. Proprietary Claims . . . . . . . . . . . . . . . . . 58 160 9.3. Claims Registered by This Document . . . . . . . . . . . 58 161 9.3.1. Claims for Early Assignment . . . . . . . . . . . . . 59 162 9.3.2. To be Assigned Claims . . . . . . . . . . . . . . . . 62 163 9.3.3. Version Schemes Registered by this Document . . . . . 65 164 9.3.4. UEID URN Registered by this Document . . . . . . . . 66 165 9.3.5. Tag for Detached EAT Bundle . . . . . . . . . . . . . 66 166 10. Privacy Considerations . . . . . . . . . . . . . . . . . . . 66 167 10.1. UEID and SUEID Privacy Considerations . . . . . . . . . 67 168 10.2. Location Privacy Considerations . . . . . . . . . . . . 67 169 10.3. Replay Protection and Privacy . . . . . . . . . . . . . 68 170 11. Security Considerations . . . . . . . . . . . . . . . . . . . 68 171 11.1. Key Provisioning . . . . . . . . . . . . . . . . . . . . 68 172 11.1.1. Transmission of Key Material . . . . . . . . . . . . 69 173 11.2. Transport Security . . . . . . . . . . . . . . . . . . . 69 174 11.3. Multiple EAT Consumers . . . . . . . . . . . . . . . . . 69 175 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 70 176 12.1. Normative References . . . . . . . . . . . . . . . . . . 70 177 12.2. Informative References . . . . . . . . . . . . . . . . . 73 178 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 76 179 A.1. Simple TEE Attestation . . . . . . . . . . . . . . . . . 76 180 A.2. Submodules for Board and Device . . . . . . . . . . . . . 77 181 A.3. EAT Produced by Attestation Hardware Block . . . . . . . 79 182 A.4. Detached EAT Bundle . . . . . . . . . . . . . . . . . . . 79 183 A.5. Key / Key Store Attestation . . . . . . . . . . . . . . . 81 184 A.6. SW Measurements of an IoT Device . . . . . . . . . . . . 83 185 A.7. Attestation Results in JSON format . . . . . . . . . . . 86 186 Appendix B. UEID Design Rationale . . . . . . . . . . . . . . . 87 187 B.1. Collision Probability . . . . . . . . . . . . . . . . . . 87 188 B.2. No Use of UUID . . . . . . . . . . . . . . . . . . . . . 89 189 Appendix C. EAT Relation to IEEE.802.1AR Secure Device Identity 190 (DevID) . . . . . . . . . . . . . . . . . . . . . . 90 191 C.1. DevID Used With EAT . . . . . . . . . . . . . . . . . . . 90 192 C.2. How EAT Provides an Equivalent Secure Device Identity . . 91 193 C.3. An X.509 Format EAT . . . . . . . . . . . . . . . . . . . 91 194 C.4. Device Identifier Permanence . . . . . . . . . . . . . . 92 195 Appendix D. Changes from Previous Drafts . . . . . . . . . . . . 92 196 D.1. From draft-rats-eat-01 . . . . . . . . . . . . . . . . . 92 197 D.2. From draft-mandyam-rats-eat-00 . . . . . . . . . . . . . 92 198 D.3. From draft-ietf-rats-eat-01 . . . . . . . . . . . . . . . 92 199 D.4. From draft-ietf-rats-eat-02 . . . . . . . . . . . . . . . 93 200 D.5. From draft-ietf-rats-eat-03 . . . . . . . . . . . . . . . 93 201 D.6. From draft-ietf-rats-eat-04 . . . . . . . . . . . . . . . 93 202 D.7. From draft-ietf-rats-eat-05 . . . . . . . . . . . . . . . 94 203 D.8. From draft-ietf-rats-eat-06 . . . . . . . . . . . . . . . 94 204 D.9. From draft-ietf-rats-eat-07 . . . . . . . . . . . . . . . 94 205 D.10. From draft-ietf-rats-eat-08 . . . . . . . . . . . . . . . 94 206 D.11. From draft-ietf-rats-eat-09 . . . . . . . . . . . . . . . 94 207 D.12. From draft-ietf-rats-eat-10 . . . . . . . . . . . . . . . 95 208 D.13. From draft-ietf-rats-eat-11 . . . . . . . . . . . . . . . 96 209 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 96 211 1. Introduction 213 EAT provides the definition of a base set of claims that can be made 214 about an entity, a device, some software and/or some hardware. This 215 claims set is received by a relying party who uses it to decide if 216 and how it will interact with the remote entity. It may choose to 217 not trust the entity and not interact with it. It may choose to 218 trust it. It may partially trust it, for example allowing monetary 219 transactions only up to a limit. 221 EAT defines the encoding of the claims set in CBOR [RFC8949] and JSON 222 [RFC7159]. EAT is an extension to CBOR Web Token (CWT) [RFC8392] and 223 JSON Web Token (JWT) [RFC7519]. 225 The claims set is secured in transit with the same mechanisms used by 226 CWT and JWT, in particular CBOR Object Signing and Encryption (COSE) 227 [RFC8152] and JSON Object Signing and Encryption (JOSE) [RFC7515] 228 [RFC7516]. Authenticity and integrity protection must always be 229 provided. Privacy (encryption) may additionally be provided. The 230 key material used to sign and encrypt is specifically created and 231 provisioned for the purpose of attestation. It is the use of this 232 key material that make the claims set "attested" rather than just 233 some parameters sent to the relying party by the device. 235 EAT is focused on authenticating, identifying and characterizing 236 implementations where implementations are devices, chips, hardware, 237 software and such. This is distinct from protocols like TLS 238 [RFC8446] that authenticate and identify servers and services. It is 239 equally distinct from protocols like SASL [RFC4422] that authenticate 240 and identify persons. 242 The notion of attestation is large, ranging over a broad variety of 243 use cases and security levels. Here are a few examples of claims: 245 o Make and model of manufactured consumer device 247 o Make and model of a chip or processor, particularly for a 248 security-oriented chip 250 o Identification and measurement of the software running on a device 252 o Configuration and state of a device 254 o Environmental characteristics of a device like its GPS location 256 o Formal certifications received 258 EAT also supports nesting of sets of claims and EAT tokens for use 259 with complex composite devices. 261 This document uses the terminology and main operational model defined 262 in [RATS.Architecture]. In particular, it can be used for RATS 263 Attestation Evidence and Attestation Results. 265 1.1. Entity Overview 267 The document uses the term "entity" to refer to the target of the 268 attestation token. The claims defined in this document are claims 269 about an entity. 271 An entity is an implementation in hardware, software or both. 273 An entity is the same as the Attester Target Environment defined in 274 RATS Architecture. 276 An entity also corresponds to a "system component" as defined in the 277 Internet Security Glossary [RFC4949]. That glossary also defines 278 "entity" and "system entity" as something that may be a person or 279 organization as well as a system component. Here "entity" never 280 refers to a person or organization. 282 An entity is never a server or a service. 284 An entity may be the whole device or it may be a subsystem, a 285 subsystem of a subsystem and so on. EAT allows claims to be 286 organized into submodules, nested EATs and so on. See Section 3.25. 287 The entity to which a claim applies is the submodule in which it 288 appears, or to the top-level entity if it doesn't appear in a 289 submodule. 291 Some examples of entities: 293 o A Secure Element 295 o A TEE 297 o A card in a network router 299 o A network router, perhaps with each card in the router a submodule 301 o An IoT device 303 o An individual process 305 o An app on a smartphone 307 o A smartphone with many submodules for its many subsystems 309 o A subsystem in a smartphone like the modem or the camera 311 An entity may have strong security like defenses against hardware 312 invasive attacks. It may also have low security, having no special 313 security defenses. There is no minimum security requirement to be an 314 entity. 316 1.2. CWT, JWT, UCCS, UJCS and DEB 318 An EAT is a claims set about an entity based on one of the following: 320 o CBOR Web Token (CWT) [RFC8392] 322 o Unprotected CWT Claims Sets (UCCS) [UCCS.Draft] 324 o JSON Web Token (JWT) [RFC7519] 326 All definitions, requirements, creation and validation procedures, 327 security considerations, IANA registrations and so on from these 328 carry over to EAT. 330 This specification extends those specifications by defining 331 additional claims for attestation. This specification also describes 332 the notion of a "profile" that can narrow the definition of an EAT, 333 ensure interoperability and fill in details for specific usage 334 scenarios. This specification also adds some considerations for 335 registration of future EAT-related claims. 337 The identification of a protocol element as an EAT, whether CBOR or 338 JSON encoded, follows the general conventions used by CWT, JWT and 339 UCCS. Largely this depends on the protocol carrying the EAT. In 340 some cases it may be by content type (e.g., MIME type). In other 341 cases it may be through use of CBOR tags. There is no fixed 342 mechanism across all use cases. 344 This specification adds two more top-level messages: 346 o Unprotected JWT Claims Set (UJCS) Section 4 348 o Detached EAT Bundle (DEB), Section 5 350 A DEB is structure to hold a collection of detached claims sets and 351 the EAT that separately provides integrity and authenticity 352 protection for them. It can be either CBOR or JSON encoded. 354 1.3. CDDL, CBOR and JSON 356 This document defines Concise Binary Object Representation (CBOR) 357 [RFC8949] and Javascript Object Notation (JSON) [RFC7159] encoding 358 for an EAT. All claims in an EAT MUST use the same encoding except 359 where explicitly allowed. It is explicitly allowed for a nested 360 token to be of a different encoding. Some claims explicitly contain 361 objects and messages that may use a different encoding than the 362 enclosing EAT. 364 This specification uses Concise Data Definition Language (CDDL) 365 [RFC8610] for all definitions. The implementor interprets the CDDL 366 to come to either the CBOR or JSON encoding. In the case of JSON, 367 Appendix E of [RFC8610] is followed. Additional rules are given in 368 Section 8.2.2 where Appendix E is insufficient. 370 The CWT and JWT specifications were authored before CDDL was 371 available and did not use CDDL. This specification includes a CDDL 372 definition of most of what is defined in [RFC8392]. Similarly, this 373 specification includes CDDL for most of what is defined in [RFC7519]. 375 The UCCS specification does not include CDDL. This specification 376 provides CDDL for it. 378 1.4. Operating Model and RATS Architecture 380 While it is not required that EAT be used with the RATS operational 381 model described in Figure 1 in [RATS.Architecture], or even that it 382 be used for attestation, this document is oriented around that model. 384 To summarize, an Attester generates Attestation Evidence. 385 Attestation Evidence is a claims set describing various 386 characteristics of an entity. Attestation Evidence also is usually 387 signed by a key that proves the entity and the evidence it produces 388 are authentic. The claims set includes a nonce or some other means 389 to provide freshness. EAT is designed to carry Attestation Evidence. 390 The Attestation Evidence goes to a Verifier where the signature is 391 verified. Some of the claims may also be checked against Reference 392 Values. The Verifier then produces Attestation Results which is also 393 usually a claims set. EAT is also designed to carry Attestation 394 Results. The Attestation Results go to the Relying Party which is 395 the ultimate consumer of the Remote Attestation Procedure. The 396 Relying Party uses the Attestation Results as needed for the use 397 case, perhaps allowing an entity on the network, allowing a financial 398 transaction or such. 400 Note that sometimes the Verifier and Relying Party are not separate 401 and thus there is no need for a protocol to carry Attestation 402 Results. 404 1.4.1. Relationship between Attestation Evidence and Attestation 405 Results 407 Any claim defined in this document or in the IANA CWT or JWT registry 408 may be used in Attestation Evidence or Attestation Results. 410 Many claims in Attestation Evidence simply will pass through the 411 Verifier to the Relying Party without modification. They will be 412 verified as authentic from the entity by the Verifier just through 413 normal verification of the Attester's signature. The UEID, 414 Section 3.4, and Location, Section 3.15, are examples of claims that 415 may be passed through. 417 Some claims in Attestation Evidence will be verified by the Verifier 418 by comparison to Reference Values. These claims will not likely be 419 conveyed to the Relying Party. Instead, some claim indicating they 420 were checked may be added to the Attestation Results or it may be 421 tacitly known that the Verifier always does this check. For example, 422 the Verifier receives the Software Evidence claim, Section 3.23, 423 compares it to Reference Values and conveys the results to the 424 Relying Party in a Software Measurement Results Claim, Section 3.24. 426 In some cases the Verifier may provide privacy-preserving 427 functionality by stripping or modifying claims that do not posses 428 sufficient privacy-preserving characteristics. For example, the data 429 in the Location claim, Section 3.15, may be modified to have a 430 precision of a few kilometers rather than a few meters. 432 2. Terminology 434 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 435 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 436 "OPTIONAL" in this document are to be interpreted as described in BCP 437 14 [RFC2119] [RFC8174] when, and only when, they appear in all 438 capitals, as shown here. 440 This document reuses terminology from JWT [RFC7519] and CWT 441 [RFC8392]. 443 Claim: A piece of information asserted about a subject. A claim is 444 represented as pair with a value and either a name or key to 445 identify it. 447 Claim Name: A unique text string that identifies the claim. It is 448 used as the claim name for JSON encoding. 450 Claim Key: The CBOR map key used to identify a claim. 452 Claim Value: The value portion of the claim. A claim value can be 453 any CBOR data item or JSON value. 455 CWT/JWT Claims Set: The CBOR map or JSON object that contains the 456 claims conveyed by the CWT or JWT. 458 This document reuses terminology from RATS Architecure 459 [RATS.Architecture] 461 Attester: A role performed by an entity (typically a device) whose 462 Evidence must be appraised in order to infer the extent to which 463 the Attester is considered trustworthy, such as when deciding 464 whether it is authorized to perform some operation. 466 Verifier: A role that appraises the validity of Attestation Evidence 467 about an Attester and produces Attestation Results to be used by a 468 Relying Party. 470 Relying Party: A role that depends on the validity of information 471 about an Attester, for purposes of reliably applying application 472 specific actions. Compare /relying party/ in [RFC4949]. 474 Attestation Evidence: A Claims Set generated by an Attester to be 475 appraised by a Verifier. Attestation Evidence may include 476 configuration data, measurements, telemetry, or inferences. 478 Attestation Results: The output generated by a Verifier, typically 479 including information about an Attester, where the Verifier 480 vouches for the validity of the results 482 Reference Values: A set of values against which values of Claims can 483 be compared as part of applying an Appraisal Policy for 484 Attestation Evidence. Reference Values are sometimes referred to 485 in other documents as known-good values, golden measurements, or 486 nominal values, although those terms typically assume comparison 487 for equality, whereas here Reference Values might be more general 488 and be used in any sort of comparison. 490 3. The Claims 492 This section describes new claims defined for attestation that are to 493 be added to the CWT [IANA.CWT.Claims] and JWT [IANA.JWT.Claims] IANA 494 registries. 496 This section also describes how several extant CWT and JWT claims 497 apply in EAT. 499 CDDL, along with a text description, is used to define each claim 500 independent of encoding. Each claim is defined as a CDDL group. In 501 Section 8 on encoding, the CDDL groups turn into CBOR map entries and 502 JSON name/value pairs. 504 Each claim described has a unique text string and integer that 505 identifies it. CBOR encoded tokens MUST use only the integer for 506 Claim Keys. JSON encoded tokens MUST use only the text string for 507 Claim Names. 509 3.1. Token ID Claim (cti and jti) 511 CWT defines the "cti" claim. JWT defines the "jti" claim. These are 512 equivalent to each other in EAT and carry a unique token identifier 513 as they do in JWT and CWT. They may be used to defend against re use 514 of the token but are distinct from the nonce that is used by the 515 Relying Party to guarantee freshness and defend against replay. 517 3.2. Timestamp claim (iat) 519 The "iat" claim defined in CWT and JWT is used to indicate the date- 520 of-creation of the token, the time at which the claims are collected 521 and the token is composed and signed. 523 The data for some claims may be held or cached for some period of 524 time before the token is created. This period may be long, even 525 days. Examples are measurements taken at boot or a geographic 526 position fix taken the last time a satellite signal was received. 527 There are individual timestamps associated with these claims to 528 indicate their age is older than the "iat" timestamp. 530 CWT allows the use floating-point for this claim. EAT disallows the 531 use of floating-point. An EAT token MUST NOT contain an iat claim in 532 float-point format. Any recipient of a token with a floating-point 533 format iat claim MUST consider it an error. A 64-bit integer 534 representation of epoch time can represent a range of +/- 500 billion 535 years, so the only point of a floating-point timestamp is to have 536 precession greater than one second. This is not needed for EAT. 538 3.3. Nonce Claim (nonce) 540 All EATs should have a nonce to prevent replay attacks. The nonce is 541 generated by the Relying Party, the end consumer of the token. It is 542 conveyed to the entity over whatever transport is in use before the 543 token is generated and then included in the token as the nonce claim. 545 This documents the nonce claim for registration in the IANA CWT 546 claims registry. This is equivalent to the JWT nonce claim that is 547 already registered. 549 The nonce must be at least 8 bytes (64 bits) long as fewer bytes are 550 unlikely to be secure. A maximum of 64 bytes is set to limit the 551 memory a constrained implementation uses. This size range is not set 552 for the already-registered JWT nonce, but it should follow this size 553 recommendation when used in an EAT. 555 Multiple nonces are allowed to accommodate multistage verification 556 and consumption. 558 $$claims-set-claims //= 559 (nonce-label => nonce-type / [ 2* nonce-type ]) 561 nonce-type = bstr .size (8..64) 563 3.4. Universal Entity ID Claim (ueid) 565 A UEID identifies an individual manufactured entity like a mobile 566 phone, a water meter, a Bluetooth speaker or a networked security 567 camera. It may identify the entire entity or a submodule. It does 568 not identify types, models or classes of entities. It is akin to a 569 serial number, though it does not have to be sequential. 571 UEIDs MUST be universally and globally unique across manufacturers 572 and countries. UEIDs MUST also be unique across protocols and 573 systems, as tokens are intended to be embedded in many different 574 protocols and systems. No two products anywhere, even in completely 575 different industries made by two different manufacturers in two 576 different countries should have the same UEID (if they are not global 577 and universal in this way, then Relying Parties receiving them will 578 have to track other characteristics of the entity to keep entities 579 distinct between manufacturers). 581 There are privacy considerations for UEIDs. See Section 10.1. 583 The UEID is permanent. It MUST never change for a given entity. 585 A UEID is constructed of a single type byte followed by the bytes 586 that are the identifier. Several types are allowed to accommodate 587 different industries, different manufacturing processes and to have 588 an alternative that doesn't require paying a registration fee. 590 Creation of new types requires a Standards Action [RFC8126]. 592 UEIDs are variable length. All implementations MUST be able to 593 receive UEIDs that are 33 bytes long (1 type byte and 256 bits). No 594 UEID longer than 33 bytes SHOULD be sent. 596 +------+------+-----------------------------------------------------+ 597 | Type | Type | Specification | 598 | Byte | Name | | 599 +------+------+-----------------------------------------------------+ 600 | 0x01 | RAND | This is a 128, 192 or 256-bit random number | 601 | | | generated once and stored in the entity. This may | 602 | | | be constructed by concatenating enough identifiers | 603 | | | to make up an equivalent number of random bits and | 604 | | | then feeding the concatenation through a | 605 | | | cryptographic hash function. It may also be a | 606 | | | cryptographic quality random number generated once | 607 | | | at the beginning of the life of the entity and | 608 | | | stored. It MUST NOT be smaller than 128 bits. See | 609 | | | the length analysis in Appendix B. | 610 | 0x02 | IEEE | This uses the IEEE company identification registry. | 611 | | EUI | An EUI is either an EUI-48, EUI-60 or EUI-64 and | 612 | | | made up of an OUI, OUI-36 or a CID, different | 613 | | | registered company identifiers, and some unique | 614 | | | per-entity identifier. EUIs are often the same as | 615 | | | or similar to MAC addresses. This type includes | 616 | | | MAC-48, an obsolete name for EUI-48. (Note that | 617 | | | while entities with multiple network interfaces may | 618 | | | have multiple MAC addresses, there is only one UEID | 619 | | | for an entity) [IEEE.802-2001], [OUI.Guide]. | 620 | 0x03 | IMEI | This is a 14-digit identifier consisting of an | 621 | | | 8-digit Type Allocation Code and a 6-digit serial | 622 | | | number allocated by the manufacturer, which SHALL | 623 | | | be encoded as byte string of length 14 with each | 624 | | | byte as the digit's value (not the ASCII encoding | 625 | | | of the digit; the digit 3 encodes as 0x03, not | 626 | | | 0x33). The IMEI value encoded SHALL NOT include | 627 | | | Luhn checksum or SVN information. See | 628 | | | [ThreeGPP.IMEI]. | 629 +------+------+-----------------------------------------------------+ 631 Table 1: UEID Composition Types 633 UEIDs are not designed for direct use by humans (e.g., printing on 634 the case of a device), so no textual representation is defined. 636 The consumer (the Relying Party) of a UEID MUST treat a UEID as a 637 completely opaque string of bytes and not make any use of its 638 internal structure. For example, they should not use the OUI part of 639 a type 0x02 UEID to identify the manufacturer of the entity. 640 Instead, they should use the OEMID claim. See Section 3.6. The 641 reasons for this are: 643 o UEIDs types may vary freely from one manufacturer to the next. 645 o New types of UEIDs may be created. For example, a type 0x07 UEID 646 may be created based on some other manufacturer registration 647 scheme. 649 o Entity manufacturers are allowed to change from one type of UEID 650 to another anytime they want. For example, they may find they can 651 optimize their manufacturing by switching from type 0x01 to type 652 0x02 or vice versa. The essential requirement on the manufacturer 653 is that UEIDs be universally unique. 655 A Device Identifier URN is registered for UEIDs. See Section 9.3.4. 657 $$claims-set-claims //= (ueid-label => ueid-type) 659 ueid-type = bstr .size (7..33) 661 3.5. Semi-permanent UEIDs (SUEIDs) 663 An SEUID is of the same format as a UEID, but it MAY change to a 664 different value on device life-cycle events. Examples of these 665 events are change of ownership, factory reset and on-boarding into an 666 IoT device management system. An entity MAY have both a UEID and 667 SUEIDs, neither, one or the other. 669 There MAY be multiple SUEIDs. Each one has a text string label the 670 purpose of which is to distinguish it from others in the token. The 671 label MAY name the purpose, application or type of the SUEID. 672 Typically, there will be few SUEDs so there is no need for a formal 673 labeling mechanism like a registry. The EAT profile MAY describe how 674 SUEIDs should be labeled. If there is only one SUEID, the claim 675 remains a map and there still must be a label. For example, the 676 label for the SUEID used by FIDO Onboarding Protocol could simply be 677 "FDO". 679 There are privacy considerations for SUEIDs. See Section 10.1. 681 A Device Indentifier URN is registered for SUEIDs. See 682 Section 9.3.4. 684 $$claims-set-claims //= (sueids-label => sueids-type) 686 sueids-type = { 687 + tstr => ueid-type 688 } 690 3.6. Hardware OEM Identification (oemid) 692 This claim identifies the Original Equipment Manufacturer (OEM) of 693 the hardware. Any of the three forms described below MAY be used at 694 the convenience of the claim sender. The receiver of this claim MUST 695 be able to handle all three forms. 697 3.6.1. Random Number Based OEMID 699 The random number based OEMID MUST always 16 bytes (128 bits). 701 The OEM MAY create their own ID by using a cryptographic-quality 702 random number generator. They would perform this only once in the 703 life of the company to generate the single ID for said company. They 704 would use that same ID in every entity they make. This uniquely 705 identifies the OEM on a statistical basis and is large enough should 706 there be ten billion companies. 708 The OEM MAY also use a hash function like SHA-256 and truncate the 709 output to 128 bits. The input to the hash should be somethings that 710 have at least 96 bits of entropy, but preferably 128 bits of entropy. 711 The input to the hash MAY be something whose uniqueness is managed by 712 a central registry like a domain name. 714 In JSON format tokens this MUST be base64url encoded. 716 3.6.2. IEEE Based OEMID 718 The IEEE operates a global registry for MAC addresses and company 719 IDs. This claim uses that database to identify OEMs. The contents 720 of the claim may be either an IEEE MA-L, MA-M, MA-S or an IEEE CID 721 [IEEE.RA]. An MA-L, formerly known as an OUI, is a 24-bit value used 722 as the first half of a MAC address. MA-M similarly is a 28-bit value 723 uses as the first part of a MAC address, and MA-S, formerly known as 724 OUI-36, a 36-bit value. Many companies already have purchased one of 725 these. A CID is also a 24-bit value from the same space as an MA-L, 726 but not for use as a MAC address. IEEE has published Guidelines for 727 Use of EUI, OUI, and CID [OUI.Guide] and provides a lookup service 728 [OUI.Lookup]. 730 Companies that have more than one of these IDs or MAC address blocks 731 SHOULD select one and prefer that for all their entities. 733 Commonly, these are expressed in Hexadecimal Representation as 734 described in [IEEE.802-2001]. It is also called the Canonical 735 format. When this claim is encoded the order of bytes in the bstr 736 are the same as the order in the Hexadecimal Representation. For 737 example, an MA-L like "AC-DE-48" would be encoded in 3 bytes with 738 values 0xAC, 0xDE, 0x48. 740 This format is always 3 bytes in size in CBOR. 742 In JSON format tokens, this MUST be base64url encoded and always 4 743 bytes. 745 3.6.3. IANA Private Enterprise Number Based OEMID 747 IANA maintains a integer-based company registry called the Private 748 Enterprise Number (PEN) [PEN]. 750 PENs are often used to create an OID. That is not the case here. 751 They are used only as an integer. 753 In CBOR this value MUST be encoded as a major type 0 integer and is 754 typically 3 bytes. In JSON, this value MUST be encoded as a number. 756 oemid-pen = int 758 oemid-ieee = bstr .size 3 760 oemid-random = bstr .size 16 762 $$claims-set-claims //= ( 763 oemid-label => 764 oemid-random / oemid-ieee / oemid-pen 765 ) 767 3.7. Hardware Model Claim (hardware-model) 769 This claim differentiates hardware models, products and variants 770 manufactured by a particular OEM, the one identified by OEM ID in 771 Section 3.6. 773 This claim must be unique so as to differentiate the models and 774 products for the OEM ID. This claim does not have to be globally 775 unique, but it can be. A receiver of this claim MUST not assume it 776 is globally unique. To globally identify a particular product, the 777 receiver should concatenate the OEM ID and this claim. 779 The granularity of the model identification is for each OEM to 780 decide. It may be very granular, perhaps including some version 781 information. It may be very general, perhaps only indicating top- 782 level products. 784 The purpose of this claim is to identify models within protocols, not 785 for human-readable descriptions. The format and encoding of this 786 claim should not be human-readable to discourage use other than in 787 protocols. If this claim is to be derived from an already-in-use 788 human-readable identifier, it can be run through a hash function. 790 There is no minimum length so that an OEM with a very small number of 791 models can use a one-byte encoding. The maximum length is 32 bytes. 792 All receivers of this claim MUST be able to receive this maximum 793 size. 795 The receiver of this claim MUST treat it as a completely opaque 796 string of bytes, even if there is some apparent naming or structure. 797 The OEM is free to alter the internal structure of these bytes as 798 long as the claim continues to uniquely identify its models. 800 hardware-model-type = bytes .size (1..32) 802 $$claims-set-claims //= ( 803 hardware-model-label => hardware-model-type 804 ) 806 3.8. Hardware Version Claims (hardware-version-claims) 808 The hardware version is a text string the format of which is set by 809 each manufacturer. The structure and sorting order of this text 810 string can be specified using the version-scheme item from CoSWID 811 [CoSWID]. It is useful to know how to sort versions so the newer can 812 be distinguished from the older. 814 The hardware version can also be given by a 13-digit [EAN-13]. A new 815 CoSWID version scheme is registered with IANA by this document in 816 Section 9.3.3. An EAN-13 is also known as an International Article 817 Number or most commonly as a bar code. 819 $$claims-set-claims //= ( 820 hardware-version-label => hardware-version-type 821 ) 823 hardware-version-type = [ 824 version: tstr, 825 scheme: $version-scheme 826 ] 828 3.9. Software Name Claim 830 This is a free-form text claim for the name of the software for the 831 entity or submodule. A CoSWID manifest or other type of manifest can 832 be used instead if this claim is to limited to correctly characterize 833 the SW for the entity or submodule. 835 $$claims-set-claims //= ( sw-name-label => tstr ) 837 3.10. Software Version Claim 839 This makes use of the CoSWID version scheme data type to give a 840 simple version for the software. A full CoSWID manifest or other 841 type of manifest can be instead if this is too simple. 843 $$claims-set-claims //= (sw-version-label => sw-version-type) 845 sw-version-type = [ 846 version: tstr, 847 scheme: $version-scheme ; As defined by CoSWID 848 ] 850 3.11. The Security Level Claim (security-level) 852 This claim characterizes the entity's ability to defend against 853 attacks aimed at capturing the signing key, forging claims and at 854 forging EATs. This is by defining four security levels. 856 This claim describes the security environment and countermeasures 857 available on the entity where the attestation key resides and the 858 claims originate. 860 1 - Unrestricted: There is some expectation that implementor will 861 protect the attestation signing keys at this level. Otherwise, 862 the EAT provides no meaningful security assurances. 864 2 - Restricted: Entities at this level are not general-purpose 865 operating environments that host features, such as app download 866 systems, web browsers and complex applications. It is akin to the 867 secure-restricted level (see below) without the security 868 orientation. Examples include a Wi-Fi subsystem, an IoT camera, 869 or sensor device. Often these can be considered more secure than 870 unrestricted just because they are much simpler and a smaller 871 attack surface, but this won't always be the case. Some 872 unrestricted devices may be implemented in a way that provides 873 poor protection of signing keys. 875 3 - Secure-Restricted: Entities at this level must meet the criteria 876 defined in Section 4 of FIDO Allowed Restricted Operating 877 Environments [FIDO.AROE]. Examples include TEE's and schemes 878 using virtualization-based security. Security at this level is 879 aimed at defending against large-scale network/remote attacks 880 against the entity. 882 4 - Hardware: Entities at this level must include substantial 883 defense against physical or electrical attacks against the entity 884 itself. It is assumed the potential attacker has captured the 885 entity and can disassemble it. Examples include TPMs and Secure 886 Elements. 888 The entity should claim the highest security level it achieves and no 889 higher. This set is not extensible so as to provide a common 890 interoperable description of security level to the Relying Party. If 891 a particular use case considers this claim to be inadequate, it can 892 define its own proprietary claim. It may consider including both 893 this claim as a coarse indication of security and its own proprietary 894 claim as a refined indication. 896 This claim is not intended as a replacement for a formal security 897 certification scheme, such as those based on FIPS 140 [FIPS-140] or 898 those based on Common Criteria [Common.Criteria]. See Section 3.21. 900 $$claims-set-claims //= ( 901 security-level-label => 902 security-level-cbor-type / 903 security-level-json-type 904 ) 906 security-level-cbor-type = &( 907 unrestricted: 1, 908 restricted: 2, 909 secure-restricted: 3, 910 hardware: 4 911 ) 913 security-level-json-type = 914 "unrestricted" / 915 "restricted" / 916 "secure-restricted" / 917 "hardware" 919 3.12. Secure Boot Claim (secure-boot) 921 The value of true indicates secure boot is enabled. Secure boot is 922 considered enabled when the firmware and operating system, are under 923 control of the manufacturer of the entity identified in the OEMID 924 claim described in Section 3.6. Control by the manufacturer of the 925 firmware and the operating system may be by it being in ROM, being 926 cryptographically authenticated, a combination of the two or similar. 928 $$claims-set-claims //= (secure-boot-label => bool) 930 3.13. Debug Status Claim (debug-status) 932 This applies to entity-wide or submodule-wide debug facilities of the 933 entity like JTAG and diagnostic hardware built into chips. It 934 applies to any software debug facilities related to root, operating 935 system or privileged software that allow system-wide memory 936 inspection, tracing or modification of non-system software like user 937 mode applications. 939 This characterization assumes that debug facilities can be enabled 940 and disabled in a dynamic way or be disabled in some permanent way 941 such that no enabling is possible. An example of dynamic enabling is 942 one where some authentication is required to enable debugging. An 943 example of permanent disabling is blowing a hardware fuse in a chip. 944 The specific type of the mechanism is not taken into account. For 945 example, it does not matter if authentication is by a global password 946 or by per-entity public keys. 948 As with all claims, the absence of the debug level claim means it is 949 not reported. A conservative interpretation might assume the enabled 950 state. 952 This claim is not extensible so as to provide a common interoperable 953 description of debug status. If a particular implementation 954 considers this claim to be inadequate, it can define its own 955 proprietary claim. It may consider including both this claim as a 956 coarse indication of debug status and its own proprietary claim as a 957 refined indication. 959 The higher levels of debug disabling requires that all debug 960 disabling of the levels below it be in effect. Since the lowest 961 level requires that all of the target's debug be currently disabled, 962 all other levels require that too. 964 There is no inheritance of claims from a submodule to a superior 965 module or vice versa. There is no assumption, requirement or 966 guarantee that the target of a superior module encompasses the 967 targets of submodules. Thus, every submodule must explicitly 968 describe its own debug state. The receiver of an EAT MUST not assume 969 that debug is turned off in a submodule because there is a claim 970 indicating it is turned off in a superior module. 972 An entity may have multiple debug facilities. The use of plural in 973 the description of the states refers to that, not to any aggregation 974 or inheritance. 976 The architecture of some chips or devices may be such that a debug 977 facility operates for the whole chip or device. If the EAT for such 978 a chip includes submodules, then each submodule should independently 979 report the status of the whole-chip or whole-device debug facility. 980 This is the only way the receiver can know the debug status of the 981 submodules since there is no inheritance. 983 3.13.1. Enabled 985 If any debug facility, even manufacturer hardware diagnostics, is 986 currently enabled, then this level must be indicated. 988 3.13.2. Disabled 990 This level indicates all debug facilities are currently disabled. It 991 may be possible to enable them in the future. It may also be that 992 they were enabled in the past, but they are currently disabled. 994 3.13.3. Disabled Since Boot 996 This level indicates all debug facilities are currently disabled and 997 have been so since the entity booted/started. 999 3.13.4. Disabled Permanently 1001 This level indicates all non-manufacturer facilities are permanently 1002 disabled such that no end user or developer can enable them. Only 1003 the manufacturer indicated in the OEMID claim can enable them. This 1004 also indicates that all debug facilities are currently disabled and 1005 have been so since boot/start. 1007 3.13.5. Disabled Fully and Permanently 1009 This level indicates that all debug facilities for the entity are 1010 permanently disabled. 1012 $$claims-set-claims //= ( 1013 debug-status-label => 1014 debug-status-cbor-type / debug-status-json-type 1015 ) 1017 debug-status-cbor-type = &( 1018 enabled: 0, 1019 disabled: 1, 1020 disabled-since-boot: 2, 1021 disabled-permanently: 3, 1022 disabled-fully-and-permanently: 4 1023 ) 1025 debug-status-json-type = 1026 "enabled" / 1027 "disabled" / 1028 "disabled-since-boot" / 1029 "disabled-permanently" / 1030 "disabled-fully-and-permanently" 1032 3.14. Including Keys 1034 An EAT may include a cryptographic key such as a public key. The 1035 signing of the EAT binds the key to all the other claims in the 1036 token. 1038 The purpose for inclusion of the key may vary by use case. For 1039 example, the key may be included as part of an IoT device onboarding 1040 protocol. When the FIDO protocol includes a public key in its 1041 attestation message, the key represents the binding of a user, device 1042 and Relying Party. This document describes how claims containing 1043 keys should be defined for the various use cases. It does not define 1044 specific claims for specific use cases. 1046 Keys in CBOR format tokens SHOULD be the COSE_Key format [RFC8152] 1047 and keys in JSON format tokens SHOULD be the JSON Web Key format 1048 [RFC7517]. These two formats support many common key types. Their 1049 use avoids the need to decode other serialization formats. These two 1050 formats can be extended to support further key types through their 1051 IANA registries. 1053 The general confirmation claim format [RFC8747], [RFC7800] may also 1054 be used. It provides key encryption. It also allows for inclusion 1055 by reference through a key ID. The confirmation claim format may 1056 employed in the definition of some new claim for a a particular use 1057 case. 1059 When the actual confirmation claim is included in an EAT, this 1060 document associates no use case semantics other than proof of 1061 possession. Different EAT use cases may choose to associate further 1062 semantics. The key in the confirmation claim MUST be protected in 1063 the same way as the key used to sign the EAT. That is, the same, 1064 equivalent or better hardware defenses, access controls, key 1065 generation and such must be used. 1067 3.15. The Location Claim (location) 1069 The location claim gives the location of the entity from which the 1070 attestation originates. It is derived from the W3C Geolocation API 1071 [W3C.GeoLoc]. The latitude, longitude, altitude and accuracy must 1072 conform to [WGS84]. The altitude is in meters above the [WGS84] 1073 ellipsoid. The two accuracy values are positive numbers in meters. 1074 The heading is in degrees relative to true north. If the entity is 1075 stationary, the heading is NaN (floating-point not-a-number). The 1076 speed is the horizontal component of the entity velocity in meters 1077 per second. 1079 When encoding floating-point numbers half-precision SHOULD NOT be 1080 used. They usually do not provide enough precision for a geographic 1081 location. 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 = 1 / "latitude" 1112 longitude = 2 / "longitude" 1113 altitude = 3 / "altitude" 1114 accuracy = 4 / "accuracy" 1115 altitude-accuracy = 5 / "altitude-accuracy" 1116 heading = 6 / "heading" 1117 speed = 7 / "speed" 1118 timestamp = 8 / "timestamp" 1119 age = 9 / "age" 1121 3.16. 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 3.17. 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 3.18. 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 => bytes) 1148 3.19. The Intended Use Claim (intended-use) 1150 EAT's may be used in the context of several different applications. 1151 The intended-use claim provides an indication to an EAT consumer 1152 about the intended usage of the token. This claim can be used as a 1153 way for an application using EAT to internally distinguish between 1154 different ways it uses EAT. 1156 1 - Generic: Generic attestation describes an application where the 1157 EAT consumer requires the most up-to-date security assessment of 1158 the attesting entity. It is expected that this is the most 1159 commonly-used application of EAT. 1161 2- Registration: Entities that are registering for a new service may 1162 be expected to provide an attestation as part of the registration 1163 process. This intended-use setting indicates that the attestation 1164 is not intended for any use but registration. 1166 3 - Provisioning: Entities may be provisioned with different values 1167 or settings by an EAT consumer. Examples include key material or 1168 device management trees. The consumer may require an EAT to 1169 assess entity security state of the entity prior to provisioning. 1171 4 - Certificate Issuance Certification Authorities (CA's) may 1172 require attestations prior to the issuance of certificates related 1173 to keypairs hosted at the entity. An EAT may be used as part of 1174 the certificate signing request (CSR). 1176 5 - Proof-of-Possession: An EAT consumer may require an attestation 1177 as part of an accompanying proof-of-possession (PoP) application. 1178 More precisely, a PoP transaction is intended to provide to the 1179 recipient cryptographically-verifiable proof that the sender has 1180 possession of a key. This kind of attestation may be necceesary 1181 to verify the security state of the entity storing the private key 1182 used in a PoP application. 1184 $$claims-set-claims //= ( 1185 intended-use-label => 1186 intended-use-cbor-type / intended-use-json-type 1187 ) 1189 intended-use-cbor-type = &( 1190 generic: 1, 1191 registration: 2, 1192 provisioning: 3, 1193 csr: 4, 1194 pop: 5 1195 ) 1197 intended-use-json-type = 1198 "generic" / 1199 "registration" / 1200 "provisioning" / 1201 "csr" / 1202 "pop" 1204 3.20. The Profile Claim (profile) 1206 See Section 7 for the detailed description of a profile. 1208 A profile is identified by either a URL or an OID. Typically, the 1209 URI will reference a document describing the profile. An OID is just 1210 a unique identifier for the profile. It may exist anywhere in the 1211 OID tree. There is no requirement that the named document be 1212 publicly accessible. The primary purpose of the profile claim is to 1213 uniquely identify the profile even if it is a private profile. 1215 The OID is always absolute and never relative. In CBOR tokens, the 1216 OID MUST be encoded according to [RFC9090] and the URI according to 1217 [RFC8949]. Both are unwrapped and thus not CBOR tags. In JSON 1218 tokens, the OID is a string of the form "X.X.X", and a URI is a 1219 normal URI string. 1221 Note that this is named "eat_profile" for JWT and is distinct from 1222 the already registered "profile" claim in the JWT claims registry. 1224 $$claims-set-claims //= (profile-label => ~uri / ~oid) 1226 3.21. The DLOA (Digital Letter or Approval) Claim (dloas) 1228 A DLOA (Digital Letter of Approval) [DLOA] is an XML document that 1229 describes a certification that an entity has received. Examples of 1230 certifications represented by a DLOA include those issued by Global 1231 Platform and those based on Common Criteria. The DLOA is unspecific 1232 to any particular certification type or those issued by any 1233 particular organization. 1235 This claim is typically issued by a Verifier, not an Attester. When 1236 this claim is issued by a Verifier, it MUST be because the entity has 1237 received the certification in the DLOA. 1239 This claim MAY contain more than one DLOA. If multiple DLOAs are 1240 present, it MUST be because the entity received all of the 1241 certifications. 1243 DLOA XML documents are always fetched from a registrar that stores 1244 them. This claim contains several data items used to construct a URL 1245 for fetching the DLOA from the particular registrar. 1247 This claim MUST be encoded as an array with either two or three 1248 elements. The first element MUST be the URI for the registrar. The 1249 second element MUST be a platform label indicating which platform was 1250 certified. If the DLOA applies to an application, then the third 1251 element is added which MUST be an application label. The method of 1252 constructing the registrar URI, platform label and possibly 1253 application label is specified in [DLOA]. 1255 $$claims-set-claims //= ( 1256 dloas-label => [ + dloa-type ] 1257 ) 1259 dloa-type = [ 1260 dloa_registrar: ~uri 1261 dloa_platform_label: text 1262 ? dloa_application_label: text 1263 ] 1265 3.22. The Software Manifests Claim (manifests) 1267 This claim contains descriptions of software present on the entity. 1268 These manifests are installed on the entity when the software is 1269 installed or are created as part of the installation process. 1270 Installation is anything that adds software to the entity, possibly 1271 factory installation, the user installing elective applications and 1272 so on. The defining characteristic is they are created by the 1273 software manufacturer. The purpose of these claims in an EAT is to 1274 relay them without modification to the Verifier and possibly to the 1275 Relying Party. 1277 Some manifests may be signed by their software manufacturer before 1278 they are put into this EAT claim. When such manifests are put into 1279 this claim, the manufacturer's signature SHOULD be included. For 1280 example, the manifest might be a CoSWID signed by the software 1281 manufacturer, in which case the full signed CoSWID should be put in 1282 this claim. 1284 This claim allows multiple formats for the manifest. For example, 1285 the manifest may be a CBOR-format CoSWID, an XML-format SWID or 1286 other. Identification of the type of manifest is always by a CBOR 1287 tag. In many cases, for examples CoSWID, a tag will already be 1288 registered with IANA. If not, a tag MUST be registered. It can be 1289 in the first-come-first-served space which has minimal requirements 1290 for registration. 1292 The claim is an array of one or more manifests. To facilitate hand 1293 off of the manifest to a decoding library, each manifest is contained 1294 in a byte string. This occurs for CBOR-format manifests as well as 1295 non-CBOR format manifests. 1297 If a particular manifest type uses CBOR encoding, then the item in 1298 the array for it MUST be a byte string that contains a CBOR tag. The 1299 EAT decoder must decode the byte string and then the CBOR within it 1300 to find the tag number to identify the type of manifest. The 1301 contents of the byte string is then handed to the particular manifest 1302 processor for that type of manifest. CoSWID and SUIT manifest are 1303 examples of this. 1305 If a particular manifest type does not use CBOR encoding, then the 1306 item in the array for it MUST be a CBOR tag that contains a byte 1307 string. The EAT decoder uses the tag to identify the processor for 1308 that type of manifest. The contents of the tag, the byte string, are 1309 handed to the manifest processor. Note that a byte string is used to 1310 contain the manifest whether it is a text based format or not. An 1311 example of this is an XML format ISO/IEC 19770 SWID. 1313 It is not possible to describe the above requirements in CDDL, so the 1314 type for an individual manifest is any in the CDDL below. The above 1315 text sets the encoding requirement. 1317 This claim allows for multiple manifests in one token since multiple 1318 software packages are likely to be present. The multiple manifests 1319 MAY be of multiple formats. In some cases EAT submodules may be used 1320 instead of the array structure in this claim for multiple manifests. 1322 When the [CoSWID] format is used, it MUST be a payload CoSWID, not an 1323 evidence CoSWID. 1325 $$claims-set-claims //= ( 1326 manifests-label => manifests-type 1327 ) 1329 manifests-type = [+ $$manifest-formats] 1331 coswid-that-is-a-cbor-tag-xx = tagged-coswid 1333 $$manifest-formats /= bytes .cbor coswid-that-is-a-cbor-tag-xx 1335 3.23. The Software Evidence Claim (swevidence) 1337 This claim contains descriptions, lists, evidence or measurements of 1338 the software that exists on the entity. The defining characteristic 1339 of this claim is that its contents are created by processes on the 1340 entity that inventory, measure or otherwise characterize the software 1341 on the entity. The contents of this claim do not originate from the 1342 software manufacturer. 1344 This claim uses the same mechanism for identification of the type of 1345 the swevidence as is used for the type of the manifest in the 1346 manifests claim. It also uses the same byte string based mechanism 1347 for containing the claim and easing the hand off to a processing 1348 library. See the discussion above in the manifests claim. 1350 When the [CoSWID] format is used, it MUST be evidence CoSWIDs, not 1351 payload CoSWIDS. 1353 $$claims-set-claims //= ( 1354 swevidence-label => swevidence-type 1355 ) 1357 swevidence-type = [+ $$swevidence-formats] 1359 coswid-that-is-a-cbor-tag = tagged-coswid 1360 $$swevidence-formats /= bytes .cbor coswid-that-is-a-cbor-tag 1362 3.24. The SW Measurement Results Claim (swresults) 1364 This claims reports the outcome of the comparison of a measurement on 1365 some software to the expected Reference Values. It may report a 1366 successful comparison, failed comparison or other. 1368 This claim MAY be generated by the Verifier and sent to the Relying 1369 Party. For example, it could be the results of the Verifier 1370 comparing the contents of the swevidence claim to Reference Values. 1372 This claim MAY also be generated on the entity if the entity has the 1373 ability for one subsystem to measure another subsystem. For example, 1374 a TEE might have the ability to measure the software of the rich OS 1375 and may have the Reference Values for the rich OS. 1377 Within an attestation target or submodule, multiple results can be 1378 reported. For example, it may be desirable to report the results for 1379 the kernel and each individual application separately. 1381 For each software objective, the following can be reported. TODO: 1382 defined objective 1384 3.24.1. Scheme 1386 This is the free-form text name of the verification system or scheme 1387 that performed the verification. There is no official registry of 1388 schemes or systems. It may be the name of a commercial product or 1389 such. 1391 3.24.2. Objective 1393 This roughly characterizes the coverage of the software measurement 1394 software. This corresponds to the attestation target or the 1395 submodule. If all of the indicated target is not covered, the 1396 measurement must indicate partial. 1398 1 - all: Indicates all the software has been verified, for example, 1399 all the software in the attestation target or the submodule 1401 2 - firmware: Indicates all of and only the firmware 1403 3 - kernel: Refers to all of the most-privileged software, for 1404 example the Linux kernel 1406 4 - privileged: Refers to all of the software used by the root, 1407 system or administrative account 1409 5 - system-libs: Refers to all of the system libraries that are 1410 broadly shared and used by applications and such 1412 6 - partial: Some other partial set of the software 1414 3.24.3. Results 1416 This describes the result of the measurement and also the comparison 1417 to Reference Values. 1419 1 - verification-not-run: Indicates that no attempt was made to run 1420 the verification 1422 2 - verification-indeterminite: The verification was attempted, but 1423 it did not produce a result; perhaps it ran out of memory, the 1424 battery died or such 1426 3 - verification-failed: The verification ran to completion, the 1427 comparison was completed and did not compare correctly to the 1428 Reference Values 1430 4 - fully-verified: The verification ran to completion and all 1431 measurements compared correctly to Reference Values 1433 5 - partially-verified: The verification ran to completion and some, 1434 but not all, measurements compared correctly to Reference Values 1436 3.24.4. Objective Name 1438 This is a free-form text string that describes the objective. For 1439 example, "Linux kernel" or "Facebook App" 1440 $$claims-set-claims //= (swresults-label => [ + swresult-type ]) 1442 verification-result-cbor-type = &( 1443 verification-not-run: 1, 1444 verification-indeterminate: 2, 1445 verification-failed: 3, 1446 fully-verified: 4, 1447 partially-verified: 5, 1448 ) 1450 verification-result-json-type = 1451 "verification-not-run" / 1452 "verification-indeterminate" / 1453 "verification-failed" / 1454 "fully-verified" / 1455 "partially-verified" 1457 verification-objective-cbor-type = &( 1458 all: 1, 1459 firmware: 2, 1460 kernel: 3, 1461 privileged: 4, 1462 system-libs: 5, 1463 partial: 6, 1464 ) 1466 verification-objective-json-type = 1467 "all" / 1468 "firmware" / 1469 "kernel" / 1470 "privileged" / 1471 "system-libs" / 1472 "partial" 1474 swresult-type = [ 1475 verification-system: tstr, 1476 objective: verification-objective-cbor-type / 1477 verification-objective-json-type, 1478 result: verification-result-cbor-type / 1479 verification-result-json-type, 1480 ? objective-name: tstr 1481 ] 1483 3.25. Submodules (submods) 1485 Some devices are complex, having many subsystems. A mobile phone is 1486 a good example. It may have several connectivity subsystems for 1487 communications (e.g., Wi-Fi and cellular). It may have subsystems 1488 for low-power audio and video playback. It may have multiple 1489 security-oriented subsystems like a TEE and a Secure Element. 1491 The claims for a subsystem can be grouped together in a submodule or 1492 submod. 1494 The submods are in a single map/object, one entry per submodule. 1495 There is only one submods map/object in a token. It is identified by 1496 its specific label. It is a peer to other claims, but it is not 1497 called a claim because it is a container for a claims set rather than 1498 an individual claim. This submods part of a token allows what might 1499 be called recursion. It allows claims sets inside of claims sets 1500 inside of claims sets... 1502 3.25.1. Submodule Types 1504 The following sections define the three types of submodules: 1506 o A submodule Claims-Set 1508 o A nested token, which can be any valid EAT token, CBOR or JSON 1510 o The digest of a detached Claims-Set 1512 3.25.1.1. Submodule Claims-Set 1514 This is a subordinate Claims-Set containing claims about the 1515 submodule. 1517 The submodule claims-set is produced by the same Attester as the 1518 surrounding token. It is secured using the same mechanism as the 1519 enclosing token (e.g., it is signed by the same attestation key). It 1520 roughly corresponds to an Attester Target Environment, as described 1521 in the RATS architecture. 1523 It may contain claims that are the same as its surrounding token or 1524 superior submodules. For example, the top-level of the token may 1525 have a UEID, a submod may have a different UEID and a further 1526 subordinate submodule may also have a UEID. 1528 The encoding of a submodule Claims-Set MUST be the same as the 1529 encoding as the token it is part of. 1531 This data type for this type of submodule is a map/object. It is 1532 identified when decoding by it's type being a map/object. 1534 3.25.1.2. Nested Token 1536 This type of submodule is a fully formed complete token. It is 1537 typically produced by a separate Attester. It is typically used by a 1538 Composite Device as described in RATS Architecture 1539 [RATS.Architecture] In being a submodule of the surrounding token, it 1540 is cryptographically bound to the surrounding token. If it was 1541 conveyed in parallel with the surrounding token, there would be no 1542 such binding and attackers could substitute a good attestation from 1543 another device for the attestation of an errant subsystem. 1545 A nested token does not need to use the same encoding as the 1546 enclosing token. This is to allow Composite Devices to be built 1547 without regards to the encoding supported by their Attesters. Thus a 1548 CBOR-encoded token like a CWT or UCCS can have a JWT as a nested 1549 token submodule and a JSON-encoded token can have a CWT or UCCS as a 1550 nested token submodule. 1552 The following two sections describe how to encode and decode a nested 1553 token. 1555 3.25.1.2.1. Surrounding EAT is CBOR-Encoded 1557 This describes the encoding and decoding of CBOR or JSON-encoded 1558 tokens nested inside a CBOR-encoded token. 1560 If the nested token is CBOR-encoded, then it MUST be a CBOR tag and 1561 MUST be wrapped in a byte string. The tag identifies whether the 1562 nested token is a CWT, a UCCS, a CBOR-encoded DEB, or some other 1563 CBOR-format token defined in the future. A nested CBOR-encoded token 1564 that is not a CBOR tag is NOT allowed. 1566 If the nested token is JSON-encoded, then the data item MUST be a 1567 text string. The text string MUST contain a JSON-encoded array of 1568 two items. The first item is a string identifying the type of the 1569 token. The second item is the JSON-encoded token. 1571 The string identifying the JSON-encoded token MUST be one of the 1572 following: 1574 "JWT": The second item MUST be a JWT formatted according to 1575 [RFC7519] 1577 "UJCS": The second item MUST be a UJCS-Message as defined in this 1578 document. 1580 "DEB": The second item MUST be a JSON-encoded Detached EAT Bundle as 1581 defined in this document. 1583 The definition of additional types requires a standards action. 1585 When decoding, if a byte string is encountered, it is known to be a 1586 nested CBOR-encoded token. The byte string wrapping is removed. The 1587 type of the token is determined by the CBOR tag. 1589 When decoding, if a text string is encountered, it is known to be a 1590 JSON-encoded token. The two-item array is decoded and tells the type 1591 of the JSON-encoded token. 1593 Nested-Token = 1594 tstr / ; A JSON-encoded Nested-Token (see json-nested-token.cddl) 1595 bstr .cbor Tagged-CBOR-Token 1597 3.25.1.2.2. Surrounding EAT is JSON-Encoded 1599 This describes the encoding and decoding of CBOR or JSON-encoded 1600 tokens nested inside a JSON-encoded token. 1602 The nested token MUST be an array of two in the same format as 1603 described in the section above. 1605 A CBOR-encoded token nested inside a JSON-encoded MUST use the same 1606 array of two, but with the type as follows: 1608 "CBOR": Some base64url-encoded CBOR that is a tag, typically a CWT, 1609 UCCS or CBOR-encoded DEB 1611 When decoding, the array of two is decoded. The first item indicates 1612 the type and encoding of the nested token. If the type string is not 1613 "CBOR", then the token is JSON-encoded and of the type indicated by 1614 the string. 1616 If the type string is "CBOR", then the token is CBOR-encoded. The 1617 base64url encoding is removed. The CBOR-encoded data is then 1618 decoded. The type of nested token is determined by the CBOR-tag. It 1619 is an error if the CBOR is not a tag. 1621 Nested-Token = [ 1622 type : "JWT" / "CBOR" / "UJCS" / "DEB", 1623 nested-token : JWT-Message / 1624 B64URL-Tagged-CBOR-Token / 1625 DEB-JSON-Message / 1626 UJCS-Message 1627 ] 1629 B64URL-Tagged-CBOR-Token = tstr .regexp "[A-Za-z0-9_=-]+" 1631 3.25.1.3. Detached Submodule Digest 1633 This is type of submodule equivalent to a Claims-Set submodule, 1634 except the Claims-Set is conveyed separately outside of the token. 1636 This type of submodule consists of a digest made using a 1637 cryptographic hash of a Claims-Set. The Claims-Set is not included 1638 in the token. It is conveyed to the Verifier outside of the token. 1639 The submodule containing the digest is called a detached digest. The 1640 separately conveyed Claims-Set is called a detached claims set. 1642 The input to the digest is exactly the byte-string wrapped encoded 1643 form of the Claims-Set for the submodule. That Claims-Set can 1644 include other submodules including nested tokens and detached 1645 digests. 1647 The primary use for this is to facilitate the implementation of a 1648 small and secure attester, perhaps purely in hardware. This small, 1649 secure attester implements COSE signing and only a few claims, 1650 perhaps just UEID and hardware identification. It has inputs for 1651 digests of submodules, perhaps 32-byte hardware registers. Software 1652 running on the device constructs larger claim sets, perhaps very 1653 large, encodes them and digests them. The digests are written into 1654 the small secure attesters registers. The EAT produced by the small 1655 secure attester only contains the UEID, hardware identification and 1656 digests and is thus simple enough to be implemented in hardware. 1657 Probably, every data item in it is of fixed length. 1659 The integrity protection for the larger Claims Sets will not be as 1660 secure as those originating in hardware block, but the key material 1661 and hardware-based claims will be. It is possible for the hardware 1662 to enforce hardware access control (memory protection) on the digest 1663 registers so that some of the larger claims can be more secure. For 1664 example, one register may be writable only by the TEE, so the 1665 detached claims from the TEE will have TEE-level security. 1667 The data type for this type of submodule MUST be an array It contains 1668 two data items, an algorithm identifier and a byte string containing 1669 the digest. 1671 When decoding a CBOR format token the detached digest type is 1672 distringuished from the other types by it being an array. In CBOR 1673 the none of other submodule types are arrays. 1675 When decoding a JSON format token, a little more work is required 1676 because both the nested token and detached digest types are an array. 1677 To distinguish the nested token from the detached digest, the first 1678 element in the array is examined. If it is "JWT", "UJCS" or "DEB", 1679 the the submodule is a nested token. Otherwise it will contain an 1680 algorithm identifier and is a detached digest. 1682 A DEB, described in Section 5, may be used to convey detached claims 1683 sets and the token with their detached digests. EAT, however, 1684 doesn't require use of a DEB. Any other protocols may be used to 1685 convey detached claims sets and the token with their detached 1686 digests. Note that since detached Claims-Sets are usually signed, 1687 protocols conveying them must make sure they are not modified in 1688 transit. 1690 3.25.2. No Inheritance 1692 The subordinate modules do not inherit anything from the containing 1693 token. The subordinate modules must explicitly include all of their 1694 claims. This is the case even for claims like the nonce. 1696 This rule is in place for simplicity. It avoids complex inheritance 1697 rules that might vary from one type of claim to another. 1699 3.25.3. Security Levels 1701 The security level of the non-token subordinate modules should always 1702 be less than or equal to that of the containing modules in the case 1703 of non-token submodules. It makes no sense for a module of lesser 1704 security to be signing claims of a module of higher security. An 1705 example of this is a TEE signing claims made by the non-TEE parts 1706 (e.g. the high-level OS) of the device. 1708 The opposite may be true for the nested tokens. They usually have 1709 their own more secure key material. An example of this is an 1710 embedded secure element. 1712 3.25.4. Submodule Names 1714 The label or name for each submodule in the submods map is a text 1715 string naming the submodule. No submodules may have the same name. 1717 3.25.5. CDDL for submods 1719 The submodule type is distinguished in the encoded bytes by its data 1720 type, map/object for a Claims-Set, string for nested token and array 1721 for a detached submodule. Nested tokens are byte-string wrapped when 1722 encoded in CBOR and base64 encoded for JSON. 1724 $$claims-set-claims //= (submods-label => { + text => Submodule }) 1726 Submodule = Claims-Set / Nested-Token / Detached-Submodule-Digest 1728 Detached-Submodule-Digest = [ 1729 algorithm : int / text, 1730 digest : bstr 1731 ] 1733 4. Unprotected JWT Claims-Sets 1735 This is simply the JSON equivalent of an Unprotected CWT Claims-Set 1736 [UCCS.Draft]. 1738 It has no protection of its own so protections must be provided by 1739 the protocol carrying it. These are extensively discussed in 1740 [UCCS.Draft]. All the security discussion and security 1741 considerations in [UCCS.Draft] apply to UJCS. 1743 (Note: The EAT author is open to this definition being moved into the 1744 UCCS draft, perhaps along with the related CDDL. It is place here 1745 for now so that the current UCCS draft plus this document are 1746 complete. UJCS is needed for the same use cases that a UCCS is 1747 needed. Further, JSON will commonly be used to convey Attestation 1748 Results since JSON is common for server to server communications. 1749 Server to server communications will often have established security 1750 (e.g., TLS) therefore the signing and encryption from JWS and JWE are 1751 unnecssary and burdensome). 1753 5. Detached EAT Bundles 1755 A detached EAT bundle is a structure to convey a fully-formed and 1756 signed token plus detached claims set that relate to that token. It 1757 is a top-level EAT message like a CWT, JWT, UCCS and UJCS. It can be 1758 used any place that CWT, JWT, UCCS or UJCS messages are used. It may 1759 also be sent as a submodule. 1761 A DEB has two main parts. 1763 The first part is a full top-level token. This top-level token must 1764 have at least one submodule that is a detached digest. This top- 1765 level token may be either CBOR or JSON-encoded. It may be a CWT, 1766 JWT, UCCS or UJCS, but not a DEB. The same mechanism for 1767 distinguishing the type for nested token submodules is used here. 1769 The second part is a map/object containing the detached Claims-Sets 1770 corresponding to the detached digests in the full token. When the 1771 DEB is CBOR-encoded, each Claims-Set is wrapped in a byte string. 1772 When the DEB is JSON-encoded, each Claims-Set is base64url encoded. 1773 All the detached Claims-Sets MUST be encoded in the same format as 1774 the DEB. No mixing of encoding formats is allowed for the Claims- 1775 Sets in a DEB. 1777 For CBOR-encoded DEBs, tag TBD602 can be used to identify it. The 1778 normal rules apply for use or non-use of a tag. When it is sent as a 1779 submodule, it is always sent as a tag to distinguish it from the 1780 other types of nested tokens. 1782 The digests of the detached claims sets are associated with detached 1783 claims-sets by label/name. It is up to the constructor of the 1784 detached EAT bundle to ensure the names uniquely identify the 1785 detached claims sets. Since the names are used only in the detached 1786 EAT bundle, they can be very short, perhaps one byte. 1788 Detached-EAT-Bundle = [ 1789 main-token : Nested-Token, 1790 detached-claims-sets: { 1791 + tstr => cbor-wrapped-claims-set / json-wrapped-claims-set 1792 } 1793 ] 1795 json-wrapped-claims-set = tstr .regexp "[A-Za-z0-9_=-]+" 1797 cbor-wrapped-claims-set = bstr .cbor Claims-Set 1799 6. Endorsements and Verification Keys 1801 The Verifier must possess the correct key when it performs the 1802 cryptographic part of an EAT verification (e.g., verifying the COSE/ 1803 JOSE signature). This section describes several ways to identify the 1804 verification key. There is not one standard method. 1806 The verification key itself may be a public key, a symmetric key or 1807 something complicated in the case of a scheme like Direct Anonymous 1808 Attestation (DAA). 1810 RATS Architecture [RATS.Architecture] describes what is called an 1811 Endorsement. This is an input to the Verifier that is usually the 1812 basis of the trust placed in an EAT and the Attester that generated 1813 it. It may contain the public key for verification of the signature 1814 on the EAT. It may contain Reference Values to which EAT claims are 1815 compared as part of the verification process. It may contain implied 1816 claims, those that are passed on to the Relying Party in Attestation 1817 Results. 1819 There is not yet any standard format(s) for an Endorsement. One 1820 format that may be used for an Endorsement is an X.509 certificate. 1821 Endorsement data like Reference Values and implied claims can be 1822 carried in X.509 v3 extensions. In this use, the public key in the 1823 X.509 certificate becomes the verification key, so identification of 1824 the Endorsement is also identification of the verification key. 1826 The verification key identification and establishment of trust in the 1827 EAT and the attester may also be by some other means than an 1828 Endorsement. 1830 For the components (Attester, Verifier, Relying Party,...) of a 1831 particular end-end attestation system to reliably interoperate, its 1832 definition should specify how the verification key is identified. 1833 Usually, this will be in the profile document for a particular 1834 attestation system. 1836 6.1. Identification Methods 1838 Following is a list of possible methods of key identification. A 1839 specific attestation system may employ any one of these or one not 1840 listed here. 1842 The following assumes Endorsements are X.509 certificates or 1843 equivalent and thus does not mention or define any identifier for 1844 Endorsements in other formats. If such an Endorsement format is 1845 created, new identifiers for them will also need to be created. 1847 6.1.1. COSE/JWS Key ID 1849 The COSE standard header parameter for Key ID (kid) may be used. See 1850 [RFC8152] and [RFC7515] 1852 COSE leaves the semantics of the key ID open-ended. It could be a 1853 record locator in a database, a hash of a public key, an input to a 1854 KDF, an authority key identifier (AKI) for an X.509 certificate or 1855 other. The profile document should specify what the key ID's 1856 semantics are. 1858 6.1.2. JWS and COSE X.509 Header Parameters 1860 COSE X.509 [COSE.X509.Draft] and JSON Web Siganture [RFC7515] define 1861 several header parameters (x5t, x5u,...) for referencing or carrying 1862 X.509 certificates any of which may be used. 1864 The X.509 certificate may be an Endorsement and thus carrying 1865 additional input to the Verifier. It may be just an X.509 1866 certificate, not an Endorsement. The same header parameters are used 1867 in both cases. It is up to the attestation system design and the 1868 Verifier to determine which. 1870 6.1.3. CBOR Certificate COSE Header Parameters 1872 Compressed X.509 and CBOR Native certificates are defined by CBOR 1873 Certificates [CBOR.Cert.Draft]. These are semantically compatible 1874 with X.509 and therefore can be used as an equivalent to X.509 as 1875 described above. 1877 These are identified by their own header parameters (c5t, c5u,...). 1879 6.1.4. Claim-Based Key Identification 1881 For some attestation systems, a claim may be re-used as a key 1882 identifier. For example, the UEID uniquely identifies the entity and 1883 therefore can work well as a key identifier or Endorsement 1884 identifier. 1886 This has the advantage that key identification requires no additional 1887 bytes in the EAT and makes the EAT smaller. 1889 This has the disadvantage that the unverified EAT must be 1890 substantially decoded to obtain the identifier since the identifier 1891 is in the COSE/JOSE payload, not in the headers. 1893 6.2. Other Considerations 1895 In all cases there must be some way that the verification key is 1896 itself verified or determined to be trustworthy. The key 1897 identification itself is never enough. This will always be by some 1898 out-of-band mechanism that is not described here. For example, the 1899 Verifier may be configured with a root certificate or a master key by 1900 the Verifier system administrator. 1902 Often an X.509 certificate or an Endorsement carries more than just 1903 the verification key. For example, an X.509 certificate might have 1904 key usage constraints and an Endorsement might have Reference Values. 1905 When this is the case, the key identifier must be either a protected 1906 header or in the payload such that it is cryptographically bound to 1907 the EAT. This is in line with the requirements in section 6 on Key 1908 Identification in JSON Web Signature [RFC7515]. 1910 7. Profiles 1912 This EAT specification does not gaurantee that implementations of it 1913 will interoperate. The variability in this specification is 1914 necessary to accommodate the widely varying use cases. An EAT 1915 profile narrows the specification for a specific use case. An ideal 1916 EAT profile will guarantee interoperability. 1918 The profile can be named in the token using the profile claim 1919 described in Section 3.20. 1921 A profile can apply to Attestation Evidence or to Attestation Results 1922 or both. 1924 7.1. Format of a Profile Document 1926 A profile document doesn't have to be in any particular format. It 1927 may be simple text, something more formal or a combination. 1929 In some cases CDDL may be created that replaces CDDL in this or other 1930 document to express some profile requirements. For example, to 1931 require the altitude data item in the location claim, CDDL can be 1932 written that replicates the location claim with the altitude no 1933 longer optional. 1935 7.2. List of Profile Issues 1937 The following is a list of EAT, CWT, UCCS, JWS, UJCS, COSE, JOSE and 1938 CBOR options that a profile should address. 1940 7.2.1. Use of JSON, CBOR or both 1942 The profile should indicate whether the token format should be CBOR, 1943 JSON, both or even some other encoding. If some other encoding, a 1944 specification for how the CDDL described here is serialized in that 1945 encoding is necessary. 1947 This should be addressed for the top-level token and for any nested 1948 tokens. For example, a profile might require all nested tokens to be 1949 of the same encoding of the top level token. 1951 7.2.2. CBOR Map and Array Encoding 1953 The profile should indicate whether definite-length arrays/maps, 1954 indefinite-length arrays/maps or both are allowed. A good default is 1955 to allow only definite-length arrays/maps. 1957 An alternate is to allow both definite and indefinite-length arrays/ 1958 maps. The decoder should accept either. Encoders that need to fit 1959 on very small hardware or be actually implement in hardware can use 1960 indefinite-length encoding. 1962 This applies to individual EAT claims, CWT and COSE parts of the 1963 implementation. 1965 7.2.3. CBOR String Encoding 1967 The profile should indicate whether definite-length strings, 1968 indefinite-length strings or both are allowed. A good default is to 1969 allow only definite-length strings. As with map and array encoding, 1970 allowing indefinite-length strings can be beneficial for some smaller 1971 implementations. 1973 7.2.4. CBOR Preferred Serialization 1975 The profile should indicate whether encoders must use preferred 1976 serialization. The profile should indicate whether decoders must 1977 accept non-preferred serialization. 1979 7.2.5. COSE/JOSE Protection 1981 COSE and JOSE have several options for signed, MACed and encrypted 1982 messages. EAT/CWT has the option to have no protection using UCCS 1983 and JOSE has a NULL protection option. It is possible to implement 1984 no protection, sign only, MAC only, sign then encrypt and so on. All 1985 combinations allowed by COSE, JOSE, JWT, CWT, UCCS and UJCS are 1986 allowed by EAT. 1988 The profile should list the protections that must be supported by all 1989 decoders implementing the profile. The encoders them must implement 1990 a subset of what is listed for the decoders, perhaps only one. 1992 Implementations may choose to sign or MAC before encryption so that 1993 the implementation layer doing the signing or MACing can be the 1994 smallest. It is often easier to make smaller implementations more 1995 secure, perhaps even implementing in solely in hardware. The key 1996 material for a signature or MAC is a private key, while for 1997 encryption it is likely to be a public key. The key for encryption 1998 requires less protection. 2000 7.2.6. COSE/JOSE Algorithms 2002 The profile document should list the COSE algorithms that a Verifier 2003 must implement. The Attester will select one of them. Since there 2004 is no negotiation, the Verifier should implement all algorithms 2005 listed in the profile. If detached submodules are used, the COSE 2006 algorithms allowed for their digests should also be in the profile. 2008 7.2.7. DEB Support 2010 A Detatched EAT Bundle Section 5 is a special case message that will 2011 not often be used. A profile may prohibit its use. 2013 7.2.8. Verification Key Identification 2015 Section Section 6 describes a number of methods for identifying a 2016 verification key. The profile document should specify one of these 2017 or one that is not described. The ones described in this document 2018 are only roughly described. The profile document should go into the 2019 full detail. 2021 7.2.9. Endorsement Identification 2023 Similar to, or perhaps the same as Verification Key Identification, 2024 the profile may wish to specify how Endorsements are to be 2025 identified. However note that Endorsement Identification is 2026 optional, where as key identification is not. 2028 7.2.10. Freshness 2030 Just about every use case will require some means of knowing the EAT 2031 is recent enough and not a replay of an old token. The profile 2032 should describe how freshness is achieved. The section on Freshness 2033 in [RATS.Architecture] describes some of the possible solutions to 2034 achieve this. 2036 7.2.11. Required Claims 2038 The profile can list claims whose absence results in Verification 2039 failure. 2041 7.2.12. Prohibited Claims 2043 The profile can list claims whose presence results in Verification 2044 failure. 2046 7.2.13. Additional Claims 2048 The profile may describe entirely new claims. These claims can be 2049 required or optional. 2051 7.2.14. Refined Claim Definition 2053 The profile may lock down optional aspects of individual claims. For 2054 example, it may require altitude in the location claim, or it may 2055 require that HW Versions always be described using EAN-13. 2057 7.2.15. CBOR Tags 2059 The profile should specify whether the token should be a CWT Tag or 2060 not. Similarly, the profile should specify whether the token should 2061 be a UCCS tag or not. 2063 When COSE protection is used, the profile should specify whether COSE 2064 tags are used or not. Note that RFC 8392 requires COSE tags be used 2065 in a CWT tag. 2067 Often a tag is unncessary because the surrounding or carrying 2068 protocol identifies the object as an EAT. 2070 7.2.16. Manifests and Software Evidence Claims 2072 The profile should specify which formats are allowed for the 2073 manifests and software evidence claims. The profile may also go on 2074 to say which parts and options of these formats are used, allowed and 2075 prohibited. 2077 8. Encoding and Collected CDDL 2079 An EAT is fundamentally defined using CDDL. This document specifies 2080 how to encode the CDDL in CBOR or JSON. Since CBOR can express some 2081 things that JSON can't (e.g., tags) or that are expressed differently 2082 (e.g., labels) there is some CDDL that is specific to the encoding 2083 format. 2085 8.1. Claims-Set and CDDL for CWT and JWT 2087 CDDL was not used to define CWT or JWT. It was not available at the 2088 time. 2090 This document defines CDDL for both CWT and JWT as well as UCCS. 2091 This document does not change the encoding or semantics of anything 2092 in a CWT or JWT. 2094 A Claims-Set is the central data structure for EAT, CWT, JWT and 2095 UCCS. It holds all the claims and is the structure that is secured 2096 by signing or other means. It is not possible to define EAT, CWT, 2097 JWT or UCCS in CDDL without it. The CDDL definition of Claims-Set 2098 here is applicable to EAT, CWT, JWT and UCCS. 2100 This document specifies how to encode a Claims-Set in CBOR or JSON. 2102 With the exception of nested tokens and some other externally defined 2103 structures (e.g., SWIDs) an entire Claims-Set must be in encoded in 2104 either CBOR or JSON, never a mixture. 2106 CDDL for the seven claims defined by [RFC8392] and [RFC7519] is 2107 included here. 2109 8.2. Encoding Data Types 2111 This makes use of the types defined in [RFC8610] Appendix D, Standard 2112 Prelude. 2114 8.2.1. Common Data Types 2116 time-int is identical to the epoch-based time, but disallows 2117 floating-point representation. 2119 Unless expliclity indicated, URIs are not the URI tag defined in 2120 [RFC8949]. They are just text strings that contain a URI. 2122 string-or-uri = tstr 2124 time-int = #6.1(int) 2126 8.2.2. JSON Interoperability 2128 JSON should be encoded per [RFC8610] Appendix E. In addition, the 2129 following CDDL types are encoded in JSON as follows: 2131 o bstr - must be base64url encoded 2133 o time - must be encoded as NumericDate as described section 2 of 2134 [RFC7519]. 2136 o string-or-uri - must be encoded as StringOrURI as described 2137 section 2 of [RFC7519]. 2139 o uri - must be a URI [RFC3986]. 2141 o oid - encoded as a string using the well established dotted- 2142 decimal notation (e.g., the text "1.2.250.1"). 2144 8.2.3. Labels 2146 Map labels, including Claims-Keys and Claim-Names, and enumerated- 2147 type values are always integers when encoding in CBOR and strings 2148 when encoding in JSON. There is an exception to this for naming 2149 submodules and detached claims sets in a DEB. These are strings in 2150 CBOR. 2152 The CDDL in most cases gives both the integer label and the string 2153 label as it is not convenient to have conditional CDDL for such. 2155 8.3. CBOR Interoperability 2157 CBOR allows data items to be serialized in more than one form. If 2158 the sender uses a form that the receiver can't decode, there will not 2159 be interoperability. 2161 This specification gives no blanket requirements to narrow CBOR 2162 serialization for all uses of EAT. This allows individual uses to 2163 tailor serialization to the environment. It also may result in EAT 2164 implementations that don't interoperate. 2166 One way to guarantee interoperability is to clearly specify CBOR 2167 serialization in a profile document. See Section 7 for a list of 2168 serialization issues that should be addressed. 2170 EAT will be commonly used where the entity generating the attestation 2171 is constrained and the receiver/Verifier of the attestation is a 2172 capacious server. Following is a set of serialization requirements 2173 that work well for that use case and are guaranteed to interoperate. 2174 Use of this serialization is recommended where possible, but not 2175 required. An EAT profile may just reference the following section 2176 rather than spell out serialization details. 2178 8.3.1. EAT Constrained Device Serialization 2180 o Preferred serialization described in section 4.1 of [RFC8949] is 2181 not required. The EAT decoder must accept all forms of number 2182 serialization. The EAT encoder may use any form it wishes. 2184 o The EAT decoder must accept indefinite length arrays and maps as 2185 described in section 3.2.2 of [RFC8949]. The EAT encoder may use 2186 indefinite length arrays and maps if it wishes. 2188 o The EAT decoder must accept indefinite length strings as described 2189 in section 3.2.3 of [RFC8949]. The EAT encoder may use indefinite 2190 length strings if it wishes. 2192 o Sorting of maps by key is not required. The EAT decoder must not 2193 rely on sorting. 2195 o Deterministic encoding described in Section 4.2 of [RFC8949] is 2196 not required. 2198 o Basic validity described in section 5.3.1 of [RFC8949] must be 2199 followed. The EAT encoder must not send duplicate map keys/labels 2200 or invalid UTF-8 strings. 2202 8.4. Collected Common CDDL 2204 Claims-Set = { 2205 * $$claims-set-claims, 2206 * Claim-Label .feature "extended-label" => any 2207 } 2209 Claim-Label = int / text 2210 string-or-uri = tstr 2212 time-int = #6.1(int) 2213 $$claims-set-claims //= (iss-label => text) 2214 $$claims-set-claims //= (sub-label => text) 2215 $$claims-set-claims //= (aud-label => text) 2216 $$claims-set-claims //= (exp-label => ~time) 2217 $$claims-set-claims //= (nbf-label => ~time) 2218 $$claims-set-claims //= (iat-label => ~time) 2220 $$claims-set-claims //= 2221 (nonce-label => nonce-type / [ 2* nonce-type ]) 2223 nonce-type = bstr .size (8..64) 2224 $$claims-set-claims //= (ueid-label => ueid-type) 2226 ueid-type = bstr .size (7..33) 2227 $$claims-set-claims //= (sueids-label => sueids-type) 2229 sueids-type = { 2230 + tstr => ueid-type 2231 } 2232 oemid-pen = int 2234 oemid-ieee = bstr .size 3 2235 oemid-random = bstr .size 16 2237 $$claims-set-claims //= ( 2238 oemid-label => 2239 oemid-random / oemid-ieee / oemid-pen 2240 ) 2241 $$claims-set-claims //= ( 2242 hardware-version-label => hardware-version-type 2243 ) 2245 hardware-version-type = [ 2246 version: tstr, 2247 scheme: $version-scheme 2248 ] 2249 hardware-model-type = bytes .size (1..32) 2251 $$claims-set-claims //= ( 2252 hardware-model-label => hardware-model-type 2253 ) 2254 $$claims-set-claims //= ( sw-name-label => tstr ) 2255 $$claims-set-claims //= (sw-version-label => sw-version-type) 2257 sw-version-type = [ 2258 version: tstr, 2259 scheme: $version-scheme ; As defined by CoSWID 2260 ] 2261 $$claims-set-claims //= ( 2262 security-level-label => 2263 security-level-cbor-type / 2264 security-level-json-type 2265 ) 2267 security-level-cbor-type = &( 2268 unrestricted: 1, 2269 restricted: 2, 2270 secure-restricted: 3, 2271 hardware: 4 2272 ) 2274 security-level-json-type = 2275 "unrestricted" / 2276 "restricted" / 2277 "secure-restricted" / 2278 "hardware" 2279 $$claims-set-claims //= (secure-boot-label => bool) 2280 $$claims-set-claims //= ( 2281 debug-status-label => 2282 debug-status-cbor-type / debug-status-json-type 2283 ) 2285 debug-status-cbor-type = &( 2286 enabled: 0, 2287 disabled: 1, 2288 disabled-since-boot: 2, 2289 disabled-permanently: 3, 2290 disabled-fully-and-permanently: 4 2291 ) 2293 debug-status-json-type = 2294 "enabled" / 2295 "disabled" / 2296 "disabled-since-boot" / 2297 "disabled-permanently" / 2298 "disabled-fully-and-permanently" 2299 $$claims-set-claims //= (location-label => location-type) 2301 location-type = { 2302 latitude => number, 2303 longitude => number, 2304 ? altitude => number, 2305 ? accuracy => number, 2306 ? altitude-accuracy => number, 2307 ? heading => number, 2308 ? speed => number, 2309 ? timestamp => ~time-int, 2310 ? age => uint 2311 } 2313 latitude = 1 / "latitude" 2314 longitude = 2 / "longitude" 2315 altitude = 3 / "altitude" 2316 accuracy = 4 / "accuracy" 2317 altitude-accuracy = 5 / "altitude-accuracy" 2318 heading = 6 / "heading" 2319 speed = 7 / "speed" 2320 timestamp = 8 / "timestamp" 2321 age = 9 / "age" 2322 $$claims-set-claims //= (uptime-label => uint) 2323 $$claims-set-claims //= (boot-seed-label => bytes) 2324 $$claims-set-claims //= (odometer-label => uint) 2325 $$claims-set-claims //= ( 2326 intended-use-label => 2327 intended-use-cbor-type / intended-use-json-type 2328 ) 2329 intended-use-cbor-type = &( 2330 generic: 1, 2331 registration: 2, 2332 provisioning: 3, 2333 csr: 4, 2334 pop: 5 2335 ) 2337 intended-use-json-type = 2338 "generic" / 2339 "registration" / 2340 "provisioning" / 2341 "csr" / 2342 "pop" 2343 $$claims-set-claims //= ( 2344 dloas-label => [ + dloa-type ] 2345 ) 2347 dloa-type = [ 2348 dloa_registrar: ~uri 2349 dloa_platform_label: text 2350 ? dloa_application_label: text 2351 ] 2352 $$claims-set-claims //= (profile-label => ~uri / ~oid) 2353 $$claims-set-claims //= ( 2354 manifests-label => manifests-type 2355 ) 2357 manifests-type = [+ $$manifest-formats] 2359 coswid-that-is-a-cbor-tag-xx = tagged-coswid 2361 $$manifest-formats /= bytes .cbor coswid-that-is-a-cbor-tag-xx$$claims-set-claims //= ( 2362 swevidence-label => swevidence-type 2363 ) 2365 swevidence-type = [+ $$swevidence-formats] 2367 coswid-that-is-a-cbor-tag = tagged-coswid 2368 $$swevidence-formats /= bytes .cbor coswid-that-is-a-cbor-tag 2369 $$claims-set-claims //= (swresults-label => [ + swresult-type ]) 2371 verification-result-cbor-type = &( 2372 verification-not-run: 1, 2373 verification-indeterminate: 2, 2374 verification-failed: 3, 2375 fully-verified: 4, 2376 partially-verified: 5, 2378 ) 2380 verification-result-json-type = 2381 "verification-not-run" / 2382 "verification-indeterminate" / 2383 "verification-failed" / 2384 "fully-verified" / 2385 "partially-verified" 2387 verification-objective-cbor-type = &( 2388 all: 1, 2389 firmware: 2, 2390 kernel: 3, 2391 privileged: 4, 2392 system-libs: 5, 2393 partial: 6, 2394 ) 2396 verification-objective-json-type = 2397 "all" / 2398 "firmware" / 2399 "kernel" / 2400 "privileged" / 2401 "system-libs" / 2402 "partial" 2404 swresult-type = [ 2405 verification-system: tstr, 2406 objective: verification-objective-cbor-type / 2407 verification-objective-json-type, 2408 result: verification-result-cbor-type / 2409 verification-result-json-type, 2410 ? objective-name: tstr 2411 ] 2412 $$claims-set-claims //= (submods-label => { + text => Submodule }) 2414 Submodule = Claims-Set / Nested-Token / Detached-Submodule-Digest 2416 Detached-Submodule-Digest = [ 2417 algorithm : int / text, 2418 digest : bstr 2419 ] 2420 Detached-EAT-Bundle = [ 2421 main-token : Nested-Token, 2422 detached-claims-sets: { 2423 + tstr => cbor-wrapped-claims-set / json-wrapped-claims-set 2425 } 2426 ] 2428 json-wrapped-claims-set = tstr .regexp "[A-Za-z0-9_=-]+" 2430 cbor-wrapped-claims-set = bstr .cbor Claims-Set 2432 8.5. Collected CDDL for CBOR 2434 CBOR-Token = Tagged-CBOR-Token / Untagged-CBOR-Token 2436 Tagged-CBOR-Token = CWT-Tagged-Message 2437 Tagged-CBOR-Token /= UCCS-Tagged-Message 2438 Tagged-CBOR-Token /= DEB-Tagged-Message 2440 Untagged-CBOR-Token = CWT-Untagged-Message 2441 Untagged-CBOR-Token /= UCCS-Untagged-Message 2442 Untagged-CBOR-Token /= DEB-Untagged-Message 2444 CWT-Tagged-Message = COSE_Tagged_Message 2445 CWT-Untagged-Message = COSE_Untagged_Message 2447 UCCS-Message = UCCS-Tagged-Message / UCCS-Untagged-Message 2449 UCCS-Tagged-Message = #6.601(UCCS-Untagged-Message) 2451 UCCS-Untagged-Message = Claims-Set 2453 DEB-Tagged-Message = #6.602(DEB-Untagged-Message) 2455 DEB-Untagged-Message = Detached-EAT-Bundle 2457 Nested-Token = 2458 tstr / ; A JSON-encoded Nested-Token (see json-nested-token.cddl) 2459 bstr .cbor Tagged-CBOR-Token 2461 iss-label = 1 2462 sub-label = 2 2463 aud-label = 3 2464 exp-label = 4 2465 nbf-label = 5 2466 iat-label = 6 2467 cti-label = 7nonce-label = 10 2468 ueid-label = 256 2469 sueids-label = 257 2470 oemid-label = 258 2471 hardware-model-label = 259 2472 hardware-version-label = 260 2473 secure-boot-label = 262 2474 debug-status-label = 263 2475 location-label = 264 2476 profile-label = 265 2477 submods-label = 266 2478 security-level-label = 2479 uptime-label = 2480 boot-seed-label = 2481 odometer-label = 2482 intended-use-label = 2483 dloas-label = 2484 sw-name-label = 2485 sw-version-label = 2486 manifests-label = 2487 swevidence-label = 2488 swresults-label = 2490 8.6. Collected CDDL for JSON 2492 JWT-Message = text .regexp [A-Za-z0-9_=-]+\.[A-Za-z0-9_=-]+\.[A-Za-z0-9_=-]+ 2494 UJCS-Message = Claims-Set 2496 Nested-Token = [ 2497 type : "JWT" / "CBOR" / "UJCS" / "DEB", 2498 nested-token : JWT-Message / 2499 B64URL-Tagged-CBOR-Token / 2500 DEB-JSON-Message / 2501 UJCS-Message 2502 ] 2504 B64URL-Tagged-CBOR-Token = tstr .regexp "[A-Za-z0-9_=-]+" 2505 iss-label = "iss" 2506 sub-label = "sub" 2507 aud-label = "aud" 2508 exp-label = "exp" 2509 nbf-label = "nbf" 2510 iat-label = "iat" 2511 cti-label = "cti"nonce-label /= "nonce" 2513 ueid-label /= "ueid" 2514 sueids-label /= "sueids" 2515 oemid-label /= "oemid" 2516 hardware-model-label /= "hwmodel" 2517 hardware-version-label /= "hwversion" 2518 security-level-label /= "seclevel" 2519 secure-boot-label /= "secboot" 2520 debug-status-label /= "dbgstat" 2521 location-label /= "location" 2522 profile-label /= "eat-profile" 2523 uptime-label /= "uptime" 2524 boot-seed-label /= "bootseed" 2525 odometer-label /= "odometer" 2526 intended-use-label /= "intuse" 2527 dloas-label /= "dloas" 2528 sw-name-label /= "swname" 2529 sw-version-label /= "swversion" 2530 manifests-label /= "manifests" 2531 swevidence-label /= "swevidence" 2532 swresults-label /= "swresults" 2533 submods-label /= "submods" 2535 latitude /= "lat" 2536 longitude /= "long" 2537 altitude /= "alt" 2538 accuracy /= "accry" 2539 altitude-accuracy /= "alt-accry" 2540 heading /= "heading" 2541 speed /= "speed" 2543 9. IANA Considerations 2545 9.1. Reuse of CBOR and JSON Web Token (CWT and JWT) Claims Registries 2547 Claims defined for EAT are compatible with those of CWT and JWT so 2548 the CWT and JWT Claims Registries, [IANA.CWT.Claims] and 2549 [IANA.JWT.Claims], are re used. No new IANA registry is created. 2551 All EAT claims defined in this document are placed in both 2552 registries. All new EAT claims defined subsequently should be placed 2553 in both registries. 2555 9.2. Claim Characteristics 2557 The following is design guidance for creating new EAT claims, 2558 particularly those to be registered with IANA. 2560 Much of this guidance is generic and could also be considered when 2561 designing new CWT or JWT claims. 2563 9.2.1. Interoperability and Relying Party Orientation 2565 It is a broad goal that EATs can be processed by Relying Parties in a 2566 general way regardless of the type, manufacturer or technology of the 2567 device from which they originate. It is a goal that there be 2568 general-purpose verification implementations that can verify tokens 2569 for large numbers of use cases with special cases and configurations 2570 for different device types. This is a goal of interoperability of 2571 the semantics of claims themselves, not just of the signing, encoding 2572 and serialization formats. 2574 This is a lofty goal and difficult to achieve broadly requiring 2575 careful definition of claims in a technology neutral way. Sometimes 2576 it will be difficult to design a claim that can represent the 2577 semantics of data from very different device types. However, the 2578 goal remains even when difficult. 2580 9.2.2. Operating System and Technology Neutral 2582 Claims should be defined such that they are not specific to an 2583 operating system. They should be applicable to multiple large high- 2584 level operating systems from different vendors. They should also be 2585 applicable to multiple small embedded operating systems from multiple 2586 vendors and everything in between. 2588 Claims should not be defined such that they are specific to a SW 2589 environment or programming language. 2591 Claims should not be defined such that they are specific to a chip or 2592 particular hardware. For example, they should not just be the 2593 contents of some HW status register as it is unlikely that the same 2594 HW status register with the same bits exists on a chip of a different 2595 manufacturer. 2597 The boot and debug state claims in this document are an example of a 2598 claim that has been defined in this neutral way. 2600 9.2.3. Security Level Neutral 2602 Many use cases will have EATs generated by some of the most secure 2603 hardware and software that exists. Secure Elements and smart cards 2604 are examples of this. However, EAT is intended for use in low- 2605 security use cases the same as high-security use case. For example, 2606 an app on a mobile device may generate EATs on its own. 2608 Claims should be defined and registered on the basis of whether they 2609 are useful and interoperable, not based on security level. In 2610 particular, there should be no exclusion of claims because they are 2611 just used only in low-security environments. 2613 9.2.4. Reuse of Extant Data Formats 2615 Where possible, claims should use already standardized data items, 2616 identifiers and formats. This takes advantage of the expertise put 2617 into creating those formats and improves interoperability. 2619 Often extant claims will not be defined in an encoding or 2620 serialization format used by EAT. It is preferred to define a CBOR 2621 and JSON format for them so that EAT implementations do not require a 2622 plethora of encoders and decoders for serialization formats. 2624 In some cases, it may be better to use the encoding and serialization 2625 as is. For example, signed X.509 certificates and CRLs can be 2626 carried as-is in a byte string. This retains interoperability with 2627 the extensive infrastructure for creating and processing X.509 2628 certificates and CRLs. 2630 9.2.5. Proprietary Claims 2632 EAT allows the definition and use of proprietary claims. 2634 For example, a device manufacturer may generate a token with 2635 proprietary claims intended only for verification by a service 2636 offered by that device manufacturer. This is a supported use case. 2638 In many cases proprietary claims will be the easiest and most obvious 2639 way to proceed, however for better interoperability, use of general 2640 standardized claims is preferred. 2642 9.3. Claims Registered by This Document 2644 This specification adds the following values to the "JSON Web Token 2645 Claims" registry established by [RFC7519] and the "CBOR Web Token 2646 Claims Registry" established by [RFC8392]. Each entry below is an 2647 addition to both registries (except for the nonce claim which is 2648 already registered for JWT, but not registered for CWT). 2650 The "Claim Description", "Change Controller" and "Specification 2651 Documents" are common and equivalent for the JWT and CWT registries. 2652 The "Claim Key" and "Claim Value Types(s)" are for the CWT registry 2653 only. The "Claim Name" is as defined for the CWT registry, not the 2654 JWT registry. The "JWT Claim Name" is equivalent to the "Claim Name" 2655 in the JWT registry. 2657 9.3.1. Claims for Early Assignment 2659 RFC Editor: in the final publication this section should be combined 2660 with the following section as it will no longer be necessary to 2661 distinguish claims with early assignment. Also, the following 2662 paragraph should be removed. 2664 The claims in this section have been (requested for / given) early 2665 assignment according to [RFC7120]. They have been assigned values 2666 and registered before final publication of this document. While 2667 their semantics is not expected to change in final publication, it is 2668 possible that they will. The JWT Claim Names and CWT Claim Keys are 2669 not expected to change. 2671 In draft -06 an early allocation was described. The processing of 2672 that early allocation was never correctly completed. This early 2673 allocation assigns different numbers for the CBOR claim labels. This 2674 early allocation will presumably complete correctly 2676 o Claim Name: Nonce 2678 o Claim Description: Nonce 2680 o JWT Claim Name: "nonce" (already registered for JWT) 2682 o Claim Key: TBD (requested value 10) 2684 o Claim Value Type(s): byte string 2686 o Change Controller: IESG 2688 o Specification Document(s): [OpenIDConnectCore], *this document* 2690 o Claim Name: UEID 2692 o Claim Description: The Universal Entity ID 2694 o JWT Claim Name: "ueid" 2695 o CWT Claim Key: TBD (requested value 256) 2697 o Claim Value Type(s): byte string 2699 o Change Controller: IESG 2701 o Specification Document(s): *this document* 2703 o Claim Name: SUEIDs 2705 o Claim Description: Semi-permanent UEIDs 2707 o JWT Claim Name: "sueids" 2709 o CWT Claim Key: TBD (requested value 257) 2711 o Claim Value Type(s): map 2713 o Change Controller: IESG 2715 o Specification Document(s): *this document* 2717 o Claim Name: Hardware OEMID 2719 o Claim Description: Hardware OEM ID 2721 o JWT Claim Name: "oemid" 2723 o Claim Key: TBD (requested value 258) 2725 o Claim Value Type(s): byte string or integer 2727 o Change Controller: IESG 2729 o Specification Document(s): *this document* 2731 o Claim Name: Hardware Model 2733 o Claim Description: Model identifier for hardware 2735 o JWT Claim Name: "hwmodel" 2737 o Claim Key: TBD (requested value 259) 2739 o Claim Value Type(s): byte string 2741 o Change Controller: IESG 2742 o Specification Document(s): *this document* 2744 o Claim Name: Hardware Version 2746 o Claim Description: Hardware Version Identifier 2748 o JWT Claim Name: "hwversion" 2750 o Claim Key: TBD (requested value 260) 2752 o Claim Value Type(s): array 2754 o Change Controller: IESG 2756 o Specification Document(s): *this document* 2758 o Claim Name: Secure Boot 2760 o Claim Description: Indicate whether the boot was secure 2762 o JWT Claim Name: "secboot" 2764 o Claim Key: TBD (requested value 262) 2766 o Claim Value Type(s): Boolean 2768 o Change Controller: IESG 2770 o Specification Document(s): *this document* 2772 o Claim Name: Debug Status 2774 o Claim Description: Indicate status of debug facilities 2776 o JWT Claim Name: "dbgstat" 2778 o Claim Key: TBD (requested value 263) 2780 o Claim Value Type(s): integer or string 2782 o Change Controller: IESG 2784 o Specification Document(s): *this document* 2786 o Claim Name: Location 2788 o Claim Description: The geographic location 2789 o JWT Claim Name: "location" 2791 o Claim Key: TBD (requested value 264) 2793 o Claim Value Type(s): map 2795 o Change Controller: IESG 2797 o Specification Document(s): *this document* 2799 o Claim Name: Profile 2801 o Claim Description: Indicates the EAT profile followed 2803 o JWT Claim Name: "eat_profile" 2805 o Claim Key: TBD (requested value 265) 2807 o Claim Value Type(s): URI or OID 2809 o Change Controller: IESG 2811 o Specification Document(s): *this document* 2813 o Claim Name: Submodules Section 2815 o Claim Description: The section containing submodules 2817 o JWT Claim Name: "submods" 2819 o Claim Key: TBD (requested value 266) 2821 o Claim Value Type(s): map 2823 o Change Controller: IESG 2825 o Specification Document(s): *this document* 2827 9.3.2. To be Assigned Claims 2829 (Early assignment is NOT requested for these claims. Implementers 2830 should be aware they may change) 2832 o Claim Name: Security Level 2834 o Claim Description: Characterization of the security of an Attester 2835 or submodule 2837 o JWT Claim Name: "seclevel" 2839 o Claim Key: TBD 2841 o Claim Value Type(s): integer or string 2843 o Change Controller: IESG 2845 o Specification Document(s): *this document* 2847 o Claim Name: Uptime 2849 o Claim Description: Uptime 2851 o JWT Claim Name: "uptime" 2853 o Claim Key: TBD 2855 o Claim Value Type(s): unsigned integer 2857 o Change Controller: IESG 2859 o Specification Document(s): *this document* 2861 o Claim Name: Boot Seed 2863 o Claim Description: Identifies a boot cycle 2865 o JWT Claim Name: "bootseed" 2867 o Claim Key: TBD 2869 o Claim Value Type(s): bytes 2871 o Change Controller: IESG 2873 o Specification Document(s): *this document* 2875 o Claim Name: Intended Use 2877 o Claim Description: Indicates intended use of the EAT 2879 o JWT Claim Name: "intuse" 2881 o Claim Key: TBD 2883 o Claim Value Type(s): integer or string 2884 o Change Controller: IESG 2886 o Specification Document(s): *this document* 2888 o Claim Name: DLOAs 2890 o Claim Description: Certifications received as Digital Letters of 2891 Approval 2893 o JWT Claim Name: "dloas" 2895 o Claim Key: TBD 2897 o Claim Value Type(s): array 2899 o Change Controller: IESG 2901 o Specification Document(s): *this document* 2903 o Claim Name: SW Name 2905 o Claim Description: The name of the SW running in the entity 2907 o JWT Claim Name: "swname" 2909 o Claim Key: TBD 2911 o Claim Value Type(s): map 2913 o Change Controller: IESG 2915 o Specification Document(s): *this document* 2917 o Claim Name: SW Version 2919 o Claim Description: The version of SW running in the entity 2921 o JWT Claim Name: "swversion" 2923 o Claim Key: TBD 2925 o Claim Value Type(s): map 2927 o Change Controller: IESG 2929 o Specification Document(s): *this document* 2931 o Claim Name: SW Manifests 2932 o Claim Description: Manifests describing the SW installed on the 2933 entity 2935 o JWT Claim Name: "manifests" 2937 o Claim Key: TBD 2939 o Claim Value Type(s): array 2941 o Change Controller: IESG 2943 o Specification Document(s): *this document* 2945 o Claim Name: SW Evidence 2947 o Claim Description: Measurements of the SW, memory configuration 2948 and such on the entity 2950 o JWT Claim Name: "swevidence" 2952 o Claim Key: TBD 2954 o Claim Value Type(s): array 2956 o Change Controller: IESG 2958 o Specification Document(s): *this document* 2960 o Claim Name: SW Measurment Results 2962 o Claim Description: The results of comparing SW measurements to 2963 reference values 2965 o JWT Claim Name: "swresults" 2967 o Claim Key: TBD 2969 o Claim Value Type(s): array 2971 o Change Controller: IESG 2973 o Specification Document(s): *this document* 2975 9.3.3. Version Schemes Registered by this Document 2977 IANA is requested to register a new value in the "Software Tag 2978 Version Scheme Values" established by [CoSWID]. 2980 The new value is a version scheme a 13-digit European Article Number 2981 [EAN-13]. An EAN-13 is also known as an International Article Number 2982 or most commonly as a bar code. This version scheme is the ASCII 2983 text representation of EAN-13 digits, the same ones often printed 2984 with a bar code. This version scheme must comply with the EAN 2985 allocation and assignment rules. For example, this requires the 2986 manufacturer to obtain a manufacture code from GS1. 2988 +-------+---------------------+---------------+ 2989 | Index | Version Scheme Name | Specification | 2990 +-------+---------------------+---------------+ 2991 | 5 | ean-13 | This document | 2992 +-------+---------------------+---------------+ 2994 9.3.4. UEID URN Registered by this Document 2996 IANA is requested to register the following new subtypes in the "DEV 2997 URN Subtypes" registry under "Device Identification". See [RFC9039]. 2999 +---------+-----------------------------------------+---------------+ 3000 | Subtype | Description | Reference | 3001 +---------+-----------------------------------------+---------------+ 3002 | ueid | Universal Entity Identifier | This document | 3003 | sueid | Semi-permanent Universal Entity | This document | 3004 | | Identifier | | 3005 +---------+-----------------------------------------+---------------+ 3007 9.3.5. Tag for Detached EAT Bundle 3009 In the registry [IANA.cbor-tags], IANA is requested to allocate the 3010 following tag from the FCFS space, with the present document as the 3011 specification reference. 3013 +--------+------------+-------------------------------+ 3014 | Tag | Data Items | Semantics | 3015 +--------+------------+-------------------------------+ 3016 | TBD602 | array | Detached EAT Bundle Section 5 | 3017 +--------+------------+-------------------------------+ 3019 10. Privacy Considerations 3021 Certain EAT claims can be used to track the owner of an entity and 3022 therefore, implementations should consider providing privacy- 3023 preserving options dependent on the intended usage of the EAT. 3024 Examples would include suppression of location claims for EAT's 3025 provided to unauthenticated consumers. 3027 10.1. UEID and SUEID Privacy Considerations 3029 A UEID is usually not privacy-preserving. Any set of Relying Parties 3030 that receives tokens that happen to be from a particular entity will 3031 be able to know the tokens are all from the same entity and be able 3032 to track it. 3034 Thus, in many usage situations UEID violates governmental privacy 3035 regulation. In other usage situations a UEID will not be allowed for 3036 certain products like browsers that give privacy for the end user. 3037 It will often be the case that tokens will not have a UEID for these 3038 reasons. 3040 An SUEID is also usually not privacy-preserving. In some cases it 3041 may have fewer privacy issues than a UEID depending on when and how 3042 and when it is generated. 3044 There are several strategies that can be used to still be able to put 3045 UEIDs and SUEIDs in tokens: 3047 o The entity obtains explicit permission from the user of the entity 3048 to use the UEID/SUEID. This may be through a prompt. It may also 3049 be through a license agreement. For example, agreements for some 3050 online banking and brokerage services might already cover use of a 3051 UEID/SUEID. 3053 o The UEID/SUEID is used only in a particular context or particular 3054 use case. It is used only by one Relying Party. 3056 o The entity authenticates the Relying Party and generates a derived 3057 UEID/SUEID just for that particular Relying Party. For example, 3058 the Relying Party could prove their identity cryptographically to 3059 the entity, then the entity generates a UEID just for that Relying 3060 Party by hashing a proofed Relying Party ID with the main entity 3061 UEID/SUEID. 3063 Note that some of these privacy preservation strategies result in 3064 multiple UEIDs and SUEIDs per entity. Each UEID/SUEID is used in a 3065 different context, use case or system on the entity. However, from 3066 the view of the Relying Party, there is just one UEID and it is still 3067 globally universal across manufacturers. 3069 10.2. Location Privacy Considerations 3071 Geographic location is most always considered personally identifiable 3072 information. Implementers should consider laws and regulations 3073 governing the transmission of location data from end user devices to 3074 servers and services. Implementers should consider using location 3075 management facilities offered by the operating system on the entity 3076 generating the attestation. For example, many mobile phones prompt 3077 the user for permission when before sending location data. 3079 10.3. Replay Protection and Privacy 3081 EAT offers 2 primary mechanisms for token replay protection (also 3082 sometimes known as token "freshness"): the cti/jti claim and the 3083 nonce claim. The cti/jti claim in a CWT/JWT is a field that may be 3084 optionally included in the EAT and is in general derived on the same 3085 device in which the entity is instantiated. The nonce claim is based 3086 on a value that is usually derived remotely (outside of the entity). 3087 These claims can be used to extract and convey personally-identifying 3088 information either inadvertently or by intention. For instance, an 3089 implementor may choose a cti that is equivalent to a username 3090 associated with the device (e.g., account login). If the token is 3091 inspected by a 3rd-party then this information could be used to 3092 identify the source of the token or an account associated with the 3093 token (e.g., if the account name is used to derive the nonce). In 3094 order to avoid the conveyance of privacy-related information in 3095 either the cti/jti or nonce claims, these fields should be derived 3096 using a salt that originates from a true and reliable random number 3097 generator or any other source of randomness that would still meet the 3098 target system requirements for replay protection. 3100 11. Security Considerations 3102 The security considerations provided in Section 8 of [RFC8392] and 3103 Section 11 of [RFC7519] apply to EAT in its CWT and JWT form, 3104 respectively. In addition, implementors should consider the 3105 following. 3107 11.1. Key Provisioning 3109 Private key material can be used to sign and/or encrypt the EAT, or 3110 can be used to derive the keys used for signing and/or encryption. 3111 In some instances, the manufacturer of the entity may create the key 3112 material separately and provision the key material in the entity 3113 itself. The manfuacturer of any entity that is capable of producing 3114 an EAT should take care to ensure that any private key material be 3115 suitably protected prior to provisioning the key material in the 3116 entity itself. This can require creation of key material in an 3117 enclave (see [RFC4949] for definition of "enclave"), secure 3118 transmission of the key material from the enclave to the entity using 3119 an appropriate protocol, and persistence of the private key material 3120 in some form of secure storage to which (preferably) only the entity 3121 has access. 3123 11.1.1. Transmission of Key Material 3125 Regarding transmission of key material from the enclave to the 3126 entity, the key material may pass through one or more intermediaries. 3127 Therefore some form of protection ("key wrapping") may be necessary. 3128 The transmission itself may be performed electronically, but can also 3129 be done by human courier. In the latter case, there should be 3130 minimal to no exposure of the key material to the human (e.g. 3131 encrypted portable memory). Moreover, the human should transport the 3132 key material directly from the secure enclave where it was created to 3133 a destination secure enclave where it can be provisioned. 3135 11.2. Transport Security 3137 As stated in Section 8 of [RFC8392], "The security of the CWT relies 3138 upon on the protections offered by COSE". Similar considerations 3139 apply to EAT when sent as a CWT. However, EAT introduces the concept 3140 of a nonce to protect against replay. Since an EAT may be created by 3141 an entity that may not support the same type of transport security as 3142 the consumer of the EAT, intermediaries may be required to bridge 3143 communications between the entity and consumer. As a result, it is 3144 RECOMMENDED that both the consumer create a nonce, and the entity 3145 leverage the nonce along with COSE mechanisms for encryption and/or 3146 signing to create the EAT. 3148 Similar considerations apply to the use of EAT as a JWT. Although 3149 the security of a JWT leverages the JSON Web Encryption (JWE) and 3150 JSON Web Signature (JWS) specifications, it is still recommended to 3151 make use of the EAT nonce. 3153 11.3. Multiple EAT Consumers 3155 In many cases, more than one EAT consumer may be required to fully 3156 verify the entity attestation. Examples include individual consumers 3157 for nested EATs, or consumers for individual claims with an EAT. 3158 When multiple consumers are required for verification of an EAT, it 3159 is important to minimize information exposure to each consumer. In 3160 addition, the communication between multiple consumers should be 3161 secure. 3163 For instance, consider the example of an encrypted and signed EAT 3164 with multiple claims. A consumer may receive the EAT (denoted as the 3165 "receiving consumer"), decrypt its payload, verify its signature, but 3166 then pass specific subsets of claims to other consumers for 3167 evaluation ("downstream consumers"). Since any COSE encryption will 3168 be removed by the receiving consumer, the communication of claim 3169 subsets to any downstream consumer should leverage a secure protocol 3170 (e.g.one that uses transport-layer security, i.e. TLS), 3171 However, assume the EAT of the previous example is hierarchical and 3172 each claim subset for a downstream consumer is created in the form of 3173 a nested EAT. Then transport security between the receiving and 3174 downstream consumers is not strictly required. Nevertheless, 3175 downstream consumers of a nested EAT should provide a nonce unique to 3176 the EAT they are consuming. 3178 12. References 3180 12.1. Normative References 3182 [CoSWID] Birkholz, H., Fitzgerald-McKay, J., Schmidt, C., and D. 3183 Waltermire, "Concise Software Identification Tags", draft- 3184 ietf-sacm-coswid-20 (work in progress), January 2022. 3186 [DLOA] "Digital Letter of Approval", November 2015, 3187 . 3190 [EAN-13] GS1, "International Article Number - EAN/UPC barcodes", 3191 2019, . 3193 [FIDO.AROE] 3194 The FIDO Alliance, "FIDO Authenticator Allowed Restricted 3195 Operating Environments List", November 2020, 3196 . 3200 [IANA.cbor-tags] 3201 "IANA CBOR Tags Registry", n.d., 3202 . 3205 [IANA.CWT.Claims] 3206 IANA, "CBOR Web Token (CWT) Claims", 3207 . 3209 [IANA.JWT.Claims] 3210 IANA, "JSON Web Token (JWT) Claims", 3211 . 3213 [OpenIDConnectCore] 3214 Sakimura, N., Bradley, J., Jones, M., Medeiros, B. D., and 3215 C. Mortimore, "OpenID Connect Core 1.0 incorporating 3216 errata set 1", November 2014, 3217 . 3219 [PEN] "Private Enterprise Number (PEN) Request", n.d., 3220 . 3222 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3223 Requirement Levels", BCP 14, RFC 2119, 3224 DOI 10.17487/RFC2119, March 1997, 3225 . 3227 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3228 Resource Identifier (URI): Generic Syntax", STD 66, 3229 RFC 3986, DOI 10.17487/RFC3986, January 2005, 3230 . 3232 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 3233 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 3234 2014, . 3236 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 3237 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 3238 2015, . 3240 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 3241 RFC 7516, DOI 10.17487/RFC7516, May 2015, 3242 . 3244 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 3245 DOI 10.17487/RFC7517, May 2015, 3246 . 3248 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 3249 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 3250 . 3252 [RFC7800] Jones, M., Bradley, J., and H. Tschofenig, "Proof-of- 3253 Possession Key Semantics for JSON Web Tokens (JWTs)", 3254 RFC 7800, DOI 10.17487/RFC7800, April 2016, 3255 . 3257 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 3258 Writing an IANA Considerations Section in RFCs", BCP 26, 3259 RFC 8126, DOI 10.17487/RFC8126, June 2017, 3260 . 3262 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 3263 RFC 8152, DOI 10.17487/RFC8152, July 2017, 3264 . 3266 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 3267 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 3268 May 2017, . 3270 [RFC8392] Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, 3271 "CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392, 3272 May 2018, . 3274 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 3275 Definition Language (CDDL): A Notational Convention to 3276 Express Concise Binary Object Representation (CBOR) and 3277 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 3278 June 2019, . 3280 [RFC8747] Jones, M., Seitz, L., Selander, G., Erdtman, S., and H. 3281 Tschofenig, "Proof-of-Possession Key Semantics for CBOR 3282 Web Tokens (CWTs)", RFC 8747, DOI 10.17487/RFC8747, March 3283 2020, . 3285 [RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object 3286 Representation (CBOR)", STD 94, RFC 8949, 3287 DOI 10.17487/RFC8949, December 2020, 3288 . 3290 [RFC9090] Bormann, C., "Concise Binary Object Representation (CBOR) 3291 Tags for Object Identifiers", RFC 9090, 3292 DOI 10.17487/RFC9090, July 2021, 3293 . 3295 [ThreeGPP.IMEI] 3296 3GPP, "3rd Generation Partnership Project; Technical 3297 Specification Group Core Network and Terminals; Numbering, 3298 addressing and identification", 2019, 3299 . 3302 [UCCS.Draft] 3303 Birkholz, H., O'Donoghue, J., Cam-Winget, N., and C. 3304 Bormann, "A CBOR Tag for Unprotected CWT Claims Sets", 3305 draft-ietf-rats-uccs-02 (work in progress), January 2022. 3307 [WGS84] National Geospatial-Intelligence Agency (NGA), "WORLD 3308 GEODETIC SYSTEM 1984, NGA.STND.0036_1.0.0_WGS84", July 3309 2014, . 3312 12.2. Informative References 3314 [BirthdayAttack] 3315 "Birthday attack", 3316 . 3318 [CBOR.Cert.Draft] 3319 Mattsson, J. P., Selander, G., Raza, S., Hoeglund, J., and 3320 M. Furuhed, "CBOR Encoded X.509 Certificates (C509 3321 Certificates)", draft-ietf-cose-cbor-encoded-cert-03 (work 3322 in progress), January 2022. 3324 [Common.Criteria] 3325 "Common Criteria for Information Technology Security 3326 Evaluation", April 2017, 3327 . 3329 [COSE.X509.Draft] 3330 Schaad, J., "CBOR Object Signing and Encryption (COSE): 3331 Header parameters for carrying and referencing X.509 3332 certificates", draft-ietf-cose-x509-08 (work in progress), 3333 December 2020. 3335 [FIPS-140] 3336 National Institue of Standards, "Security Requirements for 3337 Cryptographic Modules", May 2001, 3338 . 3341 [IEEE.802-2001] 3342 "IEEE Standard For Local And Metropolitan Area Networks 3343 Overview And Architecture", 2007, 3344 . 3347 [IEEE.802.1AR] 3348 "IEEE Standard, "IEEE 802.1AR Secure Device Identifier"", 3349 December 2009, . 3352 [IEEE.RA] "IEEE Registration Authority", 3353 . 3356 [OUI.Guide] 3357 "Guidelines for Use of Extended Unique Identifier (EUI), 3358 Organizationally Unique Identifier (OUI), and Company ID 3359 (CID)", August 2017, 3360 . 3363 [OUI.Lookup] 3364 "IEEE Registration Authority Assignments", 3365 . 3368 [RATS.Architecture] 3369 Birkholz, H., Thaler, D., Richardson, M., Smith, N., and 3370 W. Pan, "Remote Attestation Procedures Architecture", 3371 draft-ietf-rats-architecture-15 (work in progress), 3372 February 2022. 3374 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 3375 Unique IDentifier (UUID) URN Namespace", RFC 4122, 3376 DOI 10.17487/RFC4122, July 2005, 3377 . 3379 [RFC4422] Melnikov, A., Ed. and K. Zeilenga, Ed., "Simple 3380 Authentication and Security Layer (SASL)", RFC 4422, 3381 DOI 10.17487/RFC4422, June 2006, 3382 . 3384 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 3385 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 3386 . 3388 [RFC7120] Cotton, M., "Early IANA Allocation of Standards Track Code 3389 Points", BCP 100, RFC 7120, DOI 10.17487/RFC7120, January 3390 2014, . 3392 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 3393 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 3394 . 3396 [RFC9039] Arkko, J., Jennings, C., and Z. Shelby, "Uniform Resource 3397 Names for Device Identifiers", RFC 9039, 3398 DOI 10.17487/RFC9039, June 2021, 3399 . 3401 [W3C.GeoLoc] 3402 Worldwide Web Consortium, "Geolocation API Specification 3403 2nd Edition", January 2018, . 3406 Appendix A. Examples 3408 These examples are either UCCS, shown as CBOR diagnostic, or UJCS 3409 messages. Full CWT and JWT examples with signing and encryption are 3410 not given. 3412 All UCCS examples can be the payload of a CWT. To do so, they must 3413 be converted from the UCCS message to a Claims-Set, which is achieve 3414 by "removing" the tag. 3416 UJCS messages can be directly used as the payload of a JWT. 3418 WARNING: These examples use tag and label numbers not yet assigned by 3419 IANA. 3421 A.1. Simple TEE Attestation 3423 This is a simple attestation of a TEE that includes a manifest that 3424 is a payload CoSWID to describe the TEE's software. 3426 / This is a UCCS EAT that describes a simple TEE. / 3428 601({ 3429 / nonce / 10: h'948f8860d13a463e', 3430 / security-level / 261: 3, / secure-restricted / 3431 / secure-boot / 262: true, 3432 / debug-status / 263: 2, / disabled-since-boot / 3433 / manfests / 273: [ 3434 / This is byte-string wrapped / 3435 / payload CoSWID. It gives the TEE / 3436 / software name, the version and / 3437 / the name of the file it is in. / 3438 h' da53574944a60064336132340c01016b 3439 41636d6520544545204f530d65332e31 3440 2e340282a2181f6b41636d6520544545 3441 204f53182101a2181f6b41636d652054 3442 4545204f5318210206a111a118186e61 3443 636d655f7465655f332e657865' 3444 ] 3445 }) 3446 / A payload CoSWID created by the SW vendor. All this really does / 3447 / is name the TEE SW, its version and lists the one file that / 3448 / makes up the TEE. / 3450 1398229316({ 3451 / Unique CoSWID ID / 0: "3a24", 3452 / tag-version / 12: 1, 3453 / software-name / 1: "Acme TEE OS", 3454 / software-version / 13: "3.1.4", 3455 / entity / 2: [ 3456 { 3457 / entity-name / 31: "Acme TEE OS", 3458 / role / 33: 1 / tag-creator / 3459 }, 3460 { 3461 / entity-name / 31: "Acme TEE OS", 3462 / role / 33: 2 / software-creator / 3463 } 3464 ], 3465 / payload / 6: { 3466 / ...file / 17: { 3467 / ...fs-name / 24: "acme_tee_3.exe" 3468 } 3469 } 3470 }) 3472 A.2. Submodules for Board and Device 3473 / This example shows use of submodules to give information / 3474 / about the chip, board and overall device. / 3475 / / 3476 / The main attestation is associated with the chip with the / 3477 / CPU and running the main OS. It is what has the keys and / 3478 / produces the token. / 3479 / / 3480 / The board is made by a different vendor than the chip. / 3481 / Perhaps it is some generic IoT board. / 3482 / / 3483 / The device is some specific appliance that is made by a / 3484 / different vendor than either the chip or the board. / 3485 / / 3486 / Here the board and device submodules aren't the typical / 3487 / target environments as described by the RATS architecture / 3488 / document, but they are a valid use of submodules. / 3490 { 3491 / nonce / 10: h'948f8860d13a463e8e', 3492 / UEID / 256: h'0198f50a4ff6c05861c8860d13a638ea', 3493 / HW OEM ID / 258: h'894823', / IEEE OUI format OEM ID / 3494 / HW Model ID / 259: h'549dcecc8b987c737b44e40f7c635ce8' 3495 / Hash of chip model name /, 3496 / HW Version / 260: ["1.3.4", 1], / Multipartnumeric version / 3497 / SW Name / 271: "Acme OS", 3498 / SW Version / 272: ["3.5.5", 1], 3499 / secure-boot / 262: true, 3500 / debug-status / 263: 3, / permanent-disable / 3501 / timestamp (iat) / 6: 1526542894, 3502 / security-level / 261: 3, / secure restricted OS / 3503 / submods / 266: { 3504 / A submodule to hold some claims about the circuit board / 3505 "board" : { 3506 / HW OEM ID / 258: h'9bef8787eba13e2c8f6e7cb4b1f4619a', 3507 / HW Model ID / 259: h'ee80f5a66c1fb9742999a8fdab930893' 3508 / Hash of board module name /, 3509 / HW Version / 260: ["2.0a", 2] / multipartnumeric+suffix / 3510 }, 3512 / A submodule to hold claims about the overall device / 3513 "device" : { 3514 / HW OEM ID / 258: 61234, / PEN Format OEM ID / 3515 / HW Version / 260: ["4012345123456", 5] / EAN-13 format (barcode) / 3516 } 3517 } 3518 } 3519 A.3. EAT Produced by Attestation Hardware Block 3521 / This is an example of a token produced by a HW block / 3522 / purpose-built for attestation. Only the nonce claim changes / 3523 / from one attestation to the next as the rest either come / 3524 / directly from the hardware or from one-time-programmable memory / 3525 / (e.g. a fuse). 47 bytes encoded in CBOR (8 byte nonce, 16 byte / 3526 / UEID). / 3528 601({ 3529 / nonce / 10: h'948f8860d13a463e', 3530 / UEID / 256: h'0198f50a4ff6c05861c8860d13a638ea', 3531 / OEMID / 258: 64242, / Private Enterprise Number / 3532 / security-level / 261: 4, / hardware level security / 3533 / secure-boot / 262: true, 3534 / debug-status / 263: 3, / disabled-permanently / 3535 / HW version / 260: [ "3.1", 1 ] / Type is multipartnumeric / 3536 }) 3538 A.4. Detached EAT Bundle 3540 In this DEB main token is produced by a HW attestation block. The 3541 detached Claims-Set is produced by a TEE and is largely identical to 3542 the Simple TEE examples above. The TEE digests its Claims-Set and 3543 feeds that digest to the HW block. 3545 In a better example the attestation produced by the HW block would be 3546 a CWT and thus signed and secured by the HW block. Since the 3547 signature covers the digest from the TEE that Claims-Set is also 3548 secured. 3550 The DEB itself can be assembled by untrusted SW. 3552 / This is a detached EAT bundle (DEB) tag. / 3554 602([ 3556 / First part is a full EAT token with claims like nonce and / 3557 / UEID. Most importantly, it includes a submodule that is a / 3558 / detached digest which is the hash of the "TEE" claims set / 3559 / in the next section. / 3560 / / 3561 / This token here is in UCCS format (unsigned). In a more / 3562 / realistic example, it would be a signed CWT. / 3563 h'd90259a80a48948f8860d13a463e190100500198 3564 f50a4ff6c05861c8860d13a638ea19010219faf2 3565 19010504190106f5190107031901048263332e31 3566 0119010aa163544545822f5820e5cf95fd24fab7 3567 1446742dd58d43dae178e55fe2b94291a9291082 3568 ffc2635a0b', 3569 { 3570 / A CBOR-encoded byte-string wrapped EAT claims-set. It / 3571 / contains claims suitable for a TEE / 3572 "TEE" : h'a50a48948f8860d13a463e19010503190106f519 3573 01070219011181585dda53574944a60064336132 3574 340c01016b41636d6520544545204f530d65332e 3575 312e340282a2181f6b41636d6520544545204f53 3576 182101a2181f6b41636d6520544545204f531821 3577 0206a111a118186e61636d655f7465655f332e65 3578 7865' 3579 } 3580 ]) 3582 / This example contains submodule that is a detached digest, / 3583 / which is the hash of a Claims-Set convey outside this token. / 3584 / Other than that is is the other example of a token from an / 3585 / attestation HW block / 3587 601({ 3588 / nonce / 10: h'948f8860d13a463e', 3589 / UEID / 256: h'0198f50a4ff6c05861c8860d13a638ea', 3590 / OEMID / 258: 64242, / Private Enterprise Number / 3591 / security-level / 261: 4, / hardware level security / 3592 / secure-boot / 262: true, 3593 / debug-status / 263: 3, / disabled-permanently / 3594 / hw version / 260: [ "3.1", 1 ], / multipartnumeric / 3595 / submods/ 266: { 3596 "TEE": [ / detached digest submod / 3597 -16, / SHA-256 / 3598 h'e5cf95fd24fab7144674 3599 2dd58d43dae178e55fe2 3600 b94291a9291082ffc2635 3601 a0b' 3602 ] 3603 } 3604 }) 3606 A.5. Key / Key Store Attestation 3608 / This is an attestation of a public key and the key store / 3609 / implementation that protects and manages it. The key store / 3610 / implementation is in a security-oriented execution / 3611 / environment separate from the high-level OS, for example a / 3612 / TEE. The key store is the Attester. / 3613 / / 3614 / There is some attestation of the high-level OS, just version / 3615 / and boot & debug status. It is a Claims-Set submodule because/ 3616 / it has lower security level than the key store. The key / 3617 / store's implementation has access to info about the HLOS, so / 3618 / it is able to include it. / 3619 / / 3620 / A key and an indication of the user authentication given to / 3621 / allow access to the key is given. The labels for these are / 3622 / in the private space since this is just a hypothetical / 3623 / example, not part of a standard protocol. / 3624 / / 3625 / This is similar to Android Key Attestation. / 3627 601({ 3628 / nonce / 10: h'948f8860d13a463e', 3629 / security-level / 261: 3, / secure-restricted / 3630 / secure-boot / 262: true, 3631 / debug-status / 263: 2, / disabled-since-boot / 3632 / manifests / 273: [ 3633 h'da53574944a600683762623334383766 3634 0c000169436172626f6e6974650d6331 3635 2e320e0102a2181f75496e6475737472 3636 69616c204175746f6d6174696f6e1821 3637 02' 3638 / Above is an encoded CoSWID / 3639 / with the following data / 3640 / SW Name: "Carbonite" / 3641 / SW Vers: "1.2" / 3642 / SW Creator: / 3643 / "Industrial Automation" / 3644 ], 3645 / expiration / 4: 1634324274, / 2021-10-15T18:57:54Z / 3646 / creation time / 6: 1634317080, / 2021-10-15T16:58:00Z / 3647 -80000 : "fingerprint", 3648 -80001 : { / The key -- A COSE_Key / 3649 / kty / 1: 2, / EC2, eliptic curve with x & y / 3650 / kid / 2: h'36675c206f96236c3f51f54637b94ced', 3651 / curve / -1: 2, / curve is P-256 / 3652 / x-coord / -2: h'65eda5a12577c2bae829437fe338701a 3653 10aaa375e1bb5b5de108de439c08551d', 3654 / y-coord / -3: h'1e52ed75701163f7f9e40ddf9f341b3d 3655 c9ba860af7e0ca7ca7e9eecd0084d19c' 3656 }, 3658 / submods / 266 : { 3659 "HLOS" : { / submod for high-level OS / 3660 / nonce / 10: h'948f8860d13a463e', 3661 / security-level / 261: 1, / unrestricted / 3662 / secure-boot / 262: true, 3663 / manifests / 273: [ 3664 h'da53574944a600687337 3665 6537346b78380c000168 3666 44726f6964204f530d65 3667 52322e44320e0302a218 3668 1F75496E647573747269 3669 616c204175746f6d6174 3670 696f6e182102' 3671 / Above is an encoded CoSWID / 3672 / with the following data: / 3673 / SW Name: "Droid OS" / 3674 / SW Vers: "R2.D2" / 3675 / SW Creator: / 3676 / "Industrial Automation"/ 3677 ] 3678 } 3679 } 3680 }) 3682 A.6. SW Measurements of an IoT Device 3684 This is a simple token that might be for and IoT device. It includes 3685 CoSWID format measurments of the SW. The CoSWID is in byte-string 3686 wrapped in the token and also shown in diagnostic form. 3688 / This EAT UCCS is for an IoT device with a TEE. The attestation / 3689 / is produced by the TEE. There is a submodule for the IoT OS (the / 3690 / main OS of the IoT device that is not as secure as the TEE). The / 3691 / submodule contains claims for the IoT OS. The TEE also measures / 3692 / the IoT OS and puts the measurements in the submodule. / 3694 601({ 3695 / nonce / 10: h'948f8860d13a463e', 3696 / security-level / 261: 3, / secure-restricted / 3697 / secure-boot / 262: true, 3698 / debug-status / 263: 2, / disabled-since-boot / 3699 / OEMID / 258: h'8945ad', / IEEE CID based / 3700 / UEID / 256: h'0198f50a4ff6c05861c8860d13a638ea', 3701 / sumods / 266: { 3702 "OS" : { 3703 / security-level / 261: 2, / restricted / 3704 / secure-boot / 262: true, 3705 / debug-status / 263: 2, / disabled-since-boot / 3706 / swevidence / 274: [ 3707 / This is a byte-string wrapped / 3708 / evidence CoSWID. It has / 3709 / hashes of the main files of / 3710 / the IoT OS. / 3711 h'da53574944a600663463613234350c 3712 17016d41636d6520522d496f542d4f 3713 530d65332e312e3402a2181f724163 3714 6d6520426173652041747465737465 3715 7218210103a11183a318187161636d 3716 655f725f696f745f6f732e65786514 3717 1a0044b349078201582005f6b327c1 3718 73b4192bd2c3ec248a292215eab456 3719 611bf7a783e25c1782479905a31818 3720 6d7265736f75726365732e72736314 3721 1a000c38b10782015820c142b9aba4 3722 280c4bb8c75f716a43c99526694caa 3723 be529571f5569bb7dc542f98a31818 3724 6a636f6d6d6f6e2e6c6962141a0023 3725 3d3b0782015820a6a9dcdfb3884da5 3726 f884e4e1e8e8629958c2dbc7027414 3727 43a913e34de9333be6' 3728 ] 3729 } 3730 } 3731 }) 3733 / An evidence CoSWID created for the "Acme R-IoT-OS" created by / 3734 / the "Acme Base Attester" (both fictious names). It provides / 3735 / measurements of the SW (other than the attester SW) on the / 3736 / device. / 3738 1398229316({ 3739 / Unique CoSWID ID / 0: "4ca245", 3740 / tag-version / 12: 23, / Attester-maintained counter / 3741 / software-name / 1: "Acme R-IoT-OS", 3742 / software-version / 13: "3.1.4", 3743 / entity / 2: { 3744 / entity-name / 31: "Acme Base Attester", 3745 / role / 33: 1 / tag-creator / 3746 }, 3747 / evidence / 3: { 3748 / ...file / 17: [ 3749 { 3750 / ...fs-name / 24: "acme_r_iot_os.exe", 3751 / ...size / 20: 4502345, 3752 / ...hash / 7: [ 3753 1, / SHA-256 / 3754 h'05f6b327c173b419 3755 2bd2c3ec248a2922 3756 15eab456611bf7a7 3757 83e25c1782479905' 3758 ] 3759 }, 3760 { 3761 / ...fs-name / 24: "resources.rsc", 3762 / ...size / 20: 800945, 3763 / ...hash / 7: [ 3764 1, / SHA-256 / 3765 h'c142b9aba4280c4b 3766 b8c75f716a43c995 3767 26694caabe529571 3768 f5569bb7dc542f98' 3769 ] 3770 }, 3771 { 3772 / ...fs-name / 24: "common.lib", 3773 / ...size / 20: 2309435, 3774 / ...hash / 7: [ 3775 1, / SHA-256 / 3776 h'a6a9dcdfb3884da5 3777 f884e4e1e8e86299 3778 58c2dbc702741443 3779 a913e34de9333be6' 3780 ] 3781 } 3782 ] 3784 } 3785 }) 3787 A.7. Attestation Results in JSON format 3789 This is a UJCS format token that might be the output of a Verifier 3790 that evaluated the IoT Attestation example immediately above. 3792 This particular Verifier knows enough about the TEE Attester to be 3793 able to pass claims like security level directly through to the 3794 Relying Party. The Verifier also knows the Reference Values for the 3795 measured SW components and is able to check them. It informs the 3796 Relying Party that they were correct in the swresults claim. 3797 "Trustus Verifications" is the name of the services that verifies the 3798 SW component measurements. 3800 This UJCS is identical to JSON-encoded Claims-Set that could be a JWT 3801 payload. 3803 { 3804 "nonce" : "lI+IYNE6Rj4=", 3805 "seclevel" : "secure-restricted", 3806 "secboot" : true, 3807 "dbgstat" : "disabled-since-boot", 3808 "OEMID" : "iUWt", 3809 "UEID" : "AZj1Ck/2wFhhyIYNE6Y4", 3810 "submods" : { 3811 "seclevel" : "restricted", 3812 "secboot" : true, 3813 "dbgstat" : "disabled-since-boot", 3814 "swname" : "Acme R-IoT-OS", 3815 "sw-version" : [ 3816 "3.1.4" 3817 ], 3818 "swresults" : [ 3819 [ 3820 "Trustus Verifications", 3821 "all", 3822 "fully-verified" 3823 ] 3824 ] 3825 } 3827 Appendix B. UEID Design Rationale 3829 B.1. Collision Probability 3831 This calculation is to determine the probability of a collision of 3832 UEIDs given the total possible entity population and the number of 3833 entities in a particular entity management database. 3835 Three different sized databases are considered. The number of 3836 devices per person roughly models non-personal devices such as 3837 traffic lights, devices in stores they shop in, facilities they work 3838 in and so on, even considering individual light bulbs. A device may 3839 have individually attested subsystems, for example parts of a car or 3840 a mobile phone. It is assumed that the largest database will have at 3841 most 10% of the world's population of devices. Note that databases 3842 that handle more than a trillion records exist today. 3844 The trillion-record database size models an easy-to-imagine reality 3845 over the next decades. The quadrillion-record database is roughly at 3846 the limit of what is imaginable and should probably be accommodated. 3847 The 100 quadrillion datadbase is highly speculative perhaps involving 3848 nanorobots for every person, livestock animal and domesticated bird. 3849 It is included to round out the analysis. 3851 Note that the items counted here certainly do not have IP address and 3852 are not individually connected to the network. They may be connected 3853 to internal buses, via serial links, Bluetooth and so on. This is 3854 not the same problem as sizing IP addresses. 3856 +---------+------------+--------------+------------+----------------+ 3857 | People | Devices / | Subsystems / | Database | Database Size | 3858 | | Person | Device | Portion | | 3859 +---------+------------+--------------+------------+----------------+ 3860 | 10 | 100 | 10 | 10% | trillion | 3861 | billion | | | | (10^12) | 3862 | 10 | 100,000 | 10 | 10% | quadrillion | 3863 | billion | | | | (10^15) | 3864 | 100 | 1,000,000 | 10 | 10% | 100 | 3865 | billion | | | | quadrillion | 3866 | | | | | (10^17) | 3867 +---------+------------+--------------+------------+----------------+ 3869 This is conceptually similar to the Birthday Problem where m is the 3870 number of possible birthdays, always 365, and k is the number of 3871 people. It is also conceptually similar to the Birthday Attack where 3872 collisions of the output of hash functions are considered. 3874 The proper formula for the collision calculation is 3875 p = 1 - e^{-k^2/(2n)} 3877 p Collision Probability 3878 n Total possible population 3879 k Actual population 3881 However, for the very large values involved here, this formula 3882 requires floating point precision higher than commonly available in 3883 calculators and SW so this simple approximation is used. See 3884 [BirthdayAttack]. 3886 p = k^2 / 2n 3888 For this calculation: 3890 p Collision Probability 3891 n Total population based on number of bits in UEID 3892 k Population in a database 3894 +----------------------+--------------+--------------+--------------+ 3895 | Database Size | 128-bit UEID | 192-bit UEID | 256-bit UEID | 3896 +----------------------+--------------+--------------+--------------+ 3897 | trillion (10^12) | 2 * 10^-15 | 8 * 10^-35 | 5 * 10^-55 | 3898 | quadrillion (10^15) | 2 * 10^-09 | 8 * 10^-29 | 5 * 10^-49 | 3899 | 100 quadrillion | 2 * 10^-05 | 8 * 10^-25 | 5 * 10^-45 | 3900 | (10^17) | | | | 3901 +----------------------+--------------+--------------+--------------+ 3903 Next, to calculate the probability of a collision occurring in one 3904 year's operation of a database, it is assumed that the database size 3905 is in a steady state and that 10% of the database changes per year. 3906 For example, a trillion record database would have 100 billion states 3907 per year. Each of those states has the above calculated probability 3908 of a collision. 3910 This assumption is a worst-case since it assumes that each state of 3911 the database is completely independent from the previous state. In 3912 reality this is unlikely as state changes will be the addition or 3913 deletion of a few records. 3915 The following tables gives the time interval until there is a 3916 probability of a collision based on there being one tenth the number 3917 of states per year as the number of records in the database. 3919 t = 1 / ((k / 10) * p) 3921 t Time until a collision 3922 p Collision probability for UEID size 3923 k Database size 3925 +---------------------+---------------+--------------+--------------+ 3926 | Database Size | 128-bit UEID | 192-bit UEID | 256-bit UEID | 3927 +---------------------+---------------+--------------+--------------+ 3928 | trillion (10^12) | 60,000 years | 10^24 years | 10^44 years | 3929 | quadrillion (10^15) | 8 seconds | 10^14 years | 10^34 years | 3930 | 100 quadrillion | 8 | 10^11 years | 10^31 years | 3931 | (10^17) | microseconds | | | 3932 +---------------------+---------------+--------------+--------------+ 3934 Clearly, 128 bits is enough for the near future thus the requirement 3935 that UEIDs be a minimum of 128 bits. 3937 There is no requirement for 256 bits today as quadrillion-record 3938 databases are not expected in the near future and because this time- 3939 to-collision calculation is a very worst case. A future update of 3940 the standard may increase the requirement to 256 bits, so there is a 3941 requirement that implementations be able to receive 256-bit UEIDs. 3943 B.2. No Use of UUID 3945 A UEID is not a UUID [RFC4122] by conscious choice for the following 3946 reasons. 3948 UUIDs are limited to 128 bits which may not be enough for some future 3949 use cases. 3951 Today, cryptographic-quality random numbers are available from common 3952 CPUs and hardware. This hardware was introduced between 2010 and 3953 2015. Operating systems and cryptographic libraries give access to 3954 this hardware. Consequently, there is little need for 3955 implementations to construct such random values from multiple sources 3956 on their own. 3958 Version 4 UUIDs do allow for use of such cryptographic-quality random 3959 numbers, but do so by mapping into the overall UUID structure of time 3960 and clock values. This structure is of no value here yet adds 3961 complexity. It also slightly reduces the number of actual bits with 3962 entropy. 3964 UUIDs seem to have been designed for scenarios where the implementor 3965 does not have full control over the environment and uniqueness has to 3966 be constructed from identifiers at hand. UEID takes the view that 3967 hardware, software and/or manufacturing process directly implement 3968 UEID in a simple and direct way. It takes the view that 3969 cryptographic quality random number generators are readily available 3970 as they are implemented in commonly used CPU hardware. 3972 Appendix C. EAT Relation to IEEE.802.1AR Secure Device Identity (DevID) 3974 This section describes several distinct ways in which an IEEE IDevID 3975 [IEEE.802.1AR] relates to EAT, particularly to UEID and SUEID. 3977 [IEEE.802.1AR] orients around the definition of an implementation 3978 called a "DevID Module." It describes how IDevIDs and LDevIDs are 3979 stored, protected and accessed using a DevID Module. A particular 3980 level of defense against attack that should be achieved to be a DevID 3981 is defined. The intent is that IDevIDs and LDevIDs are used with an 3982 open set of network protocols for authentication and such. In these 3983 protocols the DevID secret is used to sign a nonce or similar to 3984 proof the association of the DevID certificates with the device. 3986 By contrast, EAT defines network protocol for proving trustworthiness 3987 to a Relying Party, the very thing that is not defined in 3988 [IEEE.802.1AR]. Nor does not give details on how keys, data and such 3989 are stored protected and accessed. EAT is intended to work with a 3990 variety of different on-device implementations ranging from minimal 3991 protection of assets to the highest levels of asset protection. It 3992 does not define any particular level of defense against attack, 3993 instead providing a set of security considerations. 3995 EAT and DevID can be viewed as complimentary when used together or as 3996 competing to provide a device identity service. 3998 C.1. DevID Used With EAT 4000 As just described, EAT defines a network protocol and [IEEE.802.1AR] 4001 doesn't. Vice versa, EAT doesn't define a an device implementation 4002 and DevID does. 4004 Hence, EAT can be the network protocol that a DevID is used with. 4005 The DevID secret becomes the attestation key used to sign EATs. The 4006 DevID and its certificate chain become the Endorsement sent to the 4007 Verifier. 4009 In this case the EAT and the DevID are likely to both provide a 4010 device identifier (e.g. a serial number). In the EAT it is the UEID 4011 (or SUEID). In the DevID (used as an endorsement), it is a device 4012 serial number included in the subject field of the DevID certificate. 4013 It is probably a good idea in this use for them to be the same serial 4014 number or for the UEID to be a hash of the DevID serial number. 4016 C.2. How EAT Provides an Equivalent Secure Device Identity 4018 The UEID, SUEID and other claims like OEM ID are equivalent to the 4019 secure device identity put into the subject field of a DevID 4020 certificate. These EAT claims can represent all the same fields and 4021 values that can be put in a DevID certificate subject. EAT 4022 explicitly and carefully defines a variety of useful claims. 4024 EAT secures the conveyance of these claims by having them signed on 4025 the device by the attestation key when the EAT is generated. EAT 4026 also signs the nonce that gives freshness at this time. Since these 4027 claims are signed for every EAT generated, they can include things 4028 that vary over time like GPS location. 4030 DevID secures the device identity fields by having them signed by the 4031 manufacturer of the device sign them into a certificate. That 4032 certificate is created once during the manufacturing of the device 4033 and never changes so the fields cannot change. 4035 So in one case the signing of the identity happens on the device and 4036 the other in a manufacturing facility, but in both cases the signing 4037 of the nonce that proves the binding to the actual device happens on 4038 the device. 4040 While EAT does not specify how the signing keys, signature process 4041 and storage of the identity values should be secured against attack, 4042 an EAT implementation may have equal defenses against attack. One 4043 reason EAT uses CBOR is because it is simple enough that a basic EAT 4044 implementation can be constructed entirely in hardware. This allows 4045 EAT to be implemented with the strongest defenses possible. 4047 C.3. An X.509 Format EAT 4049 It is possible to define a way to encode EAT claims in an X.509 4050 certificate. For example, the EAT claims might be mapped to X.509 v3 4051 extensions. It is even possible to stuff a whole CBOR-encoded 4052 unsigned EAT token into a X.509 certificate. 4054 If that X.509 certificate is an IDevID or LDevID, this becomes 4055 another way to use EAT and DevID together. 4057 Note that the DevID must still be used with an authentication 4058 protocol that has a nonce or equivalent. The EAT here is not being 4059 used as the protocol to interact with the rely party. 4061 C.4. Device Identifier Permanence 4063 In terms of permanence, an IDevID is similar to a UEID in that they 4064 do not change over the life of the device. They cease to exist only 4065 when the device is destroyed. 4067 An SUEID is similar to an LDevID. They change on device life-cycle 4068 events. 4070 [IEEE.802.1AR] describes much of this permanence as resistant to 4071 attacks that seek to change the ID. IDevID permanence can be 4072 described this way because [IEEE.802.1AR] is oriented around the 4073 definition of an implementation with a particular level of defense 4074 against attack. 4076 EAT is not defined around a particular implementation and must work 4077 on a range of devices that have a range of defenses against attack. 4078 EAT thus can't be defined permanence in terms of defense against 4079 attack. EAT's definition of permanence is in terms of operations and 4080 device lifecycle. 4082 Appendix D. Changes from Previous Drafts 4084 The following is a list of known changes from the previous drafts. 4085 This list is non-authoritative. It is meant to help reviewers see 4086 the significant differences. 4088 D.1. From draft-rats-eat-01 4090 o Added UEID design rationale appendix 4092 D.2. From draft-mandyam-rats-eat-00 4094 This is a fairly large change in the orientation of the document, but 4095 no new claims have been added. 4097 o Separate information and data model using CDDL. 4099 o Say an EAT is a CWT or JWT 4101 o Use a map to structure the boot_state and location claims 4103 D.3. From draft-ietf-rats-eat-01 4105 o Clarifications and corrections for OEMID claim 4107 o Minor spelling and other fixes 4108 o Add the nonce claim, clarify jti claim 4110 D.4. From draft-ietf-rats-eat-02 4112 o Roll all EUIs back into one UEID type 4114 o UEIDs can be one of three lengths, 128, 192 and 256. 4116 o Added appendix justifying UEID design and size. 4118 o Submods part now includes nested eat tokens so they can be named 4119 and there can be more tha one of them 4121 o Lots of fixes to the CDDL 4123 o Added security considerations 4125 D.5. From draft-ietf-rats-eat-03 4127 o Split boot_state into secure-boot and debug-disable claims 4129 o Debug disable is an enumerated type rather than Booleans 4131 D.6. From draft-ietf-rats-eat-04 4133 o Change IMEI-based UEIDs to be encoded as a 14-byte string 4135 o CDDL cleaned up some more 4137 o CDDL allows for JWTs and UCCSs 4139 o CWT format submodules are byte string wrapped 4141 o Allows for JWT nested in CWT and vice versa 4143 o Allows UCCS (unsigned CWTs) and JWT unsecured tokens 4145 o Clarify tag usage when nesting tokens 4147 o Add section on key inclusion 4149 o Add hardware version claims 4151 o Collected CDDL is now filled in. Other CDDL corrections. 4153 o Rename debug-disable to debug-status; clarify that it is not 4154 extensible 4156 o Security level claim is not extensible 4158 o Improve specification of location claim and added a location 4159 privacy section 4161 o Add intended use claim 4163 D.7. From draft-ietf-rats-eat-05 4165 o CDDL format issues resolved 4167 o Corrected reference to Location Privacy section 4169 D.8. From draft-ietf-rats-eat-06 4171 o Added boot-seed claim 4173 o Rework CBOR interoperability section 4175 o Added profiles claim and section 4177 D.9. From draft-ietf-rats-eat-07 4179 o Filled in IANA and other sections for possible preassignment of 4180 Claim Keys for well understood claims 4182 D.10. From draft-ietf-rats-eat-08 4184 o Change profile claim to be either a URL or an OID rather than a 4185 test string 4187 D.11. From draft-ietf-rats-eat-09 4189 o Add SUEIDs 4191 o Add appendix comparing IDevID to EAT 4193 o Added section on use for Evidence and Attestation Results 4195 o Fill in the key ID and endorsements identificaiton section 4197 o Remove origination claim as it is replaced by key IDs and 4198 endorsements 4200 o Added manifests and software evidence claims 4202 o Add string labels non-claim labels for use with JSON (e.g. labels 4203 for members of location claim) 4205 o EAN-13 HW versions are no longer a separate claim. Now they are 4206 folded in as a CoSWID version scheme. 4208 D.12. From draft-ietf-rats-eat-10 4210 o Hardware version is made into an array of two rather than two 4211 claims 4213 o Corrections and wording improvements for security levels claim 4215 o Add swresults claim 4217 o Add dloas claim - Digitial Letter of Approvals, a list of 4218 certifications 4220 o CDDL for each claim no longer in a separate sub section 4222 o Consistent use of terminology from RATS architecture document 4224 o Consistent use of terminology from CWT and JWT documents 4226 o Remove operating model and procedures; refer to CWT, JWT and RATS 4227 architecture instead 4229 o Some reorganization of Section 1 4231 o Moved a few references, including RATS Architecture, to 4232 informative. 4234 o Add detached submodule digests and detached eat bundles (DEBs) 4236 o New simpler and more universal scheme for identifying the encoding 4237 of a nested token 4239 o Made clear that CBOR and JSON are only mixed when nesting a token 4240 in another token 4242 o Clearly separate CDDL for JSON and CBOR-specific data items 4244 o Define UJCS (unsigned JWTs) 4246 o Add CDDL for a general Claims-Set used by UCCS, UJCS, CWT, JWT and 4247 EAT 4249 o Top level CDDL for CWT correctly refers to COSE 4251 o OEM ID is specifically for HW, not for SW 4252 o HW OEM ID can now be a PEN 4254 o HW OEM ID can now be a 128-bit random number 4256 o Expand the examples section 4258 o Add software and version claims as easy / JSON alternative to 4259 CoSWID 4261 D.13. From draft-ietf-rats-eat-11 4263 o Add HW model claim 4265 o Change reference for CBOR OID draft to RFC 9090 4267 o Correct the iat claim in some examples 4269 o Make HW Version just one claim rather than 3 (device, board and 4270 chip) 4272 o Remove CDDL comments from CDDL blocks 4274 o More clearly define "entity" and use it more broadly, particularly 4275 instead of "device" 4277 o Re do early allocation of CBOR labels since last one didn't 4278 complete correctly 4280 o Lots of rewording and tightening up of section 1 4282 o Lots of wording improvements in section 3, particularly better use 4283 of normative language 4285 o Improve wording in submodules section, particularly how to 4286 distinguish types when decoding 4288 o Remove security-level from early allocation 4290 o Add boot odometer claim 4292 o Add privacy considerations for replay protection 4294 Authors' Addresses 4296 Laurence Lundblade 4297 Security Theory LLC 4299 EMail: lgl@securitytheory.com 4300 Giridhar Mandyam 4301 Qualcomm Technologies Inc. 4302 5775 Morehouse Drive 4303 San Diego, California 4304 USA 4306 Phone: +1 858 651 7200 4307 EMail: mandyam@qti.qualcomm.com 4309 Jeremy O'Donoghue 4310 Qualcomm Technologies Inc. 4311 279 Farnborough Road 4312 Farnborough GU14 7LS 4313 United Kingdom 4315 Phone: +44 1252 363189 4316 EMail: jodonogh@qti.qualcomm.com