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