idnits 2.17.1 draft-ietf-rats-yang-tpm-charra-17.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 66 instances of too long lines in the document, the longest one being 8 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 196 has weird spacing: '...te-name cer...' == Line 226 has weird spacing: '...r-index pcr...' == Line 310 has weird spacing: '...-number uin...' == Line 372 has weird spacing: '...version ide...' == Line 376 has weird spacing: '...sh-algo ide...' -- The document date (16 March 2022) is 772 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. 'BIOS-Log-Event-Type' == Outdated reference: A later version (-35) exists of draft-ietf-netconf-keystore-24 == Outdated reference: A later version (-22) exists of draft-ietf-rats-architecture-15 ** Downref: Normative reference to an Informational draft: draft-ietf-rats-architecture (ref. 'I-D.ietf-rats-architecture') == Outdated reference: A later version (-14) exists of draft-ietf-rats-tpm-based-network-device-attest-13 ** Downref: Normative reference to an Informational draft: draft-ietf-rats-tpm-based-network-device-attest (ref. 'I-D.ietf-rats-tpm-based-network-device-attest') -- Possible downref: Non-RFC (?) normative reference: ref. 'IEEE-Std-1363-2000' -- Possible downref: Non-RFC (?) normative reference: ref. 'IEEE-Std-1363a-2004' -- Possible downref: Non-RFC (?) normative reference: ref. 'ISO-IEC-10116' -- Possible downref: Non-RFC (?) normative reference: ref. 'ISO-IEC-10118-3' -- Possible downref: Non-RFC (?) normative reference: ref. 'ISO-IEC-14888-3' -- Possible downref: Non-RFC (?) normative reference: ref. 'ISO-IEC-15946-1' -- Possible downref: Non-RFC (?) normative reference: ref. 'ISO-IEC-18033-3' -- Possible downref: Non-RFC (?) normative reference: ref. 'ISO-IEC-9797-1' -- Possible downref: Non-RFC (?) normative reference: ref. 'ISO-IEC-9797-2' -- Possible downref: Non-RFC (?) normative reference: ref. 'NIST-PUB-FIPS-202' -- Possible downref: Non-RFC (?) normative reference: ref. 'NIST-SP800-108' -- Possible downref: Non-RFC (?) normative reference: ref. 'NIST-SP800-38C' -- Possible downref: Non-RFC (?) normative reference: ref. 'NIST-SP800-38D' -- Possible downref: Non-RFC (?) normative reference: ref. 'NIST-SP800-38F' -- Possible downref: Non-RFC (?) normative reference: ref. 'NIST-SP800-56A' ** Downref: Normative reference to an Informational RFC: RFC 2104 ** Downref: Normative reference to an Informational RFC: RFC 8017 ** Downref: Normative reference to an Informational RFC: RFC 8032 -- Possible downref: Non-RFC (?) normative reference: ref. 'TCG-Algos' -- Possible downref: Non-RFC (?) normative reference: ref. 'UEFI-Secure-Boot' == Outdated reference: A later version (-09) exists of draft-ietf-rats-reference-interaction-models-05 Summary: 6 errors (**), 0 flaws (~~), 10 warnings (==), 19 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 RATS Working Group H. Birkholz 3 Internet-Draft M. Eckel 4 Intended status: Standards Track Fraunhofer SIT 5 Expires: 17 September 2022 S. Bhandari 6 ThoughtSpot 7 E. Voit 8 B. Sulzen 9 Cisco 10 L. Xia 11 Huawei 12 T. Laffey 13 HPE 14 G. Fedorkow 15 Juniper 16 16 March 2022 18 A YANG Data Model for Challenge-Response-based Remote Attestation 19 Procedures using TPMs 20 draft-ietf-rats-yang-tpm-charra-17 22 Abstract 24 This document defines YANG RPCs and a few configuration nodes 25 required to retrieve attestation evidence about integrity 26 measurements from a device, following the operational context defined 27 in TPM-based Network Device Remote Integrity Verification. 28 Complementary measurement logs are also provided by the YANG RPCs, 29 originating from one or more roots of trust for measurement (RTMs). 30 The module defined requires at least one TPM 1.2 or TPM 2.0 as well 31 as a corresponding TPM Software Stack (TSS), or equivalent hardware 32 implementations that include the protected capabilities as provided 33 by TPMs as well as a corresponding software stack, included in the 34 device components of the composite device the YANG server is running 35 on. 37 Status of This Memo 39 This Internet-Draft is submitted in full conformance with the 40 provisions of BCP 78 and BCP 79. 42 Internet-Drafts are working documents of the Internet Engineering 43 Task Force (IETF). Note that other groups may also distribute 44 working documents as Internet-Drafts. The list of current Internet- 45 Drafts is at https://datatracker.ietf.org/drafts/current/. 47 Internet-Drafts are draft documents valid for a maximum of six months 48 and may be updated, replaced, or obsoleted by other documents at any 49 time. It is inappropriate to use Internet-Drafts as reference 50 material or to cite them other than as "work in progress." 52 This Internet-Draft will expire on 17 September 2022. 54 Copyright Notice 56 Copyright (c) 2022 IETF Trust and the persons identified as the 57 document authors. All rights reserved. 59 This document is subject to BCP 78 and the IETF Trust's Legal 60 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 61 license-info) in effect on the date of publication of this document. 62 Please review these documents carefully, as they describe your rights 63 and restrictions with respect to this document. Code Components 64 extracted from this document must include Simplified BSD License text 65 as described in Section 4.e of the Trust Legal Provisions and are 66 provided without warranty as described in the Simplified BSD License. 68 Table of Contents 70 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 71 1.1. Requirements notation . . . . . . . . . . . . . . . . . . 3 72 2. The YANG Module for Basic Remote Attestation Procedures . . . 3 73 2.1. YANG Modules . . . . . . . . . . . . . . . . . . . . . . 3 74 2.1.1. 'ietf-tpm-remote-attestation' . . . . . . . . . . . . 4 75 2.1.2. 'ietf-tcg-algs' . . . . . . . . . . . . . . . . . . . 33 76 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 48 77 4. Security Considerations . . . . . . . . . . . . . . . . . . . 49 78 5. References . . . . . . . . . . . . . . . . . . . . . . . . . 50 79 5.1. Normative References . . . . . . . . . . . . . . . . . . 51 80 5.2. Informative References . . . . . . . . . . . . . . . . . 55 81 Appendix A. Integrity Measurement Architecture (IMA) . . . . . . 56 82 Appendix B. IMA for Network Equipment Boot Logs . . . . . . . . 57 83 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 58 85 1. Introduction 87 This document is based on the general terminology defined in the 88 [I-D.ietf-rats-architecture] and uses the operational context defined 89 in [I-D.ietf-rats-tpm-based-network-device-attest] as well as the 90 interaction model and information elements defined in 91 [I-D.ietf-rats-reference-interaction-models]. The currently 92 supported hardware security modules (HSMs) are the Trusted Platform 93 Modules (TPMs) [TPM1.2] and [TPM2.0] as specified by the Trusted 94 Computing Group (TCG). One TPM, or multiple TPMs in the case of a 95 Composite Device, are required in order to use the YANG module 96 defined in this document. Each TPM is used as a root of trust for 97 storage (RTS) in order to store system security measurement Evidence. 98 And each TPM is used as a root of trust for reporting (RTR) in order 99 to retrieve attestation Evidence. This is done by using a YANG RPC 100 to request a quote which exposes a rolling hash the security 101 measurements held internally within the TPM. 103 Specific terms imported from [I-D.ietf-rats-architecture] and used in 104 this document include: Attester, Composite Device, Evidence. 106 Specific terms imported from [TPM2.0-Key] and used in this document 107 include: Endorsement Key (EK), Initial Attestation Key (IAK), 108 Attestation Identity Key (AIK), Local Attestation Key (LAK). 110 1.1. Requirements notation 112 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 113 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 114 "OPTIONAL" in this document are to be interpreted as described in 115 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 116 capitals, as shown here. 118 2. The YANG Module for Basic Remote Attestation Procedures 120 One or more TPMs MUST be embedded in a Composite Device that provides 121 attestation evidence via the YANG module defined in this document. 122 The ietf-tpm-remote-attestation YANG module enables a composite 123 device to take on the role of an Attester, in accordance with the 124 Remote Attestation Procedures (RATS) architecture 125 [I-D.ietf-rats-architecture], and the corresponding challenge- 126 response interaction model defined in the 127 [I-D.ietf-rats-reference-interaction-models] document. A fresh nonce 128 with an appropriate amount of entropy [NIST-915121] MUST be supplied 129 by the YANG client in order to enable a proof-of-freshness with 130 respect to the attestation Evidence provided by the Attester running 131 the YANG datastore. Further, this nonce is used to prevent replay 132 attacks. The method for communicating the relationship of each 133 individual TPM to specific measured component within the Composite 134 Device is out of the scope of this document. 136 2.1. YANG Modules 138 In this section the several YANG modules are defined. 140 2.1.1. 'ietf-tpm-remote-attestation' 142 This YANG module imports modules from [RFC6991] with prefix 'yang', 143 [RFC8348] with prefix 'hw', [I-D.ietf-netconf-keystore] with prefix 144 'ks', and 'ietf-tcg-algs.yang' Section 2.1.2.3 with prefix 'taa'. 145 Additionally, references are made to [RFC8032], [RFC8017], [RFC6933], 146 [TPM1.2-Commands], [TPM2.0-Arch], [TPM2.0-Structures], [TPM2.0-Key], 147 [TPM1.2-Structures], [bios-log], [ima-log], [BIOS-Log-Event-Type], as 148 well as Appendix A and Appendix B. 150 2.1.1.1. Features 152 This module supports the following features: 154 * 'mtpm': Indicates that multiple TPMs on the device can support 155 remote attestation. For example, this feature could be used in 156 cases where multiple line cards are present, each with its own 157 TPM. 159 * 'bios': Indicates that the device supports the retrieval of BIOS/ 160 UEFI event logs. [bios-log] 162 * 'ima': Indicates that the device supports the retrieval of event 163 logs from the Linux Integrity Measurement Architecture (IMA 164 [ima-log]). Also see Appendix A. 166 * 'netequip_boot': Indicates that the device supports the retrieval 167 of netequip boot event logs. See Appendix A and Appendix B. 169 2.1.1.2. Identities 171 This module supports the following types of attestation event logs: 172 'bios', 'ima', and 'netequip_boot'. 174 2.1.1.3. Remote Procedure Calls (RPCs) 176 In the following, RPCs for both TPM 1.2 and TPM 2.0 attestation 177 procedures are defined. 179 2.1.1.3.1. 'tpm12-challenge-response-attestation' 181 This RPC allows a Verifier to request signed TPM PCRs (_TPM Quote_ 182 operation) from a TPM 1.2 compliant cryptoprocessor. Where the 183 feature 'mtpm' is active, and one or more 'certificate-name' is not 184 provided, all TPM 1.2 compliant cryptoprocessors will respond. A 185 YANG tree diagram of this RPC is as follows: 187 +---x tpm12-challenge-response-attestation {taa:tpm12}? 188 +---w input 189 | +---w tpm12-attestation-challenge 190 | +---w pcr-index* pcr 191 | +---w nonce-value binary 192 | +---w certificate-name* certificate-name-ref 193 | {tpm:mtpm}? 194 +--ro output 195 +--ro tpm12-attestation-response* [] 196 +--ro certificate-name certificate-name-ref 197 +--ro up-time? uint32 198 +--ro TPM_QUOTE2? binary 200 2.1.1.3.2. 'tpm20-challenge-response-attestation' 202 This RPC allows a Verifier to request signed TPM PCRs (_TPM Quote_ 203 operation) from a TPM 2.0 compliant cryptoprocessor. Where the 204 feature 'mtpm' is active, and one or more 'certificate-name' is not 205 provided, all TPM 2.0 compliant cryptoprocessors will respond. A 206 YANG tree diagram of this RPC is as follows: 208 +---x tpm20-challenge-response-attestation {taa:tpm20}? 209 +---w input 210 | +---w tpm20-attestation-challenge 211 | +---w nonce-value binary 212 | +---w tpm20-pcr-selection* [] 213 | | +---w tpm20-hash-algo? identityref 214 | | +---w pcr-index* pcr 215 | +---w certificate-name* certificate-name-ref 216 | {tpm:mtpm}? 217 +--ro output 218 +--ro tpm20-attestation-response* [] 219 +--ro certificate-name certificate-name-ref 220 +--ro TPMS_QUOTE_INFO binary 221 +--ro quote-signature? binary 222 +--ro up-time? uint32 223 +--ro unsigned-pcr-values* [] 224 +--ro tpm20-hash-algo? identityref 225 +--ro pcr-values* [pcr-index] 226 +--ro pcr-index pcr 227 +--ro pcr-value? binary 229 An example of an RPC challenge requesting PCRs 0-7 from a SHA-256 230 bank could look like the following: 232 233 234 xmlns="urn:ietf:params:xml:ns:yang:ietf-tpm-remote-attestation"> 235 236 (identifier of a TPM signature key with which the Verifier is 237 supposed to sign the attestation data) 238 239 240 0xe041307208d9f78f5b1bbecd19e2d152ad49de2fc5a7d8dbf769f6b8ffdeab9 241 242 243 245 TPM_ALG_SHA256 246 247 0 248 1 249 2 250 3 251 4 252 5 253 6 254 7 255 256 257 259 A successful response could be formatted as follows: 261 263 265 267 (instance of Certificate name in the Keystore) 268 269 270 (raw attestation data, i.e. the TPM quote; this includes 271 a composite digest of requested PCRs, the nonce, 272 and TPM 2.0 time information.) 273 274 275 (signature over attestation-data using the TPM key 276 identified by sig-key-id) 277 278 279 281 2.1.1.4. 'log-retrieval' 283 This RPC allows a Verifier to acquire the evidence which was extended 284 into specific TPM PCRs. A YANG tree diagram of this RPC is as 285 follows: 287 +---x log-retrieval 288 +---w input 289 | +---w log-type identityref 290 | +---w log-selector* [] 291 | +---w name* string 292 | +---w (index-type)? 293 | | +--:(last-entry) 294 | | | +---w last-entry-value? binary 295 | | +--:(index) 296 | | | +---w last-index-number? uint64 297 | | +--:(timestamp) 298 | | +---w timestamp? yang:date-and-time 299 | +---w log-entry-quantity? uint16 300 +--ro output 301 +--ro system-event-logs 302 +--ro node-data* [] 303 +--ro name? string 304 +--ro up-time? uint32 305 +--ro log-result 306 +--ro (attested_event_log_type) 307 +--:(bios) {bios}? 308 | +--ro bios-event-logs 309 | +--ro bios-event-entry* [event-number] 310 | +--ro event-number uint32 311 | +--ro event-type? uint32 312 | +--ro pcr-index? pcr 313 | +--ro digest-list* [] 314 | | +--ro hash-algo? identityref 315 | | +--ro digest* binary 316 | +--ro event-size? uint32 317 | +--ro event-data* binary 318 +--:(ima) {ima}? 319 | +--ro ima-event-logs 320 | +--ro ima-event-entry* [event-number] 321 | +--ro event-number uint64 322 | +--ro ima-template? string 323 | +--ro filename-hint? string 324 | +--ro filedata-hash? binary 325 | +--ro filedata-hash-algorithm? string 326 | +--ro template-hash-algorithm? string 327 | +--ro template-hash? binary 328 | +--ro pcr-index? pcr 329 | +--ro signature? binary 330 +--:(netequip_boot) {netequip_boot}? 331 +--ro boot-event-logs 332 +--ro boot-event-entry* [event-number] 333 +--ro event-number uint64 334 +--ro ima-template? string 335 +--ro filename-hint? string 336 +--ro filedata-hash? binary 337 +--ro filedata-hash-algorithm? string 338 +--ro template-hash-algorithm? string 339 +--ro template-hash? binary 340 +--ro pcr-index? pcr 341 +--ro signature? binary 343 2.1.1.5. Data Nodes 345 This section provides a high level description of the data nodes 346 containing the configuration and operational objects with the YANG 347 model. For more details, please see the YANG model itself in 348 Figure 1. 350 Container 'rats-support-structures': This houses the set of 351 information relating to remote attestation for a device. This 352 includes specific device TPM(s), the compute nodes (such as line 353 cards) on which the TPM(s) reside, and the algorithms supported 354 across the platform. 356 Container 'tpms': Provides configuration and operational details for 357 each supported TPM, including the tpm-firmware-version, PCRs which 358 may be quoted, certificates which are associated with that TPM, 359 and the current operational status. Of note are the certificates 360 which are associated with that TPM. As a certificate is 361 associated with a particular TPM attestation key, knowledge of the 362 certificate allows a specific TPM to be identified. 364 +--rw tpms 365 +--rw tpm* [name] 366 +--rw name string 367 +--ro hardware-based boolean 368 +--ro physical-index? int32 {hw:entity-mib}? 369 +--ro path? string 370 +--ro compute-node compute-node-ref {tpm:mtpm}? 371 +--ro manufacturer? string 372 +--rw firmware-version identityref 373 +--rw tpm12-hash-algo? identityref 374 +--rw tpm12-pcrs* pcr 375 +--rw tpm20-pcr-bank* [tpm20-hash-algo] 376 | +--rw tpm20-hash-algo identityref 377 | +--rw pcr-index* tpm:pcr 378 +--ro status enumeration 379 +--rw certificates 380 +--rw certificate* [name] 381 +--rw name string 382 +--rw keystore-ref? leafref {ks:asymmetric-keys}? 383 +--rw type? enumeration 385 container 'attester-supported-algos' - Identifies which TCG hash 386 algorithms are available for use on the Attesting platform. This 387 allows an operator to limit algorithms available for use by RPCs to 388 just a desired set from the universe of all allowed hash algorithms 389 by the TCG. 391 +--rw attester-supported-algos 392 +--rw tpm12-asymmetric-signing* identityref 393 +--rw tpm12-hash* identityref 394 +--rw tpm20-asymmetric-signing* identityref 395 +--rw tpm20-hash* identityref 397 container 'compute-nodes' - When there is more than one TPM 398 supported, this container maintains the set of information related to 399 the compute node associated with a specific TPM. This allows each 400 specific TPM to identify to which 'compute-node' it belongs. 402 +--rw compute-nodes {tpm:mtpm}? 403 +--ro compute-node* [node-id] 404 +--ro node-id string 405 +--ro node-physical-index? int32 {hw:entity-mib}? 406 +--ro node-name? string 407 +--ro node-location? string 409 2.1.1.6. YANG Module 410 file "ietf-tpm-remote-attestation@2022-03-15.yang" 411 module ietf-tpm-remote-attestation { 412 namespace "urn:ietf:params:xml:ns:yang:ietf-tpm-remote-attestation"; 413 prefix tpm; 415 import ietf-yang-types { 416 prefix yang; 417 } 418 import ietf-hardware { 419 prefix hw; 420 } 421 import ietf-keystore { 422 prefix ks; 423 } 424 import ietf-tcg-algs { 425 prefix taa; 426 } 428 organization 429 "IETF RATS (Remote ATtestation procedureS) Working Group"; 430 contact 431 "WG Web : 432 WG List : 433 Author : Eric Voit 434 Author : Henk Birkholz 435 Author : Michael Eckel 436 Author : Shwetha Bhandari 437 Author : Bill Sulzen 438 Author : Liang Xia (Frank) 439 Author : Tom Laffey 440 Author : Guy Fedorkow "; 441 description 442 "A YANG module to enable a TPM 1.2 and TPM 2.0 based 443 remote attestation procedure using a challenge-response 444 interaction model and the TPM 1.2 and TPM 2.0 Quote 445 primitive operations. 447 Copyright (c) 2022 IETF Trust and the persons identified 448 as authors of the code. All rights reserved. 449 Redistribution and use in source and binary forms, with or 450 without modification, is permitted pursuant to, and subject to 451 the license terms contained in, the Simplified BSD License set 452 forth in Section 4.c of the IETF Trust's Legal Provisions 453 Relating to IETF Documents 454 (https://trustee.ietf.org/license-info). 456 This version of this YANG module is part of RFC XXXX 457 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC 458 itself for full legal notices. 460 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 461 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 462 'MAY', and 'OPTIONAL' in this document are to be interpreted as 463 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 464 they appear in all capitals, as shown here."; 466 revision 2022-03-15 { 467 description 468 "Initial version"; 469 reference 470 "RFC XXXX: A YANG Data Model for Challenge-Response-based Remote 471 Attestation Procedures using TPMs"; 472 } 474 /*****************/ 475 /* Features */ 476 /*****************/ 478 feature mtpm { 479 description 480 "The device supports the remote attestation of multiple 481 TPM based cryptoprocessors."; 482 } 484 feature bios { 485 description 486 "The device supports the bios logs."; 487 reference 488 "bios-log: 489 https://trustedcomputinggroup.org/wp-content/uploads/ 490 PC-ClientSpecific_Platform_Profile_for_TPM_2p0_Systems_v51.pdf 491 Section 9.4.5.2"; 492 } 494 feature ima { 495 description 496 "The device supports Integrity Measurement Architecture logs. 497 Many variants of IMA logs exist in the deployment. Each encodes 498 the log entry contents as the specific measurements which get 499 hashed into a PCRs as Evidence. See the reference below for 500 one example of such an encoding."; 501 reference 502 "ima-log: 503 https://www.trustedcomputinggroup.org/wp-content/uploads/ 504 TCG_IWG_CEL_v1_r0p41_pub.pdf Section 4.3"; 505 } 506 feature netequip_boot { 507 description 508 "The device supports the netequip_boot logs."; 509 reference 510 "netequip-boot-log: 511 https://www.kernel.org/doc/Documentation/ABI/testing/ima_policy"; 512 } 514 /*****************/ 515 /* Typedefs */ 516 /*****************/ 518 typedef pcr { 519 type uint8 { 520 range "0..31"; 521 } 522 description 523 "Valid index number for a PCR. A {{TPM2.0}} compliant PCR index 524 extends from 0-31. At this time a typical TPM would have no 525 more than 32 PCRS."; 526 } 528 typedef compute-node-ref { 529 type leafref { 530 path "/tpm:rats-support-structures/tpm:compute-nodes" 531 + "/tpm:compute-node/tpm:node-name"; 532 } 533 description 534 "This type is used to reference a hardware node. Note that an 535 implementer might include an alternative leafref pointing to a 536 different YANG module node specifying hardware structures."; 537 } 539 typedef certificate-name-ref { 540 type leafref { 541 path "/tpm:rats-support-structures/tpm:tpms/tpm:tpm" 542 + "/tpm:certificates/tpm:certificate/tpm:name"; 543 } 544 description 545 "A type which allows identification of a TPM based certificate."; 546 } 548 /******************/ 549 /* Identities */ 550 /******************/ 552 identity attested_event_log_type { 553 description 554 "Base identity allowing categorization of the reasons why an 555 attested measurement has been taken on an Attester."; 556 } 558 identity ima { 559 base attested_event_log_type; 560 description 561 "An event type recorded in IMA."; 562 } 564 identity bios { 565 base attested_event_log_type; 566 description 567 "An event type associated with BIOS/UEFI."; 568 } 570 identity netequip_boot { 571 base attested_event_log_type; 572 description 573 "An event type associated with Network Equipment Boot."; 574 } 576 /*****************/ 577 /* Groupings */ 578 /*****************/ 580 grouping tpm20-hash-algo { 581 description 582 "The cryptographic algorithm used to hash the TPM2 PCRs. This 583 must be from the list of platform supported options."; 584 leaf tpm20-hash-algo { 585 type identityref { 586 base taa:hash; 587 } 588 must '/tpm:rats-support-structures/tpm:attester-supported-algos' 589 + '/tpm:tpm20-hash' { 590 error-message "This platform does not support tpm20-hash-algo"; 591 } 592 default "taa:TPM_ALG_SHA256"; 593 description 594 "The hash scheme that is used to hash a TPM2.0 PCR. This 595 must be one of those supported by a platform."; 596 } 597 } 599 grouping tpm12-hash-algo { 600 description 601 "The cryptographic algorithm used to hash the TPM1.2 PCRs."; 603 leaf tpm12-hash-algo { 604 type identityref { 605 base taa:hash; 606 } 607 must '/tpm:rats-support-structures/tpm:attester-supported-algos' 608 + '/tpm:tpm12-hash' { 609 error-message "This platform does not support tpm12-hash-algo"; 610 } 611 default "taa:TPM_ALG_SHA1"; 612 description 613 "The hash scheme that is used to hash a TPM1.2 PCR. This 614 MUST be one of those supported by a platform."; 615 } 616 } 618 grouping nonce { 619 description 620 "A random number intended to guarantee freshness and for use 621 as part of a replay-detection mechanism."; 622 leaf nonce-value { 623 type binary; 624 mandatory true; 625 description 626 "A cryptographically generated random number which should 627 not be predictable prior to its issuance from a random 628 number generation function. The random number MUST be 629 derived from an entropy source external to the Attester. 631 Note that a nonce sent into a TPM will typically be 160 or 256 632 binary digits long. (This is 20 or 32 bytes.) So if fewer 633 binary digits are sent, this nonce object will be padded 634 with leading zeros within Quotes returned from the TPM. 635 Additionally if more bytes are sent, the nonce will be trimmed 636 to the most significant binary digits."; 637 } 638 } 640 grouping tpm12-pcr-selection { 641 description 642 "A Verifier can request one or more PCR values using its 643 individually created Attestation Key Certificate (AC). 644 The corresponding selection filter is represented in this 645 grouping."; 646 leaf-list pcr-index { 647 type pcr; 648 description 649 "The numbers/indexes of the PCRs. In addition, any selection 650 of PCRs MUST verify that the set of PCRs requested are a 651 subset the set of PCRs exposed by in the leaf-list 652 /tpm:rats-support-structures 653 /tpm:tpms/tpm:tpm[name=current()]/tpm:tpm12-pcrs"; 654 } 655 } 657 grouping tpm20-pcr-selection { 658 description 659 "A Verifier can acquire one or more PCR values, which are hashed 660 together in a TPM2B_DIGEST coming from the TPM2. The selection 661 list of desired PCRs and the Hash Algorithm is represented in 662 this grouping."; 663 list tpm20-pcr-selection { 664 unique "tpm20-hash-algo"; 665 description 666 "Specifies the list of PCRs and Hash Algorithms that can be 667 returned within a TPM2B_DIGEST."; 668 reference 669 "TPM2.0-Structures: 670 https://www.trustedcomputinggroup.org/wp-content/uploads/ 671 TPM-Rev-2.0-Part-2-Structures-01.38.pdf Section 10.9.7"; 672 uses tpm20-hash-algo; 673 leaf-list pcr-index { 674 type pcr; 675 must '/tpm:rats-support-structures/tpm:tpms' 676 + '/tpm:tpm[name = current()] and ' 677 + '/tpm:rats-support-structures/tpm:tpms/tpm:tpm' 678 + '/tpm:tpm20-pcr-bank[pcr-index = current()]' { 679 error-message "Acquiring this PCR index is not supported"; 680 } 681 description 682 "The numbers of the PCRs that which are being tracked 683 with a hash based on the tpm20-hash-algo. In addition, 684 any selection of PCRs MUST verify that the set of PCRs 685 requested are a subset the set of PCR indexes exposed 686 within /tpm:rats-support-structures/tpm:tpms 687 /tpm:tpm[name=current()]/tpm:tpm20-pcr-bank 688 /tpm:pcr-index"; 689 } 690 } 691 } 693 grouping certificate-name-ref { 694 description 695 "Identifies a certificate in a keystore."; 696 leaf certificate-name { 697 type certificate-name-ref; 698 mandatory true; 699 description 700 "Identifies a certificate in a keystore."; 701 } 702 } 704 grouping tpm-name { 705 description 706 "A unique TPM on a device."; 707 leaf name { 708 type string; 709 description 710 "Unique system generated name for a TPM on a device."; 711 } 712 } 714 grouping node-uptime { 715 description 716 "Uptime in seconds of the node."; 717 leaf up-time { 718 type uint32; 719 description 720 "Uptime in seconds of this node reporting its data"; 721 } 722 } 724 grouping tpm12-attestation { 725 description 726 "Contains an instance of TPM1.2 style signed cryptoprocessor 727 measurements. It is supplemented by unsigned Attester 728 information."; 729 uses node-uptime; 730 leaf TPM_QUOTE2 { 731 type binary; 732 description 733 "Result of a TPM1.2 Quote2 operation. This includes PCRs, 734 signatures, locality, the provided nonce and other data which 735 can be further parsed to appraise the Attester."; 736 reference 737 "TPM1.2-Commands: 738 TPM1.2 commands rev116 July 2007, Section 16.5 739 https://trustedcomputinggroup.org/wp-content/uploads 740 /TPM-Main-Part-3-Commands_v1.2_rev116_01032011.pdf"; 741 } 742 } 744 grouping tpm20-attestation { 745 description 746 "Contains an instance of TPM2 style signed cryptoprocessor 747 measurements. It is supplemented by unsigned Attester 748 information."; 749 leaf TPMS_QUOTE_INFO { 750 type binary; 751 mandatory true; 752 description 753 "A hash of the latest PCR values (and the hash algorithm used) 754 which have been returned from a Verifier for the selected PCRs 755 and Hash Algorithms."; 756 reference 757 "TPM2.0-Structures: 758 https://www.trustedcomputinggroup.org/wp-content/uploads/ 759 TPM-Rev-2.0-Part-2-Structures-01.38.pdf Section 10.12.1"; 760 } 761 leaf quote-signature { 762 type binary; 763 description 764 "Quote signature returned by TPM Quote. The signature was 765 generated using the key associated with the 766 certificate 'name'."; 767 reference 768 "TPM2.0-Structures: 769 https://www.trustedcomputinggroup.org/wp-content/uploads/ 770 TPM-Rev-2.0-Part-2-Structures-01.38.pdf Section 11.2.1"; 771 } 772 uses node-uptime; 773 list unsigned-pcr-values { 774 description 775 "PCR values in each PCR bank. This might appear redundant with 776 the TPM2B_DIGEST, but that digest is calculated across multiple 777 PCRs. Having to verify across multiple PCRs does not 778 necessarily make it easy for a Verifier to appraise just the 779 minimum set of PCR information which has changed since the last 780 received TPM2B_DIGEST. Put another way, why should a Verifier 781 reconstruct the proper value of all PCR Quotes when only a 782 single PCR has changed? 783 To help this happen, if the Attester does know specific PCR 784 values, the Attester can provide these individual values via 785 'unsigned-pcr-values'. By comparing this information to 786 what has previously been validated, it is possible for a 787 Verifier to confirm the Attester's signature while eliminating 789 significant processing. Note that there should never be a 790 result where an unsigned PCR value differs from what may be 791 reconstructed from the within the PCR quote and the event logs. 792 If there is a difference, a signed result which has been 793 verified from retrieved logs is considered definitive."; 794 uses tpm20-hash-algo; 795 list pcr-values { 796 key "pcr-index"; 797 description 798 "List of one PCR bank."; 799 leaf pcr-index { 800 type pcr; 801 description 802 "PCR index number."; 803 } 804 leaf pcr-value { 805 type binary; 806 description 807 "PCR value."; 808 reference 809 "TPM2.0-Structures: 810 https://www.trustedcomputinggroup.org/wp-content/uploads/ 811 TPM-Rev-2.0-Part-2-Structures-01.38.pdf Section 10.9.7"; 812 } 813 } 814 } 815 } 817 grouping log-identifier { 818 description 819 "Identifier for type of log to be retrieved."; 820 leaf log-type { 821 type identityref { 822 base attested_event_log_type; 823 } 824 mandatory true; 825 description 826 "The corresponding measurement log type identity."; 827 } 828 } 830 grouping boot-event-log { 831 description 832 "Defines a specific instance of an event log entry 833 and corresponding to the information used to 834 extend the PCR"; 835 leaf event-number { 836 type uint32; 837 description 838 "Unique event number of this event which monotonically 839 increases. The maximum event number should not be 840 reached, nor is wrapping back to an earlier number 841 supported."; 842 } 843 leaf event-type { 844 type uint32; 845 description 846 "BIOS Log Event Type: 847 https://trustedcomputinggroup.org/wp-content/uploads/ 848 TCG_PCClient_PFP_r1p05_v23_pub.pdf Section 10.4.1"; 849 } 850 leaf pcr-index { 851 type pcr; 852 description 853 "Defines the PCR index that this event extended"; 854 } 855 list digest-list { 856 description 857 "Hash of event data"; 858 leaf hash-algo { 859 type identityref { 860 base taa:hash; 861 } 862 description 863 "The hash scheme that is used to compress the event data in 864 each of the leaf-list digest items."; 865 } 866 leaf-list digest { 867 type binary; 868 description 869 "The hash of the event data using the algorithm of the 870 'hash-algo' against 'event data'."; 871 } 872 } 873 leaf event-size { 874 type uint32; 875 description 876 "Size of the event data"; 877 } 878 leaf-list event-data { 879 type binary; 880 description 881 "The event data size determined by event-size. For more 882 see "; 883 } 884 } 886 grouping bios-event-log { 887 description 888 "Measurement log created by the BIOS/UEFI."; 889 list bios-event-entry { 890 key "event-number"; 891 description 892 "Ordered list of TCG described event log 893 that extended the PCRs in the order they 894 were logged"; 895 uses boot-event-log; 896 } 897 } 899 grouping ima-event { 900 description 901 "Defines a hash log extend event for IMA measurements"; 902 reference 903 "ima-log: 904 https://www.trustedcomputinggroup.org/wp-content/uploads/ 905 TCG_IWG_CEL_v1_r0p41_pub.pdf Section 4.3"; 906 leaf event-number { 907 type uint64; 908 description 909 "Unique event number of this event which monotonically 910 increases. The maximum event number should not be 911 reached, nor is wrapping back to an earlier number 912 supported."; 913 } 914 leaf ima-template { 915 type string; 916 description 917 "Name of the template used for event logs 918 for e.g. ima, ima-ng, ima-sig"; 919 } 920 leaf filename-hint { 921 type string; 922 description 923 "File that was measured"; 924 } 925 leaf filedata-hash { 926 type binary; 927 description 928 "Hash of filedata as updated based upon the 929 filedata-hash-algorithm"; 930 } 931 leaf filedata-hash-algorithm { 932 type string; 933 description 934 "Algorithm used for filedata-hash"; 935 } 936 leaf template-hash-algorithm { 937 type string; 938 description 939 "Algorithm used for template-hash"; 940 } 941 leaf template-hash { 942 type binary; 943 description 944 "hash(filedata-hash, filename-hint)"; 945 } 946 leaf pcr-index { 947 type pcr; 948 description 949 "Defines the PCR index that this event extended"; 950 } 951 leaf signature { 952 type binary; 953 description 954 "Digital file signature which provides a 955 fingerprint for the file being measured."; 956 } 957 } 959 grouping ima-event-log { 960 description 961 "Measurement log created by IMA."; 962 list ima-event-entry { 963 key "event-number"; 964 description 965 "Ordered list of ima event logs by event-number"; 966 uses ima-event; 967 } 968 } 970 grouping network-equipment-boot-event-log { 971 description 972 "Measurement log created by Network Equipment Boot. The Network 973 Equipment Boot format is identical to the IMA format. In 974 contrast to the IMA log, the Network Equipment Boot log 975 includes every measurable event from an Attester, including 976 the boot stages of BIOS, Bootloader, etc. In essence, the scope 977 of events represented in this format combines the scope of BIOS 978 events and IMA events."; 979 list boot-event-entry { 980 key "event-number"; 981 description 982 "Ordered list of Network Equipment Boot event logs 983 by event-number, using the IMA event format."; 984 uses ima-event; 985 } 986 } 987 grouping event-logs { 988 description 989 "A selector for the log and its type."; 990 choice attested_event_log_type { 991 mandatory true; 992 description 993 "Event log type determines the event logs content."; 994 case bios { 995 if-feature "bios"; 996 description 997 "BIOS/UEFI event logs"; 998 container bios-event-logs { 999 description 1000 "BIOS/UEFI event logs"; 1001 uses bios-event-log; 1002 } 1003 } 1004 case ima { 1005 if-feature "ima"; 1006 description 1007 "IMA event logs."; 1008 container ima-event-logs { 1009 description 1010 "IMA event logs."; 1011 uses ima-event-log; 1012 } 1013 } 1014 case netequip_boot { 1015 if-feature "netequip_boot"; 1016 description 1017 "Network Equipment Boot event logs"; 1018 container boot-event-logs { 1019 description 1020 "Network equipment boot event logs."; 1021 uses network-equipment-boot-event-log; 1022 } 1023 } 1024 } 1025 } 1027 /**********************/ 1028 /* RPC operations */ 1029 /**********************/ 1031 rpc tpm12-challenge-response-attestation { 1032 if-feature "taa:tpm12"; 1033 description 1034 "This RPC accepts the input for TSS TPM 1.2 commands made to the 1035 attesting device."; 1036 input { 1037 container tpm12-attestation-challenge { 1038 description 1039 "This container includes every information element defined 1040 in the reference challenge-response interaction model for 1041 remote attestation. Corresponding values are based on 1042 TPM 1.2 structure definitions"; 1043 uses tpm12-pcr-selection; 1044 uses nonce; 1045 leaf-list certificate-name { 1046 if-feature "tpm:mtpm"; 1047 type certificate-name-ref; 1048 must "/tpm:rats-support-structures/tpm:tpms" 1049 + "/tpm:tpm[tpm:firmware-version='taa:tpm12']" 1050 + "/tpm:certificates/" 1051 + "/tpm:certificate[name=current()]" { 1052 error-message "Not an available TPM1.2 AIK certificate."; 1053 } 1054 description 1055 "When populated, the RPC will only get a Quote for the 1056 TPMs associated with these certificate(s)."; 1057 } 1058 } 1059 } 1060 output { 1061 list tpm12-attestation-response { 1062 unique "certificate-name"; 1063 description 1064 "The binary output of TPM 1.2 TPM_Quote/TPM_Quote2, including 1065 the PCR selection and other associated attestation evidence 1066 metadata"; 1067 uses certificate-name-ref { 1068 description 1069 "Certificate associated with this tpm12-attestation."; 1070 } 1071 uses tpm12-attestation; 1072 } 1073 } 1074 } 1076 rpc tpm20-challenge-response-attestation { 1077 if-feature "taa:tpm20"; 1078 description 1079 "This RPC accepts the input for TSS TPM 2.0 commands of the 1080 managed device. ComponentIndex from the hardware manager YANG 1081 module is used to refer to dedicated TPM in composite devices, 1082 e.g. smart NICs, is not covered."; 1084 input { 1085 container tpm20-attestation-challenge { 1086 description 1087 "This container includes every information element defined 1088 in the reference challenge-response interaction model for 1089 remote attestation. Corresponding values are based on 1090 TPM 2.0 structure definitions"; 1091 uses nonce; 1092 uses tpm20-pcr-selection; 1093 leaf-list certificate-name { 1094 if-feature "tpm:mtpm"; 1095 type certificate-name-ref; 1096 must "/tpm:rats-support-structures/tpm:tpms" 1097 + "/tpm:tpm[tpm:firmware-version='taa:tpm20']" 1098 + "/tpm:certificates/" 1099 + "/tpm:certificate[name=current()]" { 1100 error-message "Not an available TPM2.0 AIK certificate."; 1101 } 1102 description 1103 "When populated, the RPC will only get a Quote for the 1104 TPMs associated with the certificates."; 1105 } 1106 } 1107 } 1108 output { 1109 list tpm20-attestation-response { 1110 unique "certificate-name"; 1111 description 1112 "The binary output of TPM2b_Quote from one TPM of the 1113 node which identified by node-id. An TPMS_ATTEST structure 1114 including a length, encapsulated in a signature"; 1115 uses certificate-name-ref { 1116 description 1117 "Certificate associated with this tpm20-attestation."; 1118 } 1119 uses tpm20-attestation; 1120 } 1121 } 1122 } 1124 rpc log-retrieval { 1125 description 1126 "Logs Entries are either identified via indices or via providing 1127 the last line received. The number of lines returned can be 1128 limited. The type of log is a choice that can be augmented."; 1129 input { 1130 uses log-identifier; 1131 list log-selector { 1132 description 1133 "Only log entries which meet all the selection criteria provided 1134 are to be returned by the RPC output."; 1135 leaf-list name { 1136 type string; 1137 description 1138 "Name of one or more unique TPMs on a device. If this object 1139 exists, a selection should pull only the objects related to 1140 these TPM(s). If it does not exist, all qualifying TPMs that 1141 are 'hardware-based' equals true on the device are selected."; 1142 } 1143 choice index-type { 1144 description 1145 "Last log entry received, log index number, or timestamp."; 1146 case last-entry { 1147 description 1148 "The last entry of the log already retrieved."; 1149 leaf last-entry-value { 1150 type binary; 1151 description 1152 "Content of a log event which matches 1:1 with a 1153 unique event record contained within the log. Log 1154 entries after this will be passed to the 1155 requester. Note: if log entry values are not unique, 1156 this MUST return an error."; 1157 } 1158 } 1159 case index { 1160 description 1161 "Numeric index of the last log entry retrieved, or 1162 zero."; 1163 leaf last-index-number { 1164 type uint64; 1165 description 1166 "The last numeric index number of a log entry. 1167 Zero means to start at the beginning of the log. 1168 Entries after this will be passed to the 1169 requester."; 1170 } 1171 } 1172 case timestamp { 1173 leaf timestamp { 1174 type yang:date-and-time; 1175 description 1176 "Timestamp from which to start the extraction. The 1177 next log entry after this timestamp is to 1178 be sent."; 1179 } 1180 description 1181 "Timestamp from which to start the extraction."; 1182 } 1183 } 1184 leaf log-entry-quantity { 1185 type uint16; 1186 description 1187 "The number of log entries to be returned. If omitted, it 1188 means all of them."; 1189 } 1190 } 1191 } 1192 output { 1193 container system-event-logs { 1194 description 1195 "The requested data of the measurement event logs"; 1196 list node-data { 1197 unique "name"; 1198 description 1199 "Event logs of a node in a distributed system 1200 identified by the node name"; 1201 uses tpm-name; 1202 uses node-uptime; 1203 container log-result { 1204 description 1205 "The requested entries of the corresponding log."; 1206 uses event-logs; 1207 } 1208 } 1209 } 1210 } 1211 } 1213 /**************************************/ 1214 /* Config & Oper accessible nodes */ 1215 /**************************************/ 1217 container rats-support-structures { 1218 description 1219 "The datastore definition enabling verifiers or relying 1220 parties to discover the information necessary to use the 1221 remote attestation RPCs appropriately."; 1222 container compute-nodes { 1223 if-feature "tpm:mtpm"; 1224 description 1225 "Holds the set of device subsystems/components in this 1226 composite device that support TPM operations."; 1227 list compute-node { 1228 key "node-id"; 1229 unique "node-name"; 1230 config false; 1231 min-elements 2; 1232 description 1233 "A component within this composite device which 1234 supports TPM operations."; 1235 leaf node-id { 1236 type string; 1237 description 1238 "ID of the compute node, such as Board Serial Number."; 1239 } 1240 leaf node-physical-index { 1241 if-feature "hw:entity-mib"; 1242 type int32 { 1243 range "1..2147483647"; 1244 } 1245 config false; 1246 description 1247 "The entPhysicalIndex for the compute node."; 1248 reference 1249 "RFC 6933: Entity MIB (Version 4) - entPhysicalIndex"; 1250 } 1251 leaf node-name { 1252 type string; 1253 description 1254 "Name of the compute node."; 1255 } 1256 leaf node-location { 1257 type string; 1258 description 1259 "Location of the compute node, such as slot number."; 1260 } 1261 } 1262 } 1263 container tpms { 1264 description 1265 "Holds the set of TPMs within an Attester."; 1266 list tpm { 1267 key "name"; 1268 unique "path"; 1269 description 1270 "A list of TPMs in this composite device that RATS 1271 can be conducted with."; 1272 uses tpm-name; 1273 leaf hardware-based { 1274 type boolean; 1275 config false; 1276 mandatory true; 1277 description 1278 "System generated indication of whether this is a 1279 hardware based TPM."; 1280 } 1281 leaf physical-index { 1282 if-feature "hw:entity-mib"; 1283 type int32 { 1284 range "1..2147483647"; 1285 } 1286 config false; 1287 description 1288 "The entPhysicalIndex for the TPM."; 1289 reference 1290 "RFC 6933: Entity MIB (Version 4) - entPhysicalIndex"; 1291 } 1292 leaf path { 1293 type string; 1294 config false; 1295 description 1296 "Device path to a unique TPM on a device. This can change 1297 across reboots."; 1298 } 1299 leaf compute-node { 1300 if-feature "tpm:mtpm"; 1301 type compute-node-ref; 1302 config false; 1303 mandatory true; 1304 description 1305 "Indicates the compute node measured by this TPM."; 1306 } 1307 leaf manufacturer { 1308 type string; 1309 config false; 1310 description 1311 "TPM manufacturer name."; 1312 } 1313 leaf firmware-version { 1314 type identityref { 1315 base taa:cryptoprocessor; 1316 } 1317 mandatory true; 1318 description 1319 "Identifies the cryptoprocessor API set supported. This 1320 is automatically configured by the device and should not 1321 be changed."; 1322 } 1323 uses tpm12-hash-algo { 1324 when "firmware-version = 'taa:tpm12'"; 1325 refine "tpm12-hash-algo" { 1326 description 1327 "The hash algorithm overwrites the default used for PCRs 1328 on this TPM1.2 compliant cryptoprocessor."; 1329 } 1330 } 1331 leaf-list tpm12-pcrs { 1332 when "../firmware-version = 'taa:tpm12'"; 1333 type pcr; 1334 description 1335 "The PCRs which may be extracted from this TPM1.2 1336 compliant cryptoprocessor."; 1337 } 1338 list tpm20-pcr-bank { 1339 when "../firmware-version = 'taa:tpm20'"; 1340 key "tpm20-hash-algo"; 1341 description 1342 "Specifies the list of PCRs that may be extracted for 1343 a specific Hash Algorithm on this TPM2 compliant 1344 cryptoprocessor. A bank is a set of PCRs which are 1345 extended using a particular hash algorithm."; 1346 reference 1347 "TPM2.0-Structures: 1348 https://www.trustedcomputinggroup.org/wp-content/uploads/ 1349 TPM-Rev-2.0-Part-2-Structures-01.38.pdf Section 10.9.7"; 1350 leaf tpm20-hash-algo { 1351 type identityref { 1352 base taa:hash; 1353 } 1354 must '/tpm:rats-support-structures' 1355 + '/tpm:attester-supported-algos' 1356 + '/tpm:tpm20-hash' { 1357 error-message "This platform does not support tpm20-hash-algo"; 1358 } 1359 description 1360 "The hash scheme actively being used to hash a 1361 one or more TPM2.0 PCRs."; 1362 } 1363 leaf-list pcr-index { 1364 type tpm:pcr; 1365 description 1366 "Defines what TPM2 PCRs are available to be extracted."; 1367 } 1368 } 1369 leaf status { 1370 type enumeration { 1371 enum operational { 1372 value 0; 1373 description 1374 "The TPM currently is running normally and 1375 is ready to accept and process TPM quotes."; 1376 reference 1377 "TPM2.0-Arch: 1378 https://trustedcomputinggroup.org/wp-content/uploads/ 1379 TCG_TPM2_r1p59_Part1_Architecture_pub.pdf 1380 Section 12"; 1381 } 1382 enum non-operational { 1383 value 1; 1384 description 1385 "TPM is in a state such as startup or shutdown which 1386 precludes the processing of TPM quotes."; 1387 } 1388 } 1389 config false; 1390 mandatory true; 1391 description 1392 "TPM chip self-test status."; 1393 } 1394 container certificates { 1395 description 1396 "The TPM's certificates, including EK certificates 1397 and Attestation Key certificates."; 1398 list certificate { 1399 key "name"; 1400 description 1401 "Three types of certificates can be accessed via 1402 this statement, including Initial Attestation 1403 Key Certificate, Local Attestation Key Certificate or 1404 Endorsement Key Certificate."; 1405 leaf name { 1406 type string; 1407 description 1408 "An arbitrary name uniquely identifying a certificate 1409 associated within key within a TPM."; 1410 } 1411 leaf keystore-ref { 1412 if-feature "ks:asymmetric-keys"; 1413 type leafref { 1414 path "/ks:keystore/ks:asymmetric-keys/ks:asymmetric-key" 1415 + "/ks:name"; 1416 } 1417 description 1418 "A reference to a specific certificate of an 1419 asymmetric key in the Keystore."; 1421 } 1422 leaf type { 1423 type enumeration { 1424 enum endorsement-certificate { 1425 value 0; 1426 description 1427 "Endorsement Key (EK) Certificate type."; 1428 reference 1429 "TPM2.0-Key: 1430 https://trustedcomputinggroup.org/wp-content/ 1431 uploads/TPM-2p0-Keys-for-Device-Identity- 1432 and-Attestation_v1_r12_pub10082021.pdf 1433 Section 3.11"; 1434 } 1435 enum initial-attestation-certificate { 1436 value 1; 1437 description 1438 "Initial Attestation key (IAK) Certificate type."; 1439 reference 1440 "TPM2.0-Key: 1441 https://trustedcomputinggroup.org/wp-content/ 1442 uploads/TPM-2p0-Keys-for-Device-Identity- 1443 and-Attestation_v1_r12_pub10082021.pdf 1444 Section 3.2"; 1445 } 1446 enum local-attestation-certificate { 1447 value 2; 1448 description 1449 "Local Attestation Key (LAK) Certificate type."; 1450 reference 1451 "TPM2.0-Key: 1452 https://trustedcomputinggroup.org/wp-content/ 1453 uploads/TPM-2p0-Keys-for-Device-Identity- 1454 and-Attestation_v1_r12_pub10082021.pdf 1455 Section 3.2"; 1456 } 1457 } 1458 description 1459 "Function supported by this certificate from within the 1460 TPM."; 1461 } 1462 } 1463 } 1464 } 1465 } 1466 container attester-supported-algos { 1467 description 1468 "Identifies which TPM algorithms are available for use on an 1469 attesting platform."; 1470 leaf-list tpm12-asymmetric-signing { 1471 when "../../tpm:tpms" 1472 + "/tpm:tpm[tpm:firmware-version='taa:tpm12']"; 1473 type identityref { 1474 base taa:asymmetric; 1475 } 1476 description 1477 "Platform Supported TPM12 asymmetric algorithms."; 1478 } 1479 leaf-list tpm12-hash { 1480 when "../../tpm:tpms" 1481 + "/tpm:tpm[tpm:firmware-version='taa:tpm12']"; 1482 type identityref { 1483 base taa:hash; 1484 } 1485 description 1486 "Platform supported TPM12 hash algorithms."; 1487 } 1488 leaf-list tpm20-asymmetric-signing { 1489 when "../../tpm:tpms" 1490 + "/tpm:tpm[tpm:firmware-version='taa:tpm20']"; 1491 type identityref { 1492 base taa:asymmetric; 1493 } 1494 description 1495 "Platform Supported TPM20 asymmetric algorithms."; 1496 } 1497 leaf-list tpm20-hash { 1498 when "../../tpm:tpms" 1499 + "/tpm:tpm[tpm:firmware-version='taa:tpm20']"; 1500 type identityref { 1501 base taa:hash; 1502 } 1503 description 1504 "Platform supported TPM20 hash algorithms."; 1505 } 1506 } 1507 } 1508 } 1509 1511 Figure 1 1513 2.1.2. 'ietf-tcg-algs' 1515 This document has encoded the TCG Algorithm definitions of 1516 [TCG-Algos], revision 1.32. By including this full table as a 1517 separate YANG file within this document, it is possible for other 1518 YANG models to leverage the contents of this model. Specific 1519 references to [RFC2104], [RFC8017], [ISO-IEC-9797-1], 1520 [ISO-IEC-9797-2], [ISO-IEC-10116], [ISO-IEC-10118-3], 1521 [ISO-IEC-14888-3], [ISO-IEC-15946-1], [ISO-IEC-18033-3], 1522 [IEEE-Std-1363-2000], [IEEE-Std-1363a-2004], [NIST-PUB-FIPS-202], 1523 [NIST-SP800-38C], [NIST-SP800-38D], [NIST-SP800-38F], 1524 [NIST-SP800-56A], [NIST-SP800-108], [bios-log], [ima-log], as well as 1525 Appendix A and Appendix B exist within the YANG Model. 1527 2.1.2.1. Features 1529 There are two types of features supported: 'TPM12' and 'TPM20'. 1530 Support for either of these features indicates that a cryptoprocessor 1531 supporting the corresponding type of TCG TPM API is present on an 1532 Attester. Most commonly, only one type of cryptoprocessor will be 1533 available on an Attester. 1535 2.1.2.2. Identities 1537 There are three types of identities in this model: 1539 1. Cryptographic functions supported by a TPM algorithm; these 1540 include: 'asymmetric', 'symmetric', 'hash', 'signing', 1541 'anonymous_signing', 'encryption_mode', 'method', and 1542 'object_type'. The definitions of each of these are in Table 2 1543 of [TCG-Algos]. 1545 2. API specifications for TPM types: 'tpm12' and 'tpm20' 1547 3. Specific algorithm types: Each algorithm type defines what 1548 cryptographic functions may be supported, and on which type of 1549 API specification. It is not required that an implementation of 1550 a specific TPM will support all algorithm types. The contents of 1551 each specific algorithm mirrors what is in Table 3 of 1552 [TCG-Algos]. 1554 2.1.2.3. YANG Module 1555 file "ietf-tcg-algs@2022-03-09.yang" 1556 module ietf-tcg-algs { 1557 yang-version 1.1; 1558 namespace "urn:ietf:params:xml:ns:yang:ietf-tcg-algs"; 1559 prefix taa; 1561 organization 1562 "IETF RATS (Remote ATtestation procedureS) Working Group"; 1563 contact 1564 "WG Web: 1565 WG List: 1566 Author: Eric Voit "; 1567 description 1568 "This module defines identities for asymmetric algorithms. 1570 Copyright (c) 2022 IETF Trust and the persons identified 1571 as authors of the code. All rights reserved. 1572 Redistribution and use in source and binary forms, with 1573 or without modification, is permitted pursuant to, and 1574 subject to the license terms contained in, the Simplified 1575 BSD License set forth in Section 4.c of the IETF Trust's 1576 Legal Provisions Relating to IETF Documents 1577 (https://trustee.ietf.org/license-info). 1578 This version of this YANG module is part of RFC XXXX 1579 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC 1580 itself for full legal notices. 1581 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1582 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 1583 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 1584 are to be interpreted as described in BCP 14 (RFC 2119) 1585 (RFC 8174) when, and only when, they appear in all 1586 capitals, as shown here."; 1588 revision 2022-03-09 { 1589 description 1590 "Initial version"; 1591 reference 1592 "RFC XXXX: A YANG Data Model for Challenge-Response-based Remote 1593 Attestation Procedures using TPMs"; 1594 } 1596 /*****************/ 1597 /* Features */ 1598 /*****************/ 1600 feature tpm12 { 1601 description 1602 "This feature indicates algorithm support for the TPM 1.2 API 1603 as per Section 4.8 of TPM1.2-Structures: 1604 TPM Main Part 2 TPM Structures 1605 https://trustedcomputinggroup.org/wp-content/uploads/TPM- 1606 Main-Part-2-TPM-Structures_v1.2_rev116_01032011.pdf"; 1607 } 1609 feature tpm20 { 1610 description 1611 "This feature indicates algorithm support for the TPM 2.0 API 1612 as per Section 11.4 of Trusted Platform Module Library 1613 Part 1: Architecture. See TPM2.0-Arch: 1614 https://trustedcomputinggroup.org/wp-content/uploads/ 1615 TCG_TPM2_r1p59_Part1_Architecture_pub.pdf"; 1616 } 1618 /*****************/ 1619 /* Identities */ 1620 /*****************/ 1622 identity asymmetric { 1623 description 1624 "A TCG recognized asymmetric algorithm with a public and 1625 private key."; 1626 reference 1627 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 2, 1628 https://trustedcomputinggroup.org/resource/ 1629 tcg-algorithm-registry/TCG-_Algorithm_Registry_r1p32_pub"; 1630 } 1632 identity symmetric { 1633 description 1634 "A TCG recognized symmetric algorithm with only a private key."; 1635 reference 1636 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 2"; 1637 } 1639 identity hash { 1640 description 1641 "A TCG recognized hash algorithm that compresses input data to 1642 a digest value or indicates a method that uses a hash."; 1643 reference 1644 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 2"; 1645 } 1647 identity signing { 1648 description 1649 "A TCG recognized signing algorithm"; 1650 reference 1651 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 2"; 1652 } 1654 identity anonymous_signing { 1655 description 1656 "A TCG recognized anonymous signing algorithm."; 1657 reference 1658 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 2"; 1659 } 1661 identity encryption_mode { 1662 description 1663 "A TCG recognized encryption mode."; 1664 reference 1665 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 2"; 1666 } 1668 identity method { 1669 description 1670 "A TCG recognized method such as a mask generation function."; 1671 reference 1672 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 2"; 1673 } 1675 identity object_type { 1676 description 1677 "A TCG recognized object type."; 1678 reference 1679 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 2"; 1680 } 1682 identity cryptoprocessor { 1683 description 1684 "Base identity identifying a crytoprocessor."; 1685 } 1687 identity tpm12 { 1688 if-feature "tpm12"; 1689 base cryptoprocessor; 1690 description 1691 "Supportable by a TPM1.2."; 1692 reference 1693 "TPM1.2-Structures: 1694 https://trustedcomputinggroup.org/wp-content/uploads/ 1695 TPM-Main-Part-2-TPM-Structures_v1.2_rev116_01032011.pdf 1696 TPM_ALGORITHM_ID values, Section 4.8"; 1697 } 1698 identity tpm20 { 1699 if-feature "tpm20"; 1700 base cryptoprocessor; 1701 description 1702 "Supportable by a TPM2."; 1703 reference 1704 "TPM2.0-Structures: 1705 https://trustedcomputinggroup.org/wp-content/uploads/ 1706 TPM-Rev-2.0-Part-2-Structures-01.38.pdf"; 1707 } 1709 identity TPM_ALG_RSA { 1710 if-feature "tpm12 or tpm20"; 1711 base tpm12; 1712 base tpm20; 1713 base asymmetric; 1714 base object_type; 1715 description 1716 "RSA algorithm"; 1717 reference 1718 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 1719 RFC 8017. ALG_ID: 0x0001"; 1720 } 1722 identity TPM_ALG_TDES { 1723 if-feature "tpm12"; 1724 base tpm12; 1725 base symmetric; 1726 description 1727 "Block cipher with various key sizes (Triple Data Encryption 1728 Algorithm, commonly called Triple Data Encryption Standard) 1729 Note: was banned in TPM1.2 v94"; 1730 reference 1731 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 1732 ISO/IEC 18033-3. ALG_ID: 0x0003"; 1733 } 1735 identity TPM_ALG_SHA1 { 1736 if-feature "tpm12 or tpm20"; 1737 base hash; 1738 base tpm12; 1739 base tpm20; 1740 description 1741 "SHA1 algorithm - Deprecated due to insufficient cryptographic 1742 protection. However, it is still useful for hash algorithms 1743 where protection is not required."; 1744 reference 1745 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 1746 ISO/IEC 10118-3. ALG_ID: 0x0004"; 1747 } 1749 identity TPM_ALG_HMAC { 1750 if-feature "tpm12 or tpm20"; 1751 base tpm12; 1752 base tpm20; 1753 base hash; 1754 base signing; 1755 description 1756 "Hash Message Authentication Code (HMAC) algorithm"; 1757 reference 1758 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3, 1759 ISO/IEC 9797-2 and RFC2104. ALG_ID: 0x0005"; 1760 } 1762 identity TPM_ALG_AES { 1763 if-feature "tpm12"; 1764 base tpm12; 1765 base symmetric; 1766 description 1767 "The AES algorithm with various key sizes"; 1768 reference 1769 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3, 1770 ISO/IEC 18033-3. ALG_ID: 0x0006"; 1771 } 1773 identity TPM_ALG_MGF1 { 1774 if-feature "tpm20"; 1775 base tpm20; 1776 base hash; 1777 base method; 1778 description 1779 "hash-based mask-generation function"; 1780 reference 1781 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3, 1782 IEEE Std 1363-2000 and IEEE Std 1363a-2004. 1783 ALG_ID: 0x0007"; 1784 } 1786 identity TPM_ALG_KEYEDHASH { 1787 if-feature "tpm20"; 1788 base tpm20; 1789 base hash; 1790 base object_type; 1791 description 1792 "An encryption or signing algorithm using a keyed hash. These 1793 may use XOR for encryption or an HMAC for signing and may 1794 also refer to a data object that is neither signing nor 1795 encrypting."; 1796 reference 1797 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3, 1798 ALG_ID: 0x0008"; 1799 } 1801 identity TPM_ALG_XOR { 1802 if-feature "tpm12 or tpm20"; 1803 base tpm12; 1804 base tpm20; 1805 base hash; 1806 base symmetric; 1807 description 1808 "The XOR encryption algorithm."; 1809 reference 1810 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3. 1811 ALG_ID: 0x000A"; 1812 } 1814 identity TPM_ALG_SHA256 { 1815 if-feature "tpm20"; 1816 base tpm20; 1817 base hash; 1818 description 1819 "The SHA 256 algorithm"; 1820 reference 1821 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 1822 ISO/IEC 10118-3. ALG_ID: 0x000B"; 1823 } 1825 identity TPM_ALG_SHA384 { 1826 if-feature "tpm20"; 1827 base tpm20; 1828 base hash; 1829 description 1830 "The SHA 384 algorithm"; 1831 reference 1832 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 1833 ISO/IEC 10118-3. ALG_ID: 0x000C"; 1834 } 1836 identity TPM_ALG_SHA512 { 1837 if-feature "tpm20"; 1838 base tpm20; 1839 base hash; 1840 description 1841 "The SHA 512 algorithm"; 1843 reference 1844 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 1845 ISO/IEC 10118-3. ALG_ID: 0x000D"; 1846 } 1848 identity TPM_ALG_NULL { 1849 if-feature "tpm20"; 1850 base tpm20; 1851 description 1852 "NULL algorithm"; 1853 reference 1854 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3. 1855 ALG_ID: 0x0010"; 1856 } 1858 identity TPM_ALG_SM3_256 { 1859 if-feature "tpm20"; 1860 base tpm20; 1861 base hash; 1862 description 1863 "The SM3 hash algorithm."; 1864 reference 1865 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 1866 ISO/IEC 10118-3:2018. ALG_ID: 0x0012"; 1867 } 1869 identity TPM_ALG_SM4 { 1870 if-feature "tpm20"; 1871 base tpm20; 1872 base symmetric; 1873 description 1874 "SM4 symmetric block cipher"; 1875 reference 1876 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3. 1877 ALG_ID: 0x0013"; 1878 } 1880 identity TPM_ALG_RSASSA { 1881 if-feature "tpm20"; 1882 base tpm20; 1883 base asymmetric; 1884 base signing; 1885 description 1886 "RFC 8017 Signature algorithm defined in section 8.2 1887 (RSASSAPKCS1-v1_5)"; 1888 reference 1889 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 1890 RFC 8017. ALG_ID: 0x0014"; 1892 } 1894 identity TPM_ALG_RSAES { 1895 if-feature "tpm20"; 1896 base tpm20; 1897 base asymmetric; 1898 base encryption_mode; 1899 description 1900 "RFC 8017 Signature algorithm defined in section 7.2 1901 (RSAES-PKCS1-v1_5)"; 1902 reference 1903 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 1904 RFC 8017. ALG_ID: 0x0015"; 1905 } 1907 identity TPM_ALG_RSAPSS { 1908 if-feature "tpm20"; 1909 base tpm20; 1910 base asymmetric; 1911 base signing; 1912 description 1913 "Padding algorithm defined in section 8.1 (RSASSA PSS)"; 1914 reference 1915 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 1916 RFC 8017. ALG_ID: 0x0016"; 1917 } 1919 identity TPM_ALG_OAEP { 1920 if-feature "tpm20"; 1921 base tpm20; 1922 base asymmetric; 1923 base encryption_mode; 1924 description 1925 "Padding algorithm defined in section 7.1 (RSASSA OAEP)"; 1926 reference 1927 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 1928 RFC 8017. ALG_ID: 0x0017"; 1929 } 1931 identity TPM_ALG_ECDSA { 1932 if-feature "tpm20"; 1933 base tpm20; 1934 base asymmetric; 1935 base signing; 1936 description 1937 "Signature algorithm using elliptic curve cryptography (ECC)"; 1938 reference 1939 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 1940 ISO/IEC 14888-3. ALG_ID: 0x0018"; 1941 } 1943 identity TPM_ALG_ECDH { 1944 if-feature "tpm20"; 1945 base tpm20; 1946 base asymmetric; 1947 base method; 1948 description 1949 "Secret sharing using ECC"; 1950 reference 1951 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 1952 NIST SP800-56A. ALG_ID: 0x0019"; 1953 } 1955 identity TPM_ALG_ECDAA { 1956 if-feature "tpm20"; 1957 base tpm20; 1958 base asymmetric; 1959 base signing; 1960 base anonymous_signing; 1961 description 1962 "Elliptic-curve based anonymous signing scheme"; 1963 reference 1964 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 1965 TCG TPM 2.0 library specification. ALG_ID: 0x001A"; 1966 } 1968 identity TPM_ALG_SM2 { 1969 if-feature "tpm20"; 1970 base tpm20; 1971 base asymmetric; 1972 base signing; 1973 base encryption_mode; 1974 base method; 1975 description 1976 "SM2 - depending on context, either an elliptic-curve based, 1977 signature algorithm, an encryption scheme, or a key exchange 1978 protocol"; 1979 reference 1980 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3. 1981 ALG_ID: 0x001B"; 1982 } 1984 identity TPM_ALG_ECSCHNORR { 1985 if-feature "tpm20"; 1986 base tpm20; 1987 base asymmetric; 1988 base signing; 1989 description 1990 "Elliptic-curve based Schnorr signature"; 1991 reference 1992 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3. 1993 ALG_ID: 0x001C"; 1994 } 1996 identity TPM_ALG_ECMQV { 1997 if-feature "tpm20"; 1998 base tpm20; 1999 base asymmetric; 2000 base method; 2001 description 2002 "Two-phase elliptic-curve key"; 2003 reference 2004 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 2005 NIST SP800-56A. ALG_ID: 0x001D"; 2006 } 2008 identity TPM_ALG_KDF1_SP800_56A { 2009 if-feature "tpm20"; 2010 base tpm20; 2011 base hash; 2012 base method; 2013 description 2014 "Concatenation key derivation function"; 2015 reference 2016 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 2017 NIST SP800-56A (approved alternative1) section 5.8.1. 2018 ALG_ID: 0x0020"; 2019 } 2021 identity TPM_ALG_KDF2 { 2022 if-feature "tpm20"; 2023 base tpm20; 2024 base hash; 2025 base method; 2026 description 2027 "Key derivation function"; 2028 reference 2029 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 2030 IEEE 1363a-2004 KDF2 section 13.2. ALG_ID: 0x0021"; 2031 } 2033 identity TPM_ALG_KDF1_SP800_108 { 2034 base TPM_ALG_KDF2; 2035 description 2036 "A key derivation method"; 2037 reference 2038 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 2039 NIST SP800-108 - Section 5.1 KDF. ALG_ID: 0x0022"; 2040 } 2042 identity TPM_ALG_ECC { 2043 if-feature "tpm20"; 2044 base tpm20; 2045 base asymmetric; 2046 base object_type; 2047 description 2048 "Prime field ECC"; 2049 reference 2050 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 2051 ISO/IEC 15946-1. ALG_ID: 0x0023"; 2052 } 2054 identity TPM_ALG_SYMCIPHER { 2055 if-feature "tpm20"; 2056 base tpm20; 2057 base symmetric; 2058 description 2059 "Object type for a symmetric block cipher"; 2060 reference 2061 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 2062 TCG TPM 2.0 library specification. ALG_ID: 0x0025"; 2063 } 2065 identity TPM_ALG_CAMELLIA { 2066 if-feature "tpm20"; 2067 base tpm20; 2068 base symmetric; 2069 description 2070 "The Camellia algorithm"; 2071 reference 2072 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 2073 ISO/IEC 18033-3. ALG_ID: 0x0026"; 2074 } 2076 identity TPM_ALG_SHA3_256 { 2077 if-feature "tpm20"; 2078 base tpm20; 2079 base hash; 2080 description 2081 "ISO/IEC 10118-3 - the SHA 256 algorithm"; 2082 reference 2083 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 2084 NIST PUB FIPS 202. ALG_ID: 0x0027"; 2085 } 2087 identity TPM_ALG_SHA3_384 { 2088 if-feature "tpm20"; 2089 base tpm20; 2090 base hash; 2091 description 2092 "The SHA 384 algorithm"; 2093 reference 2094 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 2095 NIST PUB FIPS 202. ALG_ID: 0x0028"; 2096 } 2098 identity TPM_ALG_SHA3_512 { 2099 if-feature "tpm20"; 2100 base tpm20; 2101 base hash; 2102 description 2103 "The SHA 512 algorithm"; 2104 reference 2105 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 2106 NIST PUB FIPS 202. ALG_ID: 0x0029"; 2107 } 2109 identity TPM_ALG_CMAC { 2110 if-feature "tpm20"; 2111 base tpm20; 2112 base symmetric; 2113 base signing; 2114 description 2115 "block Cipher-based Message Authentication Code (CMAC)"; 2116 reference 2117 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 2118 ISO/IEC 9797-1:2011 Algorithm 5. ALG_ID: 0x003F"; 2119 } 2121 identity TPM_ALG_CTR { 2122 if-feature "tpm20"; 2123 base tpm20; 2124 base symmetric; 2125 base encryption_mode; 2126 description 2127 "Counter mode"; 2128 reference 2129 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 2130 ISO/IEC 10116. ALG_ID: 0x0040"; 2131 } 2132 identity TPM_ALG_OFB { 2133 base tpm20; 2134 base symmetric; 2135 base encryption_mode; 2136 description 2137 "Output Feedback mode"; 2138 reference 2139 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 2140 ISO/IEC 10116. ALG_ID: 0x0041"; 2141 } 2143 identity TPM_ALG_CBC { 2144 if-feature "tpm20"; 2145 base tpm20; 2146 base symmetric; 2147 base encryption_mode; 2148 description 2149 "Cipher Block Chaining mode"; 2150 reference 2151 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 2152 ISO/IEC 10116. ALG_ID: 0x0042"; 2153 } 2155 identity TPM_ALG_CFB { 2156 if-feature "tpm20"; 2157 base tpm20; 2158 base symmetric; 2159 base encryption_mode; 2160 description 2161 "Cipher Feedback mode"; 2162 reference 2163 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 2164 ISO/IEC 10116. ALG_ID: 0x0043"; 2165 } 2167 identity TPM_ALG_ECB { 2168 if-feature "tpm20"; 2169 base tpm20; 2170 base symmetric; 2171 base encryption_mode; 2172 description 2173 "Electronic Codebook mode"; 2174 reference 2175 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 2176 ISO/IEC 10116. ALG_ID: 0x0044"; 2177 } 2179 identity TPM_ALG_CCM { 2180 if-feature "tpm20"; 2181 base tpm20; 2182 base symmetric; 2183 base signing; 2184 base encryption_mode; 2185 description 2186 "Counter with Cipher Block Chaining-Message Authentication 2187 Code (CCM)"; 2188 reference 2189 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 2190 NIST SP800-38C. ALG_ID: 0x0050"; 2191 } 2193 identity TPM_ALG_GCM { 2194 if-feature "tpm20"; 2195 base tpm20; 2196 base symmetric; 2197 base signing; 2198 base encryption_mode; 2199 description 2200 "Galois/Counter Mode (GCM)"; 2201 reference 2202 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 2203 NIST SP800-38D. ALG_ID: 0x0051"; 2204 } 2206 identity TPM_ALG_KW { 2207 if-feature "tpm20"; 2208 base tpm20; 2209 base symmetric; 2210 base signing; 2211 base encryption_mode; 2212 description 2213 "AES Key Wrap (KW)"; 2214 reference 2215 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 2216 NIST SP800-38F. ALG_ID: 0x0052"; 2217 } 2219 identity TPM_ALG_KWP { 2220 if-feature "tpm20"; 2221 base tpm20; 2222 base symmetric; 2223 base signing; 2224 base encryption_mode; 2225 description 2226 "AES Key Wrap with Padding (KWP)"; 2227 reference 2228 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 2229 NIST SP800-38F. ALG_ID: 0x0053"; 2230 } 2232 identity TPM_ALG_EAX { 2233 if-feature "tpm20"; 2234 base tpm20; 2235 base symmetric; 2236 base signing; 2237 base encryption_mode; 2238 description 2239 "Authenticated-Encryption Mode"; 2240 reference 2241 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 2242 NIST SP800-38F. ALG_ID: 0x0054"; 2243 } 2245 identity TPM_ALG_EDDSA { 2246 if-feature "tpm20"; 2247 base tpm20; 2248 base asymmetric; 2249 base signing; 2250 description 2251 "Edwards-curve Digital Signature Algorithm (PureEdDSA)"; 2252 reference 2253 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 2254 RFC 8032. ALG_ID: 0x0060"; 2255 } 2256 } 2257 2259 Note that not all cryptographic functions are required for use by 2260 "ietf-tpm-remote-attestation.yang". However the full definition of 2261 Table 3 of [TCG-Algos] will allow use by additional YANG 2262 specifications. 2264 3. IANA Considerations 2266 This document registers the following namespace URIs in the 2267 [xml-registry] as per [RFC3688]: 2269 URI: urn:ietf:params:xml:ns:yang:ietf-tpm-remote-attestation 2271 Registrant Contact: The IESG. 2273 XML: N/A; the requested URI is an XML namespace. 2275 URI: urn:ietf:params:xml:ns:yang:ietf-tcg-algs 2276 Registrant Contact: The IESG. 2278 XML: N/A; the requested URI is an XML namespace. 2280 This document registers the following YANG modules in the registry 2281 [yang-parameters] as per Section 14 of [RFC6020]: 2283 Name: ietf-tpm-remote-attestation 2285 Namespace: urn:ietf:params:xml:ns:yang:ietf-tpm-remote- 2286 attestation 2288 Prefix: tpm 2290 Reference: draft-ietf-rats-yang-tpm-charra (RFC form) 2292 Name: ietf-tcg-algs 2294 Namespace: urn:ietf:params:xml:ns:yang:ietf-tcg-algs 2296 Prefix: taa 2298 Reference: draft-ietf-rats-yang-tpm-charra (RFC form) 2300 4. Security Considerations 2302 The YANG module ietf-tpm-remote-attestation.yang specified in this 2303 document defines a schema for data that is designed to be accessed 2304 via network management protocols such as NETCONF [RFC6241] or 2305 RESTCONF [RFC8040]. The lowest NETCONF layer is the secure transport 2306 layer, and the mandatory-to-implement secure transport is Secure 2307 Shell (SSH) [RFC6242]. The lowest RESTCONF layer is HTTPS, and the 2308 mandatory-to-implement secure transport is TLS [RFC8446]. 2310 There are a number of data nodes defined in this YANG module that are 2311 writable/creatable/deletable (i.e., _config true_, which is the 2312 default). These data nodes may be considered sensitive or vulnerable 2313 in some network environments. Write operations (e.g., _edit-config_) 2314 to these data nodes without proper protection can have a negative 2315 effect on network operations. These are the subtrees and data nodes 2316 as well as their sensitivity/vulnerability: 2318 Container '/rats-support-structures/attester-supported-algos': 'tpm1 2319 2-asymmetric-signing', 'tpm12-hash', 'tpm20-asymmetric-signing', 2320 and 'tpm20-hash'. All could be populated with algorithms that are 2321 not supported by the underlying physical TPM installed by the 2322 equipment vendor. A vendor should restrict the ability to 2323 configure unsupported algorithms. 2325 Container: '/rats-support-structures/tpms': 'name': Although shown 2326 as 'rw', it is system generated. Therefore, it should not be 2327 possible for an operator to add or remove a TPM from the 2328 configuration. 2330 'tpm20-pcr-bank': It is possible to configure PCRs for extraction 2331 which are not being extended by system software. This could 2332 unnecessarily use TPM resources. 2334 'certificates': It is possible to provision a certificate which 2335 does not correspond to an Attestation Identity Key (AIK) within 2336 the TPM 1.2, or an Attestation Key (AK) within the TPM 2.0 2337 respectively. In such a case, calls to an RPC requesting this 2338 specific certificate could result in either no response or a 2339 response for an unexpected TPM. 2341 RPC 'tpm12-challenge-response-attestation': The receiver of the RPC 2342 response must verify that the certificate is for an active AIK, 2343 i.e., the certificate has been confirmed by a third party as being 2344 able to support Attestation on the targeted TPM 1.2. 2346 RPC 'tpm20-challenge-response-attestation': The receiver of the RPC 2347 response must verify that the certificate is for an active AK, 2348 i.e., the private key confirmation of the quote signature within 2349 the RPC response has been confirmed by a third party to belong to 2350 an entity legitimately able to perform Attestation on the targeted 2351 TPM 2.0. 2353 RPC 'log-retrieval': Requesting a large volume of logs from the 2354 attester could require significant system resources and create a 2355 denial of service. 2357 Information collected through the RPCs above could reveal that 2358 specific versions of software and configurations of endpoints that 2359 could identify vulnerabilities on those systems. Therefore, RPCs 2360 should be protected by NACM [RFC8341] with a default setting of deny- 2361 all to limit the extraction of attestation data by only authorized 2362 Verifiers. 2364 For the YANG module ietf-tcg-algs.yang, please use care when 2365 selecting specific algorithms. The introductory section of 2366 [TCG-Algos] highlights that some algorithms should be considered 2367 legacy, and recommends implementers and adopters diligently evaluate 2368 available information such as governmental, industrial, and academic 2369 research before selecting an algorithm for use. 2371 5. References 2372 5.1. Normative References 2374 [bios-log] "TCG PC Client Platform Firmware Profile Specification, 2375 Section 9.4.5.2", n.d., 2376 . 2380 [BIOS-Log-Event-Type] 2381 "TCG PC Client Platform Firmware Profile Specification", 2382 n.d., . 2385 [I-D.ietf-netconf-keystore] 2386 Watsen, K., "A YANG Data Model for a Keystore", Work in 2387 Progress, Internet-Draft, draft-ietf-netconf-keystore-24, 2388 7 March 2022, . 2391 [I-D.ietf-rats-architecture] 2392 Birkholz, H., Thaler, D., Richardson, M., Smith, N., and 2393 W. Pan, "Remote Attestation Procedures Architecture", Work 2394 in Progress, Internet-Draft, draft-ietf-rats-architecture- 2395 15, 8 February 2022, . 2398 [I-D.ietf-rats-tpm-based-network-device-attest] 2399 Fedorkow, G., Voit, E., and J. Fitzgerald-McKay, "TPM- 2400 based Network Device Remote Integrity Verification", Work 2401 in Progress, Internet-Draft, draft-ietf-rats-tpm-based- 2402 network-device-attest-13, 1 March 2022, 2403 . 2406 [IEEE-Std-1363-2000] 2407 "IEEE 1363-2000 - IEEE Standard Specifications for Public- 2408 Key Cryptography", n.d., 2409 . 2411 [IEEE-Std-1363a-2004] 2412 "1363a-2004 - IEEE Standard Specifications for Public-Key 2413 Cryptography - Amendment 1: Additional Techniques", n.d., 2414 . 2416 [ima-log] "Canonical Event Log Format, Section 4.3", n.d., 2417 . 2420 [ISO-IEC-10116] 2421 "ISO/IEC 10116:2017 - Information technology", n.d., 2422 . 2424 [ISO-IEC-10118-3] 2425 "Dedicated hash-functions - ISO/IEC 10118-3:2018", n.d., 2426 . 2428 [ISO-IEC-14888-3] 2429 "ISO/IEC 14888-3:2018 - Digital signatures with appendix", 2430 n.d., . 2432 [ISO-IEC-15946-1] 2433 "ISO/IEC 15946-1:2016 - Information technology", n.d., 2434 . 2436 [ISO-IEC-18033-3] 2437 "ISO/IEC 18033-3:2010 - Encryption algorithms", n.d., 2438 . 2440 [ISO-IEC-9797-1] 2441 "Message Authentication Codes (MACs) - ISO/IEC 2442 9797-1:2011", n.d., 2443 . 2445 [ISO-IEC-9797-2] 2446 "Message Authentication Codes (MACs) - ISO/IEC 2447 9797-2:2011", n.d., 2448 . 2450 [NIST-PUB-FIPS-202] 2451 "SHA-3 Standard: Permutation-Based Hash and Extendable- 2452 Output Functions", n.d., 2453 . 2456 [NIST-SP800-108] 2457 "Recommendation for Key Derivation Using Pseudorandom 2458 Functions", n.d., 2459 . 2462 [NIST-SP800-38C] 2463 "Recommendation for Block Cipher Modes of Operation: the 2464 CCM Mode for Authentication and Confidentiality", n.d., 2465 . 2468 [NIST-SP800-38D] 2469 "Recommendation for Block Cipher Modes of Operation: 2470 Galois/Counter Mode (GCM) and GMAC", n.d., 2471 . 2474 [NIST-SP800-38F] 2475 "Recommendation for Block Cipher Modes of Operation: 2476 Methods for Key Wrapping", n.d., 2477 . 2480 [NIST-SP800-56A] 2481 "Recommendation for Pair-Wise Key-Establishment Schemes 2482 Using Discrete Logarithm Cryptography", n.d., 2483 . 2486 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 2487 Hashing for Message Authentication", RFC 2104, 2488 DOI 10.17487/RFC2104, February 1997, 2489 . 2491 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2492 Requirement Levels", BCP 14, RFC 2119, 2493 DOI 10.17487/RFC2119, March 1997, 2494 . 2496 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2497 DOI 10.17487/RFC3688, January 2004, 2498 . 2500 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 2501 the Network Configuration Protocol (NETCONF)", RFC 6020, 2502 DOI 10.17487/RFC6020, October 2010, 2503 . 2505 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2506 and A. Bierman, Ed., "Network Configuration Protocol 2507 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2508 . 2510 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 2511 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 2512 . 2514 [RFC6933] Bierman, A., Romascanu, D., Quittek, J., and M. 2515 Chandramouli, "Entity MIB (Version 4)", RFC 6933, 2516 DOI 10.17487/RFC6933, May 2013, 2517 . 2519 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 2520 RFC 6991, DOI 10.17487/RFC6991, July 2013, 2521 . 2523 [RFC8017] Moriarty, K., Ed., Kaliski, B., Jonsson, J., and A. Rusch, 2524 "PKCS #1: RSA Cryptography Specifications Version 2.2", 2525 RFC 8017, DOI 10.17487/RFC8017, November 2016, 2526 . 2528 [RFC8032] Josefsson, S. and I. Liusvaara, "Edwards-Curve Digital 2529 Signature Algorithm (EdDSA)", RFC 8032, 2530 DOI 10.17487/RFC8032, January 2017, 2531 . 2533 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2534 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2535 . 2537 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2538 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2539 May 2017, . 2541 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 2542 Access Control Model", STD 91, RFC 8341, 2543 DOI 10.17487/RFC8341, March 2018, 2544 . 2546 [RFC8348] Bierman, A., Bjorklund, M., Dong, J., and D. Romascanu, "A 2547 YANG Data Model for Hardware Management", RFC 8348, 2548 DOI 10.17487/RFC8348, March 2018, 2549 . 2551 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 2552 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 2553 . 2555 [TCG-Algos] 2556 "TCG Algorithm Registry", n.d., 2557 . 2560 [TPM1.2] TCG, ., "TPM 1.2 Main Specification", 2 October 2003, 2561 . 2564 [TPM1.2-Commands] 2565 "TPM Main Part 3 Commands", n.d., 2566 . 2569 [TPM1.2-Structures] 2570 "TPM Main Part 2 TPM Structures", n.d., 2571 . 2574 [TPM2.0] TCG, ., "TPM 2.0 Library Specification", 15 March 2013, 2575 . 2578 [TPM2.0-Arch] 2579 "Trusted Platform Module Library - Part 1: Architecture", 2580 n.d., . 2584 [TPM2.0-Key] 2585 TCG, ., "TPM 2.0 Keys for Device Identity and Attestation, 2586 Rev12", 8 October 2021, 2587 . 2591 [TPM2.0-Structures] 2592 "Trusted Platform Module Library - Part 2: Structures", 2593 n.d., . 2596 [UEFI-Secure-Boot] 2597 "Unified Extensible Firmware Interface (UEFI) 2598 Specification Version 2.9 (March 2021), Section 32.1 2599 (Secure Boot)", n.d., 2600 . 2603 5.2. Informative References 2605 [I-D.ietf-rats-reference-interaction-models] 2606 Birkholz, H., Eckel, M., Pan, W., and E. Voit, "Reference 2607 Interaction Models for Remote Attestation Procedures", 2608 Work in Progress, Internet-Draft, draft-ietf-rats- 2609 reference-interaction-models-05, 26 January 2022, 2610 . 2613 [IMA-Kernel-Source] 2614 "Linux Integrity Measurement Architecture (IMA): Kernel 2615 Sourcecode", n.d., . 2619 [NIST-915121] 2620 "True Randomness Can't be Left to Chance: Why entropy is 2621 important for information security", n.d., 2622 . 2625 [xml-registry] 2626 "IETF XML Registry", n.d., 2627 . 2630 [yang-parameters] 2631 "YANG Parameters", n.d., 2632 . 2635 Appendix A. Integrity Measurement Architecture (IMA) 2637 IMA extends the principles of Measured Boot [TPM2.0-Arch] and Secure 2638 Boot [UEFI-Secure-Boot] to the Linux operating system, applying it to 2639 operating system applications and files. IMA has been part of the 2640 Linux integrity subsystem of the Linux kernel since 2009 (kernel 2641 version 2.6.30). The IMA mechanism represented by the YANG module in 2642 this specification is rooted in the kernel version 5.16 2643 [IMA-Kernel-Source]. IMA enables the protection of system integrity 2644 by collecting (commonly referred to as measuring) and storing 2645 measurements (called Claims in the context of IETF RATS) of files 2646 before execution so that these measurements can be used later, at 2647 system runtime, in remote attestation procedures. IMA acts in 2648 support of the appraisal of Evidence (which includes measurement 2649 Claims) by leveraging reference integrity measurements stored in 2650 extended file attributes. 2652 In support of the appraisal of Evidence, IMA maintains an ordered 2653 list of measurements in kernel-space, the Stored Measurement Log 2654 (SML), for all files that have been measured before execution since 2655 the operating system was started. Although IMA can be used without a 2656 TPM, it is typically used in conjunction with a TPM to anchor the 2657 integrity of the SML in a hardware-protected secure storage location, 2658 i.e., Platform Configuration Registers (PCRs) provided by TPMs. IMA 2659 provides the SML in both binary and ASCII representations in the 2660 Linux security file system _securityfs_ ("/sys/kernel/security/ 2661 ima/"). 2663 IMA templates define the format of the SML, i.e., which fields are 2664 included in a log record. Examples are file path, file hash, user 2665 ID, group ID, file signature, and extended file attributes. IMA 2666 comes with a set of predefined template formats and also allows a 2667 custom format, i.e., a format consisting of template fields supported 2668 by IMA. Template usage is typically determined by boot arguments 2669 passed to the kernel. Alternatively, the format can also be hard- 2670 compiled into custom kernels. IMA templates and fields are 2671 extensible in the kernel source code. As a result, more template 2672 fields can be added in the future. 2674 IMA policies define which files are measured using the IMA policy 2675 language. Built-in policies can be passed as boot arguments to the 2676 kernel. Custom IMA policies can be defined once during runtime or be 2677 hard-compiled into a custom kernel. If no policy is defined, no 2678 measurements are taken and IMA is effectively disabled. 2680 Appendix B. IMA for Network Equipment Boot Logs 2682 Network equipment can generally implement similar IMA-protected 2683 functions to generate measurements (Claims) about the boot process of 2684 a device and enable corresponding remote attestation. Network 2685 Equipment Boot Logs combine the measurement and logging of boot 2686 components and operating system components (executables and files) 2687 into a single log file in identical IMA format. 2689 During the boot process of the network device, i.e., from BIOS to the 2690 end of the operating system and user-space, all files executed during 2691 this process can be measured and logged in the order of their 2692 execution. When the Verifier initiates a remote attestation process 2693 (e.g., challenge-response remote attestation as defined in this 2694 document), the network equipment takes on the role of an Attester and 2695 can convey to the Verifier Claims that comprise the measurement log 2696 as well as the corresponding PCR values (Evidence) of a TPM. 2698 The verifier can appraise the integrity (compliance with the 2699 Reference Values) of each executed file by comparing its measured 2700 value with the Reference Value. Based on the execution order, the 2701 Verifier can compute a PCR reference value (by replaying the log) and 2702 compare it to the Measurement Log Claims obtained in conjunction with 2703 the PCR Evidence to assess their trustworthiness with respect to an 2704 intended operational state. 2706 Not only during the operating system loading phase, even during the 2707 BIOS boot phase, network equipment usually executes multiple 2708 components. With this measurement log mechanism, network equipment 2709 can take on the role of an Attester, proving to the Verifier the 2710 trustworthiness of its boot process. Using the measurement log, 2711 Verifiers can precisely identify mismatching log entries to infer 2712 potentially tampered components. 2714 This mechanism also supports scenarios that modify files on the 2715 Attester and are executed during the boot phase (e.g., updating/ 2716 patching) by simply updating the appropriate Reference Values in 2717 Reference Integrity Manifests that inform Verifiers about how an 2718 Attester is composed. 2720 Authors' Addresses 2722 Henk Birkholz 2723 Fraunhofer SIT 2724 Rheinstrasse 75 2725 64295 Darmstadt 2726 Germany 2728 Email: henk.birkholz@sit.fraunhofer.de 2730 Michael Eckel 2731 Fraunhofer SIT 2732 Rheinstrasse 75 2733 64295 Darmstadt 2734 Germany 2736 Email: michael.eckel@sit.fraunhofer.de 2738 Shwetha Bhandari 2739 ThoughtSpot 2741 Email: shwetha.bhandari@thoughtspot.com 2742 Eric Voit 2743 Cisco Systems 2745 Email: evoit@cisco.com 2747 Bill Sulzen 2748 Cisco Systems 2750 Email: bsulzen@cisco.com 2752 Liang Xia (Frank) 2753 Huawei Technologies 2754 101 Software Avenue, Yuhuatai District 2755 Nanjing 2756 Jiangsu, 210012 2757 China 2759 Email: Frank.Xialiang@huawei.com 2761 Tom Laffey 2762 Hewlett Packard Enterprise 2764 Email: tom.laffey@hpe.com 2766 Guy C. Fedorkow 2767 Juniper Networks 2768 10 Technology Park Drive 2769 Westford 2771 Email: gfedorkow@juniper.net