idnits 2.17.1 draft-birkholz-rats-network-device-subscription-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 297 has weird spacing: '...e-value bin...' == Line 394 has weird spacing: '...-number uin...' == Line 484 has weird spacing: '...r-index pcr...' -- The document date (March 31, 2021) is 1122 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 (-22) exists of draft-ietf-rats-architecture-08 ** 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-06 ** 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') == Outdated reference: A later version (-22) exists of draft-ietf-rats-yang-tpm-charra-05 == Outdated reference: A later version (-07) exists of draft-birkholz-rats-tuda-04 Summary: 2 errors (**), 0 flaws (~~), 8 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 Fraunhofer SIT 4 Intended status: Standards Track E. Voit 5 Expires: October 2, 2021 Cisco 6 W. Pan 7 Huawei 8 March 31, 2021 10 Attestation Event Stream Subscription 11 draft-birkholz-rats-network-device-subscription-02 13 Abstract 15 This document defines how to subscribe to an Event Stream of 16 attestation related Evidence on TPM-based network devices. 18 Status of This Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at https://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on October 2, 2021. 35 Copyright Notice 37 Copyright (c) 2021 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (https://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 53 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 54 2.1. Requirements Notation . . . . . . . . . . . . . . . . . . 3 55 3. Operational Model . . . . . . . . . . . . . . . . . . . . . . 3 56 3.1. Sequence Diagram . . . . . . . . . . . . . . . . . . . . 3 57 3.2. Continuously Verifying Freshness . . . . . . . . . . . . 5 58 3.2.1. TPM 1.2 Quote . . . . . . . . . . . . . . . . . . . . 5 59 3.2.2. TPM 2 Quote . . . . . . . . . . . . . . . . . . . . . 5 60 4. Remote Attestation Event Stream . . . . . . . . . . . . . . . 6 61 4.1. Subscription to the Event Stream . . . . . 7 62 4.2. Replaying a history of previous TPM extend operations . . 7 63 4.2.1. TPM2 Heartbeat . . . . . . . . . . . . . . . . . . . 8 64 4.3. YANG notifications placed on the Event 65 Stream . . . . . . . . . . . . . . . . . . . . . . . . . 8 66 4.3.1. pcr-extend . . . . . . . . . . . . . . . . . . . . . 8 67 4.3.2. tpm12-attestation . . . . . . . . . . . . . . . . . . 10 68 4.3.3. tpm20-attestation . . . . . . . . . . . . . . . . . . 10 69 4.4. Filtering Evidence at the Attester . . . . . . . . . . . 11 70 4.5. Replaying previous PCR Extend events . . . . . . . . . . 11 71 4.6. Configuring the Event Stream . . . . . . . 11 72 5. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 12 73 6. Security Considerations . . . . . . . . . . . . . . . . . . . 19 74 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 75 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 19 76 8.1. Normative References . . . . . . . . . . . . . . . . . . 19 77 8.2. Informative References . . . . . . . . . . . . . . . . . 20 78 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 20 79 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 21 80 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 21 82 1. Introduction 84 [I-D.ietf-rats-tpm-based-network-device-attest] and 85 [I-D.ietf-rats-yang-tpm-charra] define the operational prerequisites 86 and a YANG Model for the acquisition of Evidence from a TPM-based 87 network device. However there is a limitation inherant in the 88 challenge-response interaction models upon which these documents are 89 based. This limitation is that it is up to the Verifier to request 90 Evidence. The result is that the interval between the occurrence of 91 a security event, and the event's visibility within the Relying Party 92 can be unacceptably long. 94 This limitation results in two adverse effects: 96 1. Evidence is not streamed to an interested Verifier as soon as it 97 is generated. 99 2. If it were to be streamed, the Evidence is not appraisable for 100 freshness. 102 This specification addresses the first adverse effect by enabling a 103 Verifier to subscribe via [RFC8639] to an Event Stream 104 which exists upon the Attester. When subscribed, the Attester will 105 continuously stream a requested set of Evidence to the Verifier. 107 The second adverse effect results from the nonce based challenge- 108 response of [I-D.ietf-rats-yang-tpm-charra]. In that document an 109 Attester must wait for a new nonce from a Verifier before it 110 generates a new TPM Quote. To address delays resulting from such a 111 wait, this specification enables freshness to be asserted 112 asynchronously. 114 By removing these two adverse effects, it becomes possible for a 115 Verifier to continously maintain an appraisal of the Attested device 116 without relying on continous polling. 118 2. Terminology 120 The following terms are imported from [I-D.ietf-rats-architecture]: 121 Attester, Evidence, Relying Party, and Verifier. Also imported are 122 the time definitions time(VG), time(NS), time(EG), time(RG), and 123 time(RA) from that document's Appendix A. The following terms at 124 imported from [RFC8639]: Event Stream, Subscription, Event Stream 125 Filter, Dynamic Subscription. 127 2.1. Requirements Notation 129 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 130 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 131 "OPTIONAL" in this document are to be interpreted as described in 132 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 133 capitals, as shown here. 135 3. Operational Model 137 3.1. Sequence Diagram 139 Figure 1 below is a sequence diagram which updates Figure 5 of 140 [I-D.ietf-rats-tpm-based-network-device-attest]. This sequence 141 diagram replaces the [I-D.ietf-rats-tpm-based-network-device-attest] 142 challenge-response interaction model with an [RFC8639] Dynamic 143 Subscription to an Event Stream. The contents of the 144 Event Stream are defined below within Section 4. 146 .----------. .--------------------------. 147 | Attester | | Relying Party / Verifier | 148 '----------' '--------------------------' 149 time(VG) | 150 |<---------establish-subscription()--time(NS) 151 | | 152 time(EG) | 153 |--filter()---------------------------->| 154 |-- or ------>| 155 | | 156 | verify time(EG) Evidence @ time(RG,RA) 157 | | 158 ~ ~ 159 time(VG',EG') | 160 |--filter()---------------------------->| 161 |-- or ------>| 162 | | 163 | verify time(EG') Evidence @ time(RG',RA') 165 Figure 1: YANG Subscription Model for Remote Attestation 167 o time(VG,RG,RA) are identical to the corresponding time definitions 168 from [I-D.ietf-rats-tpm-based-network-device-attest]. 169 Time(RG',RA') are subsequent instances of the corresponding times. 171 o time(RG',RA') are subsequent instances of the corresponding times 172 from Figure 5 of [I-D.ietf-rats-tpm-based-network-device-attest]. 174 o time(NS): The Verifier generates a nonce and makes an [RFC8639] 175 request. This request also includes the 176 augmentations defined in this document's YANG model. Key 177 subscription RPC parameters include: 179 * the nonce 181 * a set of PCRs of interest which the Verifier wants to appraise 183 * an optional filter which can reduce the logged events on the 184 stream pushed to the Verifier. 186 o time(EG) - An initial response of Evidence is returned to the 187 Verifier. This includes: 189 * A replay of filtered log entries which have extended into a PCR 190 of interest since boot are sent in the 191 notification. 193 * A signed TPM quote that contains at least the PCRs from the 194 RPC are included in a 195 or ). This quote must 196 have included the nonce provided at time(NS). 198 o time(VG',EG') - This occurs when a PCR is extended subsequent to 199 time(EG). Immediately after the extension, the following 200 information needs to be pushed to the Verifier: 202 * Any values extended into a PCR of interest, and 204 * a signed TPM Quote showing the result the PCR extension. 206 3.2. Continuously Verifying Freshness 208 As there is no new Verifier nonce provided at time(EG'), it is 209 important to validate the freshness of TPM Quotes which are delivered 210 at that time. The method of doing this verification will vary based 211 on the capabilities of the TPM cryptoprocessor used. 213 3.2.1. TPM 1.2 Quote 215 The [RFC8639] notification format includes the object. 216 This can be used to determine the amount of time subsequent to the 217 initial subscription each notification was sent. However this time 218 is not part of the signed results which are returned from the Quote, 219 and therefore is not trustworthy as objects returned in the Quote. 220 Therefore a Verifier MUST periodically issue a new nonce, and receive 221 this nonce within a TPM quote response in order to ensure the 222 freshness of the results. This can be done using the RPC from 224 [I-D.ietf-rats-yang-tpm-charra]. 226 3.2.2. TPM 2 Quote 228 When the Attester includes a TPM2 compliant cryptoprocessor, internal 229 time-related counters are included within the signed TPM Quote. By 230 including a initial nonce in the [RFC8639] subscription request, 231 fresh values for these counters are pushed as part of the first TPM 232 Quote returned to the Verifier. And then as shown by 233 [I-D.birkholz-rats-tuda], subsequent TPM Quotes delivered to the 234 Verifier can the be appraised for freshness based on the predictable 235 incrementing of these time-related countersr. 237 The relevant internal time-related counters defined within [TPM2.0] 238 can be seen within . These counters include the 239 , , and objects. The rules 240 for appraising these objects are as follows: 242 o If the has incremented for no more than the same duration 243 as both the and the Verifier's internal time since the 244 initial time(EG) and any previous time(EG'), then the TPM Quote 245 may be considered fresh. Note that [TPM2.0] allows for +/- 15% 246 clock drift. However many chips significantly improve on this 247 maximum drift. If available, chip specific maximum drifts SHOULD 248 be considered during the appraisal process. 250 o If the , has incremented. The 251 existing subscription MUST be terminated, and a new SHOULD be generated. 254 o If a TPM Quote on any subscribed PCR has not been pushed to the 255 Verifier for a duration of an Attester defined heartbeat interval, 256 then a new TPM Quote notification should be sent to the Verifier. 257 This may often be the case, as certain PCRs might be infrequently 258 updated. 260 .----------. .--------------------------. 261 | Attester | | Relying Party / Verifier | 262 '----------' '--------------------------' 263 time(VG',EG') | 264 |------------------------------->| 265 | : | 266 ~ Heartbeat interval ~ 267 | : | 268 time(EG') : | 269 |------------------------------->| 270 | | 272 4. Remote Attestation Event Stream 274 The Event Stream is an [RFC8639] compliant Event Stream 275 which is defined within this section and within the YANG Module of 276 [I-D.ietf-rats-yang-tpm-charra]. This Event Stream contains YANG 277 notifications which carry Evidence which assists a Verifier in 278 appraising the Trustworthiness Level of an Attester. Data Nodes 279 within Section 4.6 allow the configuration of this Event Stream's 280 contents on an Attester. 282 This Event Stream may only be exposed on Attesters 283 supporting [I-D.ietf-rats-tpm-based-network-device-attest]. As with 284 [I-D.ietf-rats-tpm-based-network-device-attest], it is up to the 285 Verifier to understand which types of cryptoprocessors and keys are 286 acceptable. 288 4.1. Subscription to the Event Stream 290 To establish a subscription to an Attester in a way which provides 291 provably fresh Evidence, initial randomness must be provided to the 292 Attester. This is done via the augmentation of a into 293 [RFC8639] the RPC. Additionally, a Verifier 294 must ask for PCRs of interest from a platform. 296 augment /sn:establish-subscription/sn:input: 297 +---w nonce-value binary 298 +---w pcr-index* tpm:pcr 300 The result of the subscription will be that passing of the following 301 information: 303 1. and notifications which 304 include the provided . These attestation 305 notifications MUST at least include all the 306 requested in the RPC. 308 2. a series of notifications which reference the 309 requested PCRs on all TPM based cryptoprocessors on the Attester. 311 3. and notifications 312 generated within a few seconds of the notifications. 313 These attestation notifications MUST at least include any PCRs 314 extended. 316 If the Verifier does not want to see the logged extend operations for 317 all PCRs available from an Attester, an Event Stream Filter should be 318 applied. This filter will remove Evidence from any PCRs which are 319 not interesting to the Verifier. 321 4.2. Replaying a history of previous TPM extend operations 323 Unless it is relying on Known Good Values, a Verifier will need to 324 acquire a history of PCR extensions since the Attester has been 325 booted. This history may be requested from the Attester as part of 326 the RPC. This request is accomplished by 327 placing a very old within the original RPC 328 request. As the very old will pre-date the time 329 of Attester boot, a will be returned in 330 the RPC response, indicating when the 331 Attester booted. Immediately following the response (and before the 332 notifications above) one or more notifications which 333 document all extend operations which have occurred for the requested 334 PCRs since boot will be sent. Many extend operations to a single PCR 335 index on a single TPM SHOULD be included within a single 336 notification. 338 Note that if a Verifier has a partial history of extensions, the 339 can be adjusted so that known extensions are not 340 forwarded. 342 The end of this history replay will be indicated with the [RFC8639] 343 notification. For more on this sequence, see 344 Section 2.4.2.1 of [RFC8639]. 346 After the notification is provided, a TPM Quote 347 will be requested and the result passed to the Verifier via a 348 and notification. If there 349 have been any additional extend operations which have changed a 350 subscribed PCR value in this quote, these MUST be pushed to the 351 Verifier before the and 352 notification. 354 At this point the Verifier has sufficient Evidence appraise the 355 reported extend operations for each PCR, as well compare the expected 356 value of the PCR value against that signed by the TPM. 358 4.2.1. TPM2 Heartbeat 360 For TPM2, make sure that every requested PCR is sent within an 361 no less frequently than once per heartbeat 362 interval. This MAY be done with a single 363 notification that includes all requested PCRs every heartbeat 364 interval. This MAY be done with several 365 notifications at different times during that heartbeat interval. 367 4.3. YANG notifications placed on the Event Stream 369 4.3.1. pcr-extend 371 This notification documents when a subscribed PCR is extended within 372 a single TPM cryptoprocessor. It SHOULD be emmitted no less than the 373 after an the PCR is first extended. (The reason 374 for the marshalling is that it is quite possible that multiple 375 extensions to the same PCR have been made in quick succession, and 376 these should be reflected in the same notification.) This 377 notification MUST be emmitted prior to a or 378 notification which has included and signed the 379 results of any specific PCR extension. If pcr extending events occur 380 during the generation of the or 381 notification, the marshalling period MUST be 382 extended so that a new is not sent until the 383 corresponding notifications have been sent. 385 +---n pcr-extend 386 +--ro certificate-name certificate-name-ref 387 +--ro pcr-index-changed* tpm:pcr 388 +--ro attested-event* [] 389 +--ro attested-event 390 +--ro extended-with binary 391 +--ro (event-details)? 392 +--:(bios-event-log) 393 | +--ro bios-event-entry* [event-number] 394 | +--ro event-number uint32 395 | +--ro event-type? uint32 396 | +--ro pcr-index? pcr 397 | +--ro digest-list* [] 398 | | +--ro hash-algo? identityref 399 | | +--ro digest* binary 400 | +--ro event-size? uint32 401 | +--ro event-data* uint8 402 +--:(ima-event-log) 403 | +--ro ima-event-entry* [event-number] 404 | +--ro event-number uint64 405 | +--ro ima-template? string 406 | +--ro filename-hint? string 407 | +--ro filedata-hash? binary 408 | +--ro filedata-hash-algorithm? string 409 | +--ro template-hash-algorithm? string 410 | +--ro template-hash? binary 411 | +--ro pcr-index? pcr 412 | +--ro signature? binary 413 +--:(netequip-boot-event-log) 414 +--ro boot-event-entry* [event-number] 415 +--ro event-number uint64 416 +--ro filename-hint? string 417 +--ro filedata-hash? binary 418 +--ro filedata-hash-algorithm? string 419 +--ro file-version? string 420 +--ro file-type? string 421 +--ro pcr-index? pcr 423 Each MUST include one or more values being extended into 424 the PCR. These are passed within the object. For 425 each extension, details of the event SHOULD be provided within the 426 object. The format of any included 427 is identified by the . This document includes two YANG 428 structures which may be inserted into the . These two 429 structures are: . 431 Implementations wanting to provide additional documentation of a type 432 of PCR extension may choose to define additional YANG structures 433 which can be placed into . 435 4.3.2. tpm12-attestation 437 This notification contains an instance of a TPM1.2 style signed 438 cryptoprocessor measurement. It is supplemented by Attester 439 information which is not signed. This notification is generated and 440 emitted from an Attester when at least one PCR identified within the 441 subscribed has changed from the previous 442 notification. This notification MUST NOT include 443 the results of any PCR extensions not previously reported by a . This notification SHOULD be emitted as soon as a TPM Quote 445 can extract the latest PCR hashed values. This notification MUST be 446 emitted prior to a subsequent . 448 +---n tpm12-attestation {taa:TPM12}? 449 +--ro certificate-name tpm:certificate-name-ref 450 +--ro up-time? uint32 451 +--ro TPM_QUOTE2? binary 452 +--ro TPM12-hash-algo? identityref 453 +--ro unsigned-pcr-values* [] 454 +--ro pcr-index* tpm:pcr 455 +--ro pcr-value* binary 457 All YANG objects above are defined within 458 [I-D.ietf-rats-yang-tpm-charra]. The is not 459 replayable. 461 4.3.3. tpm20-attestation 463 This notification contains an instance of TPM2 style signed 464 cryptoprocessor measurements. It is supplemented by Attester 465 information which is not signed. This notification is generated at 466 two points in time: 468 o every time at least one PCR has changed from a previous 469 tpm20-attestation. In this case, the notification SHOULD be 470 emitted within 10 seconds of the corresponding being 471 sent: 473 o after a locally configurable minimum heartbeat period since a 474 previous tpm20-attestation was sent. 476 +---n tpm20-attestation {taa:TPM20}? 477 +--ro certificate-name tpm:certificate-name-ref 478 +--ro TPMS_QUOTE_INFO binary 479 +--ro quote-signature? binary 480 +--ro up-time? uint32 481 +--ro unsigned-pcr-values* [] 482 +--ro TPM20-hash-algo? identityref 483 +--ro pcr-values* [pcr-index] 484 +--ro pcr-index pcr 485 +--ro pcr-value? binary 487 All YANG objects above are defined within 488 [I-D.ietf-rats-yang-tpm-charra]. The is not 489 replayable. 491 4.4. Filtering Evidence at the Attester 493 It can be useful _not_ to receive all Evidence related to a PCR. An 494 example of this is would be a when a Verifier maintains known good 495 values of a PCR. In this case, it is not necessary to send each 496 extend operation. 498 To accomplish this reduction, when an RFC8639 RPC is sent, a as per RFC8639, 500 Section 2.2 can be set to discard a notification when 501 the is uninteresting to the verifier. 503 4.5. Replaying previous PCR Extend events 505 To verify the value of a PCR, a Verifier must either know that the 506 value is a known good value [KGV] or be able to reconstruct the hash 507 value by viewing all the PCR-Extends since the Attester rebooted. 508 Wherever a hash reconstruction might be needed, the 509 Event Stream MUST support the RFC8639 feature. Through the 510 feature, it is possible for a Verifier to retrieve and 511 sequentially hash all of the PCR extending events since an Attester 512 booted. And thus, the Verifier has access to all the evidence needed 513 to verify a PCR's current value. 515 4.6. Configuring the Event Stream 517 Figure 2 is tree diagram which exposes the operator configurable 518 elements of the Event Stream. This allows an Attester 519 to select what information should be available on the stream. A 520 fetch operation also allows an external device such as a Verifier to 521 understand the current configuration of stream. 523 Almost all YANG objects below are defined via reference from 524 [I-D.ietf-rats-yang-tpm-charra]. There is one object which is new 525 with this model however. defines the maximum amount 526 of time which should pass before a subscriber to the Event Stream 527 should get a notification from devices which 528 contain a TPM2. 530 augment /tpm:rats-support-structures: 531 +--rw marshalling-period? uint8 532 +--rw tpm12-subscribed-signature-scheme? 533 | -> ../tpm:attester-supported-algos/tpm12-asymmetric-signing 534 | {taa:TPM12}? 535 +--rw tpm20-subscribed-signature-scheme? 536 | -> ../tpm:attester-supported-algos/tpm20-asymmetric-signing 537 | {taa:TPM20}? 538 +--rw tpm20-subscription-heartbeat? uint16 539 augment /tpm:rats-support-structures/tpm:tpms: 540 +--rw subscription-aik? tpm:certificate-name-ref 541 +--rw (subscribable)? 542 +--:(tpm12-stream) {taa:TPM12}? 543 | +--rw TPM12-hash-algo? identityref 544 | +--rw tpm12-pcr-index* tpm:pcr 545 +--:(tpm20-stream) {taa:TPM20}? 546 +--rw TPM20-hash-algo? identityref 547 +--rw tpm20-pcr-index* tpm:pcr 549 Figure 2: Configuring the \ Event Stream 551 5. YANG Module 553 This YANG module imports modules from [I-D.ietf-rats-yang-tpm-charra] 554 and [RFC8639]. It is also work-in-progress. 556 ietf-rats-attestation-stream@2020-12-15.yang 557 module ietf-tpm-remote-attestation-stream { 558 yang-version 1.1; 559 namespace 560 "urn:ietf:params:xml:ns:yang:ietf-tpm-remote-attestation-stream"; 561 prefix tras; 563 import ietf-subscribed-notifications { 564 prefix sn; 565 reference 566 "RFC 8639: Subscription to YANG Notifications"; 567 } 568 import ietf-tpm-remote-attestation { 569 prefix tpm; 570 reference 571 "draft-ietf-rats-yang-tpm-charra"; 572 } 573 import ietf-tcg-algs { 574 prefix taa; 575 } 577 organization "IETF"; 578 contact 579 "WG Web: 580 WG List: 582 Editor: Eric Voit 583 "; 585 description 586 "This module contains conceptual YANG specifications for 587 subscribing to attestation streams being generated from TPM chips. 589 Copyright (c) 2020 IETF Trust and the persons identified 590 as authors of the code. All rights reserved. 592 Redistribution and use in source and binary forms, with 593 or without modification, is permitted pursuant to, and 594 subject to the license terms contained in, the Simplified 595 BSD License set forth in Section 4.c of the IETF Trust's 596 Legal Provisions Relating to IETF Documents 597 (https://trustee.ietf.org/license-info). 599 Redistribution and use in source and binary forms, with or 600 without modification, is permitted pursuant to, and subject to 601 the license terms contained in, the Simplified BSD License set 602 forth in Section 4.c of the IETF Trust's Legal Provisions 603 Relating to IETF Documents 604 (https://trustee.ietf.org/license-info). 606 This version of this YANG module is part of RFC XXXX 607 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC 608 itself for full legal notices. 610 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 611 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 612 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 613 are to be interpreted as described in BCP 14 (RFC 2119) 614 (RFC 8174) when, and only when, they appear in all 615 capitals, as shown here."; 617 revision 2020-12-15 { 618 description 619 "Initial version."; 620 reference 621 "draft-birkholz-rats-network-device-subscription"; 622 } 624 /* 625 * IDENTITIES 626 */ 628 identity pcr-unsubscribable { 629 base sn:establish-subscription-error; 630 description 631 "Requested PCR is subscribable by the Attester."; 632 } 634 /* 635 * Groupings 636 */ 638 grouping heartbeat { 639 description 640 "Allows an Attester to push verifiable, current TPM PCR values 641 even when there have been no recent changes to PCRs."; 642 leaf tpm20-subscription-heartbeat { 643 type uint16; 644 description 645 "Number of seconds before the Attestation stream should send a 646 new notification with a fresh quote. This allows confirmation 647 that the PCR values haven't changed since the last 648 tpm20-attestation."; 649 } 650 } 652 /* 653 * RPCs 654 */ 656 augment "/sn:establish-subscription/sn:input" { 657 when 'derived-from-or-self(sn:stream, "attestation")'; 658 description 659 "This augmentation adds a nonce to as a subscription parameters 660 that apply specifically to datastore updates to RPC input."; 661 uses tpm:nonce; 662 leaf-list pcr-index { 663 type tpm:pcr; 664 min-elements 1; 665 description 666 "The numbers/indexes of the PCRs. This will act as a filter for 667 the subscription so that 'tpm-extend' notifications related to 668 non-requested PCRs will not be sent to a subscriber."; 669 } 670 } 672 /* 673 * NOTIFICATIONS 674 */ 676 notification pcr-extend { 677 description 678 "This notification indicates that one or more PCRs have been 679 extended within a TPM based cryptoprocessor. In less than the 680 'marshalling-period', it MUST be followed with either a 681 corresponding tpm12-attestation or tpm20-attestation notification 682 which exposes the result of the PCRs updated."; 683 uses tpm:certificate-name-ref; 684 leaf-list pcr-index-changed { 685 type tpm:pcr; 686 min-elements 1; 687 description 688 "The number of each PCR extended. This list MUST contain the 689 set of PCRs descibed within the event log details. This leaf 690 can be derived from the list of attested events, but exposing 691 it here allows for easy filtering of the notifications of 692 interest to a verifier."; 693 } 694 list attested-event { 695 description 696 "A set of events which extended an Attester PCR. The sequence 697 of elements represented in list must match the sequence of 698 events placed into the TPM's PCR."; 699 container attested-event { 700 description 701 "An instance of an event which extended an Attester PCR"; 702 leaf extended-with { 703 type binary; 704 mandatory true; 705 description 706 "Information extending the PCR."; 707 } 708 choice event-details { 709 description 710 "Contains the event happened the Attester thought 711 was worthy of recording in a PCR. 713 choices are of types defined by the identityref 714 base tpm:attested_event_log_type"; 716 case bios-event-log { 717 description 718 "BIOS/UEFI event log format"; 719 uses tpm:bios-event-log; 720 } 721 case ima-event-log { 722 description 723 "IMA event log format"; 724 uses tpm:ima-event-log; 725 } 726 case netequip-boot-event-log { 727 description 728 "IMA event log format"; 729 uses tpm:network-equipment-boot-event-log; 730 } 731 } 732 } 733 } 734 } 736 notification tpm12-attestation { 737 if-feature "taa:TPM12"; 738 description 739 "Contains an instance of TPM1.2 style signed cryptoprocessor 740 measurements. It is supplemented by unsigned Attester 741 information."; 742 leaf certificate-name { 743 type tpm:certificate-name-ref; 744 mandatory true; 745 description 746 "Allows a TPM quote to be associated with a certificate."; 747 } 748 uses tpm:tpm12-attestation; 749 uses tpm:TPM12-hash-algo; 750 list unsigned-pcr-values { 751 description 752 "Allows notifications to be filtered by PCR number or 753 PCR value based on via YANG related mechanisms such as PATH. 754 This is done without requiring the filtering structure to be 755 applied against TCG structured data."; 756 leaf-list pcr-index { 757 type tpm:pcr; 758 description 759 "PCR index number."; 760 min-elements 1; 762 } 763 leaf-list pcr-value { 764 type binary; 765 description 766 "PCR value in a sequence which matches to the 'pcr-index'."; 767 } 768 } 769 } 771 notification tpm20-attestation { 772 if-feature "taa:TPM20"; 773 description 774 "Contains an instance of TPM2 style signed cryptoprocessor 775 measurements. It is supplemented by unsigned Attester 776 information."; 777 leaf certificate-name { 778 type tpm:certificate-name-ref; 779 mandatory true; 780 description 781 "Allows a TPM quote to be associated with a certificate."; 782 } 783 uses tpm:tpm20-attestation { 784 description 785 "Provides the attestation info. Also ensures PCRs can be XPATH 786 filtered by refining the unsigned data so that it appears."; 787 refine unsigned-pcr-values { 788 min-elements 1; 789 } 790 refine unsigned-pcr-values/pcr-values { 791 min-elements 1; 792 } 793 } 794 } 796 /* 797 * DATA NODES 798 */ 800 augment "/tpm:rats-support-structures" { 801 description 802 "Defines platform wide 'attestation' stream subscription 803 parameters."; 804 leaf marshalling-period { 805 config true; 806 type uint8; 807 default 5; 808 description 809 "The maximum number of seconds between the time an event 810 extends a PCR, and the 'tpm-extend' notification which reports 811 it to a subscribed Verifier. This period allows multiple 812 extend operations bundled together and handled as a group."; 813 } 814 leaf tpm12-subscribed-signature-scheme { 815 if-feature "taa:TPM12"; 816 type leafref { 817 path "../tpm:attester-supported-algos" + 818 "/tpm:tpm12-asymmetric-signing"; 819 } 820 description 821 "A single signature-scheme which will be used to sign the 822 evidence from a TPM 1.2. which is then placed onto the 823 'attestation' event stream."; 824 } 825 leaf tpm20-subscribed-signature-scheme { 826 if-feature "taa:TPM20"; 827 type leafref { 828 path "../tpm:attester-supported-algos" + 829 "/tpm:tpm20-asymmetric-signing"; 830 } 831 description 832 "A single signature-scheme which will be used to sign the 833 evidence from a TPM 2.0. which is then placed onto the 834 'attestation' event stream."; 835 } 836 uses heartbeat{ 837 if-feature "taa:TPM20"; 838 } 839 } 841 augment "/tpm:rats-support-structures/tpm:tpms" { 842 description 843 "Allows the configuration 'attestation' stream parameters for a 844 TPM."; 845 leaf subscription-aik { 846 config true; 847 type tpm:certificate-name-ref; 848 description 849 "Identifies the certificate-name associated with the 850 notifications in the 'attestation' stream."; 851 } 852 choice subscribable { 853 config true; 854 description 855 "Indicates that the set of notifications which comprise the 856 'attestation' event stream can be modified or tuned by a 857 network administrator."; 858 case tpm12-stream { 859 if-feature "taa:TPM12"; 860 description 861 "Configuration elements for a TPM1.2 event stream."; 862 uses tpm:TPM12-hash-algo; 863 leaf-list tpm12-pcr-index { 864 type tpm:pcr; 865 description 866 "The numbers/indexes of the PCRs which can be subscribed."; 867 } 868 } 869 case tpm20-stream { 870 if-feature "taa:TPM20"; 871 description 872 "Configuration elements for a TPM2.0 event stream."; 873 uses tpm:TPM20-hash-algo; 874 leaf-list tpm20-pcr-index { 875 type tpm:pcr; 876 description 877 "The numbers/indexes of the PCRs which can be subscribed."; 878 } 879 } 880 } 881 } 882 } 883 885 6. Security Considerations 887 To be written. 889 7. IANA Considerations 891 To be written. 893 8. References 895 8.1. Normative References 897 [I-D.ietf-rats-architecture] 898 Birkholz, H., Thaler, D., Richardson, M., Smith, N., and 899 W. Pan, "Remote Attestation Procedures Architecture", 900 draft-ietf-rats-architecture-08 (work in progress), 901 December 2020. 903 [I-D.ietf-rats-tpm-based-network-device-attest] 904 Fedorkow, G., Voit, E., and J. Fitzgerald-McKay, "TPM- 905 based Network Device Remote Integrity Verification", 906 draft-ietf-rats-tpm-based-network-device-attest-06 (work 907 in progress), December 2020. 909 [I-D.ietf-rats-yang-tpm-charra] 910 Birkholz, H., Eckel, M., Bhandari, S., Voit, E., Sulzen, 911 B., Xia, L., Laffey, T., and G. Fedorkow, "A YANG Data 912 Model for Challenge-Response-based Remote Attestation 913 Procedures using TPMs", draft-ietf-rats-yang-tpm-charra-05 914 (work in progress), January 2021. 916 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 917 Requirement Levels", BCP 14, RFC 2119, 918 DOI 10.17487/RFC2119, March 1997, 919 . 921 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 922 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 923 May 2017, . 925 [RFC8639] Voit, E., Clemm, A., Gonzalez Prieto, A., Nilsen-Nygaard, 926 E., and A. Tripathy, "Subscription to YANG Notifications", 927 RFC 8639, DOI 10.17487/RFC8639, September 2019, 928 . 930 [TPM2.0] TCG, "TPM 2.0 Library Specification", n.d., 931 . 934 8.2. Informative References 936 [I-D.birkholz-rats-tuda] 937 Fuchs, A., Birkholz, H., McDonald, I., and C. Bormann, 938 "Time-Based Uni-Directional Attestation", draft-birkholz- 939 rats-tuda-04 (work in progress), January 2021. 941 [KGV] TCG, "KGV", October 2003, 942 . 945 Appendix A. Change Log 947 v01-v02 949 o Match YANG changes/simplifications made to charra 950 v00-v01 952 o rename notification: pcr-extended, which supports multiple PCRs 954 o netequip boot added 956 o YANG structure extension removed 958 o Matched to structural changes made within charra 960 Acknowledgements 962 Thanks to ... 964 Authors' Addresses 966 Henk Birkholz 967 Fraunhofer SIT 968 Rheinstrasse 75 969 Darmstadt 64295 970 Germany 972 Email: henk.birkholz@sit.fraunhofer.de 974 Eric Voit 975 Cisco Systems, Inc. 977 Email: evoit@cisco.com 979 Wei Pan 980 Huawei Technologies 981 101 Software Avenue, Yuhuatai District 982 Nanjing, Jiangsu 210012 983 China 985 Email: william.panwei@huawei.com