idnits 2.17.1 draft-ietf-rats-yang-tpm-charra-16.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 3 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 193 has weird spacing: '...te-name cer...' == Line 222 has weird spacing: '...r-index pcr...' == Line 306 has weird spacing: '...-number uin...' == Line 365 has weird spacing: '...version ide...' == Line 369 has weird spacing: '...sh-algo ide...' -- The document date (2 March 2022) is 779 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'RFC2014' is defined on line 2538, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'BIOS-Log-Event-Type' == Outdated reference: A later version (-35) exists of draft-ietf-netconf-keystore-23 == 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 7748 ** 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' == Outdated reference: A later version (-09) exists of draft-ietf-rats-reference-interaction-models-05 Summary: 6 errors (**), 0 flaws (~~), 11 warnings (==), 18 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: 3 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 2 March 2022 18 A YANG Data Model for Challenge-Response-based Remote Attestation 19 Procedures using TPMs 20 draft-ietf-rats-yang-tpm-charra-16 22 Abstract 24 This document defines YANG RPCs and a small number of configuration 25 nodes 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 3 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 Revised BSD License text as 65 described in Section 4.e of the Trust Legal Provisions and are 66 provided without warranty as described in the Revised 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' . . . . . . . . . . . . . . . . . . . 32 76 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 48 77 4. Security Considerations . . . . . . . . . . . . . . . . . . . 49 78 5. Change Log . . . . . . . . . . . . . . . . . . . . . . . . . 50 79 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 51 80 6.1. Normative References . . . . . . . . . . . . . . . . . . 51 81 6.2. Informative References . . . . . . . . . . . . . . . . . 57 82 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 57 84 1. Introduction 86 This document is based on the general terminology defined in the 87 [I-D.ietf-rats-architecture] and uses the operational context defined 88 in [I-D.ietf-rats-tpm-based-network-device-attest] as well as the 89 interaction model and information elements defined in 90 [I-D.ietf-rats-reference-interaction-models]. The currently 91 supported hardware security modules (HSMs) are the Trusted Platform 92 Modules (TPMs) [TPM1.2] and [TPM2.0] as specified by the Trusted 93 Computing Group (TCG). One or more TPMs embedded in the components 94 of a Composite Device are required in order to use the YANG module 95 defined in this document. A TPM is used as a root of trust for 96 reporting (RTR) in order to retrieve attestation Evidence from a 97 composite device (_TPM Quote_ primitive operation). Additionally, it 98 is used as a root of trust for storage (RTS) in order to retain 99 shielded secrets and store system measurements using a folding hash 100 function (_TPM PCR Extend_ primitive operation). 102 Specific terms imported from [I-D.ietf-rats-architecture] and used in 103 this document include: Attester, Composite Device, Evidence. 105 Specific terms imported from [TPM2.0-Key] and used in this document 106 include: Endorsement Key (EK), Initial Attestation Key (IAK), Local 107 Attestation Key (LAK). 109 1.1. Requirements notation 111 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 112 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 113 "OPTIONAL" in this document are to be interpreted as described in 114 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 115 capitals, as shown here. 117 2. The YANG Module for Basic Remote Attestation Procedures 119 One or more TPMs MUST be embedded in a Composite Device that provides 120 attestation evidence via the YANG module defined in this document. 121 The ietf-basic-remote-attestation YANG module enables a composite 122 device to take on the role of an Attester, in accordance with the 123 Remote Attestation Procedures (RATS) architecture 124 [I-D.ietf-rats-architecture], and the corresponding challenge- 125 response interaction model defined in the 126 [I-D.ietf-rats-reference-interaction-models] document. A fresh nonce 127 with an appropriate amount of entropy [NIST-915121] MUST be supplied 128 by the YANG client in order to enable a proof-of-freshness with 129 respect to the attestation Evidence provided by the Attester running 130 the YANG datastore. Further, this nonce is used to prevent replay 131 attacks. The method for communicating the relationship of each 132 individual TPM to specific measured component within the Composite 133 Device is out of the scope of this document. 135 2.1. YANG Modules 137 In this section the several YANG modules are defined. 139 2.1.1. 'ietf-tpm-remote-attestation' 141 This YANG module imports modules from [RFC6991] with prefix 'yang', 142 [RFC8348] with prefix 'hw', [I-D.ietf-netconf-keystore] with prefix 143 'ks', and 'ietf-tcg-algs.yang' Section 2.1.2.3 with prefix 'taa'. 144 Additionally references are made to [RFC8032], [RFC8017], [RFC6933], 145 [TPM1.2-Commands], [TPM2.0-Arch], [TPM2.0-Structures], [TPM2.0-Key], 146 [TPM1.2-Structures], [bios-log], [ima-log], [BIOS-Log-Event-Type] and 147 [netequip-boot-log]. 149 2.1.1.1. Features 151 This module supports the following features: 153 * 'TPMs': Indicates that multiple TPMs on the device can support 154 remote attestation. This feature is applicable in cases where 155 multiple line cards are present, each with its own TPM. 157 * 'bios': Indicates that the device supports the retrieval of BIOS/ 158 UEFI event logs. [bios-log] 160 * 'ima': Indicates that the device supports the retrieval of event 161 logs from the Linux Integrity Measurement Architecture (IMA). 162 [ima-log] 164 * 'netequip_boot': Indicates that the device supports the retrieval 165 of netequip boot event logs. [netequip-boot-log] 167 2.1.1.2. Identities 169 This module supports the following types of attestation event logs: 170 'bios', 'ima', and 'netequip_boot'. 172 2.1.1.3. Remote Procedure Calls (RPCs) 174 In the following, RPCs for both TPM 1.2 and TPM 2.0 attestation 175 procedures are defined. 177 2.1.1.3.1. 'tpm12-challenge-response-attestation' 179 This RPC allows a Verifier to request signed TPM PCRs (_TPM Quote_ 180 operation) from a TPM 1.2 compliant cryptoprocessor. Where the 181 feature 'TPMs' is active, and one or more 'certificate-name' is not 182 provided, all TPM 1.2 compliant cryptoprocessors will respond. A 183 YANG tree diagram of this RPC is as follows: 185 +---x tpm12-challenge-response-attestation {taa:TPM12}? 186 +---w input 187 | +---w tpm12-attestation-challenge 188 | +---w pcr-index* pcr 189 | +---w nonce-value binary 190 | +---w certificate-name* certificate-name-ref {tpm:TPMs}? 191 +--ro output 192 +--ro tpm12-attestation-response* [] 193 +--ro certificate-name certificate-name-ref 194 +--ro up-time? uint32 195 +--ro TPM_QUOTE2? binary 197 2.1.1.3.2. 'tpm20-challenge-response-attestation' 199 This RPC allows a Verifier to request signed TPM PCRs (_TPM Quote_ 200 operation) from a TPM 2.0 compliant cryptoprocessor. Where the 201 feature 'TPMs' is active, and one or more 'certificate-name' is not 202 provided, all TPM 2.0 compliant cryptoprocessors will respond. A 203 YANG tree diagram of this RPC is as follows: 205 +---x tpm20-challenge-response-attestation {taa:TPM20}? 206 +---w input 207 | +---w tpm20-attestation-challenge 208 | +---w nonce-value binary 209 | +---w tpm20-pcr-selection* [] 210 | | +---w TPM20-hash-algo? identityref 211 | | +---w pcr-index* tpm:pcr 212 | +---w certificate-name* certificate-name-ref {tpm:TPMs}? 213 +--ro output 214 +--ro tpm20-attestation-response* [] 215 +--ro certificate-name certificate-name-ref 216 +--ro TPMS_QUOTE_INFO binary 217 +--ro quote-signature? binary 218 +--ro up-time? uint32 219 +--ro unsigned-pcr-values* [] 220 +--ro TPM20-hash-algo? identityref 221 +--ro pcr-values* [pcr-index] 222 +--ro pcr-index pcr 223 +--ro pcr-value? binary 225 An example of an RPC challenge requesting PCRs 0-7 from a SHA-256 226 bank could look like the following: 228 229 230 xmlns="urn:ietf:params:xml:ns:yang:ietf-tpm-remote-attestation"> 231 232 (identifier of a TPM signature key with which the Verifier is 233 supposed to sign the attestation data) 234 235 236 0xe041307208d9f78f5b1bbecd19e2d152ad49de2fc5a7d8dbf769f6b8ffdeab9 237 238 239 241 TPM_ALG_SHA256 242 243 0 244 1 245 2 246 3 247 4 248 5 249 6 250 7 251 252 253 255 A successful response could be formatted as follows: 257 259 261 263 (instance of Certificate name in the Keystore) 264 265 266 (raw attestation data, i.e. the TPM quote; this includes 267 a composite digest of requested PCRs, the nonce, 268 and TPM 2.0 time information.) 269 270 271 (signature over attestation-data using the TPM key 272 identified by sig-key-id) 273 274 275 277 2.1.1.4. 'log-retrieval' 279 This RPC allows a Verifier to acquire the evidence which was extended 280 into specific TPM PCRs. A YANG tree diagram of this RPC is as 281 follows: 283 +---x log-retrieval 284 +---w input 285 | +---w log-selector* [] 286 | | +---w name* string 287 | | +---w (index-type)? 288 | | | +--:(last-entry) 289 | | | | +---w last-entry-value? binary 290 | | | +--:(index) 291 | | | | +---w last-index-number? uint64 292 | | | +--:(timestamp) 293 | | | +---w timestamp? yang:date-and-time 294 | | +---w log-entry-quantity? uint16 295 | +---w log-type identityref 296 +--ro output 297 +--ro system-event-logs 298 +--ro node-data* [] 299 +--ro name? string 300 +--ro up-time? uint32 301 +--ro log-result 302 +--ro (attested_event_log_type) 303 +--:(bios) {bios}? 304 | +--ro bios-event-logs 305 | +--ro bios-event-entry* [event-number] 306 | +--ro event-number uint32 307 | +--ro event-type? uint32 308 | +--ro pcr-index? pcr 309 | +--ro digest-list* [] 310 | | +--ro hash-algo? identityref 311 | | +--ro digest* binary 312 | +--ro event-size? uint32 313 | +--ro event-data* uint8 314 +--:(ima) {ima}? 315 | +--ro ima-event-logs 316 | +--ro ima-event-entry* [event-number] 317 | +--ro event-number uint64 318 | +--ro ima-template? string 319 | +--ro filename-hint? string 320 | +--ro filedata-hash? binary 321 | +--ro filedata-hash-algorithm? string 322 | +--ro template-hash-algorithm? string 323 | +--ro template-hash? binary 324 | +--ro pcr-index? pcr 325 | +--ro signature? binary 326 +--:(netequip_boot) {netequip_boot}? 327 +--ro boot-event-logs 328 +--ro boot-event-entry* [event-number] 329 +--ro event-number uint64 330 +--ro ima-template? string 331 +--ro filename-hint? string 332 +--ro filedata-hash? binary 333 +--ro filedata-hash-algorithm? string 334 +--ro template-hash-algorithm? string 335 +--ro template-hash? binary 336 +--ro pcr-index? pcr 337 +--ro signature? binary 339 2.1.1.5. Data Nodes 341 This section provides a high level description of the data nodes 342 containing the configuration and operational objects with the YANG 343 model. For more details, please see the YANG model itself in 344 Figure 1. 346 Container 'rats-support-structures': This houses the set of 347 information relating to a device's TPM(s). 349 Container 'tpms': Provides configuration and operational details for 350 each supported TPM, including the tpm-firmware-version, PCRs which 351 may be quoted, certificates which are associated with that TPM, 352 and the current operational status. Of note are the certificates 353 which are associated with that TPM. As a certificate is 354 associated with a particular TPM attestation key, knowledge of the 355 certificate allows a specific TPM to be identified. 357 +--rw tpms 358 +--rw tpm* [name] 359 +--rw name string 360 +--ro hardware-based? boolean 361 +--ro physical-index? int32 {hw:entity-mib}? 362 +--ro path? string 363 +--ro compute-node compute-node-ref {tpm:tpms}? 364 +--ro manufacturer? string 365 +--rw firmware-version identityref 366 +--rw tpm12-hash-algo? identityref 367 +--rw tpm12-pcrs* pcr 368 +--rw tpm20-pcr-bank* [tpm20-hash-algo] 369 | +--rw tpm20-hash-algo identityref 370 | +--rw pcr-index* tpm:pcr 371 +--ro status enumeration 372 +--rw certificates 373 +--rw certificate* [name] 374 +--rw name string 375 +--rw keystore-ref? leafref 376 +--rw type? enumeration 378 container 'attester-supported-algos' - Identifies which TCG hash 379 algorithms are available for use on the Attesting platform. This 380 allows an operator to limit algorithms available for use by RPCs to 381 just a desired set from the universe of all allowed hash algorithms 382 by the TCG. 384 +--rw attester-supported-algos 385 +--rw tpm12-asymmetric-signing* identityref 386 +--rw tpm12-hash* identityref 387 +--rw tpm20-asymmetric-signing* identityref 388 +--rw tpm20-hash* identityref 390 container 'compute-nodes' - When there is more than one TPM 391 supported, this container maintains the set of information related to 392 the compute node associated with a specific TPM. This allows each 393 specific TPM to identify to which 'compute-node' it belongs. 395 +--rw compute-nodes {tpm:TPMs}? 396 +--ro compute-node* [node-id] 397 +--ro node-id string 398 +--ro node-physical-index? int32 {hw:entity-mib}? 399 +--ro node-name? string 400 +--ro node-location? string 402 2.1.1.6. YANG Module 403 file "ietf-tpm-remote-attestation@2022-02-16.yang" 404 module ietf-tpm-remote-attestation { 405 namespace "urn:ietf:params:xml:ns:yang:ietf-tpm-remote-attestation"; 406 prefix tpm; 408 import ietf-yang-types { 409 prefix yang; 410 } 411 import ietf-hardware { 412 prefix hw; 413 } 414 import ietf-keystore { 415 prefix ks; 416 } 417 import ietf-tcg-algs { 418 prefix taa; 419 } 421 organization 422 "IETF RATS (Remote ATtestation procedureS) Working Group"; 423 contact 424 "WG Web : 425 WG List : 426 Author : Eric Voit 427 Author : Henk Birkholz 428 Author : Michael Eckel 429 Author : Shwetha Bhandari 430 Author : Bill Sulzen 431 Author : Liang Xia (Frank) 432 Author : Tom Laffey 433 Author : Guy Fedorkow "; 434 description 435 "A YANG module to enable a TPM 1.2 and TPM 2.0 based 436 remote attestation procedure using a challenge-response 437 interaction model and the TPM 1.2 and TPM 2.0 Quote 438 primitive operations. 440 Copyright (c) 2022 IETF Trust and the persons identified 441 as authors of the code. All rights reserved. 442 Redistribution and use in source and binary forms, with or 443 without modification, is permitted pursuant to, and subject to 444 the license terms contained in, the Simplified BSD License set 445 forth in Section 4.c of the IETF Trust's Legal Provisions 446 Relating to IETF Documents 447 (https://trustee.ietf.org/license-info). 449 This version of this YANG module is part of RFC XXXX 450 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC 451 itself for full legal notices. 453 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 454 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 455 'MAY', and 'OPTIONAL' in this document are to be interpreted as 456 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 457 they appear in all capitals, as shown here."; 459 revision 2022-03-02 { 460 description 461 "Initial version"; 462 reference 463 "RFC XXXX: A YANG Data Model for Challenge-Response-based Remote 464 Attestation Procedures using TPMs"; 465 } 467 /*****************/ 468 /* Features */ 469 /*****************/ 471 feature tpms { 472 description 473 "The device supports the remote attestation of multiple 474 TPM based cryptoprocessors."; 475 } 477 feature bios { 478 description 479 "The device supports the bios logs."; 480 reference 481 "bios-log: 482 https://trustedcomputinggroup.org/wp-content/uploads/ 483 PC-ClientSpecific_Platform_Profile_for_TPM_2p0_Systems_v51.pdf 484 Section 9.4.5.2"; 485 } 487 feature ima { 488 description 489 "The device supports Integrity Measurement Architecture logs. 490 Many variants of IMA logs exist in the deployment. Each encodes 491 the log entry contents as the specific measurements which get 492 hashed into a PCRs as Evidence. See the reference below for 493 one example of such an encoding."; 494 reference 495 "ima-log: 496 https://www.trustedcomputinggroup.org/wp-content/uploads/ 497 TCG_IWG_CEL_v1_r0p30_13feb2021.pdf Section 4.3"; 498 } 499 feature netequip_boot { 500 description 501 "The device supports the netequip_boot logs."; 502 reference 503 "netequip-boot-log: 504 https://www.kernel.org/doc/Documentation/ABI/testing/ima_policy"; 505 } 507 /*****************/ 508 /* Typedefs */ 509 /*****************/ 511 typedef pcr { 512 type uint8 { 513 range "0..31"; 514 } 515 description 516 "Valid index number for a PCR. At this point 0-31 is viable."; 517 } 519 typedef compute-node-ref { 520 type leafref { 521 path "/tpm:rats-support-structures/tpm:compute-nodes" 522 + "/tpm:compute-node/tpm:node-name"; 523 } 524 description 525 "This type is used to reference a hardware node. It is quite 526 possible this leafref will eventually point to another YANG 527 module's node."; 528 } 530 typedef certificate-name-ref { 531 type leafref { 532 path "/tpm:rats-support-structures/tpm:tpms/tpm:tpm" 533 + "/tpm:certificates/tpm:certificate/tpm:name"; 534 } 535 description 536 "A type which allows identification of a TPM based certificate."; 537 } 539 /******************/ 540 /* Identities */ 541 /******************/ 543 identity attested_event_log_type { 544 description 545 "Base identity allowing categorization of the reasons why an 546 attested measurement has been taken on an Attester."; 548 } 550 identity ima { 551 base attested_event_log_type; 552 description 553 "An event type recorded in IMA."; 554 } 556 identity bios { 557 base attested_event_log_type; 558 description 559 "An event type associated with BIOS/UEFI."; 560 } 562 identity netequip_boot { 563 base attested_event_log_type; 564 description 565 "An event type associated with Network Equipment Boot."; 566 } 568 /*****************/ 569 /* Groupings */ 570 /*****************/ 572 grouping tpm20-hash-algo { 573 description 574 "The cryptographic algorithm used to hash the TPM2 PCRs. This 575 must be from the list of platform supported options."; 576 leaf tpm20-hash-algo { 577 type identityref { 578 base taa:hash; 579 } 580 must '/tpm:rats-support-structures/tpm:attester-supported-algos' 581 + '/tpm:tpm20-hash' { 582 error-message "This platform does not support tpm20-hash-algo"; 583 } 584 default "taa:TPM_ALG_SHA256"; 585 description 586 "The hash scheme that is used to hash a TPM1.2 PCR. This 587 must be one of those supported by a platform."; 588 } 589 } 591 grouping tpm12-hash-algo { 592 description 593 "The cryptographic algorithm used to hash the TPM1.2 PCRs."; 594 leaf tpm12-hash-algo { 595 type identityref { 596 base taa:hash; 597 } 598 must '/tpm:rats-support-structures/tpm:attester-supported-algos' 599 + '/tpm:tpm12-hash' { 600 error-message "This platform does not support tpm12-hash-algo"; 601 } 602 default "taa:TPM_ALG_SHA1"; 603 description 604 "The hash scheme that is used to hash a TPM1.2 PCR. This 605 MUST be one of those supported by a platform. This assumes 606 that an algorithm other than SHA1 can be supported on some 607 TPM1.2 cryptoprocessor variant."; 608 } 609 } 611 grouping nonce { 612 description 613 "A random number intended to be used once to show freshness 614 and to allow the detection of replay attacks."; 615 leaf nonce-value { 616 type binary; 617 mandatory true; 618 description 619 "A cryptographically generated random number which should 620 not be predictable prior to its issuance from a random 621 number generation function. The random number MUST be 622 derived from an entropy source external to the Attester. 624 Note that a nonce sent into a TPM will typically be 160 or 256 625 binary digits long. (This is 20 or 32 bytes.) So if fewer 626 binary are sent, this nonce object will be padded 627 with leading zeros any in Quotes returned from the TPM. 628 Additionally if more bytes are sent, the nonce will be trimmed 629 to the most significant binary digits."; 630 } 631 } 633 grouping tpm12-pcr-selection { 634 description 635 "A Verifier can request one or more PCR values using its 636 individually created Attestation Key Certificate (AC). 637 The corresponding selection filter is represented in this 638 grouping. 639 Requesting a PCR value that is not in scope of the AC used, 640 detailed exposure via error msg should be avoided."; 641 leaf-list pcr-index { 642 type pcr; 643 description 644 "The numbers/indexes of the PCRs. At the moment this is limited 645 to 32. In addition, any selection of PCRs MUST verify that 646 the set of PCRs requested are a subset the set of PCRs 647 exposed by in the leaf-list /tpm:rats-support-structures 648 /tpm:tpms/tpm:tpm[name=current()]/tpm:tpm12-pcrs"; 649 } 650 } 652 grouping tpm20-pcr-selection { 653 description 654 "A Verifier can acquire one or more PCR values, which are hashed 655 together in a TPM2B_DIGEST coming from the TPM2. The selection 656 list of desired PCRs and the Hash Algorithm is represented in 657 this grouping."; 658 list tpm20-pcr-selection { 659 unique "tpm20-hash-algo"; 660 description 661 "Specifies the list of PCRs and Hash Algorithms that can be 662 returned within a TPM2B_DIGEST."; 663 reference 664 "TPM2.0-Structures: 665 https://www.trustedcomputinggroup.org/wp-content/uploads/ 666 TPM-Rev-2.0-Part-2-Structures-01.38.pdf Section 10.9.7"; 667 uses tpm20-hash-algo; 668 leaf-list pcr-index { 669 type pcr; 670 must '/tpm:rats-support-structures/tpm:tpms' 671 + '/tpm:tpm[name = current()] and ' 672 + '/tpm:rats-support-structures/tpm:tpms/tpm:tpm' 673 + '/tpm:tpm20-pcr-bank[pcr-index = current()]' { 674 error-message "Acquiring this PCR index is not supported"; 675 } 676 description 677 "The numbers of the PCRs that which are being tracked 678 with a hash based on the tpm20-hash-algo. In addition, 679 any selection of PCRs MUST verify that the set of PCRs 680 requested are a subset the set of PCR indexes exposed 681 within /tpm:rats-support-structures/tpm:tpms 682 /tpm:tpm[name=current()]/tpm:tpm20-pcr-bank 683 /tpm:pcr-index"; 684 } 685 } 686 } 688 grouping certificate-name-ref { 689 description 690 "Identifies a certificate in a keystore."; 691 leaf certificate-name { 692 type certificate-name-ref; 693 mandatory true; 694 description 695 "Identifies a certificate in a keystore."; 696 } 697 } 699 grouping tpm-name { 700 description 701 "A unique TPM on a device."; 702 leaf name { 703 type string; 704 description 705 "Unique system generated name for a TPM on a device."; 706 } 707 } 709 grouping tpm-name-selector { 710 description 711 "One or more TPM on a device."; 712 leaf-list name { 713 type string; 714 config false; 715 description 716 "Name of one or more unique TPMs on a device. If this object 717 exists, a selection should pull only the objects related to 718 these TPM(s). If it does not exist, all qualifying TPMs that 719 are 'hardware-based' equals true on the device are selected."; 720 } 721 } 723 grouping node-uptime { 724 description 725 "Uptime in seconds of the node."; 726 leaf up-time { 727 type uint32; 728 description 729 "Uptime in seconds of this node reporting its data"; 730 } 731 } 733 grouping tpm12-attestation { 734 description 735 "Contains an instance of TPM1.2 style signed cryptoprocessor 736 measurements. It is supplemented by unsigned Attester 737 information."; 738 uses node-uptime; 739 leaf TPM_QUOTE2 { 740 type binary; 741 description 742 "Result of a TPM1.2 Quote2 operation. This includes PCRs, 743 signatures, locality, the provided nonce and other data which 744 can be further parsed to appraise the Attester."; 745 reference 746 "TPM1.2-Commands: 747 TPM1.2 commands rev116 July 2007, Section 16.5 748 https://trustedcomputinggroup.org/wp-content/uploads 749 /TPM-Main-Part-3-Commands_v1.2_rev116_01032011.pdf"; 750 } 751 } 753 grouping tpm20-attestation { 754 description 755 "Contains an instance of TPM2 style signed cryptoprocessor 756 measurements. It is supplemented by unsigned Attester 757 information."; 758 leaf TPMS_QUOTE_INFO { 759 type binary; 760 mandatory true; 761 description 762 "A hash of the latest PCR values (and the hash algorithm used) 763 which have been returned from a Verifier for the selected PCRs 764 and Hash Algorithms."; 765 reference 766 "TPM2.0-Structures: 767 https://www.trustedcomputinggroup.org/wp-content/uploads/ 768 TPM-Rev-2.0-Part-2-Structures-01.38.pdf Section 10.12.1"; 769 } 770 leaf quote-signature { 771 type binary; 772 description 773 "Quote signature returned by TPM Quote. The signature was 774 generated using the key associated with the 775 certificate 'name'."; 776 reference 777 "TPM2.0-Structures: 778 https://www.trustedcomputinggroup.org/wp-content/uploads/ 779 TPM-Rev-2.0-Part-2-Structures-01.38.pdf Section 11.2.1"; 780 } 781 uses node-uptime; 782 list unsigned-pcr-values { 783 description 784 "PCR values in each PCR bank. This might appear redundant with 785 the TPM2B_DIGEST, but that digest is calculated across multiple 786 PCRs. Having to verify across multiple PCRs does not 787 necessarily make it easy for a Verifier to appraise just the 788 minimum set of PCR information which has changed since the last 789 received TPM2B_DIGEST. Put another way, why should a Verifier 790 reconstruct the proper value of all PCR Quotes when only a 791 single PCR has changed? 792 To help this happen, if the Attester does know specific PCR 793 values, the Attester can provide these individual values via 794 'unsigned-pcr-values'. By comparing this information to the 795 what has previously been validated, it is possible for a 796 Verifier to confirm the Attester's signature while eliminating 797 significant processing. There should never be a result where 798 an unsigned PCR value is actually that that within a quote. 799 If there is a difference, a signed result which has been 800 verified from retrieved logs is considered definitive."; 801 uses tpm20-hash-algo; 802 list pcr-values { 803 key "pcr-index"; 804 description 805 "List of one PCR bank."; 806 leaf pcr-index { 807 type pcr; 808 description 809 "PCR index number."; 810 } 811 leaf pcr-value { 812 type binary; 813 description 814 "PCR value."; 815 reference 816 "TPM2.0-Structures: 817 https://www.trustedcomputinggroup.org/wp-content/uploads/ 818 TPM-Rev-2.0-Part-2-Structures-01.38.pdf Section 10.9.7"; 819 } 820 } 821 } 822 } 824 grouping log-identifier { 825 description 826 "Identifier for type of log to be retrieved."; 827 leaf log-type { 828 type identityref { 829 base attested_event_log_type; 830 } 831 mandatory true; 832 description 833 "The corresponding measurement log type identity."; 834 } 835 } 836 grouping boot-event-log { 837 description 838 "Defines a specific instance of an event log entry 839 and corresponding to the information used to 840 extend the PCR"; 841 leaf event-number { 842 type uint32; 843 description 844 "Unique event number of this event"; 845 } 846 leaf event-type { 847 type uint32; 848 description 849 "BIOS Log Event Type: 850 https://trustedcomputinggroup.org/wp-content/uploads/ 851 TCG_PCClient_PFP_r1p05_v23_pub.pdf Section 10.4.1"; 852 } 853 leaf pcr-index { 854 type pcr; 855 description 856 "Defines the PCR index that this event extended"; 857 } 858 list digest-list { 859 description 860 "Hash of event data"; 861 leaf hash-algo { 862 type identityref { 863 base taa:hash; 864 } 865 description 866 "The hash scheme that is used to compress the event data in 867 each of the leaf-list digest items."; 868 } 869 leaf-list digest { 870 type binary; 871 description 872 "The hash of the event data using the algorithm of the 873 'hash-algo' against 'event data'."; 874 } 875 } 876 leaf event-size { 877 type uint32; 878 description 879 "Size of the event data"; 880 } 881 leaf-list event-data { 882 type uint8; 883 description 884 "The event data size determined by event-size"; 885 } 886 } 887 grouping bios-event-log { 888 description 889 "Measurement log created by the BIOS/UEFI."; 890 list bios-event-entry { 891 key event-number; 892 description 893 "Ordered list of TCG described event log 894 that extended the PCRs in the order they 895 were logged"; 896 uses boot-event-log; 897 } 898 } 899 grouping ima-event { 900 description 901 "Defines an 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_r0p30_13feb2021.pdf Section 4.3"; 906 leaf event-number { 907 type uint64; 908 description 909 "Unique number for this event for sequencing"; 910 } 911 leaf ima-template { 912 type string; 913 description 914 "Name of the template used for event logs 915 for e.g. ima, ima-ng, ima-sig"; 916 } 917 leaf filename-hint { 918 type string; 919 description 920 "File that was measured"; 921 } 922 leaf filedata-hash { 923 type binary; 924 description 925 "Hash of filedata"; 926 } 927 leaf filedata-hash-algorithm { 928 type string; 929 description 930 "Algorithm used for filedata-hash"; 931 } 932 leaf template-hash-algorithm { 933 type string; 934 description 935 "Algorithm used for template-hash"; 936 } 937 leaf template-hash { 938 type binary; 939 description 940 "hash(filedata-hash, filename-hint)"; 941 } 942 leaf pcr-index { 943 type pcr; 944 description 945 "Defines the PCR index that this event extended"; 946 } 947 leaf signature { 948 type binary; 949 description 950 "The file signature"; 951 } 952 } 953 grouping ima-event-log { 954 description 955 "Measurement log created by IMA."; 956 list ima-event-entry { 957 key event-number; 958 description 959 "Ordered list of ima event logs by event-number"; 960 uses ima-event; 961 } 962 } 964 grouping network-equipment-boot-event-log { 965 description 966 "Measurement log created by Network Equipment Boot. The Network 967 Equipment Boot format is identical to the IMA format. In 968 contrast to the IMA log, the Network Equipment Boot log 969 includes every measurable event from an Attester, including 970 the boot stages of BIOS, Bootloader, etc. In essence, the scope 971 of events represented in this format combines the scope of BIOS 972 events and IMA events."; 973 list boot-event-entry { 974 key event-number; 975 description 976 "Ordered list of Network Equipment Boot event logs 977 by event-number, using the IMA event format."; 978 uses ima-event; 979 } 981 } 982 grouping event-logs { 983 description 984 "A selector for the log and its type."; 985 choice attested_event_log_type { 986 mandatory true; 987 description 988 "Event log type determines the event logs content."; 989 case bios { 990 if-feature "bios"; 991 description 992 "BIOS/UEFI event logs"; 993 container bios-event-logs { 994 description 995 "BIOS/UEFI event logs"; 996 uses bios-event-log; 997 } 998 } 999 case ima { 1000 if-feature "ima"; 1001 description 1002 "IMA event logs."; 1003 container ima-event-logs { 1004 description 1005 "IMA event logs."; 1006 uses ima-event-log; 1007 } 1008 } 1009 case netequip_boot { 1010 if-feature "netequip_boot"; 1011 description 1012 "Network Equipment Boot event logs"; 1013 container boot-event-logs { 1014 description 1015 "Network equipment boot event logs."; 1016 uses network-equipment-boot-event-log; 1017 } 1018 } 1019 } 1020 } 1022 /**********************/ 1023 /* RPC operations */ 1024 /**********************/ 1026 rpc tpm12-challenge-response-attestation { 1027 if-feature "taa:tpm12"; 1028 description 1029 "This RPC accepts the input for TSS TPM 1.2 commands made to the 1030 attesting device."; 1031 input { 1032 container tpm12-attestation-challenge { 1033 description 1034 "This container includes every information element defined 1035 in the reference challenge-response interaction model for 1036 remote attestation. Corresponding values are based on 1037 TPM 1.2 structure definitions"; 1038 uses tpm12-pcr-selection; 1039 uses nonce; 1040 leaf-list certificate-name { 1041 if-feature "tpm:tpms"; 1042 type certificate-name-ref; 1043 must "/tpm:rats-support-structures/tpm:tpms" 1044 + "/tpm:tpm[tpm:firmware-version='taa:tpm12']" 1045 + "/tpm:certificates/" 1046 + "/tpm:certificate[name=current()]" { 1047 error-message "Not an available TPM1.2 AIK certificate."; 1048 } 1049 description 1050 "When populated, the RPC will only get a Quote for the 1051 TPMs associated with these certificate(s)."; 1052 } 1053 } 1054 } 1055 output { 1056 list tpm12-attestation-response { 1057 unique "certificate-name"; 1058 description 1059 "The binary output of TPM 1.2 TPM_Quote/TPM_Quote2, including 1060 the PCR selection and other associated attestation evidence 1061 metadata"; 1062 uses certificate-name-ref { 1063 description 1064 "Certificate associated with this tpm12-attestation."; 1065 } 1066 uses tpm12-attestation; 1067 } 1068 } 1069 } 1071 rpc tpm20-challenge-response-attestation { 1072 if-feature "taa:tpm20"; 1073 description 1074 "This RPC accepts the input for TSS TPM 2.0 commands of the 1075 managed device. ComponentIndex from the hardware manager YANG 1076 module to refer to dedicated TPM in composite devices, 1077 e.g. smart NICs, is still a TODO."; 1078 input { 1079 container tpm20-attestation-challenge { 1080 description 1081 "This container includes every information element defined 1082 in the reference challenge-response interaction model for 1083 remote attestation. Corresponding values are based on 1084 TPM 2.0 structure definitions"; 1085 uses nonce; 1086 uses tpm20-pcr-selection; 1087 leaf-list certificate-name { 1088 if-feature "tpm:tpms"; 1089 type certificate-name-ref; 1090 must "/tpm:rats-support-structures/tpm:tpms" 1091 + "/tpm:tpm[tpm:firmware-version='taa:tpm20']" 1092 + "/tpm:certificates/" 1093 + "/tpm:certificate[name=current()]" { 1094 error-message "Not an available TPM2.0 AIK certificate."; 1095 } 1096 description 1097 "When populated, the RPC will only get a Quote for the 1098 TPMs associated with the certificates."; 1099 } 1100 } 1101 } 1102 output { 1103 list tpm20-attestation-response { 1104 unique "certificate-name"; 1105 description 1106 "The binary output of TPM2b_Quote in one TPM chip of the 1107 node which identified by node-id. An TPMS_ATTEST structure 1108 including a length, encapsulated in a signature"; 1109 uses certificate-name-ref { 1110 description 1111 "Certificate associated with this tpm20-attestation."; 1112 } 1113 uses tpm20-attestation; 1114 } 1115 } 1116 } 1118 rpc log-retrieval { 1119 description 1120 "Logs Entries are either identified via indices or via providing 1121 the last line received. The number of lines returned can be 1122 limited. The type of log is a choice that can be augmented."; 1123 input { 1124 list log-selector { 1125 description 1126 "Selection of log entries to be reported."; 1127 uses tpm-name-selector; 1128 choice index-type { 1129 description 1130 "Last log entry received, log index number, or timestamp."; 1131 case last-entry { 1132 description 1133 "The last entry of the log already retrieved."; 1134 leaf last-entry-value { 1135 type binary; 1136 description 1137 "Content of an log event which matches 1:1 with a 1138 unique event record contained within the log. Log 1139 entries subsequent to this will be passed to the 1140 requester. Note: if log entry values are not unique, 1141 this MUST return an error."; 1142 } 1143 } 1144 case index { 1145 description 1146 "Numeric index of the last log entry retrieved, or 1147 zero."; 1148 leaf last-index-number { 1149 type uint64; 1150 description 1151 "The last numeric index number of a log entry. 1152 Zero means to start at the beginning of the log. 1153 Entries subsequent to this will be passed to the 1154 requester."; 1155 } 1156 } 1157 case timestamp { 1158 leaf timestamp { 1159 type yang:date-and-time; 1160 description 1161 "Timestamp from which to start the extraction. The 1162 next log entry subsequent to this timestamp is to 1163 be sent."; 1164 } 1165 description 1166 "Timestamp from which to start the extraction."; 1167 } 1168 } 1169 leaf log-entry-quantity { 1170 type uint16; 1171 description 1172 "The number of log entries to be returned. If omitted, it 1173 means all of them."; 1174 } 1175 } 1176 uses log-identifier; 1177 } 1178 output { 1179 container system-event-logs { 1180 description 1181 "The requested data of the measurement event logs"; 1182 list node-data { 1183 unique "name"; 1184 description 1185 "Event logs of a node in a distributed system 1186 identified by the node name"; 1187 uses tpm-name; 1188 uses node-uptime; 1189 container log-result { 1190 description 1191 "The requested entries of the corresponding log."; 1192 uses event-logs; 1193 } 1194 } 1195 } 1196 } 1197 } 1199 /**************************************/ 1200 /* Config & Oper accessible nodes */ 1201 /**************************************/ 1203 container rats-support-structures { 1204 description 1205 "The datastore definition enabling verifiers or relying 1206 parties to discover the information necessary to use the 1207 remote attestation RPCs appropriately."; 1208 container compute-nodes { 1209 if-feature "tpm:tpms"; 1210 description 1211 "Holds the set device subsystems/components in this composite 1212 device that support TPM operations."; 1213 list compute-node { 1214 key "node-id"; 1215 config false; 1216 min-elements 2; 1217 description 1218 "A component within this composite device which 1219 supports TPM operations."; 1220 leaf node-id { 1221 type string; 1222 description 1223 "ID of the compute node, such as Board Serial Number."; 1224 } 1225 leaf node-physical-index { 1226 if-feature "hw:entity-mib"; 1227 type int32 { 1228 range "1..2147483647"; 1229 } 1230 config false; 1231 description 1232 "The entPhysicalIndex for the compute node."; 1233 reference 1234 "RFC 6933: Entity MIB (Version 4) - entPhysicalIndex"; 1235 } 1236 leaf node-name { 1237 type string; 1238 description 1239 "Name of the compute node."; 1240 } 1241 leaf node-location { 1242 type string; 1243 description 1244 "Location of the compute node, such as slot number."; 1245 } 1246 } 1247 } 1248 container tpms { 1249 description 1250 "Holds the set of TPMs within an Attester."; 1251 list tpm { 1252 key "name"; 1253 unique "path"; 1254 description 1255 "A list of TPMs in this composite device that RATS 1256 can be conducted with."; 1257 uses tpm-name; 1258 leaf hardware-based { 1259 type boolean; 1260 config false; 1261 description 1262 "Answers the question: is this TPM is a hardware based 1263 TPM?"; 1264 } 1265 leaf physical-index { 1266 if-feature "hw:entity-mib"; 1267 type int32 { 1268 range "1..2147483647"; 1270 } 1271 config false; 1272 description 1273 "The entPhysicalIndex for the TPM."; 1274 reference 1275 "RFC 6933: Entity MIB (Version 4) - entPhysicalIndex"; 1276 } 1277 leaf path { 1278 type string; 1279 config false; 1280 description 1281 "Path to a unique TPM on a device. This can change across 1282 reboots."; 1283 } 1284 leaf compute-node { 1285 if-feature "tpm:tpms"; 1286 type compute-node-ref; 1287 config false; 1288 mandatory true; 1289 description 1290 "Indicates the compute node measured by this TPM."; 1291 } 1292 leaf manufacturer { 1293 type string; 1294 config false; 1295 description 1296 "TPM manufacturer name."; 1297 } 1298 leaf firmware-version { 1299 type identityref { 1300 base taa:cryptoprocessor; 1301 } 1302 mandatory true; 1303 description 1304 "Identifies the cryptoprocessor API set supported. This 1305 is automatically configured by the device and should not 1306 be changed."; 1307 } 1308 uses tpm12-hash-algo { 1309 when "firmware-version = 'taa:tpm12'"; 1310 refine "tpm12-hash-algo" { 1311 description 1312 "The hash algorithm overwrites the default used for PCRs 1313 on this TPM1.2 compliant cryptoprocessor."; 1314 } 1315 } 1316 leaf-list tpm12-pcrs { 1317 when "../firmware-version = 'taa:tpm12'"; 1318 type pcr; 1319 description 1320 "The PCRs which may be extracted from this TPM1.2 1321 compliant cryptoprocessor."; 1322 } 1323 list tpm20-pcr-bank { 1324 when "../firmware-version = 'taa:tpm20'"; 1325 key "tpm20-hash-algo"; 1326 description 1327 "Specifies the list of PCRs that may be extracted for 1328 a specific Hash Algorithm on this TPM2 compliant 1329 cryptoprocessor. A bank is a set of PCRs which are 1330 extended using a particular hash algorithm."; 1331 reference 1332 "TPM2.0-Structures: 1333 https://www.trustedcomputinggroup.org/wp-content/uploads/ 1334 TPM-Rev-2.0-Part-2-Structures-01.38.pdf Section 10.9.7"; 1335 leaf tpm20-hash-algo { 1336 type identityref { 1337 base taa:hash; 1338 } 1339 must '/tpm:rats-support-structures' 1340 + '/tpm:attester-supported-algos' 1341 + '/tpm:tpm20-hash' { 1342 error-message 1343 "This platform does not support tpm20-hash-algo"; 1344 } 1345 description 1346 "The hash scheme actively being used to hash a 1347 one or more TPM2.0 PCRs."; 1348 } 1349 leaf-list pcr-index { 1350 type tpm:pcr; 1351 description 1352 "Defines what TPM2 PCRs are available to be extracted."; 1353 } 1354 } 1355 leaf status { 1356 type enumeration { 1357 enum operational { 1358 value 0; 1359 description 1360 "The TPM currently is currently running normally and 1361 is ready to accept and process TPM quotes."; 1362 reference 1363 "TPM2.0-Arch: 1364 TPM-Rev-2.0-Part-1-Architecture-01.07-2014-03-13.pdf 1365 Section 12"; 1367 } 1368 enum non-operational { 1369 value 1; 1370 description 1371 "TPM is in a state such as startup or shutdown which 1372 precludes the processing of TPM quotes."; 1373 } 1374 } 1375 config false; 1376 mandatory true; 1377 description 1378 "TPM chip self-test status."; 1379 } 1380 container certificates { 1381 description 1382 "The TPM's certificates, including EK certificates 1383 and AK certificates."; 1384 list certificate { 1385 key "name"; 1386 description 1387 "Three types of certificates can be accessed via 1388 this statement, including Initial Attestation 1389 Key Certificate, Local Attestation Key Certificate or 1390 Endorsement Key Certificate."; 1391 leaf name { 1392 type string; 1393 description 1394 "An arbitrary name uniquely identifying a certificate 1395 associated within key within a TPM."; 1396 } 1397 leaf keystore-ref { 1398 type leafref { 1399 path "/ks:keystore/ks:asymmetric-keys/ks:asymmetric-key" 1400 + "/ks:certificates/ks:certificate/ks:name"; 1401 } 1402 description 1403 "A reference to a specific certificate of an 1404 asymmetric key in the Keystore."; 1405 } 1406 leaf type { 1407 type enumeration { 1408 enum endorsement-certificate { 1409 value 0; 1410 description 1411 "Endorsement Key (EK) Certificate type."; 1412 reference 1413 "TPM2.0-Key: 1414 https://trustedcomputinggroup.org/wp-content/ 1415 uploads/TCG_IWG_DevID_v1r2_02dec2020.pdf 1416 Section 3.11"; 1417 } 1418 enum initial-attestation-certificate { 1419 value 1; 1420 description 1421 "Initial Attestation key (IAK) Certificate type."; 1422 reference 1423 "TPM2.0-Key: 1424 https://trustedcomputinggroup.org/wp-content/ 1425 uploads/TCG_IWG_DevID_v1r2_02dec2020.pdf 1426 Section 3.2"; 1427 } 1428 enum local-attestation-certificate { 1429 value 2; 1430 description 1431 "Local Attestation Key (LAK) Certificate type."; 1432 reference 1433 "TPM2.0-Key: 1434 https://trustedcomputinggroup.org/wp-content/ 1435 uploads/TCG_IWG_DevID_v1r2_02dec2020.pdf 1436 Section 3.2"; 1437 } 1438 } 1439 description 1440 "Function supported by this certificate from within the 1441 TPM."; 1442 } 1443 } 1444 } 1445 } 1446 } 1447 container attester-supported-algos { 1448 description 1449 "Identifies which TPM algorithms are available for use on an 1450 attesting platform."; 1451 leaf-list tpm12-asymmetric-signing { 1452 when "../../tpm:tpms" 1453 + "/tpm:tpm[tpm:firmware-version='taa:tpm12']"; 1454 type identityref { 1455 base taa:asymmetric; 1456 } 1457 description 1458 "Platform Supported TPM12 asymmetric algorithms."; 1459 } 1460 leaf-list tpm12-hash { 1461 when "../../tpm:tpms" 1462 + "/tpm:tpm[tpm:firmware-version='taa:tpm12']"; 1464 type identityref { 1465 base taa:hash; 1466 } 1467 description 1468 "Platform supported TPM12 hash algorithms."; 1469 } 1470 leaf-list tpm20-asymmetric-signing { 1471 when "../../tpm:tpms" 1472 + "/tpm:tpm[tpm:firmware-version='taa:tpm20']"; 1473 type identityref { 1474 base taa:asymmetric; 1475 } 1476 description 1477 "Platform Supported TPM20 asymmetric algorithms."; 1478 } 1479 leaf-list tpm20-hash { 1480 when "../../tpm:tpms" 1481 + "/tpm:tpm[tpm:firmware-version='taa:tpm20']"; 1482 type identityref { 1483 base taa:hash; 1484 } 1485 description 1486 "Platform supported TPM20 hash algorithms."; 1487 } 1488 } 1489 } 1490 } 1491 1493 Figure 1 1495 2.1.2. 'ietf-tcg-algs' 1497 This document has encoded the TCG Algorithm definitions of 1498 [TCG-Algos], revision 1.32. By including this full table as a 1499 separate YANG file within this document, it is possible for other 1500 YANG models to leverage the contents of this model. Specific 1501 references to [RFC7748], [ISO-IEC-9797-1], [ISO-IEC-9797-2], 1502 [ISO-IEC-10116], [ISO-IEC-10118-3], [ISO-IEC-14888-3], 1503 [ISO-IEC-15946-1], [ISO-IEC-18033-3], [IEEE-Std-1363-2000], 1504 [IEEE-Std-1363a-2004], [NIST-PUB-FIPS-202], [NIST-SP800-38C], 1505 [NIST-SP800-38D], [NIST-SP800-38F], [NIST-SP800-56A], 1506 [NIST-SP800-108], [bios-log], [ima-log], and [netequip-boot-log] 1507 exist within the YANG Model. 1509 2.1.2.1. Features 1511 There are two types of features supported: 'TPM12' and 'TPM20'. 1512 Support for either of these features indicates that a cryptoprocessor 1513 supporting the corresponding type of TCG TPM API is present on an 1514 Attester. Most commonly, only one type of cryptoprocessor will be 1515 available on an Attester. 1517 2.1.2.2. Identities 1519 There are three types of identities in this model: 1521 1. Cryptographic functions supported by a TPM algorithm; these 1522 include: 'asymmetric', 'symmetric', 'hash', 'signing', 1523 'anonymous_signing', 'encryption_mode', 'method', and 1524 'object_type'. The definitions of each of these are in Table 2 1525 of [TCG-Algos]. 1527 2. API specifications for TPMs: 'tpm12' and 'tpm20' 1529 3. Specific algorithm types: Each algorithm type defines what 1530 cryptographic functions may be supported, and on which type of 1531 API specification. It is not required that an implementation of 1532 a specific TPM will support all algorithm types. The contents of 1533 each specific algorithm mirrors what is in Table 3 of 1534 [TCG-Algos]. 1536 2.1.2.3. YANG Module 1538 file "ietf-tcg-algs@2022-02-16.yang" 1539 module ietf-tcg-algs { 1540 yang-version 1.1; 1541 namespace "urn:ietf:params:xml:ns:yang:ietf-tcg-algs"; 1542 prefix taa; 1544 organization 1545 "IETF RATS Working Group"; 1547 contact 1548 "WG Web: 1549 WG List: 1550 Author: Eric Voit "; 1552 description 1553 "This module defines a identities for asymmetric algorithms. 1555 Copyright (c) 2022 IETF Trust and the persons identified 1556 as authors of the code. All rights reserved. 1558 Redistribution and use in source and binary forms, with 1559 or without modification, is permitted pursuant to, and 1560 subject to the license terms contained in, the Simplified 1561 BSD License set forth in Section 4.c of the IETF Trust's 1562 Legal Provisions Relating to IETF Documents 1563 (https://trustee.ietf.org/license-info). 1564 This version of this YANG module is part of RFC XXXX 1565 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC 1566 itself for full legal notices. 1567 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1568 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 1569 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 1570 are to be interpreted as described in BCP 14 (RFC 2119) 1571 (RFC 8174) when, and only when, they appear in all 1572 capitals, as shown here."; 1574 revision 2022-02-16 { 1575 description 1576 "Initial version"; 1577 reference 1578 "RFC XXXX: A YANG Data Model for Challenge-Response-based Remote 1579 Attestation Procedures using TPMs"; 1580 } 1582 /*****************/ 1583 /* Features */ 1584 /*****************/ 1586 feature tpm12 { 1587 description 1588 "This feature indicates algorithm support for the TPM 1.2 API 1589 as per Section 4.8 of TPM1.2-Structures: 1590 TPM Main Part 2 TPM Structures 1591 https://trustedcomputinggroup.org/wp-content/uploads/TPM- 1592 Main-Part-2-TPM-Structures_v1.2_rev116_01032011.pdf"; 1593 } 1595 feature tpm20 { 1596 description 1597 "This feature indicates algorithm support for the TPM 2.0 API 1598 as per Section 11.4 of Trusted Platform Module Library 1599 Part 1: Architecture. See TPM2.0-Arch: 1600 https://trustedcomputinggroup.org/wp-content/uploads/ 1601 TPM-Rev-2.0-Part-1-Architecture-01.07-2014-03-13.pdf"; 1602 } 1604 /*****************/ 1605 /* Identities */ 1606 /*****************/ 1608 identity asymmetric { 1609 description 1610 "A TCG recognized asymmetric algorithm with a public and 1611 private key."; 1612 reference 1613 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 2, 1614 http://trustedcomputinggroup.org/resource/tcg-algorithm-registry/ 1615 TCG-_Algorithm_Registry_r1p32_pub"; 1616 } 1618 identity symmetric { 1619 description 1620 "A TCG recognized symmetric algorithm with only a private key."; 1621 reference 1622 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 2"; 1623 } 1625 identity hash { 1626 description 1627 "A TCG recognized hash algorithm that compresses input data to 1628 a digest value or indicates a method that uses a hash."; 1629 reference 1630 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 2"; 1631 } 1633 identity signing { 1634 description 1635 "A TCG recognized signing algorithm"; 1636 reference 1637 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 2"; 1638 } 1640 identity anonymous_signing { 1641 description 1642 "A TCG recognized anonymous signing algorithm."; 1643 reference 1644 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 2"; 1645 } 1647 identity encryption_mode { 1648 description 1649 "A TCG recognized encryption mode."; 1650 reference 1651 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 2"; 1652 } 1653 identity method { 1654 description 1655 "A TCG recognized method such as a mask generation function."; 1656 reference 1657 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 2"; 1658 } 1660 identity object_type { 1661 description 1662 "A TCG recognized object type."; 1663 reference 1664 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 2"; 1665 } 1667 identity cryptoprocessor { 1668 description 1669 "Base identity identifying a crytoprocessor."; 1670 } 1672 identity tpm12 { 1673 if-feature "tpm12"; 1674 base cryptoprocessor; 1675 description 1676 "Supportable by a TPM1.2."; 1677 reference 1678 "TPM1.2-Structures: 1679 https://trustedcomputinggroup.org/wp-content/uploads/ 1680 TPM-Main-Part-2-TPM-Structures_v1.2_rev116_01032011.pdf 1681 TPM_ALGORITHM_ID values, page 18"; 1682 } 1684 identity tpm20 { 1685 if-feature "tpm20"; 1686 base cryptoprocessor; 1687 description 1688 "Supportable by a TPM2."; 1689 reference 1690 "TPM2.0-Structures: 1691 https://trustedcomputinggroup.org/wp-content/uploads/ 1692 TPM-Rev-2.0-Part-2-Structures-01.38.pdf 1693 The TCG Algorithm Registry. Table 9"; 1694 } 1696 identity TPM_ALG_RSA { 1697 if-feature "tpm12 or tpm20"; 1698 base tpm12; 1699 base tpm20; 1700 base asymmetric; 1701 base object_type; 1702 description 1703 "RSA algorithm"; 1704 reference 1705 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 1706 RFC 8017. ALG_ID: 0x0001"; 1707 } 1709 identity TPM_ALG_TDES { 1710 if-feature "tpm12"; 1711 base tpm12; 1712 base symmetric; 1713 description 1714 "Block cipher with various key sizes (Triple Data Encryption 1715 Algorithm, commonly called Triple Data Encryption Standard) 1716 Note: was banned in TPM1.2 v94"; 1717 reference 1718 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 1719 ISO/IEC 18033-3. ALG_ID: 0x0003"; 1720 } 1722 identity TPM_ALG_SHA1 { 1723 if-feature "tpm12 or tpm20"; 1724 base hash; 1725 base tpm12; 1726 base tpm20; 1727 description 1728 "SHA1 algorithm - Deprecated due to insufficient cryptographic 1729 protection. However it is still useful for hash algorithms 1730 where protection is not required."; 1731 reference 1732 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 1733 ISO/IEC 10118-3. ALG_ID: 0x0004"; 1734 } 1736 identity TPM_ALG_HMAC { 1737 if-feature "tpm12 or tpm20"; 1738 base tpm12; 1739 base tpm20; 1740 base hash; 1741 base signing; 1742 description 1743 "Hash Message Authentication Code (HMAC) algorithm"; 1744 reference 1745 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3, 1746 ISO/IEC 9797-2 and RFC2014. ALG_ID: 0x0005"; 1747 } 1748 identity TPM_ALG_AES { 1749 if-feature "tpm12"; 1750 base tpm12; 1751 base symmetric; 1752 description 1753 "The AES algorithm with various key sizes"; 1754 reference 1755 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3, 1756 ISO/IEC 18033-3. ALG_ID: 0x0006"; 1757 } 1759 identity TPM_ALG_MGF1 { 1760 if-feature "tpm20"; 1761 base tpm20; 1762 base hash; 1763 base method; 1764 description 1765 "hash-based mask-generation function"; 1766 reference 1767 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3, 1768 IEEE Std 1363-2000 and IEEE Std 1363a-2004. 1769 ALG_ID: 0x0007"; 1770 } 1772 identity TPM_ALG_KEYEDHASH { 1773 if-feature "tpm20"; 1774 base tpm20; 1775 base hash; 1776 base object_type; 1777 description 1778 "An encryption or signing algorithm using a keyed hash. These 1779 may use XOR for encryption or an HMAC for signing and may 1780 also refer to a data object that is neither signing nor 1781 encrypting."; 1782 reference 1783 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3, 1784 ALG_ID: 0x0008"; 1785 } 1787 identity TPM_ALG_XOR { 1788 if-feature "tpm12 or tpm20"; 1789 base tpm12; 1790 base tpm20; 1791 base hash; 1792 base symmetric; 1793 description 1794 "The XOR encryption algorithm."; 1795 reference 1796 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3. 1797 ALG_ID: 0x000A"; 1798 } 1800 identity TPM_ALG_SHA256 { 1801 if-feature "tpm20"; 1802 base tpm20; 1803 base hash; 1804 description 1805 "The SHA 256 algorithm"; 1806 reference 1807 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 1808 ISO/IEC 10118-3. ALG_ID: 0x000B"; 1809 } 1811 identity TPM_ALG_SHA384 { 1812 if-feature "tpm20"; 1813 base tpm20; 1814 base hash; 1815 description 1816 "The SHA 384 algorithm"; 1817 reference 1818 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 1819 ISO/IEC 10118-3. ALG_ID: 0x000C"; 1820 } 1822 identity TPM_ALG_SHA512 { 1823 if-feature "tpm20"; 1824 base tpm20; 1825 base hash; 1826 description 1827 "The SHA 512 algorithm"; 1828 reference 1829 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 1830 ISO/IEC 10118-3. ALG_ID: 0x000D"; 1831 } 1833 identity TPM_ALG_NULL { 1834 if-feature "tpm20"; 1835 base tpm20; 1836 description 1837 "NULL algorithm"; 1838 reference 1839 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3. 1840 ALG_ID: 0x0010"; 1841 } 1843 identity TPM_ALG_SM3_256 { 1844 if-feature "tpm20"; 1845 base tpm20; 1846 base hash; 1847 description 1848 "The SM3 hash algorithm."; 1849 reference 1850 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 1851 ISO/IEC 10118-3:2018. ALG_ID: 0x0012"; 1852 } 1854 identity TPM_ALG_SM4 { 1855 if-feature "tpm20"; 1856 base tpm20; 1857 base symmetric; 1858 description 1859 "SM4 symmetric block cipher"; 1860 reference 1861 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3. 1862 ALG_ID: 0x0013"; 1863 } 1865 identity TPM_ALG_RSASSA { 1866 if-feature "tpm20"; 1867 base tpm20; 1868 base asymmetric; 1869 base signing; 1870 description 1871 "Signature algorithm defined in section 8.2 (RSASSAPKCS1-v1_5)"; 1872 reference 1873 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 1874 RFC 8017. ALG_ID: 0x0014"; 1875 } 1877 identity TPM_ALG_RSAES { 1878 if-feature "tpm20"; 1879 base tpm20; 1880 base asymmetric; 1881 base encryption_mode; 1882 description 1883 "Signature algorithm defined in section 7.2 (RSAES-PKCS1-v1_5)"; 1884 reference 1885 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 1886 RFC 8017. ALG_ID: 0x0015"; 1887 } 1889 identity TPM_ALG_RSAPSS { 1890 if-feature "tpm20"; 1891 base tpm20; 1892 base asymmetric; 1893 base signing; 1894 description 1895 "Padding algorithm defined in section 8.1 (RSASSA PSS)"; 1896 reference 1897 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 1898 RFC 8017. ALG_ID: 0x0016"; 1899 } 1901 identity TPM_ALG_OAEP { 1902 if-feature "tpm20"; 1903 base tpm20; 1904 base asymmetric; 1905 base encryption_mode; 1906 description 1907 "Padding algorithm defined in section 7.1 (RSASSA OAEP)"; 1908 reference 1909 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 1910 RFC 8017. ALG_ID: 0x0017"; 1911 } 1913 identity TPM_ALG_ECDSA { 1914 if-feature "tpm20"; 1915 base tpm20; 1916 base asymmetric; 1917 base signing; 1918 description 1919 "Signature algorithm using elliptic curve cryptography (ECC)"; 1920 reference 1921 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 1922 ISO/IEC 14888-3. ALG_ID: 0x0018"; 1923 } 1925 identity TPM_ALG_ECDH { 1926 if-feature "tpm20"; 1927 base tpm20; 1928 base asymmetric; 1929 base method; 1930 description 1931 "Secret sharing using ECC"; 1932 reference 1933 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 1934 NIST SP800-56A and RFC 7748. ALG_ID: 0x0019"; 1935 } 1937 identity TPM_ALG_ECDAA { 1938 if-feature "tpm20"; 1939 base tpm20; 1940 base asymmetric; 1941 base signing; 1942 base anonymous_signing; 1943 description 1944 "Elliptic-curve based anonymous signing scheme"; 1945 reference 1946 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 1947 TCG TPM 2.0 library specification. ALG_ID: 0x001A"; 1948 } 1950 identity TPM_ALG_SM2 { 1951 if-feature "tpm20"; 1952 base tpm20; 1953 base asymmetric; 1954 base signing; 1955 base encryption_mode; 1956 base method; 1957 description 1958 "SM2 - depending on context, either an elliptic-curve based, 1959 signature algorithm, an encryption scheme, or a key exchange 1960 protocol"; 1961 reference 1962 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3. 1963 ALG_ID: 0x001B"; 1964 } 1966 identity TPM_ALG_ECSCHNORR { 1967 if-feature "tpm20"; 1968 base tpm20; 1969 base asymmetric; 1970 base signing; 1971 description 1972 "Elliptic-curve based Schnorr signature"; 1973 reference 1974 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3. 1975 ALG_ID: 0x001C"; 1976 } 1978 identity TPM_ALG_ECMQV { 1979 if-feature "tpm20"; 1980 base tpm20; 1981 base asymmetric; 1982 base method; 1983 description 1984 "Two-phase elliptic-curve key"; 1985 reference 1986 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 1987 NIST SP800-56A. ALG_ID: 0x001D"; 1989 } 1991 identity TPM_ALG_KDF1_SP800_56A { 1992 if-feature "tpm20"; 1993 base tpm20; 1994 base hash; 1995 base method; 1996 description 1997 "Concatenation key derivation function"; 1998 reference 1999 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 2000 NIST SP800-56A (approved alternative1) section 5.8.1. 2001 ALG_ID: 0x0020"; 2002 } 2004 identity TPM_ALG_KDF2 { 2005 if-feature "tpm20"; 2006 base tpm20; 2007 base hash; 2008 base method; 2009 description 2010 "Key derivation function"; 2011 reference 2012 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 2013 IEEE 1363a-2004 KDF2 section 13.2. ALG_ID: 0x0021"; 2014 } 2016 identity TPM_ALG_KDF1_SP800_108 { 2017 base TPM_ALG_KDF2; 2018 description 2019 "A key derivation method"; 2020 reference 2021 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 2022 NIST SP800-108 - Section 5.1 KDF. ALG_ID: 0x0022"; 2023 } 2025 identity TPM_ALG_ECC { 2026 if-feature "tpm20"; 2027 base tpm20; 2028 base asymmetric; 2029 base object_type; 2030 description 2031 "Prime field ECC"; 2032 reference 2033 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 2034 ISO/IEC 15946-1. ALG_ID: 0x0023"; 2035 } 2036 identity TPM_ALG_SYMCIPHER { 2037 if-feature "tpm20"; 2038 base tpm20; 2039 description 2040 "Object type for a symmetric block cipher"; 2041 reference 2042 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 2043 TCG TPM 2.0 library specification. ALG_ID: 0x0025"; 2044 } 2046 identity TPM_ALG_CAMELLIA { 2047 if-feature "tpm20"; 2048 base tpm20; 2049 base symmetric; 2050 description 2051 "The Camellia algorithm"; 2052 reference 2053 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 2054 ISO/IEC 18033-3. ALG_ID: 0x0026"; 2055 } 2057 identity TPM_ALG_SHA3_256 { 2058 if-feature "tpm20"; 2059 base tpm20; 2060 base hash; 2061 description 2062 "ISO/IEC 10118-3 - the SHA 256 algorithm"; 2063 reference 2064 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 2065 NIST PUB FIPS 202. ALG_ID: 0x0027"; 2066 } 2068 identity TPM_ALG_SHA3_384 { 2069 if-feature "tpm20"; 2070 base tpm20; 2071 base hash; 2072 description 2073 "The SHA 384 algorithm"; 2074 reference 2075 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 2076 NIST PUB FIPS 202. ALG_ID: 0x0028"; 2077 } 2079 identity TPM_ALG_SHA3_512 { 2080 if-feature "tpm20"; 2081 base tpm20; 2082 base hash; 2083 description 2084 "The SHA 512 algorithm"; 2085 reference 2086 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 2087 NIST PUB FIPS 202. ALG_ID: 0x0029"; 2088 } 2090 identity TPM_ALG_CMAC { 2091 if-feature "tpm20"; 2092 base tpm20; 2093 base symmetric; 2094 base signing; 2095 description 2096 "block Cipher-based Message Authentication Code (CMAC)"; 2097 reference 2098 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 2099 ISO/IEC 9797-1:2011 Algorithm 5. ALG_ID: 0x003F"; 2100 } 2102 identity TPM_ALG_CTR { 2103 if-feature "tpm20"; 2104 base tpm20; 2105 base symmetric; 2106 base encryption_mode; 2107 description 2108 "Counter mode"; 2109 reference 2110 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 2111 ISO/IEC 10116. ALG_ID: 0x0040"; 2112 } 2114 identity TPM_ALG_OFB { 2115 base tpm20; 2116 base symmetric; 2117 base encryption_mode; 2118 description 2119 "Output Feedback mode"; 2120 reference 2121 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 2122 ISO/IEC 10116. ALG_ID: 0x0041"; 2123 } 2125 identity TPM_ALG_CBC { 2126 if-feature "tpm20"; 2127 base tpm20; 2128 base symmetric; 2129 base encryption_mode; 2130 description 2131 "Cipher Block Chaining mode"; 2133 reference 2134 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 2135 ISO/IEC 10116. ALG_ID: 0x0042"; 2136 } 2138 identity TPM_ALG_CFB { 2139 if-feature "tpm20"; 2140 base tpm20; 2141 base symmetric; 2142 base encryption_mode; 2143 description 2144 "Cipher Feedback mode"; 2145 reference 2146 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 2147 ISO/IEC 10116. ALG_ID: 0x0043"; 2148 } 2150 identity TPM_ALG_ECB { 2151 if-feature "tpm20"; 2152 base tpm20; 2153 base symmetric; 2154 base encryption_mode; 2155 description 2156 "Electronic Codebook mode"; 2157 reference 2158 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 2159 ISO/IEC 10116. ALG_ID: 0x0044"; 2160 } 2162 identity TPM_ALG_CCM { 2163 if-feature "tpm20"; 2164 base tpm20; 2165 base symmetric; 2166 base signing; 2167 base encryption_mode; 2168 description 2169 "Counter with Cipher Block Chaining-Message Authentication 2170 Code (CCM)"; 2171 reference 2172 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 2173 NIST SP800-38C. ALG_ID: 0x0050"; 2174 } 2176 identity TPM_ALG_GCM { 2177 if-feature "tpm20"; 2178 base tpm20; 2179 base symmetric; 2180 base signing; 2181 base encryption_mode; 2182 description 2183 "Galois/Counter Mode (GCM)"; 2184 reference 2185 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 2186 NIST SP800-38D. ALG_ID: 0x0051"; 2187 } 2189 identity TPM_ALG_KW { 2190 if-feature "tpm20"; 2191 base tpm20; 2192 base symmetric; 2193 base signing; 2194 base encryption_mode; 2195 description 2196 "AES Key Wrap (KW)"; 2197 reference 2198 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 2199 NIST SP800-38F. ALG_ID: 0x0052"; 2200 } 2202 identity TPM_ALG_KWP { 2203 if-feature "tpm20"; 2204 base tpm20; 2205 base symmetric; 2206 base signing; 2207 base encryption_mode; 2208 description 2209 "AES Key Wrap with Padding (KWP)"; 2210 reference 2211 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 2212 NIST SP800-38F. ALG_ID: 0x0053"; 2213 } 2215 identity TPM_ALG_EAX { 2216 if-feature "tpm20"; 2217 base tpm20; 2218 base symmetric; 2219 base signing; 2220 base encryption_mode; 2221 description 2222 "Authenticated-Encryption Mode"; 2223 reference 2224 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 2225 NIST SP800-38F. ALG_ID: 0x0054"; 2226 } 2228 identity TPM_ALG_EDDSA { 2229 if-feature "tpm20"; 2230 base tpm20; 2231 base asymmetric; 2232 base signing; 2233 description 2234 "Edwards-curve Digital Signature Algorithm (PureEdDSA)"; 2235 reference 2236 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and 2237 RFC 8032. ALG_ID: 0x0060"; 2238 } 2239 } 2240 2242 Note that not all cryptographic functions are required for use by 2243 ietf-tpm-remote-attestation.yang. However the full definition of 2244 Table 3 of [TCG-Algos] will allow use by additional YANG 2245 specifications. 2247 3. IANA Considerations 2249 This document registers the following namespace URIs in the 2250 [xml-registry] as per [RFC3688]: 2252 URI: urn:ietf:params:xml:ns:yang:ietf-tpm-remote-attestation 2254 Registrant Contact: The IESG. 2256 XML: N/A; the requested URI is an XML namespace. 2258 URI: urn:ietf:params:xml:ns:yang:ietf-tcg-algs 2260 Registrant Contact: The IESG. 2262 XML: N/A; the requested URI is an XML namespace. 2264 This document registers the following YANG modules in the registry 2265 [yang-parameters] as per Section 14 of [RFC6020]: 2267 Name: ietf-tpm-remote-attestation 2269 Namespace: urn:ietf:params:xml:ns:yang:ietf-tpm-remote- 2270 attestation 2272 Prefix: tpm 2274 Reference: draft-ietf-rats-yang-tpm-charra (RFC form) 2276 Name: ietf-tcg-algs 2277 Namespace: urn:ietf:params:xml:ns:yang:ietf-tcg-algs 2279 Prefix: taa 2281 Reference: draft-ietf-rats-yang-tpm-charra (RFC form) 2283 4. Security Considerations 2285 The YANG module ietf-tpm-remote-attestation.yang specified in this 2286 document defines a schema for data that is designed to be accessed 2287 via network management protocols such as NETCONF [RFC6241] or 2288 RESTCONF [RFC8040]. The lowest NETCONF layer is the secure transport 2289 layer, and the mandatory-to-implement secure transport is Secure 2290 Shell (SSH) [RFC6242]. The lowest RESTCONF layer is HTTPS, and the 2291 mandatory-to-implement secure transport is TLS [RFC8446]. 2293 There are a number of data nodes defined in this YANG module that are 2294 writable/creatable/deletable (i.e., _config true_, which is the 2295 default). These data nodes may be considered sensitive or vulnerable 2296 in some network environments. Write operations (e.g., _edit-config_) 2297 to these data nodes without proper protection can have a negative 2298 effect on network operations. These are the subtrees and data nodes 2299 as well as their sensitivity/vulnerability: 2301 Container '/rats-support-structures/attester-supported-algos': 'tpm1 2302 2-asymmetric-signing', 'tpm12-hash', 'tpm20-asymmetric-signing', 2303 and 'tpm20-hash'. All could be populated with algorithms that are 2304 not supported by the underlying physical TPM installed by the 2305 equipment vendor. 2307 Container: '/rats-support-structures/tpms': 'name': Although shown 2308 as 'rw', it is system generated. Therefore it should not be 2309 possible for an operator to add or remove a TPM from the 2310 configuration. 2312 'tpm20-pcr-bank': It is possible to configure PCRs for extraction 2313 which are not being extended by system software. This could 2314 unnecessarily use TPM resources. 2316 'certificates': It is possible to provision a certificate which 2317 does not correspond to an Attestation Identity Key (AIK) within 2318 the TPM 1.2, or an Attestation Key (AK) within the TPM 2.0 2319 respectively. 2321 RPC 'tpm12-challenge-response-attestation': It must be verified that 2322 the certificate is for an active AIK, i.e., the certificate 2323 provided is able to support Attestation on the targeted TPM 1.2. 2325 RPC 'tpm20-challenge-response-attestation': It must be verified that 2326 the certificate is for an active AK, i.e., the quote signature 2327 associated with RPC response has been generated by an entity 2328 legitimately able to perform Attestation on the targeted TPM 2.0. 2330 RPC 'log-retrieval': Requesting a large volume of logs from the 2331 attester could require significant system resources and create a 2332 denial of service. 2334 Information collected through the RPCs above could reveal that 2335 specific versions of software and configurations of endpoints that 2336 could identify vulnerabilities on those systems. Therefore RPCs 2337 should be protected by NACM [RFC8341] with a default setting of deny- 2338 all to limit the extraction of attestation data by only authorized 2339 Verifiers. 2341 For the YANG module ietf-tcg-algs.yang, please use care when 2342 selecting specific algorithms. The introductory section of 2343 [TCG-Algos] highlights that some algorithms should be considered 2344 legacy, and recommends implementers and adopters diligently evaluate 2345 available information such as governmental, industrial, and academic 2346 research before selecting an algorithm for use. 2348 5. Change Log 2350 Changes from version 08 to version 09: 2352 * AD Review comments 2354 Changes from version 08 to version 09: 2356 * Minor formatting tweaks for shepherd. IANA registered. 2358 Changes from version 05 to version 06: 2360 * More YANG Dr comments covered 2362 Changes from version 04 to version 05: 2364 * YANG Dr comments covered 2366 Changes from version 03 to version 04: 2368 * TPM1.2 Quote1 eliminated 2370 * YANG model simplifications so redundant info isn't exposed 2372 Changes from version 02 to version 03: 2374 * moved to tcg-algs 2376 * cleaned up model to eliminate sources of errors 2378 * removed key establishment RPC 2380 * added lots of XPATH which must all be scrubbed still 2382 * Descriptive text added on model contents. 2384 Changes from version 01 to version 02: 2386 * Extracted Crypto-types into a separate YANG file 2388 * Mades the algorithms explicit, not strings 2390 * Hash Algo as key the selected TPM2 PCRs 2392 * PCR numbers are their own type 2394 * Eliminated nested keys for node-id plus tpm-name 2396 * Eliminated TPM-Name of "ALL" 2398 * Added TPM-Path 2400 Changes from version 00 to version 01: 2402 * Addressed author's comments 2404 * Extended complementary details about attestation-certificates 2406 * Relabeled chunk-size to log-entry-quantity 2408 * Relabeled location with compute-node or tpm-name where appropriate 2410 * Added a valid entity-mib physical-index to compute-node and tpm- 2411 name to map it back to hardware inventory 2413 * Relabeled name to tpm_name 2415 * Removed event-string in last-entry 2417 6. References 2419 6.1. Normative References 2421 [bios-log] "TCG PC Client Platform Firmware Profile Specification, 2422 Section 9.4.5.2", n.d., 2423 . 2427 [BIOS-Log-Event-Type] 2428 "TCG PC Client Platform Firmware Profile Specification", 2429 n.d., . 2432 [I-D.ietf-netconf-keystore] 2433 Watsen, K., "A YANG Data Model for a Keystore", Work in 2434 Progress, Internet-Draft, draft-ietf-netconf-keystore-23, 2435 14 December 2021, . 2438 [I-D.ietf-rats-architecture] 2439 Birkholz, H., Thaler, D., Richardson, M., Smith, N., and 2440 W. Pan, "Remote Attestation Procedures Architecture", Work 2441 in Progress, Internet-Draft, draft-ietf-rats-architecture- 2442 15, 8 February 2022, . 2445 [I-D.ietf-rats-tpm-based-network-device-attest] 2446 Fedorkow, G., Voit, E., and J. Fitzgerald-McKay, "TPM- 2447 based Network Device Remote Integrity Verification", Work 2448 in Progress, Internet-Draft, draft-ietf-rats-tpm-based- 2449 network-device-attest-13, 1 March 2022, 2450 . 2453 [IEEE-Std-1363-2000] 2454 "IEEE 1363-2000 - IEEE Standard Specifications for Public- 2455 Key Cryptography", n.d., 2456 . 2458 [IEEE-Std-1363a-2004] 2459 "1363a-2004 - IEEE Standard Specifications for Public-Key 2460 Cryptography - Amendment 1: Additional Techniques", n.d., 2461 . 2463 [ima-log] "Canonical Event Log Format, Section 4.3", n.d., 2464 . 2467 [ISO-IEC-10116] 2468 "ISO/IEC 10116:2017 - Information technology", n.d., 2469 . 2471 [ISO-IEC-10118-3] 2472 "Dedicated hash-functions - ISO/IEC 10118-3:2018", n.d., 2473 . 2475 [ISO-IEC-14888-3] 2476 "ISO/IEC 14888-3:2018 - Digital signatures with appendix", 2477 n.d., . 2479 [ISO-IEC-15946-1] 2480 "ISO/IEC 15946-1:2016 - Information technology", n.d., 2481 . 2483 [ISO-IEC-18033-3] 2484 "ISO/IEC 18033-3:2010 - Encryption algorithms", n.d., 2485 . 2487 [ISO-IEC-9797-1] 2488 "Message Authentication Codes (MACs) - ISO/IEC 2489 9797-1:2011", n.d., 2490 . 2492 [ISO-IEC-9797-2] 2493 "Message Authentication Codes (MACs) - ISO/IEC 2494 9797-2:2011", n.d., 2495 . 2497 [netequip-boot-log] 2498 "IMA Policy Kernel Documentation", n.d., 2499 . 2502 [NIST-PUB-FIPS-202] 2503 "SHA-3 Standard: Permutation-Based Hash and Extendable- 2504 Output Functions", n.d., 2505 . 2508 [NIST-SP800-108] 2509 "Recommendation for Key Derivation Using Pseudorandom 2510 Functions", n.d., 2511 . 2514 [NIST-SP800-38C] 2515 "Recommendation for Block Cipher Modes of Operation: the 2516 CCM Mode for Authentication and Confidentiality", n.d., 2517 . 2520 [NIST-SP800-38D] 2521 "Recommendation for Block Cipher Modes of Operation: 2522 Galois/Counter Mode (GCM) and GMAC", n.d., 2523 . 2526 [NIST-SP800-38F] 2527 "Recommendation for Block Cipher Modes of Operation: 2528 Methods for Key Wrapping", n.d., 2529 . 2532 [NIST-SP800-56A] 2533 "Recommendation for Pair-Wise Key-Establishment Schemes 2534 Using Discrete Logarithm Cryptography", n.d., 2535 . 2538 [RFC2014] Weinrib, A. and J. Postel, "IRTF Research Group Guidelines 2539 and Procedures", BCP 8, RFC 2014, DOI 10.17487/RFC2014, 2540 October 1996, . 2542 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2543 Requirement Levels", BCP 14, RFC 2119, 2544 DOI 10.17487/RFC2119, March 1997, 2545 . 2547 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2548 DOI 10.17487/RFC3688, January 2004, 2549 . 2551 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 2552 the Network Configuration Protocol (NETCONF)", RFC 6020, 2553 DOI 10.17487/RFC6020, October 2010, 2554 . 2556 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2557 and A. Bierman, Ed., "Network Configuration Protocol 2558 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2559 . 2561 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 2562 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 2563 . 2565 [RFC6933] Bierman, A., Romascanu, D., Quittek, J., and M. 2566 Chandramouli, "Entity MIB (Version 4)", RFC 6933, 2567 DOI 10.17487/RFC6933, May 2013, 2568 . 2570 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 2571 RFC 6991, DOI 10.17487/RFC6991, July 2013, 2572 . 2574 [RFC7748] Langley, A., Hamburg, M., and S. Turner, "Elliptic Curves 2575 for Security", RFC 7748, DOI 10.17487/RFC7748, January 2576 2016, . 2578 [RFC8017] Moriarty, K., Ed., Kaliski, B., Jonsson, J., and A. Rusch, 2579 "PKCS #1: RSA Cryptography Specifications Version 2.2", 2580 RFC 8017, DOI 10.17487/RFC8017, November 2016, 2581 . 2583 [RFC8032] Josefsson, S. and I. Liusvaara, "Edwards-Curve Digital 2584 Signature Algorithm (EdDSA)", RFC 8032, 2585 DOI 10.17487/RFC8032, January 2017, 2586 . 2588 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2589 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2590 . 2592 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2593 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2594 May 2017, . 2596 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 2597 Access Control Model", STD 91, RFC 8341, 2598 DOI 10.17487/RFC8341, March 2018, 2599 . 2601 [RFC8348] Bierman, A., Bjorklund, M., Dong, J., and D. Romascanu, "A 2602 YANG Data Model for Hardware Management", RFC 8348, 2603 DOI 10.17487/RFC8348, March 2018, 2604 . 2606 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 2607 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 2608 . 2610 [TCG-Algos] 2611 "TCG Algorithm Registry", n.d., 2612 . 2615 [TPM1.2] TCG, ., "TPM 1.2 Main Specification", 2 October 2003, 2616 . 2619 [TPM1.2-Commands] 2620 "TPM Main Part 3 Commands", n.d., 2621 . 2624 [TPM1.2-Structures] 2625 "TPM Main Part 2 TPM Structures", n.d., 2626 . 2629 [TPM2.0] TCG, ., "TPM 2.0 Library Specification", 15 March 2013, 2630 . 2633 [TPM2.0-Arch] 2634 "Trusted Platform Module Library - Part 1: Architecture", 2635 n.d., . 2639 [TPM2.0-Key] 2640 TCG, ., "TPM 2.0 Keys for Device Identity and Attestation, 2641 Rev10", 14 April 2021, . 2644 [TPM2.0-Structures] 2645 "Trusted Platform Module Library - Part 2: Structures", 2646 n.d., . 2649 [xml-registry] 2650 "IETF XML Registry", n.d., 2651 . 2654 [yang-parameters] 2655 "YANG Parameters", n.d., 2656 . 2659 6.2. Informative References 2661 [I-D.ietf-rats-reference-interaction-models] 2662 Birkholz, H., Eckel, M., Pan, W., and E. Voit, "Reference 2663 Interaction Models for Remote Attestation Procedures", 2664 Work in Progress, Internet-Draft, draft-ietf-rats- 2665 reference-interaction-models-05, 26 January 2022, 2666 . 2669 [NIST-915121] 2670 "True Randomness Can't be Left to Chance: Why entropy is 2671 important for information security", n.d., 2672 . 2675 Authors' Addresses 2677 Henk Birkholz 2678 Fraunhofer SIT 2679 Rheinstrasse 75 2680 64295 Darmstadt 2681 Germany 2682 Email: henk.birkholz@sit.fraunhofer.de 2684 Michael Eckel 2685 Fraunhofer SIT 2686 Rheinstrasse 75 2687 64295 Darmstadt 2688 Germany 2689 Email: michael.eckel@sit.fraunhofer.de 2691 Shwetha Bhandari 2692 ThoughtSpot 2693 Email: shwetha.bhandari@thoughtspot.com 2695 Eric Voit 2696 Cisco Systems 2697 Email: evoit@cisco.com 2699 Bill Sulzen 2700 Cisco Systems 2701 Email: bsulzen@cisco.com 2702 Liang Xia (Frank) 2703 Huawei Technologies 2704 101 Software Avenue, Yuhuatai District 2705 Nanjing 2706 Jiangsu, 210012 2707 China 2708 Email: Frank.Xialiang@huawei.com 2710 Tom Laffey 2711 Hewlett Packard Enterprise 2712 Email: tom.laffey@hpe.com 2714 Guy C. Fedorkow 2715 Juniper Networks 2716 10 Technology Park Drive 2717 Westford 2718 Email: gfedorkow@juniper.net