Internet DRAFT - draft-birkholz-rats-network-device-subscription

draft-birkholz-rats-network-device-subscription







RATS Working Group                                           H. Birkholz
Internet-Draft                                            Fraunhofer SIT
Intended status: Standards Track                                 E. Voit
Expires: December 26, 2020                                         Cisco
                                                                  W. Pan
                                                                  Huawei
                                                           June 24, 2020


                 Attestation Event Stream Subscription
           draft-birkholz-rats-network-device-subscription-00

Abstract

   This document defines how to subscribe to a stream of attestation
   related Evidence on TPM-based network devices.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at https://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on December 26, 2020.

Copyright Notice

   Copyright (c) 2020 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (https://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.



Birkholz, et al.        Expires December 26, 2020               [Page 1]

Internet-Draft              RATS Subscription                  June 2020


Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Terminology . . . . . . . . . . . . . . . . . . . . . . . . .   3
     2.1.  Requirements Notation . . . . . . . . . . . . . . . . . .   3
   3.  Operational Model . . . . . . . . . . . . . . . . . . . . . .   3
     3.1.  Sequence Diagram  . . . . . . . . . . . . . . . . . . . .   3
     3.2.  Continuously Verifying Freshness  . . . . . . . . . . . .   5
       3.2.1.  TPM 1.2 Quote . . . . . . . . . . . . . . . . . . . .   5
       3.2.2.  TPM 2 Quote . . . . . . . . . . . . . . . . . . . . .   5
   4.  Remote Attestation Event Stream . . . . . . . . . . . . . . .   6
     4.1.  Subscription to the <attestation> Event Stream  . . . . .   7
     4.2.  Replaying a history of previous TPM extend operations . .   7
       4.2.1.  TPM2 Heartbeat  . . . . . . . . . . . . . . . . . . .   8
     4.3.  YANG notifications placed on the <attestation> Event
           Stream  . . . . . . . . . . . . . . . . . . . . . . . . .   8
       4.3.1.  tpm-extend  . . . . . . . . . . . . . . . . . . . . .   8
       4.3.2.  tpm12-attestation . . . . . . . . . . . . . . . . . .   9
       4.3.3.  tpm20-attestation . . . . . . . . . . . . . . . . . .  10
     4.4.  Filtering Evidence at the Attester  . . . . . . . . . . .  11
     4.5.  Replaying previous PCR Extend events  . . . . . . . . . .  11
     4.6.  Configuring the <attestation> Event Stream  . . . . . . .  12
   5.  YANG Module . . . . . . . . . . . . . . . . . . . . . . . . .  12
   6.  Security Considerations . . . . . . . . . . . . . . . . . . .  18
   7.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  19
   8.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  19
     8.1.  Normative References  . . . . . . . . . . . . . . . . . .  19
     8.2.  Informative References  . . . . . . . . . . . . . . . . .  19
   Appendix A.  Acknowledgements . . . . . . . . . . . . . . . . . .  20
     A.1.  Open Questions  . . . . . . . . . . . . . . . . . . . . .  20
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  20

1.  Introduction

   [RATS-Device] and [RATS-YANG] define the operational prerequisites
   and a YANG Model for the acquisition of Evidence from a TPM-based
   network device.  However, there is a limitation inherent in the
   challenge-response interaction models upon which these documents are
   based.  This limitation is that it is up to the Verifier to request
   Evidence.  The result is that the interval between the occurrence of
   a security event, and the event's visibility within the Relying Party
   can be unacceptably long.

   This limitation results in two adverse effects:

   1.  Evidence is not streamed to an interested Verifier as soon as it
       is generated.




Birkholz, et al.        Expires December 26, 2020               [Page 2]

Internet-Draft              RATS Subscription                  June 2020


   2.  If it were to be streamed, the Evidence is not appraisable for
       freshness.

   This specification addresses the first adverse effect by enabling a
   Verifier to subscribe via [RFC8639] to a YANG <attestation> Event
   Stream which exists upon the Attester.  When subscribed, the Attester
   will continuously stream a subscribed set of Evidence to the
   Verifier.

   The second adverse effect results from the nonce based challenge-
   response of [RATS-YANG].  In that document, an Attester must wait for
   a new nonce from a Verifier before it generates a new TPM Quote.  In
   this case, the nonce acts as an implicit timestamp that a windows of
   freshness is tied to.  To address delays resulting from such a
   synchronous wait for nonce based Evidence generation, this
   specification enables freshness to be asserted in an asynchronous
   manner.

   By removing these two adverse effects, it becomes possible for a
   Verifier to continuously maintain an appraisal of the Attested device
   without relying on continuous polling.

2.  Terminology

   The following terms are imported from [I-D.ietf-rats-architecture]:
   Attester, Evidence, Relying Party, and Verifier.  Also imported are
   the time definitions time(vg), time(ns), time(eg), time(rg), and
   time(ra) from that document's appendices.  The following terms at
   imported from [RFC8639]: Event Stream, Subscription, Event Stream
   Filter, Dynamic Subscription.

2.1.  Requirements Notation

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
   "OPTIONAL" in this document are to be interpreted as described in
   BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
   capitals, as shown here.

3.  Operational Model

3.1.  Sequence Diagram

   Figure 1 below is a sequence diagram which updates Figure 5 of
   [RATS-Device].  This sequence diagram replaces the [RATS-Device]
   challenge-response interaction model with an [RFC8639] Dynamic
   Subscription to an <attestation> Event Stream.  The contents of the
   <attestation> Event Stream are defined below within Section 4.



Birkholz, et al.        Expires December 26, 2020               [Page 3]

Internet-Draft              RATS Subscription                  June 2020


   .----------.                        .--------------------------.
   | Attester |                        | Relying Party / Verifier |
   '----------'                        '--------------------------'
      time(vg)                                              |
        |<---------establish-subscription(<attestation>)--time(ns)
        |                                                   |
      time(eg)                                              |
        |--filter(<tpm-extend>)---------------------------->|
        |--<tpm12-attestation> or <tpm20-attestation>------>|
        |                                                   |
        |                      verify time(eg) Evidence @ time(rg,ra)
        |                                                   |
        ~                                                   ~
      time(vg',eg')                                         |
        |--filter(<tpm-extend>)---------------------------->|
        |--<tpm12-attestation> or <tpm20-attestation>------>|
        |                                                   |
        |                     verify time(eg') Evidence @ time(rg',ra')



         Figure 1: YANG Subscription Model for Remote Attestation

   o  time(vg,rg,ra) are identical to the corresponding times from
      Figure 5 of [RATS-Device].

   o  time(rg',ra') are subsequent instances of the corresponding times
      from Figure 5 of [RATS-Device].

   o  time(ns): The Verifier generates a nonce and makes an [RFC8639]
      <establish-subscription> request.  This request also includes the
      augmentations defined in this document's YANG model.  Key
      subscription RPC parameters include:

      *  the nonce,

      *  a set of PCRs of interest which the Verifier wants to appraise,
         and

      *  an optional filter which can reduce the logged events on the
         <attestation> stream pushed to the Verifier.

   o  time(eg) - An initial response of Evidence is returned to the
      Verifier.  This includes:

      *  a replay of filtered log entries which have extended into a PCR
         of interest since boot are sent in the <tpm-extend>
         notification, and a



Birkholz, et al.        Expires December 26, 2020               [Page 4]

Internet-Draft              RATS Subscription                  June 2020


      *  a signed TPM quote that contains at least the PCRs from the
         <establish-subscription> RPC are included in a
         <tpm12-attestation> or <tpm20-attestation>).  This quote must
         have included the nonce provided at time(ns).

   o  time(vg',eg') - This occurs when a PCR is extended subsequent to
      time(eg).  Immediately after the extension, the following
      information needs to be pushed to the Verifier:

      *  Any values extended into a PCR of interest, and

      *  a signed TPM Quote showing the result the PCR extension.

3.2.  Continuously Verifying Freshness

   As there is no new Verifier nonce provided at time(eg'), it is
   important to validate the freshness of TPM Quotes which are delivered
   at that time.  The method of doing this verification will vary based
   on the capabilities of the TPM cryptoprocessor used.

3.2.1.  TPM 1.2 Quote

   The [RFC8639] notification format includes the <eventTime> object.
   This can be used to determine the amount of time subsequent to the
   initial subscription each notification was sent.  However, this time
   is not part of the signed results which are returned from the Quote,
   and therefore is not trustworthy as objects returned in the Quote.
   Therefore, a Verifier MUST periodically issue a new nonce, and
   receive this nonce within a TPM quote response in order to ensure the
   freshness of the results.  This can be done using the <tpm12-
   challenge-response-attestation> RPC from [RATS-YANG].

3.2.2.  TPM 2 Quote

   When the Attester includes a TPM2 compliant cryptoprocessor, internal
   time-related counters are included within the signed TPM Quote.  By
   including an initial nonce in the [RFC8639] subscription request,
   fresh values for these counters are pushed as part of the first TPM
   Quote returned to the Verifier.  Then, as shown by
   [I-D.birkholz-rats-tuda], subsequent TPM Quotes delivered to the
   Verifier can the be appraised for freshness based on the predictable
   incrementing of these time-related counters.

   The relevant internal time-related counters defined within [TPM2.0]
   can be seen within <tpms-clock-info>.  These counters include the
   <clock>, <reset-counter>, and <restart-counter> objects.  Normative
   rules for appraising these objects are as follows:




Birkholz, et al.        Expires December 26, 2020               [Page 5]

Internet-Draft              RATS Subscription                  June 2020


   o  If the <clock> has incremented for no more than the same duration
      as both the <eventTime> and the Verifier's internal time since the
      initial time(eg) and any previous time(eg'), then the TPM Quote
      MAY be considered fresh.  Note that [TPM2.0] allows for +/- 15%
      clock drift.  However, many chips significantly improve on this
      maximum drift.  If available, chip specific maximum drifts SHOULD
      be considered during the appraisal process.

   o  If the <reset-counter>, <restart-counter> has incremented.  The
      existing subscription MUST be terminated, and a new <establish-
      subscription> SHOULD be generated.

   o  If a TPM Quote on any subscribed PCR has not been pushed to the
      Verifier for a duration of an Attester defined heartbeat interval,
      then a new TPM Quote notification SHOULD be sent to the Verifier.
      This may often be the case, as certain PCRs might be infrequently
      updated.

   .----------.                        .--------------------------.
   | Attester |                        | Relying Party / Verifier |
   '----------'                        '--------------------------'
      time(vg',eg')                                         |
        |-<tpm20-attestation>------------------------------>|
        |                                    :              |
        ~                           Heartbeat interval      ~
        |                                    :              |
      time(eg')                              :              |
        |-<tpm20-attestation>------------------------------>|
        |                                                   |

4.  Remote Attestation Event Stream

   The <remote-attestation> Event Stream is an [RFC8639] complaint Event
   Stream which is defined within this section and within the YANG
   Module of [RATS-YANG].  This Event Stream contains YANG notifications
   which carry Evidence assisting a Verifier in the appraisal of an
   Attester.  Data Nodes within Section 4.6 allow the configuration of
   this Event Stream's contents on an Attester.

   This <remote-attestation> Event Stream may only be exposed on
   Attesters supporting [RATS-Device].  As with [RATS-Device], it is up
   to the Verifier to understand which types of cryptoprocessors and
   keys are acceptable.








Birkholz, et al.        Expires December 26, 2020               [Page 6]

Internet-Draft              RATS Subscription                  June 2020


4.1.  Subscription to the <attestation> Event Stream

   To establish a subscription to an Attester in a way which provides
   provably fresh Evidence, initial randomness must be provided to the
   Attester.  This is done via the augmentation of a <nonce-value> into
   [RFC8639] the <establish-subscription> RPC.  Additionally, a Verifier
   must ask for PCRs of interest from a platform.

     augment /sn:establish-subscription/sn:input:
       +---w nonce-value    binary
       +---w pcr-index*     tpm:pcr

   The result of the subscription will be that passing of the following
   information:

   1.  <tpm12-attestation> and <tpm20-attestation> notifications which
       include the provided <nonce-value>.  These attestation
       notifications MUST at least include all the <pcr-indicies>
       requested in the RPC.

   2.  a series of <tpm-extend> notifications which reference the
       requested PCRs on all TPM based cryptoprocessors on the Attester.

   3.  <tpm12-attestation> and <tpm20-attestation> notifications
       generated within a few seconds of the <tpm-extend> notifications.
       These attestation notifications MUST at least include any PCRs
       extended.

   If the Verifier does not want to see the logged extend operations for
   all PCRs available from an Attester, an Event Stream Filter should be
   applied.  This filter will remove Evidence from any PCRs which are
   not interesting to the Verifier.

4.2.  Replaying a history of previous TPM extend operations

   Unless it is relying on Known Good Values, a Verifier will need to
   acquire a history of PCR extensions since the Attester has been
   booted.  This history may be requested from the Attester as part of
   the <establish-subscription> RPC.  This request is accomplished by
   placing a very old <replay-start-time> within the original RPC
   request.  As the very old <replay-start-time> will pre-date the time
   of Attester boot, a <replay-start-time-revision> will be returned in
   the <establish-subscription> RPC response, indicating when the
   Attester booted.  Immediately following the response (and before the
   notifications above) one or more <tpm-extend> notifications which
   document all extend operations which have occurred for the requested
   PCRs since boot will be sent.  Many extend operations to a single PCR




Birkholz, et al.        Expires December 26, 2020               [Page 7]

Internet-Draft              RATS Subscription                  June 2020


   index on a single TPM SHOULD be included within a single
   notification.

   Note that if a Verifier has a partial history of extensions, the
   <replay-start-time> can be adjusted so that known extensions are not
   forwarded.

   The end of this history replay will be indicated with the [RFC8639]
   <replay-completed> notification.  For more on this sequence, see
   Section 2.4.2.1 of [RFC8639].

   After the <replay-complete> notification is provided, a TPM Quote
   will be requested and the result passed to the Verifier via a
   <tpm12-attestation> and <tpm20-attestation> notification.  If there
   have been any additional extend operations which have changed a
   subscribed PCR value in this quote, these MUST be pushed to the
   Verifier before the <tpm12-attestation> and <tpm20-attestation>
   notification.

   At this point, the Verifier has sufficient Evidence to appraise the
   reported extend operations for each PCR, as well as compare the
   expected value of the PCR value against that signed by the TPM.

4.2.1.  TPM2 Heartbeat

   For TPM2, every requested PCR MUST at least be sent once within a
   <tpm20-attestation> heartbeat interval.  This MAY be done with a
   single <tpm20-attestation> notification that includes all requested
   PCRs every heartbeat interval.  Alternatively, this MAY be done with
   several <tpm20-attestation> notifications at different times during
   that heartbeat interval.

4.3.  YANG notifications placed on the <attestation> Event Stream

4.3.1.  tpm-extend

   This notification documents when a single subscribed PCR is extended
   within a single TPM cryptoprocessor.  Corresponding notifications
   SHOULD be emitted no less than a <marshalling-period> after the PCR
   is first extended (the reason for the marshalling is that it is quite
   possible that multiple extensions to the same PCR have been made in
   quick succession).  A notification MUST be emitted prior to a
   <tpm12-attestation> or <tpm20-attestation> notification which has
   included and signed the results of any specific PCR extension.







Birkholz, et al.        Expires December 26, 2020               [Page 8]

Internet-Draft              RATS Subscription                  June 2020


       +---n tpm-extend
          +--ro certificate-name?    string
          +--ro pcr-index-changed    tpm:pcr
          +--ro attested-event* []
             +--ro attested-event
                +--ro extended-with    binary
                +--ro event-type?      identityref
                +--ro event-details?   <anydata>

   Each <tpm-extend> MUST include one or more values being extended into
   the PCR.  These are conveyed within the <extended-with> object.  For
   each extension, details of the event MAY be provided within the
   <event-details> object.

   The format of any included <event-details> is identified by the
   <event-type>.  This document includes two YANG structures which may
   be inserted into the <event-details>.  These two structures are:
   <ima-event-log> and <bios-event-log>.  Implementations wanting to
   provide additional documentation of a type of PCR extension may
   choose to define additional YANG structures which can be placed into
   <event-details>.

4.3.2.  tpm12-attestation

   This notification type contains an instance of a TPM1.2 style signed
   cryptoprocessor measurement.  This notification is generated at two
   points in time:

   1.  Upon initial subscription

   2.  Every time at least one subscribed PCR has changed from the
       directly previous <tpm12-attestation>.  In this case, the
       notification SHOULD be emitted within a <marshalling-period>
       since a the first subscribed PCR changed.

   This notification MUST NOT include the returned quote digest the
   results from any PCR extensions not previously reportable by a <tpm-
   extend>.













Birkholz, et al.        Expires December 26, 2020               [Page 9]

Internet-Draft              RATS Subscription                  June 2020


       +---n tpm12-attestation {tpm:TPM12}?
          +--ro certificate-name?            string
          +--ro up-time?                     uint32
          +--ro node-id?                     string
          +--ro node-physical-index?         int32 {ietfhw:entity-mib}?
          +--ro fixed?                       binary
          +--ro external-data?               binary
          +--ro signature-size?              uint32
          +--ro signature?                   binary
          +--ro (tpm12-quote)
             +--:(tpm12-quote1)
             |  +--ro version* []
             |  |  +--ro major?      uint8
             |  |  +--ro minor?      uint8
             |  |  +--ro revMajor?   uint8
             |  |  +--ro revMinor?   uint8
             |  +--ro digest-value?          binary
             |  +--ro TPM_PCR_COMPOSITE* []
             |     +--ro pcr-index*         pcr
             |     +--ro value-size?        uint32
             |     +--ro tpm12-pcr-value*   binary
             +--:(tpm12-quote2)
                +--ro tag?                   uint8
                +--ro pcr-index*             pcr
                +--ro locality-at-release?   uint8
                +--ro digest-at-release?     binary

   All YANG objects above are defined within [RATS-YANG].  The objects
   MAY include Attester information such as <tpm12-pcr-value> which are
   not signed.  The <tpm12-attestation> is not replayable.

4.3.3.  tpm20-attestation

   This notification contains an instance of TPM2 style signed
   cryptoprocessor measurements.  This notification is generated at
   three points in time:

   1.  Upon initial subscription

   2.  Every time at least one subscribed PCR has changed from the
       directly previous <tpm20-attestation>.  In this case, the
       notification SHOULD be emitted within a <marshalling-period>
       since a the first subscribed PCR changed.

   3.  After a minimum heartbeat interval since a previous
       <tpm20-attestation> was sent.





Birkholz, et al.        Expires December 26, 2020              [Page 10]

Internet-Draft              RATS Subscription                  June 2020


   This notification MUST NOT include the returned <quote> the results
   from any PCR extensions not previously reportable by a <tpm-extend>.

       +---n tpm20-attestation {tpm:TPM20}?
          +--ro certificate-name?           string
          +--ro up-time?                    uint32
          +--ro node-id?                    string
          +--ro node-physical-index?        int32 {ietfhw:entity-mib}?
          +--ro quote?                      binary
          +--ro quote-signature?            binary
          +--ro pcr-bank-values* []
          |  +--ro TPM2_Algo?    identityref
          |  +--ro pcr-values* [pcr-index]
          |     +--ro pcr-index    pcr
          |     +--ro pcr-value?   binary
          +--ro pcr-digest-algo-in-quote
             +--ro TPM2_Algo?   identityref

   All YANG objects above are defined within [RATS-YANG].  The objects
   MAY include Attester information such as <pcr-bank-values> which are
   not signed.  The <tpm20-attestation> is not replayable.

4.4.  Filtering Evidence at the Attester

   It can be useful NOT to receive all Evidence related to a PCR.  An
   example of this is would be a when a Verifier maintains Known Good
   Values of a PCR.  In this case, it is not necessary to send each
   extend operation.

   To accomplish this reduction, when an RFC8639 <establish-
   subscription> RPC is sent, a <stream-filter> as per RFC8639,
   Section 2.2 can be set to discard a <tpm-extend> notification when
   the <pcr-index-changed> is uninteresting to the verifier.

4.5.  Replaying previous PCR Extend events

   To verify the value of a PCR, a Verifier must either know that the
   value is a Known Good Value [KGV] or be able to reconstruct the hash
   value by viewing all the PCR-Extends since the Attester rebooted.
   Wherever a hash reconstruction might be needed, the <remote-
   attestation> Event Stream MUST support the RFC8639 <replay> feature.
   Through the <replay> feature, it is possible for a Verifier to
   retrieve and sequentially hash all of the PCR extending events since
   an Attester booted.  And thus, the Verifier has access to all the
   evidence needed to verify a PCR's current value.






Birkholz, et al.        Expires December 26, 2020              [Page 11]

Internet-Draft              RATS Subscription                  June 2020


4.6.  Configuring the <attestation> Event Stream

   Figure 2 is tree diagram which exposes the operator configurable
   elements of the <remote-attestation> Event Stream.  This allows an
   Attester to select what information should be available on the
   stream.  A fetch operation also allows an external device such as a
   Verifier to understand the current configuration of stream.

   Almost all YANG objects below are defined via reference from
   [RATS-YANG].  There is one object which is new with this model
   however. <tpm2-heartbeat> defines the maximum amount of time which
   should pass before a subscriber to the Event Stream should get a
   <tpm20-attestation> notification from devices which contain a TPM2.

     +--rw rats-support-structures
       +--rw rats-support-structures
        +--rw supported-algos*                          identityref
        +--rw tpms* [tpm-name]
        |  +--rw tpm-name                      string
        |  +--rw tras:leafref-to-keystore?     string
        |  +--rw (tras:subscribable)?
        |     +--:(tras:tpm12-stream) {tpm:TPM12}?
        |     |  +--rw tras:tpm12-pcr-index*   tpm:pcr
        |     +--:(tras:tpm20-stream) {tpm:TPM20}?
        |        +--rw tras:tpm20-pcr-index*   tpm:pcr
        +--rw tras:marshalling-period?                  uint8
        +--rw tras:tpm12-subscribed-signature-scheme?
        |       -> ../tpm:supported-algos {tpm:TPM12}?
        +--rw tras:tpm20-subscribed-signature-scheme?
        |       -> ../tpm:supported-algos {tpm:TPM20}?
        +--rw tras:tpm20-subscription-heartbeat?        uint16
                {tpm:TPM20}?


               Figure 2: Configuring the Attestation Stream

5.  YANG Module

   This YANG module imports modules from [RATS-YANG] and [RFC8639].  It
   is also work-in-progress.

<CODE BEGINS> ietf-tpm-remote-attestation-stream@2020-06-10.yang
module ietf-tpm-remote-attestation-stream {
  yang-version 1.1;
  namespace
     "urn:ietf:params:xml:ns:yang:ietf-tpm-remote-attestation-stream";
  prefix tras;




Birkholz, et al.        Expires December 26, 2020              [Page 12]

Internet-Draft              RATS Subscription                  June 2020


  import ietf-subscribed-notifications {
    prefix sn;
    reference
      "RFC 8639: Subscription to YANG Notifications";
  }
  import ietf-tpm-remote-attestation {
    prefix tpm;
    reference
      "draft-ietf-rats-yang-tpm-charra";
  }
  import ietf-yang-structure-ext {
    prefix sx;
    reference
      "draft-ietf-netmod-yang-data-ext";
  }

  organization "IETF";
  contact
    "WG Web:   <http://tools.ietf.org/wg/rats/>
     WG List:  <mailto:rats@ietf.org>

     Editor:   Eric Voit
               <mailto:evoit@cisco.com>";

  description
    "This module contains conceptual YANG specifications for
     subscribing to attestation streams being generated from TPM chips.

     Copyright (c) 2020 IETF Trust and the persons identified
     as authors of the code. All rights reserved.

     Redistribution and use in source and binary forms, with
     or without modification, is permitted pursuant to, and
     subject to the license terms contained in, the Simplified
     BSD License set forth in Section 4.c of the IETF Trust's
     Legal Provisions Relating to IETF Documents
     (https://trustee.ietf.org/license-info).

     Redistribution and use in source and binary forms, with or
     without modification, is permitted pursuant to, and subject to
     the license terms contained in, the Simplified BSD License set
     forth in Section 4.c of the IETF Trust's Legal Provisions
     Relating to IETF Documents
     (https://trustee.ietf.org/license-info).

     This version of this YANG module is part of RFC XXXX
     (https://www.rfc-editor.org/info/rfcXXXX); see the RFC
     itself for full legal notices.



Birkholz, et al.        Expires December 26, 2020              [Page 13]

Internet-Draft              RATS Subscription                  June 2020


     The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL',
     'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED',
     'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document
     are to be interpreted as described in BCP 14 (RFC 2119)
     (RFC 8174) when, and only when, they appear in all
     capitals, as shown here.";

  revision 2020-06-10 {
    description
      "Initial version.";
    reference
      "draft-birkholz-rats-network-device-subscription";
  }

  /*
   * IDENTITIES
   */

  identity pcr-unsubscribable {
    base sn:establish-subscription-error;
    description
      "Requested PCR is subscribable by the Attester.";
  }


  /*
   * Groupings
   */

  grouping heartbeat {
    description
      "Allows an Attester to push verifiable, current TPM PCR values even
      when there have been no recent changes to PCRs.";
    leaf tpm20-subscription-heartbeat {
      type uint16;
      description
        "Number of seconds before the Attestation stream should send a new
        notification with a fresh quote.  This allows confirmation
        that the PCR values haven't changed since the last
        tpm20-attestation.";
    }
  }


  /*
   * RPCs
   */




Birkholz, et al.        Expires December 26, 2020              [Page 14]

Internet-Draft              RATS Subscription                  June 2020


  augment "/sn:establish-subscription/sn:input" {
    when 'derived-from-or-self(sn:stream, "attestation")';
    description
      "This augmentation adds a nonce to as a subscription parameters
       that apply specifically to datastore updates to RPC input.";
    uses tpm:nonce;
    leaf-list pcr-index {
      type tpm:pcr;
      min-elements 1;
      description
        "The numbers/indexes of the PCRs. This will act as a filter for the
        subscription so that 'tpm-extend' notifications related to
        non-requested PCRs will not be sent to a subscriber.";
    }
  }

  /*
   * NOTIFICATIONS
   */

  notification tpm-extend {
    description
      "This notification indicates that a PCR has extended within a TPM based
      cryptoprocessor.  In less that 10 seconds, it should be followed with
      either a tpm12-attestation or tpm20-attestation notification.";
    uses tpm:certificate-name;
    leaf pcr-index-changed {
      type tpm:pcr;
      mandatory true;
      description
        "The number of the PCR extended.";
    }
    list attested-event {
      description
        "A set of events which extended an Attester PCR.  The sequence of
        elements represented in list must match the sequence of events
        placed into the TPM.";
      container attested-event {
        description
          "An instance of an event which extended an Attester PCR";
        leaf extended-with {
          type binary;
          mandatory true;
          description
            "Information extending the PCR.";
        }
        leaf event-type {
          type identityref {



Birkholz, et al.        Expires December 26, 2020              [Page 15]

Internet-Draft              RATS Subscription                  June 2020


            base tpm:attested-event-log-type;
          }
          description
            "Indicates what kind of event happened the Attester thought was
            worthy of recording in a PCR.";
        }
        anydata event-details {
          description
            "Any structure reference 'event-type' contains supporting
            information which allows an Attester to evaluate the trust
            implications.

            Event details may be populated with YANG log structures defined
            at the bottom of this module.";
        }
      }
    }
  }

  notification tpm12-attestation {
    if-feature "tpm:TPM12";
    description
      "Contains an instance of TPM1.2 style signed cryptoprocessor
      measurements.  It is supplemented by unsigned Attester information.";
    uses tpm:tpm12-attestation;
  }

  notification tpm20-attestation {
    if-feature "tpm:TPM20";
    description
      "Contains an instance of TPM2 style signed cryptoprocessor
      measurements.  It is supplemented by unsigned Attester information.";
    uses tpm:tpm20-attestation;
  }


  /*
   * DATA NODES
   */

  augment "/tpm:rats-support-structures" {
    description
      "Defines platform wide 'attestation' stream subscription parameters.";
    leaf marshalling-period {
      config true;
      type uint8;
      default 5;
      description



Birkholz, et al.        Expires December 26, 2020              [Page 16]

Internet-Draft              RATS Subscription                  June 2020


        "The maximum number of seconds between the time an event extends a PCR,
        and the 'tpm-extend' notification which reports it to a subscribed
        Verifier.  This period allows multiple extend operations bundled
        together and handled as a group.";
    }
    leaf tpm12-subscribed-signature-scheme {
      if-feature "tpm:TPM12";
      type leafref {
        path "../tpm:supported-algos";
          /* a specific algorithm, need to check syntax */
      }
      description
        "A single signature-scheme which will be used to sign the evidence
        from a TPM 1.2. which is then placed onto the 'attestation' event
        stream.";
    }
    leaf tpm20-subscribed-signature-scheme {
      if-feature "tpm:TPM20";
      type leafref {
        path "../tpm:supported-algos";
          /* a specific algorithm, need to check syntax */
      }
      description
        "A single signature-scheme which will be used to sign the evidence
        from a TPM 2.0. which is then placed onto the 'attestation' event
        stream.";
    }
    uses heartbeat{
      if-feature "tpm:TPM20";
    }
  }

  augment "/tpm:rats-support-structures/tpm:tpms" {
    description
      "Allows the configuration 'attestation' stream parameters for a TPM.";
    leaf leafref-to-keystore {
      config true;
      type string;
      description
        "needs to be replaced with Reference to keystore draft.";
    }
    choice subscribable {
      config true;
      description
        "Indicates that the set of notifications which comprise the attestation
        stream can be modified or tuned by a network administrator.";
      case tpm12-stream {
        if-feature "tpm:TPM12";



Birkholz, et al.        Expires December 26, 2020              [Page 17]

Internet-Draft              RATS Subscription                  June 2020


        description
          "Configuration elements for a TPM1.2 event stream.";
        leaf-list tpm12-pcr-index {
          type tpm:pcr;
          description
            "The numbers/indexes of the PCRs which can be subscribed.";
        }
      }
      case tpm20-stream {
        if-feature "tpm:TPM20";
        description
          "Configuration elements for a TPM2.0 event stream.";
        leaf-list tpm20-pcr-index {
          type tpm:pcr;
          description
            "The numbers/indexes of the PCRs which can be subscribed.";
        }
        /* We need to decide if more than one hash-algo is subscribable */
      }
    }
  }


  /*
   * STRUCTURES - these contain the schema of reportable event types
   */

   sx:structure bios-event-log {
     when 'derived-from(../event-type, "bios-event-log")';
     description
       "BIOS/UEFI event log format";
     uses tpm:bios-event-log;
   }

   sx:structure ima-event-log {
     when 'derived-from(../event-type, "ima-event-log")';
     description
       "IMA event log format";
     uses tpm:ima-event-log;
   }
}
<CODE ENDS>

6.  Security Considerations

   To be written.





Birkholz, et al.        Expires December 26, 2020              [Page 18]

Internet-Draft              RATS Subscription                  June 2020


7.  IANA Considerations

   To be written.

8.  References

8.1.  Normative References

   [I-D.ietf-rats-architecture]
              Birkholz, H., Thaler, D., Richardson, M., Smith, N., and
              W. Pan, "Remote Attestation Procedures Architecture",
              draft-ietf-rats-architecture-04 (work in progress), May
              2020.

   [RATS-Device]
              "Network Device Remote Integrity Verification", n.d.,
              <https://tools.ietf.org/html/draft-ietf-rats-tpm-based-
              network-device-attest-00>.

   [RATS-YANG]
              "A YANG Data Model for Challenge-Response-based Remote
              Attestation Procedures using TPMs", n.d.,
              <https://datatracker.ietf.org/doc/draft-ietf-rats-yang-
              tpm-charra/>.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/info/rfc2119>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <https://www.rfc-editor.org/info/rfc8174>.

   [RFC8639]  Voit, E., Clemm, A., Gonzalez Prieto, A., Nilsen-Nygaard,
              E., and A. Tripathy, "Subscription to YANG Notifications",
              RFC 8639, DOI 10.17487/RFC8639, September 2019,
              <https://www.rfc-editor.org/info/rfc8639>.

   [TPM2.0]   TCG, "TPM 2.0 Library Specification", n.d.,
              <https://trustedcomputinggroup.org/resource/tpm-library-
              specification/>.

8.2.  Informative References







Birkholz, et al.        Expires December 26, 2020              [Page 19]

Internet-Draft              RATS Subscription                  June 2020


   [I-D.birkholz-rats-tuda]
              Fuchs, A., Birkholz, H., McDonald, I., and C. Bormann,
              "Time-Based Uni-Directional Attestation", draft-birkholz-
              rats-tuda-02 (work in progress), March 2020.

   [KGV]      TCG, "KGV", October 2003,
              <https://trustedcomputinggroup.org/wp-content/uploads/TCG-
              NetEq-Attestation-Workflow-Outline_v1r9b_pubrev.pdf>.

Appendix A.  Acknowledgements

   Tim Jenkins, Paul Merlo, Wayne Mills

A.1.  Open Questions

   o  Do we need a notification correlator object to easily allow
      correlation on which extensions have been embodied within a
      specific attestation?

Authors' Addresses

   Henk Birkholz
   Fraunhofer SIT
   Rheinstrasse 75
   Darmstadt  64295
   Germany

   Email: henk.birkholz@sit.fraunhofer.de


   Eric Voit
   Cisco Systems, Inc.

   Email: evoit@cisco.com


   Wei Pan
   Huawei Technologies
   101 Software Avenue, Yuhuatai District
   Nanjing, Jiangsu  210012
   China

   Email: william.panwei@huawei.com








Birkholz, et al.        Expires December 26, 2020              [Page 20]