idnits 2.17.1
draft-ietf-rats-yang-tpm-charra-17.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 66 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 (16 March 2022) is 772 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')
== Outdated reference: A later version (-14) exists of
draft-ietf-rats-tpm-based-network-device-attest-13
** 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 (~~), 10 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: 17 September 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 16 March 2022
18 A YANG Data Model for Challenge-Response-based Remote Attestation
19 Procedures using TPMs
20 draft-ietf-rats-yang-tpm-charra-17
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 17 September 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 Simplified BSD License text
65 as described in Section 4.e of the Trust Legal Provisions and are
66 provided without warranty as described in the Simplified 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 . . . . . . . . . . . . . . . . . . . . . . . . . 50
79 5.1. Normative References . . . . . . . . . . . . . . . . . . 51
80 5.2. Informative References . . . . . . . . . . . . . . . . . 55
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 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], [ima-log], [BIOS-Log-Event-Type], as
148 well as 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
164 [ima-log]). Also see 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
374 +--rw tpm12-pcrs* pcr
375 +--rw tpm20-pcr-bank* [tpm20-hash-algo]
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. This
387 allows an operator to limit algorithms available for use by RPCs to
388 just a desired set from the universe of all allowed hash algorithms
389 by the TCG.
391 +--rw attester-supported-algos
392 +--rw tpm12-asymmetric-signing* identityref
393 +--rw tpm12-hash* identityref
394 +--rw tpm20-asymmetric-signing* identityref
395 +--rw tpm20-hash* identityref
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-03-15.yang"
411 module ietf-tpm-remote-attestation {
412 namespace "urn:ietf:params:xml:ns:yang:ietf-tpm-remote-attestation";
413 prefix tpm;
415 import ietf-yang-types {
416 prefix yang;
417 }
418 import ietf-hardware {
419 prefix hw;
420 }
421 import ietf-keystore {
422 prefix ks;
423 }
424 import ietf-tcg-algs {
425 prefix taa;
426 }
428 organization
429 "IETF RATS (Remote ATtestation procedureS) Working Group";
430 contact
431 "WG Web :
432 WG List :
433 Author : Eric Voit
434 Author : Henk Birkholz
435 Author : Michael Eckel
436 Author : Shwetha Bhandari
437 Author : Bill Sulzen
438 Author : Liang Xia (Frank)
439 Author : Tom Laffey
440 Author : Guy Fedorkow ";
441 description
442 "A YANG module to enable a TPM 1.2 and TPM 2.0 based
443 remote attestation procedure using a challenge-response
444 interaction model and the TPM 1.2 and TPM 2.0 Quote
445 primitive operations.
447 Copyright (c) 2022 IETF Trust and the persons identified
448 as authors of the code. All rights reserved.
449 Redistribution and use in source and binary forms, with or
450 without modification, is permitted pursuant to, and subject to
451 the license terms contained in, the Simplified BSD License set
452 forth in Section 4.c of the IETF Trust's Legal Provisions
453 Relating to IETF Documents
454 (https://trustee.ietf.org/license-info).
456 This version of this YANG module is part of RFC XXXX
457 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC
458 itself for full legal notices.
460 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
461 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED',
462 'MAY', and 'OPTIONAL' in this document are to be interpreted as
463 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when,
464 they appear in all capitals, as shown here.";
466 revision 2022-03-15 {
467 description
468 "Initial version";
469 reference
470 "RFC XXXX: A YANG Data Model for Challenge-Response-based Remote
471 Attestation Procedures using TPMs";
472 }
474 /*****************/
475 /* Features */
476 /*****************/
478 feature mtpm {
479 description
480 "The device supports the remote attestation of multiple
481 TPM based cryptoprocessors.";
482 }
484 feature bios {
485 description
486 "The device supports the bios logs.";
487 reference
488 "bios-log:
489 https://trustedcomputinggroup.org/wp-content/uploads/
490 PC-ClientSpecific_Platform_Profile_for_TPM_2p0_Systems_v51.pdf
491 Section 9.4.5.2";
492 }
494 feature ima {
495 description
496 "The device supports Integrity Measurement Architecture logs.
497 Many variants of IMA logs exist in the deployment. Each encodes
498 the log entry contents as the specific measurements which get
499 hashed into a PCRs as Evidence. See the reference below for
500 one example of such an encoding.";
501 reference
502 "ima-log:
503 https://www.trustedcomputinggroup.org/wp-content/uploads/
504 TCG_IWG_CEL_v1_r0p41_pub.pdf Section 4.3";
505 }
506 feature netequip_boot {
507 description
508 "The device supports the netequip_boot logs.";
509 reference
510 "netequip-boot-log:
511 https://www.kernel.org/doc/Documentation/ABI/testing/ima_policy";
512 }
514 /*****************/
515 /* Typedefs */
516 /*****************/
518 typedef pcr {
519 type uint8 {
520 range "0..31";
521 }
522 description
523 "Valid index number for a PCR. A {{TPM2.0}} compliant PCR index
524 extends from 0-31. At this time a typical TPM would have no
525 more than 32 PCRS.";
526 }
528 typedef compute-node-ref {
529 type leafref {
530 path "/tpm:rats-support-structures/tpm:compute-nodes"
531 + "/tpm:compute-node/tpm:node-name";
532 }
533 description
534 "This type is used to reference a hardware node. Note that an
535 implementer might include an alternative leafref pointing to a
536 different YANG module node specifying hardware structures.";
537 }
539 typedef certificate-name-ref {
540 type leafref {
541 path "/tpm:rats-support-structures/tpm:tpms/tpm:tpm"
542 + "/tpm:certificates/tpm:certificate/tpm:name";
543 }
544 description
545 "A type which allows identification of a TPM based certificate.";
546 }
548 /******************/
549 /* Identities */
550 /******************/
552 identity attested_event_log_type {
553 description
554 "Base identity allowing categorization of the reasons why an
555 attested measurement has been taken on an Attester.";
556 }
558 identity ima {
559 base attested_event_log_type;
560 description
561 "An event type recorded in IMA.";
562 }
564 identity bios {
565 base attested_event_log_type;
566 description
567 "An event type associated with BIOS/UEFI.";
568 }
570 identity netequip_boot {
571 base attested_event_log_type;
572 description
573 "An event type associated with Network Equipment Boot.";
574 }
576 /*****************/
577 /* Groupings */
578 /*****************/
580 grouping tpm20-hash-algo {
581 description
582 "The cryptographic algorithm used to hash the TPM2 PCRs. This
583 must be from the list of platform supported options.";
584 leaf tpm20-hash-algo {
585 type identityref {
586 base taa:hash;
587 }
588 must '/tpm:rats-support-structures/tpm:attester-supported-algos'
589 + '/tpm:tpm20-hash' {
590 error-message "This platform does not support tpm20-hash-algo";
591 }
592 default "taa:TPM_ALG_SHA256";
593 description
594 "The hash scheme that is used to hash a TPM2.0 PCR. This
595 must be one of those supported by a platform.";
596 }
597 }
599 grouping tpm12-hash-algo {
600 description
601 "The cryptographic algorithm used to hash the TPM1.2 PCRs.";
603 leaf tpm12-hash-algo {
604 type identityref {
605 base taa:hash;
606 }
607 must '/tpm:rats-support-structures/tpm:attester-supported-algos'
608 + '/tpm:tpm12-hash' {
609 error-message "This platform does not support tpm12-hash-algo";
610 }
611 default "taa:TPM_ALG_SHA1";
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 }
616 }
618 grouping nonce {
619 description
620 "A random number intended to guarantee freshness and for use
621 as part of a replay-detection mechanism.";
622 leaf nonce-value {
623 type binary;
624 mandatory true;
625 description
626 "A cryptographically generated random number which should
627 not be predictable prior to its issuance from a random
628 number generation function. The random number MUST be
629 derived from an entropy source external to the Attester.
631 Note that a nonce sent into a TPM will typically be 160 or 256
632 binary digits long. (This is 20 or 32 bytes.) So if fewer
633 binary digits are sent, this nonce object will be padded
634 with leading zeros within Quotes returned from the TPM.
635 Additionally if more bytes are sent, the nonce will be trimmed
636 to the most significant binary digits.";
637 }
638 }
640 grouping tpm12-pcr-selection {
641 description
642 "A Verifier can request one or more PCR values using its
643 individually created Attestation Key Certificate (AC).
644 The corresponding selection filter is represented in this
645 grouping.";
646 leaf-list pcr-index {
647 type pcr;
648 description
649 "The numbers/indexes of the PCRs. In addition, any selection
650 of PCRs MUST verify that the set of PCRs requested are a
651 subset the set of PCRs exposed by in the leaf-list
652 /tpm:rats-support-structures
653 /tpm:tpms/tpm:tpm[name=current()]/tpm:tpm12-pcrs";
654 }
655 }
657 grouping tpm20-pcr-selection {
658 description
659 "A Verifier can acquire one or more PCR values, which are hashed
660 together in a TPM2B_DIGEST coming from the TPM2. The selection
661 list of desired PCRs and the Hash Algorithm is represented in
662 this grouping.";
663 list tpm20-pcr-selection {
664 unique "tpm20-hash-algo";
665 description
666 "Specifies the list of PCRs and Hash Algorithms that can be
667 returned within a TPM2B_DIGEST.";
668 reference
669 "TPM2.0-Structures:
670 https://www.trustedcomputinggroup.org/wp-content/uploads/
671 TPM-Rev-2.0-Part-2-Structures-01.38.pdf Section 10.9.7";
672 uses tpm20-hash-algo;
673 leaf-list pcr-index {
674 type pcr;
675 must '/tpm:rats-support-structures/tpm:tpms'
676 + '/tpm:tpm[name = current()] and '
677 + '/tpm:rats-support-structures/tpm:tpms/tpm:tpm'
678 + '/tpm:tpm20-pcr-bank[pcr-index = current()]' {
679 error-message "Acquiring this PCR index is not supported";
680 }
681 description
682 "The numbers of the PCRs that which are being tracked
683 with a hash based on the tpm20-hash-algo. In addition,
684 any selection of PCRs MUST verify that the set of PCRs
685 requested are a subset the set of PCR indexes exposed
686 within /tpm:rats-support-structures/tpm:tpms
687 /tpm:tpm[name=current()]/tpm:tpm20-pcr-bank
688 /tpm:pcr-index";
689 }
690 }
691 }
693 grouping certificate-name-ref {
694 description
695 "Identifies a certificate in a keystore.";
696 leaf certificate-name {
697 type certificate-name-ref;
698 mandatory true;
699 description
700 "Identifies a certificate in a keystore.";
701 }
702 }
704 grouping tpm-name {
705 description
706 "A unique TPM on a device.";
707 leaf name {
708 type string;
709 description
710 "Unique system generated name for a TPM on a device.";
711 }
712 }
714 grouping node-uptime {
715 description
716 "Uptime in seconds of the node.";
717 leaf up-time {
718 type uint32;
719 description
720 "Uptime in seconds of this node reporting its data";
721 }
722 }
724 grouping tpm12-attestation {
725 description
726 "Contains an instance of TPM1.2 style signed cryptoprocessor
727 measurements. It is supplemented by unsigned Attester
728 information.";
729 uses node-uptime;
730 leaf TPM_QUOTE2 {
731 type binary;
732 description
733 "Result of a TPM1.2 Quote2 operation. This includes PCRs,
734 signatures, locality, the provided nonce and other data which
735 can be further parsed to appraise the Attester.";
736 reference
737 "TPM1.2-Commands:
738 TPM1.2 commands rev116 July 2007, Section 16.5
739 https://trustedcomputinggroup.org/wp-content/uploads
740 /TPM-Main-Part-3-Commands_v1.2_rev116_01032011.pdf";
741 }
742 }
744 grouping tpm20-attestation {
745 description
746 "Contains an instance of TPM2 style signed cryptoprocessor
747 measurements. It is supplemented by unsigned Attester
748 information.";
749 leaf TPMS_QUOTE_INFO {
750 type binary;
751 mandatory true;
752 description
753 "A hash of the latest PCR values (and the hash algorithm used)
754 which have been returned from a Verifier for the selected PCRs
755 and Hash Algorithms.";
756 reference
757 "TPM2.0-Structures:
758 https://www.trustedcomputinggroup.org/wp-content/uploads/
759 TPM-Rev-2.0-Part-2-Structures-01.38.pdf Section 10.12.1";
760 }
761 leaf quote-signature {
762 type binary;
763 description
764 "Quote signature returned by TPM Quote. The signature was
765 generated using the key associated with the
766 certificate 'name'.";
767 reference
768 "TPM2.0-Structures:
769 https://www.trustedcomputinggroup.org/wp-content/uploads/
770 TPM-Rev-2.0-Part-2-Structures-01.38.pdf Section 11.2.1";
771 }
772 uses node-uptime;
773 list unsigned-pcr-values {
774 description
775 "PCR values in each PCR bank. This might appear redundant with
776 the TPM2B_DIGEST, but that digest is calculated across multiple
777 PCRs. Having to verify across multiple PCRs does not
778 necessarily make it easy for a Verifier to appraise just the
779 minimum set of PCR information which has changed since the last
780 received TPM2B_DIGEST. Put another way, why should a Verifier
781 reconstruct the proper value of all PCR Quotes when only a
782 single PCR has changed?
783 To help this happen, if the Attester does know specific PCR
784 values, the Attester can provide these individual values via
785 'unsigned-pcr-values'. By comparing this information to
786 what has previously been validated, it is possible for a
787 Verifier to confirm the Attester's signature while eliminating
789 significant processing. Note that there should never be a
790 result where an unsigned PCR value differs from what may be
791 reconstructed from the within the PCR quote and the event logs.
792 If there is a difference, a signed result which has been
793 verified from retrieved logs is considered definitive.";
794 uses tpm20-hash-algo;
795 list pcr-values {
796 key "pcr-index";
797 description
798 "List of one PCR bank.";
799 leaf pcr-index {
800 type pcr;
801 description
802 "PCR index number.";
803 }
804 leaf pcr-value {
805 type binary;
806 description
807 "PCR value.";
808 reference
809 "TPM2.0-Structures:
810 https://www.trustedcomputinggroup.org/wp-content/uploads/
811 TPM-Rev-2.0-Part-2-Structures-01.38.pdf Section 10.9.7";
812 }
813 }
814 }
815 }
817 grouping log-identifier {
818 description
819 "Identifier for type of log to be retrieved.";
820 leaf log-type {
821 type identityref {
822 base attested_event_log_type;
823 }
824 mandatory true;
825 description
826 "The corresponding measurement log type identity.";
827 }
828 }
830 grouping boot-event-log {
831 description
832 "Defines a specific instance of an event log entry
833 and corresponding to the information used to
834 extend the PCR";
835 leaf event-number {
836 type uint32;
837 description
838 "Unique event number of this event which monotonically
839 increases. The maximum event number should not be
840 reached, nor is wrapping back to an earlier number
841 supported.";
842 }
843 leaf event-type {
844 type uint32;
845 description
846 "BIOS Log Event Type:
847 https://trustedcomputinggroup.org/wp-content/uploads/
848 TCG_PCClient_PFP_r1p05_v23_pub.pdf Section 10.4.1";
849 }
850 leaf pcr-index {
851 type pcr;
852 description
853 "Defines the PCR index that this event extended";
854 }
855 list digest-list {
856 description
857 "Hash of event data";
858 leaf hash-algo {
859 type identityref {
860 base taa:hash;
861 }
862 description
863 "The hash scheme that is used to compress the event data in
864 each of the leaf-list digest items.";
865 }
866 leaf-list digest {
867 type binary;
868 description
869 "The hash of the event data using the algorithm of the
870 'hash-algo' against 'event data'.";
871 }
872 }
873 leaf event-size {
874 type uint32;
875 description
876 "Size of the event data";
877 }
878 leaf-list event-data {
879 type binary;
880 description
881 "The event data size determined by event-size. For more
882 see ";
883 }
884 }
886 grouping bios-event-log {
887 description
888 "Measurement log created by the BIOS/UEFI.";
889 list bios-event-entry {
890 key "event-number";
891 description
892 "Ordered list of TCG described event log
893 that extended the PCRs in the order they
894 were logged";
895 uses boot-event-log;
896 }
897 }
899 grouping ima-event {
900 description
901 "Defines a hash log extend event for IMA measurements";
902 reference
903 "ima-log:
904 https://www.trustedcomputinggroup.org/wp-content/uploads/
905 TCG_IWG_CEL_v1_r0p41_pub.pdf Section 4.3";
906 leaf event-number {
907 type uint64;
908 description
909 "Unique event number of this event which monotonically
910 increases. The maximum event number should not be
911 reached, nor is wrapping back to an earlier number
912 supported.";
913 }
914 leaf ima-template {
915 type string;
916 description
917 "Name of the template used for event logs
918 for e.g. ima, ima-ng, ima-sig";
919 }
920 leaf filename-hint {
921 type string;
922 description
923 "File that was measured";
924 }
925 leaf filedata-hash {
926 type binary;
927 description
928 "Hash of filedata as updated based upon the
929 filedata-hash-algorithm";
930 }
931 leaf filedata-hash-algorithm {
932 type string;
933 description
934 "Algorithm used for filedata-hash";
935 }
936 leaf template-hash-algorithm {
937 type string;
938 description
939 "Algorithm used for template-hash";
940 }
941 leaf template-hash {
942 type binary;
943 description
944 "hash(filedata-hash, filename-hint)";
945 }
946 leaf pcr-index {
947 type pcr;
948 description
949 "Defines the PCR index that this event extended";
950 }
951 leaf signature {
952 type binary;
953 description
954 "Digital file signature which provides a
955 fingerprint for the file being measured.";
956 }
957 }
959 grouping ima-event-log {
960 description
961 "Measurement log created by IMA.";
962 list ima-event-entry {
963 key "event-number";
964 description
965 "Ordered list of ima event logs by event-number";
966 uses ima-event;
967 }
968 }
970 grouping network-equipment-boot-event-log {
971 description
972 "Measurement log created by Network Equipment Boot. The Network
973 Equipment Boot format is identical to the IMA format. In
974 contrast to the IMA log, the Network Equipment Boot log
975 includes every measurable event from an Attester, including
976 the boot stages of BIOS, Bootloader, etc. In essence, the scope
977 of events represented in this format combines the scope of BIOS
978 events and IMA events.";
979 list boot-event-entry {
980 key "event-number";
981 description
982 "Ordered list of Network Equipment Boot event logs
983 by event-number, using the IMA event format.";
984 uses ima-event;
985 }
986 }
987 grouping event-logs {
988 description
989 "A selector for the log and its type.";
990 choice attested_event_log_type {
991 mandatory true;
992 description
993 "Event log type determines the event logs content.";
994 case bios {
995 if-feature "bios";
996 description
997 "BIOS/UEFI event logs";
998 container bios-event-logs {
999 description
1000 "BIOS/UEFI event logs";
1001 uses bios-event-log;
1002 }
1003 }
1004 case ima {
1005 if-feature "ima";
1006 description
1007 "IMA event logs.";
1008 container ima-event-logs {
1009 description
1010 "IMA event logs.";
1011 uses ima-event-log;
1012 }
1013 }
1014 case netequip_boot {
1015 if-feature "netequip_boot";
1016 description
1017 "Network Equipment Boot event logs";
1018 container boot-event-logs {
1019 description
1020 "Network equipment boot event logs.";
1021 uses network-equipment-boot-event-log;
1022 }
1023 }
1024 }
1025 }
1027 /**********************/
1028 /* RPC operations */
1029 /**********************/
1031 rpc tpm12-challenge-response-attestation {
1032 if-feature "taa:tpm12";
1033 description
1034 "This RPC accepts the input for TSS TPM 1.2 commands made to the
1035 attesting device.";
1036 input {
1037 container tpm12-attestation-challenge {
1038 description
1039 "This container includes every information element defined
1040 in the reference challenge-response interaction model for
1041 remote attestation. Corresponding values are based on
1042 TPM 1.2 structure definitions";
1043 uses tpm12-pcr-selection;
1044 uses nonce;
1045 leaf-list certificate-name {
1046 if-feature "tpm:mtpm";
1047 type certificate-name-ref;
1048 must "/tpm:rats-support-structures/tpm:tpms"
1049 + "/tpm:tpm[tpm:firmware-version='taa:tpm12']"
1050 + "/tpm:certificates/"
1051 + "/tpm:certificate[name=current()]" {
1052 error-message "Not an available TPM1.2 AIK certificate.";
1053 }
1054 description
1055 "When populated, the RPC will only get a Quote for the
1056 TPMs associated with these certificate(s).";
1057 }
1058 }
1059 }
1060 output {
1061 list tpm12-attestation-response {
1062 unique "certificate-name";
1063 description
1064 "The binary output of TPM 1.2 TPM_Quote/TPM_Quote2, including
1065 the PCR selection and other associated attestation evidence
1066 metadata";
1067 uses certificate-name-ref {
1068 description
1069 "Certificate associated with this tpm12-attestation.";
1070 }
1071 uses tpm12-attestation;
1072 }
1073 }
1074 }
1076 rpc tpm20-challenge-response-attestation {
1077 if-feature "taa:tpm20";
1078 description
1079 "This RPC accepts the input for TSS TPM 2.0 commands of the
1080 managed device. ComponentIndex from the hardware manager YANG
1081 module is used to refer to dedicated TPM in composite devices,
1082 e.g. smart NICs, is not covered.";
1084 input {
1085 container tpm20-attestation-challenge {
1086 description
1087 "This container includes every information element defined
1088 in the reference challenge-response interaction model for
1089 remote attestation. Corresponding values are based on
1090 TPM 2.0 structure definitions";
1091 uses nonce;
1092 uses tpm20-pcr-selection;
1093 leaf-list certificate-name {
1094 if-feature "tpm:mtpm";
1095 type certificate-name-ref;
1096 must "/tpm:rats-support-structures/tpm:tpms"
1097 + "/tpm:tpm[tpm:firmware-version='taa:tpm20']"
1098 + "/tpm:certificates/"
1099 + "/tpm:certificate[name=current()]" {
1100 error-message "Not an available TPM2.0 AIK certificate.";
1101 }
1102 description
1103 "When populated, the RPC will only get a Quote for the
1104 TPMs associated with the certificates.";
1105 }
1106 }
1107 }
1108 output {
1109 list tpm20-attestation-response {
1110 unique "certificate-name";
1111 description
1112 "The binary output of TPM2b_Quote from one TPM of the
1113 node which identified by node-id. An TPMS_ATTEST structure
1114 including a length, encapsulated in a signature";
1115 uses certificate-name-ref {
1116 description
1117 "Certificate associated with this tpm20-attestation.";
1118 }
1119 uses tpm20-attestation;
1120 }
1121 }
1122 }
1124 rpc log-retrieval {
1125 description
1126 "Logs Entries are either identified via indices or via providing
1127 the last line received. The number of lines returned can be
1128 limited. The type of log is a choice that can be augmented.";
1129 input {
1130 uses log-identifier;
1131 list log-selector {
1132 description
1133 "Only log entries which meet all the selection criteria provided
1134 are to be returned by the RPC output.";
1135 leaf-list name {
1136 type string;
1137 description
1138 "Name of one or more unique TPMs on a device. If this object
1139 exists, a selection should pull only the objects related to
1140 these TPM(s). If it does not exist, all qualifying TPMs that
1141 are 'hardware-based' equals true on the device are selected.";
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.";
1322 }
1323 uses tpm12-hash-algo {
1324 when "firmware-version = 'taa:tpm12'";
1325 refine "tpm12-hash-algo" {
1326 description
1327 "The hash algorithm overwrites the default used for PCRs
1328 on this TPM1.2 compliant cryptoprocessor.";
1329 }
1330 }
1331 leaf-list tpm12-pcrs {
1332 when "../firmware-version = 'taa:tpm12'";
1333 type pcr;
1334 description
1335 "The PCRs which may be extracted from this TPM1.2
1336 compliant cryptoprocessor.";
1337 }
1338 list tpm20-pcr-bank {
1339 when "../firmware-version = 'taa:tpm20'";
1340 key "tpm20-hash-algo";
1341 description
1342 "Specifies the list of PCRs that may be extracted for
1343 a specific Hash Algorithm on this TPM2 compliant
1344 cryptoprocessor. A bank is a set of PCRs which are
1345 extended using a particular hash algorithm.";
1346 reference
1347 "TPM2.0-Structures:
1348 https://www.trustedcomputinggroup.org/wp-content/uploads/
1349 TPM-Rev-2.0-Part-2-Structures-01.38.pdf Section 10.9.7";
1350 leaf tpm20-hash-algo {
1351 type identityref {
1352 base taa:hash;
1353 }
1354 must '/tpm:rats-support-structures'
1355 + '/tpm:attester-supported-algos'
1356 + '/tpm:tpm20-hash' {
1357 error-message "This platform does not support tpm20-hash-algo";
1358 }
1359 description
1360 "The hash scheme actively being used to hash a
1361 one or more TPM2.0 PCRs.";
1362 }
1363 leaf-list pcr-index {
1364 type tpm:pcr;
1365 description
1366 "Defines what TPM2 PCRs are available to be extracted.";
1367 }
1368 }
1369 leaf status {
1370 type enumeration {
1371 enum operational {
1372 value 0;
1373 description
1374 "The TPM currently is running normally and
1375 is ready to accept and process TPM quotes.";
1376 reference
1377 "TPM2.0-Arch:
1378 https://trustedcomputinggroup.org/wp-content/uploads/
1379 TCG_TPM2_r1p59_Part1_Architecture_pub.pdf
1380 Section 12";
1381 }
1382 enum non-operational {
1383 value 1;
1384 description
1385 "TPM is in a state such as startup or shutdown which
1386 precludes the processing of TPM quotes.";
1387 }
1388 }
1389 config false;
1390 mandatory true;
1391 description
1392 "TPM chip self-test status.";
1393 }
1394 container certificates {
1395 description
1396 "The TPM's certificates, including EK certificates
1397 and Attestation Key certificates.";
1398 list certificate {
1399 key "name";
1400 description
1401 "Three types of certificates can be accessed via
1402 this statement, including Initial Attestation
1403 Key Certificate, Local Attestation Key Certificate or
1404 Endorsement Key Certificate.";
1405 leaf name {
1406 type string;
1407 description
1408 "An arbitrary name uniquely identifying a certificate
1409 associated within key within a TPM.";
1410 }
1411 leaf keystore-ref {
1412 if-feature "ks:asymmetric-keys";
1413 type leafref {
1414 path "/ks:keystore/ks:asymmetric-keys/ks:asymmetric-key"
1415 + "/ks:name";
1416 }
1417 description
1418 "A reference to a specific certificate of an
1419 asymmetric key in the Keystore.";
1421 }
1422 leaf type {
1423 type enumeration {
1424 enum endorsement-certificate {
1425 value 0;
1426 description
1427 "Endorsement Key (EK) Certificate type.";
1428 reference
1429 "TPM2.0-Key:
1430 https://trustedcomputinggroup.org/wp-content/
1431 uploads/TPM-2p0-Keys-for-Device-Identity-
1432 and-Attestation_v1_r12_pub10082021.pdf
1433 Section 3.11";
1434 }
1435 enum initial-attestation-certificate {
1436 value 1;
1437 description
1438 "Initial Attestation key (IAK) Certificate type.";
1439 reference
1440 "TPM2.0-Key:
1441 https://trustedcomputinggroup.org/wp-content/
1442 uploads/TPM-2p0-Keys-for-Device-Identity-
1443 and-Attestation_v1_r12_pub10082021.pdf
1444 Section 3.2";
1445 }
1446 enum local-attestation-certificate {
1447 value 2;
1448 description
1449 "Local Attestation Key (LAK) Certificate type.";
1450 reference
1451 "TPM2.0-Key:
1452 https://trustedcomputinggroup.org/wp-content/
1453 uploads/TPM-2p0-Keys-for-Device-Identity-
1454 and-Attestation_v1_r12_pub10082021.pdf
1455 Section 3.2";
1456 }
1457 }
1458 description
1459 "Function supported by this certificate from within the
1460 TPM.";
1461 }
1462 }
1463 }
1464 }
1465 }
1466 container attester-supported-algos {
1467 description
1468 "Identifies which TPM algorithms are available for use on an
1469 attesting platform.";
1470 leaf-list tpm12-asymmetric-signing {
1471 when "../../tpm:tpms"
1472 + "/tpm:tpm[tpm:firmware-version='taa:tpm12']";
1473 type identityref {
1474 base taa:asymmetric;
1475 }
1476 description
1477 "Platform Supported TPM12 asymmetric algorithms.";
1478 }
1479 leaf-list tpm12-hash {
1480 when "../../tpm:tpms"
1481 + "/tpm:tpm[tpm:firmware-version='taa:tpm12']";
1482 type identityref {
1483 base taa:hash;
1484 }
1485 description
1486 "Platform supported TPM12 hash algorithms.";
1487 }
1488 leaf-list tpm20-asymmetric-signing {
1489 when "../../tpm:tpms"
1490 + "/tpm:tpm[tpm:firmware-version='taa:tpm20']";
1491 type identityref {
1492 base taa:asymmetric;
1493 }
1494 description
1495 "Platform Supported TPM20 asymmetric algorithms.";
1496 }
1497 leaf-list tpm20-hash {
1498 when "../../tpm:tpms"
1499 + "/tpm:tpm[tpm:firmware-version='taa:tpm20']";
1500 type identityref {
1501 base taa:hash;
1502 }
1503 description
1504 "Platform supported TPM20 hash algorithms.";
1505 }
1506 }
1507 }
1508 }
1509
1511 Figure 1
1513 2.1.2. 'ietf-tcg-algs'
1515 This document has encoded the TCG Algorithm definitions of
1516 [TCG-Algos], revision 1.32. By including this full table as a
1517 separate YANG file within this document, it is possible for other
1518 YANG models to leverage the contents of this model. Specific
1519 references to [RFC2104], [RFC8017], [ISO-IEC-9797-1],
1520 [ISO-IEC-9797-2], [ISO-IEC-10116], [ISO-IEC-10118-3],
1521 [ISO-IEC-14888-3], [ISO-IEC-15946-1], [ISO-IEC-18033-3],
1522 [IEEE-Std-1363-2000], [IEEE-Std-1363a-2004], [NIST-PUB-FIPS-202],
1523 [NIST-SP800-38C], [NIST-SP800-38D], [NIST-SP800-38F],
1524 [NIST-SP800-56A], [NIST-SP800-108], [bios-log], [ima-log], as well as
1525 Appendix A and Appendix B exist within the YANG Model.
1527 2.1.2.1. Features
1529 There are two types of features supported: 'TPM12' and 'TPM20'.
1530 Support for either of these features indicates that a cryptoprocessor
1531 supporting the corresponding type of TCG TPM API is present on an
1532 Attester. Most commonly, only one type of cryptoprocessor will be
1533 available on an Attester.
1535 2.1.2.2. Identities
1537 There are three types of identities in this model:
1539 1. Cryptographic functions supported by a TPM algorithm; these
1540 include: 'asymmetric', 'symmetric', 'hash', 'signing',
1541 'anonymous_signing', 'encryption_mode', 'method', and
1542 'object_type'. The definitions of each of these are in Table 2
1543 of [TCG-Algos].
1545 2. API specifications for TPM types: 'tpm12' and 'tpm20'
1547 3. Specific algorithm types: Each algorithm type defines what
1548 cryptographic functions may be supported, and on which type of
1549 API specification. It is not required that an implementation of
1550 a specific TPM will support all algorithm types. The contents of
1551 each specific algorithm mirrors what is in Table 3 of
1552 [TCG-Algos].
1554 2.1.2.3. YANG Module
1555 file "ietf-tcg-algs@2022-03-09.yang"
1556 module ietf-tcg-algs {
1557 yang-version 1.1;
1558 namespace "urn:ietf:params:xml:ns:yang:ietf-tcg-algs";
1559 prefix taa;
1561 organization
1562 "IETF RATS (Remote ATtestation procedureS) Working Group";
1563 contact
1564 "WG Web:
1565 WG List:
1566 Author: Eric Voit ";
1567 description
1568 "This module defines identities for asymmetric algorithms.
1570 Copyright (c) 2022 IETF Trust and the persons identified
1571 as authors of the code. All rights reserved.
1572 Redistribution and use in source and binary forms, with
1573 or without modification, is permitted pursuant to, and
1574 subject to the license terms contained in, the Simplified
1575 BSD License set forth in Section 4.c of the IETF Trust's
1576 Legal Provisions Relating to IETF Documents
1577 (https://trustee.ietf.org/license-info).
1578 This version of this YANG module is part of RFC XXXX
1579 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC
1580 itself for full legal notices.
1581 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL',
1582 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED',
1583 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document
1584 are to be interpreted as described in BCP 14 (RFC 2119)
1585 (RFC 8174) when, and only when, they appear in all
1586 capitals, as shown here.";
1588 revision 2022-03-09 {
1589 description
1590 "Initial version";
1591 reference
1592 "RFC XXXX: A YANG Data Model for Challenge-Response-based Remote
1593 Attestation Procedures using TPMs";
1594 }
1596 /*****************/
1597 /* Features */
1598 /*****************/
1600 feature tpm12 {
1601 description
1602 "This feature indicates algorithm support for the TPM 1.2 API
1603 as per Section 4.8 of TPM1.2-Structures:
1604 TPM Main Part 2 TPM Structures
1605 https://trustedcomputinggroup.org/wp-content/uploads/TPM-
1606 Main-Part-2-TPM-Structures_v1.2_rev116_01032011.pdf";
1607 }
1609 feature tpm20 {
1610 description
1611 "This feature indicates algorithm support for the TPM 2.0 API
1612 as per Section 11.4 of Trusted Platform Module Library
1613 Part 1: Architecture. See TPM2.0-Arch:
1614 https://trustedcomputinggroup.org/wp-content/uploads/
1615 TCG_TPM2_r1p59_Part1_Architecture_pub.pdf";
1616 }
1618 /*****************/
1619 /* Identities */
1620 /*****************/
1622 identity asymmetric {
1623 description
1624 "A TCG recognized asymmetric algorithm with a public and
1625 private key.";
1626 reference
1627 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 2,
1628 https://trustedcomputinggroup.org/resource/
1629 tcg-algorithm-registry/TCG-_Algorithm_Registry_r1p32_pub";
1630 }
1632 identity symmetric {
1633 description
1634 "A TCG recognized symmetric algorithm with only a private key.";
1635 reference
1636 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 2";
1637 }
1639 identity hash {
1640 description
1641 "A TCG recognized hash algorithm that compresses input data to
1642 a digest value or indicates a method that uses a hash.";
1643 reference
1644 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 2";
1645 }
1647 identity signing {
1648 description
1649 "A TCG recognized signing algorithm";
1650 reference
1651 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 2";
1652 }
1654 identity anonymous_signing {
1655 description
1656 "A TCG recognized anonymous signing algorithm.";
1657 reference
1658 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 2";
1659 }
1661 identity encryption_mode {
1662 description
1663 "A TCG recognized encryption mode.";
1664 reference
1665 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 2";
1666 }
1668 identity method {
1669 description
1670 "A TCG recognized method such as a mask generation function.";
1671 reference
1672 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 2";
1673 }
1675 identity object_type {
1676 description
1677 "A TCG recognized object type.";
1678 reference
1679 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 2";
1680 }
1682 identity cryptoprocessor {
1683 description
1684 "Base identity identifying a crytoprocessor.";
1685 }
1687 identity tpm12 {
1688 if-feature "tpm12";
1689 base cryptoprocessor;
1690 description
1691 "Supportable by a TPM1.2.";
1692 reference
1693 "TPM1.2-Structures:
1694 https://trustedcomputinggroup.org/wp-content/uploads/
1695 TPM-Main-Part-2-TPM-Structures_v1.2_rev116_01032011.pdf
1696 TPM_ALGORITHM_ID values, Section 4.8";
1697 }
1698 identity tpm20 {
1699 if-feature "tpm20";
1700 base cryptoprocessor;
1701 description
1702 "Supportable by a TPM2.";
1703 reference
1704 "TPM2.0-Structures:
1705 https://trustedcomputinggroup.org/wp-content/uploads/
1706 TPM-Rev-2.0-Part-2-Structures-01.38.pdf";
1707 }
1709 identity TPM_ALG_RSA {
1710 if-feature "tpm12 or tpm20";
1711 base tpm12;
1712 base tpm20;
1713 base asymmetric;
1714 base object_type;
1715 description
1716 "RSA algorithm";
1717 reference
1718 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
1719 RFC 8017. ALG_ID: 0x0001";
1720 }
1722 identity TPM_ALG_TDES {
1723 if-feature "tpm12";
1724 base tpm12;
1725 base symmetric;
1726 description
1727 "Block cipher with various key sizes (Triple Data Encryption
1728 Algorithm, commonly called Triple Data Encryption Standard)
1729 Note: was banned in TPM1.2 v94";
1730 reference
1731 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
1732 ISO/IEC 18033-3. ALG_ID: 0x0003";
1733 }
1735 identity TPM_ALG_SHA1 {
1736 if-feature "tpm12 or tpm20";
1737 base hash;
1738 base tpm12;
1739 base tpm20;
1740 description
1741 "SHA1 algorithm - Deprecated due to insufficient cryptographic
1742 protection. However, it is still useful for hash algorithms
1743 where protection is not required.";
1744 reference
1745 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
1746 ISO/IEC 10118-3. ALG_ID: 0x0004";
1747 }
1749 identity TPM_ALG_HMAC {
1750 if-feature "tpm12 or tpm20";
1751 base tpm12;
1752 base tpm20;
1753 base hash;
1754 base signing;
1755 description
1756 "Hash Message Authentication Code (HMAC) algorithm";
1757 reference
1758 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3,
1759 ISO/IEC 9797-2 and RFC2104. ALG_ID: 0x0005";
1760 }
1762 identity TPM_ALG_AES {
1763 if-feature "tpm12";
1764 base tpm12;
1765 base symmetric;
1766 description
1767 "The AES algorithm with various key sizes";
1768 reference
1769 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3,
1770 ISO/IEC 18033-3. ALG_ID: 0x0006";
1771 }
1773 identity TPM_ALG_MGF1 {
1774 if-feature "tpm20";
1775 base tpm20;
1776 base hash;
1777 base method;
1778 description
1779 "hash-based mask-generation function";
1780 reference
1781 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3,
1782 IEEE Std 1363-2000 and IEEE Std 1363a-2004.
1783 ALG_ID: 0x0007";
1784 }
1786 identity TPM_ALG_KEYEDHASH {
1787 if-feature "tpm20";
1788 base tpm20;
1789 base hash;
1790 base object_type;
1791 description
1792 "An encryption or signing algorithm using a keyed hash. These
1793 may use XOR for encryption or an HMAC for signing and may
1794 also refer to a data object that is neither signing nor
1795 encrypting.";
1796 reference
1797 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3,
1798 ALG_ID: 0x0008";
1799 }
1801 identity TPM_ALG_XOR {
1802 if-feature "tpm12 or tpm20";
1803 base tpm12;
1804 base tpm20;
1805 base hash;
1806 base symmetric;
1807 description
1808 "The XOR encryption algorithm.";
1809 reference
1810 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3.
1811 ALG_ID: 0x000A";
1812 }
1814 identity TPM_ALG_SHA256 {
1815 if-feature "tpm20";
1816 base tpm20;
1817 base hash;
1818 description
1819 "The SHA 256 algorithm";
1820 reference
1821 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
1822 ISO/IEC 10118-3. ALG_ID: 0x000B";
1823 }
1825 identity TPM_ALG_SHA384 {
1826 if-feature "tpm20";
1827 base tpm20;
1828 base hash;
1829 description
1830 "The SHA 384 algorithm";
1831 reference
1832 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
1833 ISO/IEC 10118-3. ALG_ID: 0x000C";
1834 }
1836 identity TPM_ALG_SHA512 {
1837 if-feature "tpm20";
1838 base tpm20;
1839 base hash;
1840 description
1841 "The SHA 512 algorithm";
1843 reference
1844 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
1845 ISO/IEC 10118-3. ALG_ID: 0x000D";
1846 }
1848 identity TPM_ALG_NULL {
1849 if-feature "tpm20";
1850 base tpm20;
1851 description
1852 "NULL algorithm";
1853 reference
1854 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3.
1855 ALG_ID: 0x0010";
1856 }
1858 identity TPM_ALG_SM3_256 {
1859 if-feature "tpm20";
1860 base tpm20;
1861 base hash;
1862 description
1863 "The SM3 hash algorithm.";
1864 reference
1865 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
1866 ISO/IEC 10118-3:2018. ALG_ID: 0x0012";
1867 }
1869 identity TPM_ALG_SM4 {
1870 if-feature "tpm20";
1871 base tpm20;
1872 base symmetric;
1873 description
1874 "SM4 symmetric block cipher";
1875 reference
1876 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3.
1877 ALG_ID: 0x0013";
1878 }
1880 identity TPM_ALG_RSASSA {
1881 if-feature "tpm20";
1882 base tpm20;
1883 base asymmetric;
1884 base signing;
1885 description
1886 "RFC 8017 Signature algorithm defined in section 8.2
1887 (RSASSAPKCS1-v1_5)";
1888 reference
1889 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
1890 RFC 8017. ALG_ID: 0x0014";
1892 }
1894 identity TPM_ALG_RSAES {
1895 if-feature "tpm20";
1896 base tpm20;
1897 base asymmetric;
1898 base encryption_mode;
1899 description
1900 "RFC 8017 Signature algorithm defined in section 7.2
1901 (RSAES-PKCS1-v1_5)";
1902 reference
1903 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
1904 RFC 8017. ALG_ID: 0x0015";
1905 }
1907 identity TPM_ALG_RSAPSS {
1908 if-feature "tpm20";
1909 base tpm20;
1910 base asymmetric;
1911 base signing;
1912 description
1913 "Padding algorithm defined in section 8.1 (RSASSA PSS)";
1914 reference
1915 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
1916 RFC 8017. ALG_ID: 0x0016";
1917 }
1919 identity TPM_ALG_OAEP {
1920 if-feature "tpm20";
1921 base tpm20;
1922 base asymmetric;
1923 base encryption_mode;
1924 description
1925 "Padding algorithm defined in section 7.1 (RSASSA OAEP)";
1926 reference
1927 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
1928 RFC 8017. ALG_ID: 0x0017";
1929 }
1931 identity TPM_ALG_ECDSA {
1932 if-feature "tpm20";
1933 base tpm20;
1934 base asymmetric;
1935 base signing;
1936 description
1937 "Signature algorithm using elliptic curve cryptography (ECC)";
1938 reference
1939 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
1940 ISO/IEC 14888-3. ALG_ID: 0x0018";
1941 }
1943 identity TPM_ALG_ECDH {
1944 if-feature "tpm20";
1945 base tpm20;
1946 base asymmetric;
1947 base method;
1948 description
1949 "Secret sharing using ECC";
1950 reference
1951 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
1952 NIST SP800-56A. ALG_ID: 0x0019";
1953 }
1955 identity TPM_ALG_ECDAA {
1956 if-feature "tpm20";
1957 base tpm20;
1958 base asymmetric;
1959 base signing;
1960 base anonymous_signing;
1961 description
1962 "Elliptic-curve based anonymous signing scheme";
1963 reference
1964 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
1965 TCG TPM 2.0 library specification. ALG_ID: 0x001A";
1966 }
1968 identity TPM_ALG_SM2 {
1969 if-feature "tpm20";
1970 base tpm20;
1971 base asymmetric;
1972 base signing;
1973 base encryption_mode;
1974 base method;
1975 description
1976 "SM2 - depending on context, either an elliptic-curve based,
1977 signature algorithm, an encryption scheme, or a key exchange
1978 protocol";
1979 reference
1980 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3.
1981 ALG_ID: 0x001B";
1982 }
1984 identity TPM_ALG_ECSCHNORR {
1985 if-feature "tpm20";
1986 base tpm20;
1987 base asymmetric;
1988 base signing;
1989 description
1990 "Elliptic-curve based Schnorr signature";
1991 reference
1992 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3.
1993 ALG_ID: 0x001C";
1994 }
1996 identity TPM_ALG_ECMQV {
1997 if-feature "tpm20";
1998 base tpm20;
1999 base asymmetric;
2000 base method;
2001 description
2002 "Two-phase elliptic-curve key";
2003 reference
2004 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2005 NIST SP800-56A. ALG_ID: 0x001D";
2006 }
2008 identity TPM_ALG_KDF1_SP800_56A {
2009 if-feature "tpm20";
2010 base tpm20;
2011 base hash;
2012 base method;
2013 description
2014 "Concatenation key derivation function";
2015 reference
2016 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2017 NIST SP800-56A (approved alternative1) section 5.8.1.
2018 ALG_ID: 0x0020";
2019 }
2021 identity TPM_ALG_KDF2 {
2022 if-feature "tpm20";
2023 base tpm20;
2024 base hash;
2025 base method;
2026 description
2027 "Key derivation function";
2028 reference
2029 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2030 IEEE 1363a-2004 KDF2 section 13.2. ALG_ID: 0x0021";
2031 }
2033 identity TPM_ALG_KDF1_SP800_108 {
2034 base TPM_ALG_KDF2;
2035 description
2036 "A key derivation method";
2037 reference
2038 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2039 NIST SP800-108 - Section 5.1 KDF. ALG_ID: 0x0022";
2040 }
2042 identity TPM_ALG_ECC {
2043 if-feature "tpm20";
2044 base tpm20;
2045 base asymmetric;
2046 base object_type;
2047 description
2048 "Prime field ECC";
2049 reference
2050 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2051 ISO/IEC 15946-1. ALG_ID: 0x0023";
2052 }
2054 identity TPM_ALG_SYMCIPHER {
2055 if-feature "tpm20";
2056 base tpm20;
2057 base symmetric;
2058 description
2059 "Object type for a symmetric block cipher";
2060 reference
2061 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2062 TCG TPM 2.0 library specification. ALG_ID: 0x0025";
2063 }
2065 identity TPM_ALG_CAMELLIA {
2066 if-feature "tpm20";
2067 base tpm20;
2068 base symmetric;
2069 description
2070 "The Camellia algorithm";
2071 reference
2072 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2073 ISO/IEC 18033-3. ALG_ID: 0x0026";
2074 }
2076 identity TPM_ALG_SHA3_256 {
2077 if-feature "tpm20";
2078 base tpm20;
2079 base hash;
2080 description
2081 "ISO/IEC 10118-3 - the SHA 256 algorithm";
2082 reference
2083 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2084 NIST PUB FIPS 202. ALG_ID: 0x0027";
2085 }
2087 identity TPM_ALG_SHA3_384 {
2088 if-feature "tpm20";
2089 base tpm20;
2090 base hash;
2091 description
2092 "The SHA 384 algorithm";
2093 reference
2094 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2095 NIST PUB FIPS 202. ALG_ID: 0x0028";
2096 }
2098 identity TPM_ALG_SHA3_512 {
2099 if-feature "tpm20";
2100 base tpm20;
2101 base hash;
2102 description
2103 "The SHA 512 algorithm";
2104 reference
2105 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2106 NIST PUB FIPS 202. ALG_ID: 0x0029";
2107 }
2109 identity TPM_ALG_CMAC {
2110 if-feature "tpm20";
2111 base tpm20;
2112 base symmetric;
2113 base signing;
2114 description
2115 "block Cipher-based Message Authentication Code (CMAC)";
2116 reference
2117 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2118 ISO/IEC 9797-1:2011 Algorithm 5. ALG_ID: 0x003F";
2119 }
2121 identity TPM_ALG_CTR {
2122 if-feature "tpm20";
2123 base tpm20;
2124 base symmetric;
2125 base encryption_mode;
2126 description
2127 "Counter mode";
2128 reference
2129 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2130 ISO/IEC 10116. ALG_ID: 0x0040";
2131 }
2132 identity TPM_ALG_OFB {
2133 base tpm20;
2134 base symmetric;
2135 base encryption_mode;
2136 description
2137 "Output Feedback mode";
2138 reference
2139 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2140 ISO/IEC 10116. ALG_ID: 0x0041";
2141 }
2143 identity TPM_ALG_CBC {
2144 if-feature "tpm20";
2145 base tpm20;
2146 base symmetric;
2147 base encryption_mode;
2148 description
2149 "Cipher Block Chaining mode";
2150 reference
2151 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2152 ISO/IEC 10116. ALG_ID: 0x0042";
2153 }
2155 identity TPM_ALG_CFB {
2156 if-feature "tpm20";
2157 base tpm20;
2158 base symmetric;
2159 base encryption_mode;
2160 description
2161 "Cipher Feedback mode";
2162 reference
2163 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2164 ISO/IEC 10116. ALG_ID: 0x0043";
2165 }
2167 identity TPM_ALG_ECB {
2168 if-feature "tpm20";
2169 base tpm20;
2170 base symmetric;
2171 base encryption_mode;
2172 description
2173 "Electronic Codebook mode";
2174 reference
2175 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2176 ISO/IEC 10116. ALG_ID: 0x0044";
2177 }
2179 identity TPM_ALG_CCM {
2180 if-feature "tpm20";
2181 base tpm20;
2182 base symmetric;
2183 base signing;
2184 base encryption_mode;
2185 description
2186 "Counter with Cipher Block Chaining-Message Authentication
2187 Code (CCM)";
2188 reference
2189 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2190 NIST SP800-38C. ALG_ID: 0x0050";
2191 }
2193 identity TPM_ALG_GCM {
2194 if-feature "tpm20";
2195 base tpm20;
2196 base symmetric;
2197 base signing;
2198 base encryption_mode;
2199 description
2200 "Galois/Counter Mode (GCM)";
2201 reference
2202 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2203 NIST SP800-38D. ALG_ID: 0x0051";
2204 }
2206 identity TPM_ALG_KW {
2207 if-feature "tpm20";
2208 base tpm20;
2209 base symmetric;
2210 base signing;
2211 base encryption_mode;
2212 description
2213 "AES Key Wrap (KW)";
2214 reference
2215 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2216 NIST SP800-38F. ALG_ID: 0x0052";
2217 }
2219 identity TPM_ALG_KWP {
2220 if-feature "tpm20";
2221 base tpm20;
2222 base symmetric;
2223 base signing;
2224 base encryption_mode;
2225 description
2226 "AES Key Wrap with Padding (KWP)";
2227 reference
2228 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2229 NIST SP800-38F. ALG_ID: 0x0053";
2230 }
2232 identity TPM_ALG_EAX {
2233 if-feature "tpm20";
2234 base tpm20;
2235 base symmetric;
2236 base signing;
2237 base encryption_mode;
2238 description
2239 "Authenticated-Encryption Mode";
2240 reference
2241 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2242 NIST SP800-38F. ALG_ID: 0x0054";
2243 }
2245 identity TPM_ALG_EDDSA {
2246 if-feature "tpm20";
2247 base tpm20;
2248 base asymmetric;
2249 base signing;
2250 description
2251 "Edwards-curve Digital Signature Algorithm (PureEdDSA)";
2252 reference
2253 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2254 RFC 8032. ALG_ID: 0x0060";
2255 }
2256 }
2257
2259 Note that not all cryptographic functions are required for use by
2260 "ietf-tpm-remote-attestation.yang". However the full definition of
2261 Table 3 of [TCG-Algos] will allow use by additional YANG
2262 specifications.
2264 3. IANA Considerations
2266 This document registers the following namespace URIs in the
2267 [xml-registry] as per [RFC3688]:
2269 URI: urn:ietf:params:xml:ns:yang:ietf-tpm-remote-attestation
2271 Registrant Contact: The IESG.
2273 XML: N/A; the requested URI is an XML namespace.
2275 URI: urn:ietf:params:xml:ns:yang:ietf-tcg-algs
2276 Registrant Contact: The IESG.
2278 XML: N/A; the requested URI is an XML namespace.
2280 This document registers the following YANG modules in the registry
2281 [yang-parameters] as per Section 14 of [RFC6020]:
2283 Name: ietf-tpm-remote-attestation
2285 Namespace: urn:ietf:params:xml:ns:yang:ietf-tpm-remote-
2286 attestation
2288 Prefix: tpm
2290 Reference: draft-ietf-rats-yang-tpm-charra (RFC form)
2292 Name: ietf-tcg-algs
2294 Namespace: urn:ietf:params:xml:ns:yang:ietf-tcg-algs
2296 Prefix: taa
2298 Reference: draft-ietf-rats-yang-tpm-charra (RFC form)
2300 4. Security Considerations
2302 The YANG module ietf-tpm-remote-attestation.yang specified in this
2303 document defines a schema for data that is designed to be accessed
2304 via network management protocols such as NETCONF [RFC6241] or
2305 RESTCONF [RFC8040]. The lowest NETCONF layer is the secure transport
2306 layer, and the mandatory-to-implement secure transport is Secure
2307 Shell (SSH) [RFC6242]. The lowest RESTCONF layer is HTTPS, and the
2308 mandatory-to-implement secure transport is TLS [RFC8446].
2310 There are a number of data nodes defined in this YANG module that are
2311 writable/creatable/deletable (i.e., _config true_, which is the
2312 default). These data nodes may be considered sensitive or vulnerable
2313 in some network environments. Write operations (e.g., _edit-config_)
2314 to these data nodes without proper protection can have a negative
2315 effect on network operations. These are the subtrees and data nodes
2316 as well as their sensitivity/vulnerability:
2318 Container '/rats-support-structures/attester-supported-algos': 'tpm1
2319 2-asymmetric-signing', 'tpm12-hash', 'tpm20-asymmetric-signing',
2320 and 'tpm20-hash'. All could be populated with algorithms that are
2321 not supported by the underlying physical TPM installed by the
2322 equipment vendor. A vendor should restrict the ability to
2323 configure unsupported algorithms.
2325 Container: '/rats-support-structures/tpms': 'name': Although shown
2326 as 'rw', it is system generated. Therefore, it should not be
2327 possible for an operator to add or remove a TPM from the
2328 configuration.
2330 'tpm20-pcr-bank': It is possible to configure PCRs for extraction
2331 which are not being extended by system software. This could
2332 unnecessarily use TPM resources.
2334 'certificates': It is possible to provision a certificate which
2335 does not correspond to an Attestation Identity Key (AIK) within
2336 the TPM 1.2, or an Attestation Key (AK) within the TPM 2.0
2337 respectively. In such a case, calls to an RPC requesting this
2338 specific certificate could result in either no response or a
2339 response for an unexpected TPM.
2341 RPC 'tpm12-challenge-response-attestation': The receiver of the RPC
2342 response must verify that the certificate is for an active AIK,
2343 i.e., the certificate has been confirmed by a third party as being
2344 able to support Attestation on the targeted TPM 1.2.
2346 RPC 'tpm20-challenge-response-attestation': The receiver of the RPC
2347 response must verify that the certificate is for an active AK,
2348 i.e., the private key confirmation of the quote signature within
2349 the RPC response has been confirmed by a third party to belong to
2350 an entity legitimately able to perform Attestation on the targeted
2351 TPM 2.0.
2353 RPC 'log-retrieval': Requesting a large volume of logs from the
2354 attester could require significant system resources and create a
2355 denial of service.
2357 Information collected through the RPCs above could reveal that
2358 specific versions of software and configurations of endpoints that
2359 could identify vulnerabilities on those systems. Therefore, RPCs
2360 should be protected by NACM [RFC8341] with a default setting of deny-
2361 all to limit the extraction of attestation data by only authorized
2362 Verifiers.
2364 For the YANG module ietf-tcg-algs.yang, please use care when
2365 selecting specific algorithms. The introductory section of
2366 [TCG-Algos] highlights that some algorithms should be considered
2367 legacy, and recommends implementers and adopters diligently evaluate
2368 available information such as governmental, industrial, and academic
2369 research before selecting an algorithm for use.
2371 5. References
2372 5.1. Normative References
2374 [bios-log] "TCG PC Client Platform Firmware Profile Specification,
2375 Section 9.4.5.2", n.d.,
2376 .
2380 [BIOS-Log-Event-Type]
2381 "TCG PC Client Platform Firmware Profile Specification",
2382 n.d., .
2385 [I-D.ietf-netconf-keystore]
2386 Watsen, K., "A YANG Data Model for a Keystore", Work in
2387 Progress, Internet-Draft, draft-ietf-netconf-keystore-24,
2388 7 March 2022, .
2391 [I-D.ietf-rats-architecture]
2392 Birkholz, H., Thaler, D., Richardson, M., Smith, N., and
2393 W. Pan, "Remote Attestation Procedures Architecture", Work
2394 in Progress, Internet-Draft, draft-ietf-rats-architecture-
2395 15, 8 February 2022, .
2398 [I-D.ietf-rats-tpm-based-network-device-attest]
2399 Fedorkow, G., Voit, E., and J. Fitzgerald-McKay, "TPM-
2400 based Network Device Remote Integrity Verification", Work
2401 in Progress, Internet-Draft, draft-ietf-rats-tpm-based-
2402 network-device-attest-13, 1 March 2022,
2403 .
2406 [IEEE-Std-1363-2000]
2407 "IEEE 1363-2000 - IEEE Standard Specifications for Public-
2408 Key Cryptography", n.d.,
2409 .
2411 [IEEE-Std-1363a-2004]
2412 "1363a-2004 - IEEE Standard Specifications for Public-Key
2413 Cryptography - Amendment 1: Additional Techniques", n.d.,
2414 .
2416 [ima-log] "Canonical Event Log Format, Section 4.3", n.d.,
2417 .
2420 [ISO-IEC-10116]
2421 "ISO/IEC 10116:2017 - Information technology", n.d.,
2422 .
2424 [ISO-IEC-10118-3]
2425 "Dedicated hash-functions - ISO/IEC 10118-3:2018", n.d.,
2426 .
2428 [ISO-IEC-14888-3]
2429 "ISO/IEC 14888-3:2018 - Digital signatures with appendix",
2430 n.d., .
2432 [ISO-IEC-15946-1]
2433 "ISO/IEC 15946-1:2016 - Information technology", n.d.,
2434 .
2436 [ISO-IEC-18033-3]
2437 "ISO/IEC 18033-3:2010 - Encryption algorithms", n.d.,
2438 .
2440 [ISO-IEC-9797-1]
2441 "Message Authentication Codes (MACs) - ISO/IEC
2442 9797-1:2011", n.d.,
2443 .
2445 [ISO-IEC-9797-2]
2446 "Message Authentication Codes (MACs) - ISO/IEC
2447 9797-2:2011", n.d.,
2448 .
2450 [NIST-PUB-FIPS-202]
2451 "SHA-3 Standard: Permutation-Based Hash and Extendable-
2452 Output Functions", n.d.,
2453 .
2456 [NIST-SP800-108]
2457 "Recommendation for Key Derivation Using Pseudorandom
2458 Functions", n.d.,
2459 .
2462 [NIST-SP800-38C]
2463 "Recommendation for Block Cipher Modes of Operation: the
2464 CCM Mode for Authentication and Confidentiality", n.d.,
2465 .
2468 [NIST-SP800-38D]
2469 "Recommendation for Block Cipher Modes of Operation:
2470 Galois/Counter Mode (GCM) and GMAC", n.d.,
2471 .
2474 [NIST-SP800-38F]
2475 "Recommendation for Block Cipher Modes of Operation:
2476 Methods for Key Wrapping", n.d.,
2477 .
2480 [NIST-SP800-56A]
2481 "Recommendation for Pair-Wise Key-Establishment Schemes
2482 Using Discrete Logarithm Cryptography", n.d.,
2483 .
2486 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed-
2487 Hashing for Message Authentication", RFC 2104,
2488 DOI 10.17487/RFC2104, February 1997,
2489 .
2491 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
2492 Requirement Levels", BCP 14, RFC 2119,
2493 DOI 10.17487/RFC2119, March 1997,
2494 .
2496 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
2497 DOI 10.17487/RFC3688, January 2004,
2498 .
2500 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
2501 the Network Configuration Protocol (NETCONF)", RFC 6020,
2502 DOI 10.17487/RFC6020, October 2010,
2503 .
2505 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
2506 and A. Bierman, Ed., "Network Configuration Protocol
2507 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
2508 .
2510 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure
2511 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011,
2512 .
2514 [RFC6933] Bierman, A., Romascanu, D., Quittek, J., and M.
2515 Chandramouli, "Entity MIB (Version 4)", RFC 6933,
2516 DOI 10.17487/RFC6933, May 2013,
2517 .
2519 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types",
2520 RFC 6991, DOI 10.17487/RFC6991, July 2013,
2521 .
2523 [RFC8017] Moriarty, K., Ed., Kaliski, B., Jonsson, J., and A. Rusch,
2524 "PKCS #1: RSA Cryptography Specifications Version 2.2",
2525 RFC 8017, DOI 10.17487/RFC8017, November 2016,
2526 .
2528 [RFC8032] Josefsson, S. and I. Liusvaara, "Edwards-Curve Digital
2529 Signature Algorithm (EdDSA)", RFC 8032,
2530 DOI 10.17487/RFC8032, January 2017,
2531 .
2533 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
2534 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
2535 .
2537 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2538 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
2539 May 2017, .
2541 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration
2542 Access Control Model", STD 91, RFC 8341,
2543 DOI 10.17487/RFC8341, March 2018,
2544 .
2546 [RFC8348] Bierman, A., Bjorklund, M., Dong, J., and D. Romascanu, "A
2547 YANG Data Model for Hardware Management", RFC 8348,
2548 DOI 10.17487/RFC8348, March 2018,
2549 .
2551 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol
2552 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
2553 .
2555 [TCG-Algos]
2556 "TCG Algorithm Registry", n.d.,
2557 .
2560 [TPM1.2] TCG, ., "TPM 1.2 Main Specification", 2 October 2003,
2561 .
2564 [TPM1.2-Commands]
2565 "TPM Main Part 3 Commands", n.d.,
2566 .
2569 [TPM1.2-Structures]
2570 "TPM Main Part 2 TPM Structures", n.d.,
2571 .
2574 [TPM2.0] TCG, ., "TPM 2.0 Library Specification", 15 March 2013,
2575 .
2578 [TPM2.0-Arch]
2579 "Trusted Platform Module Library - Part 1: Architecture",
2580 n.d., .
2584 [TPM2.0-Key]
2585 TCG, ., "TPM 2.0 Keys for Device Identity and Attestation,
2586 Rev12", 8 October 2021,
2587 .
2591 [TPM2.0-Structures]
2592 "Trusted Platform Module Library - Part 2: Structures",
2593 n.d., .
2596 [UEFI-Secure-Boot]
2597 "Unified Extensible Firmware Interface (UEFI)
2598 Specification Version 2.9 (March 2021), Section 32.1
2599 (Secure Boot)", n.d.,
2600 .
2603 5.2. Informative References
2605 [I-D.ietf-rats-reference-interaction-models]
2606 Birkholz, H., Eckel, M., Pan, W., and E. Voit, "Reference
2607 Interaction Models for Remote Attestation Procedures",
2608 Work in Progress, Internet-Draft, draft-ietf-rats-
2609 reference-interaction-models-05, 26 January 2022,
2610 .
2613 [IMA-Kernel-Source]
2614 "Linux Integrity Measurement Architecture (IMA): Kernel
2615 Sourcecode", n.d., .
2619 [NIST-915121]
2620 "True Randomness Can't be Left to Chance: Why entropy is
2621 important for information security", n.d.,
2622 .
2625 [xml-registry]
2626 "IETF XML Registry", n.d.,
2627 .
2630 [yang-parameters]
2631 "YANG Parameters", n.d.,
2632 .
2635 Appendix A. Integrity Measurement Architecture (IMA)
2637 IMA extends the principles of Measured Boot [TPM2.0-Arch] and Secure
2638 Boot [UEFI-Secure-Boot] to the Linux operating system, applying it to
2639 operating system applications and files. IMA has been part of the
2640 Linux integrity subsystem of the Linux kernel since 2009 (kernel
2641 version 2.6.30). The IMA mechanism represented by the YANG module in
2642 this specification is rooted in the kernel version 5.16
2643 [IMA-Kernel-Source]. IMA enables the protection of system integrity
2644 by collecting (commonly referred to as measuring) and storing
2645 measurements (called Claims in the context of IETF RATS) of files
2646 before execution so that these measurements can be used later, at
2647 system runtime, in remote attestation procedures. IMA acts in
2648 support of the appraisal of Evidence (which includes measurement
2649 Claims) by leveraging reference integrity measurements stored in
2650 extended file attributes.
2652 In support of the appraisal of Evidence, IMA maintains an ordered
2653 list of measurements in kernel-space, the Stored Measurement Log
2654 (SML), for all files that have been measured before execution since
2655 the operating system was started. Although IMA can be used without a
2656 TPM, it is typically used in conjunction with a TPM to anchor the
2657 integrity of the SML in a hardware-protected secure storage location,
2658 i.e., Platform Configuration Registers (PCRs) provided by TPMs. IMA
2659 provides the SML in both binary and ASCII representations in the
2660 Linux security file system _securityfs_ ("/sys/kernel/security/
2661 ima/").
2663 IMA templates define the format of the SML, i.e., which fields are
2664 included in a log record. Examples are file path, file hash, user
2665 ID, group ID, file signature, and extended file attributes. IMA
2666 comes with a set of predefined template formats and also allows a
2667 custom format, i.e., a format consisting of template fields supported
2668 by IMA. Template usage is typically determined by boot arguments
2669 passed to the kernel. Alternatively, the format can also be hard-
2670 compiled into custom kernels. IMA templates and fields are
2671 extensible in the kernel source code. As a result, more template
2672 fields can be added in the future.
2674 IMA policies define which files are measured using the IMA policy
2675 language. Built-in policies can be passed as boot arguments to the
2676 kernel. Custom IMA policies can be defined once during runtime or be
2677 hard-compiled into a custom kernel. If no policy is defined, no
2678 measurements are taken and IMA is effectively disabled.
2680 Appendix B. IMA for Network Equipment Boot Logs
2682 Network equipment can generally implement similar IMA-protected
2683 functions to generate measurements (Claims) about the boot process of
2684 a device and enable corresponding remote attestation. Network
2685 Equipment Boot Logs combine the measurement and logging of boot
2686 components and operating system components (executables and files)
2687 into a single log file in identical IMA format.
2689 During the boot process of the network device, i.e., from BIOS to the
2690 end of the operating system and user-space, all files executed during
2691 this process can be measured and logged in the order of their
2692 execution. When the Verifier initiates a remote attestation process
2693 (e.g., challenge-response remote attestation as defined in this
2694 document), the network equipment takes on the role of an Attester and
2695 can convey to the Verifier Claims that comprise the measurement log
2696 as well as the corresponding PCR values (Evidence) of a TPM.
2698 The verifier can appraise the integrity (compliance with the
2699 Reference Values) of each executed file by comparing its measured
2700 value with the Reference Value. Based on the execution order, the
2701 Verifier can compute a PCR reference value (by replaying the log) and
2702 compare it to the Measurement Log Claims obtained in conjunction with
2703 the PCR Evidence to assess their trustworthiness with respect to an
2704 intended operational state.
2706 Not only during the operating system loading phase, even during the
2707 BIOS boot phase, network equipment usually executes multiple
2708 components. With this measurement log mechanism, network equipment
2709 can take on the role of an Attester, proving to the Verifier the
2710 trustworthiness of its boot process. Using the measurement log,
2711 Verifiers can precisely identify mismatching log entries to infer
2712 potentially tampered components.
2714 This mechanism also supports scenarios that modify files on the
2715 Attester and are executed during the boot phase (e.g., updating/
2716 patching) by simply updating the appropriate Reference Values in
2717 Reference Integrity Manifests that inform Verifiers about how an
2718 Attester is composed.
2720 Authors' Addresses
2722 Henk Birkholz
2723 Fraunhofer SIT
2724 Rheinstrasse 75
2725 64295 Darmstadt
2726 Germany
2728 Email: henk.birkholz@sit.fraunhofer.de
2730 Michael Eckel
2731 Fraunhofer SIT
2732 Rheinstrasse 75
2733 64295 Darmstadt
2734 Germany
2736 Email: michael.eckel@sit.fraunhofer.de
2738 Shwetha Bhandari
2739 ThoughtSpot
2741 Email: shwetha.bhandari@thoughtspot.com
2742 Eric Voit
2743 Cisco Systems
2745 Email: evoit@cisco.com
2747 Bill Sulzen
2748 Cisco Systems
2750 Email: bsulzen@cisco.com
2752 Liang Xia (Frank)
2753 Huawei Technologies
2754 101 Software Avenue, Yuhuatai District
2755 Nanjing
2756 Jiangsu, 210012
2757 China
2759 Email: Frank.Xialiang@huawei.com
2761 Tom Laffey
2762 Hewlett Packard Enterprise
2764 Email: tom.laffey@hpe.com
2766 Guy C. Fedorkow
2767 Juniper Networks
2768 10 Technology Park Drive
2769 Westford
2771 Email: gfedorkow@juniper.net