--- 1/draft-ietf-rats-yang-tpm-charra-16.txt 2022-03-16 16:13:12.052428422 -0700 +++ 2/draft-ietf-rats-yang-tpm-charra-17.txt 2022-03-16 16:13:12.156431054 -0700 @@ -1,35 +1,35 @@ RATS Working Group H. Birkholz Internet-Draft M. Eckel Intended status: Standards Track Fraunhofer SIT -Expires: 3 September 2022 S. Bhandari +Expires: 17 September 2022 S. Bhandari ThoughtSpot E. Voit B. Sulzen Cisco L. Xia Huawei T. Laffey HPE G. Fedorkow Juniper - 2 March 2022 + 16 March 2022 A YANG Data Model for Challenge-Response-based Remote Attestation Procedures using TPMs - draft-ietf-rats-yang-tpm-charra-16 + draft-ietf-rats-yang-tpm-charra-17 Abstract - This document defines YANG RPCs and a small number of configuration - nodes required to retrieve attestation evidence about integrity + This document defines YANG RPCs and a few configuration nodes + required to retrieve attestation evidence about integrity measurements from a device, following the operational context defined in TPM-based Network Device Remote Integrity Verification. Complementary measurement logs are also provided by the YANG RPCs, originating from one or more roots of trust for measurement (RTMs). The module defined requires at least one TPM 1.2 or TPM 2.0 as well as a corresponding TPM Software Stack (TSS), or equivalent hardware implementations that include the protected capabilities as provided by TPMs as well as a corresponding software stack, included in the device components of the composite device the YANG server is running on. @@ -42,90 +42,91 @@ 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 3 September 2022. + This Internet-Draft will expire on 17 September 2022. Copyright Notice Copyright (c) 2022 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 Revised BSD License text as - described in Section 4.e of the Trust Legal Provisions and are - provided without warranty as described in the Revised BSD License. + 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. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1.1. Requirements notation . . . . . . . . . . . . . . . . . . 3 2. The YANG Module for Basic Remote Attestation Procedures . . . 3 2.1. YANG Modules . . . . . . . . . . . . . . . . . . . . . . 3 2.1.1. 'ietf-tpm-remote-attestation' . . . . . . . . . . . . 4 - 2.1.2. 'ietf-tcg-algs' . . . . . . . . . . . . . . . . . . . 32 + 2.1.2. 'ietf-tcg-algs' . . . . . . . . . . . . . . . . . . . 33 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 48 4. Security Considerations . . . . . . . . . . . . . . . . . . . 49 - 5. Change Log . . . . . . . . . . . . . . . . . . . . . . . . . 50 - 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 51 - 6.1. Normative References . . . . . . . . . . . . . . . . . . 51 - 6.2. Informative References . . . . . . . . . . . . . . . . . 57 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 57 + 5. References . . . . . . . . . . . . . . . . . . . . . . . . . 50 + 5.1. Normative References . . . . . . . . . . . . . . . . . . 51 + 5.2. Informative References . . . . . . . . . . . . . . . . . 55 + Appendix A. Integrity Measurement Architecture (IMA) . . . . . . 56 + Appendix B. IMA for Network Equipment Boot Logs . . . . . . . . 57 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 58 1. Introduction This document is based on the general terminology defined in the [I-D.ietf-rats-architecture] and uses the operational context defined in [I-D.ietf-rats-tpm-based-network-device-attest] as well as the interaction model and information elements defined in [I-D.ietf-rats-reference-interaction-models]. The currently supported hardware security modules (HSMs) are the Trusted Platform Modules (TPMs) [TPM1.2] and [TPM2.0] as specified by the Trusted - Computing Group (TCG). One or more TPMs embedded in the components - of a Composite Device are required in order to use the YANG module - defined in this document. A TPM is used as a root of trust for - reporting (RTR) in order to retrieve attestation Evidence from a - composite device (_TPM Quote_ primitive operation). Additionally, it - is used as a root of trust for storage (RTS) in order to retain - shielded secrets and store system measurements using a folding hash - function (_TPM PCR Extend_ primitive operation). + Computing Group (TCG). One TPM, or multiple TPMs in the case of a + Composite Device, are required in order to use the YANG module + defined in this document. Each TPM is used as a root of trust for + storage (RTS) in order to store system security measurement Evidence. + And each TPM is used as a root of trust for reporting (RTR) in order + to retrieve attestation Evidence. This is done by using a YANG RPC + to request a quote which exposes a rolling hash the security + measurements held internally within the TPM. Specific terms imported from [I-D.ietf-rats-architecture] and used in this document include: Attester, Composite Device, Evidence. Specific terms imported from [TPM2.0-Key] and used in this document - include: Endorsement Key (EK), Initial Attestation Key (IAK), Local - Attestation Key (LAK). + include: Endorsement Key (EK), Initial Attestation Key (IAK), + Attestation Identity Key (AIK), Local Attestation Key (LAK). 1.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. 2. The YANG Module for Basic Remote Attestation Procedures One or more TPMs MUST be embedded in a Composite Device that provides attestation evidence via the YANG module defined in this document. - The ietf-basic-remote-attestation YANG module enables a composite + The ietf-tpm-remote-attestation YANG module enables a composite device to take on the role of an Attester, in accordance with the Remote Attestation Procedures (RATS) architecture [I-D.ietf-rats-architecture], and the corresponding challenge- response interaction model defined in the [I-D.ietf-rats-reference-interaction-models] document. A fresh nonce with an appropriate amount of entropy [NIST-915121] MUST be supplied by the YANG client in order to enable a proof-of-freshness with respect to the attestation Evidence provided by the Attester running the YANG datastore. Further, this nonce is used to prevent replay attacks. The method for communicating the relationship of each @@ -134,97 +135,100 @@ 2.1. YANG Modules In this section the several YANG modules are defined. 2.1.1. 'ietf-tpm-remote-attestation' This YANG module imports modules from [RFC6991] with prefix 'yang', [RFC8348] with prefix 'hw', [I-D.ietf-netconf-keystore] with prefix 'ks', and 'ietf-tcg-algs.yang' Section 2.1.2.3 with prefix 'taa'. - Additionally references are made to [RFC8032], [RFC8017], [RFC6933], + Additionally, references are made to [RFC8032], [RFC8017], [RFC6933], [TPM1.2-Commands], [TPM2.0-Arch], [TPM2.0-Structures], [TPM2.0-Key], - [TPM1.2-Structures], [bios-log], [ima-log], [BIOS-Log-Event-Type] and - [netequip-boot-log]. + [TPM1.2-Structures], [bios-log], [ima-log], [BIOS-Log-Event-Type], as + well as Appendix A and Appendix B. 2.1.1.1. Features This module supports the following features: - * 'TPMs': Indicates that multiple TPMs on the device can support - remote attestation. This feature is applicable in cases where - multiple line cards are present, each with its own TPM. + * 'mtpm': Indicates that multiple TPMs on the device can support + remote attestation. For example, this feature could be used in + cases where multiple line cards are present, each with its own + TPM. * 'bios': Indicates that the device supports the retrieval of BIOS/ UEFI event logs. [bios-log] * 'ima': Indicates that the device supports the retrieval of event - logs from the Linux Integrity Measurement Architecture (IMA). - [ima-log] + logs from the Linux Integrity Measurement Architecture (IMA + [ima-log]). Also see Appendix A. * 'netequip_boot': Indicates that the device supports the retrieval - of netequip boot event logs. [netequip-boot-log] + of netequip boot event logs. See Appendix A and Appendix B. 2.1.1.2. Identities This module supports the following types of attestation event logs: 'bios', 'ima', and 'netequip_boot'. 2.1.1.3. Remote Procedure Calls (RPCs) In the following, RPCs for both TPM 1.2 and TPM 2.0 attestation procedures are defined. 2.1.1.3.1. 'tpm12-challenge-response-attestation' This RPC allows a Verifier to request signed TPM PCRs (_TPM Quote_ operation) from a TPM 1.2 compliant cryptoprocessor. Where the - feature 'TPMs' is active, and one or more 'certificate-name' is not + feature 'mtpm' is active, and one or more 'certificate-name' is not provided, all TPM 1.2 compliant cryptoprocessors will respond. A YANG tree diagram of this RPC is as follows: - +---x tpm12-challenge-response-attestation {taa:TPM12}? + +---x tpm12-challenge-response-attestation {taa:tpm12}? +---w input | +---w tpm12-attestation-challenge | +---w pcr-index* pcr | +---w nonce-value binary - | +---w certificate-name* certificate-name-ref {tpm:TPMs}? + | +---w certificate-name* certificate-name-ref + | {tpm:mtpm}? +--ro output +--ro tpm12-attestation-response* [] +--ro certificate-name certificate-name-ref +--ro up-time? uint32 +--ro TPM_QUOTE2? binary 2.1.1.3.2. 'tpm20-challenge-response-attestation' This RPC allows a Verifier to request signed TPM PCRs (_TPM Quote_ operation) from a TPM 2.0 compliant cryptoprocessor. Where the - feature 'TPMs' is active, and one or more 'certificate-name' is not + feature 'mtpm' is active, and one or more 'certificate-name' is not provided, all TPM 2.0 compliant cryptoprocessors will respond. A YANG tree diagram of this RPC is as follows: - +---x tpm20-challenge-response-attestation {taa:TPM20}? + +---x tpm20-challenge-response-attestation {taa:tpm20}? +---w input | +---w tpm20-attestation-challenge | +---w nonce-value binary | +---w tpm20-pcr-selection* [] - | | +---w TPM20-hash-algo? identityref - | | +---w pcr-index* tpm:pcr - | +---w certificate-name* certificate-name-ref {tpm:TPMs}? + | | +---w tpm20-hash-algo? identityref + | | +---w pcr-index* pcr + | +---w certificate-name* certificate-name-ref + | {tpm:mtpm}? +--ro output +--ro tpm20-attestation-response* [] +--ro certificate-name certificate-name-ref +--ro TPMS_QUOTE_INFO binary +--ro quote-signature? binary +--ro up-time? uint32 +--ro unsigned-pcr-values* [] - +--ro TPM20-hash-algo? identityref + +--ro tpm20-hash-algo? identityref +--ro pcr-values* [pcr-index] +--ro pcr-index pcr +--ro pcr-value? binary An example of an RPC challenge requesting PCRs 0-7 from a SHA-256 bank could look like the following: xmlns="urn:ietf:params:xml:ns:yang:ietf-tpm-remote-attestation"> @@ -275,49 +279,49 @@ 2.1.1.4. 'log-retrieval' This RPC allows a Verifier to acquire the evidence which was extended into specific TPM PCRs. A YANG tree diagram of this RPC is as follows: +---x log-retrieval +---w input - | +---w log-selector* [] - | | +---w name* string - | | +---w (index-type)? - | | | +--:(last-entry) - | | | | +---w last-entry-value? binary - | | | +--:(index) - | | | | +---w last-index-number? uint64 - | | | +--:(timestamp) - | | | +---w timestamp? yang:date-and-time - | | +---w log-entry-quantity? uint16 | +---w log-type identityref + | +---w log-selector* [] + | +---w name* string + | +---w (index-type)? + | | +--:(last-entry) + | | | +---w last-entry-value? binary + | | +--:(index) + | | | +---w last-index-number? uint64 + | | +--:(timestamp) + | | +---w timestamp? yang:date-and-time + | +---w log-entry-quantity? uint16 +--ro output +--ro system-event-logs +--ro node-data* [] +--ro name? string +--ro up-time? uint32 +--ro log-result +--ro (attested_event_log_type) +--:(bios) {bios}? | +--ro bios-event-logs | +--ro bios-event-entry* [event-number] | +--ro event-number uint32 | +--ro event-type? uint32 | +--ro pcr-index? pcr | +--ro digest-list* [] | | +--ro hash-algo? identityref | | +--ro digest* binary | +--ro event-size? uint32 - | +--ro event-data* uint8 + | +--ro event-data* binary +--:(ima) {ima}? | +--ro ima-event-logs | +--ro ima-event-entry* [event-number] | +--ro event-number uint64 | +--ro ima-template? string | +--ro filename-hint? string | +--ro filedata-hash? binary | +--ro filedata-hash-algorithm? string | +--ro template-hash-algorithm? string | +--ro template-hash? binary @@ -337,77 +341,80 @@ +--ro signature? binary 2.1.1.5. Data Nodes This section provides a high level description of the data nodes containing the configuration and operational objects with the YANG model. For more details, please see the YANG model itself in Figure 1. Container 'rats-support-structures': This houses the set of - information relating to a device's TPM(s). + information relating to remote attestation for a device. This + includes specific device TPM(s), the compute nodes (such as line + cards) on which the TPM(s) reside, and the algorithms supported + across the platform. Container 'tpms': Provides configuration and operational details for each supported TPM, including the tpm-firmware-version, PCRs which may be quoted, certificates which are associated with that TPM, and the current operational status. Of note are the certificates which are associated with that TPM. As a certificate is associated with a particular TPM attestation key, knowledge of the certificate allows a specific TPM to be identified. +--rw tpms +--rw tpm* [name] +--rw name string - +--ro hardware-based? boolean + +--ro hardware-based boolean +--ro physical-index? int32 {hw:entity-mib}? +--ro path? string - +--ro compute-node compute-node-ref {tpm:tpms}? + +--ro compute-node compute-node-ref {tpm:mtpm}? +--ro manufacturer? string +--rw firmware-version identityref +--rw tpm12-hash-algo? identityref +--rw tpm12-pcrs* pcr +--rw tpm20-pcr-bank* [tpm20-hash-algo] | +--rw tpm20-hash-algo identityref | +--rw pcr-index* tpm:pcr +--ro status enumeration +--rw certificates +--rw certificate* [name] +--rw name string - +--rw keystore-ref? leafref + +--rw keystore-ref? leafref {ks:asymmetric-keys}? +--rw type? enumeration container 'attester-supported-algos' - Identifies which TCG hash algorithms are available for use on the Attesting platform. This allows an operator to limit algorithms available for use by RPCs to just a desired set from the universe of all allowed hash algorithms by the TCG. +--rw attester-supported-algos +--rw tpm12-asymmetric-signing* identityref +--rw tpm12-hash* identityref +--rw tpm20-asymmetric-signing* identityref +--rw tpm20-hash* identityref container 'compute-nodes' - When there is more than one TPM supported, this container maintains the set of information related to the compute node associated with a specific TPM. This allows each specific TPM to identify to which 'compute-node' it belongs. - +--rw compute-nodes {tpm:TPMs}? + +--rw compute-nodes {tpm:mtpm}? +--ro compute-node* [node-id] +--ro node-id string +--ro node-physical-index? int32 {hw:entity-mib}? +--ro node-name? string +--ro node-location? string 2.1.1.6. YANG Module - file "ietf-tpm-remote-attestation@2022-02-16.yang" + file "ietf-tpm-remote-attestation@2022-03-15.yang" module ietf-tpm-remote-attestation { namespace "urn:ietf:params:xml:ns:yang:ietf-tpm-remote-attestation"; prefix tpm; import ietf-yang-types { prefix yang; } import ietf-hardware { prefix hw; } @@ -449,33 +456,33 @@ 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. 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 2022-03-02 { + revision 2022-03-15 { description "Initial version"; reference "RFC XXXX: A YANG Data Model for Challenge-Response-based Remote Attestation Procedures using TPMs"; } /*****************/ /* Features */ /*****************/ - feature tpms { + feature mtpm { description "The device supports the remote attestation of multiple TPM based cryptoprocessors."; } feature bios { description "The device supports the bios logs."; reference "bios-log: @@ -487,51 +494,53 @@ feature ima { description "The device supports Integrity Measurement Architecture logs. Many variants of IMA logs exist in the deployment. Each encodes the log entry contents as the specific measurements which get hashed into a PCRs as Evidence. See the reference below for one example of such an encoding."; reference "ima-log: https://www.trustedcomputinggroup.org/wp-content/uploads/ - TCG_IWG_CEL_v1_r0p30_13feb2021.pdf Section 4.3"; + TCG_IWG_CEL_v1_r0p41_pub.pdf Section 4.3"; } feature netequip_boot { description "The device supports the netequip_boot logs."; reference "netequip-boot-log: https://www.kernel.org/doc/Documentation/ABI/testing/ima_policy"; } /*****************/ /* Typedefs */ /*****************/ typedef pcr { type uint8 { range "0..31"; } description - "Valid index number for a PCR. At this point 0-31 is viable."; + "Valid index number for a PCR. A {{TPM2.0}} compliant PCR index + extends from 0-31. At this time a typical TPM would have no + more than 32 PCRS."; } typedef compute-node-ref { type leafref { path "/tpm:rats-support-structures/tpm:compute-nodes" + "/tpm:compute-node/tpm:node-name"; } description - "This type is used to reference a hardware node. It is quite - possible this leafref will eventually point to another YANG - module's node."; + "This type is used to reference a hardware node. Note that an + implementer might include an alternative leafref pointing to a + different YANG module node specifying hardware structures."; } typedef certificate-name-ref { type leafref { path "/tpm:rats-support-structures/tpm:tpms/tpm:tpm" + "/tpm:certificates/tpm:certificate/tpm:name"; } description "A type which allows identification of a TPM based certificate."; } @@ -576,28 +584,29 @@ leaf tpm20-hash-algo { type identityref { base taa:hash; } must '/tpm:rats-support-structures/tpm:attester-supported-algos' + '/tpm:tpm20-hash' { error-message "This platform does not support tpm20-hash-algo"; } default "taa:TPM_ALG_SHA256"; description - "The hash scheme that is used to hash a TPM1.2 PCR. This + "The hash scheme that is used to hash a TPM2.0 PCR. This must be one of those supported by a platform."; } } grouping tpm12-hash-algo { description "The cryptographic algorithm used to hash the TPM1.2 PCRs."; + leaf tpm12-hash-algo { type identityref { base taa:hash; } must '/tpm:rats-support-structures/tpm:attester-supported-algos' + '/tpm:tpm12-hash' { error-message "This platform does not support tpm12-hash-algo"; } default "taa:TPM_ALG_SHA1"; description @@ -595,63 +604,59 @@ type identityref { base taa:hash; } must '/tpm:rats-support-structures/tpm:attester-supported-algos' + '/tpm:tpm12-hash' { error-message "This platform does not support tpm12-hash-algo"; } default "taa:TPM_ALG_SHA1"; description "The hash scheme that is used to hash a TPM1.2 PCR. This - MUST be one of those supported by a platform. This assumes - that an algorithm other than SHA1 can be supported on some - TPM1.2 cryptoprocessor variant."; + MUST be one of those supported by a platform."; } } grouping nonce { description - "A random number intended to be used once to show freshness - and to allow the detection of replay attacks."; + "A random number intended to guarantee freshness and for use + as part of a replay-detection mechanism."; leaf nonce-value { type binary; mandatory true; description "A cryptographically generated random number which should not be predictable prior to its issuance from a random number generation function. The random number MUST be derived from an entropy source external to the Attester. Note that a nonce sent into a TPM will typically be 160 or 256 binary digits long. (This is 20 or 32 bytes.) So if fewer - binary are sent, this nonce object will be padded - with leading zeros any in Quotes returned from the TPM. + binary digits are sent, this nonce object will be padded + with leading zeros within Quotes returned from the TPM. Additionally if more bytes are sent, the nonce will be trimmed to the most significant binary digits."; } } grouping tpm12-pcr-selection { description "A Verifier can request one or more PCR values using its individually created Attestation Key Certificate (AC). The corresponding selection filter is represented in this - grouping. - Requesting a PCR value that is not in scope of the AC used, - detailed exposure via error msg should be avoided."; + grouping."; leaf-list pcr-index { type pcr; description - "The numbers/indexes of the PCRs. At the moment this is limited - to 32. In addition, any selection of PCRs MUST verify that - the set of PCRs requested are a subset the set of PCRs - exposed by in the leaf-list /tpm:rats-support-structures + "The numbers/indexes of the PCRs. In addition, any selection + of PCRs MUST verify that the set of PCRs requested are a + subset the set of PCRs exposed by in the leaf-list + /tpm:rats-support-structures /tpm:tpms/tpm:tpm[name=current()]/tpm:tpm12-pcrs"; } } grouping tpm20-pcr-selection { description "A Verifier can acquire one or more PCR values, which are hashed together in a TPM2B_DIGEST coming from the TPM2. The selection list of desired PCRs and the Hash Algorithm is represented in this grouping."; @@ -699,34 +704,20 @@ grouping tpm-name { description "A unique TPM on a device."; leaf name { type string; description "Unique system generated name for a TPM on a device."; } } - grouping tpm-name-selector { - description - "One or more TPM on a device."; - leaf-list name { - type string; - config false; - description - "Name of one or more unique TPMs on a device. If this object - exists, a selection should pull only the objects related to - these TPM(s). If it does not exist, all qualifying TPMs that - are 'hardware-based' equals true on the device are selected."; - } - } - grouping node-uptime { description "Uptime in seconds of the node."; leaf up-time { type uint32; description "Uptime in seconds of this node reporting its data"; } } @@ -784,25 +775,27 @@ "PCR values in each PCR bank. This might appear redundant with the TPM2B_DIGEST, but that digest is calculated across multiple PCRs. Having to verify across multiple PCRs does not necessarily make it easy for a Verifier to appraise just the minimum set of PCR information which has changed since the last received TPM2B_DIGEST. Put another way, why should a Verifier reconstruct the proper value of all PCR Quotes when only a single PCR has changed? To help this happen, if the Attester does know specific PCR values, the Attester can provide these individual values via - 'unsigned-pcr-values'. By comparing this information to the + 'unsigned-pcr-values'. By comparing this information to what has previously been validated, it is possible for a Verifier to confirm the Attester's signature while eliminating - significant processing. There should never be a result where - an unsigned PCR value is actually that that within a quote. + + significant processing. Note that there should never be a + result where an unsigned PCR value differs from what may be + reconstructed from the within the PCR quote and the event logs. If there is a difference, a signed result which has been verified from retrieved logs is considered definitive."; uses tpm20-hash-algo; list pcr-values { key "pcr-index"; description "List of one PCR bank."; leaf pcr-index { type pcr; description @@ -826,29 +819,33 @@ "Identifier for type of log to be retrieved."; leaf log-type { type identityref { base attested_event_log_type; } mandatory true; description "The corresponding measurement log type identity."; } } + grouping boot-event-log { description "Defines a specific instance of an event log entry and corresponding to the information used to extend the PCR"; leaf event-number { type uint32; description - "Unique event number of this event"; + "Unique event number of this event which monotonically + increases. The maximum event number should not be + reached, nor is wrapping back to an earlier number + supported."; } leaf event-type { type uint32; description "BIOS Log Event Type: https://trustedcomputinggroup.org/wp-content/uploads/ TCG_PCClient_PFP_r1p05_v23_pub.pdf Section 10.4.1"; } leaf pcr-index { type pcr; @@ -872,64 +869,71 @@ "The hash of the event data using the algorithm of the 'hash-algo' against 'event data'."; } } leaf event-size { type uint32; description "Size of the event data"; } leaf-list event-data { - type uint8; + type binary; description - "The event data size determined by event-size"; + "The event data size determined by event-size. For more + see "; } } + grouping bios-event-log { description "Measurement log created by the BIOS/UEFI."; list bios-event-entry { - key event-number; + key "event-number"; description "Ordered list of TCG described event log that extended the PCRs in the order they were logged"; uses boot-event-log; } } + grouping ima-event { description - "Defines an hash log extend event for IMA measurements"; + "Defines a hash log extend event for IMA measurements"; reference "ima-log: https://www.trustedcomputinggroup.org/wp-content/uploads/ - TCG_IWG_CEL_v1_r0p30_13feb2021.pdf Section 4.3"; + TCG_IWG_CEL_v1_r0p41_pub.pdf Section 4.3"; leaf event-number { type uint64; description - "Unique number for this event for sequencing"; + "Unique event number of this event which monotonically + increases. The maximum event number should not be + reached, nor is wrapping back to an earlier number + supported."; } leaf ima-template { type string; description "Name of the template used for event logs for e.g. ima, ima-ng, ima-sig"; } leaf filename-hint { type string; description "File that was measured"; } leaf filedata-hash { type binary; description - "Hash of filedata"; + "Hash of filedata as updated based upon the + filedata-hash-algorithm"; } leaf filedata-hash-algorithm { type string; description "Algorithm used for filedata-hash"; } leaf template-hash-algorithm { type string; description "Algorithm used for template-hash"; @@ -940,51 +944,52 @@ "hash(filedata-hash, filename-hint)"; } leaf pcr-index { type pcr; description "Defines the PCR index that this event extended"; } leaf signature { type binary; description - "The file signature"; + "Digital file signature which provides a + fingerprint for the file being measured."; } } + grouping ima-event-log { description "Measurement log created by IMA."; list ima-event-entry { - key event-number; + key "event-number"; description "Ordered list of ima event logs by event-number"; uses ima-event; } } grouping network-equipment-boot-event-log { description "Measurement log created by Network Equipment Boot. The Network Equipment Boot format is identical to the IMA format. In contrast to the IMA log, the Network Equipment Boot log includes every measurable event from an Attester, including the boot stages of BIOS, Bootloader, etc. In essence, the scope of events represented in this format combines the scope of BIOS events and IMA events."; list boot-event-entry { - key event-number; + key "event-number"; description "Ordered list of Network Equipment Boot event logs by event-number, using the IMA event format."; uses ima-event; } - } grouping event-logs { description "A selector for the log and its type."; choice attested_event_log_type { mandatory true; description "Event log type determines the event logs content."; case bios { if-feature "bios"; @@ -1031,21 +1036,21 @@ input { container tpm12-attestation-challenge { description "This container includes every information element defined in the reference challenge-response interaction model for remote attestation. Corresponding values are based on TPM 1.2 structure definitions"; uses tpm12-pcr-selection; uses nonce; leaf-list certificate-name { - if-feature "tpm:tpms"; + if-feature "tpm:mtpm"; type certificate-name-ref; must "/tpm:rats-support-structures/tpm:tpms" + "/tpm:tpm[tpm:firmware-version='taa:tpm12']" + "/tpm:certificates/" + "/tpm:certificate[name=current()]" { error-message "Not an available TPM1.2 AIK certificate."; } description "When populated, the RPC will only get a Quote for the TPMs associated with these certificate(s)."; @@ -1066,121 +1071,130 @@ uses tpm12-attestation; } } } rpc tpm20-challenge-response-attestation { if-feature "taa:tpm20"; description "This RPC accepts the input for TSS TPM 2.0 commands of the managed device. ComponentIndex from the hardware manager YANG - module to refer to dedicated TPM in composite devices, - e.g. smart NICs, is still a TODO."; + module is used to refer to dedicated TPM in composite devices, + e.g. smart NICs, is not covered."; + input { container tpm20-attestation-challenge { description "This container includes every information element defined in the reference challenge-response interaction model for remote attestation. Corresponding values are based on TPM 2.0 structure definitions"; uses nonce; uses tpm20-pcr-selection; leaf-list certificate-name { - if-feature "tpm:tpms"; + if-feature "tpm:mtpm"; type certificate-name-ref; must "/tpm:rats-support-structures/tpm:tpms" + "/tpm:tpm[tpm:firmware-version='taa:tpm20']" + "/tpm:certificates/" + "/tpm:certificate[name=current()]" { error-message "Not an available TPM2.0 AIK certificate."; } description "When populated, the RPC will only get a Quote for the TPMs associated with the certificates."; } } } output { list tpm20-attestation-response { unique "certificate-name"; description - "The binary output of TPM2b_Quote in one TPM chip of the + "The binary output of TPM2b_Quote from one TPM of the node which identified by node-id. An TPMS_ATTEST structure including a length, encapsulated in a signature"; uses certificate-name-ref { description "Certificate associated with this tpm20-attestation."; } uses tpm20-attestation; } } } rpc log-retrieval { description "Logs Entries are either identified via indices or via providing the last line received. The number of lines returned can be limited. The type of log is a choice that can be augmented."; input { + uses log-identifier; list log-selector { description - "Selection of log entries to be reported."; - uses tpm-name-selector; + "Only log entries which meet all the selection criteria provided + are to be returned by the RPC output."; + leaf-list name { + type string; + description + "Name of one or more unique TPMs on a device. If this object + exists, a selection should pull only the objects related to + these TPM(s). If it does not exist, all qualifying TPMs that + are 'hardware-based' equals true on the device are selected."; + } choice index-type { description "Last log entry received, log index number, or timestamp."; case last-entry { description "The last entry of the log already retrieved."; leaf last-entry-value { type binary; description - "Content of an log event which matches 1:1 with a + "Content of a log event which matches 1:1 with a unique event record contained within the log. Log - entries subsequent to this will be passed to the + entries after this will be passed to the requester. Note: if log entry values are not unique, this MUST return an error."; } } case index { description "Numeric index of the last log entry retrieved, or zero."; leaf last-index-number { type uint64; description "The last numeric index number of a log entry. Zero means to start at the beginning of the log. - Entries subsequent to this will be passed to the + Entries after this will be passed to the requester."; } } case timestamp { leaf timestamp { type yang:date-and-time; description "Timestamp from which to start the extraction. The - next log entry subsequent to this timestamp is to + next log entry after this timestamp is to be sent."; } description "Timestamp from which to start the extraction."; } } leaf log-entry-quantity { type uint16; description "The number of log entries to be returned. If omitted, it means all of them."; } } - uses log-identifier; } output { container system-event-logs { description "The requested data of the measurement event logs"; list node-data { unique "name"; description "Event logs of a node in a distributed system identified by the node name"; @@ -1199,26 +1213,27 @@ /**************************************/ /* Config & Oper accessible nodes */ /**************************************/ container rats-support-structures { description "The datastore definition enabling verifiers or relying parties to discover the information necessary to use the remote attestation RPCs appropriately."; container compute-nodes { - if-feature "tpm:tpms"; + if-feature "tpm:mtpm"; description - "Holds the set device subsystems/components in this composite - device that support TPM operations."; + "Holds the set of device subsystems/components in this + composite device that support TPM operations."; list compute-node { key "node-id"; + unique "node-name"; config false; min-elements 2; description "A component within this composite device which supports TPM operations."; leaf node-id { type string; description "ID of the compute node, such as Board Serial Number."; } @@ -1251,29 +1266,29 @@ list tpm { key "name"; unique "path"; description "A list of TPMs in this composite device that RATS can be conducted with."; uses tpm-name; leaf hardware-based { type boolean; config false; + mandatory true; description - "Answers the question: is this TPM is a hardware based - TPM?"; + "System generated indication of whether this is a + hardware based TPM."; } leaf physical-index { if-feature "hw:entity-mib"; type int32 { range "1..2147483647"; - } config false; description "The entPhysicalIndex for the TPM."; reference "RFC 6933: Entity MIB (Version 4) - entPhysicalIndex"; } leaf path { type string; config false; @@ -1271,25 +1286,25 @@ config false; description "The entPhysicalIndex for the TPM."; reference "RFC 6933: Entity MIB (Version 4) - entPhysicalIndex"; } leaf path { type string; config false; description - "Path to a unique TPM on a device. This can change across - reboots."; + "Device path to a unique TPM on a device. This can change + across reboots."; } leaf compute-node { - if-feature "tpm:tpms"; + if-feature "tpm:mtpm"; type compute-node-ref; config false; mandatory true; description "Indicates the compute node measured by this TPM."; } leaf manufacturer { type string; config false; description @@ -1332,45 +1347,44 @@ "TPM2.0-Structures: https://www.trustedcomputinggroup.org/wp-content/uploads/ TPM-Rev-2.0-Part-2-Structures-01.38.pdf Section 10.9.7"; leaf tpm20-hash-algo { type identityref { base taa:hash; } must '/tpm:rats-support-structures' + '/tpm:attester-supported-algos' + '/tpm:tpm20-hash' { - error-message - "This platform does not support tpm20-hash-algo"; + error-message "This platform does not support tpm20-hash-algo"; } description "The hash scheme actively being used to hash a one or more TPM2.0 PCRs."; } leaf-list pcr-index { type tpm:pcr; description "Defines what TPM2 PCRs are available to be extracted."; } } leaf status { type enumeration { enum operational { value 0; description - "The TPM currently is currently running normally and + "The TPM currently is running normally and is ready to accept and process TPM quotes."; reference "TPM2.0-Arch: - TPM-Rev-2.0-Part-1-Architecture-01.07-2014-03-13.pdf + https://trustedcomputinggroup.org/wp-content/uploads/ + TCG_TPM2_r1p59_Part1_Architecture_pub.pdf Section 12"; - } enum non-operational { value 1; description "TPM is in a state such as startup or shutdown which precludes the processing of TPM quotes."; } } config false; mandatory true; @@ -1373,42 +1387,44 @@ } } config false; mandatory true; description "TPM chip self-test status."; } container certificates { description "The TPM's certificates, including EK certificates - and AK certificates."; + and Attestation Key certificates."; list certificate { key "name"; description "Three types of certificates can be accessed via this statement, including Initial Attestation Key Certificate, Local Attestation Key Certificate or Endorsement Key Certificate."; leaf name { type string; description "An arbitrary name uniquely identifying a certificate associated within key within a TPM."; } leaf keystore-ref { + if-feature "ks:asymmetric-keys"; type leafref { path "/ks:keystore/ks:asymmetric-keys/ks:asymmetric-key" - + "/ks:certificates/ks:certificate/ks:name"; + + "/ks:name"; } description "A reference to a specific certificate of an asymmetric key in the Keystore."; + } leaf type { type enumeration { enum endorsement-certificate { value 0; description "Endorsement Key (EK) Certificate type."; reference "TPM2.0-Key: https://trustedcomputinggroup.org/wp-content/ @@ -1405,41 +1421,44 @@ } leaf type { type enumeration { enum endorsement-certificate { value 0; description "Endorsement Key (EK) Certificate type."; reference "TPM2.0-Key: https://trustedcomputinggroup.org/wp-content/ - uploads/TCG_IWG_DevID_v1r2_02dec2020.pdf + uploads/TPM-2p0-Keys-for-Device-Identity- + and-Attestation_v1_r12_pub10082021.pdf Section 3.11"; } enum initial-attestation-certificate { value 1; description "Initial Attestation key (IAK) Certificate type."; reference "TPM2.0-Key: https://trustedcomputinggroup.org/wp-content/ - uploads/TCG_IWG_DevID_v1r2_02dec2020.pdf + uploads/TPM-2p0-Keys-for-Device-Identity- + and-Attestation_v1_r12_pub10082021.pdf Section 3.2"; } enum local-attestation-certificate { value 2; description "Local Attestation Key (LAK) Certificate type."; reference "TPM2.0-Key: https://trustedcomputinggroup.org/wp-content/ - uploads/TCG_IWG_DevID_v1r2_02dec2020.pdf + uploads/TPM-2p0-Keys-for-Device-Identity- + and-Attestation_v1_r12_pub10082021.pdf Section 3.2"; } } description "Function supported by this certificate from within the TPM."; } } } } @@ -1491,77 +1509,73 @@ Figure 1 2.1.2. 'ietf-tcg-algs' This document has encoded the TCG Algorithm definitions of [TCG-Algos], revision 1.32. By including this full table as a separate YANG file within this document, it is possible for other YANG models to leverage the contents of this model. Specific - references to [RFC7748], [ISO-IEC-9797-1], [ISO-IEC-9797-2], - [ISO-IEC-10116], [ISO-IEC-10118-3], [ISO-IEC-14888-3], - [ISO-IEC-15946-1], [ISO-IEC-18033-3], [IEEE-Std-1363-2000], - [IEEE-Std-1363a-2004], [NIST-PUB-FIPS-202], [NIST-SP800-38C], - [NIST-SP800-38D], [NIST-SP800-38F], [NIST-SP800-56A], - [NIST-SP800-108], [bios-log], [ima-log], and [netequip-boot-log] - exist within the YANG Model. + references to [RFC2104], [RFC8017], [ISO-IEC-9797-1], + [ISO-IEC-9797-2], [ISO-IEC-10116], [ISO-IEC-10118-3], + [ISO-IEC-14888-3], [ISO-IEC-15946-1], [ISO-IEC-18033-3], + [IEEE-Std-1363-2000], [IEEE-Std-1363a-2004], [NIST-PUB-FIPS-202], + [NIST-SP800-38C], [NIST-SP800-38D], [NIST-SP800-38F], + [NIST-SP800-56A], [NIST-SP800-108], [bios-log], [ima-log], as well as + Appendix A and Appendix B exist within the YANG Model. 2.1.2.1. Features There are two types of features supported: 'TPM12' and 'TPM20'. Support for either of these features indicates that a cryptoprocessor supporting the corresponding type of TCG TPM API is present on an Attester. Most commonly, only one type of cryptoprocessor will be available on an Attester. 2.1.2.2. Identities There are three types of identities in this model: 1. Cryptographic functions supported by a TPM algorithm; these include: 'asymmetric', 'symmetric', 'hash', 'signing', 'anonymous_signing', 'encryption_mode', 'method', and 'object_type'. The definitions of each of these are in Table 2 of [TCG-Algos]. - 2. API specifications for TPMs: 'tpm12' and 'tpm20' + 2. API specifications for TPM types: 'tpm12' and 'tpm20' 3. Specific algorithm types: Each algorithm type defines what cryptographic functions may be supported, and on which type of API specification. It is not required that an implementation of a specific TPM will support all algorithm types. The contents of each specific algorithm mirrors what is in Table 3 of [TCG-Algos]. 2.1.2.3. YANG Module - - file "ietf-tcg-algs@2022-02-16.yang" + file "ietf-tcg-algs@2022-03-09.yang" module ietf-tcg-algs { yang-version 1.1; namespace "urn:ietf:params:xml:ns:yang:ietf-tcg-algs"; prefix taa; organization - "IETF RATS Working Group"; - + "IETF RATS (Remote ATtestation procedureS) Working Group"; contact "WG Web: WG List: Author: Eric Voit "; - description - "This module defines a identities for asymmetric algorithms. + "This module defines identities for asymmetric algorithms. Copyright (c) 2022 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). 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. The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', @@ -1564,21 +1578,21 @@ 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. 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 2022-02-16 { + revision 2022-03-09 { description "Initial version"; reference "RFC XXXX: A YANG Data Model for Challenge-Response-based Remote Attestation Procedures using TPMs"; } /*****************/ /* Features */ /*****************/ @@ -1591,35 +1605,35 @@ https://trustedcomputinggroup.org/wp-content/uploads/TPM- Main-Part-2-TPM-Structures_v1.2_rev116_01032011.pdf"; } feature tpm20 { description "This feature indicates algorithm support for the TPM 2.0 API as per Section 11.4 of Trusted Platform Module Library Part 1: Architecture. See TPM2.0-Arch: https://trustedcomputinggroup.org/wp-content/uploads/ - TPM-Rev-2.0-Part-1-Architecture-01.07-2014-03-13.pdf"; + TCG_TPM2_r1p59_Part1_Architecture_pub.pdf"; } /*****************/ /* Identities */ /*****************/ identity asymmetric { description "A TCG recognized asymmetric algorithm with a public and private key."; reference "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 2, - http://trustedcomputinggroup.org/resource/tcg-algorithm-registry/ - TCG-_Algorithm_Registry_r1p32_pub"; + https://trustedcomputinggroup.org/resource/ + tcg-algorithm-registry/TCG-_Algorithm_Registry_r1p32_pub"; } identity symmetric { description "A TCG recognized symmetric algorithm with only a private key."; reference "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 2"; } identity hash { @@ -1671,33 +1686,31 @@ identity tpm12 { if-feature "tpm12"; base cryptoprocessor; description "Supportable by a TPM1.2."; reference "TPM1.2-Structures: https://trustedcomputinggroup.org/wp-content/uploads/ TPM-Main-Part-2-TPM-Structures_v1.2_rev116_01032011.pdf - TPM_ALGORITHM_ID values, page 18"; + TPM_ALGORITHM_ID values, Section 4.8"; } - identity tpm20 { if-feature "tpm20"; base cryptoprocessor; description "Supportable by a TPM2."; reference "TPM2.0-Structures: https://trustedcomputinggroup.org/wp-content/uploads/ - TPM-Rev-2.0-Part-2-Structures-01.38.pdf - The TCG Algorithm Registry. Table 9"; + TPM-Rev-2.0-Part-2-Structures-01.38.pdf"; } identity TPM_ALG_RSA { if-feature "tpm12 or tpm20"; base tpm12; base tpm20; base asymmetric; base object_type; description "RSA algorithm"; @@ -1719,39 +1732,40 @@ ISO/IEC 18033-3. ALG_ID: 0x0003"; } identity TPM_ALG_SHA1 { if-feature "tpm12 or tpm20"; base hash; base tpm12; base tpm20; description "SHA1 algorithm - Deprecated due to insufficient cryptographic - protection. However it is still useful for hash algorithms + protection. However, it is still useful for hash algorithms where protection is not required."; reference "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and ISO/IEC 10118-3. ALG_ID: 0x0004"; } identity TPM_ALG_HMAC { if-feature "tpm12 or tpm20"; base tpm12; base tpm20; base hash; base signing; description "Hash Message Authentication Code (HMAC) algorithm"; reference "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3, - ISO/IEC 9797-2 and RFC2014. ALG_ID: 0x0005"; + ISO/IEC 9797-2 and RFC2104. ALG_ID: 0x0005"; } + identity TPM_ALG_AES { if-feature "tpm12"; base tpm12; base symmetric; description "The AES algorithm with various key sizes"; reference "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3, ISO/IEC 18033-3. ALG_ID: 0x0006"; } @@ -1861,33 +1876,36 @@ "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3. ALG_ID: 0x0013"; } identity TPM_ALG_RSASSA { if-feature "tpm20"; base tpm20; base asymmetric; base signing; description - "Signature algorithm defined in section 8.2 (RSASSAPKCS1-v1_5)"; + "RFC 8017 Signature algorithm defined in section 8.2 + (RSASSAPKCS1-v1_5)"; reference "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and RFC 8017. ALG_ID: 0x0014"; + } identity TPM_ALG_RSAES { if-feature "tpm20"; base tpm20; base asymmetric; base encryption_mode; description - "Signature algorithm defined in section 7.2 (RSAES-PKCS1-v1_5)"; + "RFC 8017 Signature algorithm defined in section 7.2 + (RSAES-PKCS1-v1_5)"; reference "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and RFC 8017. ALG_ID: 0x0015"; } identity TPM_ALG_RSAPSS { if-feature "tpm20"; base tpm20; base asymmetric; base signing; @@ -1924,21 +1942,21 @@ identity TPM_ALG_ECDH { if-feature "tpm20"; base tpm20; base asymmetric; base method; description "Secret sharing using ECC"; reference "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and - NIST SP800-56A and RFC 7748. ALG_ID: 0x0019"; + NIST SP800-56A. ALG_ID: 0x0019"; } identity TPM_ALG_ECDAA { if-feature "tpm20"; base tpm20; base asymmetric; base signing; base anonymous_signing; description "Elliptic-curve based anonymous signing scheme"; @@ -2026,23 +2043,25 @@ if-feature "tpm20"; base tpm20; base asymmetric; base object_type; description "Prime field ECC"; reference "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and ISO/IEC 15946-1. ALG_ID: 0x0023"; } + identity TPM_ALG_SYMCIPHER { if-feature "tpm20"; base tpm20; + base symmetric; description "Object type for a symmetric block cipher"; reference "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and TCG TPM 2.0 library specification. ALG_ID: 0x0025"; } identity TPM_ALG_CAMELLIA { if-feature "tpm20"; base tpm20; @@ -2233,21 +2250,21 @@ description "Edwards-curve Digital Signature Algorithm (PureEdDSA)"; reference "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and RFC 8032. ALG_ID: 0x0060"; } } Note that not all cryptographic functions are required for use by - ietf-tpm-remote-attestation.yang. However the full definition of + "ietf-tpm-remote-attestation.yang". However the full definition of Table 3 of [TCG-Algos] will allow use by additional YANG specifications. 3. IANA Considerations This document registers the following namespace URIs in the [xml-registry] as per [RFC3688]: URI: urn:ietf:params:xml:ns:yang:ietf-tpm-remote-attestation @@ -2295,152 +2312,88 @@ default). These data nodes may be considered sensitive or vulnerable in some network environments. Write operations (e.g., _edit-config_) to these data nodes without proper protection can have a negative effect on network operations. These are the subtrees and data nodes as well as their sensitivity/vulnerability: Container '/rats-support-structures/attester-supported-algos': 'tpm1 2-asymmetric-signing', 'tpm12-hash', 'tpm20-asymmetric-signing', and 'tpm20-hash'. All could be populated with algorithms that are not supported by the underlying physical TPM installed by the - equipment vendor. + equipment vendor. A vendor should restrict the ability to + configure unsupported algorithms. Container: '/rats-support-structures/tpms': 'name': Although shown - as 'rw', it is system generated. Therefore it should not be + as 'rw', it is system generated. Therefore, it should not be possible for an operator to add or remove a TPM from the configuration. 'tpm20-pcr-bank': It is possible to configure PCRs for extraction which are not being extended by system software. This could unnecessarily use TPM resources. 'certificates': It is possible to provision a certificate which does not correspond to an Attestation Identity Key (AIK) within the TPM 1.2, or an Attestation Key (AK) within the TPM 2.0 - respectively. + respectively. In such a case, calls to an RPC requesting this + specific certificate could result in either no response or a + response for an unexpected TPM. - RPC 'tpm12-challenge-response-attestation': It must be verified that - the certificate is for an active AIK, i.e., the certificate - provided is able to support Attestation on the targeted TPM 1.2. + RPC 'tpm12-challenge-response-attestation': The receiver of the RPC + response must verify that the certificate is for an active AIK, + i.e., the certificate has been confirmed by a third party as being + able to support Attestation on the targeted TPM 1.2. - RPC 'tpm20-challenge-response-attestation': It must be verified that - the certificate is for an active AK, i.e., the quote signature - associated with RPC response has been generated by an entity - legitimately able to perform Attestation on the targeted TPM 2.0. + RPC 'tpm20-challenge-response-attestation': The receiver of the RPC + response must verify that the certificate is for an active AK, + i.e., the private key confirmation of the quote signature within + the RPC response has been confirmed by a third party to belong to + an entity legitimately able to perform Attestation on the targeted + TPM 2.0. RPC 'log-retrieval': Requesting a large volume of logs from the attester could require significant system resources and create a denial of service. Information collected through the RPCs above could reveal that specific versions of software and configurations of endpoints that - could identify vulnerabilities on those systems. Therefore RPCs + could identify vulnerabilities on those systems. Therefore, RPCs should be protected by NACM [RFC8341] with a default setting of deny- all to limit the extraction of attestation data by only authorized Verifiers. For the YANG module ietf-tcg-algs.yang, please use care when selecting specific algorithms. The introductory section of [TCG-Algos] highlights that some algorithms should be considered legacy, and recommends implementers and adopters diligently evaluate available information such as governmental, industrial, and academic research before selecting an algorithm for use. -5. Change Log - - Changes from version 08 to version 09: - - * AD Review comments - - Changes from version 08 to version 09: - - * Minor formatting tweaks for shepherd. IANA registered. - - Changes from version 05 to version 06: - - * More YANG Dr comments covered - - Changes from version 04 to version 05: - - * YANG Dr comments covered - - Changes from version 03 to version 04: - - * TPM1.2 Quote1 eliminated - - * YANG model simplifications so redundant info isn't exposed - - Changes from version 02 to version 03: - - * moved to tcg-algs - - * cleaned up model to eliminate sources of errors - - * removed key establishment RPC - - * added lots of XPATH which must all be scrubbed still - - * Descriptive text added on model contents. - - Changes from version 01 to version 02: - - * Extracted Crypto-types into a separate YANG file - - * Mades the algorithms explicit, not strings - - * Hash Algo as key the selected TPM2 PCRs - - * PCR numbers are their own type - - * Eliminated nested keys for node-id plus tpm-name - - * Eliminated TPM-Name of "ALL" - - * Added TPM-Path - - Changes from version 00 to version 01: - - * Addressed author's comments - - * Extended complementary details about attestation-certificates - - * Relabeled chunk-size to log-entry-quantity - - * Relabeled location with compute-node or tpm-name where appropriate - - * Added a valid entity-mib physical-index to compute-node and tpm- - name to map it back to hardware inventory - - * Relabeled name to tpm_name - - * Removed event-string in last-entry - -6. References - -6.1. Normative References +5. References +5.1. Normative References [bios-log] "TCG PC Client Platform Firmware Profile Specification, Section 9.4.5.2", n.d., . [BIOS-Log-Event-Type] "TCG PC Client Platform Firmware Profile Specification", n.d., . [I-D.ietf-netconf-keystore] Watsen, K., "A YANG Data Model for a Keystore", Work in - Progress, Internet-Draft, draft-ietf-netconf-keystore-23, - 14 December 2021, . + Progress, Internet-Draft, draft-ietf-netconf-keystore-24, + 7 March 2022, . [I-D.ietf-rats-architecture] Birkholz, H., Thaler, D., Richardson, M., Smith, N., and W. Pan, "Remote Attestation Procedures Architecture", Work in Progress, Internet-Draft, draft-ietf-rats-architecture- 15, 8 February 2022, . [I-D.ietf-rats-tpm-based-network-device-attest] Fedorkow, G., Voit, E., and J. Fitzgerald-McKay, "TPM- @@ -2487,25 +2440,20 @@ [ISO-IEC-9797-1] "Message Authentication Codes (MACs) - ISO/IEC 9797-1:2011", n.d., . [ISO-IEC-9797-2] "Message Authentication Codes (MACs) - ISO/IEC 9797-2:2011", n.d., . - [netequip-boot-log] - "IMA Policy Kernel Documentation", n.d., - . - [NIST-PUB-FIPS-202] "SHA-3 Standard: Permutation-Based Hash and Extendable- Output Functions", n.d., . [NIST-SP800-108] "Recommendation for Key Derivation Using Pseudorandom Functions", n.d., . [NIST-SP800-56A] "Recommendation for Pair-Wise Key-Establishment Schemes Using Discrete Logarithm Cryptography", n.d., . - [RFC2014] Weinrib, A. and J. Postel, "IRTF Research Group Guidelines - and Procedures", BCP 8, RFC 2014, DOI 10.17487/RFC2014, - October 1996, . + [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- + Hashing for Message Authentication", RFC 2104, + DOI 10.17487/RFC2104, February 1997, + . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, DOI 10.17487/RFC3688, January 2004, . @@ -2564,24 +2513,20 @@ [RFC6933] Bierman, A., Romascanu, D., Quittek, J., and M. Chandramouli, "Entity MIB (Version 4)", RFC 6933, DOI 10.17487/RFC6933, May 2013, . [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", RFC 6991, DOI 10.17487/RFC6991, July 2013, . - [RFC7748] Langley, A., Hamburg, M., and S. Turner, "Elliptic Curves - for Security", RFC 7748, DOI 10.17487/RFC7748, January - 2016, . - [RFC8017] Moriarty, K., Ed., Kaliski, B., Jonsson, J., and A. Rusch, "PKCS #1: RSA Cryptography Specifications Version 2.2", RFC 8017, DOI 10.17487/RFC8017, November 2016, . [RFC8032] Josefsson, S. and I. Liusvaara, "Edwards-Curve Digital Signature Algorithm (EdDSA)", RFC 8032, DOI 10.17487/RFC8032, January 2017, . @@ -2626,93 +2571,201 @@ . [TPM2.0] TCG, ., "TPM 2.0 Library Specification", 15 March 2013, . [TPM2.0-Arch] "Trusted Platform Module Library - Part 1: Architecture", n.d., . + content/uploads/ + TCG_TPM2_r1p59_Part1_Architecture_pub.pdf>. [TPM2.0-Key] TCG, ., "TPM 2.0 Keys for Device Identity and Attestation, - Rev10", 14 April 2021, . + Rev12", 8 October 2021, + . [TPM2.0-Structures] "Trusted Platform Module Library - Part 2: Structures", n.d., . - [xml-registry] - "IETF XML Registry", n.d., - . - - [yang-parameters] - "YANG Parameters", n.d., - . + [UEFI-Secure-Boot] + "Unified Extensible Firmware Interface (UEFI) + Specification Version 2.9 (March 2021), Section 32.1 + (Secure Boot)", n.d., + . -6.2. Informative References +5.2. Informative References [I-D.ietf-rats-reference-interaction-models] Birkholz, H., Eckel, M., Pan, W., and E. Voit, "Reference Interaction Models for Remote Attestation Procedures", Work in Progress, Internet-Draft, draft-ietf-rats- reference-interaction-models-05, 26 January 2022, . + [IMA-Kernel-Source] + "Linux Integrity Measurement Architecture (IMA): Kernel + Sourcecode", n.d., . + [NIST-915121] "True Randomness Can't be Left to Chance: Why entropy is important for information security", n.d., . + [xml-registry] + "IETF XML Registry", n.d., + . + + [yang-parameters] + "YANG Parameters", n.d., + . + +Appendix A. Integrity Measurement Architecture (IMA) + + IMA extends the principles of Measured Boot [TPM2.0-Arch] and Secure + Boot [UEFI-Secure-Boot] to the Linux operating system, applying it to + operating system applications and files. IMA has been part of the + Linux integrity subsystem of the Linux kernel since 2009 (kernel + version 2.6.30). The IMA mechanism represented by the YANG module in + this specification is rooted in the kernel version 5.16 + [IMA-Kernel-Source]. IMA enables the protection of system integrity + by collecting (commonly referred to as measuring) and storing + measurements (called Claims in the context of IETF RATS) of files + before execution so that these measurements can be used later, at + system runtime, in remote attestation procedures. IMA acts in + support of the appraisal of Evidence (which includes measurement + Claims) by leveraging reference integrity measurements stored in + extended file attributes. + + In support of the appraisal of Evidence, IMA maintains an ordered + list of measurements in kernel-space, the Stored Measurement Log + (SML), for all files that have been measured before execution since + the operating system was started. Although IMA can be used without a + TPM, it is typically used in conjunction with a TPM to anchor the + integrity of the SML in a hardware-protected secure storage location, + i.e., Platform Configuration Registers (PCRs) provided by TPMs. IMA + provides the SML in both binary and ASCII representations in the + Linux security file system _securityfs_ ("/sys/kernel/security/ + ima/"). + + IMA templates define the format of the SML, i.e., which fields are + included in a log record. Examples are file path, file hash, user + ID, group ID, file signature, and extended file attributes. IMA + comes with a set of predefined template formats and also allows a + custom format, i.e., a format consisting of template fields supported + by IMA. Template usage is typically determined by boot arguments + passed to the kernel. Alternatively, the format can also be hard- + compiled into custom kernels. IMA templates and fields are + extensible in the kernel source code. As a result, more template + fields can be added in the future. + + IMA policies define which files are measured using the IMA policy + language. Built-in policies can be passed as boot arguments to the + kernel. Custom IMA policies can be defined once during runtime or be + hard-compiled into a custom kernel. If no policy is defined, no + measurements are taken and IMA is effectively disabled. + +Appendix B. IMA for Network Equipment Boot Logs + + Network equipment can generally implement similar IMA-protected + functions to generate measurements (Claims) about the boot process of + a device and enable corresponding remote attestation. Network + Equipment Boot Logs combine the measurement and logging of boot + components and operating system components (executables and files) + into a single log file in identical IMA format. + + During the boot process of the network device, i.e., from BIOS to the + end of the operating system and user-space, all files executed during + this process can be measured and logged in the order of their + execution. When the Verifier initiates a remote attestation process + (e.g., challenge-response remote attestation as defined in this + document), the network equipment takes on the role of an Attester and + can convey to the Verifier Claims that comprise the measurement log + as well as the corresponding PCR values (Evidence) of a TPM. + + The verifier can appraise the integrity (compliance with the + Reference Values) of each executed file by comparing its measured + value with the Reference Value. Based on the execution order, the + Verifier can compute a PCR reference value (by replaying the log) and + compare it to the Measurement Log Claims obtained in conjunction with + the PCR Evidence to assess their trustworthiness with respect to an + intended operational state. + + Not only during the operating system loading phase, even during the + BIOS boot phase, network equipment usually executes multiple + components. With this measurement log mechanism, network equipment + can take on the role of an Attester, proving to the Verifier the + trustworthiness of its boot process. Using the measurement log, + Verifiers can precisely identify mismatching log entries to infer + potentially tampered components. + + This mechanism also supports scenarios that modify files on the + Attester and are executed during the boot phase (e.g., updating/ + patching) by simply updating the appropriate Reference Values in + Reference Integrity Manifests that inform Verifiers about how an + Attester is composed. + Authors' Addresses Henk Birkholz Fraunhofer SIT Rheinstrasse 75 64295 Darmstadt Germany + Email: henk.birkholz@sit.fraunhofer.de Michael Eckel Fraunhofer SIT Rheinstrasse 75 64295 Darmstadt Germany + Email: michael.eckel@sit.fraunhofer.de Shwetha Bhandari ThoughtSpot - Email: shwetha.bhandari@thoughtspot.com + Email: shwetha.bhandari@thoughtspot.com Eric Voit Cisco Systems + Email: evoit@cisco.com Bill Sulzen Cisco Systems + Email: bsulzen@cisco.com + Liang Xia (Frank) Huawei Technologies 101 Software Avenue, Yuhuatai District Nanjing Jiangsu, 210012 China + Email: Frank.Xialiang@huawei.com Tom Laffey Hewlett Packard Enterprise + Email: tom.laffey@hpe.com Guy C. Fedorkow Juniper Networks 10 Technology Park Drive Westford + Email: gfedorkow@juniper.net