idnits 2.17.1
draft-ietf-rats-yang-tpm-charra-20.txt:
Checking boilerplate required by RFC 5378 and the IETF Trust (see
https://trustee.ietf.org/license-info):
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt:
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/checklist :
----------------------------------------------------------------------------
** There are 58 instances of too long lines in the document, the longest
one being 8 characters in excess of 72.
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
== Line 196 has weird spacing: '...te-name cer...'
== Line 226 has weird spacing: '...r-index pcr...'
== Line 310 has weird spacing: '...-number uin...'
== Line 372 has weird spacing: '...version ide...'
== Line 376 has weird spacing: '...sh-algo ide...'
-- The document date (18 May 2022) is 681 days in the past. Is this
intentional?
Checking references for intended status: Proposed Standard
----------------------------------------------------------------------------
(See RFCs 3967 and 4897 for information about using normative references
to lower-maturity documents in RFCs)
-- Possible downref: Non-RFC (?) normative reference: ref.
'BIOS-Log-Event-Type'
== Outdated reference: A later version (-35) exists of
draft-ietf-netconf-keystore-24
== Outdated reference: A later version (-22) exists of
draft-ietf-rats-architecture-15
** Downref: Normative reference to an Informational draft:
draft-ietf-rats-architecture (ref. 'I-D.ietf-rats-architecture')
** Downref: Normative reference to an Informational draft:
draft-ietf-rats-tpm-based-network-device-attest (ref.
'I-D.ietf-rats-tpm-based-network-device-attest')
-- Possible downref: Non-RFC (?) normative reference: ref.
'IEEE-Std-1363-2000'
-- Possible downref: Non-RFC (?) normative reference: ref.
'IEEE-Std-1363a-2004'
-- Possible downref: Non-RFC (?) normative reference: ref. 'ISO-IEC-10116'
-- Possible downref: Non-RFC (?) normative reference: ref. 'ISO-IEC-10118-3'
-- Possible downref: Non-RFC (?) normative reference: ref. 'ISO-IEC-14888-3'
-- Possible downref: Non-RFC (?) normative reference: ref. 'ISO-IEC-15946-1'
-- Possible downref: Non-RFC (?) normative reference: ref. 'ISO-IEC-18033-3'
-- Possible downref: Non-RFC (?) normative reference: ref. 'ISO-IEC-9797-1'
-- Possible downref: Non-RFC (?) normative reference: ref. 'ISO-IEC-9797-2'
-- Possible downref: Non-RFC (?) normative reference: ref.
'NIST-PUB-FIPS-202'
-- Possible downref: Non-RFC (?) normative reference: ref. 'NIST-SP800-108'
-- Possible downref: Non-RFC (?) normative reference: ref. 'NIST-SP800-38C'
-- Possible downref: Non-RFC (?) normative reference: ref. 'NIST-SP800-38D'
-- Possible downref: Non-RFC (?) normative reference: ref. 'NIST-SP800-38F'
-- Possible downref: Non-RFC (?) normative reference: ref. 'NIST-SP800-56A'
** Downref: Normative reference to an Informational RFC: RFC 2104
** Downref: Normative reference to an Informational RFC: RFC 8017
** Downref: Normative reference to an Informational RFC: RFC 8032
-- Possible downref: Non-RFC (?) normative reference: ref. 'TCG-Algos'
-- Possible downref: Non-RFC (?) normative reference: ref.
'UEFI-Secure-Boot'
== Outdated reference: A later version (-09) exists of
draft-ietf-rats-reference-interaction-models-05
Summary: 6 errors (**), 0 flaws (~~), 9 warnings (==), 19 comments (--).
Run idnits with the --verbose option for more detailed information about
the items above.
--------------------------------------------------------------------------------
2 RATS Working Group H. Birkholz
3 Internet-Draft M. Eckel
4 Intended status: Standards Track Fraunhofer SIT
5 Expires: 19 November 2022 S. Bhandari
6 ThoughtSpot
7 E. Voit
8 B. Sulzen
9 Cisco
10 L. Xia
11 Huawei
12 T. Laffey
13 HPE
14 G. Fedorkow
15 Juniper
16 18 May 2022
18 A YANG Data Model for Challenge-Response-based Remote Attestation
19 Procedures using TPMs
20 draft-ietf-rats-yang-tpm-charra-20
22 Abstract
24 This document defines YANG RPCs and a few configuration nodes
25 required to retrieve attestation evidence about integrity
26 measurements from a device, following the operational context defined
27 in TPM-based Network Device Remote Integrity Verification.
28 Complementary measurement logs are also provided by the YANG RPCs,
29 originating from one or more roots of trust for measurement (RTMs).
30 The module defined requires at least one TPM 1.2 or TPM 2.0 as well
31 as a corresponding TPM Software Stack (TSS), or equivalent hardware
32 implementations that include the protected capabilities as provided
33 by TPMs as well as a corresponding software stack, included in the
34 device components of the composite device the YANG server is running
35 on.
37 Status of This Memo
39 This Internet-Draft is submitted in full conformance with the
40 provisions of BCP 78 and BCP 79.
42 Internet-Drafts are working documents of the Internet Engineering
43 Task Force (IETF). Note that other groups may also distribute
44 working documents as Internet-Drafts. The list of current Internet-
45 Drafts is at https://datatracker.ietf.org/drafts/current/.
47 Internet-Drafts are draft documents valid for a maximum of six months
48 and may be updated, replaced, or obsoleted by other documents at any
49 time. It is inappropriate to use Internet-Drafts as reference
50 material or to cite them other than as "work in progress."
52 This Internet-Draft will expire on 19 November 2022.
54 Copyright Notice
56 Copyright (c) 2022 IETF Trust and the persons identified as the
57 document authors. All rights reserved.
59 This document is subject to BCP 78 and the IETF Trust's Legal
60 Provisions Relating to IETF Documents (https://trustee.ietf.org/
61 license-info) in effect on the date of publication of this document.
62 Please review these documents carefully, as they describe your rights
63 and restrictions with respect to this document. Code Components
64 extracted from this document must include Revised BSD License text as
65 described in Section 4.e of the Trust Legal Provisions and are
66 provided without warranty as described in the Revised BSD License.
68 Table of Contents
70 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
71 1.1. Requirements notation . . . . . . . . . . . . . . . . . . 3
72 2. The YANG Module for Basic Remote Attestation Procedures . . . 3
73 2.1. YANG Modules . . . . . . . . . . . . . . . . . . . . . . 3
74 2.1.1. 'ietf-tpm-remote-attestation' . . . . . . . . . . . . 4
75 2.1.2. 'ietf-tcg-algs' . . . . . . . . . . . . . . . . . . . 33
76 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 48
77 4. Security Considerations . . . . . . . . . . . . . . . . . . . 49
78 5. References . . . . . . . . . . . . . . . . . . . . . . . . . 51
79 5.1. Normative References . . . . . . . . . . . . . . . . . . 51
80 5.2. Informative References . . . . . . . . . . . . . . . . . 56
81 Appendix A. Integrity Measurement Architecture (IMA) . . . . . . 56
82 Appendix B. IMA for Network Equipment Boot Logs . . . . . . . . 57
83 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 58
85 1. Introduction
87 This document is based on the general terminology defined in the
88 [I-D.ietf-rats-architecture] and uses the operational context defined
89 in [I-D.ietf-rats-tpm-based-network-device-attest] as well as the
90 interaction model and information elements defined in
91 [I-D.ietf-rats-reference-interaction-models]. The currently
92 supported hardware security modules (HSMs) are the Trusted Platform
93 Modules (TPMs) [TPM1.2] and [TPM2.0] as specified by the Trusted
94 Computing Group (TCG). One TPM, or multiple TPMs in the case of a
95 Composite Device, are required in order to use the YANG module
96 defined in this document. Each TPM is used as a root of trust for
97 storage (RTS) in order to store system security measurement Evidence.
98 And each TPM is used as a root of trust for reporting (RTR) in order
99 to retrieve attestation Evidence. This is done by using a YANG RPC
100 to request a quote which exposes a rolling hash of the security
101 measurements held internally within the TPM.
103 Specific terms imported from [I-D.ietf-rats-architecture] and used in
104 this document include: Attester, Composite Device, Evidence.
106 Specific terms imported from [TPM2.0-Key] and used in this document
107 include: Endorsement Key (EK), Initial Attestation Key (IAK),
108 Attestation Identity Key (AIK), Local Attestation Key (LAK).
110 1.1. Requirements notation
112 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
113 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
114 "OPTIONAL" in this document are to be interpreted as described in
115 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
116 capitals, as shown here.
118 2. The YANG Module for Basic Remote Attestation Procedures
120 One or more TPMs MUST be embedded in a Composite Device that provides
121 attestation evidence via the YANG module defined in this document.
122 The ietf-tpm-remote-attestation YANG module enables a composite
123 device to take on the role of an Attester, in accordance with the
124 Remote Attestation Procedures (RATS) architecture
125 [I-D.ietf-rats-architecture], and the corresponding challenge-
126 response interaction model defined in the
127 [I-D.ietf-rats-reference-interaction-models] document. A fresh nonce
128 with an appropriate amount of entropy [NIST-915121] MUST be supplied
129 by the YANG client in order to enable a proof-of-freshness with
130 respect to the attestation Evidence provided by the Attester running
131 the YANG datastore. Further, this nonce is used to prevent replay
132 attacks. The method for communicating the relationship of each
133 individual TPM to specific measured component within the Composite
134 Device is out of the scope of this document.
136 2.1. YANG Modules
138 In this section the several YANG modules are defined.
140 2.1.1. 'ietf-tpm-remote-attestation'
142 This YANG module imports modules from [RFC6991] with prefix 'yang',
143 [RFC8348] with prefix 'hw', [I-D.ietf-netconf-keystore] with prefix
144 'ks', and 'ietf-tcg-algs.yang' Section 2.1.2.3 with prefix 'taa'.
145 Additionally, references are made to [RFC8032], [RFC8017], [RFC6933],
146 [TPM1.2-Commands], [TPM2.0-Arch], [TPM2.0-Structures], [TPM2.0-Key],
147 [TPM1.2-Structures], [bios-log], [BIOS-Log-Event-Type], as well as
148 Appendix A and Appendix B.
150 2.1.1.1. Features
152 This module supports the following features:
154 * 'mtpm': Indicates that multiple TPMs on the device can support
155 remote attestation. For example, this feature could be used in
156 cases where multiple line cards are present, each with its own
157 TPM.
159 * 'bios': Indicates that the device supports the retrieval of BIOS/
160 UEFI event logs. [bios-log]
162 * 'ima': Indicates that the device supports the retrieval of event
163 logs from the Linux Integrity Measurement Architecture (IMA, see
164 Appendix A).
166 * 'netequip_boot': Indicates that the device supports the retrieval
167 of netequip boot event logs. See Appendix A and Appendix B.
169 2.1.1.2. Identities
171 This module supports the following types of attestation event logs:
172 'bios', 'ima', and 'netequip_boot'.
174 2.1.1.3. Remote Procedure Calls (RPCs)
176 In the following, RPCs for both TPM 1.2 and TPM 2.0 attestation
177 procedures are defined.
179 2.1.1.3.1. 'tpm12-challenge-response-attestation'
181 This RPC allows a Verifier to request signed TPM PCRs (_TPM Quote_
182 operation) from a TPM 1.2 compliant cryptoprocessor. Where the
183 feature 'mtpm' is active, and one or more 'certificate-name' is not
184 provided, all TPM 1.2 compliant cryptoprocessors will respond. A
185 YANG tree diagram of this RPC is as follows:
187 +---x tpm12-challenge-response-attestation {taa:tpm12}?
188 +---w input
189 | +---w tpm12-attestation-challenge
190 | +---w pcr-index* pcr
191 | +---w nonce-value binary
192 | +---w certificate-name* certificate-name-ref
193 | {tpm:mtpm}?
194 +--ro output
195 +--ro tpm12-attestation-response* []
196 +--ro certificate-name certificate-name-ref
197 +--ro up-time? uint32
198 +--ro TPM_QUOTE2? binary
200 2.1.1.3.2. 'tpm20-challenge-response-attestation'
202 This RPC allows a Verifier to request signed TPM PCRs (_TPM Quote_
203 operation) from a TPM 2.0 compliant cryptoprocessor. Where the
204 feature 'mtpm' is active, and one or more 'certificate-name' is not
205 provided, all TPM 2.0 compliant cryptoprocessors will respond. A
206 YANG tree diagram of this RPC is as follows:
208 +---x tpm20-challenge-response-attestation {taa:tpm20}?
209 +---w input
210 | +---w tpm20-attestation-challenge
211 | +---w nonce-value binary
212 | +---w tpm20-pcr-selection* []
213 | | +---w tpm20-hash-algo? identityref
214 | | +---w pcr-index* pcr
215 | +---w certificate-name* certificate-name-ref
216 | {tpm:mtpm}?
217 +--ro output
218 +--ro tpm20-attestation-response* []
219 +--ro certificate-name certificate-name-ref
220 +--ro TPMS_QUOTE_INFO binary
221 +--ro quote-signature? binary
222 +--ro up-time? uint32
223 +--ro unsigned-pcr-values* []
224 +--ro tpm20-hash-algo? identityref
225 +--ro pcr-values* [pcr-index]
226 +--ro pcr-index pcr
227 +--ro pcr-value? binary
229 An example of an RPC challenge requesting PCRs 0-7 from a SHA-256
230 bank could look like the following:
232
233
234 xmlns="urn:ietf:params:xml:ns:yang:ietf-tpm-remote-attestation">
235
236 (identifier of a TPM signature key with which the Verifier is
237 supposed to sign the attestation data)
238
239
240 0xe041307208d9f78f5b1bbecd19e2d152ad49de2fc5a7d8dbf769f6b8ffdeab9
241
242
243
245 TPM_ALG_SHA256
246
247 0
248 1
249 2
250 3
251 4
252 5
253 6
254 7
255
256
257
259 A successful response could be formatted as follows:
261
263
265
267 (instance of Certificate name in the Keystore)
268
269
270 (raw attestation data, i.e. the TPM quote; this includes
271 a composite digest of requested PCRs, the nonce,
272 and TPM 2.0 time information.)
273
274
275 (signature over attestation-data using the TPM key
276 identified by sig-key-id)
277
278
279
281 2.1.1.4. 'log-retrieval'
283 This RPC allows a Verifier to acquire the evidence which was extended
284 into specific TPM PCRs. A YANG tree diagram of this RPC is as
285 follows:
287 +---x log-retrieval
288 +---w input
289 | +---w log-type identityref
290 | +---w log-selector* []
291 | +---w name* string
292 | +---w (index-type)?
293 | | +--:(last-entry)
294 | | | +---w last-entry-value? binary
295 | | +--:(index)
296 | | | +---w last-index-number? uint64
297 | | +--:(timestamp)
298 | | +---w timestamp? yang:date-and-time
299 | +---w log-entry-quantity? uint16
300 +--ro output
301 +--ro system-event-logs
302 +--ro node-data* []
303 +--ro name? string
304 +--ro up-time? uint32
305 +--ro log-result
306 +--ro (attested_event_log_type)
307 +--:(bios) {bios}?
308 | +--ro bios-event-logs
309 | +--ro bios-event-entry* [event-number]
310 | +--ro event-number uint32
311 | +--ro event-type? uint32
312 | +--ro pcr-index? pcr
313 | +--ro digest-list* []
314 | | +--ro hash-algo? identityref
315 | | +--ro digest* binary
316 | +--ro event-size? uint32
317 | +--ro event-data* binary
318 +--:(ima) {ima}?
319 | +--ro ima-event-logs
320 | +--ro ima-event-entry* [event-number]
321 | +--ro event-number uint64
322 | +--ro ima-template? string
323 | +--ro filename-hint? string
324 | +--ro filedata-hash? binary
325 | +--ro filedata-hash-algorithm? string
326 | +--ro template-hash-algorithm? string
327 | +--ro template-hash? binary
328 | +--ro pcr-index? pcr
329 | +--ro signature? binary
330 +--:(netequip_boot) {netequip_boot}?
331 +--ro boot-event-logs
332 +--ro boot-event-entry* [event-number]
333 +--ro event-number uint64
334 +--ro ima-template? string
335 +--ro filename-hint? string
336 +--ro filedata-hash? binary
337 +--ro filedata-hash-algorithm? string
338 +--ro template-hash-algorithm? string
339 +--ro template-hash? binary
340 +--ro pcr-index? pcr
341 +--ro signature? binary
343 2.1.1.5. Data Nodes
345 This section provides a high level description of the data nodes
346 containing the configuration and operational objects with the YANG
347 model. For more details, please see the YANG model itself in
348 Figure 1.
350 Container 'rats-support-structures': This houses the set of
351 information relating to remote attestation for a device. This
352 includes specific device TPM(s), the compute nodes (such as line
353 cards) on which the TPM(s) reside, and the algorithms supported
354 across the platform.
356 Container 'tpms': Provides configuration and operational details for
357 each supported TPM, including the tpm-firmware-version, PCRs which
358 may be quoted, certificates which are associated with that TPM,
359 and the current operational status. Of note are the certificates
360 which are associated with that TPM. As a certificate is
361 associated with a particular TPM attestation key, knowledge of the
362 certificate allows a specific TPM to be identified.
364 +--rw tpms
365 +--rw tpm* [name]
366 +--rw name string
367 +--ro hardware-based boolean
368 +--ro physical-index? int32 {hw:entity-mib}?
369 +--ro path? string
370 +--ro compute-node compute-node-ref {tpm:mtpm}?
371 +--ro manufacturer? string
372 +--rw firmware-version identityref
373 +--rw tpm12-hash-algo? identityref {taa:tpm12}?
374 +--rw tpm12-pcrs* pcr
375 +--rw tpm20-pcr-bank* [tpm20-hash-algo] {taa:tpm20}?
376 | +--rw tpm20-hash-algo identityref
377 | +--rw pcr-index* tpm:pcr
378 +--ro status enumeration
379 +--rw certificates
380 +--rw certificate* [name]
381 +--rw name string
382 +--rw keystore-ref? leafref {ks:asymmetric-keys}?
383 +--rw type? enumeration
385 container 'attester-supported-algos' - Identifies which TCG hash
386 algorithms are available for use on the Attesting platform. An
387 operator will use this information to limit algorithms available for
388 use by RPCs to just a desired set from the universe of all allowed
389 hash algorithms by the TCG.
391 +--rw attester-supported-algos
392 +--rw tpm12-asymmetric-signing* identityref {taa:tpm12}?
393 +--rw tpm12-hash* identityref {taa:tpm12}?
394 +--rw tpm20-asymmetric-signing* identityref {taa:tpm20}?
395 +--rw tpm20-hash* identityref {taa:tpm20}?
397 container 'compute-nodes' - When there is more than one TPM
398 supported, this container maintains the set of information related to
399 the compute node associated with a specific TPM. This allows each
400 specific TPM to identify to which 'compute-node' it belongs.
402 +--rw compute-nodes {tpm:mtpm}?
403 +--ro compute-node* [node-id]
404 +--ro node-id string
405 +--ro node-physical-index? int32 {hw:entity-mib}?
406 +--ro node-name? string
407 +--ro node-location? string
409 2.1.1.6. YANG Module
410 file "ietf-tpm-remote-attestation@2022-05-13.yang"
411 module ietf-tpm-remote-attestation {
412 yang-version 1.1;
413 namespace "urn:ietf:params:xml:ns:yang:ietf-tpm-remote-attestation";
414 prefix tpm;
416 import ietf-yang-types {
417 prefix yang;
418 }
419 import ietf-hardware {
420 prefix hw;
421 }
422 import ietf-keystore {
423 prefix ks;
424 }
425 import ietf-tcg-algs {
426 prefix taa;
427 }
429 organization
430 "IETF RATS (Remote ATtestation procedureS) Working Group";
431 contact
432 "WG Web :
433 WG List :
434 Author : Eric Voit
435 Author : Henk Birkholz
436 Author : Michael Eckel
437 Author : Shwetha Bhandari
438 Author : Bill Sulzen
439 Author : Liang Xia (Frank)
440 Author : Tom Laffey
441 Author : Guy Fedorkow ";
442 description
443 "A YANG module to enable a TPM 1.2 and TPM 2.0 based
444 remote attestation procedure using a challenge-response
445 interaction model and the TPM 1.2 and TPM 2.0 Quote
446 primitive operations.
448 Copyright (c) 2022 IETF Trust and the persons identified
449 as authors of the code. All rights reserved.
450 Redistribution and use in source and binary forms, with or
451 without modification, is permitted pursuant to, and subject to
452 the license terms contained in, the Revised BSD License set
453 forth in Section 4.c of the IETF Trust's Legal Provisions
454 Relating to IETF Documents
455 (https://trustee.ietf.org/license-info).
457 This version of this YANG module is part of RFC XXXX
458 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC
459 itself for full legal notices.
461 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
462 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED',
463 'MAY', and 'OPTIONAL' in this document are to be interpreted as
464 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when,
465 they appear in all capitals, as shown here.";
467 revision 2022-05-13 {
468 description
469 "Initial version";
470 reference
471 "RFC XXXX: A YANG Data Model for Challenge-Response-based Remote
472 Attestation Procedures using TPMs";
473 }
475 /*****************/
476 /* Features */
477 /*****************/
479 feature mtpm {
480 description
481 "The device supports the remote attestation of multiple
482 TPM based cryptoprocessors.";
483 }
485 feature bios {
486 description
487 "The device supports the bios logs.";
488 reference
489 "bios-log:
490 https://trustedcomputinggroup.org/wp-content/uploads/
491 PC-ClientSpecific_Platform_Profile_for_TPM_2p0_Systems_v51.pdf
492 Section 9.4.5.2";
493 }
495 feature ima {
496 description
497 "The device supports Integrity Measurement Architecture logs.
498 Many variants of IMA logs exist in the deployment. Each encodes
499 the log entry contents as the specific measurements which get
500 hashed into a PCRs as Evidence. See the reference below for
501 one example of such an encoding.";
502 reference
503 "ima-log:
504 https://www.trustedcomputinggroup.org/wp-content/uploads/
505 TCG_IWG_CEL_v1_r0p41_pub.pdf Section 5.1.6";
507 }
509 feature netequip_boot {
510 description
511 "The device supports the netequip_boot logs.";
512 reference
513 "netequip-boot-log:
514 RFC XXXX Appendix B";
515 }
517 /*****************/
518 /* Typedefs */
519 /*****************/
521 typedef pcr {
522 type uint8 {
523 range "0..31";
524 }
525 description
526 "Valid index number for a PCR. A {{TPM2.0}} compliant PCR index
527 extends from 0-31. At this time a typical TPM would have no
528 more than 32 PCRS.";
529 }
531 typedef compute-node-ref {
532 type leafref {
533 path "/tpm:rats-support-structures/tpm:compute-nodes"
534 + "/tpm:compute-node/tpm:node-id";
535 }
536 description
537 "This type is used to reference a hardware node. Note that an
538 implementer might include an alternative leafref pointing to a
539 different YANG module node specifying hardware structures.";
540 }
542 typedef certificate-name-ref {
543 type leafref {
544 path "/tpm:rats-support-structures/tpm:tpms/tpm:tpm"
545 + "/tpm:certificates/tpm:certificate/tpm:name";
546 }
547 description
548 "A type which allows identification of a TPM based certificate.";
549 }
551 /******************/
552 /* Identities */
553 /******************/
554 identity attested_event_log_type {
555 description
556 "Base identity allowing categorization of the reasons why an
557 attested measurement has been taken on an Attester.";
558 }
560 identity ima {
561 base attested_event_log_type;
562 description
563 "An event type recorded in IMA.";
564 }
566 identity bios {
567 base attested_event_log_type;
568 description
569 "An event type associated with BIOS/UEFI.";
570 }
572 identity netequip_boot {
573 base attested_event_log_type;
574 description
575 "An event type associated with Network Equipment Boot.";
576 }
578 /*****************/
579 /* Groupings */
580 /*****************/
582 grouping tpm20-hash-algo {
583 description
584 "The cryptographic algorithm used to hash the TPM2 PCRs. This
585 must be from the list of platform supported options.";
586 leaf tpm20-hash-algo {
587 type identityref {
588 base taa:hash;
589 }
590 must '. = /tpm:rats-support-structures'
591 + '/tpm:attester-supported-algos/tpm:tpm20-hash' {
592 error-message "This platform does not support tpm20-hash-algo";
593 }
594 description
595 "The hash scheme that is used to hash a TPM2.0 PCR. This
596 must be one of those supported by a platform.
597 Where this object does not appear, the default value of
598 'taa:TPM_ALG_SHA256' will apply.";
599 }
600 }
601 grouping tpm12-hash-algo {
602 description
603 "The cryptographic algorithm used to hash the TPM1.2 PCRs.";
604 leaf tpm12-hash-algo {
605 type identityref {
606 base taa:hash;
607 }
608 must '. = /tpm:rats-support-structures'
609 + '/tpm:attester-supported-algos/tpm:tpm12-hash' {
610 error-message "This platform does not support tpm12-hash-algo";
611 }
612 description
613 "The hash scheme that is used to hash a TPM1.2 PCR. This
614 MUST be one of those supported by a platform.
615 Where this object does not appear, the default value of
616 'taa:TPM_ALG_SHA1' will apply.";
617 }
618 }
620 grouping nonce {
621 description
622 "A random number intended to guarantee freshness and for use
623 as part of a replay-detection mechanism.";
624 leaf nonce-value {
625 type binary;
626 mandatory true;
627 description
628 "A cryptographically generated random number which should
629 not be predictable prior to its issuance from a random
630 number generation function. The random number MUST be
631 derived from an entropy source external to the Attester.
633 Note that a nonce sent into a TPM will typically be 160 or 256
634 binary digits long. (This is 20 or 32 bytes.) So if fewer
635 binary digits are sent, this nonce object will be padded
636 with leading zeros within Quotes returned from the TPM.
637 Additionally if more bytes are sent, the nonce will be trimmed
638 to the most significant binary digits.";
639 }
640 }
642 grouping tpm12-pcr-selection {
643 description
644 "A Verifier can request one or more PCR values using its
645 individually created Attestation Key Certificate (AC).
646 The corresponding selection filter is represented in this
647 grouping.";
648 leaf-list pcr-index {
649 type pcr;
650 description
651 "The numbers/indexes of the PCRs. In addition, any selection
652 of PCRs MUST verify that the set of PCRs requested are a
653 subset the set of PCRs exposed by in the leaf-list
654 /tpm:rats-support-structures
655 /tpm:tpms/tpm:tpm[name=current()]/tpm:tpm12-pcrs";
656 }
657 }
659 grouping tpm20-pcr-selection {
660 description
661 "A Verifier can acquire one or more PCR values, which are hashed
662 together in a TPM2B_DIGEST coming from the TPM2. The selection
663 list of desired PCRs and the Hash Algorithm is represented in
664 this grouping.";
665 list tpm20-pcr-selection {
666 unique "tpm20-hash-algo";
667 description
668 "Specifies the list of PCRs and Hash Algorithms that can be
669 returned within a TPM2B_DIGEST.";
670 reference
671 "TPM2.0-Structures:
672 https://www.trustedcomputinggroup.org/wp-content/uploads/
673 TPM-Rev-2.0-Part-2-Structures-01.38.pdf Section 10.9.7";
674 uses tpm20-hash-algo;
675 leaf-list pcr-index {
676 type pcr;
677 description
678 "The numbers of the PCRs that which are being tracked
679 with a hash based on the tpm20-hash-algo. In addition,
680 any selection of PCRs MUST verify that the set of PCRs
681 requested are a subset the set of PCR indexes selected
682 are available for that specific TPM.";
683 }
684 }
685 }
687 grouping certificate-name-ref {
688 description
689 "Identifies a certificate in a keystore.";
690 leaf certificate-name {
691 type certificate-name-ref;
692 mandatory true;
693 description
694 "Identifies a certificate in a keystore.";
695 }
696 }
697 grouping tpm-name {
698 description
699 "A unique TPM on a device.";
700 leaf name {
701 type string;
702 description
703 "Unique system generated name for a TPM on a device.";
704 }
705 }
707 grouping node-uptime {
708 description
709 "Uptime in seconds of the node.";
710 leaf up-time {
711 type uint32;
712 description
713 "Uptime in seconds of this node reporting its data";
714 }
715 }
717 grouping tpm12-attestation {
718 description
719 "Contains an instance of TPM1.2 style signed cryptoprocessor
720 measurements. It is supplemented by unsigned Attester
721 information.";
722 uses node-uptime;
723 leaf TPM_QUOTE2 {
724 type binary;
725 description
726 "Result of a TPM1.2 Quote2 operation. This includes PCRs,
727 signatures, locality, the provided nonce and other data which
728 can be further parsed to appraise the Attester.";
729 reference
730 "TPM1.2-Commands:
731 TPM1.2 commands rev116 July 2007, Section 16.5
732 https://trustedcomputinggroup.org/wp-content/uploads
733 /TPM-Main-Part-3-Commands_v1.2_rev116_01032011.pdf";
734 }
735 }
737 grouping tpm20-attestation {
738 description
739 "Contains an instance of TPM2 style signed cryptoprocessor
740 measurements. It is supplemented by unsigned Attester
741 information.";
742 leaf TPMS_QUOTE_INFO {
743 type binary;
744 mandatory true;
745 description
746 "A hash of the latest PCR values (and the hash algorithm used)
747 which have been returned from a Verifier for the selected PCRs
748 and Hash Algorithms.";
749 reference
750 "TPM2.0-Structures:
751 https://www.trustedcomputinggroup.org/wp-content/uploads/
752 TPM-Rev-2.0-Part-2-Structures-01.38.pdf Section 10.12.1";
753 }
754 leaf quote-signature {
755 type binary;
756 description
757 "Quote signature returned by TPM Quote. The signature was
758 generated using the key associated with the
759 certificate 'name'.";
760 reference
761 "TPM2.0-Structures:
762 https://www.trustedcomputinggroup.org/wp-content/uploads/
763 TPM-Rev-2.0-Part-2-Structures-01.38.pdf Section 11.2.1";
764 }
765 uses node-uptime;
766 list unsigned-pcr-values {
767 description
768 "PCR values in each PCR bank. This might appear redundant with
769 the TPM2B_DIGEST, but that digest is calculated across multiple
770 PCRs. Having to verify across multiple PCRs does not
771 necessarily make it easy for a Verifier to appraise just the
772 minimum set of PCR information which has changed since the last
773 received TPM2B_DIGEST. Put another way, why should a Verifier
774 reconstruct the proper value of all PCR Quotes when only a
775 single PCR has changed?
776 To help this happen, if the Attester does know specific PCR
777 values, the Attester can provide these individual values via
778 'unsigned-pcr-values'. By comparing this information to
779 what has previously been validated, it is possible for a
780 Verifier to confirm the Attester's signature while eliminating
782 significant processing. Note that there should never be a
783 result where an unsigned PCR value differs from what may be
784 reconstructed from the within the PCR quote and the event logs.
785 If there is a difference, a signed result which has been
786 verified from retrieved logs is considered definitive.";
787 uses tpm20-hash-algo;
788 list pcr-values {
789 key "pcr-index";
790 description
791 "List of one PCR bank.";
792 leaf pcr-index {
793 type pcr;
794 description
795 "PCR index number.";
796 }
797 leaf pcr-value {
798 type binary;
799 description
800 "PCR value.";
801 reference
802 "TPM2.0-Structures:
803 https://www.trustedcomputinggroup.org/wp-content/uploads/
804 TPM-Rev-2.0-Part-2-Structures-01.38.pdf Section 10.9.7";
805 }
806 }
807 }
808 }
810 grouping log-identifier {
811 description
812 "Identifier for type of log to be retrieved.";
813 leaf log-type {
814 type identityref {
815 base attested_event_log_type;
816 }
817 mandatory true;
818 description
819 "The corresponding measurement log type identity.";
820 }
821 }
823 grouping boot-event-log {
824 description
825 "Defines a specific instance of an event log entry
826 and corresponding to the information used to
827 extend the PCR";
828 leaf event-number {
829 type uint32;
830 description
831 "Unique event number of this event which monotonically
832 increases within a given event log. The maximum event
833 number should not be reached, nor is wrapping back to
834 an earlier number supported.";
835 }
836 leaf event-type {
837 type uint32;
838 description
839 "BIOS Log Event Type:
840 https://trustedcomputinggroup.org/wp-content/uploads/
841 TCG_PCClient_PFP_r1p05_v23_pub.pdf Section 10.4.1";
842 }
843 leaf pcr-index {
844 type pcr;
845 description
846 "Defines the PCR index that this event extended";
847 }
848 list digest-list {
849 description
850 "Hash of event data";
851 leaf hash-algo {
852 type identityref {
853 base taa:hash;
854 }
855 description
856 "The hash scheme that is used to compress the event data in
857 each of the leaf-list digest items.";
858 }
859 leaf-list digest {
860 type binary;
861 description
862 "The hash of the event data using the algorithm of the
863 'hash-algo' against 'event data'.";
864 }
865 }
866 leaf event-size {
867 type uint32;
868 description
869 "Size of the event data";
870 }
871 leaf-list event-data {
872 type binary;
873 description
874 "The event data. This is a binary structure
875 of size 'event-size'. For more on what
876 might be recorded within this object
877 see [bios-log] Section 9 which details
878 viable events which might be recorded.";
879 }
880 }
882 grouping bios-event-log {
883 description
884 "Measurement log created by the BIOS/UEFI.";
885 list bios-event-entry {
886 key "event-number";
887 description
888 "Ordered list of TCG described event log
889 that extended the PCRs in the order they
890 were logged";
891 uses boot-event-log;
892 }
893 }
895 grouping ima-event {
896 description
897 "Defines a hash log extend event for IMA measurements";
898 reference
899 "ima-log:
900 https://www.trustedcomputinggroup.org/wp-content/uploads/
901 TCG_IWG_CEL_v1_r0p41_pub.pdf Section 4.3";
902 leaf event-number {
903 type uint64;
904 description
905 "Unique event number of this event which monotonically
906 increases. The maximum event number should not be
907 reached, nor is wrapping back to an earlier number
908 supported.";
909 }
910 leaf ima-template {
911 type string;
912 description
913 "Name of the template used for event logs
914 for e.g. ima, ima-ng, ima-sig";
915 }
916 leaf filename-hint {
917 type string;
918 description
919 "File name (including the path) that was measured.";
920 }
921 leaf filedata-hash {
922 type binary;
923 description
924 "Hash of filedata as updated based upon the
925 filedata-hash-algorithm";
926 }
927 leaf filedata-hash-algorithm {
928 type string;
929 description
930 "Algorithm used for filedata-hash";
931 }
932 leaf template-hash-algorithm {
933 type string;
934 description
935 "Algorithm used for template-hash";
936 }
937 leaf template-hash {
938 type binary;
939 description
940 "hash(filedata-hash, filename-hint)";
941 }
942 leaf pcr-index {
943 type pcr;
944 description
945 "Defines the PCR index that this event extended";
946 }
947 leaf signature {
948 type binary;
949 description
950 "Digital file signature which provides a
951 fingerprint for the file being measured.";
952 }
953 }
955 grouping ima-event-log {
956 description
957 "Measurement log created by IMA.";
958 list ima-event-entry {
959 key "event-number";
960 description
961 "Ordered list of ima event logs by event-number";
962 uses ima-event;
963 }
964 }
966 grouping network-equipment-boot-event-log {
967 description
968 "Measurement log created by Network Equipment Boot. The Network
969 Equipment Boot format is identical to the IMA format. In
970 contrast to the IMA log, the Network Equipment Boot log
971 includes every measurable event from an Attester, including
972 the boot stages of BIOS, Bootloader, etc. In essence, the scope
973 of events represented in this format combines the scope of BIOS
974 events and IMA events.";
975 list boot-event-entry {
976 key "event-number";
977 description
978 "Ordered list of Network Equipment Boot event logs
979 by event-number, using the IMA event format.";
980 uses ima-event;
981 }
982 }
984 grouping event-logs {
985 description
986 "A selector for the log and its type.";
987 choice attested_event_log_type {
988 mandatory true;
989 description
990 "Event log type determines the event logs content.";
991 case bios {
992 if-feature "bios";
993 description
994 "BIOS/UEFI event logs";
995 container bios-event-logs {
996 description
997 "BIOS/UEFI event logs";
998 uses bios-event-log;
999 }
1000 }
1001 case ima {
1002 if-feature "ima";
1003 description
1004 "IMA event logs.";
1005 container ima-event-logs {
1006 description
1007 "IMA event logs.";
1008 uses ima-event-log;
1009 }
1010 }
1011 case netequip_boot {
1012 if-feature "netequip_boot";
1013 description
1014 "Network Equipment Boot event logs";
1015 container boot-event-logs {
1016 description
1017 "Network equipment boot event logs.";
1018 uses network-equipment-boot-event-log;
1019 }
1020 }
1021 }
1022 }
1024 /**********************/
1025 /* RPC operations */
1026 /**********************/
1028 rpc tpm12-challenge-response-attestation {
1029 if-feature "taa:tpm12";
1030 description
1031 "This RPC accepts the input for TSS TPM 1.2 commands made to the
1032 attesting device.";
1034 input {
1035 container tpm12-attestation-challenge {
1036 description
1037 "This container includes every information element defined
1038 in the reference challenge-response interaction model for
1039 remote attestation. Corresponding values are based on
1040 TPM 1.2 structure definitions";
1041 uses tpm12-pcr-selection;
1042 uses nonce;
1043 leaf-list certificate-name {
1044 if-feature "tpm:mtpm";
1045 type certificate-name-ref;
1046 must "/tpm:rats-support-structures/tpm:tpms"
1047 + "/tpm:tpm[tpm:firmware-version='taa:tpm12']"
1048 + "/tpm:certificates/"
1049 + "/tpm:certificate[name=current()]" {
1050 error-message "Not an available TPM1.2 AIK certificate.";
1051 }
1052 description
1053 "When populated, the RPC will only get a Quote for the
1054 TPMs associated with these certificate(s).";
1055 }
1056 }
1057 }
1058 output {
1059 list tpm12-attestation-response {
1060 unique "certificate-name";
1061 description
1062 "The binary output of TPM 1.2 TPM_Quote/TPM_Quote2, including
1063 the PCR selection and other associated attestation evidence
1064 metadata";
1065 uses certificate-name-ref {
1066 description
1067 "Certificate associated with this tpm12-attestation.";
1068 }
1069 uses tpm12-attestation;
1070 }
1071 }
1072 }
1074 rpc tpm20-challenge-response-attestation {
1075 if-feature "taa:tpm20";
1076 description
1077 "This RPC accepts the input for TSS TPM 2.0 commands of the
1078 managed device. ComponentIndex from the hardware manager YANG
1079 module is used to refer to dedicated TPM in composite devices,
1080 e.g. smart NICs, is not covered.";
1081 input {
1082 container tpm20-attestation-challenge {
1083 description
1084 "This container includes every information element defined
1085 in the reference challenge-response interaction model for
1086 remote attestation. Corresponding values are based on
1087 TPM 2.0 structure definitions";
1088 uses nonce;
1089 uses tpm20-pcr-selection;
1090 leaf-list certificate-name {
1091 if-feature "tpm:mtpm";
1092 type certificate-name-ref;
1093 must "/tpm:rats-support-structures/tpm:tpms"
1094 + "/tpm:tpm[tpm:firmware-version='taa:tpm20']"
1095 + "/tpm:certificates/"
1096 + "/tpm:certificate[name=current()]" {
1097 error-message "Not an available TPM2.0 AIK certificate.";
1098 }
1099 description
1100 "When populated, the RPC will only get a Quote for the
1101 TPMs associated with the certificates.";
1102 }
1103 }
1104 }
1105 output {
1106 list tpm20-attestation-response {
1107 unique "certificate-name";
1108 description
1109 "The binary output of TPM2b_Quote from one TPM of the
1110 node which identified by node-id. An TPMS_ATTEST structure
1111 including a length, encapsulated in a signature";
1112 uses certificate-name-ref {
1113 description
1114 "Certificate associated with this tpm20-attestation.";
1115 }
1116 uses tpm20-attestation;
1117 }
1118 }
1119 }
1121 rpc log-retrieval {
1122 description
1123 "Logs Entries are either identified via indices or via providing
1124 the last line received. The number of lines returned can be
1125 limited. The type of log is a choice that can be augmented.";
1126 input {
1127 uses log-identifier;
1128 list log-selector {
1129 description
1130 "Only log entries which meet all the selection criteria
1131 provided are to be returned by the RPC output.";
1132 leaf-list name {
1133 type string;
1134 description
1135 "Name of one or more unique TPMs on a device. If this
1136 object exists, a selection should pull only the objects
1137 related to these TPM(s). If it does not exist, all
1138 qualifying TPMs that are 'hardware-based' equals true
1139 on the device are selected. When this selection
1140 criteria is provided, it will be considered as a logical
1141 AND with any other selection criteria provided.";
1142 }
1143 choice index-type {
1144 description
1145 "Last log entry received, log index number, or timestamp.";
1146 case last-entry {
1147 description
1148 "The last entry of the log already retrieved.";
1149 leaf last-entry-value {
1150 type binary;
1151 description
1152 "Content of a log event which matches 1:1 with a
1153 unique event record contained within the log. Log
1154 entries after this will be passed to the
1155 requester. Note: if log entry values are not unique,
1156 this MUST return an error.";
1157 }
1158 }
1159 case index {
1160 description
1161 "Numeric index of the last log entry retrieved, or
1162 zero.";
1163 leaf last-index-number {
1164 type uint64;
1165 description
1166 "The last numeric index number of a log entry.
1167 Zero means to start at the beginning of the log.
1168 Entries after this will be passed to the
1169 requester.";
1170 }
1171 }
1172 case timestamp {
1173 leaf timestamp {
1174 type yang:date-and-time;
1175 description
1176 "Timestamp from which to start the extraction. The
1177 next log entry after this timestamp is to
1178 be sent.";
1179 }
1180 description
1181 "Timestamp from which to start the extraction.";
1182 }
1183 }
1184 leaf log-entry-quantity {
1185 type uint16;
1186 description
1187 "The number of log entries to be returned. If omitted, it
1188 means all of them.";
1189 }
1190 }
1191 }
1192 output {
1193 container system-event-logs {
1194 description
1195 "The requested data of the measurement event logs";
1196 list node-data {
1197 unique "name";
1198 description
1199 "Event logs of a node in a distributed system
1200 identified by the node name";
1201 uses tpm-name;
1202 uses node-uptime;
1203 container log-result {
1204 description
1205 "The requested entries of the corresponding log.";
1206 uses event-logs;
1207 }
1208 }
1209 }
1210 }
1211 }
1213 /**************************************/
1214 /* Config & Oper accessible nodes */
1215 /**************************************/
1217 container rats-support-structures {
1218 description
1219 "The datastore definition enabling verifiers or relying
1220 parties to discover the information necessary to use the
1221 remote attestation RPCs appropriately.";
1222 container compute-nodes {
1223 if-feature "tpm:mtpm";
1224 description
1225 "Holds the set of device subsystems/components in this
1226 composite device that support TPM operations.";
1227 list compute-node {
1228 key "node-id";
1229 unique "node-name";
1230 config false;
1231 min-elements 2;
1232 description
1233 "A component within this composite device which
1234 supports TPM operations.";
1235 leaf node-id {
1236 type string;
1237 description
1238 "ID of the compute node, such as Board Serial Number.";
1239 }
1240 leaf node-physical-index {
1241 if-feature "hw:entity-mib";
1242 type int32 {
1243 range "1..2147483647";
1244 }
1245 config false;
1246 description
1247 "The entPhysicalIndex for the compute node.";
1248 reference
1249 "RFC 6933: Entity MIB (Version 4) - entPhysicalIndex";
1250 }
1251 leaf node-name {
1252 type string;
1253 description
1254 "Name of the compute node.";
1255 }
1256 leaf node-location {
1257 type string;
1258 description
1259 "Location of the compute node, such as slot number.";
1260 }
1261 }
1262 }
1263 container tpms {
1264 description
1265 "Holds the set of TPMs within an Attester.";
1266 list tpm {
1267 key "name";
1268 unique "path";
1269 description
1270 "A list of TPMs in this composite device that RATS
1271 can be conducted with.";
1272 uses tpm-name;
1273 leaf hardware-based {
1274 type boolean;
1275 config false;
1276 mandatory true;
1277 description
1278 "System generated indication of whether this is a
1279 hardware based TPM.";
1280 }
1281 leaf physical-index {
1282 if-feature "hw:entity-mib";
1283 type int32 {
1284 range "1..2147483647";
1285 }
1286 config false;
1287 description
1288 "The entPhysicalIndex for the TPM.";
1289 reference
1290 "RFC 6933: Entity MIB (Version 4) - entPhysicalIndex";
1291 }
1292 leaf path {
1293 type string;
1294 config false;
1295 description
1296 "Device path to a unique TPM on a device. This can change
1297 across reboots.";
1298 }
1299 leaf compute-node {
1300 if-feature "tpm:mtpm";
1301 type compute-node-ref;
1302 config false;
1303 mandatory true;
1304 description
1305 "Indicates the compute node measured by this TPM.";
1306 }
1307 leaf manufacturer {
1308 type string;
1309 config false;
1310 description
1311 "TPM manufacturer name.";
1312 }
1313 leaf firmware-version {
1314 type identityref {
1315 base taa:cryptoprocessor;
1316 }
1317 mandatory true;
1318 description
1319 "Identifies the cryptoprocessor API set supported. This
1320 is automatically configured by the device and should not
1321 be changed.";
1323 }
1324 uses tpm12-hash-algo {
1325 if-feature "taa:tpm12";
1326 when "derived-from-or-self(firmware-version, 'taa:tpm12')";
1327 refine "tpm12-hash-algo" {
1328 description
1329 "The hash algorithm overwrites the default used for PCRs
1330 on this TPM1.2 compliant cryptoprocessor.";
1331 }
1332 }
1333 leaf-list tpm12-pcrs {
1334 if-feature "taa:tpm12";
1335 when
1336 "derived-from-or-self(../firmware-version, 'taa:tpm12')";
1337 type pcr;
1338 description
1339 "The PCRs which may be extracted from this TPM1.2
1340 compliant cryptoprocessor.";
1341 }
1342 list tpm20-pcr-bank {
1343 if-feature "taa:tpm20";
1344 when
1345 "derived-from-or-self(../firmware-version, 'taa:tpm20')";
1346 key "tpm20-hash-algo";
1347 description
1348 "Specifies the list of PCRs that may be extracted for
1349 a specific Hash Algorithm on this TPM2 compliant
1350 cryptoprocessor. A bank is a set of PCRs which are
1351 extended using a particular hash algorithm.";
1352 reference
1353 "TPM2.0-Structures:
1354 https://www.trustedcomputinggroup.org/wp-content/uploads/
1355 TPM-Rev-2.0-Part-2-Structures-01.38.pdf Section 10.9.7";
1356 leaf tpm20-hash-algo {
1357 type identityref {
1358 base taa:hash;
1359 }
1360 must '/tpm:rats-support-structures'
1361 + '/tpm:attester-supported-algos'
1362 + '/tpm:tpm20-hash' {
1363 error-message "This platform does not support tpm20-hash-algo";
1364 }
1365 description
1366 "The hash scheme actively being used to hash a
1367 one or more TPM2.0 PCRs.";
1368 }
1369 leaf-list pcr-index {
1370 type tpm:pcr;
1371 description
1372 "Defines what TPM2 PCRs are available to be extracted.";
1373 }
1374 }
1375 leaf status {
1376 type enumeration {
1377 enum operational {
1378 value 0;
1379 description
1380 "The TPM currently is running normally and
1381 is ready to accept and process TPM quotes.";
1382 reference
1383 "TPM2.0-Arch:
1384 https://trustedcomputinggroup.org/wp-content/uploads/
1385 TCG_TPM2_r1p59_Part1_Architecture_pub.pdf
1386 Section 12";
1387 }
1388 enum non-operational {
1389 value 1;
1390 description
1391 "TPM is in a state such as startup or shutdown which
1392 precludes the processing of TPM quotes.";
1393 }
1394 }
1395 config false;
1396 mandatory true;
1397 description
1398 "TPM chip self-test status.";
1399 }
1400 container certificates {
1401 description
1402 "The TPM's certificates, including EK certificates
1403 and Attestation Key certificates.";
1404 list certificate {
1405 key "name";
1406 description
1407 "Three types of certificates can be accessed via
1408 this statement, including Initial Attestation
1409 Key Certificate, Local Attestation Key Certificate or
1410 Endorsement Key Certificate.";
1411 leaf name {
1412 type string;
1413 description
1414 "An arbitrary name uniquely identifying a certificate
1415 associated within key within a TPM.";
1416 }
1417 leaf keystore-ref {
1418 if-feature "ks:asymmetric-keys";
1419 type leafref {
1420 path "/ks:keystore/ks:asymmetric-keys/ks:asymmetric-key"
1421 + "/ks:name";
1422 }
1423 description
1424 "A reference to a specific certificate of an
1425 asymmetric key in the Keystore.";
1426 }
1427 leaf type {
1428 type enumeration {
1429 enum endorsement-certificate {
1430 value 0;
1431 description
1432 "Endorsement Key (EK) Certificate type.";
1433 reference
1434 "TPM2.0-Key:
1435 https://trustedcomputinggroup.org/wp-content/
1436 uploads/TPM-2p0-Keys-for-Device-Identity-
1437 and-Attestation_v1_r12_pub10082021.pdf
1438 Section 3.11";
1439 }
1440 enum initial-attestation-certificate {
1441 value 1;
1442 description
1443 "Initial Attestation key (IAK) Certificate type.";
1444 reference
1445 "TPM2.0-Key:
1446 https://trustedcomputinggroup.org/wp-content/
1447 uploads/TPM-2p0-Keys-for-Device-Identity-
1448 and-Attestation_v1_r12_pub10082021.pdf
1449 Section 3.2";
1450 }
1451 enum local-attestation-certificate {
1452 value 2;
1453 description
1454 "Local Attestation Key (LAK) Certificate type.";
1455 reference
1456 "TPM2.0-Key:
1457 https://trustedcomputinggroup.org/wp-content/
1458 uploads/TPM-2p0-Keys-for-Device-Identity-
1459 and-Attestation_v1_r12_pub10082021.pdf
1460 Section 3.2";
1461 }
1462 }
1463 description
1464 "Function supported by this certificate from within the
1465 TPM.";
1466 }
1468 }
1469 }
1470 }
1471 }
1472 container attester-supported-algos {
1473 description
1474 "Identifies which TPM algorithms are available for use on an
1475 attesting platform.";
1476 leaf-list tpm12-asymmetric-signing {
1477 if-feature "taa:tpm12";
1478 when "../../tpm:tpms"
1479 + "/tpm:tpm[tpm:firmware-version='taa:tpm12']";
1480 type identityref {
1481 base taa:asymmetric;
1482 }
1483 description
1484 "Platform Supported TPM12 asymmetric algorithms.";
1485 }
1486 leaf-list tpm12-hash {
1487 if-feature "taa:tpm12";
1488 when "../../tpm:tpms"
1489 + "/tpm:tpm[tpm:firmware-version='taa:tpm12']";
1490 type identityref {
1491 base taa:hash;
1492 }
1493 description
1494 "Platform supported TPM12 hash algorithms.";
1495 }
1496 leaf-list tpm20-asymmetric-signing {
1497 if-feature "taa:tpm20";
1498 when "../../tpm:tpms"
1499 + "/tpm:tpm[tpm:firmware-version='taa:tpm20']";
1500 type identityref {
1501 base taa:asymmetric;
1502 }
1503 description
1504 "Platform Supported TPM20 asymmetric algorithms.";
1505 }
1506 leaf-list tpm20-hash {
1507 if-feature "taa:tpm20";
1508 when "../../tpm:tpms"
1509 + "/tpm:tpm[tpm:firmware-version='taa:tpm20']";
1510 type identityref {
1511 base taa:hash;
1512 }
1513 description
1514 "Platform supported TPM20 hash algorithms.";
1515 }
1517 }
1518 }
1519 }
1520
1522 Figure 1
1524 2.1.2. 'ietf-tcg-algs'
1526 This document has encoded the TCG Algorithm definitions of
1527 [TCG-Algos], revision 1.32. By including this full table as a
1528 separate YANG file within this document, it is possible for other
1529 YANG models to leverage the contents of this model. Specific
1530 references to [RFC2104], [RFC8017], [ISO-IEC-9797-1],
1531 [ISO-IEC-9797-2], [ISO-IEC-10116], [ISO-IEC-10118-3],
1532 [ISO-IEC-14888-3], [ISO-IEC-15946-1], [ISO-IEC-18033-3],
1533 [IEEE-Std-1363-2000], [IEEE-Std-1363a-2004], [NIST-PUB-FIPS-202],
1534 [NIST-SP800-38C], [NIST-SP800-38D], [NIST-SP800-38F],
1535 [NIST-SP800-56A], [NIST-SP800-108], [bios-log], as well as Appendix A
1536 and Appendix B exist within the YANG Model.
1538 2.1.2.1. Features
1540 There are two types of features supported: 'TPM12' and 'TPM20'.
1541 Support for either of these features indicates that a cryptoprocessor
1542 supporting the corresponding type of TCG TPM API is present on an
1543 Attester. Most commonly, only one type of cryptoprocessor will be
1544 available on an Attester.
1546 2.1.2.2. Identities
1548 There are three types of identities in this model:
1550 1. Cryptographic functions supported by a TPM algorithm; these
1551 include: 'asymmetric', 'symmetric', 'hash', 'signing',
1552 'anonymous_signing', 'encryption_mode', 'method', and
1553 'object_type'. The definitions of each of these are in Table 2
1554 of [TCG-Algos].
1556 2. API specifications for TPM types: 'tpm12' and 'tpm20'
1558 3. Specific algorithm types: Each algorithm type defines what
1559 cryptographic functions may be supported, and on which type of
1560 API specification. It is not required that an implementation of
1561 a specific TPM will support all algorithm types. The contents of
1562 each specific algorithm mirrors what is in Table 3 of
1563 [TCG-Algos].
1565 2.1.2.3. YANG Module
1567 file "ietf-tcg-algs@2022-03-23.yang"
1568 module ietf-tcg-algs {
1569 yang-version 1.1;
1570 namespace "urn:ietf:params:xml:ns:yang:ietf-tcg-algs";
1571 prefix taa;
1573 organization
1574 "IETF RATS (Remote ATtestation procedureS) Working Group";
1575 contact
1576 "WG Web:
1577 WG List:
1578 Author: Eric Voit ";
1579 description
1580 "This module defines identities for asymmetric algorithms.
1582 Copyright (c) 2022 IETF Trust and the persons identified as
1583 authors of the code. All rights reserved.
1584 Redistribution and use in source and binary forms, with
1585 or without modification, is permitted pursuant to, and
1586 subject to the license terms contained in, the Revised
1587 BSD License set forth in Section 4.c of the IETF Trust's
1588 Legal Provisions Relating to IETF Documents
1589 (https://trustee.ietf.org/license-info).
1591 This version of this YANG module is part of RFC XXXX
1592 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC itself
1593 for full legal notices.
1595 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL',
1596 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED',
1597 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document
1598 are to be interpreted as described in BCP 14 (RFC 2119)
1599 (RFC 8174) when, and only when, they appear in all
1600 capitals, as shown here.";
1602 revision 2022-03-23 {
1603 description
1604 "Initial version";
1605 reference
1606 "RFC XXXX: A YANG Data Model for Challenge-Response-based Remote
1607 Attestation Procedures using TPMs";
1608 }
1610 /*****************/
1611 /* Features */
1612 /*****************/
1613 feature tpm12 {
1614 description
1615 "This feature indicates algorithm support for the TPM 1.2 API
1616 as per Section 4.8 of TPM1.2-Structures:
1617 TPM Main Part 2 TPM Structures
1618 https://trustedcomputinggroup.org/wp-content/uploads/TPM-
1619 Main-Part-2-TPM-Structures_v1.2_rev116_01032011.pdf";
1620 }
1622 feature tpm20 {
1623 description
1624 "This feature indicates algorithm support for the TPM 2.0 API
1625 as per Section 11.4 of Trusted Platform Module Library
1626 Part 1: Architecture. See TPM2.0-Arch:
1627 https://trustedcomputinggroup.org/wp-content/uploads/
1628 TCG_TPM2_r1p59_Part1_Architecture_pub.pdf";
1629 }
1631 /*****************/
1632 /* Identities */
1633 /*****************/
1635 identity asymmetric {
1636 description
1637 "A TCG recognized asymmetric algorithm with a public and
1638 private key.";
1639 reference
1640 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 2,
1641 https://trustedcomputinggroup.org/resource/
1642 tcg-algorithm-registry/TCG-_Algorithm_Registry_r1p32_pub";
1643 }
1645 identity symmetric {
1646 description
1647 "A TCG recognized symmetric algorithm with only a private key.";
1648 reference
1649 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 2";
1650 }
1652 identity hash {
1653 description
1654 "A TCG recognized hash algorithm that compresses input data to
1655 a digest value or indicates a method that uses a hash.";
1656 reference
1657 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 2";
1658 }
1660 identity signing {
1661 description
1662 "A TCG recognized signing algorithm";
1663 reference
1664 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 2";
1665 }
1667 identity anonymous_signing {
1668 description
1669 "A TCG recognized anonymous signing algorithm.";
1670 reference
1671 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 2";
1672 }
1674 identity encryption_mode {
1675 description
1676 "A TCG recognized encryption mode.";
1677 reference
1678 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 2";
1679 }
1681 identity method {
1682 description
1683 "A TCG recognized method such as a mask generation function.";
1684 reference
1685 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 2";
1686 }
1688 identity object_type {
1689 description
1690 "A TCG recognized object type.";
1691 reference
1692 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 2";
1693 }
1695 identity cryptoprocessor {
1696 description
1697 "Base identity identifying a crytoprocessor.";
1698 }
1700 identity tpm12 {
1701 if-feature "tpm12";
1702 base cryptoprocessor;
1703 description
1704 "Supportable by a TPM1.2.";
1705 reference
1706 "TPM1.2-Structures:
1707 https://trustedcomputinggroup.org/wp-content/uploads/
1708 TPM-Main-Part-2-TPM-Structures_v1.2_rev116_01032011.pdf
1709 TPM_ALGORITHM_ID values, Section 4.8";
1710 }
1712 identity tpm20 {
1713 if-feature "tpm20";
1714 base cryptoprocessor;
1715 description
1716 "Supportable by a TPM2.";
1717 reference
1718 "TPM2.0-Structures:
1719 https://trustedcomputinggroup.org/wp-content/uploads/
1720 TPM-Rev-2.0-Part-2-Structures-01.38.pdf";
1721 }
1723 identity TPM_ALG_RSA {
1724 if-feature "tpm12 or tpm20";
1725 base tpm12;
1726 base tpm20;
1727 base asymmetric;
1728 base object_type;
1729 description
1730 "RSA algorithm";
1731 reference
1732 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
1733 RFC 8017. ALG_ID: 0x0001";
1734 }
1736 identity TPM_ALG_TDES {
1737 if-feature "tpm12";
1738 base tpm12;
1739 base symmetric;
1740 description
1741 "Block cipher with various key sizes (Triple Data Encryption
1742 Algorithm, commonly called Triple Data Encryption Standard)
1743 Note: was banned in TPM1.2 v94";
1744 reference
1745 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
1746 ISO/IEC 18033-3. ALG_ID: 0x0003";
1747 }
1749 identity TPM_ALG_SHA1 {
1750 if-feature "tpm12 or tpm20";
1751 base hash;
1752 base tpm12;
1753 base tpm20;
1754 description
1755 "SHA1 algorithm - Deprecated due to insufficient cryptographic
1756 protection. However, it is still useful for hash algorithms
1757 where protection is not required.";
1758 reference
1759 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
1760 ISO/IEC 10118-3. ALG_ID: 0x0004";
1761 }
1763 identity TPM_ALG_HMAC {
1764 if-feature "tpm12 or tpm20";
1765 base tpm12;
1766 base tpm20;
1767 base hash;
1768 base signing;
1769 description
1770 "Hash Message Authentication Code (HMAC) algorithm";
1771 reference
1772 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3,
1773 ISO/IEC 9797-2 and RFC2104. ALG_ID: 0x0005";
1774 }
1776 identity TPM_ALG_AES {
1777 if-feature "tpm12";
1778 base tpm12;
1779 base symmetric;
1780 description
1781 "The AES algorithm with various key sizes";
1782 reference
1783 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3,
1784 ISO/IEC 18033-3. ALG_ID: 0x0006";
1785 }
1787 identity TPM_ALG_MGF1 {
1788 if-feature "tpm20";
1789 base tpm20;
1790 base hash;
1791 base method;
1792 description
1793 "hash-based mask-generation function";
1794 reference
1795 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3,
1796 IEEE Std 1363-2000 and IEEE Std 1363a-2004.
1797 ALG_ID: 0x0007";
1798 }
1800 identity TPM_ALG_KEYEDHASH {
1801 if-feature "tpm20";
1802 base tpm20;
1803 base hash;
1804 base object_type;
1805 description
1806 "An encryption or signing algorithm using a keyed hash. These
1807 may use XOR for encryption or an HMAC for signing and may
1808 also refer to a data object that is neither signing nor
1809 encrypting.";
1810 reference
1811 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3,
1812 ALG_ID: 0x0008";
1813 }
1815 identity TPM_ALG_XOR {
1816 if-feature "tpm12 or tpm20";
1817 base tpm12;
1818 base tpm20;
1819 base hash;
1820 base symmetric;
1821 description
1822 "The XOR encryption algorithm.";
1823 reference
1824 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3.
1825 ALG_ID: 0x000A";
1826 }
1828 identity TPM_ALG_SHA256 {
1829 if-feature "tpm20";
1830 base tpm20;
1831 base hash;
1832 description
1833 "The SHA 256 algorithm";
1834 reference
1835 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
1836 ISO/IEC 10118-3. ALG_ID: 0x000B";
1837 }
1839 identity TPM_ALG_SHA384 {
1840 if-feature "tpm20";
1841 base tpm20;
1842 base hash;
1843 description
1844 "The SHA 384 algorithm";
1845 reference
1846 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
1847 ISO/IEC 10118-3. ALG_ID: 0x000C";
1848 }
1850 identity TPM_ALG_SHA512 {
1851 if-feature "tpm20";
1852 base tpm20;
1853 base hash;
1854 description
1855 "The SHA 512 algorithm";
1856 reference
1857 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
1858 ISO/IEC 10118-3. ALG_ID: 0x000D";
1859 }
1861 identity TPM_ALG_NULL {
1862 if-feature "tpm20";
1863 base tpm20;
1864 description
1865 "NULL algorithm";
1866 reference
1867 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3.
1868 ALG_ID: 0x0010";
1869 }
1871 identity TPM_ALG_SM3_256 {
1872 if-feature "tpm20";
1873 base tpm20;
1874 base hash;
1875 description
1876 "The SM3 hash algorithm.";
1877 reference
1878 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
1879 ISO/IEC 10118-3:2018. ALG_ID: 0x0012";
1880 }
1882 identity TPM_ALG_SM4 {
1883 if-feature "tpm20";
1884 base tpm20;
1885 base symmetric;
1886 description
1887 "SM4 symmetric block cipher";
1888 reference
1889 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3.
1890 ALG_ID: 0x0013";
1891 }
1893 identity TPM_ALG_RSASSA {
1894 if-feature "tpm20";
1895 base tpm20;
1896 base asymmetric;
1897 base signing;
1898 description
1899 "RFC 8017 Signature algorithm defined in section 8.2
1900 (RSASSAPKCS1-v1_5)";
1902 reference
1903 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
1904 RFC 8017. ALG_ID: 0x0014";
1905 }
1907 identity TPM_ALG_RSAES {
1908 if-feature "tpm20";
1909 base tpm20;
1910 base asymmetric;
1911 base encryption_mode;
1912 description
1913 "RFC 8017 Signature algorithm defined in section 7.2
1914 (RSAES-PKCS1-v1_5)";
1915 reference
1916 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
1917 RFC 8017. ALG_ID: 0x0015";
1918 }
1920 identity TPM_ALG_RSAPSS {
1921 if-feature "tpm20";
1922 base tpm20;
1923 base asymmetric;
1924 base signing;
1925 description
1926 "Padding algorithm defined in section 8.1 (RSASSA PSS)";
1927 reference
1928 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
1929 RFC 8017. ALG_ID: 0x0016";
1930 }
1932 identity TPM_ALG_OAEP {
1933 if-feature "tpm20";
1934 base tpm20;
1935 base asymmetric;
1936 base encryption_mode;
1937 description
1938 "Padding algorithm defined in section 7.1 (RSASSA OAEP)";
1939 reference
1940 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
1941 RFC 8017. ALG_ID: 0x0017";
1942 }
1944 identity TPM_ALG_ECDSA {
1945 if-feature "tpm20";
1946 base tpm20;
1947 base asymmetric;
1948 base signing;
1949 description
1950 "Signature algorithm using elliptic curve cryptography (ECC)";
1951 reference
1952 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
1953 ISO/IEC 14888-3. ALG_ID: 0x0018";
1954 }
1956 identity TPM_ALG_ECDH {
1957 if-feature "tpm20";
1958 base tpm20;
1959 base asymmetric;
1960 base method;
1961 description
1962 "Secret sharing using ECC";
1963 reference
1964 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
1965 NIST SP800-56A. ALG_ID: 0x0019";
1966 }
1968 identity TPM_ALG_ECDAA {
1969 if-feature "tpm20";
1970 base tpm20;
1971 base asymmetric;
1972 base signing;
1973 base anonymous_signing;
1974 description
1975 "Elliptic-curve based anonymous signing scheme";
1976 reference
1977 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
1978 TCG TPM 2.0 library specification. ALG_ID: 0x001A";
1979 }
1981 identity TPM_ALG_SM2 {
1982 if-feature "tpm20";
1983 base tpm20;
1984 base asymmetric;
1985 base signing;
1986 base encryption_mode;
1987 base method;
1988 description
1989 "SM2 - depending on context, either an elliptic-curve based,
1990 signature algorithm, an encryption scheme, or a key exchange
1991 protocol";
1992 reference
1993 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3.
1994 ALG_ID: 0x001B";
1995 }
1997 identity TPM_ALG_ECSCHNORR {
1998 if-feature "tpm20";
1999 base tpm20;
2000 base asymmetric;
2001 base signing;
2002 description
2003 "Elliptic-curve based Schnorr signature";
2004 reference
2005 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3.
2006 ALG_ID: 0x001C";
2007 }
2009 identity TPM_ALG_ECMQV {
2010 if-feature "tpm20";
2011 base tpm20;
2012 base asymmetric;
2013 base method;
2014 description
2015 "Two-phase elliptic-curve key";
2016 reference
2017 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2018 NIST SP800-56A. ALG_ID: 0x001D";
2019 }
2021 identity TPM_ALG_KDF1_SP800_56A {
2022 if-feature "tpm20";
2023 base tpm20;
2024 base hash;
2025 base method;
2026 description
2027 "Concatenation key derivation function";
2028 reference
2029 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2030 NIST SP800-56A (approved alternative1) section 5.8.1.
2031 ALG_ID: 0x0020";
2032 }
2034 identity TPM_ALG_KDF2 {
2035 if-feature "tpm20";
2036 base tpm20;
2037 base hash;
2038 base method;
2039 description
2040 "Key derivation function";
2041 reference
2042 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2043 IEEE 1363a-2004 KDF2 section 13.2. ALG_ID: 0x0021";
2044 }
2045 identity TPM_ALG_KDF1_SP800_108 {
2046 base TPM_ALG_KDF2;
2047 description
2048 "A key derivation method";
2049 reference
2050 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2051 NIST SP800-108 - Section 5.1 KDF. ALG_ID: 0x0022";
2052 }
2054 identity TPM_ALG_ECC {
2055 if-feature "tpm20";
2056 base tpm20;
2057 base asymmetric;
2058 base object_type;
2059 description
2060 "Prime field ECC";
2061 reference
2062 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2063 ISO/IEC 15946-1. ALG_ID: 0x0023";
2064 }
2066 identity TPM_ALG_SYMCIPHER {
2067 if-feature "tpm20";
2068 base tpm20;
2069 base symmetric;
2070 base object_type;
2071 description
2072 "Object type for a symmetric block cipher";
2073 reference
2074 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2075 TCG TPM 2.0 library specification. ALG_ID: 0x0025";
2076 }
2078 identity TPM_ALG_CAMELLIA {
2079 if-feature "tpm20";
2080 base tpm20;
2081 base symmetric;
2082 description
2083 "The Camellia algorithm";
2084 reference
2085 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2086 ISO/IEC 18033-3. ALG_ID: 0x0026";
2087 }
2089 identity TPM_ALG_SHA3_256 {
2090 if-feature "tpm20";
2091 base tpm20;
2092 base hash;
2093 description
2094 "ISO/IEC 10118-3 - the SHA 256 algorithm";
2095 reference
2096 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2097 NIST PUB FIPS 202. ALG_ID: 0x0027";
2098 }
2100 identity TPM_ALG_SHA3_384 {
2101 if-feature "tpm20";
2102 base tpm20;
2103 base hash;
2104 description
2105 "The SHA 384 algorithm";
2106 reference
2107 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2108 NIST PUB FIPS 202. ALG_ID: 0x0028";
2109 }
2111 identity TPM_ALG_SHA3_512 {
2112 if-feature "tpm20";
2113 base tpm20;
2114 base hash;
2115 description
2116 "The SHA 512 algorithm";
2117 reference
2118 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2119 NIST PUB FIPS 202. ALG_ID: 0x0029";
2120 }
2122 identity TPM_ALG_CMAC {
2123 if-feature "tpm20";
2124 base tpm20;
2125 base symmetric;
2126 base signing;
2127 description
2128 "block Cipher-based Message Authentication Code (CMAC)";
2129 reference
2130 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2131 ISO/IEC 9797-1:2011 Algorithm 5. ALG_ID: 0x003F";
2132 }
2134 identity TPM_ALG_CTR {
2135 if-feature "tpm20";
2136 base tpm20;
2137 base symmetric;
2138 base encryption_mode;
2139 description
2140 "Counter mode";
2142 reference
2143 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2144 ISO/IEC 10116. ALG_ID: 0x0040";
2145 }
2147 identity TPM_ALG_OFB {
2148 base tpm20;
2149 base symmetric;
2150 base encryption_mode;
2151 description
2152 "Output Feedback mode";
2153 reference
2154 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2155 ISO/IEC 10116. ALG_ID: 0x0041";
2156 }
2158 identity TPM_ALG_CBC {
2159 if-feature "tpm20";
2160 base tpm20;
2161 base symmetric;
2162 base encryption_mode;
2163 description
2164 "Cipher Block Chaining mode";
2165 reference
2166 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2167 ISO/IEC 10116. ALG_ID: 0x0042";
2168 }
2170 identity TPM_ALG_CFB {
2171 if-feature "tpm20";
2172 base tpm20;
2173 base symmetric;
2174 base encryption_mode;
2175 description
2176 "Cipher Feedback mode";
2177 reference
2178 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2179 ISO/IEC 10116. ALG_ID: 0x0043";
2180 }
2182 identity TPM_ALG_ECB {
2183 if-feature "tpm20";
2184 base tpm20;
2185 base symmetric;
2186 base encryption_mode;
2187 description
2188 "Electronic Codebook mode";
2189 reference
2190 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2191 ISO/IEC 10116. ALG_ID: 0x0044";
2192 }
2194 identity TPM_ALG_CCM {
2195 if-feature "tpm20";
2196 base tpm20;
2197 base symmetric;
2198 base signing;
2199 base encryption_mode;
2200 description
2201 "Counter with Cipher Block Chaining-Message Authentication
2202 Code (CCM)";
2203 reference
2204 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2205 NIST SP800-38C. ALG_ID: 0x0050";
2206 }
2208 identity TPM_ALG_GCM {
2209 if-feature "tpm20";
2210 base tpm20;
2211 base symmetric;
2212 base signing;
2213 base encryption_mode;
2214 description
2215 "Galois/Counter Mode (GCM)";
2216 reference
2217 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2218 NIST SP800-38D. ALG_ID: 0x0051";
2219 }
2221 identity TPM_ALG_KW {
2222 if-feature "tpm20";
2223 base tpm20;
2224 base symmetric;
2225 base signing;
2226 base encryption_mode;
2227 description
2228 "AES Key Wrap (KW)";
2229 reference
2230 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2231 NIST SP800-38F. ALG_ID: 0x0052";
2232 }
2234 identity TPM_ALG_KWP {
2235 if-feature "tpm20";
2236 base tpm20;
2237 base symmetric;
2238 base signing;
2239 base encryption_mode;
2240 description
2241 "AES Key Wrap with Padding (KWP)";
2242 reference
2243 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2244 NIST SP800-38F. ALG_ID: 0x0053";
2245 }
2247 identity TPM_ALG_EAX {
2248 if-feature "tpm20";
2249 base tpm20;
2250 base symmetric;
2251 base signing;
2252 base encryption_mode;
2253 description
2254 "Authenticated-Encryption Mode";
2255 reference
2256 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2257 NIST SP800-38F. ALG_ID: 0x0054";
2258 }
2260 identity TPM_ALG_EDDSA {
2261 if-feature "tpm20";
2262 base tpm20;
2263 base asymmetric;
2264 base signing;
2265 description
2266 "Edwards-curve Digital Signature Algorithm (PureEdDSA)";
2267 reference
2268 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2269 RFC 8032. ALG_ID: 0x0060";
2270 }
2271 }
2272
2274 Note that not all cryptographic functions are required for use by
2275 ietf-tpm-remote-attestation.yang. However the full definition of
2276 Table 3 of [TCG-Algos] will allow use by additional YANG
2277 specifications.
2279 3. IANA Considerations
2281 This document registers the following namespace URIs in the
2282 [xml-registry] as per [RFC3688]:
2284 URI: urn:ietf:params:xml:ns:yang:ietf-tpm-remote-attestation
2285 Registrant Contact: The IESG.
2287 XML: N/A; the requested URI is an XML namespace.
2289 URI: urn:ietf:params:xml:ns:yang:ietf-tcg-algs
2291 Registrant Contact: The IESG.
2293 XML: N/A; the requested URI is an XML namespace.
2295 This document registers the following YANG modules in the registry
2296 [yang-parameters] as per Section 14 of [RFC6020]:
2298 Name: ietf-tpm-remote-attestation
2300 Namespace: urn:ietf:params:xml:ns:yang:ietf-tpm-remote-
2301 attestation
2303 Prefix: tpm
2305 Reference: draft-ietf-rats-yang-tpm-charra (RFC form)
2307 Name: ietf-tcg-algs
2309 Namespace: urn:ietf:params:xml:ns:yang:ietf-tcg-algs
2311 Prefix: taa
2313 Reference: draft-ietf-rats-yang-tpm-charra (RFC form)
2315 4. Security Considerations
2317 The YANG module ietf-tpm-remote-attestation.yang specified in this
2318 document defines a schema for data that is designed to be accessed
2319 via network management protocols such as NETCONF [RFC6241] or
2320 RESTCONF [RFC8040]. The lowest NETCONF layer is the secure transport
2321 layer, and the mandatory-to-implement secure transport is Secure
2322 Shell (SSH) [RFC6242]. The lowest RESTCONF layer is HTTPS, and the
2323 mandatory-to-implement secure transport is TLS [RFC8446].
2325 There are a number of data nodes defined in this YANG module that are
2326 writable/creatable/deletable (i.e., _config true_, which is the
2327 default). These data nodes may be considered sensitive or vulnerable
2328 in some network environments. Write operations (e.g., _edit-config_)
2329 to these data nodes without proper protection can have a negative
2330 effect on network operations. These are the subtrees and data nodes
2331 as well as their sensitivity/vulnerability:
2333 Container '/rats-support-structures/attester-supported-algos': 'tpm1
2334 2-asymmetric-signing', 'tpm12-hash', 'tpm20-asymmetric-signing',
2335 and 'tpm20-hash'. All could be populated with algorithms that are
2336 not supported by the underlying physical TPM installed by the
2337 equipment vendor. A vendor should restrict the ability to
2338 configure unsupported algorithms.
2340 Container: '/rats-support-structures/tpms': 'name': Although shown
2341 as 'rw', it is system generated. Therefore, it should not be
2342 possible for an operator to add or remove a TPM from the
2343 configuration.
2345 'tpm20-pcr-bank': It is possible to configure PCRs for extraction
2346 which are not being extended by system software. This could
2347 unnecessarily use TPM resources.
2349 'certificates': It is possible to provision a certificate which
2350 does not correspond to an Attestation Identity Key (AIK) within
2351 the TPM 1.2, or an Attestation Key (AK) within the TPM 2.0
2352 respectively. In such a case, calls to an RPC requesting this
2353 specific certificate could result in either no response or a
2354 response for an unexpected TPM.
2356 RPC 'tpm12-challenge-response-attestation': The receiver of the RPC
2357 response must verify that the certificate is for an active AIK,
2358 i.e., the certificate has been confirmed by a third party as being
2359 able to support Attestation on the targeted TPM 1.2.
2361 RPC 'tpm20-challenge-response-attestation': The receiver of the RPC
2362 response must verify that the certificate is for an active AK,
2363 i.e., the private key confirmation of the quote signature within
2364 the RPC response has been confirmed by a third party to belong to
2365 an entity legitimately able to perform Attestation on the targeted
2366 TPM 2.0.
2368 RPC 'log-retrieval': Requesting a large volume of logs from the
2369 attester could require significant system resources and create a
2370 denial of service.
2372 Information collected through the RPCs above could reveal that
2373 specific versions of software and configurations of endpoints that
2374 could identify vulnerabilities on those systems. Therefore, RPCs
2375 should be protected by NACM [RFC8341] with a default setting of deny-
2376 all to limit the extraction of attestation data by only authorized
2377 Verifiers.
2379 For the YANG module ietf-tcg-algs.yang, please use care when
2380 selecting specific algorithms. The introductory section of
2381 [TCG-Algos] highlights that some algorithms should be considered
2382 legacy, and recommends implementers and adopters diligently evaluate
2383 available information such as governmental, industrial, and academic
2384 research before selecting an algorithm for use.
2386 5. References
2388 5.1. Normative References
2390 [bios-log] "TCG PC Client Platform Firmware Profile Specification,
2391 Section 9.4.5.2", n.d.,
2392 .
2396 [BIOS-Log-Event-Type]
2397 "TCG PC Client Platform Firmware Profile Specification",
2398 n.d., .
2401 [cel] "Canonical Event Log Format, Section 4.3", n.d.,
2402 .
2405 [I-D.ietf-netconf-keystore]
2406 Watsen, K., "A YANG Data Model for a Keystore", Work in
2407 Progress, Internet-Draft, draft-ietf-netconf-keystore-24,
2408 7 March 2022, .
2411 [I-D.ietf-rats-architecture]
2412 Birkholz, H., Thaler, D., Richardson, M., Smith, N., and
2413 W. Pan, "Remote Attestation Procedures Architecture", Work
2414 in Progress, Internet-Draft, draft-ietf-rats-architecture-
2415 15, 8 February 2022, .
2418 [I-D.ietf-rats-tpm-based-network-device-attest]
2419 Fedorkow, G., Voit, E., and J. Fitzgerald-McKay, "TPM-
2420 based Network Device Remote Integrity Verification", Work
2421 in Progress, Internet-Draft, draft-ietf-rats-tpm-based-
2422 network-device-attest-14, 22 March 2022,
2423 .
2426 [IEEE-Std-1363-2000]
2427 "IEEE 1363-2000 - IEEE Standard Specifications for Public-
2428 Key Cryptography", n.d.,
2429 .
2431 [IEEE-Std-1363a-2004]
2432 "1363a-2004 - IEEE Standard Specifications for Public-Key
2433 Cryptography - Amendment 1: Additional Techniques", n.d.,
2434 .
2436 [ISO-IEC-10116]
2437 "ISO/IEC 10116:2017 - Information technology", n.d.,
2438 .
2440 [ISO-IEC-10118-3]
2441 "Dedicated hash-functions - ISO/IEC 10118-3:2018", n.d.,
2442 .
2444 [ISO-IEC-14888-3]
2445 "ISO/IEC 14888-3:2018 - Digital signatures with appendix",
2446 n.d., .
2448 [ISO-IEC-15946-1]
2449 "ISO/IEC 15946-1:2016 - Information technology", n.d.,
2450 .
2452 [ISO-IEC-18033-3]
2453 "ISO/IEC 18033-3:2010 - Encryption algorithms", n.d.,
2454 .
2456 [ISO-IEC-9797-1]
2457 "Message Authentication Codes (MACs) - ISO/IEC
2458 9797-1:2011", n.d.,
2459 .
2461 [ISO-IEC-9797-2]
2462 "Message Authentication Codes (MACs) - ISO/IEC
2463 9797-2:2011", n.d.,
2464 .
2466 [NIST-PUB-FIPS-202]
2467 "SHA-3 Standard: Permutation-Based Hash and Extendable-
2468 Output Functions", n.d.,
2469 .
2472 [NIST-SP800-108]
2473 "Recommendation for Key Derivation Using Pseudorandom
2474 Functions", n.d.,
2475 .
2478 [NIST-SP800-38C]
2479 "Recommendation for Block Cipher Modes of Operation: the
2480 CCM Mode for Authentication and Confidentiality", n.d.,
2481 .
2484 [NIST-SP800-38D]
2485 "Recommendation for Block Cipher Modes of Operation:
2486 Galois/Counter Mode (GCM) and GMAC", n.d.,
2487 .
2490 [NIST-SP800-38F]
2491 "Recommendation for Block Cipher Modes of Operation:
2492 Methods for Key Wrapping", n.d.,
2493 .
2496 [NIST-SP800-56A]
2497 "Recommendation for Pair-Wise Key-Establishment Schemes
2498 Using Discrete Logarithm Cryptography", n.d.,
2499 .
2502 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed-
2503 Hashing for Message Authentication", RFC 2104,
2504 DOI 10.17487/RFC2104, February 1997,
2505 .
2507 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
2508 Requirement Levels", BCP 14, RFC 2119,
2509 DOI 10.17487/RFC2119, March 1997,
2510 .
2512 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
2513 DOI 10.17487/RFC3688, January 2004,
2514 .
2516 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
2517 the Network Configuration Protocol (NETCONF)", RFC 6020,
2518 DOI 10.17487/RFC6020, October 2010,
2519 .
2521 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
2522 and A. Bierman, Ed., "Network Configuration Protocol
2523 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
2524 .
2526 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure
2527 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011,
2528 .
2530 [RFC6933] Bierman, A., Romascanu, D., Quittek, J., and M.
2531 Chandramouli, "Entity MIB (Version 4)", RFC 6933,
2532 DOI 10.17487/RFC6933, May 2013,
2533 .
2535 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types",
2536 RFC 6991, DOI 10.17487/RFC6991, July 2013,
2537 .
2539 [RFC8017] Moriarty, K., Ed., Kaliski, B., Jonsson, J., and A. Rusch,
2540 "PKCS #1: RSA Cryptography Specifications Version 2.2",
2541 RFC 8017, DOI 10.17487/RFC8017, November 2016,
2542 .
2544 [RFC8032] Josefsson, S. and I. Liusvaara, "Edwards-Curve Digital
2545 Signature Algorithm (EdDSA)", RFC 8032,
2546 DOI 10.17487/RFC8032, January 2017,
2547 .
2549 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
2550 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
2551 .
2553 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2554 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
2555 May 2017, .
2557 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration
2558 Access Control Model", STD 91, RFC 8341,
2559 DOI 10.17487/RFC8341, March 2018,
2560 .
2562 [RFC8348] Bierman, A., Bjorklund, M., Dong, J., and D. Romascanu, "A
2563 YANG Data Model for Hardware Management", RFC 8348,
2564 DOI 10.17487/RFC8348, March 2018,
2565 .
2567 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol
2568 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
2569 .
2571 [TCG-Algos]
2572 "TCG Algorithm Registry", n.d.,
2573 .
2576 [TPM1.2] TCG, "TPM 1.2 Main Specification", 2 October 2003,
2577 .
2580 [TPM1.2-Commands]
2581 "TPM Main Part 3 Commands", n.d.,
2582 .
2585 [TPM1.2-Structures]
2586 "TPM Main Part 2 TPM Structures", n.d.,
2587 .
2590 [TPM2.0] TCG, "TPM 2.0 Library Specification", 15 March 2013,
2591 .
2594 [TPM2.0-Arch]
2595 "Trusted Platform Module Library - Part 1: Architecture",
2596 n.d., .
2600 [TPM2.0-Key]
2601 TCG, "TPM 2.0 Keys for Device Identity and Attestation,
2602 Rev12", 8 October 2021,
2603 .
2607 [TPM2.0-Structures]
2608 "Trusted Platform Module Library - Part 2: Structures",
2609 n.d., .
2612 [UEFI-Secure-Boot]
2613 "Unified Extensible Firmware Interface (UEFI)
2614 Specification Version 2.9 (March 2021), Section 32.1
2615 (Secure Boot)", n.d.,
2616 .
2619 5.2. Informative References
2621 [I-D.ietf-rats-reference-interaction-models]
2622 Birkholz, H., Eckel, M., Pan, W., and E. Voit, "Reference
2623 Interaction Models for Remote Attestation Procedures",
2624 Work in Progress, Internet-Draft, draft-ietf-rats-
2625 reference-interaction-models-05, 26 January 2022,
2626 .
2629 [IMA-Kernel-Source]
2630 "Linux Integrity Measurement Architecture (IMA): Kernel
2631 Sourcecode", n.d., .
2635 [NIST-915121]
2636 "True Randomness Can't be Left to Chance: Why entropy is
2637 important for information security", n.d.,
2638 .
2641 [xml-registry]
2642 "IETF XML Registry", n.d.,
2643 .
2646 [yang-parameters]
2647 "YANG Parameters", n.d.,
2648 .
2651 Appendix A. Integrity Measurement Architecture (IMA)
2653 IMA extends the principles of Measured Boot [TPM2.0-Arch] and Secure
2654 Boot [UEFI-Secure-Boot] to the Linux operating system, applying it to
2655 operating system applications and files. IMA has been part of the
2656 Linux integrity subsystem of the Linux kernel since 2009 (kernel
2657 version 2.6.30). The IMA mechanism represented by the YANG module in
2658 this specification is rooted in the kernel version 5.16
2659 [IMA-Kernel-Source]. IMA enables the protection of system integrity
2660 by collecting (commonly referred to as measuring) and storing
2661 measurements (called Claims in the context of IETF RATS) of files
2662 before execution so that these measurements can be used later, at
2663 system runtime, in remote attestation procedures. IMA acts in
2664 support of the appraisal of Evidence (which includes measurement
2665 Claims) by leveraging reference integrity measurements stored in
2666 extended file attributes.
2668 In support of the appraisal of Evidence, IMA maintains an ordered
2669 list of measurements in kernel-space, the Stored Measurement Log
2670 (SML), for all files that have been measured before execution since
2671 the operating system was started. Although IMA can be used without a
2672 TPM, it is typically used in conjunction with a TPM to anchor the
2673 integrity of the SML in a hardware-protected secure storage location,
2674 i.e., Platform Configuration Registers (PCRs) provided by TPMs. IMA
2675 provides the SML in both binary and ASCII representations in the
2676 Linux security file system _securityfs_ (/sys/kernel/security/ima/).
2678 IMA templates define the format of the SML, i.e., which fields are
2679 included in a log record. Examples are file path, file hash, user
2680 ID, group ID, file signature, and extended file attributes. IMA
2681 comes with a set of predefined template formats and also allows a
2682 custom format, i.e., a format consisting of template fields supported
2683 by IMA. Template usage is typically determined by boot arguments
2684 passed to the kernel. Alternatively, the format can also be hard-
2685 coded into custom kernels. IMA templates and fields are extensible
2686 in the kernel source code. As a result, more template fields can be
2687 added in the future.
2689 IMA policies define which files are measured using the IMA policy
2690 language. Built-in policies can be passed as boot arguments to the
2691 kernel. Custom IMA policies can be defined once during runtime or be
2692 hard-coded into a custom kernel. If no policy is defined, no
2693 measurements are taken and IMA is effectively disabled.
2695 A comprehensive description of the content fields ins in native Linux
2696 IMA TLV format can be found in Table 16 of the Canonical Event Log
2697 (CEL) specification [cel]. The CEL specification also illustrates
2698 the use of templates to enable extended or customized IMA TLV formats
2699 in Section 5.1.6.
2701 Appendix B. IMA for Network Equipment Boot Logs
2703 Network equipment can generally implement similar IMA-protected
2704 functions to generate measurements (Claims) about the boot process of
2705 a device and enable corresponding remote attestation. Network
2706 Equipment Boot Logs combine the measurement and logging of boot
2707 components and operating system components (executables and files)
2708 into a single log file in a format identical to the IMA format. Note
2709 that the format used for logging measurement of boot components in
2710 this scheme differs from the boot logging strategy described
2711 elsewhere in this document.
2713 During the boot process of the network device, i.e., from BIOS to the
2714 end of the operating system and user-space, all files executed can be
2715 measured and logged in the order of their execution. When the
2716 Verifier initiates a remote attestation process (e.g., challenge-
2717 response remote attestation as defined in this document), the network
2718 equipment takes on the role of an Attester and can convey to the
2719 Verifier Claims that comprise the measurement log as well as the
2720 corresponding PCR values (Evidence) of a TPM.
2722 The verifier can appraise the integrity (compliance with the
2723 Reference Values) of each executed file by comparing its measured
2724 value with the Reference Value. Based on the execution order, the
2725 Verifier can compute a PCR reference value (by replaying the log) and
2726 compare it to the Measurement Log Claims obtained in conjunction with
2727 the PCR Evidence to assess their trustworthiness with respect to an
2728 intended operational state.
2730 Network equipment usually executes multiple components in parallel.
2731 This holds not only during the operating system loading phase, but
2732 also even during the BIOS boot phase. With this measurement log
2733 mechanism, network equipment can take on the role of an Attester,
2734 proving to the Verifier the trustworthiness of its boot process.
2735 Using the measurement log, Verifiers can precisely identify
2736 mismatching log entries to infer potentially tampered components.
2738 This mechanism also supports scenarios that modify files on the
2739 Attester that are subsequently executed during the boot phase (e.g.,
2740 updating/patching) by simply updating the appropriate Reference
2741 Values in Reference Integrity Manifests that inform Verifiers about
2742 how an Attester is composed.
2744 Authors' Addresses
2746 Henk Birkholz
2747 Fraunhofer SIT
2748 Rheinstrasse 75
2749 64295 Darmstadt
2750 Germany
2751 Email: henk.birkholz@sit.fraunhofer.de
2753 Michael Eckel
2754 Fraunhofer SIT
2755 Rheinstrasse 75
2756 64295 Darmstadt
2757 Germany
2758 Email: michael.eckel@sit.fraunhofer.de
2760 Shwetha Bhandari
2761 ThoughtSpot
2762 Email: shwetha.bhandari@thoughtspot.com
2764 Eric Voit
2765 Cisco Systems
2766 Email: evoit@cisco.com
2768 Bill Sulzen
2769 Cisco Systems
2770 Email: bsulzen@cisco.com
2772 Liang Xia (Frank)
2773 Huawei Technologies
2774 101 Software Avenue, Yuhuatai District
2775 Nanjing
2776 Jiangsu, 210012
2777 China
2778 Email: Frank.Xialiang@huawei.com
2780 Tom Laffey
2781 Hewlett Packard Enterprise
2782 Email: tom.laffey@hpe.com
2784 Guy C. Fedorkow
2785 Juniper Networks
2786 10 Technology Park Drive
2787 Westford
2788 Email: gfedorkow@juniper.net