idnits 2.17.00 (12 Aug 2021)
/tmp/idnits8664/draft-ietf-rats-yang-tpm-charra-19.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:
----------------------------------------------------------------------------
== 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 (15 April 2022) is 29 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'
** 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'
Summary: 6 errors (**), 0 flaws (~~), 5 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 October 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 15 April 2022
18 A YANG Data Model for Challenge-Response-based Remote Attestation
19 Procedures using TPMs
20 draft-ietf-rats-yang-tpm-charra-19
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 October 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
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. 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
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-23.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 Simplified 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-03-23 {
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 must '/tpm:rats-support-structures/tpm:tpms'
678 + '/tpm:tpm[name = current()]'
679 + '/tpm:tpm20-pcr-bank[pcr-index = current()]' {
680 error-message "Acquiring this PCR index is not supported";
681 }
682 description
683 "The numbers of the PCRs that which are being tracked
684 with a hash based on the tpm20-hash-algo. In addition,
685 any selection of PCRs MUST verify that the set of PCRs
686 requested are a subset the set of PCR indexes exposed
687 within /tpm:rats-support-structures/tpm:tpms
688 /tpm:tpm[name=current()]/tpm:tpm20-pcr-bank
689 /tpm:pcr-index";
690 }
691 }
692 }
694 grouping certificate-name-ref {
695 description
696 "Identifies a certificate in a keystore.";
698 leaf certificate-name {
699 type certificate-name-ref;
700 mandatory true;
701 description
702 "Identifies a certificate in a keystore.";
703 }
704 }
706 grouping tpm-name {
707 description
708 "A unique TPM on a device.";
709 leaf name {
710 type string;
711 description
712 "Unique system generated name for a TPM on a device.";
713 }
714 }
716 grouping node-uptime {
717 description
718 "Uptime in seconds of the node.";
719 leaf up-time {
720 type uint32;
721 description
722 "Uptime in seconds of this node reporting its data";
723 }
724 }
726 grouping tpm12-attestation {
727 description
728 "Contains an instance of TPM1.2 style signed cryptoprocessor
729 measurements. It is supplemented by unsigned Attester
730 information.";
731 uses node-uptime;
732 leaf TPM_QUOTE2 {
733 type binary;
734 description
735 "Result of a TPM1.2 Quote2 operation. This includes PCRs,
736 signatures, locality, the provided nonce and other data which
737 can be further parsed to appraise the Attester.";
738 reference
739 "TPM1.2-Commands:
740 TPM1.2 commands rev116 July 2007, Section 16.5
741 https://trustedcomputinggroup.org/wp-content/uploads
742 /TPM-Main-Part-3-Commands_v1.2_rev116_01032011.pdf";
743 }
744 }
745 grouping tpm20-attestation {
746 description
747 "Contains an instance of TPM2 style signed cryptoprocessor
748 measurements. It is supplemented by unsigned Attester
749 information.";
750 leaf TPMS_QUOTE_INFO {
751 type binary;
752 mandatory true;
753 description
754 "A hash of the latest PCR values (and the hash algorithm used)
755 which have been returned from a Verifier for the selected PCRs
756 and Hash Algorithms.";
757 reference
758 "TPM2.0-Structures:
759 https://www.trustedcomputinggroup.org/wp-content/uploads/
760 TPM-Rev-2.0-Part-2-Structures-01.38.pdf Section 10.12.1";
761 }
762 leaf quote-signature {
763 type binary;
764 description
765 "Quote signature returned by TPM Quote. The signature was
766 generated using the key associated with the
767 certificate 'name'.";
768 reference
769 "TPM2.0-Structures:
770 https://www.trustedcomputinggroup.org/wp-content/uploads/
771 TPM-Rev-2.0-Part-2-Structures-01.38.pdf Section 11.2.1";
772 }
773 uses node-uptime;
774 list unsigned-pcr-values {
775 description
776 "PCR values in each PCR bank. This might appear redundant with
777 the TPM2B_DIGEST, but that digest is calculated across multiple
778 PCRs. Having to verify across multiple PCRs does not
779 necessarily make it easy for a Verifier to appraise just the
780 minimum set of PCR information which has changed since the last
781 received TPM2B_DIGEST. Put another way, why should a Verifier
782 reconstruct the proper value of all PCR Quotes when only a
783 single PCR has changed?
784 To help this happen, if the Attester does know specific PCR
785 values, the Attester can provide these individual values via
786 'unsigned-pcr-values'. By comparing this information to
787 what has previously been validated, it is possible for a
788 Verifier to confirm the Attester's signature while eliminating
790 significant processing. Note that there should never be a
791 result where an unsigned PCR value differs from what may be
792 reconstructed from the within the PCR quote and the event logs.
794 If there is a difference, a signed result which has been
795 verified from retrieved logs is considered definitive.";
796 uses tpm20-hash-algo;
797 list pcr-values {
798 key "pcr-index";
799 description
800 "List of one PCR bank.";
801 leaf pcr-index {
802 type pcr;
803 description
804 "PCR index number.";
805 }
806 leaf pcr-value {
807 type binary;
808 description
809 "PCR value.";
810 reference
811 "TPM2.0-Structures:
812 https://www.trustedcomputinggroup.org/wp-content/uploads/
813 TPM-Rev-2.0-Part-2-Structures-01.38.pdf Section 10.9.7";
814 }
815 }
816 }
817 }
819 grouping log-identifier {
820 description
821 "Identifier for type of log to be retrieved.";
822 leaf log-type {
823 type identityref {
824 base attested_event_log_type;
825 }
826 mandatory true;
827 description
828 "The corresponding measurement log type identity.";
829 }
830 }
832 grouping boot-event-log {
833 description
834 "Defines a specific instance of an event log entry
835 and corresponding to the information used to
836 extend the PCR";
837 leaf event-number {
838 type uint32;
839 description
840 "Unique event number of this event which monotonically
841 increases within a given event log. The maximum event
842 number should not be reached, nor is wrapping back to
843 an earlier number supported.";
844 }
845 leaf event-type {
846 type uint32;
847 description
848 "BIOS Log Event Type:
849 https://trustedcomputinggroup.org/wp-content/uploads/
850 TCG_PCClient_PFP_r1p05_v23_pub.pdf Section 10.4.1";
851 }
852 leaf pcr-index {
853 type pcr;
854 description
855 "Defines the PCR index that this event extended";
856 }
857 list digest-list {
858 description
859 "Hash of event data";
860 leaf hash-algo {
861 type identityref {
862 base taa:hash;
863 }
864 description
865 "The hash scheme that is used to compress the event data in
866 each of the leaf-list digest items.";
867 }
868 leaf-list digest {
869 type binary;
870 description
871 "The hash of the event data using the algorithm of the
872 'hash-algo' against 'event data'.";
873 }
874 }
875 leaf event-size {
876 type uint32;
877 description
878 "Size of the event data";
879 }
880 leaf-list event-data {
881 type binary;
882 description
883 "The event data. This is a binary structure
884 of size 'event-size'. For more on what
885 might be recorded within this object
886 see [bios-log] Section 9 which details
887 viable events which might be recorded.";
888 }
889 }
890 grouping bios-event-log {
891 description
892 "Measurement log created by the BIOS/UEFI.";
893 list bios-event-entry {
894 key "event-number";
895 description
896 "Ordered list of TCG described event log
897 that extended the PCRs in the order they
898 were logged";
899 uses boot-event-log;
900 }
901 }
903 grouping ima-event {
904 description
905 "Defines a hash log extend event for IMA measurements";
906 reference
907 "ima-log:
908 https://www.trustedcomputinggroup.org/wp-content/uploads/
909 TCG_IWG_CEL_v1_r0p41_pub.pdf Section 4.3";
910 leaf event-number {
911 type uint64;
912 description
913 "Unique event number of this event which monotonically
914 increases. The maximum event number should not be
915 reached, nor is wrapping back to an earlier number
916 supported.";
917 }
918 leaf ima-template {
919 type string;
920 description
921 "Name of the template used for event logs
922 for e.g. ima, ima-ng, ima-sig";
923 }
924 leaf filename-hint {
925 type string;
926 description
927 "File name (including the path) that was measured.";
928 }
929 leaf filedata-hash {
930 type binary;
931 description
932 "Hash of filedata as updated based upon the
933 filedata-hash-algorithm";
934 }
935 leaf filedata-hash-algorithm {
936 type string;
937 description
938 "Algorithm used for filedata-hash";
939 }
940 leaf template-hash-algorithm {
941 type string;
942 description
943 "Algorithm used for template-hash";
944 }
945 leaf template-hash {
946 type binary;
947 description
948 "hash(filedata-hash, filename-hint)";
949 }
950 leaf pcr-index {
951 type pcr;
952 description
953 "Defines the PCR index that this event extended";
954 }
955 leaf signature {
956 type binary;
957 description
958 "Digital file signature which provides a
959 fingerprint for the file being measured.";
960 }
961 }
963 grouping ima-event-log {
964 description
965 "Measurement log created by IMA.";
966 list ima-event-entry {
967 key "event-number";
968 description
969 "Ordered list of ima event logs by event-number";
970 uses ima-event;
971 }
972 }
974 grouping network-equipment-boot-event-log {
975 description
976 "Measurement log created by Network Equipment Boot. The Network
977 Equipment Boot format is identical to the IMA format. In
978 contrast to the IMA log, the Network Equipment Boot log
979 includes every measurable event from an Attester, including
980 the boot stages of BIOS, Bootloader, etc. In essence, the scope
981 of events represented in this format combines the scope of BIOS
982 events and IMA events.";
983 list boot-event-entry {
984 key "event-number";
985 description
986 "Ordered list of Network Equipment Boot event logs
987 by event-number, using the IMA event format.";
988 uses ima-event;
989 }
990 }
992 grouping event-logs {
993 description
994 "A selector for the log and its type.";
995 choice attested_event_log_type {
996 mandatory true;
997 description
998 "Event log type determines the event logs content.";
999 case bios {
1000 if-feature "bios";
1001 description
1002 "BIOS/UEFI event logs";
1003 container bios-event-logs {
1004 description
1005 "BIOS/UEFI event logs";
1006 uses bios-event-log;
1007 }
1008 }
1009 case ima {
1010 if-feature "ima";
1011 description
1012 "IMA event logs.";
1013 container ima-event-logs {
1014 description
1015 "IMA event logs.";
1016 uses ima-event-log;
1017 }
1018 }
1019 case netequip_boot {
1020 if-feature "netequip_boot";
1021 description
1022 "Network Equipment Boot event logs";
1023 container boot-event-logs {
1024 description
1025 "Network equipment boot event logs.";
1026 uses network-equipment-boot-event-log;
1027 }
1028 }
1029 }
1030 }
1032 /**********************/
1033 /* RPC operations */
1034 /**********************/
1036 rpc tpm12-challenge-response-attestation {
1037 if-feature "taa:tpm12";
1038 description
1039 "This RPC accepts the input for TSS TPM 1.2 commands made to the
1040 attesting device.";
1041 input {
1042 container tpm12-attestation-challenge {
1043 description
1044 "This container includes every information element defined
1045 in the reference challenge-response interaction model for
1046 remote attestation. Corresponding values are based on
1047 TPM 1.2 structure definitions";
1048 uses tpm12-pcr-selection;
1049 uses nonce;
1050 leaf-list certificate-name {
1051 if-feature "tpm:mtpm";
1052 type certificate-name-ref;
1053 must "/tpm:rats-support-structures/tpm:tpms"
1054 + "/tpm:tpm[tpm:firmware-version='taa:tpm12']"
1055 + "/tpm:certificates/"
1056 + "/tpm:certificate[name=current()]" {
1057 error-message "Not an available TPM1.2 AIK certificate.";
1058 }
1059 description
1060 "When populated, the RPC will only get a Quote for the
1061 TPMs associated with these certificate(s).";
1062 }
1063 }
1064 }
1065 output {
1066 list tpm12-attestation-response {
1067 unique "certificate-name";
1068 description
1069 "The binary output of TPM 1.2 TPM_Quote/TPM_Quote2, including
1070 the PCR selection and other associated attestation evidence
1071 metadata";
1072 uses certificate-name-ref {
1073 description
1074 "Certificate associated with this tpm12-attestation.";
1075 }
1076 uses tpm12-attestation;
1077 }
1078 }
1079 }
1081 rpc tpm20-challenge-response-attestation {
1082 if-feature "taa:tpm20";
1083 description
1084 "This RPC accepts the input for TSS TPM 2.0 commands of the
1085 managed device. ComponentIndex from the hardware manager YANG
1086 module is used to refer to dedicated TPM in composite devices,
1087 e.g. smart NICs, is not covered.";
1088 input {
1089 container tpm20-attestation-challenge {
1090 description
1091 "This container includes every information element defined
1092 in the reference challenge-response interaction model for
1093 remote attestation. Corresponding values are based on
1094 TPM 2.0 structure definitions";
1095 uses nonce;
1096 uses tpm20-pcr-selection;
1097 leaf-list certificate-name {
1098 if-feature "tpm:mtpm";
1099 type certificate-name-ref;
1100 must "/tpm:rats-support-structures/tpm:tpms"
1101 + "/tpm:tpm[tpm:firmware-version='taa:tpm20']"
1102 + "/tpm:certificates/"
1103 + "/tpm:certificate[name=current()]" {
1104 error-message "Not an available TPM2.0 AIK certificate.";
1105 }
1106 description
1107 "When populated, the RPC will only get a Quote for the
1108 TPMs associated with the certificates.";
1109 }
1110 }
1111 }
1112 output {
1113 list tpm20-attestation-response {
1114 unique "certificate-name";
1115 description
1116 "The binary output of TPM2b_Quote from one TPM of the
1117 node which identified by node-id. An TPMS_ATTEST structure
1118 including a length, encapsulated in a signature";
1119 uses certificate-name-ref {
1120 description
1121 "Certificate associated with this tpm20-attestation.";
1122 }
1123 uses tpm20-attestation;
1124 }
1125 }
1126 }
1128 rpc log-retrieval {
1129 description
1130 "Logs Entries are either identified via indices or via providing
1131 the last line received. The number of lines returned can be
1132 limited. The type of log is a choice that can be augmented.";
1133 input {
1134 uses log-identifier;
1135 list log-selector {
1136 description
1137 "Only log entries which meet all the selection criteria
1138 provided are to be returned by the RPC output.";
1139 leaf-list name {
1140 type string;
1141 description
1142 "Name of one or more unique TPMs on a device. If this
1143 object exists, a selection should pull only the objects
1144 related to these TPM(s). If it does not exist, all
1145 qualifying TPMs that are 'hardware-based' equals true
1146 on the device are selected. When this selection
1147 criteria is provided, it will be considered as a logical
1148 AND with any other selection criteria provided.";
1149 }
1150 choice index-type {
1151 description
1152 "Last log entry received, log index number, or timestamp.";
1153 case last-entry {
1154 description
1155 "The last entry of the log already retrieved.";
1156 leaf last-entry-value {
1157 type binary;
1158 description
1159 "Content of a log event which matches 1:1 with a
1160 unique event record contained within the log. Log
1161 entries after this will be passed to the
1162 requester. Note: if log entry values are not unique,
1163 this MUST return an error.";
1164 }
1165 }
1166 case index {
1167 description
1168 "Numeric index of the last log entry retrieved, or
1169 zero.";
1170 leaf last-index-number {
1171 type uint64;
1172 description
1173 "The last numeric index number of a log entry.
1174 Zero means to start at the beginning of the log.
1175 Entries after this will be passed to the
1176 requester.";
1177 }
1179 }
1180 case timestamp {
1181 leaf timestamp {
1182 type yang:date-and-time;
1183 description
1184 "Timestamp from which to start the extraction. The
1185 next log entry after this timestamp is to
1186 be sent.";
1187 }
1188 description
1189 "Timestamp from which to start the extraction.";
1190 }
1191 }
1192 leaf log-entry-quantity {
1193 type uint16;
1194 description
1195 "The number of log entries to be returned. If omitted, it
1196 means all of them.";
1197 }
1198 }
1199 }
1200 output {
1201 container system-event-logs {
1202 description
1203 "The requested data of the measurement event logs";
1204 list node-data {
1205 unique "name";
1206 description
1207 "Event logs of a node in a distributed system
1208 identified by the node name";
1209 uses tpm-name;
1210 uses node-uptime;
1211 container log-result {
1212 description
1213 "The requested entries of the corresponding log.";
1214 uses event-logs;
1215 }
1216 }
1217 }
1218 }
1219 }
1221 /**************************************/
1222 /* Config & Oper accessible nodes */
1223 /**************************************/
1225 container rats-support-structures {
1226 description
1227 "The datastore definition enabling verifiers or relying
1228 parties to discover the information necessary to use the
1229 remote attestation RPCs appropriately.";
1230 container compute-nodes {
1231 if-feature "tpm:mtpm";
1232 description
1233 "Holds the set of device subsystems/components in this
1234 composite device that support TPM operations.";
1235 list compute-node {
1236 key "node-id";
1237 unique "node-name";
1238 config false;
1239 min-elements 2;
1240 description
1241 "A component within this composite device which
1242 supports TPM operations.";
1243 leaf node-id {
1244 type string;
1245 description
1246 "ID of the compute node, such as Board Serial Number.";
1247 }
1248 leaf node-physical-index {
1249 if-feature "hw:entity-mib";
1250 type int32 {
1251 range "1..2147483647";
1252 }
1253 config false;
1254 description
1255 "The entPhysicalIndex for the compute node.";
1256 reference
1257 "RFC 6933: Entity MIB (Version 4) - entPhysicalIndex";
1258 }
1259 leaf node-name {
1260 type string;
1261 description
1262 "Name of the compute node.";
1263 }
1264 leaf node-location {
1265 type string;
1266 description
1267 "Location of the compute node, such as slot number.";
1268 }
1269 }
1270 }
1271 container tpms {
1272 description
1273 "Holds the set of TPMs within an Attester.";
1274 list tpm {
1275 key "name";
1276 unique "path";
1277 description
1278 "A list of TPMs in this composite device that RATS
1279 can be conducted with.";
1280 uses tpm-name;
1281 leaf hardware-based {
1282 type boolean;
1283 config false;
1284 mandatory true;
1285 description
1286 "System generated indication of whether this is a
1287 hardware based TPM.";
1288 }
1289 leaf physical-index {
1290 if-feature "hw:entity-mib";
1291 type int32 {
1292 range "1..2147483647";
1293 }
1294 config false;
1295 description
1296 "The entPhysicalIndex for the TPM.";
1297 reference
1298 "RFC 6933: Entity MIB (Version 4) - entPhysicalIndex";
1299 }
1300 leaf path {
1301 type string;
1302 config false;
1303 description
1304 "Device path to a unique TPM on a device. This can change
1305 across reboots.";
1306 }
1307 leaf compute-node {
1308 if-feature "tpm:mtpm";
1309 type compute-node-ref;
1310 config false;
1311 mandatory true;
1312 description
1313 "Indicates the compute node measured by this TPM.";
1314 }
1315 leaf manufacturer {
1316 type string;
1317 config false;
1318 description
1319 "TPM manufacturer name.";
1320 }
1321 leaf firmware-version {
1322 type identityref {
1323 base taa:cryptoprocessor;
1324 }
1325 mandatory true;
1326 description
1327 "Identifies the cryptoprocessor API set supported. This
1328 is automatically configured by the device and should not
1329 be changed.";
1330 }
1331 uses tpm12-hash-algo {
1332 when "derived-from-or-self(firmware-version, 'taa:tpm12')";
1333 refine "tpm12-hash-algo" {
1334 description
1335 "The hash algorithm overwrites the default used for PCRs
1336 on this TPM1.2 compliant cryptoprocessor.";
1337 }
1338 }
1339 leaf-list tpm12-pcrs {
1340 when
1341 "derived-from-or-self(../firmware-version, 'taa:tpm12')";
1342 type pcr;
1343 description
1344 "The PCRs which may be extracted from this TPM1.2
1345 compliant cryptoprocessor.";
1346 }
1347 list tpm20-pcr-bank {
1348 when
1349 "derived-from-or-self(../firmware-version, 'taa:tpm20')";
1350 key "tpm20-hash-algo";
1351 description
1352 "Specifies the list of PCRs that may be extracted for
1353 a specific Hash Algorithm on this TPM2 compliant
1354 cryptoprocessor. A bank is a set of PCRs which are
1355 extended using a particular hash algorithm.";
1356 reference
1357 "TPM2.0-Structures:
1358 https://www.trustedcomputinggroup.org/wp-content/uploads/
1359 TPM-Rev-2.0-Part-2-Structures-01.38.pdf Section 10.9.7";
1360 leaf tpm20-hash-algo {
1361 type identityref {
1362 base taa:hash;
1363 }
1364 must '/tpm:rats-support-structures'
1365 + '/tpm:attester-supported-algos'
1366 + '/tpm:tpm20-hash' {
1367 error-message "This platform does not support tpm20-hash-algo";
1368 }
1369 description
1370 "The hash scheme actively being used to hash a
1371 one or more TPM2.0 PCRs.";
1372 }
1373 leaf-list pcr-index {
1374 type tpm:pcr;
1375 description
1376 "Defines what TPM2 PCRs are available to be extracted.";
1377 }
1378 }
1379 leaf status {
1380 type enumeration {
1381 enum operational {
1382 value 0;
1383 description
1384 "The TPM currently is running normally and
1385 is ready to accept and process TPM quotes.";
1386 reference
1387 "TPM2.0-Arch:
1388 https://trustedcomputinggroup.org/wp-content/uploads/
1389 TCG_TPM2_r1p59_Part1_Architecture_pub.pdf
1390 Section 12";
1391 }
1392 enum non-operational {
1393 value 1;
1394 description
1395 "TPM is in a state such as startup or shutdown which
1396 precludes the processing of TPM quotes.";
1397 }
1398 }
1399 config false;
1400 mandatory true;
1401 description
1402 "TPM chip self-test status.";
1403 }
1404 container certificates {
1405 description
1406 "The TPM's certificates, including EK certificates
1407 and Attestation Key certificates.";
1408 list certificate {
1409 key "name";
1410 description
1411 "Three types of certificates can be accessed via
1412 this statement, including Initial Attestation
1413 Key Certificate, Local Attestation Key Certificate or
1414 Endorsement Key Certificate.";
1415 leaf name {
1416 type string;
1417 description
1418 "An arbitrary name uniquely identifying a certificate
1419 associated within key within a TPM.";
1420 }
1421 leaf keystore-ref {
1422 if-feature "ks:asymmetric-keys";
1423 type leafref {
1424 path "/ks:keystore/ks:asymmetric-keys/ks:asymmetric-key"
1425 + "/ks:name";
1426 }
1427 description
1428 "A reference to a specific certificate of an
1429 asymmetric key in the Keystore.";
1430 }
1431 leaf type {
1432 type enumeration {
1433 enum endorsement-certificate {
1434 value 0;
1435 description
1436 "Endorsement Key (EK) Certificate type.";
1437 reference
1438 "TPM2.0-Key:
1439 https://trustedcomputinggroup.org/wp-content/
1440 uploads/TPM-2p0-Keys-for-Device-Identity-
1441 and-Attestation_v1_r12_pub10082021.pdf
1442 Section 3.11";
1443 }
1444 enum initial-attestation-certificate {
1445 value 1;
1446 description
1447 "Initial Attestation key (IAK) Certificate type.";
1448 reference
1449 "TPM2.0-Key:
1450 https://trustedcomputinggroup.org/wp-content/
1451 uploads/TPM-2p0-Keys-for-Device-Identity-
1452 and-Attestation_v1_r12_pub10082021.pdf
1453 Section 3.2";
1454 }
1455 enum local-attestation-certificate {
1456 value 2;
1457 description
1458 "Local Attestation Key (LAK) Certificate type.";
1459 reference
1460 "TPM2.0-Key:
1461 https://trustedcomputinggroup.org/wp-content/
1462 uploads/TPM-2p0-Keys-for-Device-Identity-
1463 and-Attestation_v1_r12_pub10082021.pdf
1464 Section 3.2";
1465 }
1466 }
1467 description
1468 "Function supported by this certificate from within the
1469 TPM.";
1470 }
1471 }
1472 }
1473 }
1474 }
1475 container attester-supported-algos {
1476 description
1477 "Identifies which TPM algorithms are available for use on an
1478 attesting platform.";
1479 leaf-list tpm12-asymmetric-signing {
1480 when "../../tpm:tpms"
1481 + "/tpm:tpm[tpm:firmware-version='taa:tpm12']";
1482 type identityref {
1483 base taa:asymmetric;
1484 }
1485 description
1486 "Platform Supported TPM12 asymmetric algorithms.";
1487 }
1488 leaf-list tpm12-hash {
1489 when "../../tpm:tpms"
1490 + "/tpm:tpm[tpm:firmware-version='taa:tpm12']";
1491 type identityref {
1492 base taa:hash;
1493 }
1494 description
1495 "Platform supported TPM12 hash algorithms.";
1496 }
1497 leaf-list tpm20-asymmetric-signing {
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 when "../../tpm:tpms"
1508 + "/tpm:tpm[tpm:firmware-version='taa:tpm20']";
1509 type identityref {
1510 base taa:hash;
1511 }
1512 description
1513 "Platform supported TPM20 hash algorithms.";
1514 }
1516 }
1517 }
1518 }
1519
1521 Figure 1
1523 2.1.2. 'ietf-tcg-algs'
1525 This document has encoded the TCG Algorithm definitions of
1526 [TCG-Algos], revision 1.32. By including this full table as a
1527 separate YANG file within this document, it is possible for other
1528 YANG models to leverage the contents of this model. Specific
1529 references to [RFC2104], [RFC8017], [ISO-IEC-9797-1],
1530 [ISO-IEC-9797-2], [ISO-IEC-10116], [ISO-IEC-10118-3],
1531 [ISO-IEC-14888-3], [ISO-IEC-15946-1], [ISO-IEC-18033-3],
1532 [IEEE-Std-1363-2000], [IEEE-Std-1363a-2004], [NIST-PUB-FIPS-202],
1533 [NIST-SP800-38C], [NIST-SP800-38D], [NIST-SP800-38F],
1534 [NIST-SP800-56A], [NIST-SP800-108], [bios-log], as well as Appendix A
1535 and Appendix B exist within the YANG Model.
1537 2.1.2.1. Features
1539 There are two types of features supported: 'TPM12' and 'TPM20'.
1540 Support for either of these features indicates that a cryptoprocessor
1541 supporting the corresponding type of TCG TPM API is present on an
1542 Attester. Most commonly, only one type of cryptoprocessor will be
1543 available on an Attester.
1545 2.1.2.2. Identities
1547 There are three types of identities in this model:
1549 1. Cryptographic functions supported by a TPM algorithm; these
1550 include: 'asymmetric', 'symmetric', 'hash', 'signing',
1551 'anonymous_signing', 'encryption_mode', 'method', and
1552 'object_type'. The definitions of each of these are in Table 2
1553 of [TCG-Algos].
1555 2. API specifications for TPM types: 'tpm12' and 'tpm20'
1557 3. Specific algorithm types: Each algorithm type defines what
1558 cryptographic functions may be supported, and on which type of
1559 API specification. It is not required that an implementation of
1560 a specific TPM will support all algorithm types. The contents of
1561 each specific algorithm mirrors what is in Table 3 of
1562 [TCG-Algos].
1564 2.1.2.3. YANG Module
1566 file "ietf-tcg-algs@2022-03-23.yang"
1567 module ietf-tcg-algs {
1568 yang-version 1.1;
1569 namespace "urn:ietf:params:xml:ns:yang:ietf-tcg-algs";
1570 prefix taa;
1572 organization
1573 "IETF RATS (Remote ATtestation procedureS) Working Group";
1574 contact
1575 "WG Web:
1576 WG List:
1577 Author: Eric Voit ";
1578 description
1579 "This module defines identities for asymmetric algorithms.
1581 Copyright (c) 2022 IETF Trust and the persons identified as
1582 authors of the code. All rights reserved.
1583 Redistribution and use in source and binary forms, with
1584 or without modification, is permitted pursuant to, and
1585 subject to the license terms contained in, the Revised
1586 BSD License set forth in Section 4.c of the IETF Trust's
1587 Legal Provisions Relating to IETF Documents
1588 (https://trustee.ietf.org/license-info).
1590 This version of this YANG module is part of RFC XXXX
1591 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC itself
1592 for full legal notices.
1594 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL',
1595 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED',
1596 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document
1597 are to be interpreted as described in BCP 14 (RFC 2119)
1598 (RFC 8174) when, and only when, they appear in all
1599 capitals, as shown here.";
1601 revision 2022-03-23 {
1602 description
1603 "Initial version";
1604 reference
1605 "RFC XXXX: A YANG Data Model for Challenge-Response-based Remote
1606 Attestation Procedures using TPMs";
1607 }
1609 /*****************/
1610 /* Features */
1611 /*****************/
1612 feature tpm12 {
1613 description
1614 "This feature indicates algorithm support for the TPM 1.2 API
1615 as per Section 4.8 of TPM1.2-Structures:
1616 TPM Main Part 2 TPM Structures
1617 https://trustedcomputinggroup.org/wp-content/uploads/TPM-
1618 Main-Part-2-TPM-Structures_v1.2_rev116_01032011.pdf";
1619 }
1621 feature tpm20 {
1622 description
1623 "This feature indicates algorithm support for the TPM 2.0 API
1624 as per Section 11.4 of Trusted Platform Module Library
1625 Part 1: Architecture. See TPM2.0-Arch:
1626 https://trustedcomputinggroup.org/wp-content/uploads/
1627 TCG_TPM2_r1p59_Part1_Architecture_pub.pdf";
1628 }
1630 /*****************/
1631 /* Identities */
1632 /*****************/
1634 identity asymmetric {
1635 description
1636 "A TCG recognized asymmetric algorithm with a public and
1637 private key.";
1638 reference
1639 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 2,
1640 https://trustedcomputinggroup.org/resource/
1641 tcg-algorithm-registry/TCG-_Algorithm_Registry_r1p32_pub";
1642 }
1644 identity symmetric {
1645 description
1646 "A TCG recognized symmetric algorithm with only a private key.";
1647 reference
1648 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 2";
1649 }
1651 identity hash {
1652 description
1653 "A TCG recognized hash algorithm that compresses input data to
1654 a digest value or indicates a method that uses a hash.";
1655 reference
1656 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 2";
1657 }
1659 identity signing {
1660 description
1661 "A TCG recognized signing algorithm";
1662 reference
1663 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 2";
1664 }
1666 identity anonymous_signing {
1667 description
1668 "A TCG recognized anonymous signing algorithm.";
1669 reference
1670 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 2";
1671 }
1673 identity encryption_mode {
1674 description
1675 "A TCG recognized encryption mode.";
1676 reference
1677 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 2";
1678 }
1680 identity method {
1681 description
1682 "A TCG recognized method such as a mask generation function.";
1683 reference
1684 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 2";
1685 }
1687 identity object_type {
1688 description
1689 "A TCG recognized object type.";
1690 reference
1691 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 2";
1692 }
1694 identity cryptoprocessor {
1695 description
1696 "Base identity identifying a crytoprocessor.";
1697 }
1699 identity tpm12 {
1700 if-feature "tpm12";
1701 base cryptoprocessor;
1702 description
1703 "Supportable by a TPM1.2.";
1704 reference
1705 "TPM1.2-Structures:
1706 https://trustedcomputinggroup.org/wp-content/uploads/
1707 TPM-Main-Part-2-TPM-Structures_v1.2_rev116_01032011.pdf
1708 TPM_ALGORITHM_ID values, Section 4.8";
1709 }
1711 identity tpm20 {
1712 if-feature "tpm20";
1713 base cryptoprocessor;
1714 description
1715 "Supportable by a TPM2.";
1716 reference
1717 "TPM2.0-Structures:
1718 https://trustedcomputinggroup.org/wp-content/uploads/
1719 TPM-Rev-2.0-Part-2-Structures-01.38.pdf";
1720 }
1722 identity TPM_ALG_RSA {
1723 if-feature "tpm12 or tpm20";
1724 base tpm12;
1725 base tpm20;
1726 base asymmetric;
1727 base object_type;
1728 description
1729 "RSA algorithm";
1730 reference
1731 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
1732 RFC 8017. ALG_ID: 0x0001";
1733 }
1735 identity TPM_ALG_TDES {
1736 if-feature "tpm12";
1737 base tpm12;
1738 base symmetric;
1739 description
1740 "Block cipher with various key sizes (Triple Data Encryption
1741 Algorithm, commonly called Triple Data Encryption Standard)
1742 Note: was banned in TPM1.2 v94";
1743 reference
1744 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
1745 ISO/IEC 18033-3. ALG_ID: 0x0003";
1746 }
1748 identity TPM_ALG_SHA1 {
1749 if-feature "tpm12 or tpm20";
1750 base hash;
1751 base tpm12;
1752 base tpm20;
1753 description
1754 "SHA1 algorithm - Deprecated due to insufficient cryptographic
1755 protection. However, it is still useful for hash algorithms
1756 where protection is not required.";
1757 reference
1758 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
1759 ISO/IEC 10118-3. ALG_ID: 0x0004";
1760 }
1762 identity TPM_ALG_HMAC {
1763 if-feature "tpm12 or tpm20";
1764 base tpm12;
1765 base tpm20;
1766 base hash;
1767 base signing;
1768 description
1769 "Hash Message Authentication Code (HMAC) algorithm";
1770 reference
1771 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3,
1772 ISO/IEC 9797-2 and RFC2104. ALG_ID: 0x0005";
1773 }
1775 identity TPM_ALG_AES {
1776 if-feature "tpm12";
1777 base tpm12;
1778 base symmetric;
1779 description
1780 "The AES algorithm with various key sizes";
1781 reference
1782 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3,
1783 ISO/IEC 18033-3. ALG_ID: 0x0006";
1784 }
1786 identity TPM_ALG_MGF1 {
1787 if-feature "tpm20";
1788 base tpm20;
1789 base hash;
1790 base method;
1791 description
1792 "hash-based mask-generation function";
1793 reference
1794 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3,
1795 IEEE Std 1363-2000 and IEEE Std 1363a-2004.
1796 ALG_ID: 0x0007";
1797 }
1799 identity TPM_ALG_KEYEDHASH {
1800 if-feature "tpm20";
1801 base tpm20;
1802 base hash;
1803 base object_type;
1804 description
1805 "An encryption or signing algorithm using a keyed hash. These
1806 may use XOR for encryption or an HMAC for signing and may
1807 also refer to a data object that is neither signing nor
1808 encrypting.";
1809 reference
1810 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3,
1811 ALG_ID: 0x0008";
1812 }
1814 identity TPM_ALG_XOR {
1815 if-feature "tpm12 or tpm20";
1816 base tpm12;
1817 base tpm20;
1818 base hash;
1819 base symmetric;
1820 description
1821 "The XOR encryption algorithm.";
1822 reference
1823 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3.
1824 ALG_ID: 0x000A";
1825 }
1827 identity TPM_ALG_SHA256 {
1828 if-feature "tpm20";
1829 base tpm20;
1830 base hash;
1831 description
1832 "The SHA 256 algorithm";
1833 reference
1834 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
1835 ISO/IEC 10118-3. ALG_ID: 0x000B";
1836 }
1838 identity TPM_ALG_SHA384 {
1839 if-feature "tpm20";
1840 base tpm20;
1841 base hash;
1842 description
1843 "The SHA 384 algorithm";
1844 reference
1845 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
1846 ISO/IEC 10118-3. ALG_ID: 0x000C";
1847 }
1849 identity TPM_ALG_SHA512 {
1850 if-feature "tpm20";
1851 base tpm20;
1852 base hash;
1853 description
1854 "The SHA 512 algorithm";
1855 reference
1856 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
1857 ISO/IEC 10118-3. ALG_ID: 0x000D";
1858 }
1860 identity TPM_ALG_NULL {
1861 if-feature "tpm20";
1862 base tpm20;
1863 description
1864 "NULL algorithm";
1865 reference
1866 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3.
1867 ALG_ID: 0x0010";
1868 }
1870 identity TPM_ALG_SM3_256 {
1871 if-feature "tpm20";
1872 base tpm20;
1873 base hash;
1874 description
1875 "The SM3 hash algorithm.";
1876 reference
1877 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
1878 ISO/IEC 10118-3:2018. ALG_ID: 0x0012";
1879 }
1881 identity TPM_ALG_SM4 {
1882 if-feature "tpm20";
1883 base tpm20;
1884 base symmetric;
1885 description
1886 "SM4 symmetric block cipher";
1887 reference
1888 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3.
1889 ALG_ID: 0x0013";
1890 }
1892 identity TPM_ALG_RSASSA {
1893 if-feature "tpm20";
1894 base tpm20;
1895 base asymmetric;
1896 base signing;
1897 description
1898 "RFC 8017 Signature algorithm defined in section 8.2
1899 (RSASSAPKCS1-v1_5)";
1901 reference
1902 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
1903 RFC 8017. ALG_ID: 0x0014";
1904 }
1906 identity TPM_ALG_RSAES {
1907 if-feature "tpm20";
1908 base tpm20;
1909 base asymmetric;
1910 base encryption_mode;
1911 description
1912 "RFC 8017 Signature algorithm defined in section 7.2
1913 (RSAES-PKCS1-v1_5)";
1914 reference
1915 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
1916 RFC 8017. ALG_ID: 0x0015";
1917 }
1919 identity TPM_ALG_RSAPSS {
1920 if-feature "tpm20";
1921 base tpm20;
1922 base asymmetric;
1923 base signing;
1924 description
1925 "Padding algorithm defined in section 8.1 (RSASSA PSS)";
1926 reference
1927 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
1928 RFC 8017. ALG_ID: 0x0016";
1929 }
1931 identity TPM_ALG_OAEP {
1932 if-feature "tpm20";
1933 base tpm20;
1934 base asymmetric;
1935 base encryption_mode;
1936 description
1937 "Padding algorithm defined in section 7.1 (RSASSA OAEP)";
1938 reference
1939 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
1940 RFC 8017. ALG_ID: 0x0017";
1941 }
1943 identity TPM_ALG_ECDSA {
1944 if-feature "tpm20";
1945 base tpm20;
1946 base asymmetric;
1947 base signing;
1948 description
1949 "Signature algorithm using elliptic curve cryptography (ECC)";
1950 reference
1951 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
1952 ISO/IEC 14888-3. ALG_ID: 0x0018";
1953 }
1955 identity TPM_ALG_ECDH {
1956 if-feature "tpm20";
1957 base tpm20;
1958 base asymmetric;
1959 base method;
1960 description
1961 "Secret sharing using ECC";
1962 reference
1963 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
1964 NIST SP800-56A. ALG_ID: 0x0019";
1965 }
1967 identity TPM_ALG_ECDAA {
1968 if-feature "tpm20";
1969 base tpm20;
1970 base asymmetric;
1971 base signing;
1972 base anonymous_signing;
1973 description
1974 "Elliptic-curve based anonymous signing scheme";
1975 reference
1976 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
1977 TCG TPM 2.0 library specification. ALG_ID: 0x001A";
1978 }
1980 identity TPM_ALG_SM2 {
1981 if-feature "tpm20";
1982 base tpm20;
1983 base asymmetric;
1984 base signing;
1985 base encryption_mode;
1986 base method;
1987 description
1988 "SM2 - depending on context, either an elliptic-curve based,
1989 signature algorithm, an encryption scheme, or a key exchange
1990 protocol";
1991 reference
1992 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3.
1993 ALG_ID: 0x001B";
1994 }
1996 identity TPM_ALG_ECSCHNORR {
1997 if-feature "tpm20";
1998 base tpm20;
1999 base asymmetric;
2000 base signing;
2001 description
2002 "Elliptic-curve based Schnorr signature";
2003 reference
2004 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3.
2005 ALG_ID: 0x001C";
2006 }
2008 identity TPM_ALG_ECMQV {
2009 if-feature "tpm20";
2010 base tpm20;
2011 base asymmetric;
2012 base method;
2013 description
2014 "Two-phase elliptic-curve key";
2015 reference
2016 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2017 NIST SP800-56A. ALG_ID: 0x001D";
2018 }
2020 identity TPM_ALG_KDF1_SP800_56A {
2021 if-feature "tpm20";
2022 base tpm20;
2023 base hash;
2024 base method;
2025 description
2026 "Concatenation key derivation function";
2027 reference
2028 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2029 NIST SP800-56A (approved alternative1) section 5.8.1.
2030 ALG_ID: 0x0020";
2031 }
2033 identity TPM_ALG_KDF2 {
2034 if-feature "tpm20";
2035 base tpm20;
2036 base hash;
2037 base method;
2038 description
2039 "Key derivation function";
2040 reference
2041 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2042 IEEE 1363a-2004 KDF2 section 13.2. ALG_ID: 0x0021";
2043 }
2044 identity TPM_ALG_KDF1_SP800_108 {
2045 base TPM_ALG_KDF2;
2046 description
2047 "A key derivation method";
2048 reference
2049 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2050 NIST SP800-108 - Section 5.1 KDF. ALG_ID: 0x0022";
2051 }
2053 identity TPM_ALG_ECC {
2054 if-feature "tpm20";
2055 base tpm20;
2056 base asymmetric;
2057 base object_type;
2058 description
2059 "Prime field ECC";
2060 reference
2061 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2062 ISO/IEC 15946-1. ALG_ID: 0x0023";
2063 }
2065 identity TPM_ALG_SYMCIPHER {
2066 if-feature "tpm20";
2067 base tpm20;
2068 base symmetric;
2069 base object_type;
2070 description
2071 "Object type for a symmetric block cipher";
2072 reference
2073 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2074 TCG TPM 2.0 library specification. ALG_ID: 0x0025";
2075 }
2077 identity TPM_ALG_CAMELLIA {
2078 if-feature "tpm20";
2079 base tpm20;
2080 base symmetric;
2081 description
2082 "The Camellia algorithm";
2083 reference
2084 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2085 ISO/IEC 18033-3. ALG_ID: 0x0026";
2086 }
2088 identity TPM_ALG_SHA3_256 {
2089 if-feature "tpm20";
2090 base tpm20;
2091 base hash;
2092 description
2093 "ISO/IEC 10118-3 - the SHA 256 algorithm";
2094 reference
2095 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2096 NIST PUB FIPS 202. ALG_ID: 0x0027";
2097 }
2099 identity TPM_ALG_SHA3_384 {
2100 if-feature "tpm20";
2101 base tpm20;
2102 base hash;
2103 description
2104 "The SHA 384 algorithm";
2105 reference
2106 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2107 NIST PUB FIPS 202. ALG_ID: 0x0028";
2108 }
2110 identity TPM_ALG_SHA3_512 {
2111 if-feature "tpm20";
2112 base tpm20;
2113 base hash;
2114 description
2115 "The SHA 512 algorithm";
2116 reference
2117 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2118 NIST PUB FIPS 202. ALG_ID: 0x0029";
2119 }
2121 identity TPM_ALG_CMAC {
2122 if-feature "tpm20";
2123 base tpm20;
2124 base symmetric;
2125 base signing;
2126 description
2127 "block Cipher-based Message Authentication Code (CMAC)";
2128 reference
2129 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2130 ISO/IEC 9797-1:2011 Algorithm 5. ALG_ID: 0x003F";
2131 }
2133 identity TPM_ALG_CTR {
2134 if-feature "tpm20";
2135 base tpm20;
2136 base symmetric;
2137 base encryption_mode;
2138 description
2139 "Counter mode";
2141 reference
2142 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2143 ISO/IEC 10116. ALG_ID: 0x0040";
2144 }
2146 identity TPM_ALG_OFB {
2147 base tpm20;
2148 base symmetric;
2149 base encryption_mode;
2150 description
2151 "Output Feedback mode";
2152 reference
2153 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2154 ISO/IEC 10116. ALG_ID: 0x0041";
2155 }
2157 identity TPM_ALG_CBC {
2158 if-feature "tpm20";
2159 base tpm20;
2160 base symmetric;
2161 base encryption_mode;
2162 description
2163 "Cipher Block Chaining mode";
2164 reference
2165 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2166 ISO/IEC 10116. ALG_ID: 0x0042";
2167 }
2169 identity TPM_ALG_CFB {
2170 if-feature "tpm20";
2171 base tpm20;
2172 base symmetric;
2173 base encryption_mode;
2174 description
2175 "Cipher Feedback mode";
2176 reference
2177 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2178 ISO/IEC 10116. ALG_ID: 0x0043";
2179 }
2181 identity TPM_ALG_ECB {
2182 if-feature "tpm20";
2183 base tpm20;
2184 base symmetric;
2185 base encryption_mode;
2186 description
2187 "Electronic Codebook mode";
2188 reference
2189 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2190 ISO/IEC 10116. ALG_ID: 0x0044";
2191 }
2193 identity TPM_ALG_CCM {
2194 if-feature "tpm20";
2195 base tpm20;
2196 base symmetric;
2197 base signing;
2198 base encryption_mode;
2199 description
2200 "Counter with Cipher Block Chaining-Message Authentication
2201 Code (CCM)";
2202 reference
2203 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2204 NIST SP800-38C. ALG_ID: 0x0050";
2205 }
2207 identity TPM_ALG_GCM {
2208 if-feature "tpm20";
2209 base tpm20;
2210 base symmetric;
2211 base signing;
2212 base encryption_mode;
2213 description
2214 "Galois/Counter Mode (GCM)";
2215 reference
2216 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2217 NIST SP800-38D. ALG_ID: 0x0051";
2218 }
2220 identity TPM_ALG_KW {
2221 if-feature "tpm20";
2222 base tpm20;
2223 base symmetric;
2224 base signing;
2225 base encryption_mode;
2226 description
2227 "AES Key Wrap (KW)";
2228 reference
2229 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2230 NIST SP800-38F. ALG_ID: 0x0052";
2231 }
2233 identity TPM_ALG_KWP {
2234 if-feature "tpm20";
2235 base tpm20;
2236 base symmetric;
2237 base signing;
2238 base encryption_mode;
2239 description
2240 "AES Key Wrap with Padding (KWP)";
2241 reference
2242 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2243 NIST SP800-38F. ALG_ID: 0x0053";
2244 }
2246 identity TPM_ALG_EAX {
2247 if-feature "tpm20";
2248 base tpm20;
2249 base symmetric;
2250 base signing;
2251 base encryption_mode;
2252 description
2253 "Authenticated-Encryption Mode";
2254 reference
2255 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2256 NIST SP800-38F. ALG_ID: 0x0054";
2257 }
2259 identity TPM_ALG_EDDSA {
2260 if-feature "tpm20";
2261 base tpm20;
2262 base asymmetric;
2263 base signing;
2264 description
2265 "Edwards-curve Digital Signature Algorithm (PureEdDSA)";
2266 reference
2267 "TCG-Algos:TCG Algorithm Registry Rev1.32 Table 3 and
2268 RFC 8032. ALG_ID: 0x0060";
2269 }
2270 }
2271
2273 Note that not all cryptographic functions are required for use by
2274 ietf-tpm-remote-attestation.yang. However the full definition of
2275 Table 3 of [TCG-Algos] will allow use by additional YANG
2276 specifications.
2278 3. IANA Considerations
2280 This document registers the following namespace URIs in the
2281 [xml-registry] as per [RFC3688]:
2283 URI: urn:ietf:params:xml:ns:yang:ietf-tpm-remote-attestation
2284 Registrant Contact: The IESG.
2286 XML: N/A; the requested URI is an XML namespace.
2288 URI: urn:ietf:params:xml:ns:yang:ietf-tcg-algs
2290 Registrant Contact: The IESG.
2292 XML: N/A; the requested URI is an XML namespace.
2294 This document registers the following YANG modules in the registry
2295 [yang-parameters] as per Section 14 of [RFC6020]:
2297 Name: ietf-tpm-remote-attestation
2299 Namespace: urn:ietf:params:xml:ns:yang:ietf-tpm-remote-
2300 attestation
2302 Prefix: tpm
2304 Reference: draft-ietf-rats-yang-tpm-charra (RFC form)
2306 Name: ietf-tcg-algs
2308 Namespace: urn:ietf:params:xml:ns:yang:ietf-tcg-algs
2310 Prefix: taa
2312 Reference: draft-ietf-rats-yang-tpm-charra (RFC form)
2314 4. Security Considerations
2316 The YANG module ietf-tpm-remote-attestation.yang specified in this
2317 document defines a schema for data that is designed to be accessed
2318 via network management protocols such as NETCONF [RFC6241] or
2319 RESTCONF [RFC8040]. The lowest NETCONF layer is the secure transport
2320 layer, and the mandatory-to-implement secure transport is Secure
2321 Shell (SSH) [RFC6242]. The lowest RESTCONF layer is HTTPS, and the
2322 mandatory-to-implement secure transport is TLS [RFC8446].
2324 There are a number of data nodes defined in this YANG module that are
2325 writable/creatable/deletable (i.e., _config true_, which is the
2326 default). These data nodes may be considered sensitive or vulnerable
2327 in some network environments. Write operations (e.g., _edit-config_)
2328 to these data nodes without proper protection can have a negative
2329 effect on network operations. These are the subtrees and data nodes
2330 as well as their sensitivity/vulnerability:
2332 Container '/rats-support-structures/attester-supported-algos': 'tpm1
2333 2-asymmetric-signing', 'tpm12-hash', 'tpm20-asymmetric-signing',
2334 and 'tpm20-hash'. All could be populated with algorithms that are
2335 not supported by the underlying physical TPM installed by the
2336 equipment vendor. A vendor should restrict the ability to
2337 configure unsupported algorithms.
2339 Container: '/rats-support-structures/tpms': 'name': Although shown
2340 as 'rw', it is system generated. Therefore, it should not be
2341 possible for an operator to add or remove a TPM from the
2342 configuration.
2344 'tpm20-pcr-bank': It is possible to configure PCRs for extraction
2345 which are not being extended by system software. This could
2346 unnecessarily use TPM resources.
2348 'certificates': It is possible to provision a certificate which
2349 does not correspond to an Attestation Identity Key (AIK) within
2350 the TPM 1.2, or an Attestation Key (AK) within the TPM 2.0
2351 respectively. In such a case, calls to an RPC requesting this
2352 specific certificate could result in either no response or a
2353 response for an unexpected TPM.
2355 RPC 'tpm12-challenge-response-attestation': The receiver of the RPC
2356 response must verify that the certificate is for an active AIK,
2357 i.e., the certificate has been confirmed by a third party as being
2358 able to support Attestation on the targeted TPM 1.2.
2360 RPC 'tpm20-challenge-response-attestation': The receiver of the RPC
2361 response must verify that the certificate is for an active AK,
2362 i.e., the private key confirmation of the quote signature within
2363 the RPC response has been confirmed by a third party to belong to
2364 an entity legitimately able to perform Attestation on the targeted
2365 TPM 2.0.
2367 RPC 'log-retrieval': Requesting a large volume of logs from the
2368 attester could require significant system resources and create a
2369 denial of service.
2371 Information collected through the RPCs above could reveal that
2372 specific versions of software and configurations of endpoints that
2373 could identify vulnerabilities on those systems. Therefore, RPCs
2374 should be protected by NACM [RFC8341] with a default setting of deny-
2375 all to limit the extraction of attestation data by only authorized
2376 Verifiers.
2378 For the YANG module ietf-tcg-algs.yang, please use care when
2379 selecting specific algorithms. The introductory section of
2380 [TCG-Algos] highlights that some algorithms should be considered
2381 legacy, and recommends implementers and adopters diligently evaluate
2382 available information such as governmental, industrial, and academic
2383 research before selecting an algorithm for use.
2385 5. References
2387 5.1. Normative References
2389 [bios-log] "TCG PC Client Platform Firmware Profile Specification,
2390 Section 9.4.5.2", n.d.,
2391 .
2395 [BIOS-Log-Event-Type]
2396 "TCG PC Client Platform Firmware Profile Specification",
2397 n.d., .
2400 [cel] "Canonical Event Log Format, Section 4.3", n.d.,
2401 .
2404 [I-D.ietf-netconf-keystore]
2405 Watsen, K., "A YANG Data Model for a Keystore", Work in
2406 Progress, Internet-Draft, draft-ietf-netconf-keystore-24,
2407 7 March 2022, .
2410 [I-D.ietf-rats-architecture]
2411 Birkholz, H., Thaler, D., Richardson, M., Smith, N., and
2412 W. Pan, "Remote Attestation Procedures Architecture", Work
2413 in Progress, Internet-Draft, draft-ietf-rats-architecture-
2414 15, 8 February 2022, .
2417 [I-D.ietf-rats-tpm-based-network-device-attest]
2418 Fedorkow, G., Voit, E., and J. Fitzgerald-McKay, "TPM-
2419 based Network Device Remote Integrity Verification", Work
2420 in Progress, Internet-Draft, draft-ietf-rats-tpm-based-
2421 network-device-attest-14, 22 March 2022,
2422 .
2425 [IEEE-Std-1363-2000]
2426 "IEEE 1363-2000 - IEEE Standard Specifications for Public-
2427 Key Cryptography", n.d.,
2428 .
2430 [IEEE-Std-1363a-2004]
2431 "1363a-2004 - IEEE Standard Specifications for Public-Key
2432 Cryptography - Amendment 1: Additional Techniques", n.d.,
2433 .
2435 [ISO-IEC-10116]
2436 "ISO/IEC 10116:2017 - Information technology", n.d.,
2437 .
2439 [ISO-IEC-10118-3]
2440 "Dedicated hash-functions - ISO/IEC 10118-3:2018", n.d.,
2441 .
2443 [ISO-IEC-14888-3]
2444 "ISO/IEC 14888-3:2018 - Digital signatures with appendix",
2445 n.d., .
2447 [ISO-IEC-15946-1]
2448 "ISO/IEC 15946-1:2016 - Information technology", n.d.,
2449 .
2451 [ISO-IEC-18033-3]
2452 "ISO/IEC 18033-3:2010 - Encryption algorithms", n.d.,
2453 .
2455 [ISO-IEC-9797-1]
2456 "Message Authentication Codes (MACs) - ISO/IEC
2457 9797-1:2011", n.d.,
2458 .
2460 [ISO-IEC-9797-2]
2461 "Message Authentication Codes (MACs) - ISO/IEC
2462 9797-2:2011", n.d.,
2463 .
2465 [NIST-PUB-FIPS-202]
2466 "SHA-3 Standard: Permutation-Based Hash and Extendable-
2467 Output Functions", n.d.,
2468 .
2471 [NIST-SP800-108]
2472 "Recommendation for Key Derivation Using Pseudorandom
2473 Functions", n.d.,
2474 .
2477 [NIST-SP800-38C]
2478 "Recommendation for Block Cipher Modes of Operation: the
2479 CCM Mode for Authentication and Confidentiality", n.d.,
2480 .
2483 [NIST-SP800-38D]
2484 "Recommendation for Block Cipher Modes of Operation:
2485 Galois/Counter Mode (GCM) and GMAC", n.d.,
2486 .
2489 [NIST-SP800-38F]
2490 "Recommendation for Block Cipher Modes of Operation:
2491 Methods for Key Wrapping", n.d.,
2492 .
2495 [NIST-SP800-56A]
2496 "Recommendation for Pair-Wise Key-Establishment Schemes
2497 Using Discrete Logarithm Cryptography", n.d.,
2498 .
2501 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed-
2502 Hashing for Message Authentication", RFC 2104,
2503 DOI 10.17487/RFC2104, February 1997,
2504 .
2506 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
2507 Requirement Levels", BCP 14, RFC 2119,
2508 DOI 10.17487/RFC2119, March 1997,
2509 .
2511 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
2512 DOI 10.17487/RFC3688, January 2004,
2513 .
2515 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
2516 the Network Configuration Protocol (NETCONF)", RFC 6020,
2517 DOI 10.17487/RFC6020, October 2010,
2518 .
2520 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
2521 and A. Bierman, Ed., "Network Configuration Protocol
2522 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
2523 .
2525 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure
2526 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011,
2527 .
2529 [RFC6933] Bierman, A., Romascanu, D., Quittek, J., and M.
2530 Chandramouli, "Entity MIB (Version 4)", RFC 6933,
2531 DOI 10.17487/RFC6933, May 2013,
2532 .
2534 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types",
2535 RFC 6991, DOI 10.17487/RFC6991, July 2013,
2536 .
2538 [RFC8017] Moriarty, K., Ed., Kaliski, B., Jonsson, J., and A. Rusch,
2539 "PKCS #1: RSA Cryptography Specifications Version 2.2",
2540 RFC 8017, DOI 10.17487/RFC8017, November 2016,
2541 .
2543 [RFC8032] Josefsson, S. and I. Liusvaara, "Edwards-Curve Digital
2544 Signature Algorithm (EdDSA)", RFC 8032,
2545 DOI 10.17487/RFC8032, January 2017,
2546 .
2548 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
2549 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
2550 .
2552 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2553 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
2554 May 2017, .
2556 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration
2557 Access Control Model", STD 91, RFC 8341,
2558 DOI 10.17487/RFC8341, March 2018,
2559 .
2561 [RFC8348] Bierman, A., Bjorklund, M., Dong, J., and D. Romascanu, "A
2562 YANG Data Model for Hardware Management", RFC 8348,
2563 DOI 10.17487/RFC8348, March 2018,
2564 .
2566 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol
2567 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
2568 .
2570 [TCG-Algos]
2571 "TCG Algorithm Registry", n.d.,
2572 .
2575 [TPM1.2] TCG, ., "TPM 1.2 Main Specification", 2 October 2003,
2576 .
2579 [TPM1.2-Commands]
2580 "TPM Main Part 3 Commands", n.d.,
2581 .
2584 [TPM1.2-Structures]
2585 "TPM Main Part 2 TPM Structures", n.d.,
2586 .
2589 [TPM2.0] TCG, ., "TPM 2.0 Library Specification", 15 March 2013,
2590 .
2593 [TPM2.0-Arch]
2594 "Trusted Platform Module Library - Part 1: Architecture",
2595 n.d., .
2599 [TPM2.0-Key]
2600 TCG, ., "TPM 2.0 Keys for Device Identity and Attestation,
2601 Rev12", 8 October 2021,
2602 .
2606 [TPM2.0-Structures]
2607 "Trusted Platform Module Library - Part 2: Structures",
2608 n.d., .
2611 [UEFI-Secure-Boot]
2612 "Unified Extensible Firmware Interface (UEFI)
2613 Specification Version 2.9 (March 2021), Section 32.1
2614 (Secure Boot)", n.d.,
2615 .
2618 5.2. Informative References
2620 [I-D.ietf-rats-reference-interaction-models]
2621 Birkholz, H., Eckel, M., Pan, W., and E. Voit, "Reference
2622 Interaction Models for Remote Attestation Procedures",
2623 Work in Progress, Internet-Draft, draft-ietf-rats-
2624 reference-interaction-models-05, 26 January 2022,
2625 .
2628 [IMA-Kernel-Source]
2629 "Linux Integrity Measurement Architecture (IMA): Kernel
2630 Sourcecode", n.d., .
2634 [NIST-915121]
2635 "True Randomness Can't be Left to Chance: Why entropy is
2636 important for information security", n.d.,
2637 .
2640 [xml-registry]
2641 "IETF XML Registry", n.d.,
2642 .
2645 [yang-parameters]
2646 "YANG Parameters", n.d.,
2647 .
2650 Appendix A. Integrity Measurement Architecture (IMA)
2652 IMA extends the principles of Measured Boot [TPM2.0-Arch] and Secure
2653 Boot [UEFI-Secure-Boot] to the Linux operating system, applying it to
2654 operating system applications and files. IMA has been part of the
2655 Linux integrity subsystem of the Linux kernel since 2009 (kernel
2656 version 2.6.30). The IMA mechanism represented by the YANG module in
2657 this specification is rooted in the kernel version 5.16
2658 [IMA-Kernel-Source]. IMA enables the protection of system integrity
2659 by collecting (commonly referred to as measuring) and storing
2660 measurements (called Claims in the context of IETF RATS) of files
2661 before execution so that these measurements can be used later, at
2662 system runtime, in remote attestation procedures. IMA acts in
2663 support of the appraisal of Evidence (which includes measurement
2664 Claims) by leveraging reference integrity measurements stored in
2665 extended file attributes.
2667 In support of the appraisal of Evidence, IMA maintains an ordered
2668 list of measurements in kernel-space, the Stored Measurement Log
2669 (SML), for all files that have been measured before execution since
2670 the operating system was started. Although IMA can be used without a
2671 TPM, it is typically used in conjunction with a TPM to anchor the
2672 integrity of the SML in a hardware-protected secure storage location,
2673 i.e., Platform Configuration Registers (PCRs) provided by TPMs. IMA
2674 provides the SML in both binary and ASCII representations in the
2675 Linux security file system _securityfs_ (/sys/kernel/security/ima/).
2677 IMA templates define the format of the SML, i.e., which fields are
2678 included in a log record. Examples are file path, file hash, user
2679 ID, group ID, file signature, and extended file attributes. IMA
2680 comes with a set of predefined template formats and also allows a
2681 custom format, i.e., a format consisting of template fields supported
2682 by IMA. Template usage is typically determined by boot arguments
2683 passed to the kernel. Alternatively, the format can also be hard-
2684 coded into custom kernels. IMA templates and fields are extensible
2685 in the kernel source code. As a result, more template fields can be
2686 added in the future.
2688 IMA policies define which files are measured using the IMA policy
2689 language. Built-in policies can be passed as boot arguments to the
2690 kernel. Custom IMA policies can be defined once during runtime or be
2691 hard-coded into a custom kernel. If no policy is defined, no
2692 measurements are taken and IMA is effectively disabled.
2694 A comprehensive description of the content fields ins in native Linux
2695 IMA TLV format can be found in Table 16 of the Canonical Event Log
2696 (CEL) specification [cel]. The CEL specification also illustrates
2697 the use of templates to enable extended or customized IMA TLV formats
2698 in Section 5.1.6.
2700 Appendix B. IMA for Network Equipment Boot Logs
2702 Network equipment can generally implement similar IMA-protected
2703 functions to generate measurements (Claims) about the boot process of
2704 a device and enable corresponding remote attestation. Network
2705 Equipment Boot Logs combine the measurement and logging of boot
2706 components and operating system components (executables and files)
2707 into a single log file in a format identical to the IMA format. Note
2708 that the format used for logging measurement of boot components in
2709 this scheme differs from the boot logging strategy described
2710 elsewhere in this document.
2712 During the boot process of the network device, i.e., from BIOS to the
2713 end of the operating system and user-space, all files executed can be
2714 measured and logged in the order of their execution. When the
2715 Verifier initiates a remote attestation process (e.g., challenge-
2716 response remote attestation as defined in this document), the network
2717 equipment takes on the role of an Attester and can convey to the
2718 Verifier Claims that comprise the measurement log as well as the
2719 corresponding PCR values (Evidence) of a TPM.
2721 The verifier can appraise the integrity (compliance with the
2722 Reference Values) of each executed file by comparing its measured
2723 value with the Reference Value. Based on the execution order, the
2724 Verifier can compute a PCR reference value (by replaying the log) and
2725 compare it to the Measurement Log Claims obtained in conjunction with
2726 the PCR Evidence to assess their trustworthiness with respect to an
2727 intended operational state.
2729 Network equipment usually executes multiple components in parallel.
2730 This holds not only during the operating system loading phase, but
2731 also even during the BIOS boot phase. With this measurement log
2732 mechanism, network equipment can take on the role of an Attester,
2733 proving to the Verifier the trustworthiness of its boot process.
2734 Using the measurement log, Verifiers can precisely identify
2735 mismatching log entries to infer potentially tampered components.
2737 This mechanism also supports scenarios that modify files on the
2738 Attester that are subsequently executed during the boot phase (e.g.,
2739 updating/patching) by simply updating the appropriate Reference
2740 Values in Reference Integrity Manifests that inform Verifiers about
2741 how an Attester is composed.
2743 Authors' Addresses
2745 Henk Birkholz
2746 Fraunhofer SIT
2747 Rheinstrasse 75
2748 64295 Darmstadt
2749 Germany
2750 Email: henk.birkholz@sit.fraunhofer.de
2752 Michael Eckel
2753 Fraunhofer SIT
2754 Rheinstrasse 75
2755 64295 Darmstadt
2756 Germany
2757 Email: michael.eckel@sit.fraunhofer.de
2759 Shwetha Bhandari
2760 ThoughtSpot
2761 Email: shwetha.bhandari@thoughtspot.com
2763 Eric Voit
2764 Cisco Systems
2765 Email: evoit@cisco.com
2767 Bill Sulzen
2768 Cisco Systems
2769 Email: bsulzen@cisco.com
2771 Liang Xia (Frank)
2772 Huawei Technologies
2773 101 Software Avenue, Yuhuatai District
2774 Nanjing
2775 Jiangsu, 210012
2776 China
2777 Email: Frank.Xialiang@huawei.com
2779 Tom Laffey
2780 Hewlett Packard Enterprise
2781 Email: tom.laffey@hpe.com
2783 Guy C. Fedorkow
2784 Juniper Networks
2785 10 Technology Park Drive
2786 Westford
2787 Email: gfedorkow@juniper.net