idnits 2.17.1 draft-birkholz-rats-basic-yang-module-01.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 8 instances of too long lines in the document, the longest one being 4 characters in excess of 72. == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 145 has weird spacing: '...E-value uin...' == Line 285 has weird spacing: '...-number uin...' -- The document date (July 08, 2019) is 1751 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: 'I-D.ietf-netconf-crypto-types' is defined on line 1400, but no explicit reference was found in the text == Outdated reference: A later version (-03) exists of draft-birkholz-rats-reference-interaction-model-00 ** Downref: Normative reference to an Informational draft: draft-birkholz-rats-reference-interaction-model (ref. 'I-D.birkholz-rats-reference-interaction-model') == Outdated reference: A later version (-34) exists of draft-ietf-netconf-crypto-types-10 Summary: 2 errors (**), 0 flaws (~~), 7 warnings (==), 1 comment (--). 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: January 9, 2020 S. Bhandari 6 B. Sulzen 7 E. Voit 8 Cisco 9 L. Xia 10 Huawei 11 T. Laffey 12 HPE 13 G. Fedorkow 14 Juniper 15 July 08, 2019 17 YANG Module for Basic Challenge-Response-based Remote Attestation 18 Procedures 19 draft-birkholz-rats-basic-yang-module-01 21 Abstract 23 This document defines a YANG RPC and a minimal datastore tree 24 required to retrieve attestation evidence about integrity 25 measurements from a composite device with one or more roots of trust 26 for reporting. Complementary measurement logs are also provided by 27 the YANG RPC originating from one or more roots of trust of 28 measurement. The module defined requires a TPM 2.0 and corresponding 29 Trusted Software Stack included in the device components of the 30 composite device the YANG server is running on. 32 Status of This Memo 34 This Internet-Draft is submitted in full conformance with the 35 provisions of BCP 78 and BCP 79. 37 Internet-Drafts are working documents of the Internet Engineering 38 Task Force (IETF). Note that other groups may also distribute 39 working documents as Internet-Drafts. The list of current Internet- 40 Drafts is at https://datatracker.ietf.org/drafts/current/. 42 Internet-Drafts are draft documents valid for a maximum of six months 43 and may be updated, replaced, or obsoleted by other documents at any 44 time. It is inappropriate to use Internet-Drafts as reference 45 material or to cite them other than as "work in progress." 47 This Internet-Draft will expire on January 9, 2020. 49 Copyright Notice 51 Copyright (c) 2019 IETF Trust and the persons identified as the 52 document authors. All rights reserved. 54 This document is subject to BCP 78 and the IETF Trust's Legal 55 Provisions Relating to IETF Documents 56 (https://trustee.ietf.org/license-info) in effect on the date of 57 publication of this document. Please review these documents 58 carefully, as they describe your rights and restrictions with respect 59 to this document. Code Components extracted from this document must 60 include Simplified BSD License text as described in Section 4.e of 61 the Trust Legal Provisions and are provided without warranty as 62 described in the Simplified BSD License. 64 Table of Contents 66 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 67 1.1. Requirements notation . . . . . . . . . . . . . . . . . . 3 68 2. The YANG Module for Basic Remote Attestation Procedures . . . 3 69 2.1. Tree format . . . . . . . . . . . . . . . . . . . . . . . 3 70 2.2. Raw Format . . . . . . . . . . . . . . . . . . . . . . . 7 71 3. IANA considerations . . . . . . . . . . . . . . . . . . . . . 29 72 4. Security Considerations . . . . . . . . . . . . . . . . . . . 29 73 5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 29 74 6. Change Log . . . . . . . . . . . . . . . . . . . . . . . . . 29 75 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 29 76 7.1. Normative References . . . . . . . . . . . . . . . . . . 29 77 7.2. Informative References . . . . . . . . . . . . . . . . . 30 78 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 30 80 1. Introduction 82 This document is based on the terminology defined in the 83 [I-D.birkholz-attestation-terminology] and uses the interaction model 84 and information elements defined in the 85 [I-D.birkholz-rats-reference-interaction-model] document. The 86 currently supported hardware security module (HWM) - sometimes also 87 referred to as an embedded secure element(eSE) - is the Trusted 88 Platform Module (TPM) 2.0 specified by the Trusted Computing Group 89 (TCG). One ore more TPM 2.0 embedded in the components of a 90 composite device - sometimes also referred to as an aggregate device 91 - are required in order to use the YANG module defined in this 92 document. A TPM 2.0 is used as a root of trust for reporting (RTR) 93 in order to retrieve attestation evidence from a composite device. 94 Additionally, it is used as a root of trust for measurement (RTM) in 95 order to provide event logs - sometimes also referred to as 96 measurement logs. 98 1.1. Requirements notation 100 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 101 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 102 "OPTIONAL" in this document are to be interpreted as described in RFC 103 2119, BCP 14 [RFC2119]. 105 2. The YANG Module for Basic Remote Attestation Procedures 107 One or more TPM 2.0 MUST be embedded in the composite device that is 108 providing attestation evidence via the YANG module defined in this 109 document. The ietf-basic-remote-attestation YANG module enables a 110 composite device to take on the role of Claimant and Attester in 111 accordance with the Remote Attestation Procedures (RATS) architecture 112 [I-D.birkholz-attestation-terminology] and the corresponding 113 challenge-response interaction model defined in the 114 [I-D.birkholz-rats-reference-interaction-model] document. A fresh 115 nonce with an appropriate amount of entropy MUST be supplied by the 116 YANG client in order to enable a proof-of-freshness with respect to 117 the attestation evidence provided by the attester running the YANG 118 datastore. The functions of this YANG module are restricted to 0-1 119 TPM 2.0 per hardware component. 121 2.1. Tree format 123 124 module: ietf-basic-remote-attestation 125 +--ro rats-support-structures 126 +--ro supported-algos* uint16 127 +--ro tpms* [tpm_name] 128 | +--ro tpm_name string 129 | +--ro tpm-physical-index? int32 {ietfhw:entity-mib}? 130 | +--ro certificates* [] 131 | +--ro certificate 132 | +--ro certificate-name? string 133 | +--ro certificate-type? enumeration 134 | +--ro certificate-value? ietfct:end-entity-cert-cms 135 +--ro compute-nodes* [node-name] 136 +--ro node-name string 137 +--ro node-physical-index? int32 {ietfhw:entity-mib}? 139 rpcs: 140 +---x tpm12-challenge-response-attestation 141 | +---w input 142 | | +---w tpm1-attestation-challenge 143 | | +---w pcr-indices* uint8 144 | | +---w nonce-value binary 145 | | +---w TPM_SIG_SCHEME-value uint8 146 | | +---w (key-identifier)? 147 | | | +--:(public-key) 148 | | | | +---w pub-key-id? binary 149 | | | +--:(TSS_UUID) 150 | | | +---w TSS_UUID-value 151 | | | +---w ulTimeLow? uint32 152 | | | +---w usTimeMid? uint16 153 | | | +---w usTimeHigh? uint16 154 | | | +---w bClockSeqHigh? uint8 155 | | | +---w bClockSeqLow? uint8 156 | | | +---w rgbNode* uint8 157 | | +---w add-version? boolean 158 | | +---w tpm_name? string 159 | | +---w tpm-physical-index? int32 {ietfhw:entity-mib}? 160 | +--ro output 161 | +--ro tpm12-attestation-response* [tpm_name] 162 | +--ro tpm_name string 163 | +--ro tpm-physical-index? int32 {ietfhw:entity-mib}? 164 | +--ro up-time? uint32 165 | +--ro node-name? string 166 | +--ro node-physical-index? int32 {ietfhw:entity-mib}? 167 | +--ro fixed? binary 168 | +--ro external-data? binary 169 | +--ro signature-size? uint32 170 | +--ro signature? binary 171 | +--ro (tpm12-quote) 172 | +--:(tpm12-quote1) 173 | | +--ro version* [] 174 | | | +--ro major? uint8 175 | | | +--ro minor? uint8 176 | | | +--ro revMajor? uint8 177 | | | +--ro revMinor? uint8 178 | | +--ro digest-value? binary 179 | | +--ro TPM_PCR_COMPOSITE* [] 180 | | +--ro pcr-indices* uint8 181 | | +--ro value-size? uint32 182 | | +--ro tpm12-pcr-value* binary 183 | +--:(tpm12-quote2) 184 | +--ro tag? uint8 185 | +--ro pcr-indices* uint8 186 | +--ro locality-at-release? uint8 187 | +--ro digest-at-release? binary 188 +---x tpm20-challenge-response-attestation 189 | +---w input 190 | | +---w tpm20-attestation-challenge 191 | | | +---w pcr-list* [] 192 | | | | +---w pcr 193 | | | | +---w pcr-indices* uint8 194 | | | | +---w (algo-registry-type) 195 | | | | +--:(tcg) 196 | | | | | +---w tcg-hash-algo-id? uint16 197 | | | | +--:(ietf) 198 | | | | +---w ietf-ni-hash-algo-id? uint8 199 | | | +---w nonce-value binary 200 | | | +---w (signature-identifier-type) 201 | | | | +--:(TPM_ALG_ID) 202 | | | | | +---w TPM_ALG_ID-value? uint16 203 | | | | +--:(COSE_Algorithm) 204 | | | | +---w COSE_Algorithm-value? int32 205 | | | +---w (key-identifier)? 206 | | | +--:(public-key) 207 | | | | +---w pub-key-id? binary 208 | | | +--:(uuid) 209 | | | +---w uuid-value? binary 210 | | +---w tpms* [tpm_name] 211 | | +---w tpm_name string 212 | | +---w tpm-physical-index? int32 {ietfhw:entity-mib}? 213 | +--ro output 214 | +--ro tpm20-attestation-response* [tpm_name] 215 | +--ro tpm_name string 216 | +--ro tpm-physical-index? int32 {ietfhw:entity-mib}? 217 | +--ro up-time? uint32 218 | +--ro node-name? string 219 | +--ro node-physical-index? int32 {ietfhw:entity-mib}? 220 | +--ro tpms-attest 221 | | +--ro pcrdigest? binary 222 | | +--ro tpms-attest-result? binary 223 | | +--ro tpms-attest-result-length? uint32 224 | +--ro tpmt-signature? binary 225 +---x basic-trust-establishment 226 | +---w input 227 | | +---w nonce-value binary 228 | | +---w (signature-identifier-type) 229 | | | +--:(TPM_ALG_ID) 230 | | | | +---w TPM_ALG_ID-value? uint16 231 | | | +--:(COSE_Algorithm) 232 | | | +---w COSE_Algorithm-value? int32 233 | | +---w tpm_name? string 234 | | +---w tpm-physical-index? int32 {ietfhw:entity-mib}? 235 | | +---w certificate-name? string 236 | +--ro output 237 | +--ro attestation-certificates* [tpm_name] 238 | +--ro tpm_name string 239 | +--ro tpm-physical-index? int32 {ietfhw:entity-mib}? 240 | +--ro up-time? uint32 241 | +--ro node-name? string 242 | +--ro node-physical-index? int32 {ietfhw:entity-mib}? 243 | +--ro certificate-name? string 244 | +--ro attestation-certificate? ietfct:end-entity-cert-cms 245 | +--ro (key-identifier)? 246 | +--:(public-key) 247 | | +--ro pub-key-id? binary 248 | +--:(uuid) 249 | +--ro uuid-value? binary 250 +---x log-retrieval 251 +---w input 252 | +---w log-selector* [node-name] 253 | | +---w node-name string 254 | | +---w node-physical-index? int32 {ietfhw:entity-mib}? 255 | | +---w (index-type)? 256 | | +--:(last-entry) 257 | | | +---w last-entry-value? binary 258 | | +--:(index) 259 | | | +---w index-number? uint64 260 | | +--:(timestamp) 261 | | +---w timestamp? yang:date-and-time 262 | +---w log-type identityref 263 | +---w pcr-list* [] 264 | | +---w pcr 265 | | +---w pcr-indices* uint8 266 | | +---w (algo-registry-type) 267 | | +--:(tcg) 268 | | | +---w tcg-hash-algo-id? uint16 269 | | +--:(ietf) 270 | | +---w ietf-ni-hash-algo-id? uint8 271 | +---w log-entry-quantity? uint16 272 +--ro output 273 +--ro system-event-logs 274 +--ro node-data* [node-name tpm_name] 275 +--ro node-name string 276 +--ro node-physical-index? int32 {ietfhw:entity-mib}? 277 +--ro up-time? uint32 278 +--ro tpm_name string 279 +--ro tpm-physical-index? int32 {ietfhw:entity-mib}? 280 +--ro log-result 281 +--ro (log-type) 282 +--:(bios) 283 | +--ro bios-event-logs 284 | +--ro bios-event-entry* [event-number] 285 | +--ro event-number uint32 286 | +--ro event-type? uint32 287 | +--ro pcr-index? uint16 288 | +--ro digest-list* [] 289 | | +--ro (algo-registry-type) 290 | | | +--:(tcg) 291 | | | | +--ro tcg-hash-algo-id? uint16 292 | | | +--:(ietf) 293 | | | +--ro ietf-ni-hash-algo-id? uint8 294 | | +--ro digest* binary 295 | +--ro event-size? uint32 296 | +--ro event-data* uint8 297 +--:(ima) 298 +--ro ima-event-logs 299 +--ro ima-event-entry* [event-number] 300 +--ro event-number uint64 301 +--ro ima-template? string 302 +--ro filename-hint? string 303 +--ro filedata-hash? binary 304 +--ro template-hash-algorithm? string 305 +--ro template-hash? binary 306 +--ro pcr-index? uint16 307 +--ro signature? binary 308 310 2.2. Raw Format 312 313 module ietf-basic-remote-attestation { 314 namespace "urn:ietf:params:xml:ns:yang:ietf-basic-remote-attestation"; 315 prefix "yang-brat"; 317 import ietf-yang-types { 318 prefix yang; 319 } 320 import ietf-hardware { 321 prefix ietfhw; 322 } 323 import ietf-crypto-types { 324 prefix ietfct; 325 } 327 organization 328 "Fraunhofer SIT"; 329 contact 330 "Henk Birkholz 331 Fraunhofer Institute for Secure Information Technology 332 Email: henk.birkholz@sit.fraunhofer.de"; 333 description 334 "A YANG module to enable TPM 1.2 and TPM 2.0 based 335 remote attestation procedures. 336 Copyright (C) Fraunhofer SIT (2019)."; 337 revision "2019-07-08" { 338 description 339 "Second version"; 340 reference 341 "draft-birkholz-rats-basic-yang-module"; 342 } 344 grouping hash-algo { 345 description 346 "A selector for the hashing algorithm"; 347 choice algo-registry-type { 348 mandatory true; 349 description 350 "Unfortunately, both IETF and TCG have registries here. 351 Choose your weapon wisely."; 352 case tcg { 353 description 354 "you chose the east door, the tcg space opens up to 355 you."; 356 leaf tcg-hash-algo-id { 357 type uint16; 358 description 359 "This is an index referencing the TCG Algorithm 360 Registry based on TPM_ALG_ID."; 361 } 362 } 363 case ietf { 364 description 365 "you chose the west door, the ietf space opens up to 366 you."; 367 leaf ietf-ni-hash-algo-id { 368 type uint8; 369 description 370 "This is an index referencing the Named Information 371 Hash Algorithm Registry."; 372 } 373 } 374 } 375 } 377 grouping hash { 378 description 379 "The hash value including hash-algo identifier"; 380 list hash-digests { 381 description 382 "The list of hashes."; 383 container hash-digest { 384 description 385 "A hash value based on a hash algorithm registered by an 386 SDO."; 387 uses hash-algo; 388 leaf hash-value { 389 type binary; 390 description 391 "The binary representation of the hash value."; 392 } 393 } 394 } 395 } 397 grouping nonce { 398 description 399 "A nonce to show freshness and counter replays."; 400 leaf nonce-value { 401 type binary; 402 mandatory true; 403 description 404 "This nonce SHOULD be generated via a registered 405 cryptographic-strength algorithm. In consequence, the length 406 of the nonce depends on the hash algorithm used. The algorithm 407 used in this case is independent from the hash algorithm used to 408 create the hash-value in the response of the attestor."; 409 } 410 } 412 grouping tpm12-pcr-selection { 413 description 414 "A Verifier can request one or more PCR values using its 415 individually created Attestation Key Certificate (AC). 416 The corresponding selection filter is represented in this grouping. 417 Requesting a PCR value that is not in scope of the AC used, detailed 418 exposure via error msg should be avoided."; 419 leaf-list pcr-indices { 420 type uint8; 421 description 422 "The numbers/indexes of the PCRs. At the moment this is limited 423 to 32."; 424 } 425 } 427 grouping tpm20-pcr-selection { 428 description 429 "A Verifier can request one or more PCR values uses its 430 individually created AC. The corresponding selection filter is 431 represented in this grouping. Requesting a PCR value that is not 432 in scope of the AC used, detailed exposure via error msg should 433 be avoided."; 435 list pcr-list { 436 description 437 "For each PCR in this list an individual list of banks 438 (hash-algo) can be requested. It depends on the datastore, if 439 every bank in this grouping is included per PCR (crude), or if 440 each requested bank set is returned for each PCR individually 441 (elegant)."; 442 container pcr { 443 description 444 "The composite of a PCR number and corresponding bank 445 numbers."; 446 leaf-list pcr-indices { 447 type uint8; 448 description 449 "The number of the PCR. At the moment this is limited 450 32"; 451 } 452 uses hash-algo; 453 } 454 } 455 } 457 grouping pcr-selector { 458 description 459 "A Verifier can request the generation of an attestation 460 certificate (a signed public attestation key 461 (non-migratable, tpm-resident) wrt one or more PCR values. 462 The corresponding creation input is represented in this grouping. 463 Requesting a PCR value that is not supported results in an error, 464 detailed exposure via error msg should be avoided."; 465 list pcr-list { 466 description 467 "For each PCR in this list an individual hash-algo can be 468 requested."; 469 container pcr { 470 description 471 "The composite of a PCR number and corresponding bank 472 numbers."; 473 leaf-list pcr-index { 474 type uint8; 475 description 476 "The numbers of the PCRs that are associated with 477 the created key. At the moment the highest number is 32"; 478 } 479 uses hash-algo; 480 } 481 } 482 } 483 grouping tpm12-signature-scheme { 484 description 485 "The signature scheme used to sign the evidence via a TPM 1.2."; 486 leaf TPM_SIG_SCHEME-value { 487 type uint8; 488 mandatory true; 489 description 490 "Selects the signature scheme that is used to sign the TPM quote 491 information response. Allowed values can be found in the table at 492 the bottom of page 32 in the TPM 1.2 Structures specification 493 (Level 2 Revision 116, 1 March 2011)."; 494 } 495 } 497 grouping tpm20-signature-scheme { 498 description 499 "The signature scheme used to sign the evidence."; 500 choice signature-identifier-type { 501 mandatory true; 502 description 503 "There are multiple ways to reference a signature type. 504 This used to select the signature algo to sign the quote 505 information response."; 506 case TPM_ALG_ID { 507 description 508 "This references the indices of table 9 in the TPM 2.0 509 structure specification."; 510 leaf TPM_ALG_ID-value { 511 type uint16; 512 description 513 "The TPM Algo ID."; 514 } 515 } 516 case COSE_Algorithm { 517 description 518 "This references the IANA COSE Algorithms Registry indices. 519 Every index of this registry to be used must be mapable to a 520 TPM_ALG_ID value."; 521 leaf COSE_Algorithm-value { 522 type int32; 523 description 524 "The TPM Algo ID."; 525 } 526 } 527 } 528 } 530 grouping tpm12-attestation-key-identifier { 531 description 532 "A selector for a suitable key identifier for a TPM 1.2."; 533 choice key-identifier { 534 description 535 "Identifier for the attestation key to use for signing 536 attestation evidence."; 537 case public-key { 538 leaf pub-key-id { 539 type binary; 540 description 541 "The value of the identifier for the public key."; 542 } 543 } 544 case TSS_UUID { 545 description 546 "Use a YANG agent generated (and maintained) attestation 547 key UUID that complies with the TSS_UUID datatype of the TCG 548 Software Stack (TSS) Specification, Version 1.10 Golden, 549 August 20, 2003."; 550 container TSS_UUID-value { 551 description 552 "A detailed structure that is used to create the 553 TPM 1.2 native TSS_UUID as defined in the TCG Software 554 Stack (TSS) Specification, Version 1.10 Golden, 555 August 20, 2003."; 556 leaf ulTimeLow { 557 type uint32; 558 description 559 "The low field of the timestamp."; 560 } 561 leaf usTimeMid { 562 type uint16; 563 description 564 "The middle field of the timestamp."; 565 } 566 leaf usTimeHigh { 567 type uint16; 568 description 569 "The high field of the timestamp multiplexed with the 570 version number."; 571 } 572 leaf bClockSeqHigh { 573 type uint8; 574 description 575 "The high field of the clock sequence multiplexed with 576 the variant."; 577 } 578 leaf bClockSeqLow { 579 type uint8; 580 description 581 "The low field of the clock sequence."; 582 } 583 leaf-list rgbNode { 584 type uint8; 585 description 586 "The spatially unique node identifier."; 587 } 588 } 589 } 590 } 591 } 593 grouping tpm20-attestation-key-identifier { 594 description 595 "A selector for a suitable key identifier."; 596 choice key-identifier { 597 description 598 "Identifier for the attestation key to use for signing 599 attestation evidence."; 600 case public-key { 601 leaf pub-key-id { 602 type binary; 603 description 604 "The value of the identifier for the public key."; 605 } 606 } 607 case uuid { 608 description 609 "Use a YANG agent generated (and maintained) attestation 610 key UUID."; 611 leaf uuid-value { 612 type binary; 613 description 614 "The UUID identifying the corresponding public key."; 615 } 616 } 617 } 618 } 620 grouping tpm-name { 621 description 622 "In a system with multiple-TPMs get the data from a specific TPM 623 identified by the name and physical-index."; 624 leaf tpm_name { 625 type string; 626 description 627 "Name of the TPM or All"; 628 } 629 leaf tpm-physical-index { 630 if-feature ietfhw:entity-mib; 631 type int32 { 632 range "1..2147483647"; 633 } 634 config false; 635 description 636 "The entPhysicalIndex for the TPM."; 637 reference 638 "RFC 6933: Entity MIB (Version 4) - entPhysicalIndex"; 639 } 640 } 641 grouping compute-node { 642 description 643 "In a distributed system with multiple compute nodes 644 this is the node identified by name and physical-index."; 645 leaf node-name { 646 type string; 647 description 648 "Name of the compute node or All"; 649 } 650 leaf node-physical-index { 651 if-feature ietfhw:entity-mib; 652 type int32 { 653 range "1..2147483647"; 654 } 655 config false; 656 description 657 "The entPhysicalIndex for the compute node."; 658 reference 659 "RFC 6933: Entity MIB (Version 4) - entPhysicalIndex"; 660 } 661 } 663 grouping tpm12-pcr-info-short { 664 description 665 "This structure is for defining a digest at release when the only 666 information that is necessary is the release configuration."; 667 uses tpm12-pcr-selection; 668 leaf locality-at-release { 669 type uint8; 670 description 671 ".This SHALL be the locality modifier required to release the 672 information (TPM 1.2 type TPM_LOCALITY_SELECTION)"; 673 } 674 leaf digest-at-release { 675 type binary; 676 description 677 "This SHALL be the digest of the PCR indices and PCR values 678 to verify when revealing auth data (TPM 1.2 type 679 TPM_COMPOSITE_HASH)."; 680 } 681 } 683 grouping tpm12-version { 684 description 685 "This structure provides information relative the version of 686 the TPM."; 687 list version { 688 description 689 "This indicates the version of the structure 690 (TPM 1.2 type TPM_STRUCT_VER). This MUST be 1.1.0.0."; 691 leaf major { 692 type uint8; 693 description 694 "Indicates the major version of the structure. 695 MUST be 0x01."; 696 } 697 leaf minor { 698 type uint8; 699 description 700 "Indicates the minor version of the structure. 701 MUST be 0x01."; 702 } 703 leaf revMajor { 704 type uint8; 705 description 706 "Indicates the rev major version of the structure. 707 MUST be 0x00."; 708 } 709 leaf revMinor { 710 type uint8; 711 description 712 "Indicates the rev minor version of the structure. 713 MUST be 0x00."; 714 } 715 } 716 } 718 grouping tpm12-quote-info-common { 719 description 720 "These statements are used in bot quote variants of the TPM 1.2"; 721 leaf fixed { 722 type binary; 723 description 724 "This SHALL always be the string 'QUOT' or 'QUO2' 725 (length is 4 bytes)."; 726 } 727 leaf external-data { 728 type binary; 729 description 730 "160 bits of externally supplied data, typically a nonce."; 731 } 732 leaf signature-size { 733 type uint32; 734 description 735 "The size of TPM 1.2 'signature' value."; 736 } 737 leaf signature { 738 type binary; 739 description 740 "Signature over SHA-1 hash of tpm12-quote-info2'."; 741 } 742 } 744 grouping tpm12-quote-info { 745 description 746 "This structure provides the mechanism for the TPM to quote the 747 current values of a list of PCRs (as used by the TPM_Quote2 748 command)."; 749 uses tpm12-version; 750 leaf digest-value { 751 type binary; 752 description 753 "This SHALL be the result of the composite hash algorithm using 754 the current values of the requested PCR indices 755 (TPM 1.2 type TPM_COMPOSITE_HASH.)"; 756 } 757 } 759 grouping tpm12-quote-info2 { 760 description 761 "This structure provides the mechanism for the TPM to quote the 762 current values of a list of PCRs 763 (as used by the TPM_Quote2 command)."; 764 leaf tag { 765 type uint8; 766 description 767 "This SHALL be TPM_TAG_QUOTE_INFO2."; 768 } 769 uses tpm12-pcr-info-short; 770 } 771 grouping tpm12-cap-version-info { 772 description 773 "TPM returns the current version and revision of the TPM 1.2 ."; 774 list TPM_PCR_COMPOSITE { 775 description 776 "The TPM 1.2 TPM_PCRVALUEs for the pcr-indices."; 777 uses tpm12-pcr-selection; 778 leaf value-size { 779 type uint32; 780 description 781 "This SHALL be the size of the 'tpm12-pcr-value' field 782 (not the number of PCRs)."; 783 } 784 leaf-list tpm12-pcr-value { 785 type binary; 786 description 787 "The list of TPM_PCRVALUEs from each PCR selected in sequence 788 of tpm12-pcr-selection."; 789 } 790 list version-info { 791 description 792 "An optional output parameter from a TPM 1.2 TPM_Quote2."; 793 leaf tag { 794 type uint16; 795 description 796 "The TPM 1.2 version and revision 797 (TPM 1.2 type TPM_STRUCTURE_TAG). 798 This MUST be TPM_CAP_VERSION_INFO (0x0030)"; 799 } 800 uses tpm12-version; 801 leaf spec-level { 802 type uint16; 803 description 804 "A number indicating the level of ordinals supported."; 805 } 806 leaf errata-rev { 807 type uint8; 808 description 809 "A number indicating the errata version of the 810 specification."; 811 } 812 leaf tpm-vendor-id { 813 type binary; 814 description 815 "The vendor ID unique to each TPM manufacturer."; 816 } 817 leaf vendor-specific-size { 818 type uint16; 819 description 820 "The size of the vendor-specific area."; 821 } 822 leaf vendor-specific { 823 type binary; 824 description 825 "Vendor specific information."; 826 } 827 } 828 } 829 } 831 grouping tpm12-pcr-composite { 832 description 833 "The actual values of the selected PCRs (a list of TPM_PCRVALUEs 834 (binary)and associated metadata for TPM 1.2."; 835 list TPM_PCR_COMPOSITE { 836 description 837 "The TPM 1.2 TPM_PCRVALUEs for the pcr-indices."; 838 uses tpm12-pcr-selection; 839 leaf value-size { 840 type uint32; 841 description 842 "This SHALL be the size of the 'tpm12-pcr-value' field 843 (not the number of PCRs)."; 844 } 845 leaf-list tpm12-pcr-value { 846 type binary; 847 description 848 "The list of TPM_PCRVALUEs from each PCR selected in sequence 849 of tpm12-pcr-selection."; 850 } 851 } 852 } 854 grouping node-uptime { 855 description 856 "Uptime in seconds of the node."; 857 leaf up-time { 858 type uint32; 859 description 860 "Uptime in seconds of this node reporting its data"; 861 } 862 } 864 identity log-type { 865 description 866 "The type of logs available."; 868 } 870 identity bios { 871 base log-type; 872 description 873 "Measurement log created by the BIOS/UEFI."; 874 } 876 identity ima { 877 base log-type; 878 description 879 "Measurement log created by IMA."; 880 } 882 grouping log-identifier { 883 description 884 "Identifier for type of log to be retrieved."; 885 leaf log-type { 886 type identityref { 887 base log-type; 888 } 889 mandatory true; 890 description 891 "The corresponding measurement log type identity."; 892 } 893 } 895 grouping boot-event-log { 896 description 897 "Defines an event log corresponding to the event that extended the 898 PCR"; 899 leaf event-number { 900 type uint32; 901 description 902 "Unique event number of this event"; 903 } 904 leaf event-type { 905 type uint32; 906 description 907 "log event type"; 908 } 909 leaf pcr-index { 910 type uint16; 911 description 912 "Defines the PCR index that this event extended"; 913 } 914 list digest-list { 915 description "Hash of event data"; 916 uses hash-algo; 917 leaf-list digest { 918 type binary; 919 description 920 "The hash of the event data"; 921 } 922 } 923 leaf event-size { 924 type uint32; 925 description 926 "Size of the event data"; 927 } 928 leaf-list event-data { 929 type uint8; 930 description 931 "the event data size determined by event-size"; 932 } 933 } 935 grouping ima-event { 936 description 937 "Defines an hash log extend event for IMA measurements"; 938 leaf event-number { 939 type uint64; 940 description 941 "Unique number for this event for sequencing"; 942 } 943 leaf ima-template { 944 type string; 945 description 946 "Name of the template used for event logs 947 for e.g. ima, ima-ng"; 948 } 949 leaf filename-hint { 950 type string; 951 description 952 "File that was measured"; 953 } 954 leaf filedata-hash { 955 type binary; 956 description 957 "Hash of filedata"; 958 } 959 leaf template-hash-algorithm { 960 type string; 961 description 962 "Algorithm used for template-hash"; 963 } 964 leaf template-hash { 965 type binary; 966 description 967 "hash(filedata-hash, filename-hint)"; 968 } 969 leaf pcr-index { 970 type uint16; 971 description 972 "Defines the PCR index that this event extended"; 973 } 974 leaf signature { 975 type binary; 976 description 977 "The file signature"; 978 } 979 } 981 grouping bios-event-log { 982 description 983 "Measurement log created by the BIOS/UEFI."; 984 list bios-event-entry { 985 key event-number; 986 description 987 "Ordered list of TCG described event log 988 that extended the PCRs in the order they 989 were logged"; 990 uses boot-event-log; 991 } 992 } 994 grouping ima-event-log { 995 list ima-event-entry { 996 key event-number; 997 description 998 "Ordered list of ima event logs by event-number"; 999 uses ima-event; 1000 } 1001 description 1002 "Measurement log created by IMA."; 1003 } 1005 grouping event-logs { 1006 description 1007 "A selector for the log and its type."; 1008 choice log-type { 1009 mandatory true; 1010 description 1011 "Event log type determines the event logs content."; 1013 case bios { 1014 description 1015 "BIOS/UEFI event logs"; 1016 container bios-event-logs { 1017 description 1018 "This is an index referencing the TCG Algorithm 1019 Registry based on TPM_ALG_ID."; 1020 uses bios-event-log; 1021 } 1022 } 1023 case ima { 1024 description 1025 "IMA event logs"; 1026 container ima-event-logs { 1027 description 1028 "This is an index referencing the TCG Algorithm 1029 Registry based on TPM_ALG_ID."; 1030 uses ima-event-log; 1031 } 1032 } 1033 } 1034 } 1036 rpc tpm12-challenge-response-attestation { 1037 description 1038 "This RPC accepts the input for TSS TPM 1.2 commands of the 1039 managed device. ComponentIndex from the hardware manager YANG 1040 module to refer to dedicated TPM in composite devices, 1041 e.g. smart NICs, is still a TODO."; 1042 input { 1043 container tpm1-attestation-challenge { 1044 description 1045 "This container includes every information element defined 1046 in the reference challenge-response interaction model for 1047 remote attestation. Corresponding values are based on 1048 TPM 1.2 structure definitions"; 1049 uses tpm12-pcr-selection; 1050 uses nonce; 1051 uses tpm12-signature-scheme; 1052 uses tpm12-attestation-key-identifier; 1053 leaf add-version { 1054 type boolean; 1055 description 1056 "Whether or not to include TPM_CAP_VERSION_INFO; if true, 1057 then TPM_Quote2 must be used to create the response."; 1058 } 1059 uses tpm-name; 1060 } 1062 } 1063 output { 1064 list tpm12-attestation-response { 1065 key tpm_name; 1066 description 1067 "The binary output of TPM 1.2 TPM_Quote/TPM_Quote2, including 1068 the PCR selection and other associated attestation evidence 1069 metadata"; 1070 uses tpm-name; 1071 uses node-uptime; 1072 uses compute-node; 1073 uses tpm12-quote-info-common; 1074 choice tpm12-quote { 1075 mandatory true; 1076 description 1077 "Either a tpm12-quote-info or tpm12-quote-info2, depending 1078 on whether TPM_Quote or TPM_Quote2 was used 1079 (cf. input field add-verson)."; 1080 case tpm12-quote1 { 1081 description 1082 "BIOS/UEFI event logs"; 1083 uses tpm12-quote-info; 1084 uses tpm12-pcr-composite; 1085 } 1086 case tpm12-quote2 { 1087 description 1088 "BIOS/UEFI event logs"; 1089 uses tpm12-quote-info2; 1090 } 1091 } 1092 } 1093 } 1094 } 1096 rpc tpm20-challenge-response-attestation { 1097 description 1098 "This RPC accepts the input for TSS TPM 2.0 commands of the 1099 managed device. ComponentIndex from the hardware manager YANG 1100 module to refer to dedicated TPM in composite devices, 1101 e.g. smart NICs, is still a TODO."; 1102 input { 1103 container tpm20-attestation-challenge { 1104 description 1105 "This container includes every information element defined 1106 in the reference challenge-response interaction model for 1107 remote attestation. Corresponding values are based on 1108 TPM 2.0 structure definitions"; 1109 uses tpm20-pcr-selection; 1110 uses nonce; 1111 uses tpm20-signature-scheme; 1112 uses tpm20-attestation-key-identifier; 1113 } 1114 list tpms { 1115 key tpm_name; 1116 description 1117 "TPMs to fetch the attestation information."; 1118 uses tpm-name; 1119 } 1120 } 1121 output { 1122 list tpm20-attestation-response { 1123 key tpm_name; 1124 description 1125 "The binary output of TPM2b_Quote. An TPMS_ATTEST structure 1126 including a length, encapsulated in a signature"; 1127 uses tpm-name; 1128 uses node-uptime; 1129 uses compute-node; 1130 container tpms-attest { 1131 leaf pcrdigest { 1132 type binary; 1133 description 1134 "split out value of TPMS_QUOTE_INFO for convenience"; 1135 } 1136 leaf tpms-attest-result { 1137 type binary; 1138 description 1139 "The complete TPM generate structure including 1140 signature."; 1141 } 1142 leaf tpms-attest-result-length { 1143 type uint32; 1144 description 1145 "Length of attest result provided by the TPM structure."; 1146 } 1147 description 1148 "A composite of value and length and list of selected 1149 pcrs (original name: [type]attested)"; 1150 } 1151 leaf tpmt-signature { 1152 type binary; 1153 description 1154 "Split out value of the signature for convenience. 1155 TODO: check for length values that complent binary value 1156 data node leafs."; 1157 } 1159 } 1160 } 1161 } 1163 rpc basic-trust-establishment { 1164 description 1165 "This RPC creates a tpm-resident, non-migratable key to be used 1166 in TPM_Quote commands, an attestation certificate."; 1167 input { 1168 uses nonce; 1169 uses tpm20-signature-scheme; 1170 uses tpm-name; 1171 leaf certificate-name { 1172 type string; 1173 description 1174 "An arbitrary name for the identity certificate chain 1175 requested."; 1176 } 1177 } 1178 output { 1179 list attestation-certificates { 1180 key tpm_name; 1181 description 1182 "Attestation Certificate data from a TPM identified by the TPM 1183 name"; 1184 uses tpm-name; 1185 uses node-uptime; 1186 uses compute-node; 1187 leaf certificate-name { 1188 type string; 1189 description 1190 "An arbitrary name for this identity certificate or 1191 certificate chain."; 1192 } 1193 leaf attestation-certificate { 1194 type ietfct:end-entity-cert-cms; 1195 description 1196 "The binary signed certificate chain data for this identity 1197 certificate."; 1198 } 1199 uses tpm20-attestation-key-identifier; 1200 } 1201 } 1202 } 1204 rpc log-retrieval { 1205 description 1206 "Logs Entries are either identified via indices or via providing 1207 the last line received. The number of lines returned can be 1208 limited. The type of log is a choice that can be augmented."; 1209 input { 1210 list log-selector { 1211 key node-name; 1212 description 1213 "Selection of log entries to be reported."; 1214 uses compute-node; 1215 choice index-type { 1216 description 1217 "Last log entry received, log index number, or timestamp."; 1218 case last-entry { 1219 description 1220 "The last entry of the log already retrieved."; 1221 leaf last-entry-value { 1222 type binary; 1223 description 1224 "Content of an log event which matches 1:1 with a 1225 unique event record contained within the log. Log 1226 entries subsequent to this will be passed to the 1227 requester. Note: if log entry values are not unique, 1228 this MUST return an error."; 1229 } 1230 } 1231 case index { 1232 description 1233 "Numeric index of the last log entry retrieved, or zero."; 1234 leaf index-number { 1235 type uint64; 1236 description 1237 "The numeric index number of a log entry. Zero means 1238 to start at the beginning of the log. Entries 1239 subsequent to this will be passed to the 1240 requester."; 1241 } 1242 } 1243 case timestamp { 1244 leaf timestamp { 1245 type yang:date-and-time; 1246 description 1247 "Timestamp from which to start the extraction. The next 1248 log entry subsequent to this timestamp is to be sent."; 1249 } 1250 description 1251 "Timestamp from which to start the extraction."; 1252 } 1253 } 1254 } 1255 uses log-identifier; 1256 uses tpm20-pcr-selection; 1257 leaf log-entry-quantity { 1258 type uint16; 1259 description 1260 "The number of log entries to be returned. If omitted, it 1261 means all of them."; 1262 } 1263 } 1264 output { 1265 container system-event-logs { 1266 description 1267 "The requested data of the measurement event logs"; 1268 list node-data { 1269 key "node-name tpm_name"; 1270 description 1271 "Event logs of a node in a distributed system 1272 identified by the node name"; 1273 uses compute-node; 1274 uses node-uptime; 1275 uses tpm-name; 1276 container log-result { 1277 description 1278 "The requested entries of the corresponding log."; 1279 uses event-logs; 1280 } 1281 } 1282 } 1283 } 1284 } 1286 container rats-support-structures { 1287 config false; 1288 description 1289 "The datastore definition enabling verifiers or relying 1290 parties to discover the information necessary to use the 1291 remote attestation RPCs appropriately."; 1292 leaf-list supported-algos { 1293 type uint16; 1294 description 1295 "Supported TPM_ALG_ID values for the TPM in question. 1296 Will include ComponentIndex soon."; 1297 } 1298 list tpms { 1299 key tpm_name; 1300 uses tpm-name; 1301 description 1302 "A list of TPMs in this composite 1303 device that rats can be conducted with."; 1304 list certificates { 1305 description 1306 "The TPM's endorsement-certificate."; 1307 container certificate { 1308 leaf certificate-name { 1309 type string; 1310 description 1311 "An arbitrary name for this identity certificate or 1312 certificate chain."; 1313 } 1314 leaf certificate-type { 1315 type enumeration { 1316 enum endorsement-cert { 1317 value 0; 1318 description 1319 "EK Cert type."; 1320 } 1321 enum attestation-cert { 1322 value 1; 1323 description 1324 "AK Cert type."; 1325 } 1326 } 1327 description "Type of this certificate"; 1328 } 1329 leaf certificate-value { 1330 type ietfct:end-entity-cert-cms; 1331 description 1332 "The binary signed public endorsement key (EK), 1333 attestation key(AK) and corresponding assertions 1334 (EK,AK Certificate). In a TPM 2.0 the EK,AK Certificate 1335 resides in a well-defined NVRAM location by the TPM 1336 vendor."; 1337 } 1338 description 1339 "Two kinds of certificates can be accessed via this 1340 statement. An Attestation Key Certificate and a 1341 Endorsement Key Certificate."; 1342 } 1343 } 1344 } 1345 list compute-nodes { 1346 key node-name; 1347 uses compute-node; 1348 description 1349 "A list names of hardware components in this composite 1350 device that rats can be conducted with."; 1352 } 1353 } 1354 } 1355 1357 3. IANA considerations 1359 This document will include requests to IANA: 1361 To be defined yet. 1363 4. Security Considerations 1365 There are always some. 1367 5. Acknowledgements 1369 Not yet. 1371 6. Change Log 1373 Changes from version 00 to version 01: 1375 o Addressed author's comments 1377 o Extended complementary details about attestation-certificates 1379 o Relabeled chunk-size to log-entry-quantity 1381 o Relabeled location with compute-node or tpm-name where appropriate 1383 o Added a valid entity-mib physical-index to compute-node and tpm- 1384 name to map it back to hardware inventory 1386 o Relabeled name to tpm_name 1388 o Removed event-string in last-entry 1390 7. References 1392 7.1. Normative References 1394 [I-D.birkholz-rats-reference-interaction-model] 1395 Birkholz, H. and M. Eckel, "Reference Interaction Model 1396 for Challenge-Response-based Remote Attestation", draft- 1397 birkholz-rats-reference-interaction-model-00 (work in 1398 progress), March 2019. 1400 [I-D.ietf-netconf-crypto-types] 1401 Watsen, K. and H. Wang, "Common YANG Data Types for 1402 Cryptography", draft-ietf-netconf-crypto-types-10 (work in 1403 progress), July 2019. 1405 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1406 Requirement Levels", BCP 14, RFC 2119, 1407 DOI 10.17487/RFC2119, March 1997, 1408 . 1410 7.2. Informative References 1412 [I-D.birkholz-attestation-terminology] 1413 Birkholz, H., Wiseman, M., and H. Tschofenig, "Reference 1414 Terminology for Remote Attestation Procedures", draft- 1415 birkholz-attestation-terminology-02 (work in progress), 1416 July 2018. 1418 Authors' Addresses 1420 Henk Birkholz 1421 Fraunhofer SIT 1422 Rheinstrasse 75 1423 Darmstadt 64295 1424 Germany 1426 Email: henk.birkholz@sit.fraunhofer.de 1428 Michael Eckel 1429 Fraunhofer SIT 1430 Rheinstrasse 75 1431 Darmstadt 64295 1432 Germany 1434 Email: michael.eckel@sit.fraunhofer.de 1436 Shwetha Bhandari 1437 Cisco Systems 1439 Email: shwethab@cisco.com 1441 Bill Sulzen 1442 Cisco Systems 1444 Email: bsulzen@cisco.com 1445 Eric Voit 1446 Cisco Systems 1448 Email: evoit@cisco.com 1450 Liang Xia (Frank) 1451 Huawei Technologies 1452 101 Software Avenue, Yuhuatai District 1453 Nanjing, Jiangsu 210012 1454 China 1456 Email: Frank.Xialiang@huawei.com 1458 Tom Laffey 1459 Hewlett Packard Enterprise 1461 Email: tom.laffey@hpe.com 1463 Guy C. Fedorkow 1464 Juniper Networks 1465 10 Technology Park Drive 1466 Westford, Massachusetts 01886 1468 Email: gfedorkow@juniper.net