idnits 2.17.1 draft-ietf-rats-eat-07.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (February 03, 2021) is 1177 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) -- Possible downref: Non-RFC (?) normative reference: ref. 'CoSWID' -- Possible downref: Non-RFC (?) normative reference: ref. 'EAN-13' ** Obsolete normative reference: RFC 8152 (Obsoleted by RFC 9052, RFC 9053) -- Possible downref: Non-RFC (?) normative reference: ref. 'WGS84' Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 4 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: August 7, 2021 Security Theory LLC 6 M. Ballesteros 7 J. O'Donoghue 8 Qualcomm Technologies Inc. 9 February 03, 2021 11 The Entity Attestation Token (EAT) 12 draft-ietf-rats-eat-07 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 August 7, 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 . . . . . . . . . . . . . . . . . . . . . . . . 4 64 1.1. CWT, JWT and UCCS . . . . . . . . . . . . . . . . . . . . 5 65 1.2. CDDL . . . . . . . . . . . . . . . . . . . . . . . . . . 5 66 1.3. Entity Overview . . . . . . . . . . . . . . . . . . . . . 6 67 1.4. EAT Operating Models . . . . . . . . . . . . . . . . . . 6 68 1.5. What is Not Standardized . . . . . . . . . . . . . . . . 7 69 1.5.1. Transmission Protocol . . . . . . . . . . . . . . . . 8 70 1.5.2. Signing Scheme . . . . . . . . . . . . . . . . . . . 8 71 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 8 72 3. The Claims . . . . . . . . . . . . . . . . . . . . . . . . . 9 73 3.1. Token ID Claim (cti and jti) . . . . . . . . . . . . . . 10 74 3.2. Timestamp claim (iat) . . . . . . . . . . . . . . . . . . 10 75 3.3. Nonce Claim (nonce) . . . . . . . . . . . . . . . . . . . 10 76 3.3.1. nonce CDDL . . . . . . . . . . . . . . . . . . . . . 11 77 3.4. Universal Entity ID Claim (ueid) . . . . . . . . . . . . 11 78 3.4.1. ueid CDDL . . . . . . . . . . . . . . . . . . . . . . 13 79 3.5. Origination Claim (origination) . . . . . . . . . . . . . 13 80 3.5.1. origination CDDL . . . . . . . . . . . . . . . . . . 14 81 3.6. OEM Identification by IEEE (oemid) . . . . . . . . . . . 14 82 3.6.1. oemid CDDL . . . . . . . . . . . . . . . . . . . . . 14 83 3.7. Hardware Version Claims (hardware-version-claims) . . . . 14 84 3.8. Software Description and Version . . . . . . . . . . . . 16 85 3.9. The Security Level Claim (security-level) . . . . . . . . 16 86 3.9.1. security-level CDDL . . . . . . . . . . . . . . . . . 17 87 3.10. Secure Boot Claim (secure-boot) . . . . . . . . . . . . . 17 88 3.10.1. secure-boot CDDL . . . . . . . . . . . . . . . . . . 17 89 3.11. Debug Status Claim (debug-status) . . . . . . . . . . . . 18 90 3.11.1. Enabled . . . . . . . . . . . . . . . . . . . . . . 19 91 3.11.2. Disabled . . . . . . . . . . . . . . . . . . . . . . 19 92 3.11.3. Disabled Since Boot . . . . . . . . . . . . . . . . 19 93 3.11.4. Disabled Permanently . . . . . . . . . . . . . . . . 19 94 3.11.5. Disabled Fully and Permanently . . . . . . . . . . . 19 95 3.11.6. debug-status CDDL . . . . . . . . . . . . . . . . . 19 96 3.12. Including Keys . . . . . . . . . . . . . . . . . . . . . 20 97 3.13. The Location Claim (location) . . . . . . . . . . . . . . 21 98 3.13.1. location CDDL . . . . . . . . . . . . . . . . . . . 21 99 3.14. The Uptime Claim (uptime) . . . . . . . . . . . . . . . . 22 100 3.14.1. uptime CDDL . . . . . . . . . . . . . . . . . . . . 22 101 3.14.2. The Boot Seed Claim (boot-seed) . . . . . . . . . . 22 102 3.15. The Intended Use Claim (intended-use) . . . . . . . . . . 23 103 3.15.1. intended-use CDDL . . . . . . . . . . . . . . . . . 23 104 3.16. The Profile Claim (profile) . . . . . . . . . . . . . . . 24 105 3.17. The Submodules Part of a Token (submods) . . . . . . . . 24 106 3.17.1. Two Types of Submodules . . . . . . . . . . . . . . 25 107 3.17.1.1. Non-token Submodules . . . . . . . . . . . . . . 25 108 3.17.1.2. Nested EATs . . . . . . . . . . . . . . . . . . 25 109 3.17.1.3. Unsecured JWTs and UCCS Tokens as Submodules . . 26 110 3.17.2. No Inheritance . . . . . . . . . . . . . . . . . . . 27 111 3.17.3. Security Levels . . . . . . . . . . . . . . . . . . 27 112 3.17.4. Submodule Names . . . . . . . . . . . . . . . . . . 27 113 3.17.5. submods CDDL . . . . . . . . . . . . . . . . . . . . 27 114 4. Endorsements and Verification Keys . . . . . . . . . . . . . 28 115 5. Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . 28 116 5.1. List of Profile Issues . . . . . . . . . . . . . . . . . 29 117 5.1.1. Use of JSON, CBOR or both . . . . . . . . . . . . . . 29 118 5.1.2. CBOR Map and Array Encoding . . . . . . . . . . . . . 29 119 5.1.3. CBOR String Encoding . . . . . . . . . . . . . . . . 29 120 5.1.4. COSE/JOSE Protection . . . . . . . . . . . . . . . . 29 121 5.1.5. COSE/JOSE Algorithms . . . . . . . . . . . . . . . . 30 122 5.1.6. Verification Key Identification . . . . . . . . . . . 30 123 5.1.7. Endorsement Identification . . . . . . . . . . . . . 30 124 5.1.8. Required Claims . . . . . . . . . . . . . . . . . . . 30 125 5.1.9. Prohibited Claims . . . . . . . . . . . . . . . . . . 30 126 5.1.10. Additional Claims . . . . . . . . . . . . . . . . . . 31 127 5.1.11. Refined Claim Definition . . . . . . . . . . . . . . 31 128 5.1.12. CBOR Tags . . . . . . . . . . . . . . . . . . . . . . 31 129 6. Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . 31 130 6.1. Common CDDL Types . . . . . . . . . . . . . . . . . . . . 31 131 6.2. CDDL for CWT-defined Claims . . . . . . . . . . . . . . . 31 132 6.3. JSON . . . . . . . . . . . . . . . . . . . . . . . . . . 32 133 6.3.1. JSON Labels . . . . . . . . . . . . . . . . . . . . . 32 134 6.3.2. JSON Interoperability . . . . . . . . . . . . . . . . 33 135 6.4. CBOR . . . . . . . . . . . . . . . . . . . . . . . . . . 33 136 6.4.1. CBOR Interoperability . . . . . . . . . . . . . . . . 33 137 6.4.1.1. EAT Constrained Device Serialization . . . . . . 33 138 6.5. Collected CDDL . . . . . . . . . . . . . . . . . . . . . 34 139 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 40 140 7.1. Reuse of CBOR Web Token (CWT) Claims Registry . . . . . . 40 141 7.2. Claim Characteristics . . . . . . . . . . . . . . . . . . 40 142 7.2.1. Interoperability and Relying Party Orientation . . . 40 143 7.2.2. Operating System and Technology Neutral . . . . . . . 41 144 7.2.3. Security Level Neutral . . . . . . . . . . . . . . . 41 145 7.2.4. Reuse of Extant Data Formats . . . . . . . . . . . . 41 146 7.2.5. Proprietary Claims . . . . . . . . . . . . . . . . . 42 147 7.3. Claims Registered by This Document . . . . . . . . . . . 42 148 8. Privacy Considerations . . . . . . . . . . . . . . . . . . . 42 149 8.1. UEID Privacy Considerations . . . . . . . . . . . . . . . 43 150 8.2. Location Privacy Considerations . . . . . . . . . . . . . 43 151 9. Security Considerations . . . . . . . . . . . . . . . . . . . 44 152 9.1. Key Provisioning . . . . . . . . . . . . . . . . . . . . 44 153 9.1.1. Transmission of Key Material . . . . . . . . . . . . 44 154 9.2. Transport Security . . . . . . . . . . . . . . . . . . . 44 155 9.3. Multiple EAT Consumers . . . . . . . . . . . . . . . . . 45 156 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 45 157 10.1. Normative References . . . . . . . . . . . . . . . . . . 45 158 10.2. Informative References . . . . . . . . . . . . . . . . . 47 159 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 49 160 A.1. Very Simple EAT . . . . . . . . . . . . . . . . . . . . . 49 161 A.2. Example with Submodules, Nesting and Security Levels . . 49 162 Appendix B. UEID Design Rationale . . . . . . . . . . . . . . . 50 163 B.1. Collision Probability . . . . . . . . . . . . . . . . . . 50 164 B.2. No Use of UUID . . . . . . . . . . . . . . . . . . . . . 52 165 Appendix C. Changes from Previous Drafts . . . . . . . . . . . . 53 166 C.1. From draft-rats-eat-01 . . . . . . . . . . . . . . . . . 53 167 C.2. From draft-mandyam-rats-eat-00 . . . . . . . . . . . . . 53 168 C.3. From draft-ietf-rats-eat-01 . . . . . . . . . . . . . . . 53 169 C.4. From draft-ietf-rats-eat-02 . . . . . . . . . . . . . . . 53 170 C.5. From draft-ietf-rats-eat-03 . . . . . . . . . . . . . . . 54 171 C.6. From draft-ietf-rats-eat-04 . . . . . . . . . . . . . . . 54 172 C.7. From draft-ietf-rats-05 . . . . . . . . . . . . . . . . . 54 173 C.8. From draft-ietf-rats-06 . . . . . . . . . . . . . . . . . 55 174 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 55 176 1. Introduction 178 Remote device attestation is a fundamental service that allows a 179 remote device such as a mobile phone, an Internet-of-Things (IoT) 180 device, or other endpoint to prove itself to a relying party, a 181 server or a service. This allows the relying party to know some 182 characteristics about the device and decide whether it trusts the 183 device. 185 Remote attestation is a fundamental service that can underlie other 186 protocols and services that need to know about the trustworthiness of 187 the device before proceeding. One good example is biometric 188 authentication where the biometric matching is done on the device. 189 The relying party needs to know that the device is one that is known 190 to do biometric matching correctly. Another example is content 191 protection where the relying party wants to know the device will 192 protect the data. This generalizes on to corporate enterprises that 193 might want to know that a device is trustworthy before allowing 194 corporate data to be accessed by it. 196 The notion of attestation here is large and may include, but is not 197 limited to the following: 199 o Proof of the make and model of the device hardware (HW) 201 o Proof of the make and model of the device processor, particularly 202 for security-oriented chips 204 o Measurement of the software (SW) running on the device 206 o Configuration and state of the device 208 o Environmental characteristics of the device such as its GPS 209 location 211 TODO: mention use for Attestation Evidence and Results. 213 1.1. CWT, JWT and UCCS 215 For flexibility and ease of imlpementation in a wide variety of 216 environments, EATs can be either CBOR [RFC8949] or JSON [ECMAScript] 217 format. This specification simultaneously describes both formats. 219 An EAT is either a CWT as defined in [RFC8392], a UCCS as defined in 220 [UCCS.Draft], or a JWT as defined in [RFC7519]. This specification 221 extends those specifications with additional claims for attestation. 223 The identification of a protocol element as an EAT, whether CBOR or 224 JSON format, follows the general conventions used by CWT, JWT and 225 UCCS. Largely this depends on the protocol carrying the EAT. In 226 some cases it may be by content type (e.g., MIME type). In other 227 cases it may be through use of CBOR tags. There is no fixed 228 mechanism across all use cases. 230 1.2. CDDL 232 This specification uses CDDL, [RFC8610], as the primary formalism to 233 define each claim. The implementor then interprets the CDDL to come 234 to either the CBOR [RFC8949] or JSON [ECMAScript] representation. In 235 the case of JSON, Appendix E of [RFC8610] is followed. Additional 236 rules are given in Section 6.3.2 of this document where Appendix E is 237 insufficient. (Note that this is not to define a general means to 238 translate between CBOR and JSON, but only to define enough such that 239 the claims defined in this document can be rendered unambiguously in 240 JSON). 242 The CWT specification was authored before CDDL was available and did 243 not use it. This specification includes a CDDL definition of most of 244 what is described in [RFC8392]. 246 1.3. Entity Overview 248 An "entity" can be any device or device subassembly ("submodule") 249 that can generate its own attestation in the form of an EAT. The 250 attestation should be cryptographically verifiable by the EAT 251 consumer. An EAT at the device-level can be composed of several 252 submodule EAT's. It is assumed that any entity that can create an 253 EAT does so by means of a dedicated root-of-trust (RoT). 255 Modern devices such as a mobile phone have many different execution 256 environments operating with different security levels. For example, 257 it is common for a mobile phone to have an "apps" environment that 258 runs an operating system (OS) that hosts a plethora of downloadable 259 apps. It may also have a TEE (Trusted Execution Environment) that is 260 distinct, isolated, and hosts security-oriented functionality like 261 biometric authentication. Additionally, it may have an eSE (embedded 262 Secure Element) - a high security chip with defenses against HW 263 attacks that can serve as a RoT. This device attestation format 264 allows the attested data to be tagged at a security level from which 265 it originates. In general, any discrete execution environment that 266 has an identifiable security level can be considered an entity. 268 1.4. EAT Operating Models 270 TODO: Rewrite (or eliminate) this section in light of the RATS 271 architecture draft. 273 At least the following three participants exist in all EAT operating 274 models. Some operating models have additional participants. 276 The Entity. This is the phone, the IoT device, the sensor, the sub- 277 assembly or such that the attestation provides information about. 279 The Manufacturer. The company that made the entity. This may be a 280 chip vendor, a circuit board module vendor or a vendor of finished 281 consumer products. 283 The Relying Party. The server, service or company that makes use of 284 the information in the EAT about the entity. 286 In all operating models, the manufacturer provisions some secret 287 attestation key material (AKM) into the entity during manufacturing. 288 This might be during the manufacturer of a chip at a fabrication 289 facility (fab) or during final assembly of a consumer product or any 290 time in between. This attestation key material is used for signing 291 EATs. 293 In all operating models, hardware and/or software on the entity 294 create an EAT of the format described in this document. The EAT is 295 always signed by the attestation key material provisioned by the 296 manufacturer. 298 In all operating models, the relying party must end up knowing that 299 the signature on the EAT is valid and consistent with data from 300 claims in the EAT. This can happen in many different ways. Here are 301 some examples. 303 o The EAT is transmitted to the relying party. The relying party 304 gets corresponding key material (e.g. a root certificate) from the 305 manufacturer. The relying party performs the verification. 307 o The EAT is transmitted to the relying party. The relying party 308 transmits the EAT to a verification service offered by the 309 manufacturer. The server returns the validated claims. 311 o The EAT is transmitted directly to a verification service, perhaps 312 operated by the manufacturer or perhaps by another party. It 313 verifies the EAT and makes the validated claims available to the 314 relying party. It may even modify the claims in some way and re- 315 sign the EAT (with a different signing key). 317 All these operating models are supported and there is no preference 318 of one over the other. It is important to support this variety of 319 operating models to generally facilitate deployment and to allow for 320 some special scenarios. One special scenario has a validation 321 service that is monetized, most likely by the manufacturer. In 322 another, a privacy proxy service processes the EAT before it is 323 transmitted to the relying party. In yet another, symmetric key 324 material is used for signing. In this case the manufacturer should 325 perform the verification, because any release of the key material 326 would enable a participant other than the entity to create valid 327 signed EATs. 329 1.5. What is Not Standardized 331 The following is not standardized for EAT, just the same they are not 332 standardized for CWT or JWT. 334 1.5.1. Transmission Protocol 336 EATs may be transmitted by any protocol the same as CWTs and JWTs. 337 For example, they might be added in extension fields of other 338 protocols, bundled into an HTTP header, or just transmitted as files. 339 This flexibility is intentional to allow broader adoption. This 340 flexibility is possible because EAT's are self-secured with signing 341 (and possibly additionally with encryption and anti-replay). The 342 transmission protocol is not required to fulfill any additional 343 security requirements. 345 For certain devices, a direct connection may not exist between the 346 EAT-producing device and the Relying Party. In such cases, the EAT 347 should be protected against malicious access. The use of COSE and 348 JOSE allows for signing and encryption of the EAT. Therefore, even 349 if the EAT is conveyed through intermediaries between the device and 350 Relying Party, such intermediaries cannot easily modify the EAT 351 payload or alter the signature. 353 1.5.2. Signing Scheme 355 The term "signing scheme" is used to refer to the system that 356 includes end-end process of establishing signing attestation key 357 material in the entity, signing the EAT, and verifying it. This 358 might involve key IDs and X.509 certificate chains or something 359 similar but different. The term "signing algorithm" refers just to 360 the algorithm ID in the COSE signing structure. No particular 361 signing algorithm or signing scheme is required by this standard. 363 There are three main implementation issues driving this. First, 364 secure non-volatile storage space in the entity for the attestation 365 key material may be highly limited, perhaps to only a few hundred 366 bits, on some small IoT chips. Second, the factory cost of 367 provisioning key material in each chip or device may be high, with 368 even millisecond delays adding to the cost of a chip. Third, 369 privacy-preserving signing schemes like ECDAA (Elliptic Curve Direct 370 Anonymous Attestation) are complex and not suitable for all use 371 cases. 373 Over time to faciliate interoperability, some signing schemes may be 374 defined in EAT profiles or other documents either in the IETF or 375 outside. 377 2. Terminology 379 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 380 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 381 "OPTIONAL" in this document are to be interpreted as described in BCP 382 14 [RFC2119] [RFC8174] when, and only when, they appear in all 383 capitals, as shown here. 385 This document reuses terminology from JWT [RFC7519], COSE [RFC8152], 386 and CWT [RFC8392]. 388 Claim Name. The human-readable name used to identify a claim. 390 Claim Key. The CBOR map key or JSON name used to identify a claim. 392 Claim Value. The value portion of the claim. A claim value can be 393 any CBOR data item or JSON value. 395 CWT Claims Set. The CBOR map or JSON object that contains the claims 396 conveyed by the CWT or JWT. 398 Attestation Key Material (AKM). The key material used to sign the 399 EAT token. If it is done symmetrically with HMAC, then this is a 400 simple symmetric key. If it is done with ECC, such as an IEEE 401 DevID [IDevID], then this is the private part of the EC key pair. 402 If ECDAA is used, (e.g., as used by Enhanced Privacy ID, i.e. 403 EPID) then it is the key material needed for ECDAA. 405 3. The Claims 407 This section describes new claims defined for attestation. It also 408 mentions several claims defined by CWT and JWT that are particularly 409 important for EAT. 411 Note also: * Any claim defined for CWT or JWT may be used in an EAT 412 including those in the CWT [IANA.CWT.Claims] and JWT IANA 413 [IANA.JWT.Claims] claims registries. 415 o All claims are optional 417 o No claims are mandatory 419 o All claims that are not understood by implementations MUST be 420 ignored 422 There are no default values or meanings assigned to absent claims 423 other than they are not reported. The reason for a claim's absence 424 may be the implementation not supporting the claim, an inability to 425 determine its value, or a preference to report in a different way 426 such as a proprietary claim. 428 CDDL along with text descriptions is used to define each claim 429 indepdent of encoding. Each claim is defined as a CDDL group (the 430 group is a general aggregation and type definition feature of CDDL). 431 In the encoding section Section 6, the CDDL groups turn into CBOR map 432 entries and JSON name/value pairs. 434 TODO: add paragraph here about use for Attestation Evidence and for 435 Results. 437 3.1. Token ID Claim (cti and jti) 439 CWT defines the "cti" claim. JWT defines the "jti" claim. These are 440 equivalent to each other in EAT and carry a unique token identifier 441 as they do in JWT and CWT. They may be used to defend against re use 442 of the token but are distinct from the nonce that is used by the 443 relying party to guarantee freshness and defend against replay. 445 3.2. Timestamp claim (iat) 447 The "iat" claim defined in CWT and JWT is used to indicate the date- 448 of-creation of the token, the time at which the claims are collected 449 and the token is composed and signed. 451 The data for some claims may be held or cached for some period of 452 time before the token is created. This period may be long, even 453 days. Examples are measurements taken at boot or a geographic 454 position fix taken the last time a satellite signal was received. 455 There are individual timestamps associated with these claims to 456 indicate their age is older than the "iat" timestamp. 458 CWT allows the use floating-point for this claim. EAT disallows the 459 use of floating-point. No token may contain an iat claim in float- 460 point format. Any recipient of a token with a floating-point format 461 iat claim may consider it an error. A 64-bit integer representation 462 of epoch time can represent a range of +/- 500 billion years, so the 463 only point of a floating-point timestamp is to have precession 464 greater than one second. This is not needed for EAT. 466 3.3. Nonce Claim (nonce) 468 All EATs should have a nonce to prevent replay attacks. The nonce is 469 generated by the relying party, the end consumer of the token. It is 470 conveyed to the entity over whatever transport is in use before the 471 token is generated and then included in the token as the nonce claim. 473 This documents the nonce claim for registration in the IANA CWT 474 claims registry. This is equivalent to the JWT nonce claim that is 475 already registered. 477 The nonce must be at least 8 bytes (64 bits) as fewer are unlikely to 478 be secure. A maximum of 64 bytes is set to limit the memory a 479 constrained implementation uses. This size range is not set for the 480 already-registered JWT nonce, but it should follow this size 481 recommendation when used in an EAT. 483 Multiple nonces are allowed to accommodate multistage verification 484 and consumption. 486 3.3.1. nonce CDDL 488 nonce-type = bstr .size (8..64) 490 nonce-claim = ( 491 nonce => nonce-type / [ 2* nonce-type ] 492 ) 494 3.4. Universal Entity ID Claim (ueid) 496 UEID's identify individual manufactured entities / devices such as a 497 mobile phone, a water meter, a Bluetooth speaker or a networked 498 security camera. It may identify the entire device or a submodule or 499 subsystem. It does not identify types, models or classes of devices. 500 It is akin to a serial number, though it does not have to be 501 sequential. 503 UEID's must be universally and globally unique across manufacturers 504 and countries. UEIDs must also be unique across protocols and 505 systems, as tokens are intended to be embedded in many different 506 protocols and systems. No two products anywhere, even in completely 507 different industries made by two different manufacturers in two 508 different countries should have the same UEID (if they are not global 509 and universal in this way, then relying parties receiving them will 510 have to track other characteristics of the device to keep devices 511 distinct between manufacturers). 513 There are privacy considerations for UEID's. See Section 8.1. 515 The UEID should be permanent. It should never change for a given 516 device / entity. In addition, it should not be reprogrammable. 517 UEID's are variable length. All implementations MUST be able to 518 receive UEID's that are 33 bytes long (1 type byte and 256 bits). 519 The recommended maximum sent is also 33 bytes. 521 When the entity constructs the UEID, the first byte is a type and the 522 following bytes the ID for that type. Several types are allowed to 523 accommodate different industries and different manufacturing 524 processes and to give options to avoid paying fees for certain types 525 of manufacturer registrations. 527 Creation of new types requires a Standards Action [RFC8126]. 529 +------+------+-----------------------------------------------------+ 530 | Type | Type | Specification | 531 | Byte | Name | | 532 +------+------+-----------------------------------------------------+ 533 | 0x01 | RAND | This is a 128, 192 or 256 bit random number | 534 | | | generated once and stored in the device. This may | 535 | | | be constructed by concatenating enough identifiers | 536 | | | to make up an equivalent number of random bits and | 537 | | | then feeding the concatenation through a | 538 | | | cryptographic hash function. It may also be a | 539 | | | cryptographic quality random number generated once | 540 | | | at the beginning of the life of the device and | 541 | | | stored. It may not be smaller than 128 bits. | 542 | 0x02 | IEEE | This makes use of the IEEE company identification | 543 | | EUI | registry. An EUI is either an EUI-48, EUI-60 or | 544 | | | EUI-64 and made up of an OUI, OUI-36 or a CID, | 545 | | | different registered company identifiers, and some | 546 | | | unique per-device identifier. EUIs are often the | 547 | | | same as or similar to MAC addresses. This type | 548 | | | includes MAC-48, an obsolete name for EUI-48. (Note | 549 | | | that while devices with multiple network interfaces | 550 | | | may have multiple MAC addresses, there is only one | 551 | | | UEID for a device) [IEEE.802-2001], [OUI.Guide] | 552 | 0x03 | IMEI | This is a 14-digit identifier consisting of an | 553 | | | 8-digit Type Allocation Code and a 6-digit serial | 554 | | | number allocated by the manufacturer, which SHALL | 555 | | | be encoded as byte string of length 14 with each | 556 | | | byte as the digit's value (not the ASCII encoding | 557 | | | of the digit; the digit 3 encodes as 0x03, not | 558 | | | 0x33). The IMEI value encoded SHALL NOT include | 559 | | | Luhn checksum or SVN information. [ThreeGPP.IMEI] | 560 +------+------+-----------------------------------------------------+ 562 Table 1: UEID Composition Types 564 UEID's are not designed for direct use by humans (e.g., printing on 565 the case of a device), so no textual representation is defined. 567 The consumer (the relying party) of a UEID MUST treat a UEID as a 568 completely opaque string of bytes and not make any use of its 569 internal structure. For example, they should not use the OUI part of 570 a type 0x02 UEID to identify the manufacturer of the device. Instead 571 they should use the oemid claim that is defined elsewhere. The 572 reasons for this are: 574 o UEIDs types may vary freely from one manufacturer to the next. 576 o New types of UEIDs may be created. For example, a type 0x07 UEID 577 may be created based on some other manufacturer registration 578 scheme. 580 o Device manufacturers are allowed to change from one type of UEID 581 to another anytime they want. For example, they may find they can 582 optimize their manufacturing by switching from type 0x01 to type 583 0x02 or vice versa. The main requirement on the manufacturer is 584 that UEIDs be universally unique. 586 3.4.1. ueid CDDL 588 ueid-type = bstr .size (7..33) 590 ueid-claim = ( 591 ueid => ueid-type 592 ) 594 3.5. Origination Claim (origination) 596 TODO: this claim is likely to be dropped in favor of Endorsement 597 identifier and locators. 599 This claim describes the parts of the device or entity that are 600 creating the EAT. Often it will be tied back to the device or chip 601 manufacturer. The following table gives some examples: 603 +-------------------+-----------------------------------------------+ 604 | Name | Description | 605 +-------------------+-----------------------------------------------+ 606 | Acme-TEE | The EATs are generated in the TEE authored | 607 | | and configured by "Acme" | 608 | Acme-TPM | The EATs are generated in a TPM manufactured | 609 | | by "Acme" | 610 | Acme-Linux-Kernel | The EATs are generated in a Linux kernel | 611 | | configured and shipped by "Acme" | 612 | Acme-TA | The EATs are generated in a Trusted | 613 | | Application (TA) authored by "Acme" | 614 +-------------------+-----------------------------------------------+ 616 TODO: consider a more structure approach where the name and the URI 617 and other are in separate fields. 619 TODO: This needs refinement. It is somewhat parallel to issuer claim 620 in CWT in that it describes the authority that created the token. 622 3.5.1. origination CDDL 624 origination-claim = ( 625 origination => string-or-uri 626 ) 628 3.6. OEM Identification by IEEE (oemid) 630 The IEEE operates a global registry for MAC addresses and company 631 IDs. This claim uses that database to identify OEMs. The contents 632 of the claim may be either an IEEE MA-L, MA-M, MA-S or an IEEE CID 633 [IEEE.RA]. An MA-L, formerly known as an OUI, is a 24-bit value used 634 as the first half of a MAC address. MA-M similarly is a 28-bit value 635 uses as the first part of a MAC address, and MA-S, formerly known as 636 OUI-36, a 36-bit value. Many companies already have purchased one of 637 these. A CID is also a 24-bit value from the same space as an MA-L, 638 but not for use as a MAC address. IEEE has published Guidelines for 639 Use of EUI, OUI, and CID [OUI.Guide] and provides a lookup services 640 [OUI.Lookup] 642 Companies that have more than one of these IDs or MAC address blocks 643 should pick one and prefer that for all their devices. 645 Commonly, these are expressed in Hexadecimal Representation 646 [IEEE.802-2001] also called the Canonical format. When this claim is 647 encoded the order of bytes in the bstr are the same as the order in 648 the Hexadecimal Representation. For example, an MA-L like "AC-DE-48" 649 would be encoded in 3 bytes with values 0xAC, 0xDE, 0x48. For JSON 650 encoded tokens, this is further base64url encoded. 652 3.6.1. oemid CDDL 654 oemid-claim = ( 655 oemid => bstr 656 ) 658 3.7. Hardware Version Claims (hardware-version-claims) 660 The hardware version can be claimed at three different levels, the 661 chip, the circuit board and the final device assembly. An EAT can 662 include any combination these claims. 664 The hardware version is a simple text string the format of which is 665 set by each manufacturer. The structure and sorting order of this 666 text string can be specified using the version-scheme item from 667 CoSWID [CoSWID]. 669 The hardware version can also be given by a 13-digit European Article 670 Number [EAN-13]. An EAN-13 is also known as an International Article 671 Number or most commonly as a bar code. This claim is the ASCII text 672 representation of actual digits often printed with a bar code. Use 673 of this claim must comply with the EAN allocation and assignment 674 rules. For example, this requires the manufacturer to obtain a 675 manufacture code from GS1. 677 Both the simple version string and EAN-13 versions may be included 678 for the same hardware. 680 chip-version-claim = ( 681 chip-version => tstr 682 ) 684 chip-version-scheme-claim = ( 685 chip-version-scheme => $version-scheme 686 ) 688 board-version-claim = ( 689 board-version => tstr 690 ) 692 board-version-scheme-claim = ( 693 board-version-scheme => $version-scheme 694 ) 696 device-version-claim = ( 697 device-version => tstr 698 ) 700 device-version-scheme-claim = ( 701 device-version-scheme => $version-scheme 702 ) 704 ean-type = text .regexp "[0-9]{13}" 706 ean-chip-version-claim = ( 707 ean-chip-version => ean-type 708 ) 710 ean-board-version-claim = ( 711 ean-board-version => ean-type 712 ) 713 ean-device-version-claim = ( 714 ean-device-version => ean-type 715 ) 717 hardware-version-claims = ( 718 ? chip-version-claim, 719 ? board-version-claim, 720 ? device-version-claim, 721 ? chip-version-scheme-claim, 722 ? board-version-scheme-claim, 723 ? device-version-scheme-claim, 724 ? ean-chip-version-claim, 725 ? ean-board-version-claim, 726 ? ean-device-version-claim, 727 ) 729 3.8. Software Description and Version 731 TODO: Add claims that reference CoSWID. 733 3.9. The Security Level Claim (security-level) 735 This claim characterizes the device/entity ability to defend against 736 attacks aimed at capturing the signing key, forging claims and at 737 forging EATs. This is done by defining four security levels as 738 described below. This is similar to the key protection types defined 739 by the Fast Identity Online (FIDO) Alliance [FIDO.Registry]. 741 These claims describe security environment and countermeasures 742 available on the end-entity / client device where the attestation key 743 reside and the claims originate. 745 1 - Unrestricted There is some expectation that implementor will 746 protect the attestation signing keys at this level. Otherwise the 747 EAT provides no meaningful security assurances. 749 2- Restricted Entities at this level should not be general-purpose 750 operating environments that host features such as app download 751 systems, web browsers and complex productivity applications. It 752 is akin to the Secure Restricted level (see below) without the 753 security orientation. Examples include a Wi-Fi subsystem, an IoT 754 camera, or sensor device. 756 3 - Secure Restricted Entities at this level must meet the criteria 757 defined by FIDO Allowed Restricted Operating Environments 758 [FIDO.AROE]. Examples include TEE's and schemes using 759 virtualization-based security. Like the FIDO security goal, 760 security at this level is aimed at defending well against large- 761 scale network / remote attacks against the device. 763 4 - Hardware Entities at this level must include substantial defense 764 against physical or electrical attacks against the device itself. 765 It is assumed any potential attacker has captured the device and 766 can disassemble it. Example include TPMs and Secure Elements. 768 The entity should claim the highest security level it achieves and no 769 higher. This set is not extensible so as to provide a common 770 interoperable description of security level to the relying party. If 771 a particular implementation considers this claim to be inadequate, it 772 can define its own proprietary claim. It may consider including both 773 this claim as a coarse indication of security and its own proprietary 774 claim as a refined indication. 776 This claim is not intended as a replacement for a proper end-device 777 security certification schemes such as those based on FIPS 140 778 [FIPS-140] or those based on Common Criteria [Common.Criteria]. The 779 claim made here is solely a self-claim made by the Entity Originator. 781 3.9.1. security-level CDDL 783 security-level-type = &( 784 unrestricted: 1, 785 restricted: 2, 786 secure-restricted: 3, 787 hardware: 4 788 ) 790 security-level-claim = ( 791 security-level => security-level-type 792 ) 794 3.10. Secure Boot Claim (secure-boot) 796 The value of true indicates secure boot is enabled. Secure boot is 797 considered enabled when base software, the firmware and operating 798 system, are under control of the entity manufacturer identified in 799 the oemid claimd described in Section 3.6. This may because the 800 software is in ROM or because it is cryptographically authenticated 801 or some combination of the two or other. 803 3.10.1. secure-boot CDDL 805 secure-boot-claim = ( 806 secure-boot => bool 807 ) 809 3.11. Debug Status Claim (debug-status) 811 This applies to system-wide or submodule-wide debug facilities of the 812 target device / submodule like JTAG and diagnostic hardware built 813 into chips. It applies to any software debug facilities related to 814 root, operating system or privileged software that allow system-wide 815 memory inspection, tracing or modification of non-system software 816 like user mode applications. 818 This characterization assumes that debug facilities can be enabled 819 and disabled in a dynamic way or be disabled in some permanent way 820 such that no enabling is possible. An example of dynamic enabling is 821 one where some authentication is required to enable debugging. An 822 example of permanent disabling is blowing a hardware fuse in a chip. 823 The specific type of the mechanism is not taken into account. For 824 example, it does not matter if authentication is by a global password 825 or by per-device public keys. 827 As with all claims, the absence of the debug level claim means it is 828 not reported. A conservative interpretation might assume the Not 829 Disabled state. It could however be that it is reported in a 830 proprietary claim. 832 This claim is not extensible so as to provide a common interoperable 833 description of debug status to the relying party. If a particular 834 implementation considers this claim to be inadequate, it can define 835 its own proprietary claim. It may consider including both this claim 836 as a coarse indication of debug status and its own proprietary claim 837 as a refined indication. 839 The higher levels of debug disabling requires that all debug 840 disabling of the levels below it be in effect. Since the lowest 841 level requires that all of the target's debug be currently disabled, 842 all other levels require that too. 844 There is no inheritance of claims from a submodule to a superior 845 module or vice versa. There is no assumption, requirement or 846 guarantee that the target of a superior module encompasses the 847 targets of submodules. Thus, every submodule must explicitly 848 describe its own debug state. The verifier or relying party 849 receiving an EAT cannot assume that debug is turned off in a 850 submodule because there is a claim indicating it is turned off in a 851 superior module. 853 An individual target device / submodule may have multiple debug 854 facilities. The use of plural in the description of the states 855 refers to that, not to any aggregation or inheritance. 857 The architecture of some chips or devices may be such that a debug 858 facility operates for the whole chip or device. If the EAT for such 859 a chip includes submodules, then each submodule should independently 860 report the status of the whole-chip or whole-device debug facility. 861 This is the only way the relying party can know the debug status of 862 the submodules since there is no inheritance. 864 3.11.1. Enabled 866 If any debug facility, even manufacturer hardware diagnostics, is 867 currently enabled, then this level must be indicated. 869 3.11.2. Disabled 871 This level indicates all debug facilities are currently disabled. It 872 may be possible to enable them in the future, and it may also be 873 possible that they were enabled in the past after the target device/ 874 sub-system booted/started, but they are currently disabled. 876 3.11.3. Disabled Since Boot 878 This level indicates all debug facilities are currently disabled and 879 have been so since the target device/sub-system booted/started. 881 3.11.4. Disabled Permanently 883 This level indicates all non-manufacturer facilities are permanently 884 disabled such that no end user or developer cannot enable them. Only 885 the manufacturer indicated in the OEMID claim can enable them. This 886 also indicates that all debug facilities are currently disabled and 887 have been so since boot/start. 889 3.11.5. Disabled Fully and Permanently 891 This level indicates that all debug capabilities for the target 892 device/sub-module are permanently disabled. 894 3.11.6. debug-status CDDL 895 debug-status-type = &( 896 enabled: 0, 897 disabled: 1, 898 disabled-since-boot: 2, 899 disabled-permanently: 3, 900 disabled-fully-and-permanently: 4 901 ) 903 debug-status-claim = ( 904 debug-status => debug-status-type 905 ) 907 3.12. Including Keys 909 An EAT may include a cryptographic key such as a public key. The 910 signing of the EAT binds the key to all the other claims in the 911 token. 913 The purpose for inclusion of the key may vary by use case. For 914 example, the key may be included as part of an IoT device onboarding 915 protocol. When the FIDO protocol includes a pubic key in its 916 attestation message, the key represents the binding of a user, device 917 and relying party. This document describes how claims containing 918 keys should be defined for the various use cases. It does not define 919 specific claims for specific use cases. 921 Keys in CBOR format tokens SHOULD be the COSE_Key format [RFC8152] 922 and keys in JSON format tokens SHOULD be the JSON Web Key format 923 [RFC7517]. These two formats support many common key types. Their 924 use avoids the need to decode other serialization formats. These two 925 formats can be extended to support further key types through their 926 IANA registries. 928 The general confirmation claim format [RFC8747], [RFC7800] may also 929 be used. It provides key encryption. It also allows for inclusion 930 by reference through a key ID. The confirmation claim format may 931 employed in the definition of some new claim for a a particular use 932 case. 934 When the actual confirmation claim is included in an EAT, this 935 document associates no use case semantics other than proof of 936 posession. Different EAT use cases may choose to associate further 937 semantics. The key in the confirmation claim MUST be protected the 938 same as the key used to sign the EAT. That is, the same, equivalent 939 or better hardware defenses, access controls, key generation and such 940 must be used. 942 3.13. The Location Claim (location) 944 The location claim gives the location of the device entity from which 945 the attestation originates. It is derived from the W3C Geolocation 946 API [W3C.GeoLoc]. The latitude, longitude, altitude and accuracy 947 must conform to [WGS84]. The altitude is in meters above the [WGS84] 948 ellipsoid. The two accuracy values are positive numbers in meters. 949 The heading is in degrees relative to true north. If the device is 950 stationary, the heading is NaN (floating-point not-a-number). The 951 speed is the horizontal component of the device velocity in meters 952 per second. 954 When encoding floating-point numbers half-precision should not be 955 used. It usually does not provide enough precision for a geographic 956 location. It is not a requirement that the receiver of an EAT 957 implement half-precision, so the receiver may not be able to decode 958 the location. 960 The location may have been cached for a period of time before token 961 creation. For example, it might have been minutes or hours or more 962 since the last contact with a GPS satellite. Either the timestamp or 963 age data item can be used to quantify the cached period. The 964 timestamp data item is preferred as it a non-relative time. 966 The age data item can be used when the entity doesn't know what time 967 it is either because it doesn't have a clock or it isn't set. The 968 entity must still have a "ticker" that can measure a time interval. 969 The age is the interval between acquisition of the location data and 970 token creation. 972 See location-related privacy considerations in Section 8.2 below. 974 3.13.1. location CDDL 975 location-type = { 976 latitude => number, 977 longitude => number, 978 ? altitude => number, 979 ? accuracy => number, 980 ? altitude-accuracy => number, 981 ? heading => number, 982 ? speed => number, 983 ? timestamp => ~time-int, 984 ? age => uint 985 } 987 latitude = 1 988 longitude = 2 989 altitude = 3 990 accuracy = 4 991 altitude-accuracy = 5 992 heading = 6 993 speed = 7 994 timestamp = 8 995 age = 9 997 location-claim = ( 998 location => location-type 999 ) 1001 3.14. The Uptime Claim (uptime) 1003 The "uptime" claim contains a value that represents the number of 1004 seconds that have elapsed since the entity or submod was last booted. 1006 3.14.1. uptime CDDL 1008 uptime-claim = ( 1009 uptime => uint 1010 ) 1012 3.14.2. The Boot Seed Claim (boot-seed) 1014 The Boot Seed claim is a random value created at system boot time 1015 that will allow differentiation of reports from different boot 1016 sessions. This value is usually public and not protected. It is not 1017 the same as a seed for a random number generator which must be kept 1018 secret. 1020 boot-seed-claim = ( 1021 boot-seed => bytes 1022 ) 1024 3.15. The Intended Use Claim (intended-use) 1026 EAT's may be used in the context of several different applications. 1027 The intended-use claim provides an indication to an EAT consumer 1028 about the intended usage of the token. This claim can be used as a 1029 way for an application using EAT to internally distinguish between 1030 different ways it uses EAT. 1032 1 - Generic Generic attestation describes an application where the 1033 EAT consumer requres the most up-to-date security assessment of 1034 the attesting entity. It is expected that this is the most 1035 commonly-used application of EAT. 1037 2- Registration Entities that are registering for a new service may 1038 be expected to provide an attestation as part of the registration 1039 process. This intended-use setting indicates that the attestation 1040 is not intended for any use but registration. 1042 3 - Provisioning Entities may be provisioned with different values 1043 or settings by an EAT consumer. Examples include key material or 1044 device management trees. The consumer may require an EAT to 1045 assess device security state of the entity prior to provisioning. 1047 4 - Certificate Issuance (Certificate Signing Request) Certifying 1048 authorities (CA's) may require attestations prior to the issuance 1049 of certificates related to keypairs hosted at the entity. An EAT 1050 may be used as part of the certificate signing request (CSR). 1052 5 - Proof-of-Possession An EAT consumer may require an attestation 1053 as part of an accompanying proof-of-possession (PoP) appication. 1054 More precisely, a PoP transaction is intended to provide to the 1055 recipient cryptographically-verifiable proof that the sender has 1056 posession of a key. This kind of attestation may be neceesary to 1057 verify the security state of the entity storing the private key 1058 used in a PoP application. 1060 3.15.1. intended-use CDDL 1061 intended-use-type = &( 1062 generic: 1, 1063 registration: 2, 1064 provisioning: 3, 1065 csr: 4, 1066 pop: 5 1067 ) 1069 intended-use-claim = ( 1070 intended-use => intended-use-type 1071 ) 1073 3.16. The Profile Claim (profile) 1075 The profile claim is a text string that simply gives the name of the 1076 profile to which the token purports to adhere to. It may name an 1077 IETF document, some other document or no particular document. There 1078 is no requirement that the named document be publicly accessible. 1080 See Section 5 for a detailed description of a profile. 1082 Note that this named "eat-profile" for JWT and is distinct from the 1083 already registered "profile" claim in the JWT claims registry. 1085 profile-claim = ( 1086 profile => tstr 1087 ) 1089 3.17. The Submodules Part of a Token (submods) 1091 Some devices are complex, having many subsystems or submodules. A 1092 mobile phone is a good example. It may have several connectivity 1093 submodules for communications (e.g., Wi-Fi and cellular). It may 1094 have subsystems for low-power audio and video playback. It may have 1095 one or more security-oriented subsystems like a TEE or a Secure 1096 Element. 1098 The claims for each these can be grouped together in a submodule. 1100 The submods part of a token are in a single map/object with many 1101 entries, one per submodule. There is only one submods map in a 1102 token. It is identified by its specific label. It is a peer to 1103 other claims, but it is not called a claim because it is a container 1104 for a claim set rather than an individual claim. This submods part 1105 of a token allows what might be called recursion. It allows claim 1106 sets inside of claim sets inside of claims sets... 1108 3.17.1. Two Types of Submodules 1110 Each entry in the submod map is one of two types: 1112 o A non-token submodule that is a map or object directly containing 1113 claims for the submodule. 1115 o A nested EAT that is a fully formed, independently signed EAT 1116 token 1118 3.17.1.1. Non-token Submodules 1120 This is simply a map or object containing claims about the submodule. 1122 It may contain claims that are the same as its surrounding token or 1123 superior submodules. For example, the top-level of the token may 1124 have a UEID, a submod may have a different UEID and a further 1125 subordinate submodule may also have a UEID. 1127 It is signed/encrypted along with the rest of the token and thus the 1128 claims are secured by the same Attester with the same signing key as 1129 the rest of the token. 1131 If a token is in CBOR format (a CWT or a UCCS), all non-token 1132 submodules must be CBOR format. If a token in in JSON format (a 1133 JWT), all non-token submodules must be in JSON format. 1135 When decoding, this type of submodule is recognized from the other 1136 type by being a data item of type map for CBOR or type object for 1137 JSON. 1139 3.17.1.2. Nested EATs 1141 This type of submodule is a fully formed secured EAT as defined in 1142 this document except that it MUST NOT be a UCCS or an unsecured JWT. 1143 A nested token that is one that is always secured using COSE or JOSE, 1144 usually by an independent Attester. When the surrounding EAT is a 1145 CWT or secured JWT, the nested token becomes securely bound with the 1146 other claims in the surrounding token. 1148 It is allowed to have a CWT as a submodule in a JWT and vice versa, 1149 but this SHOULD be avoided unless necessary. 1151 3.17.1.2.1. Surrounding EAT is CBOR format 1153 They type of an EAT nested in a CWT is determined by whether the CBOR 1154 type is a text string or a byte string. If a text string, then it is 1155 a JWT. If a byte string, then it is a CWT. 1157 A CWT nested in a CBOR-format token is always wrapped by a byte 1158 string for easier handling with standard CBOR decoders and token 1159 processing APIs that will typically take a byte buffer as input. 1161 Nested CWTs may be either a CWT CBOR tag or a CWT Protocol Message. 1162 COSE layers in nested CWT EATs MUST be a COSE_Tagged_Message, never a 1163 COSE_Untagged_Message. If a nested EAT has more than one level of 1164 COSE, for example one that is both encrypted and signed, a 1165 COSE_Tagged_message must be used at every level. 1167 3.17.1.2.2. Surrounding EAT is JSON format 1169 When a CWT is nested in a JWT, it must be as a 55799 tag in order to 1170 distinguish it from a nested JWT. 1172 When a nested EAT in a JWT is decoded, first remove the base64url 1173 encoding. Next, check to see if it starts with the bytes 0xd9d9f7. 1174 If so, then it is a CWT as a JWT will never start with these four 1175 bytes. If not if it is a JWT. 1177 Other than the 55799 tag requirement, tag usage for CWT's nested in a 1178 JSON format token follow the same rules as for CWTs nested in CBOR- 1179 format tokens. It may be a CWT CBOR tag or a CWT Protocol Message 1180 and COSE_Tagged_Message MUST be used at all COSE layers. 1182 3.17.1.3. Unsecured JWTs and UCCS Tokens as Submodules 1184 To incorporate a UCCS token as a submodule, it MUST be as a non-token 1185 submodule. This can be accomplished inserting the content of the 1186 UCCS Tag into the submodule map. The content of a UCCS tag is 1187 exactly a map of claims as required for a non-token submodule. If 1188 the UCCS is not a UCCS tag, then it can just be inserted into the 1189 submodule map directly. 1191 The definition of a nested EAT type of submodule is that it is one 1192 that is secured (signed) by an Attester. Since UCCS tokens are 1193 unsecured, they do not fulfill this definition and must be non-token 1194 submodules. 1196 To incorporate an Unsecured JWT as a submodule, the null-security 1197 JOSE wrapping should be removed. The resulting claims set should be 1198 inserted as a non-token submodule. 1200 To incorporate a UCCS token in a surrounding JSON token, the UCCS 1201 token claims should be translated from CBOR to JSON. To incorporate 1202 an Unsecured JWT into a surrounding CBOR-format token, the null- 1203 security JOSE should be removed and the claims translated from JSON 1204 to CBOR. 1206 3.17.2. No Inheritance 1208 The subordinate modules do not inherit anything from the containing 1209 token. The subordinate modules must explicitly include all of their 1210 claims. This is the case even for claims like the nonce and age. 1212 This rule is in place for simplicity. It avoids complex inheritance 1213 rules that might vary from one type of claim to another. 1215 3.17.3. Security Levels 1217 The security level of the non-token subordinate modules should always 1218 be less than or equal to that of the containing modules in the case 1219 of non-token submodules. It makes no sense for a module of lesser 1220 security to be signing claims of a module of higher security. An 1221 example of this is a TEE signing claims made by the non-TEE parts 1222 (e.g. the high-level OS) of the device. 1224 The opposite may be true for the nested tokens. They usually have 1225 their own more secure key material. An example of this is an 1226 embedded secure element. 1228 3.17.4. Submodule Names 1230 The label or name for each submodule in the submods map is a text 1231 string naming the submodule. No submodules may have the same name. 1233 3.17.5. submods CDDL 1234 ; The part of a token that contains all the submodules. It is a peer 1235 ; with the claims in the token, but not a claim, only a map/object to 1236 ; hold all the submodules. 1238 submods-part = ( 1239 submods => submods-type 1240 ) 1242 submods-type = { + submod-type } 1244 ; The type of a submodule which can either be a nested claim set or a 1245 ; nested separately signed token. Nested tokens are wrapped in a bstr 1246 ; or a tstr. 1248 submod-type = ( 1249 submod-name => eat-claim-set / nested-token 1250 ) 1252 ; When this is a bstr, the contents are an eat-token in CWT or UCCS 1253 ; format. When this is a tstr, the contents are an eat-token in JWT 1254 ; format. 1256 nested-token = bstr / tstr; 1258 ; Each submodule has a unique text string name. 1260 submod-name = tstr 1262 4. Endorsements and Verification Keys 1264 TODO: fill this section in. It will discuss key IDs, endorsement ID 1265 and such that are needed as input needed to by the Verifier to verify 1266 the signature. This will NOT discuss the contents of an Endorsement, 1267 just and ID/locator. 1269 5. Profiles 1271 This EAT specification does not gaurantee that implementations of it 1272 will interoperate. The variability in this specification is 1273 necessary to accommodate the widely varying use cases. An EAT 1274 profile narrows the specification for a specific use case. An ideal 1275 EAT profile will gauarantee interoperability. 1277 The profile can be named in the token using the profile claim 1278 described in Section 3.16. 1280 5.1. List of Profile Issues 1282 The following is a list of EAT, CWT, UCCS, JWS, COSE, JOSE and CBOR 1283 options that a profile should address. 1285 5.1.1. Use of JSON, CBOR or both 1287 The profile should indicate whether the token format should be CBOR, 1288 JSON, both or even some other encoding. If some other encoding, a 1289 specification for how the CDDL described here is serialized in that 1290 encoding is necessary. 1292 This should be addressed for the top-level token and for any nested 1293 tokens. For example, a profile might require all nested tokens to be 1294 of the same encoding of the top level token. 1296 5.1.2. CBOR Map and Array Encoding 1298 The profile should indicate whether definite-length arrays/maps, 1299 indefinite-length arrays/maps or both are allowed. A good default is 1300 to allow only definite-length arrays/maps. 1302 An alternate is to allow both definite and indefinite-length arrays/ 1303 maps. The decoder should accept either. Encoders that need to fit 1304 on very small hardware or be actually implement in hardware can use 1305 indefinite-length encoding. 1307 This applies to individual EAT claims, CWT and COSE parts of the 1308 implementation. 1310 5.1.3. CBOR String Encoding 1312 The profile should indicate whether definite-length strings, 1313 indefinite-length strings or both are allowed. A good default is to 1314 allow only definite-length strings. As with map and array encoding, 1315 allowing indefinite-length strings can be beneficial for some smaller 1316 implementations. 1318 5.1.4. COSE/JOSE Protection 1320 COSE and JOSE have several options for signed, MACed and encrypted 1321 messages. EAT/CWT has the option to have no protection using UCCS 1322 and JOSE has a NULL protection option. It is possible to implement 1323 no protection, sign only, MAC only, sign then encrypt and so on. All 1324 combinations allowed by COSE, JOSE, JWT, CWT and UCCS are allowed by 1325 EAT. 1327 The profile should list the protections that must be supported by all 1328 decoders implementing the profile. The encoders them must implement 1329 a subset of what is listed for the decoders, perhaps only one. 1331 Implementations may choose to sign or MAC before encryption so that 1332 the implementation layer doing the signing or MACing can be the 1333 smallest. It is often easier to make smaller implementations more 1334 secure, perhaps even implementing in solely in hardware. The key 1335 material for a signature or MAC is a private key, while for 1336 encryption it is likely to be a public key. The key for encryption 1337 requires less protection. 1339 5.1.5. COSE/JOSE Algorithms 1341 The profile document should list the COSE algorithms that a Verifier 1342 must implement. The Attester will select one of them. Since there 1343 is no negotiation, the Verifier should implement all algorithms 1344 listed in the profile. 1346 5.1.6. Verification Key Identification 1348 Section Section 4 describes a number of methods for identifying a 1349 verification key. The profile document should specify one of these 1350 or one that is not described. The ones described in this document 1351 are only roughly described. The profile document should go into the 1352 full detail. 1354 5.1.7. Endorsement Identification 1356 Similar to, or perhaps the same as Verification Key Identification, 1357 the profile may wish to specify how Endorsements are to be 1358 identified. However note that Endorsement Identification is 1359 optional, where as key identification is not. 1361 5.1.8. Required Claims 1363 The profile can list claims whose absence results in Verification 1364 failure. 1366 5.1.9. Prohibited Claims 1368 The profile can list claims whose presence results in Verification 1369 failure. 1371 5.1.10. Additional Claims 1373 The profile may describe entirely new claims. These claims can be 1374 required or optional. 1376 5.1.11. Refined Claim Definition 1378 The profile may lock down optional aspects of individual claims. For 1379 example, it may require altitude in the location claim, or it may 1380 require that HW Versions always be described using EAN-13. 1382 5.1.12. CBOR Tags 1384 The profile should specify whether the token should be a CWT Tag or 1385 not. Similarly, the profile should specify whether the token should 1386 be a UCCS tag or not. 1388 When COSE protection is used, the profile should specify whether COSE 1389 tags are used or not. Note that RFC 8392 requires COSE tags be used 1390 in a CWT tag. 1392 Often a tag is unncessary because the surrounding or carrying 1393 protocol identifies the object as an EAT. 1395 6. Encoding 1397 This makes use of the types defined in CDDL Appendix D, Standard 1398 Prelude. 1400 Some of the CDDL included here is for claims that are defined in CWT 1401 [RFC8392] or JWT [RFC7519] or are in the IANA CWT or JWT registries. 1402 CDDL was not in use when these claims where defined. 1404 6.1. Common CDDL Types 1406 time-int is identical to the epoch-based time, but disallows 1407 floating-point representation. 1409 string-or-uri = tstr 1411 time-int = #6.1(int) 1413 6.2. CDDL for CWT-defined Claims 1415 This section provides CDDL for the claims defined in CWT. It is non- 1416 normative as [RFC8392] is the authoritative definition of these 1417 claims. 1419 $$eat-extension //= ( 1420 ? issuer => text, 1421 ? subject => text, 1422 ? audience => text, 1423 ? expiration => time, 1424 ? not-before => time, 1425 ? issued-at => time, 1426 ? cwt-id => bytes, 1427 ) 1429 issuer = 1 1430 subject = 2 1431 audience = 3 1432 expiration = 4 1433 not-before = 5 1434 issued-at = 6 1435 cwt-id = 7 1437 6.3. JSON 1439 6.3.1. JSON Labels 1441 ueid /= "ueid" 1442 nonce /= "nonce" 1443 origination /= "origination" 1444 oemid /= "oemid" 1445 security-level /= "security-level" 1446 secure-boot /= "secure-boot" 1447 debug-status /= "debug-status" 1448 location /= "location" 1449 age /= "age" 1450 uptime /= "uptime" 1451 profile /= "eat-profile" 1452 boot-seed /= "bootseed" 1453 submods /= "submods" 1454 timestamp /= "timestamp" 1456 latitude /= "lat" 1457 longitude /= "long" 1458 altitude /= "alt" 1459 accuracy /= "accry" 1460 altitude-accuracy /= "alt-accry" 1461 heading /= "heading" 1462 speed /= "speed" 1464 6.3.2. JSON Interoperability 1466 JSON should be encoded per RFC 8610 Appendix E. In addition, the 1467 following CDDL types are encoded in JSON as follows: 1469 o bstr - must be base64url encoded 1471 o time - must be encoded as NumericDate as described section 2 of 1472 [RFC7519]. 1474 o string-or-uri - must be encoded as StringOrURI as described 1475 section 2 of [RFC7519]. 1477 6.4. CBOR 1479 6.4.1. CBOR Interoperability 1481 CBOR allows data items to be serialized in more than one form. If 1482 the sender uses a form that the receiver can't decode, there will not 1483 be interoperability. 1485 This specification gives no blanket requirements to narrow CBOR 1486 serialization for all uses of EAT. This allows individual uses to 1487 tailor serialization to the environment. It also may result in EAT 1488 implementations that don't interoperate. 1490 One way to guarantee interoperability is to clearly specify CBOR 1491 serialization in a profile document. See Section 5 for a list of 1492 serialization issues that should be addressed. 1494 EAT will be commonly used where the device generating the attestation 1495 is constrained and the receiver/verifier of the attestation is a 1496 capacious server. Following is a set of serialization requirements 1497 that work well for that use case and are guaranteed to interoperate. 1498 Use of this serialization is recommended where possible, but not 1499 required. An EAT profile may just reference the following section 1500 rather than spell out serialization details. 1502 6.4.1.1. EAT Constrained Device Serialization 1504 o Preferred serialization described in section 4.1 of [RFC8949] is 1505 not required. The EAT decoder must accept all forms of number 1506 serialization. The EAT encoder may use any form it wishes. 1508 o The EAT decoder must accept indefinite length arrays and maps as 1509 described in section 3.2.2 of [RFC8949]. The EAT encoder may use 1510 indefinite length arrays and maps if it wishes. 1512 o The EAT decoder must accept indefinite length strings as described 1513 in section 3.2.3 of [RFC8949]. The EAT encoder may use indefinite 1514 length strings if it wishes. 1516 o Sorting of maps by key is not required. The EAT decoder must not 1517 rely on sorting. 1519 o Deterministic encoding described in Section 4.2 of [RFC8949] is 1520 not required. 1522 o Basic validity described in section 5.3.1 of [RFC8949] must be 1523 followed. The EAT encoder must not send duplicate map keys/labels 1524 or invalid UTF-8 strings. 1526 6.5. Collected CDDL 1528 ; This is the top-level definition of the claims in EAT tokens. To 1529 ; form an actual EAT Token, this claim set is enclosed in a COSE, JOSE 1530 ; or UCCS message. 1532 eat-claim-set = { 1533 ? ueid-claim, 1534 ? nonce-claim, 1535 ? origination-claim, 1536 ? oemid-claim, 1537 ? hardware-version-claims, 1538 ? security-level-claim, 1539 ? secure-boot-claim, 1540 ? debug-status-claim, 1541 ? location-claim, 1542 ? profile-claim, 1543 ? uptime-claim, 1544 ? boot-seed-claim, 1545 ? submods-part, 1546 * $$eat-extension, 1547 } 1549 ; This is the top-level definition of an EAT Token. It is a CWT, JWT 1550 ; or UCSS where the payload is an eat-claim-set. A JWT_Message is what 1551 ; is defined by JWT in RFC 7519. (RFC 7519 doesn't use CDDL so a there 1552 ; is no actual CDDL definition of JWT_Message). 1554 eat-token = EAT_Tagged_Message / EAT_Untagged_Message / JWT_Message 1556 ; This is CBOR-format EAT token in the CWT or UCCS format that is a 1557 ; tag. COSE_Tagged_message is defined in RFC 8152. Tag 601 is 1558 ; proposed by the UCCS draft, but not yet assigned. 1560 EAT_Tagged_Message = #6.61(COSE_Tagged_Message) / #6.601(eat-claim-set) 1562 ; This is a CBOR-format EAT token that is a CWT or UCSS that is not a 1563 ; tag COSE_Tagged_message and COSE_Untagged_Message are defined in RFC 1564 ; 8152. 1566 EAT_Untagged_Message = COSE_Tagged_Message / 1567 COSE_Untagged_Message / 1568 UCCS_Untagged_Message 1570 ; This is an "unwrapped" UCCS tag. Unwrapping a tag means to use the 1571 ; definition of its content without the preceding type 6 tag 1572 ; integer. Since a UCCS is nothing but a tag for an unsecured CWT 1573 ; claim set, unwrapping reduces to a bare eat-claim-set. 1575 UCCS_Untagged_Message = eat-claim-set 1577 ; The following Claim Keys (labels) are temporary. They are not 1578 ; assigned by IANA 1580 nonce = 10 1581 ueid = 11 1582 origination = 12 1583 oemid = 13 1584 security-level = 14 1585 secure-boot = 15 1586 debug-status = 16 1587 location = 17 1588 profile = 18 1589 uptime = 19 1590 submods = 20 1591 boot-seed = 21 1593 chip-version = 21 1594 board-version = 22 1595 device-version = 23 1596 chip-version-scheme = 24 1597 board-version-scheme = 25 1598 device-version-scheme = 26 1599 ean-chip-version = 27 1600 ean-board-version = 28 1601 ean-device-version = 29 1602 string-or-uri = tstr 1603 time-int = #6.1(int) 1604 $$eat-extension //= ( 1605 ? issuer => text, 1606 ? subject => text, 1607 ? audience => text, 1608 ? expiration => time, 1609 ? not-before => time, 1610 ? issued-at => time, 1611 ? cwt-id => bytes, 1612 ) 1614 issuer = 1 1615 subject = 2 1616 audience = 3 1617 expiration = 4 1618 not-before = 5 1619 issued-at = 6 1620 cwt-id = 7 1622 debug-status-type = &( 1623 enabled: 0, 1624 disabled: 1, 1625 disabled-since-boot: 2, 1626 disabled-permanently: 3, 1627 disabled-fully-and-permanently: 4 1628 ) 1630 debug-status-claim = ( 1631 debug-status => debug-status-type 1632 ) 1633 location-type = { 1634 latitude => number, 1635 longitude => number, 1636 ? altitude => number, 1637 ? accuracy => number, 1638 ? altitude-accuracy => number, 1639 ? heading => number, 1640 ? speed => number, 1641 ? timestamp => ~time-int, 1642 ? age => uint 1643 } 1645 latitude = 1 1646 longitude = 2 1647 altitude = 3 1648 accuracy = 4 1649 altitude-accuracy = 5 1650 heading = 6 1651 speed = 7 1652 timestamp = 8 1653 age = 9 1655 location-claim = ( 1656 location => location-type 1657 ) 1658 nonce-type = bstr .size (8..64) 1660 nonce-claim = ( 1661 nonce => nonce-type / [ 2* nonce-type ] 1662 ) 1663 oemid-claim = ( 1664 oemid => bstr 1665 ) 1666 ; copied from CoSWID 1667 ; TODO: how to properly make reference to CoSWID and have tool validate 1669 $version-scheme /= multipartnumeric 1670 $version-scheme /= multipartnumeric-suffix 1671 $version-scheme /= alphanumeric 1672 $version-scheme /= decimal 1673 $version-scheme /= semver 1674 $version-scheme /= uint / text 1675 multipartnumeric = 1 1676 multipartnumeric-suffix = 2 1677 alphanumeric = 3 1678 decimal = 4 1679 semver = 16384 1681 chip-version-claim = ( 1682 chip-version => tstr 1683 ) 1685 chip-version-scheme-claim = ( 1686 chip-version-scheme => $version-scheme 1687 ) 1689 board-version-claim = ( 1690 board-version => tstr 1691 ) 1693 board-version-scheme-claim = ( 1694 board-version-scheme => $version-scheme 1695 ) 1697 device-version-claim = ( 1698 device-version => tstr 1700 ) 1702 device-version-scheme-claim = ( 1703 device-version-scheme => $version-scheme 1704 ) 1706 ean-type = text .regexp "[0-9]{13}" 1708 ean-chip-version-claim = ( 1709 ean-chip-version => ean-type 1710 ) 1712 ean-board-version-claim = ( 1713 ean-board-version => ean-type 1714 ) 1716 ean-device-version-claim = ( 1717 ean-device-version => ean-type 1718 ) 1720 hardware-version-claims = ( 1721 ? chip-version-claim, 1722 ? board-version-claim, 1723 ? device-version-claim, 1724 ? chip-version-scheme-claim, 1725 ? board-version-scheme-claim, 1726 ? device-version-scheme-claim, 1727 ? ean-chip-version-claim, 1728 ? ean-board-version-claim, 1729 ? ean-device-version-claim, 1730 ) 1732 origination-claim = ( 1733 origination => string-or-uri 1734 ) 1735 secure-boot-claim = ( 1736 secure-boot => bool 1737 ) 1738 security-level-type = &( 1739 unrestricted: 1, 1740 restricted: 2, 1741 secure-restricted: 3, 1742 hardware: 4 1743 ) 1745 security-level-claim = ( 1746 security-level => security-level-type 1748 ) 1749 ; The part of a token that contains all the submodules. It is a peer 1750 ; with the claims in the token, but not a claim, only a map/object to 1751 ; hold all the submodules. 1753 submods-part = ( 1754 submods => submods-type 1755 ) 1757 submods-type = { + submod-type } 1759 ; The type of a submodule which can either be a nested claim set or a 1760 ; nested separately signed token. Nested tokens are wrapped in a bstr 1761 ; or a tstr. 1763 submod-type = ( 1764 submod-name => eat-claim-set / nested-token 1765 ) 1767 ; When this is a bstr, the contents are an eat-token in CWT or UCCS 1768 ; format. When this is a tstr, the contents are an eat-token in JWT 1769 ; format. 1771 nested-token = bstr / tstr; 1773 ; Each submodule has a unique text string name. 1775 submod-name = tstr 1777 ueid-type = bstr .size (7..33) 1779 ueid-claim = ( 1780 ueid => ueid-type 1781 ) 1782 uptime-claim = ( 1783 uptime => uint 1784 ) 1785 profile-claim = ( 1786 profile => tstr 1787 ) 1788 boot-seed-claim = ( 1789 boot-seed => bytes 1790 ) 1791 ueid /= "ueid" 1792 nonce /= "nonce" 1793 origination /= "origination" 1794 oemid /= "oemid" 1795 security-level /= "security-level" 1796 secure-boot /= "secure-boot" 1797 debug-status /= "debug-status" 1798 location /= "location" 1799 age /= "age" 1800 uptime /= "uptime" 1801 profile /= "eat-profile" 1802 boot-seed /= "bootseed" 1803 submods /= "submods" 1804 timestamp /= "timestamp" 1806 latitude /= "lat" 1807 longitude /= "long" 1808 altitude /= "alt" 1809 accuracy /= "accry" 1810 altitude-accuracy /= "alt-accry" 1811 heading /= "heading" 1812 speed /= "speed" 1814 7. IANA Considerations 1816 7.1. Reuse of CBOR Web Token (CWT) Claims Registry 1818 Claims defined for EAT are compatible with those of CWT so the CWT 1819 Claims Registry is re used. No new IANA registry is created. All 1820 EAT claims should be registered in the CWT and JWT Claims Registries. 1822 7.2. Claim Characteristics 1824 The following is design guidance for creating new EAT claims, 1825 particularly those to be registered with IANA. 1827 Much of this guidance is generic and could also be considered when 1828 designing new CWT or JWT claims. 1830 7.2.1. Interoperability and Relying Party Orientation 1832 It is a broad goal that EATs can be processed by relying parties in a 1833 general way regardless of the type, manufacturer or technology of the 1834 device from which they originate. It is a goal that there be 1835 general-purpose verification implementations that can verify tokens 1836 for large numbers of use cases with special cases and configurations 1837 for different device types. This is a goal of interoperability of 1838 the semantics of claims themselves, not just of the signing, encoding 1839 and serialization formats. 1841 This is a lofty goal and difficult to achieve broadly requiring 1842 careful definition of claims in a technology neutral way. Sometimes 1843 it will be difficult to design a claim that can represent the 1844 semantics of data from very different device types. However, the 1845 goal remains even when difficult. 1847 7.2.2. Operating System and Technology Neutral 1849 Claims should be defined such that they are not specific to an 1850 operating system. They should be applicable to multiple large high- 1851 level operating systems from different vendors. They should also be 1852 applicable to multiple small embedded operating systems from multiple 1853 vendors and everything in between. 1855 Claims should not be defined such that they are specific to a SW 1856 environment or programming language. 1858 Claims should not be defined such that they are specific to a chip or 1859 particular hardware. For example, they should not just be the 1860 contents of some HW status register as it is unlikely that the same 1861 HW status register with the same bits exists on a chip of a different 1862 manufacturer. 1864 The boot and debug state claims in this document are an example of a 1865 claim that has been defined in this neutral way. 1867 7.2.3. Security Level Neutral 1869 Many use cases will have EATs generated by some of the most secure 1870 hardware and software that exists. Secure Elements and smart cards 1871 are examples of this. However, EAT is intended for use in low- 1872 security use cases the same as high-security use case. For example, 1873 an app on a mobile device may generate EATs on its own. 1875 Claims should be defined and registered on the basis of whether they 1876 are useful and interoperable, not based on security level. In 1877 particular, there should be no exclusion of claims because they are 1878 just used only in low-security environments. 1880 7.2.4. Reuse of Extant Data Formats 1882 Where possible, claims should use already standardized data items, 1883 identifiers and formats. This takes advantage of the expertise put 1884 into creating those formats and improves interoperability. 1886 Often extant claims will not be defined in an encoding or 1887 serialization format used by EAT. It is preferred to define a CBOR 1888 and JSON format for them so that EAT implementations do not require a 1889 plethora of encoders and decoders for serialization formats. 1891 In some cases, it may be better to use the encoding and serialization 1892 as is. For example, signed X.509 certificates and CRLs can be 1893 carried as-is in a byte string. This retains interoperability with 1894 the extensive infrastructure for creating and processing X.509 1895 certificates and CRLs. 1897 7.2.5. Proprietary Claims 1899 EAT allows the definition and use of proprietary claims. 1901 For example, a device manufacturer may generate a token with 1902 proprietary claims intended only for verification by a service 1903 offered by that device manufacturer. This is a supported use case. 1905 In many cases proprietary claims will be the easiest and most obvious 1906 way to proceed, however for better interoperability, use of general 1907 standardized claims is preferred. 1909 7.3. Claims Registered by This Document 1911 o Claim Name: UEID 1913 o Claim Description: The Universal Entity ID 1915 o JWT Claim Name: N/A 1917 o Claim Key: 8 1919 o Claim Value Type(s): byte string 1921 o Change Controller: IESG 1923 o Specification Document(s): *this document* 1925 TODO: add the rest of the claims in here 1927 8. Privacy Considerations 1929 Certain EAT claims can be used to track the owner of an entity and 1930 therefore, implementations should consider providing privacy- 1931 preserving options dependent on the intended usage of the EAT. 1932 Examples would include suppression of location claims for EAT's 1933 provided to unauthenticated consumers. 1935 8.1. UEID Privacy Considerations 1937 A UEID is usually not privacy-preserving. Any set of relying parties 1938 that receives tokens that happen to be from a single device will be 1939 able to know the tokens are all from the same device and be able to 1940 track the device. Thus, in many usage situations ueid violates 1941 governmental privacy regulation. In other usage situations UEID will 1942 not be allowed for certain products like browsers that give privacy 1943 for the end user. It will often be the case that tokens will not 1944 have a UEID for these reasons. 1946 There are several strategies that can be used to still be able to put 1947 UEID's in tokens: 1949 o The device obtains explicit permission from the user of the device 1950 to use the UEID. This may be through a prompt. It may also be 1951 through a license agreement. For example, agreements for some 1952 online banking and brokerage services might already cover use of a 1953 UEID. 1955 o The UEID is used only in a particular context or particular use 1956 case. It is used only by one relying party. 1958 o The device authenticates the relying party and generates a derived 1959 UEID just for that particular relying party. For example, the 1960 relying party could prove their identity cryptographically to the 1961 device, then the device generates a UEID just for that relying 1962 party by hashing a proofed relying party ID with the main device 1963 UEID. 1965 Note that some of these privacy preservation strategies result in 1966 multiple UEIDs per device. Each UEID is used in a different context, 1967 use case or system on the device. However, from the view of the 1968 relying party, there is just one UEID and it is still globally 1969 universal across manufacturers. 1971 8.2. Location Privacy Considerations 1973 Geographic location is most always considered personally identifiable 1974 information. Implementers should consider laws and regulations 1975 governing the transmission of location data from end user devices to 1976 servers and services. Implementers should consider using location 1977 management facilities offered by the operating system on the device 1978 generating the attestation. For example, many mobile phones prompt 1979 the user for permission when before sending location data. 1981 9. Security Considerations 1983 The security considerations provided in Section 8 of [RFC8392] and 1984 Section 11 of [RFC7519] apply to EAT in its CWT and JWT form, 1985 respectively. In addition, implementors should consider the 1986 following. 1988 9.1. Key Provisioning 1990 Private key material can be used to sign and/or encrypt the EAT, or 1991 can be used to derive the keys used for signing and/or encryption. 1992 In some instances, the manufacturer of the entity may create the key 1993 material separately and provision the key material in the entity 1994 itself. The manfuacturer of any entity that is capable of producing 1995 an EAT should take care to ensure that any private key material be 1996 suitably protected prior to provisioning the key material in the 1997 entity itself. This can require creation of key material in an 1998 enclave (see [RFC4949] for definition of "enclave"), secure 1999 transmission of the key material from the enclave to the entity using 2000 an appropriate protocol, and persistence of the private key material 2001 in some form of secure storage to which (preferably) only the entity 2002 has access. 2004 9.1.1. Transmission of Key Material 2006 Regarding transmission of key material from the enclave to the 2007 entity, the key material may pass through one or more intermediaries. 2008 Therefore some form of protection ("key wrapping") may be necessary. 2009 The transmission itself may be performed electronically, but can also 2010 be done by human courier. In the latter case, there should be 2011 minimal to no exposure of the key material to the human (e.g. 2012 encrypted portable memory). Moreover, the human should transport the 2013 key material directly from the secure enclave where it was created to 2014 a destination secure enclave where it can be provisioned. 2016 9.2. Transport Security 2018 As stated in Section 8 of [RFC8392], "The security of the CWT relies 2019 upon on the protections offered by COSE". Similar considerations 2020 apply to EAT when sent as a CWT. However, EAT introduces the concept 2021 of a nonce to protect against replay. Since an EAT may be created by 2022 an entity that may not support the same type of transport security as 2023 the consumer of the EAT, intermediaries may be required to bridge 2024 communications between the entity and consumer. As a result, it is 2025 RECOMMENDED that both the consumer create a nonce, and the entity 2026 leverage the nonce along with COSE mechanisms for encryption and/or 2027 signing to create the EAT. 2029 Similar considerations apply to the use of EAT as a JWT. Although 2030 the security of a JWT leverages the JSON Web Encryption (JWE) and 2031 JSON Web Signature (JWS) specifications, it is still recommended to 2032 make use of the EAT nonce. 2034 9.3. Multiple EAT Consumers 2036 In many cases, more than one EAT consumer may be required to fully 2037 verify the entity attestation. Examples include individual consumers 2038 for nested EATs, or consumers for individual claims with an EAT. 2039 When multiple consumers are required for verification of an EAT, it 2040 is important to minimize information exposure to each consumer. In 2041 addition, the communication between multiple consumers should be 2042 secure. 2044 For instance, consider the example of an encrypted and signed EAT 2045 with multiple claims. A consumer may receive the EAT (denoted as the 2046 "receiving consumer"), decrypt its payload, verify its signature, but 2047 then pass specific subsets of claims to other consumers for 2048 evaluation ("downstream consumers"). Since any COSE encryption will 2049 be removed by the receiving consumer, the communication of claim 2050 subsets to any downstream consumer should leverage a secure protocol 2051 (e.g.one that uses transport-layer security, i.e. TLS), 2053 However, assume the EAT of the previous example is hierarchical and 2054 each claim subset for a downstream consumer is created in the form of 2055 a nested EAT. Then transport security between the receiving and 2056 downstream consumers is not strictly required. Nevertheless, 2057 downstream consumers of a nested EAT should provide a nonce unique to 2058 the EAT they are consuming. 2060 10. References 2062 10.1. Normative References 2064 [CoSWID] "Concise Software Identification Tags", November 2020, 2065 . 2067 [EAN-13] GS1, "International Article Number - EAN/UPC barcodes", 2068 2019, . 2070 [FIDO.AROE] 2071 The FIDO Alliance, "FIDO Authenticator Allowed Restricted 2072 Operating Environments List", November 2019, 2073 . 2076 [IANA.CWT.Claims] 2077 IANA, "CBOR Web Token (CWT) Claims", 2078 . 2080 [IANA.JWT.Claims] 2081 IANA, "JSON Web Token (JWT) Claims", 2082 . 2084 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2085 Requirement Levels", BCP 14, RFC 2119, 2086 DOI 10.17487/RFC2119, March 1997, 2087 . 2089 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 2090 DOI 10.17487/RFC7517, May 2015, 2091 . 2093 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 2094 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 2095 . 2097 [RFC7800] Jones, M., Bradley, J., and H. Tschofenig, "Proof-of- 2098 Possession Key Semantics for JSON Web Tokens (JWTs)", 2099 RFC 7800, DOI 10.17487/RFC7800, April 2016, 2100 . 2102 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 2103 Writing an IANA Considerations Section in RFCs", BCP 26, 2104 RFC 8126, DOI 10.17487/RFC8126, June 2017, 2105 . 2107 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 2108 RFC 8152, DOI 10.17487/RFC8152, July 2017, 2109 . 2111 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2112 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2113 May 2017, . 2115 [RFC8392] Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, 2116 "CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392, 2117 May 2018, . 2119 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 2120 Definition Language (CDDL): A Notational Convention to 2121 Express Concise Binary Object Representation (CBOR) and 2122 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 2123 June 2019, . 2125 [RFC8747] Jones, M., Seitz, L., Selander, G., Erdtman, S., and H. 2126 Tschofenig, "Proof-of-Possession Key Semantics for CBOR 2127 Web Tokens (CWTs)", RFC 8747, DOI 10.17487/RFC8747, March 2128 2020, . 2130 [RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object 2131 Representation (CBOR)", STD 94, RFC 8949, 2132 DOI 10.17487/RFC8949, December 2020, 2133 . 2135 [ThreeGPP.IMEI] 2136 3GPP, "3rd Generation Partnership Project; Technical 2137 Specification Group Core Network and Terminals; Numbering, 2138 addressing and identification", 2019, 2139 . 2142 [UCCS.Draft] 2143 Birkholz, H., "A CBOR Tag for Unprotected CWT Claims 2144 Sets", 2020, 2145 . 2147 [WGS84] National Imagery and Mapping Agency, "National Imagery and 2148 Mapping Agency Technical Report 8350.2, Third Edition", 2149 2000, . 2152 10.2. Informative References 2154 [BirthdayAttack] 2155 "Birthday attack", 2156 . 2158 [Common.Criteria] 2159 "Common Criteria for Information Technology Security 2160 Evaluation", April 2017, 2161 . 2163 [ECMAScript] 2164 "Ecma International, "ECMAScript Language Specification, 2165 5.1 Edition", ECMA Standard 262", June 2011, 2166 . 2169 [FIDO.Registry] 2170 The FIDO Alliance, "FIDO Registry of Predefined Values", 2171 December 2019, . 2174 [FIPS-140] 2175 National Institue of Standards, "Security Requirements for 2176 Cryptographic Modules", May 2001, 2177 . 2180 [IDevID] "IEEE Standard, "IEEE 802.1AR Secure Device Identifier"", 2181 December 2009, . 2184 [IEEE.802-2001] 2185 "IEEE Standard For Local And Metropolitan Area Networks 2186 Overview And Architecture", 2007, 2187 . 2190 [IEEE.RA] "IEEE Registration Authority", 2191 . 2194 [OUI.Guide] 2195 "Guidelines for Use of Extended Unique Identifier (EUI), 2196 Organizationally Unique Identifier (OUI), and Company ID 2197 (CID)", August 2017, 2198 . 2201 [OUI.Lookup] 2202 "IEEE Registration Authority Assignments", 2203 . 2206 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 2207 Unique IDentifier (UUID) URN Namespace", RFC 4122, 2208 DOI 10.17487/RFC4122, July 2005, 2209 . 2211 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 2212 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 2213 . 2215 [W3C.GeoLoc] 2216 Worldwide Web Consortium, "Geolocation API Specification 2217 2nd Edition", January 2018, . 2220 Appendix A. Examples 2222 A.1. Very Simple EAT 2224 This is shown in CBOR diagnostic form. Only the payload signed by 2225 COSE is shown. 2227 { 2228 / issuer / 1: "joe", 2229 / nonce / 10: h'948f8860d13a463e8e', 2230 / UEID / 11: h'0198f50a4ff6c05861c8860d13a638ea', 2231 / secure-boot / 15: true, 2232 / debug-disable / 16: 3, / permanent-disable / 2233 / timestamp (iat) / 6: 1(1526542894), 2234 / chip-version / 21: "1.4a", 2235 / chip-version-scheme / 24: 2 / multipartnumeric+suffix / 2236 } 2238 A.2. Example with Submodules, Nesting and Security Levels 2240 { 2241 / nonce / 10: h'948f8860d13a463e8e', 2242 / UEID / 11: h'0198f50a4ff6c05861c8860d13a638ea' 2243 / secure-boot / 15: true, 2244 / debug-disable / 16: 3, / permanent-disable / 2245 / timestamp (iat) / 6: 1(1526542894), 2246 / security-level / 14: 3, / secure restricted OS / 2247 / submods / 20: { 2248 / first submod, an Android Application / 2249 "Android App Foo" : { 2250 / security-level / 14: 1 / unrestricted / 2251 }, 2253 / 2nd submod, A nested EAT from a secure element / 2254 "Secure Element Eat" : 2255 / an embedded EAT, bytes of which are not shown / 2256 h'420123', 2258 / 3rd submod, information about Linux Android / 2259 "Linux Android": { 2260 / security-level / 14: 1 / unrestricted / 2261 } 2262 } 2263 } 2265 Appendix B. UEID Design Rationale 2267 B.1. Collision Probability 2269 This calculation is to determine the probability of a collision of 2270 UEIDs given the total possible entity population and the number of 2271 entities in a particular entity management database. 2273 Three different sized databases are considered. The number of 2274 devices per person roughly models non-personal devices such as 2275 traffic lights, devices in stores they shop in, facilities they work 2276 in and so on, even considering individual light bulbs. A device may 2277 have individually attested subsystems, for example parts of a car or 2278 a mobile phone. It is assumed that the largest database will have at 2279 most 10% of the world's population of devices. Note that databases 2280 that handle more than a trillion records exist today. 2282 The trillion-record database size models an easy-to-imagine reality 2283 over the next decades. The quadrillion-record database is roughly at 2284 the limit of what is imaginable and should probably be accommodated. 2285 The 100 quadrillion datadbase is highly speculative perhaps involving 2286 nanorobots for every person, livestock animal and domesticated bird. 2287 It is included to round out the analysis. 2289 Note that the items counted here certainly do not have IP address and 2290 are not individually connected to the network. They may be connected 2291 to internal buses, via serial links, Bluetooth and so on. This is 2292 not the same problem as sizing IP addresses. 2294 +---------+------------+--------------+------------+----------------+ 2295 | People | Devices / | Subsystems / | Database | Database Size | 2296 | | Person | Device | Portion | | 2297 +---------+------------+--------------+------------+----------------+ 2298 | 10 | 100 | 10 | 10% | trillion | 2299 | billion | | | | (10^12) | 2300 | 10 | 100,000 | 10 | 10% | quadrillion | 2301 | billion | | | | (10^15) | 2302 | 100 | 1,000,000 | 10 | 10% | 100 | 2303 | billion | | | | quadrillion | 2304 | | | | | (10^17) | 2305 +---------+------------+--------------+------------+----------------+ 2307 This is conceptually similar to the Birthday Problem where m is the 2308 number of possible birthdays, always 365, and k is the number of 2309 people. It is also conceptually similar to the Birthday Attack where 2310 collisions of the output of hash functions are considered. 2312 The proper formula for the collision calculation is 2313 p = 1 - e^{-k^2/(2n)} 2315 p Collision Probability 2316 n Total possible population 2317 k Actual population 2319 However, for the very large values involved here, this formula 2320 requires floating point precision higher than commonly available in 2321 calculators and SW so this simple approximation is used. See 2322 [BirthdayAttack]. 2324 p = k^2 / 2n 2326 For this calculation: 2328 p Collision Probability 2329 n Total population based on number of bits in UEID 2330 k Population in a database 2332 +----------------------+--------------+--------------+--------------+ 2333 | Database Size | 128-bit UEID | 192-bit UEID | 256-bit UEID | 2334 +----------------------+--------------+--------------+--------------+ 2335 | trillion (10^12) | 2 * 10^-15 | 8 * 10^-35 | 5 * 10^-55 | 2336 | quadrillion (10^15) | 2 * 10^-09 | 8 * 10^-29 | 5 * 10^-49 | 2337 | 100 quadrillion | 2 * 10^-05 | 8 * 10^-25 | 5 * 10^-45 | 2338 | (10^17) | | | | 2339 +----------------------+--------------+--------------+--------------+ 2341 Next, to calculate the probability of a collision occurring in one 2342 year's operation of a database, it is assumed that the database size 2343 is in a steady state and that 10% of the database changes per year. 2344 For example, a trillion record database would have 100 billion states 2345 per year. Each of those states has the above calculated probability 2346 of a collision. 2348 This assumption is a worst-case since it assumes that each state of 2349 the database is completely independent from the previous state. In 2350 reality this is unlikely as state changes will be the addition or 2351 deletion of a few records. 2353 The following tables gives the time interval until there is a 2354 probability of a collision based on there being one tenth the number 2355 of states per year as the number of records in the database. 2357 t = 1 / ((k / 10) * p) 2359 t Time until a collision 2360 p Collision probability for UEID size 2361 k Database size 2363 +---------------------+---------------+--------------+--------------+ 2364 | Database Size | 128-bit UEID | 192-bit UEID | 256-bit UEID | 2365 +---------------------+---------------+--------------+--------------+ 2366 | trillion (10^12) | 60,000 years | 10^24 years | 10^44 years | 2367 | quadrillion (10^15) | 8 seconds | 10^14 years | 10^34 years | 2368 | 100 quadrillion | 8 | 10^11 years | 10^31 years | 2369 | (10^17) | microseconds | | | 2370 +---------------------+---------------+--------------+--------------+ 2372 Clearly, 128 bits is enough for the near future thus the requirement 2373 that UEIDs be a minimum of 128 bits. 2375 There is no requirement for 256 bits today as quadrillion-record 2376 databases are not expected in the near future and because this time- 2377 to-collision calculation is a very worst case. A future update of 2378 the standard may increase the requirement to 256 bits, so there is a 2379 requirement that implementations be able to receive 256-bit UEIDs. 2381 B.2. No Use of UUID 2383 A UEID is not a UUID [RFC4122] by conscious choice for the following 2384 reasons. 2386 UUIDs are limited to 128 bits which may not be enough for some future 2387 use cases. 2389 Today, cryptographic-quality random numbers are available from common 2390 CPUs and hardware. This hardware was introduced between 2010 and 2391 2015. Operating systems and cryptographic libraries give access to 2392 this hardware. Consequently, there is little need for 2393 implementations to construct such random values from multiple sources 2394 on their own. 2396 Version 4 UUIDs do allow for use of such cryptographic-quality random 2397 numbers, but do so by mapping into the overall UUID structure of time 2398 and clock values. This structure is of no value here yet adds 2399 complexity. It also slightly reduces the number of actual bits with 2400 entropy. 2402 UUIDs seem to have been designed for scenarios where the implementor 2403 does not have full control over the environment and uniqueness has to 2404 be constructed from identifiers at hand. UEID takes the view that 2405 hardware, software and/or manufacturing process directly implement 2406 UEID in a simple and direct way. It takes the view that 2407 cryptographic quality random number generators are readily available 2408 as they are implemented in commonly used CPU hardware. 2410 Appendix C. Changes from Previous Drafts 2412 The following is a list of known changes from the previous drafts. 2413 This list is non-authoritative. It is meant to help reviewers see 2414 the significant differences. 2416 C.1. From draft-rats-eat-01 2418 o Added UEID design rationale appendix 2420 C.2. From draft-mandyam-rats-eat-00 2422 This is a fairly large change in the orientation of the document, but 2423 no new claims have been added. 2425 o Separate information and data model using CDDL. 2427 o Say an EAT is a CWT or JWT 2429 o Use a map to structure the boot_state and location claims 2431 C.3. From draft-ietf-rats-eat-01 2433 o Clarifications and corrections for OEMID claim 2435 o Minor spelling and other fixes 2437 o Add the nonce claim, clarify jti claim 2439 C.4. From draft-ietf-rats-eat-02 2441 o Roll all EUIs back into one UEID type 2443 o UEIDs can be one of three lengths, 128, 192 and 256. 2445 o Added appendix justifying UEID design and size. 2447 o Submods part now includes nested eat tokens so they can be named 2448 and there can be more tha one of them 2450 o Lots of fixes to the CDDL 2452 o Added security considerations 2454 C.5. From draft-ietf-rats-eat-03 2456 o Split boot_state into secure-boot and debug-disable claims 2458 o Debug disable is an enumerated type rather than Booleans 2460 C.6. From draft-ietf-rats-eat-04 2462 o Change IMEI-based UEIDs to be encoded as a 14-byte string 2464 o CDDL cleaned up some more 2466 o CDDL allows for JWTs and UCCSs 2468 o CWT format submodules are byte string wrapped 2470 o Allows for JWT nested in CWT and vice versa 2472 o Allows UCCS (unsigned CWTs) and JWT unsecured tokens 2474 o Clarify tag usage when nesting tokens 2476 o Add section on key inclusion 2478 o Add hardware version claims 2480 o Collected CDDL is now filled in. Other CDDL corrections. 2482 o Rename debug-disable to debug-status; clarify that it is not 2483 extensible 2485 o Security level claim is not extensible 2487 o Improve specification of location claim and added a location 2488 privacy section 2490 o Add intended use claim 2492 C.7. From draft-ietf-rats-05 2494 o CDDL format issues resolved 2496 o Corrected reference to Location Privacy section 2498 C.8. From draft-ietf-rats-06 2500 o Added boot-seed claim 2502 o Rework CBOR interoperability section 2504 o Added profiles claim and section 2506 Authors' Addresses 2508 Giridhar Mandyam 2509 Qualcomm Technologies Inc. 2510 5775 Morehouse Drive 2511 San Diego, California 2512 USA 2514 Phone: +1 858 651 7200 2515 EMail: mandyam@qti.qualcomm.com 2517 Laurence Lundblade 2518 Security Theory LLC 2520 EMail: lgl@island-resort.com 2522 Miguel Ballesteros 2523 Qualcomm Technologies Inc. 2524 5775 Morehouse Drive 2525 San Diego, California 2526 USA 2528 Phone: +1 858 651 4299 2529 EMail: mballest@qti.qualcomm.com 2531 Jeremy O'Donoghue 2532 Qualcomm Technologies Inc. 2533 279 Farnborough Road 2534 Farnborough GU14 7LS 2535 United Kingdom 2537 Phone: +44 1252 363189 2538 EMail: jodonogh@qti.qualcomm.com