idnits 2.17.1 draft-ietf-rats-eat-10.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 4 instances of too long lines in the document, the longest one being 18 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (June 07, 2021) is 1047 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 (-08) exists of draft-ietf-cbor-tags-oid-06 -- Possible downref: Non-RFC (?) normative reference: ref. 'CoSWID' -- Possible downref: Non-RFC (?) normative reference: ref. 'EAN-13' -- Possible downref: Non-RFC (?) normative reference: ref. 'OpenIDConnectCore' == Outdated reference: A later version (-22) exists of draft-ietf-rats-architecture-12 ** Downref: Normative reference to an Informational draft: draft-ietf-rats-architecture (ref. 'RATS-Architecture') ** Obsolete normative reference: RFC 8152 (Obsoleted by RFC 9052, RFC 9053) -- Possible downref: Non-RFC (?) normative reference: ref. 'WGS84' Summary: 3 errors (**), 0 flaws (~~), 3 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 RATS Working Group G. Mandyam 3 Internet-Draft Qualcomm Technologies Inc. 4 Intended status: Standards Track L. Lundblade 5 Expires: December 9, 2021 Security Theory LLC 6 M. Ballesteros 7 J. O'Donoghue 8 Qualcomm Technologies Inc. 9 June 07, 2021 11 The Entity Attestation Token (EAT) 12 draft-ietf-rats-eat-10 14 Abstract 16 An Entity Attestation Token (EAT) provides a signed (attested) set of 17 claims that describe state and characteristics of an entity, 18 typically a device like a phone or an IoT device. These claims are 19 used by a relying party to determine how much it wishes to trust the 20 entity. 22 An EAT is either a CWT or JWT with some attestation-oriented claims. 23 To a large degree, all this document does is extend CWT and JWT. 25 Contributing 27 TBD 29 Status of This Memo 31 This Internet-Draft is submitted in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF). Note that other groups may also distribute 36 working documents as Internet-Drafts. The list of current Internet- 37 Drafts is at https://datatracker.ietf.org/drafts/current/. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 This Internet-Draft will expire on December 9, 2021. 46 Copyright Notice 48 Copyright (c) 2021 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents 53 (https://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with respect 56 to this document. Code Components extracted from this document must 57 include Simplified BSD License text as described in Section 4.e of 58 the Trust Legal Provisions and are provided without warranty as 59 described in the Simplified BSD License. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5 64 1.1. CWT, JWT and UCCS . . . . . . . . . . . . . . . . . . . . 6 65 1.2. CDDL . . . . . . . . . . . . . . . . . . . . . . . . . . 6 66 1.3. Entity Overview . . . . . . . . . . . . . . . . . . . . . 6 67 1.4. Use as Evidence and Attestation Results . . . . . . . . . 7 68 1.5. EAT Operating Models . . . . . . . . . . . . . . . . . . 7 69 1.6. What is Not Standardized . . . . . . . . . . . . . . . . 9 70 1.6.1. Transmission Protocol . . . . . . . . . . . . . . . . 9 71 1.6.2. Signing Scheme . . . . . . . . . . . . . . . . . . . 9 72 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 10 73 3. The Claims . . . . . . . . . . . . . . . . . . . . . . . . . 10 74 3.1. Token ID Claim (cti and jti) . . . . . . . . . . . . . . 11 75 3.2. Timestamp claim (iat) . . . . . . . . . . . . . . . . . . 11 76 3.3. Nonce Claim (nonce) . . . . . . . . . . . . . . . . . . . 12 77 3.3.1. nonce CDDL . . . . . . . . . . . . . . . . . . . . . 12 78 3.4. Universal Entity ID Claim (ueid) . . . . . . . . . . . . 12 79 3.4.1. ueid CDDL . . . . . . . . . . . . . . . . . . . . . . 15 80 3.5. Semi-permanent UEIDs (SUEIDs) . . . . . . . . . . . . . . 15 81 3.6. OEM Identification by IEEE (oemid) . . . . . . . . . . . 16 82 3.6.1. oemid CDDL . . . . . . . . . . . . . . . . . . . . . 16 83 3.7. Hardware Version Claims (hardware-version-claims) . . . . 16 84 3.8. Software Description and Version . . . . . . . . . . . . 17 85 3.9. The Security Level Claim (security-level) . . . . . . . . 17 86 3.9.1. security-level CDDL . . . . . . . . . . . . . . . . . 18 87 3.10. Secure Boot Claim (secure-boot) . . . . . . . . . . . . . 19 88 3.10.1. secure-boot CDDL . . . . . . . . . . . . . . . . . . 19 89 3.11. Debug Status Claim (debug-status) . . . . . . . . . . . . 19 90 3.11.1. Enabled . . . . . . . . . . . . . . . . . . . . . . 20 91 3.11.2. Disabled . . . . . . . . . . . . . . . . . . . . . . 21 92 3.11.3. Disabled Since Boot . . . . . . . . . . . . . . . . 21 93 3.11.4. Disabled Permanently . . . . . . . . . . . . . . . . 21 94 3.11.5. Disabled Fully and Permanently . . . . . . . . . . . 21 95 3.11.6. debug-status CDDL . . . . . . . . . . . . . . . . . 21 96 3.12. Including Keys . . . . . . . . . . . . . . . . . . . . . 22 97 3.13. The Location Claim (location) . . . . . . . . . . . . . . 22 98 3.13.1. location CDDL . . . . . . . . . . . . . . . . . . . 23 99 3.14. The Uptime Claim (uptime) . . . . . . . . . . . . . . . . 24 100 3.14.1. uptime CDDL . . . . . . . . . . . . . . . . . . . . 24 101 3.15. The Boot Seed Claim (boot-seed) . . . . . . . . . . . . . 24 102 3.16. The Intended Use Claim (intended-use) . . . . . . . . . . 24 103 3.16.1. intended-use CDDL . . . . . . . . . . . . . . . . . 25 104 3.17. The Profile Claim (profile) . . . . . . . . . . . . . . . 25 105 3.18. The Software Manifests Claim (manifests) . . . . . . . . 26 106 3.19. The Software Evidence Claim {swevidence} . . . . . . . . 27 107 3.20. The Submodules Part of a Token (submods) . . . . . . . . 28 108 3.20.1. Two Types of Submodules . . . . . . . . . . . . . . 28 109 3.20.1.1. Non-token Submodules . . . . . . . . . . . . . . 29 110 3.20.1.2. Nested EATs . . . . . . . . . . . . . . . . . . 29 111 3.20.1.3. Unsecured JWTs and UCCS Tokens as Submodules . . 30 112 3.20.2. No Inheritance . . . . . . . . . . . . . . . . . . . 30 113 3.20.3. Security Levels . . . . . . . . . . . . . . . . . . 31 114 3.20.4. Submodule Names . . . . . . . . . . . . . . . . . . 31 115 3.20.5. submods CDDL . . . . . . . . . . . . . . . . . . . . 31 116 4. Endorsements and Verification Keys . . . . . . . . . . . . . 32 117 4.1. Identification Methods . . . . . . . . . . . . . . . . . 33 118 4.1.1. COSE/JWS Key ID . . . . . . . . . . . . . . . . . . . 33 119 4.1.2. JWS and COSE X.509 Header Parameters . . . . . . . . 34 120 4.1.3. CBOR Certificate COSE Header Parameters . . . . . . . 34 121 4.1.4. Claim-Based Key Identification . . . . . . . . . . . 34 122 4.2. Other Considerations . . . . . . . . . . . . . . . . . . 34 123 5. Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . 35 124 5.1. Format of a Profile Document . . . . . . . . . . . . . . 35 125 5.2. List of Profile Issues . . . . . . . . . . . . . . . . . 35 126 5.2.1. Use of JSON, CBOR or both . . . . . . . . . . . . . . 35 127 5.2.2. CBOR Map and Array Encoding . . . . . . . . . . . . . 35 128 5.2.3. CBOR String Encoding . . . . . . . . . . . . . . . . 36 129 5.2.4. CBOR Preferred Serialization . . . . . . . . . . . . 36 130 5.2.5. COSE/JOSE Protection . . . . . . . . . . . . . . . . 36 131 5.2.6. COSE/JOSE Algorithms . . . . . . . . . . . . . . . . 36 132 5.2.7. Verification Key Identification . . . . . . . . . . . 37 133 5.2.8. Endorsement Identification . . . . . . . . . . . . . 37 134 5.2.9. Freshness . . . . . . . . . . . . . . . . . . . . . . 37 135 5.2.10. Required Claims . . . . . . . . . . . . . . . . . . . 37 136 5.2.11. Prohibited Claims . . . . . . . . . . . . . . . . . . 37 137 5.2.12. Additional Claims . . . . . . . . . . . . . . . . . . 37 138 5.2.13. Refined Claim Definition . . . . . . . . . . . . . . 37 139 5.2.14. CBOR Tags . . . . . . . . . . . . . . . . . . . . . . 38 140 5.2.15. Manifests and Software Evidence Claims . . . . . . . 38 141 6. Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . 38 142 6.1. Common CDDL Types . . . . . . . . . . . . . . . . . . . . 38 143 6.2. CDDL for CWT-defined Claims . . . . . . . . . . . . . . . 38 144 6.3. JSON . . . . . . . . . . . . . . . . . . . . . . . . . . 39 145 6.3.1. JSON Labels . . . . . . . . . . . . . . . . . . . . . 39 146 6.3.2. JSON Interoperability . . . . . . . . . . . . . . . . 40 147 6.4. CBOR . . . . . . . . . . . . . . . . . . . . . . . . . . 41 148 6.4.1. CBOR Interoperability . . . . . . . . . . . . . . . . 41 149 6.4.1.1. EAT Constrained Device Serialization . . . . . . 41 150 6.5. Collected CDDL . . . . . . . . . . . . . . . . . . . . . 42 151 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 47 152 7.1. Reuse of CBOR Web Token (CWT) Claims Registry . . . . . . 47 153 7.2. Claim Characteristics . . . . . . . . . . . . . . . . . . 48 154 7.2.1. Interoperability and Relying Party Orientation . . . 48 155 7.2.2. Operating System and Technology Neutral . . . . . . . 48 156 7.2.3. Security Level Neutral . . . . . . . . . . . . . . . 49 157 7.2.4. Reuse of Extant Data Formats . . . . . . . . . . . . 49 158 7.2.5. Proprietary Claims . . . . . . . . . . . . . . . . . 49 159 7.3. Claims Registered by This Document . . . . . . . . . . . 49 160 7.3.1. Claims for Early Assignment . . . . . . . . . . . . . 50 161 7.3.2. To be Assigned Claims . . . . . . . . . . . . . . . . 53 162 7.3.3. Version Schemes Registered by this Document . . . . . 53 163 8. Privacy Considerations . . . . . . . . . . . . . . . . . . . 53 164 8.1. UEID and SUEID Privacy Considerations . . . . . . . . . . 53 165 8.2. Location Privacy Considerations . . . . . . . . . . . . . 54 166 9. Security Considerations . . . . . . . . . . . . . . . . . . . 54 167 9.1. Key Provisioning . . . . . . . . . . . . . . . . . . . . 55 168 9.1.1. Transmission of Key Material . . . . . . . . . . . . 55 169 9.2. Transport Security . . . . . . . . . . . . . . . . . . . 55 170 9.3. Multiple EAT Consumers . . . . . . . . . . . . . . . . . 56 171 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 56 172 10.1. Normative References . . . . . . . . . . . . . . . . . . 56 173 10.2. Informative References . . . . . . . . . . . . . . . . . 59 174 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 61 175 A.1. Very Simple EAT . . . . . . . . . . . . . . . . . . . . . 61 176 A.2. Example with Submodules, Nesting and Security Levels . . 61 177 Appendix B. UEID Design Rationale . . . . . . . . . . . . . . . 61 178 B.1. Collision Probability . . . . . . . . . . . . . . . . . . 62 179 B.2. No Use of UUID . . . . . . . . . . . . . . . . . . . . . 64 180 Appendix C. EAT Relation to IEEE.802.1AR Secure Device Identity 181 (DevID) . . . . . . . . . . . . . . . . . . . . . . 65 182 C.1. DevID Used With EAT . . . . . . . . . . . . . . . . . . . 65 183 C.2. How EAT Provides an Equivalent Secure Device Identity . . 66 184 C.3. An X.509 Format EAT . . . . . . . . . . . . . . . . . . . 66 185 C.4. Device Identifier Permanence . . . . . . . . . . . . . . 67 186 Appendix D. Changes from Previous Drafts . . . . . . . . . . . . 67 187 D.1. From draft-rats-eat-01 . . . . . . . . . . . . . . . . . 67 188 D.2. From draft-mandyam-rats-eat-00 . . . . . . . . . . . . . 67 189 D.3. From draft-ietf-rats-eat-01 . . . . . . . . . . . . . . . 67 190 D.4. From draft-ietf-rats-eat-02 . . . . . . . . . . . . . . . 68 191 D.5. From draft-ietf-rats-eat-03 . . . . . . . . . . . . . . . 68 192 D.6. From draft-ietf-rats-eat-04 . . . . . . . . . . . . . . . 68 193 D.7. From draft-ietf-rats-05 . . . . . . . . . . . . . . . . . 69 194 D.8. From draft-ietf-rats-06 . . . . . . . . . . . . . . . . . 69 195 D.9. From draft-ietf-rats-07 . . . . . . . . . . . . . . . . . 69 196 D.10. From draft-ietf-rats-08 . . . . . . . . . . . . . . . . . 69 197 D.11. From draft-ietf-rats-09 . . . . . . . . . . . . . . . . . 69 198 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 70 200 1. Introduction 202 Remote device attestation is a fundamental service that allows a 203 remote device such as a mobile phone, an Internet-of-Things (IoT) 204 device, or other endpoint to prove itself to a relying party, a 205 server or a service. This allows the relying party to know some 206 characteristics about the device and decide whether it trusts the 207 device. 209 Remote attestation is a fundamental service that can underlie other 210 protocols and services that need to know about the trustworthiness of 211 the device before proceeding. One good example is biometric 212 authentication where the biometric matching is done on the device. 213 The relying party needs to know that the device is one that is known 214 to do biometric matching correctly. Another example is content 215 protection where the relying party wants to know the device will 216 protect the data. This generalizes on to corporate enterprises that 217 might want to know that a device is trustworthy before allowing 218 corporate data to be accessed by it. 220 The notion of attestation here is large and may include, but is not 221 limited to the following: 223 o Proof of the make and model of the device hardware (HW) 225 o Proof of the make and model of the device processor, particularly 226 for security-oriented chips 228 o Measurement of the software (SW) running on the device 230 o Configuration and state of the device 232 o Environmental characteristics of the device such as its GPS 233 location 235 1.1. CWT, JWT and UCCS 237 For flexibility and ease of imlpementation in a wide variety of 238 environments, EATs can be either CBOR [RFC8949] or JSON [ECMAScript] 239 format. This specification simultaneously describes both formats. 241 An EAT is either a CWT as defined in [RFC8392], a UCCS as defined in 242 [UCCS.Draft], or a JWT as defined in [RFC7519]. This specification 243 extends those specifications with additional claims for attestation. 245 The identification of a protocol element as an EAT, whether CBOR or 246 JSON format, follows the general conventions used by CWT, JWT and 247 UCCS. Largely this depends on the protocol carrying the EAT. In 248 some cases it may be by content type (e.g., MIME type). In other 249 cases it may be through use of CBOR tags. There is no fixed 250 mechanism across all use cases. 252 1.2. CDDL 254 This specification uses CDDL, [RFC8610], as the primary formalism to 255 define each claim. The implementor then interprets the CDDL to come 256 to either the CBOR [RFC8949] or JSON [ECMAScript] representation. In 257 the case of JSON, Appendix E of [RFC8610] is followed. Additional 258 rules are given in Section 6.3.2 of this document where Appendix E is 259 insufficient. (Note that this is not to define a general means to 260 translate between CBOR and JSON, but only to define enough such that 261 the claims defined in this document can be rendered unambiguously in 262 JSON). 264 The CWT specification was authored before CDDL was available and did 265 not use it. This specification includes a CDDL definition of most of 266 what is described in [RFC8392]. 268 1.3. Entity Overview 270 An "entity" can be any device or device subassembly ("submodule") 271 that can generate its own attestation in the form of an EAT. The 272 attestation should be cryptographically verifiable by the EAT 273 consumer. An EAT at the device-level can be composed of several 274 submodule EAT's. 276 Modern devices such as a mobile phone have many different execution 277 environments operating with different security levels. For example, 278 it is common for a mobile phone to have an "apps" environment that 279 runs an operating system (OS) that hosts a plethora of downloadable 280 apps. It may also have a TEE (Trusted Execution Environment) that is 281 distinct, isolated, and hosts security-oriented functionality like 282 biometric authentication. Additionally, it may have an eSE (embedded 283 Secure Element) - a high security chip with defenses against HW 284 attacks that is used to produce attestations. This device 285 attestation format allows the attested data to be tagged at a 286 security level from which it originates. In general, any discrete 287 execution environment that has an identifiable security level can be 288 considered an entity. 290 1.4. Use as Evidence and Attestation Results 292 Here, normative reference is made to [RATS-Architecture], 293 particularly the definition of Evidence, the Verifier, Attestation 294 Results and the Relying Party. Per Figure 1 in [RATS-Architecture], 295 Evidence is a protocol message that goes from the Attester to the 296 Verifier and Attestation Results a message that goes from the 297 Verifier to the Relying Party. EAT is defined such that it can be 298 used to represent either Evidence, Attestation Results or both. No 299 claims defined here are considered exclusive to or are prohibited in 300 either use. It is useful to create EAT profiles as described in 301 Section 5 for either use. 303 It is useful to characterize the relationship of claims in Evidence 304 to those in Attestation Results. 306 Many claims in Evidence simply will pass through the Verifier to the 307 Relying Party without modification. They will be verified as 308 authentic from the device by the Verifier just through normal 309 verification of the Attester's signature. They will be protected 310 from modification when they are conveyed to the Relying Party by 311 whatever means is used to protect Attestation Results. (The details 312 of that protection are out of scope of this document.) 314 Some claims in Evidence will be verified by the Verifier by 315 comparison to Reference Values. In this case the claims in Evidence 316 will not likely be conveyed to the Relying Party. Instead, some 317 claim indicating they were checked may be added to the Attestation 318 Results or it may be tacitly known that the Verifier always does this 319 check. 321 In some cases the Verifier may provide privacy-preserving 322 functionality by stripping or modifying claims that do not posses 323 sufficient privacy-preserving characteristics. 325 1.5. EAT Operating Models 327 TODO: Rewrite (or eliminate) this section in light of the RATS 328 architecture draft. 330 At least the following three participants exist in all EAT operating 331 models. Some operating models have additional participants. 333 The Entity. This is the phone, the IoT device, the sensor, the sub- 334 assembly or such that the attestation provides information about. 336 The Manufacturer. The company that made the entity. This may be a 337 chip vendor, a circuit board module vendor or a vendor of finished 338 consumer products. 340 The Relying Party. The server, service or company that makes use of 341 the information in the EAT about the entity. 343 In all operating models, the manufacturer provisions some secret 344 attestation key material (AKM) into the entity during manufacturing. 345 This might be during the manufacturer of a chip at a fabrication 346 facility (fab) or during final assembly of a consumer product or any 347 time in between. This attestation key material is used for signing 348 EATs. 350 In all operating models, hardware and/or software on the entity 351 create an EAT of the format described in this document. The EAT is 352 always signed by the attestation key material provisioned by the 353 manufacturer. 355 In all operating models, the relying party must end up knowing that 356 the signature on the EAT is valid and consistent with data from 357 claims in the EAT. This can happen in many different ways. Here are 358 some examples. 360 o The EAT is transmitted to the relying party. The relying party 361 gets corresponding key material (e.g. a root certificate) from the 362 manufacturer. The relying party performs the verification. 364 o The EAT is transmitted to the relying party. The relying party 365 transmits the EAT to a verification service offered by the 366 manufacturer. The server returns the validated claims. 368 o The EAT is transmitted directly to a verification service, perhaps 369 operated by the manufacturer or perhaps by another party. It 370 verifies the EAT and makes the validated claims available to the 371 relying party. It may even modify the claims in some way and re- 372 sign the EAT (with a different signing key). 374 All these operating models are supported and there is no preference 375 of one over the other. It is important to support this variety of 376 operating models to generally facilitate deployment and to allow for 377 some special scenarios. One special scenario has a validation 378 service that is monetized, most likely by the manufacturer. In 379 another, a privacy proxy service processes the EAT before it is 380 transmitted to the relying party. In yet another, symmetric key 381 material is used for signing. In this case the manufacturer should 382 perform the verification, because any release of the key material 383 would enable a participant other than the entity to create valid 384 signed EATs. 386 1.6. What is Not Standardized 388 The following is not standardized for EAT, just the same they are not 389 standardized for CWT or JWT. 391 1.6.1. Transmission Protocol 393 EATs may be transmitted by any protocol the same as CWTs and JWTs. 394 For example, they might be added in extension fields of other 395 protocols, bundled into an HTTP header, or just transmitted as files. 396 This flexibility is intentional to allow broader adoption. This 397 flexibility is possible because EAT's are self-secured with signing 398 (and possibly additionally with encryption and anti-replay). The 399 transmission protocol is not required to fulfill any additional 400 security requirements. 402 For certain devices, a direct connection may not exist between the 403 EAT-producing device and the Relying Party. In such cases, the EAT 404 should be protected against malicious access. The use of COSE and 405 JOSE allows for signing and encryption of the EAT. Therefore, even 406 if the EAT is conveyed through intermediaries between the device and 407 Relying Party, such intermediaries cannot easily modify the EAT 408 payload or alter the signature. 410 1.6.2. Signing Scheme 412 The term "signing scheme" is used to refer to the system that 413 includes end-end process of establishing signing attestation key 414 material in the entity, signing the EAT, and verifying it. This 415 might involve key IDs and X.509 certificate chains or something 416 similar but different. The term "signing algorithm" refers just to 417 the algorithm ID in the COSE signing structure. No particular 418 signing algorithm or signing scheme is required by this standard. 420 There are three main implementation issues driving this. First, 421 secure non-volatile storage space in the entity for the attestation 422 key material may be highly limited, perhaps to only a few hundred 423 bits, on some small IoT chips. Second, the factory cost of 424 provisioning key material in each chip or device may be high, with 425 even millisecond delays adding to the cost of a chip. Third, 426 privacy-preserving signing schemes like ECDAA (Elliptic Curve Direct 427 Anonymous Attestation) are complex and not suitable for all use 428 cases. 430 Over time to faciliate interoperability, some signing schemes may be 431 defined in EAT profiles or other documents either in the IETF or 432 outside. 434 2. Terminology 436 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 437 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 438 "OPTIONAL" in this document are to be interpreted as described in BCP 439 14 [RFC2119] [RFC8174] when, and only when, they appear in all 440 capitals, as shown here. 442 This document reuses terminology from JWT [RFC7519], COSE [RFC8152], 443 and CWT [RFC8392]. 445 Claim Name. The human-readable name used to identify a claim. 447 Claim Key. The CBOR map key or JSON name used to identify a claim. 449 Claim Value. The value portion of the claim. A claim value can be 450 any CBOR data item or JSON value. 452 CWT Claims Set. The CBOR map or JSON object that contains the claims 453 conveyed by the CWT or JWT. 455 Attestation Key Material (AKM). The key material used to sign the 456 EAT token. If it is done symmetrically with HMAC, then this is a 457 simple symmetric key. If it is done with ECC, such as an IEEE 458 DevID [IEEE.802.1AR], then this is the private part of the EC key 459 pair. If ECDAA is used, (e.g., as used by Enhanced Privacy ID, 460 i.e. EPID) then it is the key material needed for ECDAA. 462 3. The Claims 464 This section describes new claims defined for attestation. It also 465 mentions several claims defined by CWT and JWT that are particularly 466 important for EAT. 468 Note also: * Any claim defined for CWT or JWT may be used in an EAT 469 including those in the CWT [IANA.CWT.Claims] and JWT IANA 470 [IANA.JWT.Claims] claims registries. 472 o All claims are optional 473 o No claims are mandatory 475 o All claims that are not understood by implementations MUST be 476 ignored 478 There are no default values or meanings assigned to absent claims 479 other than they are not reported. The reason for a claim's absence 480 may be the implementation not supporting the claim, an inability to 481 determine its value, or a preference to report in a different way 482 such as a proprietary claim. 484 CDDL along with text descriptions is used to define each claim 485 indepdent of encoding. Each claim is defined as a CDDL group (the 486 group is a general aggregation and type definition feature of CDDL). 487 In the encoding section Section 6, the CDDL groups turn into CBOR map 488 entries and JSON name/value pairs. 490 Map labels are assigned both an integer and string value. CBOR 491 encoded tokens MUST use only integer labels. JSON encoded tokens 492 MUST use only string labels. 494 TODO: add paragraph here about use for Attestation Evidence and for 495 Results. 497 3.1. Token ID Claim (cti and jti) 499 CWT defines the "cti" claim. JWT defines the "jti" claim. These are 500 equivalent to each other in EAT and carry a unique token identifier 501 as they do in JWT and CWT. They may be used to defend against re use 502 of the token but are distinct from the nonce that is used by the 503 relying party to guarantee freshness and defend against replay. 505 3.2. Timestamp claim (iat) 507 The "iat" claim defined in CWT and JWT is used to indicate the date- 508 of-creation of the token, the time at which the claims are collected 509 and the token is composed and signed. 511 The data for some claims may be held or cached for some period of 512 time before the token is created. This period may be long, even 513 days. Examples are measurements taken at boot or a geographic 514 position fix taken the last time a satellite signal was received. 515 There are individual timestamps associated with these claims to 516 indicate their age is older than the "iat" timestamp. 518 CWT allows the use floating-point for this claim. EAT disallows the 519 use of floating-point. No token may contain an iat claim in float- 520 point format. Any recipient of a token with a floating-point format 521 iat claim may consider it an error. A 64-bit integer representation 522 of epoch time can represent a range of +/- 500 billion years, so the 523 only point of a floating-point timestamp is to have precession 524 greater than one second. This is not needed for EAT. 526 3.3. Nonce Claim (nonce) 528 All EATs should have a nonce to prevent replay attacks. The nonce is 529 generated by the relying party, the end consumer of the token. It is 530 conveyed to the entity over whatever transport is in use before the 531 token is generated and then included in the token as the nonce claim. 533 This documents the nonce claim for registration in the IANA CWT 534 claims registry. This is equivalent to the JWT nonce claim that is 535 already registered. 537 The nonce must be at least 8 bytes (64 bits) as fewer are unlikely to 538 be secure. A maximum of 64 bytes is set to limit the memory a 539 constrained implementation uses. This size range is not set for the 540 already-registered JWT nonce, but it should follow this size 541 recommendation when used in an EAT. 543 Multiple nonces are allowed to accommodate multistage verification 544 and consumption. 546 3.3.1. nonce CDDL 548 nonce-type = bstr .size (8..64) 550 nonce-claim = ( 551 nonce => nonce-type / [ 2* nonce-type ] 552 ) 554 3.4. Universal Entity ID Claim (ueid) 556 UEID's identify individual manufactured entities / devices such as a 557 mobile phone, a water meter, a Bluetooth speaker or a networked 558 security camera. It may identify the entire device or a submodule or 559 subsystem. It does not identify types, models or classes of devices. 560 It is akin to a serial number, though it does not have to be 561 sequential. 563 UEID's must be universally and globally unique across manufacturers 564 and countries. UEIDs must also be unique across protocols and 565 systems, as tokens are intended to be embedded in many different 566 protocols and systems. No two products anywhere, even in completely 567 different industries made by two different manufacturers in two 568 different countries should have the same UEID (if they are not global 569 and universal in this way, then relying parties receiving them will 570 have to track other characteristics of the device to keep devices 571 distinct between manufacturers). 573 There are privacy considerations for UEID's. See Section 8.1. 575 The UEID is permanent. It never change for a given device / entity. 577 UEIDs are variable length. All implementations MUST be able to 578 receive UEIDs that are 33 bytes long (1 type byte and 256 bits). The 579 recommended maximum sent is also 33 bytes. 581 When the entity constructs the UEID, the first byte is a type and the 582 following bytes the ID for that type. Several types are allowed to 583 accommodate different industries and different manufacturing 584 processes and to give options to avoid paying fees for certain types 585 of manufacturer registrations. 587 Creation of new types requires a Standards Action [RFC8126]. 589 +------+------+-----------------------------------------------------+ 590 | Type | Type | Specification | 591 | Byte | Name | | 592 +------+------+-----------------------------------------------------+ 593 | 0x01 | RAND | This is a 128, 192 or 256 bit random number | 594 | | | generated once and stored in the device. This may | 595 | | | be constructed by concatenating enough identifiers | 596 | | | to make up an equivalent number of random bits and | 597 | | | then feeding the concatenation through a | 598 | | | cryptographic hash function. It may also be a | 599 | | | cryptographic quality random number generated once | 600 | | | at the beginning of the life of the device and | 601 | | | stored. It may not be smaller than 128 bits. | 602 | 0x02 | IEEE | This makes use of the IEEE company identification | 603 | | EUI | registry. An EUI is either an EUI-48, EUI-60 or | 604 | | | EUI-64 and made up of an OUI, OUI-36 or a CID, | 605 | | | different registered company identifiers, and some | 606 | | | unique per-device identifier. EUIs are often the | 607 | | | same as or similar to MAC addresses. This type | 608 | | | includes MAC-48, an obsolete name for EUI-48. (Note | 609 | | | that while devices with multiple network interfaces | 610 | | | may have multiple MAC addresses, there is only one | 611 | | | UEID for a device) [IEEE.802-2001], [OUI.Guide] | 612 | 0x03 | IMEI | This is a 14-digit identifier consisting of an | 613 | | | 8-digit Type Allocation Code and a 6-digit serial | 614 | | | number allocated by the manufacturer, which SHALL | 615 | | | be encoded as byte string of length 14 with each | 616 | | | byte as the digit's value (not the ASCII encoding | 617 | | | of the digit; the digit 3 encodes as 0x03, not | 618 | | | 0x33). The IMEI value encoded SHALL NOT include | 619 | | | Luhn checksum or SVN information. [ThreeGPP.IMEI] | 620 +------+------+-----------------------------------------------------+ 622 Table 1: UEID Composition Types 624 UEID's are not designed for direct use by humans (e.g., printing on 625 the case of a device), so no textual representation is defined. 627 The consumer (the relying party) of a UEID MUST treat a UEID as a 628 completely opaque string of bytes and not make any use of its 629 internal structure. For example, they should not use the OUI part of 630 a type 0x02 UEID to identify the manufacturer of the device. Instead 631 they should use the oemid claim that is defined elsewhere. The 632 reasons for this are: 634 o UEIDs types may vary freely from one manufacturer to the next. 636 o New types of UEIDs may be created. For example, a type 0x07 UEID 637 may be created based on some other manufacturer registration 638 scheme. 640 o Device manufacturers are allowed to change from one type of UEID 641 to another anytime they want. For example, they may find they can 642 optimize their manufacturing by switching from type 0x01 to type 643 0x02 or vice versa. The main requirement on the manufacturer is 644 that UEIDs be universally unique. 646 3.4.1. ueid CDDL 648 ueid-type = bstr .size (7..33) 650 ueid-claim = ( 651 ueid => ueid-type 652 ) 654 3.5. Semi-permanent UEIDs (SUEIDs) 656 An SEUID is of the same format as a UEID, but it may change to a 657 different value on device life-cycle events. Examples of these 658 events are change of ownership, factory reset and on-boarding into an 659 IoT device management system. A device may have both a UEID and 660 SUEIDs, neither, one or the other. 662 There may be multiple SUEIDs. Each one has a text string label the 663 purpose of which is to distinguish it from others in the token. The 664 label may name the purpose, application or type of the SUEID. 665 Typically, there will be few SUEDs so there is no need for a formal 666 labeling mechanism like a registry. The EAT profile may describe how 667 SUEIDs should be labeled. If there is only one SUEID, the claim 668 remains a map and there still must be a label. For example, the 669 label for the SUEID used by FIDO Onboarding Protocol could simply be 670 "FDO". 672 There are privacy considerations for SUEID's. See Section 8.1. 674 sueids-type = { 675 + tstr => ueid-type 676 } 678 sueids-claim = ( 679 sueids => sueids-type 680 ) 682 3.6. OEM Identification by IEEE (oemid) 684 The IEEE operates a global registry for MAC addresses and company 685 IDs. This claim uses that database to identify OEMs. The contents 686 of the claim may be either an IEEE MA-L, MA-M, MA-S or an IEEE CID 687 [IEEE.RA]. An MA-L, formerly known as an OUI, is a 24-bit value used 688 as the first half of a MAC address. MA-M similarly is a 28-bit value 689 uses as the first part of a MAC address, and MA-S, formerly known as 690 OUI-36, a 36-bit value. Many companies already have purchased one of 691 these. A CID is also a 24-bit value from the same space as an MA-L, 692 but not for use as a MAC address. IEEE has published Guidelines for 693 Use of EUI, OUI, and CID [OUI.Guide] and provides a lookup services 694 [OUI.Lookup] 696 Companies that have more than one of these IDs or MAC address blocks 697 should pick one and prefer that for all their devices. 699 Commonly, these are expressed in Hexadecimal Representation 700 [IEEE.802-2001] also called the Canonical format. When this claim is 701 encoded the order of bytes in the bstr are the same as the order in 702 the Hexadecimal Representation. For example, an MA-L like "AC-DE-48" 703 would be encoded in 3 bytes with values 0xAC, 0xDE, 0x48. For JSON 704 encoded tokens, this is further base64url encoded. 706 3.6.1. oemid CDDL 708 oemid-claim = ( 709 oemid => bstr 710 ) 712 3.7. Hardware Version Claims (hardware-version-claims) 714 The hardware version can be claimed at three different levels, the 715 chip, the circuit board and the final device assembly. An EAT can 716 include any combination these claims. 718 The hardware version is a simple text string the format of which is 719 set by each manufacturer. The structure and sorting order of this 720 text string can be specified using the version-scheme item from 721 CoSWID [CoSWID]. 723 The hardware version can also be given by a 13-digit [EAN-13]. A new 724 CoSWID version scheme is registered with IANA by this document in 725 Section 7.3.3. An EAN-13 is also known as an International Article 726 Number or most commonly as a bar code. 728 chip-version-claim = ( 729 chip-version => tstr 730 ) 732 chip-version-scheme-claim = ( 733 chip-version-scheme => $version-scheme 734 ) 736 board-version-claim = ( 737 board-version => tstr 738 ) 740 board-version-scheme-claim = ( 741 board-version-scheme => $version-scheme 742 ) 744 device-version-claim = ( 745 device-version => tstr 746 ) 748 device-version-scheme-claim = ( 749 device-version-scheme => $version-scheme 750 ) 752 hardware-version-claims = ( 753 ? chip-version-claim, 754 ? board-version-claim, 755 ? device-version-claim, 756 ? chip-version-scheme-claim, 757 ? board-version-scheme-claim, 758 ? device-version-scheme-claim, 759 ) 761 3.8. Software Description and Version 763 TODO: Add claims that reference CoSWID. 765 3.9. The Security Level Claim (security-level) 767 This claim characterizes the device/entity ability to defend against 768 attacks aimed at capturing the signing key, forging claims and at 769 forging EATs. This is done by defining four security levels as 770 described below. This is similar to the key protection types defined 771 by the Fast Identity Online (FIDO) Alliance [FIDO.Registry]. 773 These claims describe security environment and countermeasures 774 available on the end-entity / client device where the attestation key 775 reside and the claims originate. 777 1 - Unrestricted There is some expectation that implementor will 778 protect the attestation signing keys at this level. Otherwise the 779 EAT provides no meaningful security assurances. 781 2- Restricted Entities at this level should not be general-purpose 782 operating environments that host features such as app download 783 systems, web browsers and complex productivity applications. It 784 is akin to the Secure Restricted level (see below) without the 785 security orientation. Examples include a Wi-Fi subsystem, an IoT 786 camera, or sensor device. 788 3 - Secure Restricted Entities at this level must meet the criteria 789 defined by FIDO Allowed Restricted Operating Environments 790 [FIDO.AROE]. Examples include TEE's and schemes using 791 virtualization-based security. Like the FIDO security goal, 792 security at this level is aimed at defending well against large- 793 scale network / remote attacks against the device. 795 4 - Hardware Entities at this level must include substantial defense 796 against physical or electrical attacks against the device itself. 797 It is assumed any potential attacker has captured the device and 798 can disassemble it. Example include TPMs and Secure Elements. 800 The entity should claim the highest security level it achieves and no 801 higher. This set is not extensible so as to provide a common 802 interoperable description of security level to the relying party. If 803 a particular implementation considers this claim to be inadequate, it 804 can define its own proprietary claim. It may consider including both 805 this claim as a coarse indication of security and its own proprietary 806 claim as a refined indication. 808 This claim is not intended as a replacement for a proper end-device 809 security certification schemes such as those based on FIPS 140 810 [FIPS-140] or those based on Common Criteria [Common.Criteria]. The 811 claim made here is solely a self-claim made by the Entity Originator. 813 3.9.1. security-level CDDL 814 security-level-cbor-type = &( 815 unrestricted: 1, 816 restricted: 2, 817 secure-restricted: 3, 818 hardware: 4 819 ) 821 security-level-json-type = 822 "unrestricted" / 823 "restricted" / 824 "secure-restricted" / 825 "hardware" 827 security-level-claim = ( 828 security-level => security-level-cbor-type / security-level-json-type 829 ) 831 3.10. Secure Boot Claim (secure-boot) 833 The value of true indicates secure boot is enabled. Secure boot is 834 considered enabled when base software, the firmware and operating 835 system, are under control of the entity manufacturer identified in 836 the oemid claimd described in Section 3.6. This may because the 837 software is in ROM or because it is cryptographically authenticated 838 or some combination of the two or other. 840 3.10.1. secure-boot CDDL 842 secure-boot-claim = ( 843 secure-boot => bool 844 ) 846 3.11. Debug Status Claim (debug-status) 848 This applies to system-wide or submodule-wide debug facilities of the 849 target device / submodule like JTAG and diagnostic hardware built 850 into chips. It applies to any software debug facilities related to 851 root, operating system or privileged software that allow system-wide 852 memory inspection, tracing or modification of non-system software 853 like user mode applications. 855 This characterization assumes that debug facilities can be enabled 856 and disabled in a dynamic way or be disabled in some permanent way 857 such that no enabling is possible. An example of dynamic enabling is 858 one where some authentication is required to enable debugging. An 859 example of permanent disabling is blowing a hardware fuse in a chip. 860 The specific type of the mechanism is not taken into account. For 861 example, it does not matter if authentication is by a global password 862 or by per-device public keys. 864 As with all claims, the absence of the debug level claim means it is 865 not reported. A conservative interpretation might assume the Not 866 Disabled state. It could however be that it is reported in a 867 proprietary claim. 869 This claim is not extensible so as to provide a common interoperable 870 description of debug status to the relying party. If a particular 871 implementation considers this claim to be inadequate, it can define 872 its own proprietary claim. It may consider including both this claim 873 as a coarse indication of debug status and its own proprietary claim 874 as a refined indication. 876 The higher levels of debug disabling requires that all debug 877 disabling of the levels below it be in effect. Since the lowest 878 level requires that all of the target's debug be currently disabled, 879 all other levels require that too. 881 There is no inheritance of claims from a submodule to a superior 882 module or vice versa. There is no assumption, requirement or 883 guarantee that the target of a superior module encompasses the 884 targets of submodules. Thus, every submodule must explicitly 885 describe its own debug state. The verifier or relying party 886 receiving an EAT cannot assume that debug is turned off in a 887 submodule because there is a claim indicating it is turned off in a 888 superior module. 890 An individual target device / submodule may have multiple debug 891 facilities. The use of plural in the description of the states 892 refers to that, not to any aggregation or inheritance. 894 The architecture of some chips or devices may be such that a debug 895 facility operates for the whole chip or device. If the EAT for such 896 a chip includes submodules, then each submodule should independently 897 report the status of the whole-chip or whole-device debug facility. 898 This is the only way the relying party can know the debug status of 899 the submodules since there is no inheritance. 901 3.11.1. Enabled 903 If any debug facility, even manufacturer hardware diagnostics, is 904 currently enabled, then this level must be indicated. 906 3.11.2. Disabled 908 This level indicates all debug facilities are currently disabled. It 909 may be possible to enable them in the future, and it may also be 910 possible that they were enabled in the past after the target device/ 911 sub-system booted/started, but they are currently disabled. 913 3.11.3. Disabled Since Boot 915 This level indicates all debug facilities are currently disabled and 916 have been so since the target device/sub-system booted/started. 918 3.11.4. Disabled Permanently 920 This level indicates all non-manufacturer facilities are permanently 921 disabled such that no end user or developer cannot enable them. Only 922 the manufacturer indicated in the OEMID claim can enable them. This 923 also indicates that all debug facilities are currently disabled and 924 have been so since boot/start. 926 3.11.5. Disabled Fully and Permanently 928 This level indicates that all debug capabilities for the target 929 device/sub-module are permanently disabled. 931 3.11.6. debug-status CDDL 933 debug-status-cbor-type = &( 934 enabled: 0, 935 disabled: 1, 936 disabled-since-boot: 2, 937 disabled-permanently: 3, 938 disabled-fully-and-permanently: 4 939 ) 941 debug-status-json-type = 942 "enabled" / 943 "disabled" / 944 "disabled-since-boot" / 945 "disabled-permanently" / 946 "disabled-fully-and-permanently" 948 debug-status-claim = ( 949 debug-status => debug-status-cbor-type / debug-status-json-type 950 ) 952 3.12. Including Keys 954 An EAT may include a cryptographic key such as a public key. The 955 signing of the EAT binds the key to all the other claims in the 956 token. 958 The purpose for inclusion of the key may vary by use case. For 959 example, the key may be included as part of an IoT device onboarding 960 protocol. When the FIDO protocol includes a pubic key in its 961 attestation message, the key represents the binding of a user, device 962 and relying party. This document describes how claims containing 963 keys should be defined for the various use cases. It does not define 964 specific claims for specific use cases. 966 Keys in CBOR format tokens SHOULD be the COSE_Key format [RFC8152] 967 and keys in JSON format tokens SHOULD be the JSON Web Key format 968 [RFC7517]. These two formats support many common key types. Their 969 use avoids the need to decode other serialization formats. These two 970 formats can be extended to support further key types through their 971 IANA registries. 973 The general confirmation claim format [RFC8747], [RFC7800] may also 974 be used. It provides key encryption. It also allows for inclusion 975 by reference through a key ID. The confirmation claim format may 976 employed in the definition of some new claim for a a particular use 977 case. 979 When the actual confirmation claim is included in an EAT, this 980 document associates no use case semantics other than proof of 981 posession. Different EAT use cases may choose to associate further 982 semantics. The key in the confirmation claim MUST be protected the 983 same as the key used to sign the EAT. That is, the same, equivalent 984 or better hardware defenses, access controls, key generation and such 985 must be used. 987 3.13. The Location Claim (location) 989 The location claim gives the location of the device entity from which 990 the attestation originates. It is derived from the W3C Geolocation 991 API [W3C.GeoLoc]. The latitude, longitude, altitude and accuracy 992 must conform to [WGS84]. The altitude is in meters above the [WGS84] 993 ellipsoid. The two accuracy values are positive numbers in meters. 994 The heading is in degrees relative to true north. If the device is 995 stationary, the heading is NaN (floating-point not-a-number). The 996 speed is the horizontal component of the device velocity in meters 997 per second. 999 When encoding floating-point numbers half-precision should not be 1000 used. It usually does not provide enough precision for a geographic 1001 location. It is not a requirement that the receiver of an EAT 1002 implement half-precision, so the receiver may not be able to decode 1003 the location. 1005 The location may have been cached for a period of time before token 1006 creation. For example, it might have been minutes or hours or more 1007 since the last contact with a GPS satellite. Either the timestamp or 1008 age data item can be used to quantify the cached period. The 1009 timestamp data item is preferred as it a non-relative time. 1011 The age data item can be used when the entity doesn't know what time 1012 it is either because it doesn't have a clock or it isn't set. The 1013 entity must still have a "ticker" that can measure a time interval. 1014 The age is the interval between acquisition of the location data and 1015 token creation. 1017 See location-related privacy considerations in Section 8.2 below. 1019 3.13.1. location CDDL 1021 location-type = { 1022 latitude => number, 1023 longitude => number, 1024 ? altitude => number, 1025 ? accuracy => number, 1026 ? altitude-accuracy => number, 1027 ? heading => number, 1028 ? speed => number, 1029 ? timestamp => ~time-int, 1030 ? age => uint 1031 } 1033 latitude = 1 / "latitude" 1034 longitude = 2 / "longitude" 1035 altitude = 3 / "altitude" 1036 accuracy = 4 / "accuracy" 1037 altitude-accuracy = 5 / "altitude-accuracy" 1038 heading = 6 / "heading" 1039 speed = 7 / "speed" 1040 timestamp = 8 / "timestamp" 1041 age = 9 / "age" 1043 location-claim = ( 1044 location-label => location-type 1045 ) 1047 3.14. The Uptime Claim (uptime) 1049 The "uptime" claim contains a value that represents the number of 1050 seconds that have elapsed since the entity or submod was last booted. 1052 3.14.1. uptime CDDL 1054 uptime-claim = ( 1055 uptime => uint 1056 ) 1058 3.15. The Boot Seed Claim (boot-seed) 1060 The Boot Seed claim is a random value created at system boot time 1061 that will allow differentiation of reports from different boot 1062 sessions. This value is usually public and not protected. It is not 1063 the same as a seed for a random number generator which must be kept 1064 secret. 1066 boot-seed-claim = ( 1067 boot-seed => bytes 1068 ) 1070 3.16. The Intended Use Claim (intended-use) 1072 EAT's may be used in the context of several different applications. 1073 The intended-use claim provides an indication to an EAT consumer 1074 about the intended usage of the token. This claim can be used as a 1075 way for an application using EAT to internally distinguish between 1076 different ways it uses EAT. 1078 1 - Generic Generic attestation describes an application where the 1079 EAT consumer requres the most up-to-date security assessment of 1080 the attesting entity. It is expected that this is the most 1081 commonly-used application of EAT. 1083 2- Registration Entities that are registering for a new service may 1084 be expected to provide an attestation as part of the registration 1085 process. This intended-use setting indicates that the attestation 1086 is not intended for any use but registration. 1088 3 - Provisioning Entities may be provisioned with different values 1089 or settings by an EAT consumer. Examples include key material or 1090 device management trees. The consumer may require an EAT to 1091 assess device security state of the entity prior to provisioning. 1093 4 - Certificate Issuance (Certificate Signing Request) Certifying 1094 authorities (CA's) may require attestations prior to the issuance 1095 of certificates related to keypairs hosted at the entity. An EAT 1096 may be used as part of the certificate signing request (CSR). 1098 5 - Proof-of-Possession An EAT consumer may require an attestation 1099 as part of an accompanying proof-of-possession (PoP) appication. 1100 More precisely, a PoP transaction is intended to provide to the 1101 recipient cryptographically-verifiable proof that the sender has 1102 posession of a key. This kind of attestation may be neceesary to 1103 verify the security state of the entity storing the private key 1104 used in a PoP application. 1106 3.16.1. intended-use CDDL 1108 intended-use-cbor-type = &( 1109 generic: 1, 1110 registration: 2, 1111 provisioning: 3, 1112 csr: 4, 1113 pop: 5 1114 ) 1116 intended-use-json-type = 1117 "generic" / 1118 "registration" / 1119 "provisioning" / 1120 "csr" / 1121 "pop" 1123 intended-use-claim = ( 1124 intended-use => intended-use-cbor-type / intended-use-json-type 1125 ) 1127 3.17. The Profile Claim (profile) 1129 See Section 5 for the detailed description of a profile. 1131 A profile is identified by either a URL or an OID. Typically, the 1132 URI will reference a document describing the profile. An OID is just 1133 a unique identifier for the profile. It may exist anywhere in the 1134 OID tree. There is no requirement that the named document be 1135 publicly accessible. The primary purpose of the profile claim is to 1136 uniquely identify the profile even if it is a private profile. 1138 The OID is encoded in CBOR according to [CBOR-OID] and the URI 1139 according to [RFC8949]. Both are unwrapped and thus not tags. The 1140 OID is always absolute and never relative. If the claims CBOR type 1141 is a text string it is a URI and if a byte string it is an OID. 1143 Note that this named "eat_profile" for JWT and is distinct from the 1144 already registered "profile" claim in the JWT claims registry. 1146 oid = #6.4000(bstr) ; TODO: fill this in with correct CDDL from OID RFC 1148 profile-claim = ( 1149 profile => ~uri / ~oid 1150 ) 1152 3.18. The Software Manifests Claim (manifests) 1154 This claim contains descriptions of software that is present on the 1155 device. These manifests are installed on the device when the 1156 software is installed or are created as part of the installation 1157 process. Installation is anything that adds software to the device, 1158 possibly factory installation, the user installing elective 1159 applications and so on. The defining characteristic is that they are 1160 created by the software manufacturer. The purpose of these claims in 1161 an EAT is to relay them without modification to the Verifier and/or 1162 the Relying Party. 1164 In some cases these will be signed by the software manufacturer 1165 independent of any signing for the purpose of EAT attestation. 1166 Manifest claims should include the manufacturer's signature (which 1167 will be signed over by the attestation signature). In other cases 1168 the attestation signature will be the only one. 1170 This claim allows multiple formats for the manifest. For example the 1171 manifest may be a CBOR-format CoSWID, an XML-format SWID or other. 1172 Identification of the type of manifest is always by a CBOR tag. In 1173 many cases, for examples CoSWID, a tag will already be registered 1174 with IANA. If not, a tag MUST be registered. It can be in the 1175 first-come-first-served space which has minimal requirements for 1176 registration. 1178 The claim is an array of one or more manifests. To facilitate hand 1179 off of the manifest to a decoding library, each manifest is contained 1180 in a byte string. This occurs for CBOR-format manifests as well as 1181 non-CBOR format manifests. 1183 If a particular manifest type uses CBOR encoding, then the item in 1184 the array for it MUST be a byte string that contains a CBOR tag. The 1185 EAT decoder must decode the byte string and then the CBOR within it 1186 to find the tag number to identify the type of manifest. The 1187 contents of the byte string is then handed to the particular manifest 1188 processor for that type of manifest. CoSWID and SUIT manifest are 1189 examples of this. 1191 If a particular manifest type does not use CBOR encoding, then the 1192 item in the array for it must be a CBOR tag that contains a byte 1193 string. The EAT decoder uses the tag to identify the processor for 1194 that type of manifest. The contents of the tag, the byte string, are 1195 handed to the manifest processor. Note that a byte string is used to 1196 contain the manifest whether it is a text based format or not. An 1197 example of this is an XML format ISO/IEC 19770 SWID. 1199 It is not possible to describe the above requirements in CDDL so the 1200 type for an individual manifest is any in the CDDL below. The above 1201 text sets the encoding requirement. 1203 This claim allows for multiple manifests in one token since multiple 1204 software packages are likely to be present. The multiple manifests 1205 may be of multiple formats. In some cases EAT submodules may be used 1206 instead of the array structure in this claim for multiple manifests. 1208 When the [CoSWID] format is used, it MUST be a payload CoSWID, not an 1209 evidence CoSWID. 1211 manifests-claim = ( 1212 manifests => manifests-type 1213 ) 1215 manifests-type = [+ $manifest-formats] 1217 ; Must be a CoSWID payload type 1218 $manifest-formats /= bytes .cbor concise-swid-tag 1220 $manifest-formats /= bytes .cbor SUIT_Envelope_Tagged 1222 3.19. The Software Evidence Claim {swevidence} 1224 This claim contains descriptions, lists, evidence or measurements of 1225 the software that exists on the device. The defining characteristic 1226 of this claim is that its contents are created by processes on the 1227 device that inventory, measure or otherwise characterize the software 1228 on the device. The contents of this claim do not originate from the 1229 software manufacturer. 1231 In most cases the contents of this claim are signed as part of 1232 attestation signing, but independent signing in addition to the 1233 attestation signing is not ruled out when a particular evidence 1234 format supports it. 1236 This claim uses the same mechanism for identification of the type of 1237 the swevidence as is used for the type of the manifest in the 1238 manifests claim. It also uses the same byte string based mechanism 1239 for containing the claim and easing the hand off to a processing 1240 library. See the discussion above in the manifests claim. 1242 When the [CoSWID] format is used, it MUST be evidence CoSWIDs, not 1243 payload CoSWIDS. 1245 swevidence-claim = ( 1246 swevidence => swevidence-type 1247 ) 1249 swevidence-type = [+ $swevidence-formats] 1251 ; Must be a CoSWID evidence type 1252 $swevidence-formats /= bytes .cbor concise-swid-tag 1254 3.20. The Submodules Part of a Token (submods) 1256 Some devices are complex, having many subsystems or submodules. A 1257 mobile phone is a good example. It may have several connectivity 1258 submodules for communications (e.g., Wi-Fi and cellular). It may 1259 have subsystems for low-power audio and video playback. It may have 1260 one or more security-oriented subsystems like a TEE or a Secure 1261 Element. 1263 The claims for each these can be grouped together in a submodule. 1265 The submods part of a token are in a single map/object with many 1266 entries, one per submodule. There is only one submods map in a 1267 token. It is identified by its specific label. It is a peer to 1268 other claims, but it is not called a claim because it is a container 1269 for a claim set rather than an individual claim. This submods part 1270 of a token allows what might be called recursion. It allows claim 1271 sets inside of claim sets inside of claims sets... 1273 3.20.1. Two Types of Submodules 1275 Each entry in the submod map is one of two types: 1277 o A non-token submodule that is a map or object directly containing 1278 claims for the submodule. 1280 o A nested EAT that is a fully formed, independently signed EAT 1281 token 1283 3.20.1.1. Non-token Submodules 1285 This is simply a map or object containing claims about the submodule. 1287 It may contain claims that are the same as its surrounding token or 1288 superior submodules. For example, the top-level of the token may 1289 have a UEID, a submod may have a different UEID and a further 1290 subordinate submodule may also have a UEID. 1292 It is signed/encrypted along with the rest of the token and thus the 1293 claims are secured by the same Attester with the same signing key as 1294 the rest of the token. 1296 If a token is in CBOR format (a CWT or a UCCS), all non-token 1297 submodules must be CBOR format. If a token in in JSON format (a 1298 JWT), all non-token submodules must be in JSON format. 1300 When decoding, this type of submodule is recognized from the other 1301 type by being a data item of type map for CBOR or type object for 1302 JSON. 1304 3.20.1.2. Nested EATs 1306 This type of submodule is a fully formed secured EAT as defined in 1307 this document except that it MUST NOT be a UCCS or an unsecured JWT. 1308 A nested token that is one that is always secured using COSE or JOSE, 1309 usually by an independent Attester. When the surrounding EAT is a 1310 CWT or secured JWT, the nested token becomes securely bound with the 1311 other claims in the surrounding token. 1313 It is allowed to have a CWT as a submodule in a JWT and vice versa, 1314 but this SHOULD be avoided unless necessary. 1316 3.20.1.2.1. Surrounding EAT is CBOR format 1318 They type of an EAT nested in a CWT is determined by whether the CBOR 1319 type is a text string or a byte string. If a text string, then it is 1320 a JWT. If a byte string, then it is a CWT. 1322 A CWT nested in a CBOR-format token is always wrapped by a byte 1323 string for easier handling with standard CBOR decoders and token 1324 processing APIs that will typically take a byte buffer as input. 1326 Nested CWTs may be either a CWT CBOR tag or a CWT Protocol Message. 1327 COSE layers in nested CWT EATs MUST be a COSE_Tagged_Message, never a 1328 COSE_Untagged_Message. If a nested EAT has more than one level of 1329 COSE, for example one that is both encrypted and signed, a 1330 COSE_Tagged_message must be used at every level. 1332 3.20.1.2.2. Surrounding EAT is JSON format 1334 When a CWT is nested in a JWT, it must be as a 55799 tag in order to 1335 distinguish it from a nested JWT. 1337 When a nested EAT in a JWT is decoded, first remove the base64url 1338 encoding. Next, check to see if it starts with the bytes 0xd9d9f7. 1339 If so, then it is a CWT as a JWT will never start with these four 1340 bytes. If not if it is a JWT. 1342 Other than the 55799 tag requirement, tag usage for CWT's nested in a 1343 JSON format token follow the same rules as for CWTs nested in CBOR- 1344 format tokens. It may be a CWT CBOR tag or a CWT Protocol Message 1345 and COSE_Tagged_Message MUST be used at all COSE layers. 1347 3.20.1.3. Unsecured JWTs and UCCS Tokens as Submodules 1349 To incorporate a UCCS token as a submodule, it MUST be as a non-token 1350 submodule. This can be accomplished inserting the content of the 1351 UCCS Tag into the submodule map. The content of a UCCS tag is 1352 exactly a map of claims as required for a non-token submodule. If 1353 the UCCS is not a UCCS tag, then it can just be inserted into the 1354 submodule map directly. 1356 The definition of a nested EAT type of submodule is that it is one 1357 that is secured (signed) by an Attester. Since UCCS tokens are 1358 unsecured, they do not fulfill this definition and must be non-token 1359 submodules. 1361 To incorporate an Unsecured JWT as a submodule, the null-security 1362 JOSE wrapping should be removed. The resulting claims set should be 1363 inserted as a non-token submodule. 1365 To incorporate a UCCS token in a surrounding JSON token, the UCCS 1366 token claims should be translated from CBOR to JSON. To incorporate 1367 an Unsecured JWT into a surrounding CBOR-format token, the null- 1368 security JOSE should be removed and the claims translated from JSON 1369 to CBOR. 1371 3.20.2. No Inheritance 1373 The subordinate modules do not inherit anything from the containing 1374 token. The subordinate modules must explicitly include all of their 1375 claims. This is the case even for claims like the nonce and age. 1377 This rule is in place for simplicity. It avoids complex inheritance 1378 rules that might vary from one type of claim to another. 1380 3.20.3. Security Levels 1382 The security level of the non-token subordinate modules should always 1383 be less than or equal to that of the containing modules in the case 1384 of non-token submodules. It makes no sense for a module of lesser 1385 security to be signing claims of a module of higher security. An 1386 example of this is a TEE signing claims made by the non-TEE parts 1387 (e.g. the high-level OS) of the device. 1389 The opposite may be true for the nested tokens. They usually have 1390 their own more secure key material. An example of this is an 1391 embedded secure element. 1393 3.20.4. Submodule Names 1395 The label or name for each submodule in the submods map is a text 1396 string naming the submodule. No submodules may have the same name. 1398 3.20.5. submods CDDL 1399 ; The part of a token that contains all the submodules. It is a peer 1400 ; with the claims in the token, but not a claim, only a map/object to 1401 ; hold all the submodules. 1403 submods-part = ( 1404 submods => submods-type 1405 ) 1407 submods-type = { + submod-type } 1409 ; The type of a submodule which can either be a nested claim set or a 1410 ; nested separately signed token. Nested tokens are wrapped in a bstr 1411 ; or a tstr. 1413 submod-type = ( 1414 submod-name => eat-claim-set / nested-token 1415 ) 1417 ; When this is a bstr, the contents are an eat-token in CWT or UCCS 1418 ; format. When this is a tstr, the contents are an eat-token in JWT 1419 ; format. 1421 nested-token = bstr / tstr; 1423 ; Each submodule has a unique text string name. 1425 submod-name = tstr 1427 4. Endorsements and Verification Keys 1429 The Verifier must possess the correct key when it performs the 1430 cryptographic part of an EAT verification (e.g., verifying the COSE 1431 signature). This section describes several ways to identify the 1432 verification key. There is not one standard method. 1434 The verification key itself may be a public key, a symmetric key or 1435 something complicated in the case of a scheme like Direct Anonymous 1436 Attestation (DAA). 1438 RATS Architecture [RATS.Architecture] describes what is called an 1439 Endorsement. This is an input to the Verifier that is usually the 1440 basis of the trust placed in an EAT and the Attester that generated 1441 it. It may contain the public key for verification of the signature 1442 on the EAT. It may contain Reference Values to which EAT claims are 1443 compared as part of the verification process. It may contain implied 1444 claims, those that are passed on to the Relying Party in Attestation 1445 Results. 1447 There is not yet any standard format(s) for an Endorsement. One 1448 format that may be used for an Endorsement is an X.509 certificate. 1449 Endorsement data like Reference Values and implied claims can be 1450 carried in X.509 v3 extensions. In this use, the public key in the 1451 X.509 certificate becomes the verification key, so identification of 1452 the Endorsement is also identification of the verification key. 1454 The verification key identification and establishment of trust in the 1455 EAT and the attester may also be by some other means than an 1456 Endorsement. 1458 For the components (Attester, Verifier, Relying Party,...) of a 1459 particular end-end attestation system to reliably interoperate, its 1460 definition should specify how the verification key is identified. 1461 Usually, this will be in the profile document for a particular 1462 attestation system. 1464 4.1. Identification Methods 1466 Following is a list of possible methods of key identification. A 1467 specific attestation system may employ any one of these or one not 1468 listed here. 1470 The following assumes Endorsements are X.509 certificates or 1471 equivalent and thus does not mention or define any identifier for 1472 Endorsements in other formats. If such an Endorsement format is 1473 created, new identifiers for them will also need to be created. 1475 4.1.1. COSE/JWS Key ID 1477 The COSE standard header parameter for Key ID (kid) may be used. See 1478 [RFC8152] and [RFC7515] 1480 COSE leaves the semantics of the key ID open-ended. It could be a 1481 record locator in a database, a hash of a public key, an input to a 1482 KDF, an authority key identifier (AKI) for an X.509 certificate or 1483 other. The profile document should specify what the key ID's 1484 semantics are. 1486 4.1.2. JWS and COSE X.509 Header Parameters 1488 COSE X.509 [COSE.X509.Draft] and JSON Web Siganture [RFC7515] define 1489 several header parameters (x5t, x5u,...) for referencing or carrying 1490 X.509 certificates any of which may be used. 1492 The X.509 certificate may be an Endorsement and thus carrying 1493 additional input to the Verifier. It may be just an X.509 1494 certificate, not an Endorsement. The same header parameters are used 1495 in both cases. It is up to the attestation system design and the 1496 Verifier to determine which. 1498 4.1.3. CBOR Certificate COSE Header Parameters 1500 Compressed X.509 and CBOR Native certificates are defined by CBOR 1501 Certificates [CBOR.Cert.Draft]. These are semantically compatible 1502 with X.509 and therefore can be used as an equivalent to X.509 as 1503 described above. 1505 These are identified by their own header parameters (c5t, c5u,...). 1507 4.1.4. Claim-Based Key Identification 1509 For some attestation systems, a claim may be re-used as a key 1510 identifier. For example, the UEID uniquely identifies the device and 1511 therefore can work well as a key identifier or Endorsement 1512 identifier. 1514 This has the advantage that key identification requires no additional 1515 bytes in the EAT and makes the EAT smaller. 1517 This has the disadvantage that the unverified EAT must be 1518 substantially decoded to obtain the identifier since the identifier 1519 is in the COSE/JOSE payload, not in the headers. 1521 4.2. Other Considerations 1523 In all cases there must be some way that the verification key is 1524 itself verified or determined to be trustworthy. The key 1525 identification itself is never enough. This will always be by some 1526 out-of-band mechanism that is not described here. For example, the 1527 Verifier may be configured with a root certificate or a master key by 1528 the Verifier system administrator. 1530 Often an X.509 certificate or an Endorsement carries more than just 1531 the verification key. For example, an X.509 certificate might have 1532 key usage constraints and an Endorsement might have Reference Values. 1533 When this is the case, the key identifier must be either a protected 1534 header or in the payload such that it is cryptographically bound to 1535 the EAT. This is in line with the requirements in section 6 on Key 1536 Identification in JSON Web Signature [RFC7515]. 1538 5. Profiles 1540 This EAT specification does not gaurantee that implementations of it 1541 will interoperate. The variability in this specification is 1542 necessary to accommodate the widely varying use cases. An EAT 1543 profile narrows the specification for a specific use case. An ideal 1544 EAT profile will gauarantee interoperability. 1546 The profile can be named in the token using the profile claim 1547 described in Section 3.17. 1549 5.1. Format of a Profile Document 1551 A profile document doesn't have to be in any particular format. It 1552 may be simple text, something more formal or a combination. 1554 In some cases CDDL may be created that replaces CDDL in this or other 1555 document to express some profile requirements. For example, to 1556 require the altitude data item in the location claim, CDDL can be 1557 written that replicates the location claim with the altitude no 1558 longer optional. 1560 5.2. List of Profile Issues 1562 The following is a list of EAT, CWT, UCCS, JWS, COSE, JOSE and CBOR 1563 options that a profile should address. 1565 5.2.1. Use of JSON, CBOR or both 1567 The profile should indicate whether the token format should be CBOR, 1568 JSON, both or even some other encoding. If some other encoding, a 1569 specification for how the CDDL described here is serialized in that 1570 encoding is necessary. 1572 This should be addressed for the top-level token and for any nested 1573 tokens. For example, a profile might require all nested tokens to be 1574 of the same encoding of the top level token. 1576 5.2.2. CBOR Map and Array Encoding 1578 The profile should indicate whether definite-length arrays/maps, 1579 indefinite-length arrays/maps or both are allowed. A good default is 1580 to allow only definite-length arrays/maps. 1582 An alternate is to allow both definite and indefinite-length arrays/ 1583 maps. The decoder should accept either. Encoders that need to fit 1584 on very small hardware or be actually implement in hardware can use 1585 indefinite-length encoding. 1587 This applies to individual EAT claims, CWT and COSE parts of the 1588 implementation. 1590 5.2.3. CBOR String Encoding 1592 The profile should indicate whether definite-length strings, 1593 indefinite-length strings or both are allowed. A good default is to 1594 allow only definite-length strings. As with map and array encoding, 1595 allowing indefinite-length strings can be beneficial for some smaller 1596 implementations. 1598 5.2.4. CBOR Preferred Serialization 1600 The profile should indicate whether encoders must use preferred 1601 serialization. The profile should indicate whether decoders must 1602 accept non-preferred serialization. 1604 5.2.5. COSE/JOSE Protection 1606 COSE and JOSE have several options for signed, MACed and encrypted 1607 messages. EAT/CWT has the option to have no protection using UCCS 1608 and JOSE has a NULL protection option. It is possible to implement 1609 no protection, sign only, MAC only, sign then encrypt and so on. All 1610 combinations allowed by COSE, JOSE, JWT, CWT and UCCS are allowed by 1611 EAT. 1613 The profile should list the protections that must be supported by all 1614 decoders implementing the profile. The encoders them must implement 1615 a subset of what is listed for the decoders, perhaps only one. 1617 Implementations may choose to sign or MAC before encryption so that 1618 the implementation layer doing the signing or MACing can be the 1619 smallest. It is often easier to make smaller implementations more 1620 secure, perhaps even implementing in solely in hardware. The key 1621 material for a signature or MAC is a private key, while for 1622 encryption it is likely to be a public key. The key for encryption 1623 requires less protection. 1625 5.2.6. COSE/JOSE Algorithms 1627 The profile document should list the COSE algorithms that a Verifier 1628 must implement. The Attester will select one of them. Since there 1629 is no negotiation, the Verifier should implement all algorithms 1630 listed in the profile. 1632 5.2.7. Verification Key Identification 1634 Section Section 4 describes a number of methods for identifying a 1635 verification key. The profile document should specify one of these 1636 or one that is not described. The ones described in this document 1637 are only roughly described. The profile document should go into the 1638 full detail. 1640 5.2.8. Endorsement Identification 1642 Similar to, or perhaps the same as Verification Key Identification, 1643 the profile may wish to specify how Endorsements are to be 1644 identified. However note that Endorsement Identification is 1645 optional, where as key identification is not. 1647 5.2.9. Freshness 1649 Just about every use case will require some means of knowing the EAT 1650 is recent enough and not a replay of an old token. The profile 1651 should describe how freshness is achieved. The section on Freshness 1652 in [RATS-Architecture] describes some of the possible solutions to 1653 achieve this. 1655 5.2.10. Required Claims 1657 The profile can list claims whose absence results in Verification 1658 failure. 1660 5.2.11. Prohibited Claims 1662 The profile can list claims whose presence results in Verification 1663 failure. 1665 5.2.12. Additional Claims 1667 The profile may describe entirely new claims. These claims can be 1668 required or optional. 1670 5.2.13. Refined Claim Definition 1672 The profile may lock down optional aspects of individual claims. For 1673 example, it may require altitude in the location claim, or it may 1674 require that HW Versions always be described using EAN-13. 1676 5.2.14. CBOR Tags 1678 The profile should specify whether the token should be a CWT Tag or 1679 not. Similarly, the profile should specify whether the token should 1680 be a UCCS tag or not. 1682 When COSE protection is used, the profile should specify whether COSE 1683 tags are used or not. Note that RFC 8392 requires COSE tags be used 1684 in a CWT tag. 1686 Often a tag is unncessary because the surrounding or carrying 1687 protocol identifies the object as an EAT. 1689 5.2.15. Manifests and Software Evidence Claims 1691 The profile should specify which formats are allowed for the 1692 manifests and software evidence claims. The profile may also go on 1693 to say which parts and options of these formats are used, allowed and 1694 prohibited. 1696 6. Encoding 1698 This makes use of the types defined in CDDL Appendix D, Standard 1699 Prelude. 1701 Some of the CDDL included here is for claims that are defined in CWT 1702 [RFC8392] or JWT [RFC7519] or are in the IANA CWT or JWT registries. 1703 CDDL was not in use when these claims where defined. 1705 6.1. Common CDDL Types 1707 time-int is identical to the epoch-based time, but disallows 1708 floating-point representation. 1710 Note that unless expliclity indicated, URIs are not the URI tag 1711 defined in [RFC8949]. They are just text strings that contain a URI. 1713 string-or-uri = tstr 1715 time-int = #6.1(int) 1717 6.2. CDDL for CWT-defined Claims 1719 This section provides CDDL for the claims defined in CWT. It is non- 1720 normative as [RFC8392] is the authoritative definition of these 1721 claims. 1723 Note that the subject, issue and audience claims may be a text string 1724 containing a URI per [RFC8392] and [RFC7519]. These are never the 1725 URI tag defined in [RFC8949]. 1727 $$eat-extension //= ( 1728 ? issuer => text, 1729 ? subject => text, 1730 ? audience => text, 1731 ? expiration => time, 1732 ? not-before => time, 1733 ? issued-at => time, 1734 ? cwt-id => bytes, 1735 ) 1737 issuer = 1 1738 subject = 2 1739 audience = 3 1740 expiration = 4 1741 not-before = 5 1742 issued-at = 6 1743 cwt-id = 7 1745 6.3. JSON 1747 6.3.1. JSON Labels 1748 ; The following are Claim Keys (labels) assigned for JSON-encoded tokens. 1750 ueid /= "ueid" 1751 sueids /= "sueids" 1752 nonce /= "nonce" 1753 oemid /= "oemid" 1754 security-level /= "seclevel" 1755 secure-boot /= "secboot" 1756 debug-status /= "dbgstat" 1757 location /= "location" 1758 uptime /= "uptime" 1759 profile /= "eat-profile" 1760 intended-use /= "intuse" 1761 boot-seed /= "bootseed" 1762 submods /= "submods" 1763 timestamp /= "timestamp" 1764 manifests /= "manifests" 1765 swevidence /= "swevidence" 1767 latitude /= "lat" 1768 longitude /= "long" 1769 altitude /= "alt" 1770 accuracy /= "accry" 1771 altitude-accuracy /= "alt-accry" 1772 heading /= "heading" 1773 speed /= "speed" 1775 6.3.2. JSON Interoperability 1777 JSON should be encoded per RFC 8610 Appendix E. In addition, the 1778 following CDDL types are encoded in JSON as follows: 1780 o bstr - must be base64url encoded 1782 o time - must be encoded as NumericDate as described section 2 of 1783 [RFC7519]. 1785 o string-or-uri - must be encoded as StringOrURI as described 1786 section 2 of [RFC7519]. 1788 o uri - must be a URI [RFC3986]. 1790 o oid - encoded as a string using the well established dotted- 1791 decimal notation (e.g., the text "1.2.250.1"). 1793 6.4. CBOR 1795 6.4.1. CBOR Interoperability 1797 CBOR allows data items to be serialized in more than one form. If 1798 the sender uses a form that the receiver can't decode, there will not 1799 be interoperability. 1801 This specification gives no blanket requirements to narrow CBOR 1802 serialization for all uses of EAT. This allows individual uses to 1803 tailor serialization to the environment. It also may result in EAT 1804 implementations that don't interoperate. 1806 One way to guarantee interoperability is to clearly specify CBOR 1807 serialization in a profile document. See Section 5 for a list of 1808 serialization issues that should be addressed. 1810 EAT will be commonly used where the device generating the attestation 1811 is constrained and the receiver/verifier of the attestation is a 1812 capacious server. Following is a set of serialization requirements 1813 that work well for that use case and are guaranteed to interoperate. 1814 Use of this serialization is recommended where possible, but not 1815 required. An EAT profile may just reference the following section 1816 rather than spell out serialization details. 1818 6.4.1.1. EAT Constrained Device Serialization 1820 o Preferred serialization described in section 4.1 of [RFC8949] is 1821 not required. The EAT decoder must accept all forms of number 1822 serialization. The EAT encoder may use any form it wishes. 1824 o The EAT decoder must accept indefinite length arrays and maps as 1825 described in section 3.2.2 of [RFC8949]. The EAT encoder may use 1826 indefinite length arrays and maps if it wishes. 1828 o The EAT decoder must accept indefinite length strings as described 1829 in section 3.2.3 of [RFC8949]. The EAT encoder may use indefinite 1830 length strings if it wishes. 1832 o Sorting of maps by key is not required. The EAT decoder must not 1833 rely on sorting. 1835 o Deterministic encoding described in Section 4.2 of [RFC8949] is 1836 not required. 1838 o Basic validity described in section 5.3.1 of [RFC8949] must be 1839 followed. The EAT encoder must not send duplicate map keys/labels 1840 or invalid UTF-8 strings. 1842 6.5. Collected CDDL 1844 ; This is the top-level definition of the claims in EAT tokens. To 1845 ; form an actual EAT Token, this claim set is enclosed in a COSE, JOSE 1846 ; or UCCS message. 1848 eat-claim-set = { 1849 ? ueid-claim, 1850 ? sueids-claim, 1851 ? nonce-claim, 1852 ? oemid-claim, 1853 ? hardware-version-claims, 1854 ? security-level-claim, 1855 ? secure-boot-claim, 1856 ? debug-status-claim, 1857 ? location-claim, 1858 ? intended-use-claim, 1859 ? profile-claim, 1860 ? uptime-claim, 1861 ? manifests-claim, 1862 ? swevidence-claim, 1863 ? submods-part, 1864 * $$eat-extension, 1865 } 1867 ; This is the top-level definition of an EAT Token. It is a CWT, JWT 1868 ; or UCSS where the payload is an eat-claim-set. A JWT_Message is what 1869 ; is defined by JWT in RFC 7519. (RFC 7519 doesn't use CDDL so a there 1870 ; is no actual CDDL definition of JWT_Message). 1872 eat-token = EAT_Tagged_Message / EAT_Untagged_Message / JWT_Message 1874 ; This is CBOR-format EAT token in the CWT or UCCS format that is a 1875 ; tag. COSE_Tagged_message is defined in RFC 8152. Tag 601 is 1876 ; proposed by the UCCS draft, but not yet assigned. 1878 EAT_Tagged_Message = #6.61(COSE_Tagged_Message) / #6.601(eat-claim-set) 1880 ; This is a CBOR-format EAT token that is a CWT or UCSS that is not a 1881 ; tag COSE_Tagged_message and COSE_Untagged_Message are defined in RFC 1882 ; 8152. 1884 EAT_Untagged_Message = COSE_Tagged_Message / COSE_Untagged_Message / UCCS_Untagged_Message 1885 ; This is an "unwrapped" UCCS tag. Unwrapping a tag means to use the 1886 ; definition of its content without the preceding type 6 tag 1887 ; integer. Since a UCCS is nothing but a tag for an unsecured CWT 1888 ; claim set, unwrapping reduces to a bare eat-claim-set. 1890 UCCS_Untagged_Message = eat-claim-set 1892 string-or-uri = tstr 1894 time-int = #6.1(int) 1895 $$eat-extension //= ( 1896 ? issuer => text, 1897 ? subject => text, 1898 ? audience => text, 1899 ? expiration => time, 1900 ? not-before => time, 1901 ? issued-at => time, 1902 ? cwt-id => bytes, 1903 ) 1905 issuer = 1 1906 subject = 2 1907 audience = 3 1908 expiration = 4 1909 not-before = 5 1910 issued-at = 6 1911 cwt-id = 7 1913 debug-status-cbor-type = &( 1914 enabled: 0, 1915 disabled: 1, 1916 disabled-since-boot: 2, 1917 disabled-permanently: 3, 1918 disabled-fully-and-permanently: 4 1919 ) 1921 debug-status-json-type = 1922 "enabled" / 1923 "disabled" / 1924 "disabled-since-boot" / 1925 "disabled-permanently" / 1926 "disabled-fully-and-permanently" 1928 debug-status-claim = ( 1929 debug-status => debug-status-cbor-type / debug-status-json-type 1930 ) 1931 location-type = { 1932 latitude => number, 1933 longitude => number, 1934 ? altitude => number, 1935 ? accuracy => number, 1936 ? altitude-accuracy => number, 1937 ? heading => number, 1938 ? speed => number, 1939 ? timestamp => ~time-int, 1940 ? age => uint 1941 } 1943 latitude = 1 / "latitude" 1944 longitude = 2 / "longitude" 1945 altitude = 3 / "altitude" 1946 accuracy = 4 / "accuracy" 1947 altitude-accuracy = 5 / "altitude-accuracy" 1948 heading = 6 / "heading" 1949 speed = 7 / "speed" 1950 timestamp = 8 / "timestamp" 1951 age = 9 / "age" 1953 location-claim = ( 1954 location-label => location-type 1955 ) 1956 nonce-type = bstr .size (8..64) 1958 nonce-claim = ( 1959 nonce => nonce-type / [ 2* nonce-type ] 1960 ) 1961 oemid-claim = ( 1962 oemid => bstr 1963 ) 1964 chip-version-claim = ( 1965 chip-version => tstr 1966 ) 1968 chip-version-scheme-claim = ( 1969 chip-version-scheme => $version-scheme 1970 ) 1972 board-version-claim = ( 1973 board-version => tstr 1974 ) 1976 board-version-scheme-claim = ( 1977 board-version-scheme => $version-scheme 1978 ) 1980 device-version-claim = ( 1981 device-version => tstr 1982 ) 1984 device-version-scheme-claim = ( 1985 device-version-scheme => $version-scheme 1986 ) 1988 hardware-version-claims = ( 1989 ? chip-version-claim, 1990 ? board-version-claim, 1991 ? device-version-claim, 1992 ? chip-version-scheme-claim, 1993 ? board-version-scheme-claim, 1994 ? device-version-scheme-claim, 1995 ) 1997 secure-boot-claim = ( 1998 secure-boot => bool 1999 ) 2000 security-level-cbor-type = &( 2001 unrestricted: 1, 2002 restricted: 2, 2003 secure-restricted: 3, 2004 hardware: 4 2005 ) 2007 security-level-json-type = 2008 "unrestricted" / 2009 "restricted" / 2010 "secure-restricted" / 2011 "hardware" 2013 security-level-claim = ( 2014 security-level => security-level-cbor-type / security-level-json-type 2015 ) 2016 ; The part of a token that contains all the submodules. It is a peer 2017 ; with the claims in the token, but not a claim, only a map/object to 2018 ; hold all the submodules. 2020 submods-part = ( 2021 submods => submods-type 2022 ) 2024 submods-type = { + submod-type } 2026 ; The type of a submodule which can either be a nested claim set or a 2027 ; nested separately signed token. Nested tokens are wrapped in a bstr 2028 ; or a tstr. 2030 submod-type = ( 2031 submod-name => eat-claim-set / nested-token 2032 ) 2034 ; When this is a bstr, the contents are an eat-token in CWT or UCCS 2035 ; format. When this is a tstr, the contents are an eat-token in JWT 2036 ; format. 2038 nested-token = bstr / tstr; 2040 ; Each submodule has a unique text string name. 2042 submod-name = tstr 2044 ueid-type = bstr .size (7..33) 2046 ueid-claim = ( 2047 ueid => ueid-type 2048 ) 2049 sueids-type = { 2050 + tstr => ueid-type 2051 } 2053 sueids-claim = ( 2054 sueids => sueids-type 2055 ) 2056 intended-use-cbor-type = &( 2057 generic: 1, 2058 registration: 2, 2059 provisioning: 3, 2060 csr: 4, 2061 pop: 5 2062 ) 2064 intended-use-json-type = 2065 "generic" / 2066 "registration" / 2067 "provisioning" / 2068 "csr" / 2069 "pop" 2071 intended-use-claim = ( 2072 intended-use => intended-use-cbor-type / intended-use-json-type 2073 ) 2074 oid = #6.4000(bstr) ; TODO: fill this in with correct CDDL from OID RFC 2076 uptime-claim = ( 2077 uptime => uint 2078 ) 2080 manifests-claim = ( 2081 manifests => manifests-type 2082 ) 2084 manifests-type = [+ $manifest-formats] 2086 ; Must be a CoSWID payload type 2087 $manifest-formats /= bytes .cbor concise-swid-tag 2089 $manifest-formats /= bytes .cbor SUIT_Envelope_Tagged 2091 swevidence-claim = ( 2092 swevidence => swevidence-type 2093 ) 2095 swevidence-type = [+ $swevidence-formats] 2097 ; Must be a CoSWID evidence type 2098 $swevidence-formats /= bytes .cbor concise-swid-tag 2100 oid = #6.4000(bstr) ; TODO: fill this in with correct CDDL from OID RFC 2102 profile-claim = ( 2103 profile => ~uri / ~oid 2104 ) 2106 boot-seed-claim = ( 2107 boot-seed => bytes 2108 ) 2110 7. IANA Considerations 2112 7.1. Reuse of CBOR Web Token (CWT) Claims Registry 2114 Claims defined for EAT are compatible with those of CWT so the CWT 2115 Claims Registry is re used. No new IANA registry is created. All 2116 EAT claims should be registered in the CWT and JWT Claims Registries. 2118 7.2. Claim Characteristics 2120 The following is design guidance for creating new EAT claims, 2121 particularly those to be registered with IANA. 2123 Much of this guidance is generic and could also be considered when 2124 designing new CWT or JWT claims. 2126 7.2.1. Interoperability and Relying Party Orientation 2128 It is a broad goal that EATs can be processed by relying parties in a 2129 general way regardless of the type, manufacturer or technology of the 2130 device from which they originate. It is a goal that there be 2131 general-purpose verification implementations that can verify tokens 2132 for large numbers of use cases with special cases and configurations 2133 for different device types. This is a goal of interoperability of 2134 the semantics of claims themselves, not just of the signing, encoding 2135 and serialization formats. 2137 This is a lofty goal and difficult to achieve broadly requiring 2138 careful definition of claims in a technology neutral way. Sometimes 2139 it will be difficult to design a claim that can represent the 2140 semantics of data from very different device types. However, the 2141 goal remains even when difficult. 2143 7.2.2. Operating System and Technology Neutral 2145 Claims should be defined such that they are not specific to an 2146 operating system. They should be applicable to multiple large high- 2147 level operating systems from different vendors. They should also be 2148 applicable to multiple small embedded operating systems from multiple 2149 vendors and everything in between. 2151 Claims should not be defined such that they are specific to a SW 2152 environment or programming language. 2154 Claims should not be defined such that they are specific to a chip or 2155 particular hardware. For example, they should not just be the 2156 contents of some HW status register as it is unlikely that the same 2157 HW status register with the same bits exists on a chip of a different 2158 manufacturer. 2160 The boot and debug state claims in this document are an example of a 2161 claim that has been defined in this neutral way. 2163 7.2.3. Security Level Neutral 2165 Many use cases will have EATs generated by some of the most secure 2166 hardware and software that exists. Secure Elements and smart cards 2167 are examples of this. However, EAT is intended for use in low- 2168 security use cases the same as high-security use case. For example, 2169 an app on a mobile device may generate EATs on its own. 2171 Claims should be defined and registered on the basis of whether they 2172 are useful and interoperable, not based on security level. In 2173 particular, there should be no exclusion of claims because they are 2174 just used only in low-security environments. 2176 7.2.4. Reuse of Extant Data Formats 2178 Where possible, claims should use already standardized data items, 2179 identifiers and formats. This takes advantage of the expertise put 2180 into creating those formats and improves interoperability. 2182 Often extant claims will not be defined in an encoding or 2183 serialization format used by EAT. It is preferred to define a CBOR 2184 and JSON format for them so that EAT implementations do not require a 2185 plethora of encoders and decoders for serialization formats. 2187 In some cases, it may be better to use the encoding and serialization 2188 as is. For example, signed X.509 certificates and CRLs can be 2189 carried as-is in a byte string. This retains interoperability with 2190 the extensive infrastructure for creating and processing X.509 2191 certificates and CRLs. 2193 7.2.5. Proprietary Claims 2195 EAT allows the definition and use of proprietary claims. 2197 For example, a device manufacturer may generate a token with 2198 proprietary claims intended only for verification by a service 2199 offered by that device manufacturer. This is a supported use case. 2201 In many cases proprietary claims will be the easiest and most obvious 2202 way to proceed, however for better interoperability, use of general 2203 standardized claims is preferred. 2205 7.3. Claims Registered by This Document 2207 This specification adds the following values to the "JSON Web Token 2208 Claims" registry established by [RFC7519] and the "CBOR Web Token 2209 Claims Registry" established by [RFC8392]. Each entry below is an 2210 addition to both registries (except for the nonce claim which is 2211 already registered for JWT, but not registered for CWT). 2213 The "Claim Description", "Change Controller" and "Specification 2214 Documents" are common and equivalent for the JWT and CWT registries. 2215 The "Claim Key" and "Claim Value Types(s)" are for the CWT registry 2216 only. The "Claim Name" is as defined for the CWT registry, not the 2217 JWT registry. The "JWT Claim Name" is equivalent to the "Claim Name" 2218 in the JWT registry. 2220 7.3.1. Claims for Early Assignment 2222 RFC Editor: in the final publication this section should be combined 2223 with the following section as it will no longer be necessary to 2224 distinguish claims with early assignment. Also, the following 2225 paragraph should be removed. 2227 The claims in this section have been (requested for / given) early 2228 assignment according to [RFC7120]. They have been assigned values 2229 and registered before final publication of this document. While 2230 their semantics is not expected to change in final publication, it is 2231 possible that they will. The JWT Claim Names and CWT Claim Keys are 2232 not expected to change. 2234 o Claim Name: Nonce 2236 o Claim Description: Nonce 2238 o JWT Claim Name: "nonce" (already registered for JWT) 2240 o Claim Key: 10 2242 o Claim Value Type(s): byte string 2244 o Change Controller: IESG 2246 o Specification Document(s): [OpenIDConnectCore], *this document* 2248 o Claim Name: UEID 2250 o Claim Description: The Universal Entity ID 2252 o JWT Claim Name: "ueid" 2254 o CWT Claim Key: 11 2256 o Claim Value Type(s): byte string 2257 o Change Controller: IESG 2259 o Specification Document(s): *this document* 2261 o Claim Name: OEMID 2263 o Claim Description: IEEE-based OEM ID 2265 o JWT Claim Name: "oemid" 2267 o Claim Key: 13 2269 o Claim Value Type(s): byte string 2271 o Change Controller: IESG 2273 o Specification Document(s): *this document* 2275 o Claim Name: Security Level 2277 o Claim Description: Characterization of the security of an Attester 2278 or submodule 2280 o JWT Claim Name: "seclevel" 2282 o Claim Key: 14 2284 o Claim Value Type(s): integer 2286 o Change Controller: IESG 2288 o Specification Document(s): *this document* 2290 o Claim Name: Secure Boot 2292 o Claim Description: Indicate whether the boot was secure 2294 o JWT Claim Name: "secboot" 2296 o Claim Key: 15 2298 o Claim Value Type(s): Boolean 2300 o Change Controller: IESG 2302 o Specification Document(s): *this document* 2304 o Claim Name: Debug Status 2305 o Claim Description: Indicate status of debug facilities 2307 o JWT Claim Name: "dbgstat" 2309 o Claim Key: 16 2311 o Claim Value Type(s): integer 2313 o Change Controller: IESG 2315 o Specification Document(s): *this document* 2317 o Claim Name: Location 2319 o Claim Description: The geographic location 2321 o JWT Claim Name: "location" 2323 o Claim Key: 17 2325 o Claim Value Type(s): map 2327 o Change Controller: IESG 2329 o Specification Document(s): *this document* 2331 o Claim Name: Profile 2333 o Claim Description: Indicates the EAT profile followed 2335 o JWT Claim Name: "eat_profile" 2337 o Claim Key: 18 2339 o Claim Value Type(s): map 2341 o Change Controller: IESG 2343 o Specification Document(s): *this document* 2345 o Claim Name: Submodules Section 2347 o Claim Description: The section containing submodules (not actually 2348 a claim) 2350 o JWT Claim Name: "submods" 2352 o Claim Key: 20 2353 o Claim Value Type(s): map 2355 o Change Controller: IESG 2357 o Specification Document(s): *this document* 2359 7.3.2. To be Assigned Claims 2361 TODO: add the rest of the claims in here 2363 7.3.3. Version Schemes Registered by this Document 2365 IANA is requested to register a new value in the "Software Tag 2366 Version Scheme Values" established by [CoSWID]. 2368 The new value is a version scheme a 13-digit European Article Number 2369 [EAN-13]. An EAN-13 is also known as an International Article Number 2370 or most commonly as a bar code. This version scheme is the ASCII 2371 text representation of EAN-13 digits, the same ones often printed 2372 with a bar code. This version scheme must comply with the EAN 2373 allocation and assignment rules. For example, this requires the 2374 manufacturer to obtain a manufacture code from GS1. 2376 +-------+---------------------+---------------+ 2377 | Index | Version Scheme Name | Specification | 2378 +-------+---------------------+---------------+ 2379 | 5 | ean-13 | This document | 2380 +-------+---------------------+---------------+ 2382 8. Privacy Considerations 2384 Certain EAT claims can be used to track the owner of an entity and 2385 therefore, implementations should consider providing privacy- 2386 preserving options dependent on the intended usage of the EAT. 2387 Examples would include suppression of location claims for EAT's 2388 provided to unauthenticated consumers. 2390 8.1. UEID and SUEID Privacy Considerations 2392 A UEID is usually not privacy-preserving. Any set of relying parties 2393 that receives tokens that happen to be from a single device will be 2394 able to know the tokens are all from the same device and be able to 2395 track the device. Thus, in many usage situations UEID violates 2396 governmental privacy regulation. In other usage situations a UEID 2397 will not be allowed for certain products like browsers that give 2398 privacy for the end user. It will often be the case that tokens will 2399 not have a UEID for these reasons. 2401 An SUEID is also usually not privacy-preserving. In some cases it 2402 may have fewer privacy issues than a UEID depending on when and how 2403 and when it is generated. 2405 There are several strategies that can be used to still be able to put 2406 UEIDs and SUEIDs in tokens: 2408 o The device obtains explicit permission from the user of the device 2409 to use the UEID/SUEID. This may be through a prompt. It may also 2410 be through a license agreement. For example, agreements for some 2411 online banking and brokerage services might already cover use of a 2412 UEID/SUEID. 2414 o The UEID/SUEID is used only in a particular context or particular 2415 use case. It is used only by one relying party. 2417 o The device authenticates the relying party and generates a derived 2418 UEID/SUEID just for that particular relying party. For example, 2419 the relying party could prove their identity cryptographically to 2420 the device, then the device generates a UEID just for that relying 2421 party by hashing a proofed relying party ID with the main device 2422 UEID/SUEID. 2424 Note that some of these privacy preservation strategies result in 2425 multiple UEIDs and SUEIDs per device. Each UEID/SUEID is used in a 2426 different context, use case or system on the device. However, from 2427 the view of the relying party, there is just one UEID and it is still 2428 globally universal across manufacturers. 2430 8.2. Location Privacy Considerations 2432 Geographic location is most always considered personally identifiable 2433 information. Implementers should consider laws and regulations 2434 governing the transmission of location data from end user devices to 2435 servers and services. Implementers should consider using location 2436 management facilities offered by the operating system on the device 2437 generating the attestation. For example, many mobile phones prompt 2438 the user for permission when before sending location data. 2440 9. Security Considerations 2442 The security considerations provided in Section 8 of [RFC8392] and 2443 Section 11 of [RFC7519] apply to EAT in its CWT and JWT form, 2444 respectively. In addition, implementors should consider the 2445 following. 2447 9.1. Key Provisioning 2449 Private key material can be used to sign and/or encrypt the EAT, or 2450 can be used to derive the keys used for signing and/or encryption. 2451 In some instances, the manufacturer of the entity may create the key 2452 material separately and provision the key material in the entity 2453 itself. The manfuacturer of any entity that is capable of producing 2454 an EAT should take care to ensure that any private key material be 2455 suitably protected prior to provisioning the key material in the 2456 entity itself. This can require creation of key material in an 2457 enclave (see [RFC4949] for definition of "enclave"), secure 2458 transmission of the key material from the enclave to the entity using 2459 an appropriate protocol, and persistence of the private key material 2460 in some form of secure storage to which (preferably) only the entity 2461 has access. 2463 9.1.1. Transmission of Key Material 2465 Regarding transmission of key material from the enclave to the 2466 entity, the key material may pass through one or more intermediaries. 2467 Therefore some form of protection ("key wrapping") may be necessary. 2468 The transmission itself may be performed electronically, but can also 2469 be done by human courier. In the latter case, there should be 2470 minimal to no exposure of the key material to the human (e.g. 2471 encrypted portable memory). Moreover, the human should transport the 2472 key material directly from the secure enclave where it was created to 2473 a destination secure enclave where it can be provisioned. 2475 9.2. Transport Security 2477 As stated in Section 8 of [RFC8392], "The security of the CWT relies 2478 upon on the protections offered by COSE". Similar considerations 2479 apply to EAT when sent as a CWT. However, EAT introduces the concept 2480 of a nonce to protect against replay. Since an EAT may be created by 2481 an entity that may not support the same type of transport security as 2482 the consumer of the EAT, intermediaries may be required to bridge 2483 communications between the entity and consumer. As a result, it is 2484 RECOMMENDED that both the consumer create a nonce, and the entity 2485 leverage the nonce along with COSE mechanisms for encryption and/or 2486 signing to create the EAT. 2488 Similar considerations apply to the use of EAT as a JWT. Although 2489 the security of a JWT leverages the JSON Web Encryption (JWE) and 2490 JSON Web Signature (JWS) specifications, it is still recommended to 2491 make use of the EAT nonce. 2493 9.3. Multiple EAT Consumers 2495 In many cases, more than one EAT consumer may be required to fully 2496 verify the entity attestation. Examples include individual consumers 2497 for nested EATs, or consumers for individual claims with an EAT. 2498 When multiple consumers are required for verification of an EAT, it 2499 is important to minimize information exposure to each consumer. In 2500 addition, the communication between multiple consumers should be 2501 secure. 2503 For instance, consider the example of an encrypted and signed EAT 2504 with multiple claims. A consumer may receive the EAT (denoted as the 2505 "receiving consumer"), decrypt its payload, verify its signature, but 2506 then pass specific subsets of claims to other consumers for 2507 evaluation ("downstream consumers"). Since any COSE encryption will 2508 be removed by the receiving consumer, the communication of claim 2509 subsets to any downstream consumer should leverage a secure protocol 2510 (e.g.one that uses transport-layer security, i.e. TLS), 2512 However, assume the EAT of the previous example is hierarchical and 2513 each claim subset for a downstream consumer is created in the form of 2514 a nested EAT. Then transport security between the receiving and 2515 downstream consumers is not strictly required. Nevertheless, 2516 downstream consumers of a nested EAT should provide a nonce unique to 2517 the EAT they are consuming. 2519 10. References 2521 10.1. Normative References 2523 [CBOR-OID] 2524 Bormann, C., "Concise Binary Object Representation (CBOR) 2525 Tags for Object Identifiers", draft-ietf-cbor-tags-oid-06 2526 (work in progress), March 2021. 2528 [CBOR.Cert.Draft] 2529 Raza, S., "CBOR Encoding of X.509 Certificates (CBOR 2530 Certificates)", 2020, . 2533 [COSE.X509.Draft] 2534 Schaad, J., "CBOR Object Signing and Encryption (COSE): 2535 Header parameters for carrying and referencing X.509 2536 certificates", 2020, 2537 . 2539 [CoSWID] "Concise Software Identification Tags", November 2020, 2540 . 2542 [EAN-13] GS1, "International Article Number - EAN/UPC barcodes", 2543 2019, . 2545 [FIDO.AROE] 2546 The FIDO Alliance, "FIDO Authenticator Allowed Restricted 2547 Operating Environments List", November 2019, 2548 . 2551 [IANA.CWT.Claims] 2552 IANA, "CBOR Web Token (CWT) Claims", 2553 . 2555 [IANA.JWT.Claims] 2556 IANA, "JSON Web Token (JWT) Claims", 2557 . 2559 [OpenIDConnectCore] 2560 Sakimura, N., Bradley, J., Jones, M., Medeiros, B. D., and 2561 C. Mortimore, "OpenID Connect Core 1.0 incorporating 2562 errata set 1", November 2014, 2563 . 2565 [RATS-Architecture] 2566 Birkholz, H., Thaler, D., Richardson, M., Smith, N., and 2567 W. Pan, "Remote Attestation Procedures Architecture", 2568 draft-ietf-rats-architecture-12 (work in progress), April 2569 2021. 2571 [RATS.Architecture] 2572 Birkholz, H., "Remote Attestation Procedures 2573 Architecture", 2020, . 2576 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2577 Requirement Levels", BCP 14, RFC 2119, 2578 DOI 10.17487/RFC2119, March 1997, 2579 . 2581 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2582 Resource Identifier (URI): Generic Syntax", STD 66, 2583 RFC 3986, DOI 10.17487/RFC3986, January 2005, 2584 . 2586 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 2587 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 2588 2015, . 2590 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 2591 DOI 10.17487/RFC7517, May 2015, 2592 . 2594 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 2595 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 2596 . 2598 [RFC7800] Jones, M., Bradley, J., and H. Tschofenig, "Proof-of- 2599 Possession Key Semantics for JSON Web Tokens (JWTs)", 2600 RFC 7800, DOI 10.17487/RFC7800, April 2016, 2601 . 2603 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 2604 Writing an IANA Considerations Section in RFCs", BCP 26, 2605 RFC 8126, DOI 10.17487/RFC8126, June 2017, 2606 . 2608 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 2609 RFC 8152, DOI 10.17487/RFC8152, July 2017, 2610 . 2612 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2613 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2614 May 2017, . 2616 [RFC8392] Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, 2617 "CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392, 2618 May 2018, . 2620 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 2621 Definition Language (CDDL): A Notational Convention to 2622 Express Concise Binary Object Representation (CBOR) and 2623 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 2624 June 2019, . 2626 [RFC8747] Jones, M., Seitz, L., Selander, G., Erdtman, S., and H. 2627 Tschofenig, "Proof-of-Possession Key Semantics for CBOR 2628 Web Tokens (CWTs)", RFC 8747, DOI 10.17487/RFC8747, March 2629 2020, . 2631 [RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object 2632 Representation (CBOR)", STD 94, RFC 8949, 2633 DOI 10.17487/RFC8949, December 2020, 2634 . 2636 [ThreeGPP.IMEI] 2637 3GPP, "3rd Generation Partnership Project; Technical 2638 Specification Group Core Network and Terminals; Numbering, 2639 addressing and identification", 2019, 2640 . 2643 [UCCS.Draft] 2644 Birkholz, H., "A CBOR Tag for Unprotected CWT Claims 2645 Sets", 2020, 2646 . 2648 [WGS84] National Imagery and Mapping Agency, "National Imagery and 2649 Mapping Agency Technical Report 8350.2, Third Edition", 2650 2000, . 2653 10.2. Informative References 2655 [BirthdayAttack] 2656 "Birthday attack", 2657 . 2659 [Common.Criteria] 2660 "Common Criteria for Information Technology Security 2661 Evaluation", April 2017, 2662 . 2664 [ECMAScript] 2665 "Ecma International, "ECMAScript Language Specification, 2666 5.1 Edition", ECMA Standard 262", June 2011, 2667 . 2670 [FIDO.Registry] 2671 The FIDO Alliance, "FIDO Registry of Predefined Values", 2672 December 2019, . 2675 [FIPS-140] 2676 National Institue of Standards, "Security Requirements for 2677 Cryptographic Modules", May 2001, 2678 . 2681 [IEEE.802-2001] 2682 "IEEE Standard For Local And Metropolitan Area Networks 2683 Overview And Architecture", 2007, 2684 . 2687 [IEEE.802.1AR] 2688 "IEEE Standard, "IEEE 802.1AR Secure Device Identifier"", 2689 December 2009, . 2692 [IEEE.RA] "IEEE Registration Authority", 2693 . 2696 [OUI.Guide] 2697 "Guidelines for Use of Extended Unique Identifier (EUI), 2698 Organizationally Unique Identifier (OUI), and Company ID 2699 (CID)", August 2017, 2700 . 2703 [OUI.Lookup] 2704 "IEEE Registration Authority Assignments", 2705 . 2708 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 2709 Unique IDentifier (UUID) URN Namespace", RFC 4122, 2710 DOI 10.17487/RFC4122, July 2005, 2711 . 2713 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 2714 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 2715 . 2717 [RFC7120] Cotton, M., "Early IANA Allocation of Standards Track Code 2718 Points", BCP 100, RFC 7120, DOI 10.17487/RFC7120, January 2719 2014, . 2721 [W3C.GeoLoc] 2722 Worldwide Web Consortium, "Geolocation API Specification 2723 2nd Edition", January 2018, . 2726 Appendix A. Examples 2728 A.1. Very Simple EAT 2730 This is shown in CBOR diagnostic form. Only the payload signed by 2731 COSE is shown. 2733 { 2734 / issuer / 1: "joe", 2735 / nonce / 10: h'948f8860d13a463e8e', 2736 / UEID / 11: h'0198f50a4ff6c05861c8860d13a638ea', 2737 / secure-boot / 15: true, 2738 / debug-disable / 16: 3, / permanent-disable / 2739 / timestamp (iat) / 6: 1(1526542894) 2740 } 2742 A.2. Example with Submodules, Nesting and Security Levels 2744 { 2745 / nonce / 10: h'948f8860d13a463e8e', 2746 / UEID / 11: h'0198f50a4ff6c05861c8860d13a638ea', 2747 / secure-boot / 15: true, 2748 / debug-disable / 16: 3, / permanent-disable / 2749 / timestamp (iat) / 6: 1(1526542894), 2750 / security-level / 14: 3, / secure restricted OS / 2751 / submods / 20: { 2752 / first submod, an Android Application / 2753 "Android App Foo" : { 2754 / security-level / 14: 1 / unrestricted / 2755 }, 2757 / 2nd submod, A nested EAT from a secure element / 2758 "Secure Element Eat" : 2759 / an embedded EAT, bytes of which are not shown / 2760 h'420123', 2762 / 3rd submod, information about Linux Android / 2763 "Linux Android": { 2764 / security-level / 14: 1 / unrestricted / 2765 } 2766 } 2767 } 2769 Appendix B. UEID Design Rationale 2770 B.1. Collision Probability 2772 This calculation is to determine the probability of a collision of 2773 UEIDs given the total possible entity population and the number of 2774 entities in a particular entity management database. 2776 Three different sized databases are considered. The number of 2777 devices per person roughly models non-personal devices such as 2778 traffic lights, devices in stores they shop in, facilities they work 2779 in and so on, even considering individual light bulbs. A device may 2780 have individually attested subsystems, for example parts of a car or 2781 a mobile phone. It is assumed that the largest database will have at 2782 most 10% of the world's population of devices. Note that databases 2783 that handle more than a trillion records exist today. 2785 The trillion-record database size models an easy-to-imagine reality 2786 over the next decades. The quadrillion-record database is roughly at 2787 the limit of what is imaginable and should probably be accommodated. 2788 The 100 quadrillion datadbase is highly speculative perhaps involving 2789 nanorobots for every person, livestock animal and domesticated bird. 2790 It is included to round out the analysis. 2792 Note that the items counted here certainly do not have IP address and 2793 are not individually connected to the network. They may be connected 2794 to internal buses, via serial links, Bluetooth and so on. This is 2795 not the same problem as sizing IP addresses. 2797 +---------+------------+--------------+------------+----------------+ 2798 | People | Devices / | Subsystems / | Database | Database Size | 2799 | | Person | Device | Portion | | 2800 +---------+------------+--------------+------------+----------------+ 2801 | 10 | 100 | 10 | 10% | trillion | 2802 | billion | | | | (10^12) | 2803 | 10 | 100,000 | 10 | 10% | quadrillion | 2804 | billion | | | | (10^15) | 2805 | 100 | 1,000,000 | 10 | 10% | 100 | 2806 | billion | | | | quadrillion | 2807 | | | | | (10^17) | 2808 +---------+------------+--------------+------------+----------------+ 2810 This is conceptually similar to the Birthday Problem where m is the 2811 number of possible birthdays, always 365, and k is the number of 2812 people. It is also conceptually similar to the Birthday Attack where 2813 collisions of the output of hash functions are considered. 2815 The proper formula for the collision calculation is 2816 p = 1 - e^{-k^2/(2n)} 2818 p Collision Probability 2819 n Total possible population 2820 k Actual population 2822 However, for the very large values involved here, this formula 2823 requires floating point precision higher than commonly available in 2824 calculators and SW so this simple approximation is used. See 2825 [BirthdayAttack]. 2827 p = k^2 / 2n 2829 For this calculation: 2831 p Collision Probability 2832 n Total population based on number of bits in UEID 2833 k Population in a database 2835 +----------------------+--------------+--------------+--------------+ 2836 | Database Size | 128-bit UEID | 192-bit UEID | 256-bit UEID | 2837 +----------------------+--------------+--------------+--------------+ 2838 | trillion (10^12) | 2 * 10^-15 | 8 * 10^-35 | 5 * 10^-55 | 2839 | quadrillion (10^15) | 2 * 10^-09 | 8 * 10^-29 | 5 * 10^-49 | 2840 | 100 quadrillion | 2 * 10^-05 | 8 * 10^-25 | 5 * 10^-45 | 2841 | (10^17) | | | | 2842 +----------------------+--------------+--------------+--------------+ 2844 Next, to calculate the probability of a collision occurring in one 2845 year's operation of a database, it is assumed that the database size 2846 is in a steady state and that 10% of the database changes per year. 2847 For example, a trillion record database would have 100 billion states 2848 per year. Each of those states has the above calculated probability 2849 of a collision. 2851 This assumption is a worst-case since it assumes that each state of 2852 the database is completely independent from the previous state. In 2853 reality this is unlikely as state changes will be the addition or 2854 deletion of a few records. 2856 The following tables gives the time interval until there is a 2857 probability of a collision based on there being one tenth the number 2858 of states per year as the number of records in the database. 2860 t = 1 / ((k / 10) * p) 2862 t Time until a collision 2863 p Collision probability for UEID size 2864 k Database size 2866 +---------------------+---------------+--------------+--------------+ 2867 | Database Size | 128-bit UEID | 192-bit UEID | 256-bit UEID | 2868 +---------------------+---------------+--------------+--------------+ 2869 | trillion (10^12) | 60,000 years | 10^24 years | 10^44 years | 2870 | quadrillion (10^15) | 8 seconds | 10^14 years | 10^34 years | 2871 | 100 quadrillion | 8 | 10^11 years | 10^31 years | 2872 | (10^17) | microseconds | | | 2873 +---------------------+---------------+--------------+--------------+ 2875 Clearly, 128 bits is enough for the near future thus the requirement 2876 that UEIDs be a minimum of 128 bits. 2878 There is no requirement for 256 bits today as quadrillion-record 2879 databases are not expected in the near future and because this time- 2880 to-collision calculation is a very worst case. A future update of 2881 the standard may increase the requirement to 256 bits, so there is a 2882 requirement that implementations be able to receive 256-bit UEIDs. 2884 B.2. No Use of UUID 2886 A UEID is not a UUID [RFC4122] by conscious choice for the following 2887 reasons. 2889 UUIDs are limited to 128 bits which may not be enough for some future 2890 use cases. 2892 Today, cryptographic-quality random numbers are available from common 2893 CPUs and hardware. This hardware was introduced between 2010 and 2894 2015. Operating systems and cryptographic libraries give access to 2895 this hardware. Consequently, there is little need for 2896 implementations to construct such random values from multiple sources 2897 on their own. 2899 Version 4 UUIDs do allow for use of such cryptographic-quality random 2900 numbers, but do so by mapping into the overall UUID structure of time 2901 and clock values. This structure is of no value here yet adds 2902 complexity. It also slightly reduces the number of actual bits with 2903 entropy. 2905 UUIDs seem to have been designed for scenarios where the implementor 2906 does not have full control over the environment and uniqueness has to 2907 be constructed from identifiers at hand. UEID takes the view that 2908 hardware, software and/or manufacturing process directly implement 2909 UEID in a simple and direct way. It takes the view that 2910 cryptographic quality random number generators are readily available 2911 as they are implemented in commonly used CPU hardware. 2913 Appendix C. EAT Relation to IEEE.802.1AR Secure Device Identity (DevID) 2915 This section describes several distinct ways in which an IEEE IDevID 2916 [IEEE.802.1AR] relates to EAT, particularly to UEID and SUEID. 2918 [IEEE.802.1AR] orients around the definition of an implementation 2919 called a "DevID Module." It describes how IDevIDs and LDevIDs are 2920 stored, protected and accessed using a DevID Module. A particular 2921 level of defense against attack that should be achieved to be a DevID 2922 is defined. The intent is that IDevIDs and LDevIDs are used with an 2923 open set of network protocols for authentication and such. In these 2924 protocols the DevID secret is used to sign a nonce or similar to 2925 proof the association of the DevID certificates with the device. 2927 By contrast, EAT defines network protocol for proving trustworthiness 2928 to a relying party, the very thing that is not defined in 2929 [IEEE.802.1AR]. Nor does not give details on how keys, data and such 2930 are stored protected and accessed. EAT is intended to work with a 2931 variety of different on-device implementations ranging from minimal 2932 protection of assets to the highest levels of asset protection. It 2933 does not define any particular level of defense against attack, 2934 instead providing a set of security considerations. 2936 EAT and DevID can be viewed as complimentary when used together or as 2937 competing to provide a device identity service. 2939 C.1. DevID Used With EAT 2941 As just described, EAT defines a network protocol and [IEEE.802.1AR] 2942 doesn't. Vice versa, EAT doesn't define a an device implementation 2943 and DevID does. 2945 Hence, EAT can be the network protocol that a DevID is used with. 2946 The DevID secret becomes the attestation key used to sign EATs. The 2947 DevID and its certificate chain become the Endorsement sent to the 2948 Verifier. 2950 In this case the EAT and the DevID are likely to both provide a 2951 device identifier (e.g. a serial number). In the EAT it is the UEID 2952 (or SUEID). In the DevID (used as an endorsement), it is a device 2953 serial number included in the subject field of the DevID certificate. 2954 It is probably a good idea in this use for them to be the same serial 2955 number or for the UEID to be a hash of the DevID serial number. 2957 C.2. How EAT Provides an Equivalent Secure Device Identity 2959 The UEID, SUEID and other claims like OEM ID are equivalent to the 2960 secure device identity put into the subject field of a DevID 2961 certificate. These EAT claims can represent all the same fields and 2962 values that can be put in a DevID certificate subject. EAT 2963 explicitly and carefully defines a variety of useful claims. 2965 EAT secures the conveyance of these claims by having them signed on 2966 the device by the attestation key when the EAT is generated. EAT 2967 also signs the nonce that gives freshness at this time. Since these 2968 claims are signed for every EAT generated, they can include things 2969 that vary over time like GPS location. 2971 DevID secures the device identity fields by having them signed by the 2972 manufacturer of the device sign them into a certificate. That 2973 certificate is created once during the manufacturing of the device 2974 and never changes so the fields cannot change. 2976 So in one case the signing of the identity happens on the device and 2977 the other in a manufacturing facility, but in both cases the signing 2978 of the nonce that proves the binding to the actual device happens on 2979 the device. 2981 While EAT does not specify how the signing keys, signature process 2982 and storage of the identity values should be secured against attack, 2983 an EAT implementation may have equal defenses against attack. One 2984 reason EAT uses CBOR is because it is simple enough that a basic EAT 2985 implementation can be constructed entirely in hardware. This allows 2986 EAT to be implemented with the strongest defenses possible. 2988 C.3. An X.509 Format EAT 2990 It is possible to define a way to encode EAT claims in an X.509 2991 certificate. For example, the EAT claims might be mapped to X.509 v3 2992 extensions. It is even possible to stuff a whole CBOR-encoded 2993 unsigned EAT token into a X.509 certificate. 2995 If that X.509 certificate is an IDevID or LDevID, this becomes 2996 another way to use EAT and DevID together. 2998 Note that the DevID must still be used with an authentication 2999 protocol that has a nonce or equivalent. The EAT here is not being 3000 used as the protocol to interact with the rely party. 3002 C.4. Device Identifier Permanence 3004 In terms of permanence, an IDevID is similar to a UEID in that they 3005 do not change over the life of the device. They cease to exist only 3006 when the device is destroyed. 3008 An SUEID is similar to an LDevID. They change on device life-cycle 3009 events. 3011 [IEEE.802.1AR] describes much of this permanence as resistant to 3012 attacks that seek to change the ID. IDevID permanence can be 3013 described this way because [IEEE.802.1AR] is oriented around the 3014 definition of an implementation with a particular level of defense 3015 against attack. 3017 EAT is not defined around a particular implementation and must work 3018 on a range of devices that have a range of defenses against attack. 3019 EAT thus can't be defined permanence in terms of defense against 3020 attack. EAT's definition of permanence is in terms of operations and 3021 device lifecycle. 3023 Appendix D. Changes from Previous Drafts 3025 The following is a list of known changes from the previous drafts. 3026 This list is non-authoritative. It is meant to help reviewers see 3027 the significant differences. 3029 D.1. From draft-rats-eat-01 3031 o Added UEID design rationale appendix 3033 D.2. From draft-mandyam-rats-eat-00 3035 This is a fairly large change in the orientation of the document, but 3036 no new claims have been added. 3038 o Separate information and data model using CDDL. 3040 o Say an EAT is a CWT or JWT 3042 o Use a map to structure the boot_state and location claims 3044 D.3. From draft-ietf-rats-eat-01 3046 o Clarifications and corrections for OEMID claim 3048 o Minor spelling and other fixes 3049 o Add the nonce claim, clarify jti claim 3051 D.4. From draft-ietf-rats-eat-02 3053 o Roll all EUIs back into one UEID type 3055 o UEIDs can be one of three lengths, 128, 192 and 256. 3057 o Added appendix justifying UEID design and size. 3059 o Submods part now includes nested eat tokens so they can be named 3060 and there can be more tha one of them 3062 o Lots of fixes to the CDDL 3064 o Added security considerations 3066 D.5. From draft-ietf-rats-eat-03 3068 o Split boot_state into secure-boot and debug-disable claims 3070 o Debug disable is an enumerated type rather than Booleans 3072 D.6. From draft-ietf-rats-eat-04 3074 o Change IMEI-based UEIDs to be encoded as a 14-byte string 3076 o CDDL cleaned up some more 3078 o CDDL allows for JWTs and UCCSs 3080 o CWT format submodules are byte string wrapped 3082 o Allows for JWT nested in CWT and vice versa 3084 o Allows UCCS (unsigned CWTs) and JWT unsecured tokens 3086 o Clarify tag usage when nesting tokens 3088 o Add section on key inclusion 3090 o Add hardware version claims 3092 o Collected CDDL is now filled in. Other CDDL corrections. 3094 o Rename debug-disable to debug-status; clarify that it is not 3095 extensible 3097 o Security level claim is not extensible 3099 o Improve specification of location claim and added a location 3100 privacy section 3102 o Add intended use claim 3104 D.7. From draft-ietf-rats-05 3106 o CDDL format issues resolved 3108 o Corrected reference to Location Privacy section 3110 D.8. From draft-ietf-rats-06 3112 o Added boot-seed claim 3114 o Rework CBOR interoperability section 3116 o Added profiles claim and section 3118 D.9. From draft-ietf-rats-07 3120 o Filled in IANA and other sections for possible preassignment of 3121 claim keys for well understood claims 3123 D.10. From draft-ietf-rats-08 3125 o Change profile claim to be either a URL or an OID rather than a 3126 test string 3128 D.11. From draft-ietf-rats-09 3130 o Add SUEIDs 3132 o Add appendix comparing IDevID to EAT 3134 o Added section on use for Evidence and Attestation Results 3136 o Fill in the key ID and endorsements identificaiton section 3138 o Remove origination claim as it is replaced by key IDs and 3139 endorsements 3141 o Added manifests and software evidence claims 3143 o Add string labels non-claim labels for use with JSON (e.g. labels 3144 for members of location claim) 3146 o EAN-13 HW versions are no longer a separate claim. Now they are 3147 folded in as a CoSWID version scheme. 3149 Authors' Addresses 3151 Giridhar Mandyam 3152 Qualcomm Technologies Inc. 3153 5775 Morehouse Drive 3154 San Diego, California 3155 USA 3157 Phone: +1 858 651 7200 3158 EMail: mandyam@qti.qualcomm.com 3160 Laurence Lundblade 3161 Security Theory LLC 3163 EMail: lgl@island-resort.com 3165 Miguel Ballesteros 3166 Qualcomm Technologies Inc. 3167 5775 Morehouse Drive 3168 San Diego, California 3169 USA 3171 Phone: +1 858 651 4299 3172 EMail: mballest@qti.qualcomm.com 3174 Jeremy O'Donoghue 3175 Qualcomm Technologies Inc. 3176 279 Farnborough Road 3177 Farnborough GU14 7LS 3178 United Kingdom 3180 Phone: +44 1252 363189 3181 EMail: jodonogh@qti.qualcomm.com