idnits 2.17.00 (12 Aug 2021) /tmp/idnits7853/draft-ietf-netconf-keystore-23.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 570 has weird spacing: '...-format ide...' == Line 578 has weird spacing: '...on-date yan...' == Line 582 has weird spacing: '...sr-info ct:...' == Line 584 has weird spacing: '...request ct:...' == Line 604 has weird spacing: '...-format ide...' == (10 more instances...) -- The document date (14 December 2021) is 157 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) == Outdated reference: A later version (-22) exists of draft-ietf-netconf-crypto-types-21 == Outdated reference: A later version (-09) exists of draft-ietf-netconf-http-client-server-07 == Outdated reference: A later version (-24) exists of draft-ietf-netconf-keystore-22 == Outdated reference: A later version (-25) exists of draft-ietf-netconf-netconf-client-server-23 == Outdated reference: A later version (-25) exists of draft-ietf-netconf-restconf-client-server-23 == Outdated reference: A later version (-27) exists of draft-ietf-netconf-ssh-client-server-25 == Outdated reference: A later version (-12) exists of draft-ietf-netconf-tcp-client-server-10 == Outdated reference: A later version (-27) exists of draft-ietf-netconf-tls-client-server-25 == Outdated reference: A later version (-17) exists of draft-ietf-netconf-trust-anchors-15 Summary: 0 errors (**), 0 flaws (~~), 16 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF Working Group K. Watsen 3 Internet-Draft Watsen Networks 4 Intended status: Standards Track 14 December 2021 5 Expires: 17 June 2022 7 A YANG Data Model for a Keystore 8 draft-ietf-netconf-keystore-23 10 Abstract 12 This document defines a YANG module called "ietf-keystore" that 13 enables centralized configuration of both symmetric and asymmetric 14 keys. The secret value for both key types may be encrypted or 15 hidden. Asymmetric keys may be associated with certificates. 16 Notifications are sent when certificates are about to expire. 18 Editorial Note (To be removed by RFC Editor) 20 This draft contains placeholder values that need to be replaced with 21 finalized values at the time of publication. This note summarizes 22 all of the substitutions that are needed. No other RFC Editor 23 instructions are specified elsewhere in this document. 25 Artwork in this document contains shorthand references to drafts in 26 progress. Please apply the following replacements: 28 * AAAA --> the assigned RFC value for draft-ietf-netconf-crypto- 29 types 31 * CCCC --> the assigned RFC value for this draft 33 Artwork in this document contains placeholder values for the date of 34 publication of this draft. Please apply the following replacement: 36 * 2021-12-14 --> the publication date of this draft 38 The following Appendix section is to be removed prior to publication: 40 * Appendix A. Change Log 42 Status of This Memo 44 This Internet-Draft is submitted in full conformance with the 45 provisions of BCP 78 and BCP 79. 47 Internet-Drafts are working documents of the Internet Engineering 48 Task Force (IETF). Note that other groups may also distribute 49 working documents as Internet-Drafts. The list of current Internet- 50 Drafts is at https://datatracker.ietf.org/drafts/current/. 52 Internet-Drafts are draft documents valid for a maximum of six months 53 and may be updated, replaced, or obsoleted by other documents at any 54 time. It is inappropriate to use Internet-Drafts as reference 55 material or to cite them other than as "work in progress." 57 This Internet-Draft will expire on 17 June 2022. 59 Copyright Notice 61 Copyright (c) 2021 IETF Trust and the persons identified as the 62 document authors. All rights reserved. 64 This document is subject to BCP 78 and the IETF Trust's Legal 65 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 66 license-info) in effect on the date of publication of this document. 67 Please review these documents carefully, as they describe your rights 68 and restrictions with respect to this document. Code Components 69 extracted from this document must include Revised BSD License text as 70 described in Section 4.e of the Trust Legal Provisions and are 71 provided without warranty as described in the Revised BSD License. 73 Table of Contents 75 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 76 1.1. Relation to other RFCs . . . . . . . . . . . . . . . . . 4 77 1.2. Specification Language . . . . . . . . . . . . . . . . . 6 78 1.3. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 79 1.4. Adherence to the NMDA . . . . . . . . . . . . . . . . . . 6 80 1.5. Conventions . . . . . . . . . . . . . . . . . . . . . . . 6 81 2. The "ietf-keystore" Module . . . . . . . . . . . . . . . . . 6 82 2.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 7 83 2.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 14 84 2.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 26 85 3. Support for Built-in Keys . . . . . . . . . . . . . . . . . . 34 86 4. Encrypting Keys in Configuration . . . . . . . . . . . . . . 36 87 5. Security Considerations . . . . . . . . . . . . . . . . . . . 40 88 5.1. Security of Data at Rest . . . . . . . . . . . . . . . . 40 89 5.2. Unconstrained Private Key Usage . . . . . . . . . . . . . 40 90 5.3. The "ietf-keystore" YANG Module . . . . . . . . . . . . . 40 91 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 41 92 6.1. The "IETF XML" Registry . . . . . . . . . . . . . . . . . 41 93 6.2. The "YANG Module Names" Registry . . . . . . . . . . . . 41 94 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 41 95 7.1. Normative References . . . . . . . . . . . . . . . . . . 41 96 7.2. Informative References . . . . . . . . . . . . . . . . . 42 97 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 44 98 A.1. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 44 99 A.2. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 44 100 A.3. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 44 101 A.4. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 45 102 A.5. 04 to 05 . . . . . . . . . . . . . . . . . . . . . . . . 45 103 A.6. 05 to 06 . . . . . . . . . . . . . . . . . . . . . . . . 45 104 A.7. 06 to 07 . . . . . . . . . . . . . . . . . . . . . . . . 45 105 A.8. 07 to 08 . . . . . . . . . . . . . . . . . . . . . . . . 46 106 A.9. 08 to 09 . . . . . . . . . . . . . . . . . . . . . . . . 46 107 A.10. 09 to 10 . . . . . . . . . . . . . . . . . . . . . . . . 46 108 A.11. 10 to 11 . . . . . . . . . . . . . . . . . . . . . . . . 46 109 A.12. 11 to 12 . . . . . . . . . . . . . . . . . . . . . . . . 47 110 A.13. 12 to 13 . . . . . . . . . . . . . . . . . . . . . . . . 47 111 A.14. 13 to 14 . . . . . . . . . . . . . . . . . . . . . . . . 47 112 A.15. 14 to 15 . . . . . . . . . . . . . . . . . . . . . . . . 47 113 A.16. 15 to 16 . . . . . . . . . . . . . . . . . . . . . . . . 47 114 A.17. 16 to 17 . . . . . . . . . . . . . . . . . . . . . . . . 48 115 A.18. 17 to 18 . . . . . . . . . . . . . . . . . . . . . . . . 48 116 A.19. 18 to 19 . . . . . . . . . . . . . . . . . . . . . . . . 48 117 A.20. 19 to 20 . . . . . . . . . . . . . . . . . . . . . . . . 48 118 A.21. 20 to 21 . . . . . . . . . . . . . . . . . . . . . . . . 49 119 A.22. 21 to 22 . . . . . . . . . . . . . . . . . . . . . . . . 49 120 A.23. 22 to 23 . . . . . . . . . . . . . . . . . . . . . . . . 49 121 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 49 122 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 49 124 1. Introduction 126 This document defines a YANG 1.1 [RFC7950] module called "ietf- 127 keystore" that enables centralized configuration of both symmetric 128 and asymmetric keys. The secret value for both key types may be 129 encrypted or hidden (see [I-D.ietf-netconf-crypto-types]. Asymmetric 130 keys may be associated with certificates. Notifications are sent 131 when certificates are about to expire. 133 The "ietf-keystore" module defines many "grouping" statements 134 intended for use by other modules that may import it. For instance, 135 there are groupings that define enabling a key to be either 136 configured locally (within the defining data model) or be a reference 137 to a key in the keystore. 139 Special consideration has been given for systems that have 140 cryptographic hardware, such as a Trusted Platform Module (TPM). 141 These systems are unique in that the cryptographic hardware hides the 142 secret key values. Additionally, such hardware is commonly 143 initialized when manufactured to protect a "built-in" asymmetric key 144 for which the public half is conveyed in an identity certificate 145 (e.g., an IDevID [Std-802.1AR-2018] certificate). Please see 146 Section 3 to see how built-in keys are supported. 148 This document intends to support existing practices; it does not 149 intend to define new behavior for systems to implement. To simplify 150 implementation, advanced key formats may be selectively implemented. 152 Implementations may utilize zero or more operating system level 153 keystore utilities and/or hardware security modules (HSMs). 155 1.1. Relation to other RFCs 157 This document presents one or more YANG modules [RFC7950] that are 158 part of a collection of RFCs that work together to, ultimately, 159 enable the configuration of the clients and servers of both the 160 NETCONF [RFC6241] and RESTCONF [RFC8040] protocols. 162 The modules have been defined in a modular fashion to enable their 163 use by other efforts, some of which are known to be in progress at 164 the time of this writing, with many more expected to be defined in 165 time. 167 The normative dependency relationship between the various RFCs in the 168 collection is presented in the below diagram. The labels in the 169 diagram represent the primary purpose provided by each RFC. 170 Hyperlinks to each RFC are provided below the diagram. 172 crypto-types 173 ^ ^ 174 / \ 175 / \ 176 truststore keystore 177 ^ ^ ^ ^ 178 | +---------+ | | 179 | | | | 180 | +------------+ | 181 tcp-client-server | / | | 182 ^ ^ ssh-client-server | | 183 | | ^ tls-client-server 184 | | | ^ ^ http-client-server 185 | | | | | ^ 186 | | | +-----+ +---------+ | 187 | | | | | | 188 | +-----------|--------|--------------+ | | 189 | | | | | | 190 +-----------+ | | | | | 191 | | | | | | 192 | | | | | | 193 netconf-client-server restconf-client-server 195 +=======================+===========================================+ 196 |Label in Diagram | Originating RFC | 197 +=======================+===========================================+ 198 |crypto-types | [I-D.ietf-netconf-crypto-types] | 199 +-----------------------+-------------------------------------------+ 200 |truststore | [I-D.ietf-netconf-trust-anchors] | 201 +-----------------------+-------------------------------------------+ 202 |keystore | [I-D.ietf-netconf-keystore] | 203 +-----------------------+-------------------------------------------+ 204 |tcp-client-server | [I-D.ietf-netconf-tcp-client-server] | 205 +-----------------------+-------------------------------------------+ 206 |ssh-client-server | [I-D.ietf-netconf-ssh-client-server] | 207 +-----------------------+-------------------------------------------+ 208 |tls-client-server | [I-D.ietf-netconf-tls-client-server] | 209 +-----------------------+-------------------------------------------+ 210 |http-client-server | [I-D.ietf-netconf-http-client-server] | 211 +-----------------------+-------------------------------------------+ 212 |netconf-client-server | [I-D.ietf-netconf-netconf-client-server] | 213 +-----------------------+-------------------------------------------+ 214 |restconf-client-server | [I-D.ietf-netconf-restconf-client-server] | 215 +-----------------------+-------------------------------------------+ 217 Table 1: Label to RFC Mapping 219 1.2. Specification Language 221 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 222 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 223 "OPTIONAL" in this document are to be interpreted as described in BCP 224 14 [RFC2119] [RFC8174] when, and only when, they appear in all 225 capitals, as shown here. 227 1.3. Terminology 229 The terms "client" and "server" are defined in [RFC6241] and are not 230 redefined here. 232 The term "keystore" is defined in this draft as a mechanism that 233 intends safeguard secrets placed into it for protection. 235 The nomenclature "" and "" are defined in 236 [RFC8342]. 238 The sentence fragments "augmented" and "augmented in" are used herein 239 as the past tense verbified form of the "augment" statement defined 240 in Section 7.17 of [RFC7950]. 242 1.4. Adherence to the NMDA 244 This document is compliant with Network Management Datastore 245 Architecture (NMDA) [RFC8342]. For instance, keys and associated 246 certificates installed during manufacturing (e.g., for an IDevID 247 certificate) are expected to appear in (see Section 3). 249 1.5. Conventions 251 Various examples used in this document use a placeholder value for 252 binary data that has been base64 encoded (e.g., "BASE64VALUE="). 253 This placeholder value is used as real base64 encoded structures are 254 often many lines long and hence distracting to the example being 255 presented. 257 2. The "ietf-keystore" Module 259 This section defines a YANG 1.1 [RFC7950] module called "ietf- 260 keystore". A high-level overview of the module is provided in 261 Section 2.1. Examples illustrating the module's use are provided in 262 Section 2.2. The YANG module itself is defined in Section 2.3. 264 2.1. Data Model Overview 266 This section provides an overview of the "ietf-keystore" module in 267 terms of its features, typedefs, groupings, and protocol-accessible 268 nodes. 270 2.1.1. Features 272 The following diagram lists all the "feature" statements defined in 273 the "ietf-keystore" module: 275 Features: 276 +-- central-keystore-supported 277 +-- local-definitions-supported 279 | The diagram above uses syntax that is similar to but not 280 | defined in [RFC8340]. 282 2.1.2. Typedefs 284 The following diagram lists the "typedef" statements defined in the 285 "ietf-keystore" module: 287 Typedefs: 288 leafref 289 +-- symmetric-key-ref 290 +-- asymmetric-key-ref 292 | The diagram above uses syntax that is similar to but not 293 | defined in [RFC8340]. 295 Comments: 297 * All the typedefs defined in the "ietf-keystore" module extend the 298 base "leafref" type defined in [RFC7950]. 300 * The leafrefs refer to symmetric and asymmetric keys in the central 301 keystore, when this module is implemented. 303 * These typedefs are provided as an aid to downstream modules that 304 import the "ietf-keystore" module. 306 2.1.3. Groupings 308 The "ietf-keystore" module defines the following "grouping" 309 statements: 311 * encrypted-by-choice-grouping 312 * asymmetric-key-certificate-ref-grouping 313 * local-or-keystore-symmetric-key-grouping 314 * local-or-keystore-asymmetric-key-grouping 315 * local-or-keystore-asymmetric-key-with-certs-grouping 316 * local-or-keystore-end-entity-cert-with-key-grouping 317 * keystore-grouping 319 Each of these groupings are presented in the following subsections. 321 2.1.3.1. The "encrypted-by-choice-grouping" Grouping 323 The following tree diagram [RFC8340] illustrates the "encrypted-by- 324 choice-grouping" grouping: 326 | The grouping's name is intended to be parsed "(encrypted- 327 | by)-(choice)-(grouping)", not as "(encrypted)-(by- 328 | choice)-(grouping)". 330 grouping encrypted-by-choice-grouping 331 +-- (encrypted-by-choice) 332 +--:(symmetric-key-ref) 333 | +-- symmetric-key-ref? ks:symmetric-key-ref 334 +--:(asymmetric-key-ref) 335 +-- asymmetric-key-ref? ks:asymmetric-key-ref 337 Comments: 339 * This grouping defines a "choice" statement with options to 340 reference either a symmetric or an asymmetric key configured in 341 the keystore. 343 * This grouping is usable only when the keystore module is 344 implemented. Servers defining custom keystore locations MUST 345 augment in alternate "encrypted-by" references to the alternate 346 locations. 348 2.1.3.2. The "asymmetric-key-certificate-ref-grouping" Grouping 350 The following tree diagram [RFC8340] illustrates the "asymmetric-key- 351 certificate-ref-grouping" grouping: 353 grouping asymmetric-key-certificate-ref-grouping 354 +-- asymmetric-key? ks:asymmetric-key-ref 355 +-- certificate? leafref 357 Comments: 359 * This grouping defines a reference to a certificate in two parts: 360 the first being the name of the asymmetric key the certificate is 361 associated with, and the second being the name of the certificate 362 itself. 364 * This grouping is usable only when the keystore module is 365 implemented. Servers defining custom keystore locations MAY 366 define an alternate grouping for references to the alternate 367 locations. 369 2.1.3.3. The "local-or-keystore-symmetric-key-grouping" Grouping 371 The following tree diagram [RFC8340] illustrates the "local-or- 372 keystore-symmetric-key-grouping" grouping: 374 grouping local-or-keystore-symmetric-key-grouping 375 +-- (local-or-keystore) 376 +--:(local) {local-definitions-supported}? 377 | +-- local-definition 378 | +---u ct:symmetric-key-grouping 379 +--:(keystore) {central-keystore-supported}? 380 +-- keystore-reference? ks:symmetric-key-ref 382 Comments: 384 * The "local-or-keystore-symmetric-key-grouping" grouping is 385 provided soley as convenience to downstream modules that wish to 386 offer an option for whether a symmetric key is defined locally or 387 as a reference to a symmetric key in the keystore. 389 * A "choice" statement is used to expose the various options. Each 390 option is enabled by a "feature" statement. Additional "case" 391 statements MAY be augmented in if, e.g., there is a need to 392 reference a symmetric key in an alternate location. 394 * For the "local-definition" option, the definition uses the 395 "symmetric-key-grouping" grouping discussed in Section 2.1.4.3 of 396 [I-D.ietf-netconf-crypto-types]. 398 * For the "keystore" option, the "keystore-reference" is an instance 399 of the "symmetric-key-ref" discussed in Section 2.1.2. 401 2.1.3.4. The "local-or-keystore-asymmetric-key-grouping" Grouping 403 The following tree diagram [RFC8340] illustrates the "local-or- 404 keystore-asymmetric-key-grouping" grouping: 406 grouping local-or-keystore-asymmetric-key-grouping 407 +-- (local-or-keystore) 408 +--:(local) {local-definitions-supported}? 409 | +-- local-definition 410 | +---u ct:asymmetric-key-pair-grouping 411 +--:(keystore) {central-keystore-supported}? 412 +-- keystore-reference? ks:asymmetric-key-ref 414 Comments: 416 * The "local-or-keystore-asymmetric-key-grouping" grouping is 417 provided soley as convenience to downstream modules that wish to 418 offer an option for whether an asymmetric key is defined locally 419 or as a reference to an asymmetric key in the keystore. 421 * A "choice" statement is used to expose the various options. Each 422 option is enabled by a "feature" statement. Additional "case" 423 statements MAY be augmented in if, e.g., there is a need to 424 reference an asymmetric key in an alternate location. 426 * For the "local-definition" option, the definition uses the 427 "asymmetric-key-pair-grouping" grouping discussed in 428 Section 2.1.4.5 of [I-D.ietf-netconf-crypto-types]. 430 * For the "keystore" option, the "keystore-reference" is an instance 431 of the "asymmetric-key-ref" typedef discussed in Section 2.1.2. 433 2.1.3.5. The "local-or-keystore-asymmetric-key-with-certs-grouping" 434 Grouping 436 The following tree diagram [RFC8340] illustrates the "local-or- 437 keystore-asymmetric-key-with-certs-grouping" grouping: 439 grouping local-or-keystore-asymmetric-key-with-certs-grouping 440 +-- (local-or-keystore) 441 +--:(local) {local-definitions-supported}? 442 | +-- local-definition 443 | +---u ct:asymmetric-key-pair-with-certs-grouping 444 +--:(keystore) {central-keystore-supported}? 445 +-- keystore-reference? ks:asymmetric-key-ref 447 Comments: 449 * The "local-or-keystore-asymmetric-key-with-certs-grouping" 450 grouping is provided soley as convenience to downstream modules 451 that wish to offer an option for whether an asymmetric key is 452 defined locally or as a reference to an asymmetric key in the 453 keystore. 455 * A "choice" statement is used to expose the various options. Each 456 option is enabled by a "feature" statement. Additional "case" 457 statements MAY be augmented in if, e.g., there is a need to 458 reference an asymmetric key in an alternate location. 460 * For the "local-definition" option, the definition uses the 461 "asymmetric-key-pair-with-certs-grouping" grouping discussed in 462 Section 2.1.4.11 of [I-D.ietf-netconf-crypto-types]. 464 * For the "keystore" option, the "keystore-reference" is an instance 465 of the "asymmetric-key-ref" typedef discussed in Section 2.1.2. 467 2.1.3.6. The "local-or-keystore-end-entity-cert-with-key-grouping" 468 Grouping 470 The following tree diagram [RFC8340] illustrates the "local-or- 471 keystore-end-entity-cert-with-key-grouping" grouping: 473 grouping local-or-keystore-end-entity-cert-with-key-grouping 474 +-- (local-or-keystore) 475 +--:(local) {local-definitions-supported}? 476 | +-- local-definition 477 | +---u ct:asymmetric-key-pair-with-cert-grouping 478 +--:(keystore) {central-keystore-supported}? 479 +-- keystore-reference 480 +---u asymmetric-key-certificate-ref-grouping 482 Comments: 484 * The "local-or-keystore-end-entity-cert-with-key-grouping" grouping 485 is provided soley as convenience to downstream modules that wish 486 to offer an option for whether a symmetric key is defined locally 487 or as a reference to a symmetric key in the keystore. 489 * A "choice" statement is used to expose the various options. Each 490 option is enabled by a "feature" statement. Additional "case" 491 statements MAY be augmented in if, e.g., there is a need to 492 reference a symmetric key in an alternate location. 494 * For the "local-definition" option, the definition uses the 495 "asymmetric-key-pair-with-certs-grouping" grouping discussed in 496 Section 2.1.4.11 of [I-D.ietf-netconf-crypto-types]. 498 * For the "keystore" option, the "keystore-reference" uses the 499 "asymmetric-key-certificate-ref-grouping" grouping discussed in 500 Section 2.1.3.2. 502 2.1.3.7. The "keystore-grouping" Grouping 504 The following tree diagram [RFC8340] illustrates the "keystore- 505 grouping" grouping: 507 grouping keystore-grouping 508 +-- asymmetric-keys 509 | +-- asymmetric-key* [name] 510 | +-- name? string 511 | +---u ct:asymmetric-key-pair-with-certs-grouping 512 +-- symmetric-keys 513 +-- symmetric-key* [name] 514 +-- name? string 515 +---u ct:symmetric-key-grouping 517 Comments: 519 * The "keystore-grouping" grouping defines a keystore instance as 520 being composed of symmetric and asymmetric keys. The structure 521 for the symmetric and asymmetric keys is essentially the same, 522 being a "list" inside a "container". 524 * For asymmetric keys, each "asymmetric-key" uses the "asymmetric- 525 key-pair-with-certs-grouping" grouping discussed in 526 Section 2.1.4.11 of [I-D.ietf-netconf-crypto-types]. 528 * For symmetric keys, each "symmetric-key" uses the "symmetric-key- 529 grouping" grouping discussed in Section 2.1.4.3 of 530 [I-D.ietf-netconf-crypto-types]. 532 2.1.4. Protocol-accessible Nodes 534 The following tree diagram [RFC8340] lists all the protocol- 535 accessible nodes defined in the "ietf-keystore" module, without 536 expanding the "grouping" statements: 538 module: ietf-keystore 539 +--rw keystore 540 +---u keystore-grouping 542 The following tree diagram [RFC8340] lists all the protocol- 543 accessible nodes defined in the "ietf-keystore" module, with all 544 "grouping" statements expanded, enabling the keystore's full 545 structure to be seen: 547 module: ietf-keystore 548 +--rw keystore 549 +--rw asymmetric-keys 550 | +--rw asymmetric-key* [name] 551 | +--rw name string 552 | +--rw public-key-format identityref 553 | +--rw public-key binary 554 | +--rw private-key-format? identityref 555 | +--rw (private-key-type) 556 | | +--:(cleartext-private-key) 557 | | | +--rw cleartext-private-key? binary 558 | | +--:(hidden-private-key) 559 | | | +--rw hidden-private-key? empty 560 | | +--:(encrypted-private-key) {private-key-encryption}? 561 | | +--rw encrypted-private-key 562 | | +--rw encrypted-by 563 | | | +--rw (encrypted-by-choice) 564 | | | +--:(symmetric-key-ref) 565 | | | | +--rw symmetric-key-ref? 566 | | | | ks:symmetric-key-ref 567 | | | +--:(asymmetric-key-ref) 568 | | | +--rw asymmetric-key-ref? 569 | | | ks:asymmetric-key-ref 570 | | +--rw encrypted-value-format identityref 571 | | +--rw encrypted-value binary 572 | +--rw certificates 573 | | +--rw certificate* [name] 574 | | +--rw name string 575 | | +--rw cert-data end-entity-cert-cms 576 | | +---n certificate-expiration 577 | | {certificate-expiration-notification}? 578 | | +-- expiration-date yang:date-and-time 579 | +---x generate-certificate-signing-request 580 | {certificate-signing-request-generation}? 581 | +---w input 582 | | +---w csr-info ct:csr-info 583 | +--ro output 584 | +--ro certificate-signing-request ct:csr 585 +--rw symmetric-keys 586 +--rw symmetric-key* [name] 587 +--rw name string 588 +--rw key-format? identityref 589 +--rw (key-type) 590 +--:(cleartext-key) 591 | +--rw cleartext-key? binary 592 +--:(hidden-key) 593 | +--rw hidden-key? empty 594 +--:(encrypted-key) {symmetric-key-encryption}? 595 +--rw encrypted-key 596 +--rw encrypted-by 597 | +--rw (encrypted-by-choice) 598 | +--:(symmetric-key-ref) 599 | | +--rw symmetric-key-ref? 600 | | ks:symmetric-key-ref 601 | +--:(asymmetric-key-ref) 602 | +--rw asymmetric-key-ref? 603 | ks:asymmetric-key-ref 604 +--rw encrypted-value-format identityref 605 +--rw encrypted-value binary 607 Comments: 609 * Protocol-accessible nodes are those nodes that are accessible when 610 the module is "implemented", as described in Section 5.6.5 of 611 [RFC7950]. 613 * The protocol-accessible nodes for the "ietf-keystore" module are 614 an instance of the "keystore-grouping" grouping discussed in 615 Section 2.1.3.7. 617 * The reason for why "keystore-grouping" exists separate from the 618 protocol-accessible nodes definition is so as to enable instances 619 of the keystore to be instantiated in other locations, as may be 620 needed or desired by some modules. 622 2.2. Example Usage 624 The examples in this section are encoded using XML, such as might be 625 the case when using the NETCONF protocol. Other encodings MAY be 626 used, such as JSON when using the RESTCONF protocol. 628 2.2.1. A Keystore Instance 630 The following example illustrates keys in . Please see 631 Section 3 for an example illustrating built-in values in 632 . 634 =============== NOTE: '\' line wrapping per RFC 8792 ================ 636 639 640 641 cleartext-symmetric-key 642 ct:octet-string-key-format 643 BASE64VALUE= 644 645 646 hidden-symmetric-key 647 648 649 650 encrypted-symmetric-key 651 ct:one-symmetric-key-format 652 653 654 hidden-asymmetric-key 656 657 658 ct:cms-enveloped-data-format 659 660 BASE64VALUE= 661 662 663 665 666 667 ssh-rsa-key 668 669 ct:ssh-public-key-format 670 671 BASE64VALUE= 672 673 ct:rsa-private-key-format 674 675 BASE64VALUE= 676 677 678 ssh-rsa-key-with-cert 679 680 ct:subject-public-key-info-format 681 682 BASE64VALUE= 683 684 ct:rsa-private-key-format 685 686 BASE64VALUE= 687 688 689 ex-rsa-cert2 690 BASE64VALUE= 692 693 694 695 696 raw-private-key 697 698 ct:subject-public-key-info-format 699 700 BASE64VALUE= 701 702 ct:rsa-private-key-format 703 704 BASE64VALUE= 705 706 707 rsa-asymmetric-key 708 709 ct:subject-public-key-info-format 710 711 BASE64VALUE= 712 713 ct:rsa-private-key-format 714 715 BASE64VALUE= 716 717 718 ex-rsa-cert 719 BASE64VALUE= 720 721 722 723 724 ec-asymmetric-key 725 726 ct:subject-public-key-info-format 727 728 BASE64VALUE= 729 730 ct:ec-private-key-format 731 732 BASE64VALUE= 733 734 735 ex-ec-cert 736 BASE64VALUE= 737 738 739 740 741 hidden-asymmetric-key 742 743 ct:subject-public-key-info-format 744 745 BASE64VALUE= 746 747 748 749 builtin-idevid-cert 750 BASE64VALUE= 751 752 753 my-ldevid-cert 754 BASE64VALUE= 755 756 757 758 759 encrypted-asymmetric-key 760 761 ct:subject-public-key-info-format 762 763 BASE64VALUE= 764 765 ct:one-asymmetric-key-format 766 767 768 769 encrypted-symmetric-key 771 772 773 ct:cms-encrypted-data-format 774 775 BASE64VALUE= 776 777 778 779 781 2.2.2. A Certificate Expiration Notification 783 The following example illustrates a "certificate-expiration" 784 notification for a certificate associated with a key configured in 785 the keystore. 787 =============== NOTE: '\' line wrapping per RFC 8792 ================ 789 791 2018-05-25T00:01:00Z 792 793 794 795 hidden-asymmetric-key 796 797 798 my-ldevid-cert 799 800 2018-08-05T14:18:53-05:00 802 803 804 805 806 807 808 810 2.2.3. The "Local or Keystore" Groupings 812 This section illustrates the various "local-or-keystore" groupings 813 defined in the "ietf-keystore" module, specifically the "local-or- 814 keystore-symmetric-key-grouping" (Section 2.1.3.3), "local-or- 815 keystore-asymmetric-key-grouping" (Section 2.1.3.4), "local-or- 816 keystore-asymmetric-key-with-certs-grouping" (Section 2.1.3.5), and 817 "local-or-keystore-end-entity-cert-with-key-grouping" 818 (Section 2.1.3.6) groupings. 820 These examples assume the existence of an example module called "ex- 821 keystore-usage" having the namespace "http://example.com/ns/example- 822 keystore-usage". 824 The ex-keystore-usage module is first presented using tree diagrams 825 [RFC8340], followed by an instance example illustrating all the 826 "local-or-keystore" groupings in use, followed by the YANG module 827 itself. 829 The following tree diagram illustrates "ex-keystore-usage" without 830 expanding the "grouping" statements: 832 module: ex-keystore-usage 833 +--rw keystore-usage 834 +--rw symmetric-key* [name] 835 | +--rw name string 836 | +---u ks:local-or-keystore-symmetric-key-grouping 837 +--rw asymmetric-key* [name] 838 | +--rw name string 839 | +---u ks:local-or-keystore-asymmetric-key-grouping 840 +--rw asymmetric-key-with-certs* [name] 841 | +--rw name 842 | | string 843 | +---u ks:local-or-keystore-asymmetric-key-with-certs-grouping 844 +--rw end-entity-cert-with-key* [name] 845 +--rw name 846 | string 847 +---u ks:local-or-keystore-end-entity-cert-with-key-grouping 849 The following tree diagram illustrates the "ex-keystore-usage" 850 module, with all "grouping" statements expanded, enabling the usage's 851 full structure to be seen: 853 module: ex-keystore-usage 854 +--rw keystore-usage 855 +--rw symmetric-key* [name] 856 | +--rw name string 857 | +--rw (local-or-keystore) 858 | +--:(local) {local-definitions-supported}? 859 | | +--rw local-definition 860 | | +--rw key-format? identityref 861 | | +--rw (key-type) 862 | | +--:(cleartext-key) 863 | | | +--rw cleartext-key? binary 864 | | +--:(hidden-key) 865 | | | +--rw hidden-key? empty 866 | | +--:(encrypted-key) {symmetric-key-encryption}? 867 | | +--rw encrypted-key 868 | | +--rw encrypted-by 869 | | +--rw encrypted-value-format identityref 870 | | +--rw encrypted-value binary 871 | +--:(keystore) {central-keystore-supported}? 872 | +--rw keystore-reference? ks:symmetric-key-ref 873 +--rw asymmetric-key* [name] 874 | +--rw name string 875 | +--rw (local-or-keystore) 876 | +--:(local) {local-definitions-supported}? 877 | | +--rw local-definition 878 | | +--rw public-key-format identityref 879 | | +--rw public-key binary 880 | | +--rw private-key-format? identityref 881 | | +--rw (private-key-type) 882 | | +--:(cleartext-private-key) 883 | | | +--rw cleartext-private-key? binary 884 | | +--:(hidden-private-key) 885 | | | +--rw hidden-private-key? empty 886 | | +--:(encrypted-private-key) 887 | | {private-key-encryption}? 888 | | +--rw encrypted-private-key 889 | | +--rw encrypted-by 890 | | +--rw encrypted-value-format identityref 891 | | +--rw encrypted-value binary 892 | +--:(keystore) {central-keystore-supported}? 893 | +--rw keystore-reference? ks:asymmetric-key-ref 894 +--rw asymmetric-key-with-certs* [name] 895 | +--rw name string 896 | +--rw (local-or-keystore) 897 | +--:(local) {local-definitions-supported}? 898 | | +--rw local-definition 899 | | +--rw public-key-format 900 | | | identityref 901 | | +--rw public-key binary 902 | | +--rw private-key-format? 903 | | | identityref 904 | | +--rw (private-key-type) 905 | | | +--:(cleartext-private-key) 906 | | | | +--rw cleartext-private-key? binary 907 | | | +--:(hidden-private-key) 908 | | | | +--rw hidden-private-key? empty 909 | | | +--:(encrypted-private-key) 910 | | | {private-key-encryption}? 911 | | | +--rw encrypted-private-key 912 | | | +--rw encrypted-by 913 | | | +--rw encrypted-value-format identityref 914 | | | +--rw encrypted-value binary 915 | | +--rw certificates 916 | | | +--rw certificate* [name] 917 | | | +--rw name string 918 | | | +--rw cert-data 919 | | | | end-entity-cert-cms 920 | | | +---n certificate-expiration 921 | | | {certificate-expiration-notification}? 922 | | | +-- expiration-date yang:date-and-time 923 | | +---x generate-certificate-signing-request 924 | | {certificate-signing-request-generation}? 925 | | +---w input 926 | | | +---w csr-info ct:csr-info 927 | | +--ro output 928 | | +--ro certificate-signing-request ct:csr 929 | +--:(keystore) {central-keystore-supported}? 930 | +--rw keystore-reference? ks:asymmetric-key-ref 931 +--rw end-entity-cert-with-key* [name] 932 +--rw name string 933 +--rw (local-or-keystore) 934 +--:(local) {local-definitions-supported}? 935 | +--rw local-definition 936 | +--rw public-key-format 937 | | identityref 938 | +--rw public-key binary 939 | +--rw private-key-format? 940 | | identityref 941 | +--rw (private-key-type) 942 | | +--:(cleartext-private-key) 943 | | | +--rw cleartext-private-key? binary 944 | | +--:(hidden-private-key) 945 | | | +--rw hidden-private-key? empty 946 | | +--:(encrypted-private-key) 947 | | {private-key-encryption}? 948 | | +--rw encrypted-private-key 949 | | +--rw encrypted-by 950 | | +--rw encrypted-value-format identityref 951 | | +--rw encrypted-value binary 952 | +--rw cert-data? 953 | | end-entity-cert-cms 954 | +---n certificate-expiration 955 | | {certificate-expiration-notification}? 956 | | +-- expiration-date yang:date-and-time 957 | +---x generate-certificate-signing-request 958 | {certificate-signing-request-generation}? 959 | +---w input 960 | | +---w csr-info ct:csr-info 961 | +--ro output 962 | +--ro certificate-signing-request ct:csr 963 +--:(keystore) {central-keystore-supported}? 964 +--rw keystore-reference 965 +--rw asymmetric-key? ks:asymmetric-key-ref 966 +--rw certificate? leafref 968 The following example provides two equivalent instances of each 969 grouping, the first being a reference to a keystore and the second 970 being locally-defined. The instance having a reference to a keystore 971 is consistent with the keystore defined in Section 2.2.1. The two 972 instances are equivalent, as the locally-defined instance example 973 contains the same values defined by the keystore instance referenced 974 by its sibling example. 976 980 981 983 984 example 1a 985 cleartext-symmetric-key 986 988 989 example 1b 990 991 ct:octet-string-key-format 992 BASE64VALUE= 993 994 996 997 999 1000 example 2a 1001 rsa-asymmetric-key 1002 1004 1005 example 2b 1006 1007 1008 ct:subject-public-key-info-format 1009 1010 BASE64VALUE= 1011 1012 ct:rsa-private-key-format 1013 1014 BASE64VALUE= 1015 1016 1018 1019 1021 1022 example 3a 1023 rsa-asymmetric-key 1024 1026 1027 example 3b 1028 1029 1030 ct:subject-public-key-info-format 1031 1032 BASE64VALUE= 1033 1034 ct:rsa-private-key-format 1035 1036 BASE64VALUE= 1037 1038 1039 a locally-defined cert 1040 BASE64VALUE= 1041 1042 1043 1044 1046 1047 1049 1050 example 4a 1051 1052 rsa-asymmetric-key 1053 ex-rsa-cert 1054 1055 1057 1058 example 4b 1059 1060 1061 ct:subject-public-key-info-format 1062 1063 BASE64VALUE= 1064 1065 ct:rsa-private-key-format 1066 1067 BASE64VALUE= 1068 BASE64VALUE= 1070 1071 1073 1075 Following is the "ex-keystore-usage" module's YANG definition: 1077 module ex-keystore-usage { 1078 yang-version 1.1; 1079 namespace "http://example.com/ns/example-keystore-usage"; 1080 prefix eku; 1082 import ietf-keystore { 1083 prefix ks; 1084 reference 1085 "RFC CCCC: A YANG Data Model for a Keystore"; 1086 } 1088 organization 1089 "Example Corporation"; 1091 contact 1092 "Author: YANG Designer "; 1094 description 1095 "This module illustrates notable groupings defined in 1096 the 'ietf-keystore' module."; 1098 revision 2021-12-14 { 1099 description 1100 "Initial version"; 1101 reference 1102 "RFC CCCC: A YANG Data Model for a Keystore"; 1103 } 1105 container keystore-usage { 1106 description 1107 "An illustration of the various keystore groupings."; 1108 list symmetric-key { 1109 key "name"; 1110 leaf name { 1111 type string; 1112 description 1113 "An arbitrary name for this key."; 1114 } 1115 uses ks:local-or-keystore-symmetric-key-grouping; 1116 description 1117 "An symmetric key that may be configured locally or be a 1118 reference to a symmetric key in the keystore."; 1119 } 1120 list asymmetric-key { 1121 key "name"; 1122 leaf name { 1123 type string; 1124 description 1125 "An arbitrary name for this key."; 1126 } 1127 uses ks:local-or-keystore-asymmetric-key-grouping; 1128 description 1129 "An asymmetric key, with no certs, that may be configured 1130 locally or be a reference to an asymmetric key in the 1131 keystore. The intent is to reference just the asymmetric 1132 key, not any certificates that may also be associated 1133 with the asymmetric key."; 1134 } 1135 list asymmetric-key-with-certs { 1136 key "name"; 1137 leaf name { 1138 type string; 1139 description 1140 "An arbitrary name for this key."; 1141 } 1142 uses ks:local-or-keystore-asymmetric-key-with-certs-grouping; 1143 description 1144 "An asymmetric key and its associated certs, that may be 1145 configured locally or be a reference to an asymmetric key 1146 (and its associated certs) in the keystore."; 1147 } 1148 list end-entity-cert-with-key { 1149 key "name"; 1150 leaf name { 1151 type string; 1152 description 1153 "An arbitrary name for this key."; 1154 } 1155 uses ks:local-or-keystore-end-entity-cert-with-key-grouping; 1156 description 1157 "An end-entity certificate and its associated asymmetric 1158 key, that may be configured locally or be a reference 1159 to another certificate (and its associated asymmetric 1160 key) in the keystore."; 1161 } 1162 } 1163 } 1165 2.3. YANG Module 1167 This YANG module has normative references to [RFC8341] and 1168 [I-D.ietf-netconf-crypto-types]. 1170 file "ietf-keystore@2021-12-14.yang" 1172 module ietf-keystore { 1173 yang-version 1.1; 1174 namespace "urn:ietf:params:xml:ns:yang:ietf-keystore"; 1175 prefix ks; 1177 import ietf-netconf-acm { 1178 prefix nacm; 1179 reference 1180 "RFC 8341: Network Configuration Access Control Model"; 1181 } 1183 import ietf-crypto-types { 1184 prefix ct; 1185 reference 1186 "RFC AAAA: YANG Data Types and Groupings for Cryptography"; 1187 } 1189 organization 1190 "IETF NETCONF (Network Configuration) Working Group"; 1192 contact 1193 "WG Web: 1194 WG List: 1195 Author: Kent Watsen "; 1197 description 1198 "This module defines a 'keystore' to centralize management 1199 of security credentials. 1201 Copyright (c) 2021 IETF Trust and the persons identified 1202 as authors of the code. All rights reserved. 1204 Redistribution and use in source and binary forms, with 1205 or without modification, is permitted pursuant to, and 1206 subject to the license terms contained in, the Simplified 1207 BSD License set forth in Section 4.c of the IETF Trust's 1208 Legal Provisions Relating to IETF Documents 1209 (https://trustee.ietf.org/license-info). 1211 This version of this YANG module is part of RFC CCCC 1212 (https://www.rfc-editor.org/info/rfcCCCC); see the RFC 1213 itself for full legal notices. 1215 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1216 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 1217 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 1218 are to be interpreted as described in BCP 14 (RFC 2119) 1219 (RFC 8174) when, and only when, they appear in all 1220 capitals, as shown here."; 1222 revision 2021-12-14 { 1223 description 1224 "Initial version"; 1225 reference 1226 "RFC CCCC: A YANG Data Model for a Keystore"; 1227 } 1229 /****************/ 1230 /* Features */ 1231 /****************/ 1233 feature central-keystore-supported { 1234 description 1235 "The 'central-keystore-supported' feature indicates that 1236 the server supports the keystore."; 1237 } 1239 feature local-definitions-supported { 1240 description 1241 "The 'local-definitions-supported' feature indicates that 1242 the server supports locally-defined keys."; 1243 } 1245 /****************/ 1246 /* Typedefs */ 1247 /****************/ 1249 typedef symmetric-key-ref { 1250 type leafref { 1251 path "/ks:keystore/ks:symmetric-keys/ks:symmetric-key" 1252 + "/ks:name"; 1253 } 1254 description 1255 "This typedef enables modules to easily define a reference 1256 to a symmetric key stored in the keystore, when this 1257 module is implemented."; 1258 } 1260 typedef asymmetric-key-ref { 1261 type leafref { 1262 path "/ks:keystore/ks:asymmetric-keys/ks:asymmetric-key" 1263 + "/ks:name"; 1264 } 1265 description 1266 "This typedef enables modules to easily define a reference 1267 to an asymmetric key stored in the keystore, when this 1268 module is implemented."; 1269 } 1271 /*****************/ 1272 /* Groupings */ 1273 /*****************/ 1275 grouping encrypted-by-choice-grouping { 1276 description 1277 "A grouping that defines a 'choice' statement that can be 1278 augmented into the 'encrypted-by' node, present in the 1279 'symmetric-key-grouping' and 'asymmetric-key-pair-grouping' 1280 groupings defined in RFC AAAA, enabling references to keys 1281 in the keystore, when this module is implemented."; 1282 choice encrypted-by-choice { 1283 nacm:default-deny-write; 1284 mandatory true; 1285 description 1286 "A choice amongst other symmetric or asymmetric keys."; 1287 case symmetric-key-ref { 1288 leaf symmetric-key-ref { 1289 type ks:symmetric-key-ref; 1290 description 1291 "Identifies the symmetric key used to encrypt the 1292 associated key."; 1293 } 1294 } 1295 case asymmetric-key-ref { 1296 leaf asymmetric-key-ref { 1297 type ks:asymmetric-key-ref; 1298 description 1299 "Identifies the asymmetric key whose public key 1300 encrypted the associated key."; 1301 } 1302 } 1303 } 1304 } 1306 grouping asymmetric-key-certificate-ref-grouping { 1307 description 1308 "This grouping defines a reference to a specific certificate 1309 associated with an asymmetric key stored in the keystore, 1310 when this module is implemented."; 1311 leaf asymmetric-key { 1312 nacm:default-deny-write; 1313 type ks:asymmetric-key-ref; 1314 must '../certificate'; 1315 description 1316 "A reference to an asymmetric key in the keystore."; 1317 } 1318 leaf certificate { 1319 nacm:default-deny-write; 1320 type leafref { 1321 path "/ks:keystore/ks:asymmetric-keys/ks:asymmetric-key" 1322 + "[ks:name = current()/../asymmetric-key]/" 1323 + "ks:certificates/ks:certificate/ks:name"; 1324 } 1325 must '../asymmetric-key'; 1326 description 1327 "A reference to a specific certificate of the 1328 asymmetric key in the keystore."; 1329 } 1330 } 1332 // local-or-keystore-* groupings 1334 grouping local-or-keystore-symmetric-key-grouping { 1335 description 1336 "A grouping that expands to allow the symmetric key to be 1337 either stored locally, i.e., within the using data model, 1338 or a reference to a symmetric key stored in the keystore. 1340 Servers that do not 'implement' this module, and hence 1341 'central-keystore-supported' is not defined, SHOULD 1342 augment in custom 'case' statements enabling references 1343 to the alternate keystore locations."; 1344 choice local-or-keystore { 1345 nacm:default-deny-write; 1346 mandatory true; 1347 description 1348 "A choice between an inlined definition and a definition 1349 that exists in the keystore."; 1350 case local { 1351 if-feature "local-definitions-supported"; 1352 container local-definition { 1353 description 1354 "Container to hold the local key definition."; 1355 uses ct:symmetric-key-grouping; 1356 } 1358 } 1359 case keystore { 1360 if-feature "central-keystore-supported"; 1361 leaf keystore-reference { 1362 type ks:symmetric-key-ref; 1363 description 1364 "A reference to an symmetric key that exists in 1365 the keystore, when this module is implemented."; 1366 } 1367 } 1368 } 1369 } 1371 grouping local-or-keystore-asymmetric-key-grouping { 1372 description 1373 "A grouping that expands to allow the asymmetric key to be 1374 either stored locally, i.e., within the using data model, 1375 or a reference to an asymmetric key stored in the keystore. 1377 Servers that do not 'implement' this module, and hence 1378 'central-keystore-supported' is not defined, SHOULD 1379 augment in custom 'case' statements enabling references 1380 to the alternate keystore locations."; 1381 choice local-or-keystore { 1382 nacm:default-deny-write; 1383 mandatory true; 1384 description 1385 "A choice between an inlined definition and a definition 1386 that exists in the keystore."; 1387 case local { 1388 if-feature "local-definitions-supported"; 1389 container local-definition { 1390 description 1391 "Container to hold the local key definition."; 1392 uses ct:asymmetric-key-pair-grouping; 1393 } 1394 } 1395 case keystore { 1396 if-feature "central-keystore-supported"; 1397 leaf keystore-reference { 1398 type ks:asymmetric-key-ref; 1399 description 1400 "A reference to an asymmetric key that exists in 1401 the keystore, when this module is implemented. The 1402 intent is to reference just the asymmetric key 1403 without any regard for any certificates that may 1404 be associated with it."; 1405 } 1407 } 1408 } 1409 } 1411 grouping local-or-keystore-asymmetric-key-with-certs-grouping { 1412 description 1413 "A grouping that expands to allow an asymmetric key and 1414 its associated certificates to be either stored locally, 1415 i.e., within the using data model, or a reference to an 1416 asymmetric key (and its associated certificates) stored 1417 in the keystore. 1419 Servers that do not 'implement' this module, and hence 1420 'central-keystore-supported' is not defined, SHOULD 1421 augment in custom 'case' statements enabling references 1422 to the alternate keystore locations."; 1423 choice local-or-keystore { 1424 nacm:default-deny-write; 1425 mandatory true; 1426 description 1427 "A choice between an inlined definition and a definition 1428 that exists in the keystore."; 1429 case local { 1430 if-feature "local-definitions-supported"; 1431 container local-definition { 1432 description 1433 "Container to hold the local key definition."; 1434 uses ct:asymmetric-key-pair-with-certs-grouping; 1435 } 1436 } 1437 case keystore { 1438 if-feature "central-keystore-supported"; 1439 leaf keystore-reference { 1440 type ks:asymmetric-key-ref; 1441 description 1442 "A reference to an asymmetric-key (and all of its 1443 associated certificates) in the keystore, when 1444 this module is implemented."; 1445 } 1446 } 1447 } 1448 } 1450 grouping local-or-keystore-end-entity-cert-with-key-grouping { 1451 description 1452 "A grouping that expands to allow an end-entity certificate 1453 (and its associated asymmetric key pair) to be either stored 1454 locally, i.e., within the using data model, or a reference 1455 to a specific certificate in the keystore. 1457 Servers that do not 'implement' this module, and hence 1458 'central-keystore-supported' is not defined, SHOULD 1459 augment in custom 'case' statements enabling references 1460 to the alternate keystore locations."; 1461 choice local-or-keystore { 1462 nacm:default-deny-write; 1463 mandatory true; 1464 description 1465 "A choice between an inlined definition and a definition 1466 that exists in the keystore."; 1467 case local { 1468 if-feature "local-definitions-supported"; 1469 container local-definition { 1470 description 1471 "Container to hold the local key definition."; 1472 uses ct:asymmetric-key-pair-with-cert-grouping; 1473 } 1474 } 1475 case keystore { 1476 if-feature "central-keystore-supported"; 1477 container keystore-reference { 1478 uses asymmetric-key-certificate-ref-grouping; 1479 description 1480 "A reference to a specific certificate associated with 1481 an asymmetric key stored in the keystore, when this 1482 module is implemented."; 1483 } 1484 } 1485 } 1486 } 1488 grouping keystore-grouping { 1489 description 1490 "Grouping definition enables use in other contexts. If ever 1491 done, implementations MUST augment new 'case' statements 1492 into the various local-or-keystore 'choice' statements to 1493 supply leafrefs to the model-specific location(s)."; 1494 container asymmetric-keys { 1495 nacm:default-deny-write; 1496 description 1497 "A list of asymmetric keys."; 1498 list asymmetric-key { 1499 key "name"; 1500 description 1501 "An asymmetric key."; 1502 leaf name { 1503 type string; 1504 description 1505 "An arbitrary name for the asymmetric key."; 1506 } 1507 uses ct:asymmetric-key-pair-with-certs-grouping; 1508 } 1509 } 1510 container symmetric-keys { 1511 nacm:default-deny-write; 1512 description 1513 "A list of symmetric keys."; 1514 list symmetric-key { 1515 key "name"; 1516 description 1517 "A symmetric key."; 1518 leaf name { 1519 type string; 1520 description 1521 "An arbitrary name for the symmetric key."; 1522 } 1523 uses ct:symmetric-key-grouping; 1524 } 1525 } 1526 } 1528 /*********************************/ 1529 /* Protocol accessible nodes */ 1530 /*********************************/ 1532 container keystore { 1533 description 1534 "A central keystore containing a list of symmetric keys and 1535 a list of asymmetric keys."; 1536 nacm:default-deny-write; 1537 uses keystore-grouping { 1538 augment "symmetric-keys/symmetric-key/key-type/encrypted-key/" 1539 + "encrypted-key/encrypted-by" { 1540 description 1541 "Augments in a choice statement enabling the encrypting 1542 key to be any other symmetric or asymmetric key in the 1543 central keystore."; 1544 uses encrypted-by-choice-grouping; 1545 } 1546 augment "asymmetric-keys/asymmetric-key/private-key-type/" 1547 + "encrypted-private-key/encrypted-private-key/" 1548 + "encrypted-by" { 1549 description 1550 "Augments in a choice statement enabling the encrypting 1551 key to be any other symmetric or asymmetric key in the 1552 central keystore."; 1553 uses encrypted-by-choice-grouping; 1554 } 1555 } 1556 } 1557 } 1559 1561 3. Support for Built-in Keys 1563 In some implementations, a server may support built-in keys. Built- 1564 in keys MAY be set during the manufacturing process or be dynamically 1565 generated the first time the server is booted or a particular service 1566 (e.g., SSH) is enabled. 1568 The primary characteristic of the built-in keys is that they are 1569 provided by the system, as opposed to configuration. As such, they 1570 are present in . The example below illustrates what the 1571 keystore in might look like for a server in its factory 1572 default state. 1574 1578 1579 1580 Manufacturer-Generated Hidden Key 1581 1582 ct:subject-public-key-info-format 1583 1584 BASE64VALUE= 1585 1586 1587 1588 Manufacturer-Generated IDevID Cert 1589 BASE64VALUE= 1590 1591 1592 1593 1594 1596 In order for the built-in keys (and their associated built-in 1597 certificates) to be referenced by configuration, the referenced keys 1598 and associated certificates MUST first be copied into . 1600 Built-in keys that are "hidden" MUST be copied into using 1601 the same key values, so that the server can bind them to the built-in 1602 entries. 1604 Built-in keys that are "encrypted" MAY be copied into other parts of 1605 the configuration so long as they are otherwise unmodified (e.g., the 1606 "encrypted-by" reference cannot be altered). 1608 Built-in keys that are "cleartext" MAY be copied into other parts of 1609 the configuration but, by doing so, they lose their association to 1610 the built-in entries and any assurances afforded by knowing they are/ 1611 were built-in. 1613 The built-in keys and built-in associated certificates are immutable 1614 by configuration operations. With exception to additional/custom 1615 certificates associated to a built-in key, servers MUST ignore 1616 attempts to modify any aspect of built-in keys and/or built-in 1617 associated certificates. 1619 The following example illustrates how a single built-in key 1620 definition from the previous example has been propagated to 1621 : 1623 1625 1626 1627 Manufacturer-Generated Hidden Key 1628 1629 ct:subject-public-key-info-format 1630 1631 BASE64VALUE= 1632 1633 1634 1635 Manufacturer-Generated IDevID Cert 1636 BASE64VALUE= 1637 1638 1639 Deployment-Specific LDevID Cert 1640 BASE64VALUE= 1641 1642 1643 1644 1645 1646 After the above configuration is applied, should appear 1647 as follows: 1649 1653 1654 1655 Manufacturer-Generated Hidden Key 1656 1657 ct:subject-public-key-info-format 1658 1659 BASE64VALUE= 1660 1661 1662 1663 Manufacturer-Generated IDevID Cert 1664 BASE64VALUE= 1665 1666 1667 Deployment-Specific LDevID Cert 1668 BASE64VALUE= 1669 1670 1671 1672 1673 1675 4. Encrypting Keys in Configuration 1677 This section describes an approach that enables both the symmetric 1678 and asymmetric keys on a server to be encrypted, such that 1679 traditional backup/restore procedures can be used without concern for 1680 the keys being compromised when in transit. 1682 4.1. Key Encryption Key 1684 The ability to encrypt configured keys is predicated on the existence 1685 of a "key encryption key" (KEK). There may be any number of KEKs in 1686 a system. A KEK, by its namesake, is a key that is used to encrypt 1687 other keys. A KEK MAY be either a symmetric key or an asymmetric 1688 key. 1690 If a KEK is a symmetric key, then the server MUST provide an API for 1691 administrators to encrypt other keys without needing to know the 1692 symmetric key's value. If the KEK is an asymmetric key, then the 1693 server MAY provide an API enabling the encryption of other keys or, 1694 alternatively, let the administrators do so themselves using the 1695 asymmetric key's public half. 1697 A server MUST possess (or be able to possess, in case the KEK has 1698 been encrypted by another KEK) a KEK's cleartext value so that it can 1699 decrypt the other keys in the configuration at runtime. 1701 4.2. Configuring Encrypted Keys 1703 Each time a new key is configured, it SHOULD be encrypted by a KEK. 1705 In "ietf-crypto-types" [I-D.ietf-netconf-crypto-types], the format 1706 for encrypted values is described by identity statements derived from 1707 the "symmetrically-encrypted-value-format" and "symmetrically- 1708 encrypted-value-format" identity statements. 1710 Implementations SHOULD provide an API that simultaneously generates 1711 and encrypts a key (symmetric or asymmetric) using a KEK. Thusly 1712 newly generated key cleartext values may never known to the 1713 administrators generating the keys. 1715 In case the server implementation does not provide such an API, then 1716 the generating and encrypting steps MAY be performed outside the 1717 server, e.g., by an administrator with special access control rights 1718 (e.g., an organization's crypto officer). 1720 In either case, the encrypted key can be configured into the keystore 1721 using either the "encrypted-key" (for symmetric keys) or the 1722 "encrypted-private-key" (for asymmetric keys) nodes. These two nodes 1723 contain both the encrypted value as well as a reference to the KEK 1724 that encrypted the key. 1726 4.3. Migrating Configuration to Another Server 1728 When a KEK is used to encrypt other keys, migrating the configuration 1729 to another server is only possible if the second server has the same 1730 KEK. How the second server comes to have the same KEK is discussed 1731 in this section. 1733 In some deployments, mechanisms outside the scope of this document 1734 may be used to migrate a KEK from one server to another. That said, 1735 beware that the ability to do so typically entails having access to 1736 the first server but, in many scenarios, the first server may no 1737 longer be operational. 1739 In other deployments, an organization's crypto officer, possessing a 1740 KEK's cleartext value, configures the same KEK on the second server, 1741 presumably as a hidden key or a key protected by access-control 1742 (e.g., NACM's "default-deny-all"), so that the cleartext value is not 1743 disclosed to regular administrators. However, this approach creates 1744 high-coupling to and dependency on the crypto officers that does not 1745 scale in production environments. 1747 In order to decouple the crypto officers from the regular 1748 administrators, a special KEK, called the "master key" (MK), may be 1749 used. 1751 A MK is commonly a globally-unique built-in (see Section 3) 1752 asymmetric key. The private key, due to its long lifetime, is hidden 1753 (i.e., "hidden-private-key" in Section 2.1.4.5. of 1754 [I-D.ietf-netconf-crypto-types]). The public key is often contained 1755 in an identity certificate (e.g., IDevID). How to configure a MK 1756 during the manufacturing process is outside the scope of this 1757 document. 1759 It is RECOMMENDED that MKs are built-in and hidden but, if this is 1760 not possible, access control mechanisms like NACM SHOULD be used to 1761 limit access to the MK's secret data only to the most trusted 1762 authorized clients (e.g., an organization's crypto officer). In this 1763 case, it is RECOMMENDED that the MK is not built-in and hence is, 1764 effectively, just like a KEK. 1766 Assuming the server has a MK, the MK can be used to encrypt a "shared 1767 KEK", which is then used to encrypt the keys configured by regular 1768 administrators. 1770 With this extra level of indirection, it is possible for a crypto 1771 officer to encrypt the same KEK for a multiplicity of servers offline 1772 using the public key contained in their identity certificates. The 1773 crypto officer can then safely handoff the encrypted KEKs to the 1774 regular administrators responsible for server installations, 1775 including migrations. 1777 In order to migrate the configuration from a first server, an 1778 administrator would need to make just a single modification to the 1779 configuration before loading it onto a second server, which is to 1780 replace the encrypted KEK keystore entry from the first server with 1781 the encrypted KEK for the second server. Upon doing this, the 1782 configuration (containing many encrypted keys) can be loaded into the 1783 second server while enabling the second server to decrypt all the 1784 encrypted keys in the configuration. 1786 The following diagram illustrates this idea: 1788 +-------------+ +-------------+ 1789 | shared KEK | | shared KEK | 1790 |(unencrypted)|-------------------------------> | (encrypted) | 1791 +-------------+ encrypts offline using +-------------+ 1792 ^ each server's MK | 1793 | | 1794 | | 1795 | possesses \o | 1796 +-------------- |\ | 1797 / \ shares with | 1798 crypto +--------------------+ 1799 officer | 1800 | 1801 | 1802 +----------------------+ | +----------------------+ 1803 | server-1 | | | server-2 | 1804 | configuration | | | configuration | 1805 | | | | | 1806 | | | | | 1807 | +----------------+ | | | +----------------+ | 1808 | | MK-1 | | | | | MK-2 | | 1809 | | (hidden) | | | | | (hidden) | | 1810 | +----------------+ | | | +----------------+ | 1811 | ^ | | | ^ | 1812 | | | | | | | 1813 | | | | | | | 1814 | | encrypted | | | | encrypted | 1815 | | by | | | | by | 1816 | | | | | | | 1817 | | | | | | | 1818 | +----------------+ | | | +----------------+ | 1819 | | shared KEK | | | | | shared KEK | | 1820 | | (encrypted) | | v | | (encrypted) | | 1821 | +----------------+ | | +----------------+ | 1822 | ^ | regular | ^ | 1823 | | | admin | | | 1824 | | | | | | 1825 | | encrypted | \o | | encrypted | 1826 | | by | |\ | | by | 1827 | | | / \ | | | 1828 | | | | | | 1829 | +----------------+ |----------------->| +----------------+ | 1830 | | all other keys | | migrate | | all other keys | | 1831 | | (encrypted) | | configuration | | (encrypted) | | 1832 | +----------------+ | | +----------------+ | 1833 | | | | 1834 +----------------------+ +----------------------+ 1836 5. Security Considerations 1838 5.1. Security of Data at Rest 1840 The YANG module defined in this document defines a mechanism called a 1841 "keystore" that, by its name, suggests that it will protect its 1842 contents from unauthorized disclosure and modification. 1844 Security controls for the API (i.e., data in motion) are discussed in 1845 Section 5.3, but controls for the data at rest cannot be specified by 1846 the YANG module. 1848 In order to satisfy the expectations of a "keystore", it is 1849 RECOMMENDED that implementations ensure that the keystore contents 1850 are encrypted when persisted to non-volatile memory. 1852 5.2. Unconstrained Private Key Usage 1854 This module enables the configuration of private keys without 1855 constraints on their usage, e.g., what operations the key is allowed 1856 to be used for (e.g., signature, decryption, both). 1858 This module also does not constrain the usage of the associated 1859 public keys, other than in the context of a configured certificate 1860 (e.g., an identity certificate), in which case the key usage is 1861 constrained by the certificate. 1863 5.3. The "ietf-keystore" YANG Module 1865 The YANG module defined in this document is designed to be accessed 1866 via YANG based management protocols, such as NETCONF [RFC6241] and 1867 RESTCONF [RFC8040]. Both of these protocols have mandatory-to- 1868 implement secure transport layers (e.g., SSH, TLS) with mutual 1869 authentication. 1871 The NETCONF access control model (NACM) [RFC8341] provides the means 1872 to restrict access for particular users to a pre-configured subset of 1873 all available protocol operations and content. 1875 None of the readable data nodes defined in this YANG module are 1876 considered sensitive or vulnerable in network environments. The NACM 1877 "default-deny-all" extension has not been set for any data nodes 1878 defined in this module. 1880 | Please be aware that this module uses the "cleartext-key" and 1881 | "cleartext-private-key" nodes from the "ietf-crypto-types" 1882 | module [I-D.ietf-netconf-crypto-types], where said nodes have 1883 | the NACM extension "default-deny-all" set, thus preventing 1884 | uncontrolled read-access to the cleartext key values. 1886 All the writable data nodes defined by this module, both in the 1887 "grouping" statements as well as the protocol-accessible "keystore" 1888 instance, may be considered sensitive or vulnerable in some network 1889 environments.. For instance, any modification to a key or reference 1890 to a key may dramatically alter the implemented security policy. For 1891 this reason, the NACM extension "default-deny-write" has been set for 1892 all data nodes defined in this module. 1894 This module does not define any "rpc" or "action" statements, and 1895 thus the security considerations for such is not provided here. 1897 6. IANA Considerations 1899 6.1. The "IETF XML" Registry 1901 This document registers one URI in the "ns" subregistry of the IETF 1902 XML Registry [RFC3688]. Following the format in [RFC3688], the 1903 following registration is requested: 1905 URI: urn:ietf:params:xml:ns:yang:ietf-keystore 1906 Registrant Contact: The IESG 1907 XML: N/A, the requested URI is an XML namespace. 1909 6.2. The "YANG Module Names" Registry 1911 This document registers one YANG module in the YANG Module Names 1912 registry [RFC6020]. Following the format in [RFC6020], the following 1913 registration is requested: 1915 name: ietf-keystore 1916 namespace: urn:ietf:params:xml:ns:yang:ietf-keystore 1917 prefix: ks 1918 reference: RFC CCCC 1920 7. References 1922 7.1. Normative References 1924 [I-D.ietf-netconf-crypto-types] 1925 Watsen, K., "YANG Data Types and Groupings for 1926 Cryptography", Work in Progress, Internet-Draft, draft- 1927 ietf-netconf-crypto-types-21, 14 September 2021, 1928 . 1931 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1932 Requirement Levels", BCP 14, RFC 2119, 1933 DOI 10.17487/RFC2119, March 1997, 1934 . 1936 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1937 the Network Configuration Protocol (NETCONF)", RFC 6020, 1938 DOI 10.17487/RFC6020, October 2010, 1939 . 1941 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1942 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1943 . 1945 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 1946 Access Control Model", STD 91, RFC 8341, 1947 DOI 10.17487/RFC8341, March 2018, 1948 . 1950 7.2. Informative References 1952 [I-D.ietf-netconf-http-client-server] 1953 Watsen, K., "YANG Groupings for HTTP Clients and HTTP 1954 Servers", Work in Progress, Internet-Draft, draft-ietf- 1955 netconf-http-client-server-07, 18 May 2021, 1956 . 1959 [I-D.ietf-netconf-keystore] 1960 Watsen, K., "A YANG Data Model for a Keystore", Work in 1961 Progress, Internet-Draft, draft-ietf-netconf-keystore-22, 1962 18 May 2021, . 1965 [I-D.ietf-netconf-netconf-client-server] 1966 Watsen, K., "NETCONF Client and Server Models", Work in 1967 Progress, Internet-Draft, draft-ietf-netconf-netconf- 1968 client-server-23, 18 May 2021, 1969 . 1972 [I-D.ietf-netconf-restconf-client-server] 1973 Watsen, K., "RESTCONF Client and Server Models", Work in 1974 Progress, Internet-Draft, draft-ietf-netconf-restconf- 1975 client-server-23, 18 May 2021, 1976 . 1979 [I-D.ietf-netconf-ssh-client-server] 1980 Watsen, K., "YANG Groupings for SSH Clients and SSH 1981 Servers", Work in Progress, Internet-Draft, draft-ietf- 1982 netconf-ssh-client-server-25, 18 June 2021, 1983 . 1986 [I-D.ietf-netconf-tcp-client-server] 1987 Watsen, K. and M. Scharf, "YANG Groupings for TCP Clients 1988 and TCP Servers", Work in Progress, Internet-Draft, draft- 1989 ietf-netconf-tcp-client-server-10, 18 May 2021, 1990 . 1993 [I-D.ietf-netconf-tls-client-server] 1994 Watsen, K., "YANG Groupings for TLS Clients and TLS 1995 Servers", Work in Progress, Internet-Draft, draft-ietf- 1996 netconf-tls-client-server-25, 18 June 2021, 1997 . 2000 [I-D.ietf-netconf-trust-anchors] 2001 Watsen, K., "A YANG Data Model for a Truststore", Work in 2002 Progress, Internet-Draft, draft-ietf-netconf-trust- 2003 anchors-15, 18 May 2021, 2004 . 2007 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2008 DOI 10.17487/RFC3688, January 2004, 2009 . 2011 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2012 and A. Bierman, Ed., "Network Configuration Protocol 2013 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2014 . 2016 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2017 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2018 . 2020 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2021 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2022 May 2017, . 2024 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 2025 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 2026 . 2028 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 2029 and R. Wilton, "Network Management Datastore Architecture 2030 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 2031 . 2033 [Std-802.1AR-2018] 2034 IEEE SA-Standards Board, "IEEE Standard for Local and 2035 metropolitan area networks - Secure Device Identity", 2036 August 2018, 2037 . 2039 Appendix A. Change Log 2041 This section is to be removed before publishing as an RFC. 2043 A.1. 00 to 01 2045 * Replaced the 'certificate-chain' structures with PKCS#7 2046 structures. (Issue #1) 2048 * Added 'private-key' as a configurable data node, and removed the 2049 'generate-private-key' and 'load-private-key' actions. (Issue #2) 2051 * Moved 'user-auth-credentials' to the ietf-ssh-client module. 2052 (Issues #4 and #5) 2054 A.2. 01 to 02 2056 * Added back 'generate-private-key' action. 2058 * Removed 'RESTRICTED' enum from the 'private-key' leaf type. 2060 * Fixed up a few description statements. 2062 A.3. 02 to 03 2064 * Changed draft's title. 2066 * Added missing references. 2068 * Collapsed sections and levels. 2070 * Added RFC 8174 to Requirements Language Section. 2072 * Renamed 'trusted-certificates' to 'pinned-certificates'. 2074 * Changed 'public-key' from config false to config true. 2076 * Switched 'host-key' from OneAsymmetricKey to definition from RFC 2077 4253. 2079 A.4. 03 to 04 2081 * Added typedefs around leafrefs to common keystore paths 2083 * Now tree diagrams reference ietf-netmod-yang-tree-diagrams 2085 * Removed Design Considerations section 2087 * Moved key and certificate definitions from data tree to groupings 2089 A.5. 04 to 05 2091 * Removed trust anchors (now in their own draft) 2093 * Added back global keystore structure 2095 * Added groupings enabling keys to either be locally defined or a 2096 reference to the keystore. 2098 A.6. 05 to 06 2100 * Added feature "local-keys-supported" 2102 * Added nacm:default-deny-all and nacm:default-deny-write 2104 * Renamed generate-asymmetric-key to generate-hidden-key 2106 * Added an install-hidden-key action 2108 * Moved actions inside fo the "asymmetric-key" container 2110 * Moved some groupings to draft-ietf-netconf-crypto-types 2112 A.7. 06 to 07 2114 * Removed a "require-instance false" 2115 * Clarified some description statements 2117 * Improved the keystore-usage examples 2119 A.8. 07 to 08 2121 * Added "local-definition" containers to avoid posibility of the 2122 action/notification statements being under a "case" statement. 2124 * Updated copyright date, boilerplate template, affiliation, folding 2125 algorithm, and reformatted the YANG module. 2127 A.9. 08 to 09 2129 * Added a 'description' statement to the 'must' in the /keystore/ 2130 asymmetric-key node explaining that the descendant values may 2131 exist in only, and that implementation MUST assert 2132 that the values are either configured or that they exist in 2133 . 2135 * Copied above 'must' statement (and description) into the local-or- 2136 keystore-asymmetric-key-grouping, local-or-keystore-asymmetric- 2137 key-with-certs-grouping, and local-or-keystore-end-entity-cert- 2138 with-key-grouping statements. 2140 A.10. 09 to 10 2142 * Updated draft title to match new truststore draft title 2144 * Moved everything under a top-level 'grouping' to enable use in 2145 other contexts. 2147 * Renamed feature from 'local-keys-supported' to 'local-definitions- 2148 supported' (same name used in truststore) 2150 * Removed the either-all-or-none 'must' expressions for the key's 2151 3-tuple values (since the values are now 'mandatory true' in 2152 crypto-types) 2154 * Example updated to reflect 'mandatory true' change in crypto-types 2155 draft 2157 A.11. 10 to 11 2159 * Replaced typedef asymmetric-key-certificate-ref with grouping 2160 asymmetric-key-certificate-ref-grouping. 2162 * Added feature feature 'key-generation'. 2164 * Cloned groupings symmetric-key-grouping, asymmetric-key-pair- 2165 grouping, asymmetric-key-pair-with-cert-grouping, and asymmetric- 2166 key-pair-with-certs-grouping from crypto-keys, augmenting into 2167 each new case statements for values that have been encrypted by 2168 other keys in the keystore. Refactored keystore model to use 2169 these groupings. 2171 * Added new 'symmetric-keys' lists, as a sibling to the existing 2172 'asymmetric-keys' list. 2174 * Added RPCs (not actions) 'generate-symmetric-key' and 'generate- 2175 asymmetric-key' to *return* a (potentially encrypted) key. 2177 A.12. 11 to 12 2179 * Updated to reflect crypto-type's draft using enumerations over 2180 identities. 2182 * Added examples for the 'generate-symmetric-key' and 'generate- 2183 asymmetric-key' RPCs. 2185 * Updated the Introduction section. 2187 A.13. 12 to 13 2189 * Updated examples to incorporate new "key-format" identities. 2191 * Made the two "generate-*-key" RPCs be "action" statements instead. 2193 A.14. 13 to 14 2195 * Updated YANG module and examples to incorporate the new 2196 iana-*-algorithm modules in the crypto-types draft.. 2198 A.15. 14 to 15 2200 * Added new "Support for Built-in Keys" section. 2202 * Added 'must' expressions asserting that the 'key-format' leaf 2203 whenever an encrypted key is specified. 2205 * Added local-or-keystore-symmetric-key-grouping for PSK support. 2207 A.16. 15 to 16 2209 * Moved the generate key actions to ietf-crypt-types as RPCs, which 2210 are augmented by ietf-keystore to support encrypted keys. 2211 Examples updated accordingly. 2213 * Added a SSH certificate-based key (RFC 6187) and a raw private key 2214 to the example instance document (partly so they could be 2215 referenced by examples in the SSH and TLS client/server drafts. 2217 A.17. 16 to 17 2219 * Removed augments to the "generate-symmetric-key" and "generate- 2220 asymmetric-key" groupings. 2222 * Removed "generate-symmetric-key" and "generate-asymmetric-key" 2223 examples. 2225 * Removed the "algorithm" nodes from remaining examples. 2227 * Updated the "Support for Built-in Keys" section. 2229 * Added new section "Encrypting Keys in Configuration". 2231 * Added a "Note to Reviewers" note to first page. 2233 A.18. 17 to 18 2235 * Removed dangling/unnecessary ref to RFC 8342. 2237 * r/MUST/SHOULD/ wrt strength of keys being configured over 2238 transports. 2240 * Added an example for the "certificate-expiration" notification. 2242 * Clarified that OS MAY have a multiplicity of underlying keystores 2243 and/or HSMs. 2245 * Clarified expected behavior for "built-in" keys in 2247 * Clarified the "Migrating Configuration to Another Server" section. 2249 * Expanded "Data Model Overview section(s) [remove "wall" of tree 2250 diagrams]. 2252 * Updated the Security Considerations section. 2254 A.19. 18 to 19 2256 * Updated examples to reflect new "cleartext-" prefix in the crypto- 2257 types draft. 2259 A.20. 19 to 20 2260 * Addressed SecDir comments from Magnus Nystroem and Sandra Murphy. 2262 A.21. 20 to 21 2264 * Added a "Unconstrained Private Key Usage" Security Consideration 2265 to address concern raised by SecDir. 2267 * (Editorial) Removed the output of "grouping" statements in the 2268 tree diagrams for the "ietf-keystore" and "ex-keystore-usage" 2269 modules. 2271 * Addressed comments raised by YANG Doctor. 2273 A.22. 21 to 22 2275 * Added prefixes to 'path' statements per trust-anchors/issues/1 2277 * Renamed feature "keystore-supported" to "central-keystore- 2278 supported". 2280 * Associated with above, generally moved text to refer to a 2281 "central" keystore. 2283 * Aligned modules with `pyang -f` formatting. 2285 * Fixed nits found by YANG Doctor reviews. 2287 A.23. 22 to 23 2289 * Updated 802.1AR ref to latest version 2291 * Replaced "base64encodedvalue==" with "BASE64VALUE=" in examples. 2293 * Minor editorial nits 2295 Acknowledgements 2297 The authors would like to thank for following for lively discussions 2298 on list and in the halls (ordered by first name): Alan Luchuk, Andy 2299 Bierman, Benoit Claise, Bert Wijnen, Balazs Kovacs, David Lamparter, 2300 Eric Voit, Ladislav Lhotka, Liang Xia, Juergen Schoenwaelder, Mahesh 2301 Jethanandani, Magnus Nystroem, Martin Bjoerklund, Mehmet Ersue, Phil 2302 Shafer, Radek Krejci, Ramkumar Dhanapal, Reshad Rahman, Sandra 2303 Murphy, Sean Turner, and Tom Petch. 2305 Author's Address 2306 Kent Watsen 2307 Watsen Networks 2309 Email: kent+ietf@watsen.net