idnits 2.17.1 draft-ietf-netconf-keystore-20.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 599 has weird spacing: '...d-value bin...' == Line 606 has weird spacing: '...on-date yan...' == Line 610 has weird spacing: '...sr-info ct:...' == Line 612 has weird spacing: '...request ct:...' == Line 632 has weird spacing: '...d-value bin...' == (25 more instances...) -- The document date (20 August 2020) is 1338 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 (-34) exists of draft-ietf-netconf-crypto-types-17 == Outdated reference: A later version (-20) exists of draft-ietf-netconf-http-client-server-04 == Outdated reference: A later version (-35) exists of draft-ietf-netconf-keystore-19 == Outdated reference: A later version (-36) exists of draft-ietf-netconf-netconf-client-server-20 == Outdated reference: A later version (-36) exists of draft-ietf-netconf-restconf-client-server-20 == Outdated reference: A later version (-40) exists of draft-ietf-netconf-ssh-client-server-21 == Outdated reference: A later version (-26) exists of draft-ietf-netconf-tcp-client-server-07 == Outdated reference: A later version (-41) exists of draft-ietf-netconf-tls-client-server-21 == Outdated reference: A later version (-28) exists of draft-ietf-netconf-trust-anchors-12 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 20 August 2020 5 Expires: 21 February 2021 7 A YANG Data Model for a Keystore 8 draft-ietf-netconf-keystore-20 10 Abstract 12 This document defines a YANG 1.1 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 * "2020-08-20" --> 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 21 February 2021. 59 Copyright Notice 61 Copyright (c) 2020 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 Simplified BSD License text 70 as described in Section 4.e of the Trust Legal Provisions and are 71 provided without warranty as described in the Simplified BSD License. 73 Table of Contents 75 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 76 1.1. Relation to other RFCs . . . . . . . . . . . . . . . . . 4 77 1.2. Specification Language . . . . . . . . . . . . . . . . . 5 78 1.3. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 79 1.4. Adherence to the NMDA . . . . . . . . . . . . . . . . . . 6 80 2. The "ietf-keystore" Module . . . . . . . . . . . . . . . . . 6 81 2.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 6 82 2.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 17 83 2.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 29 84 3. Support for Built-in Keys . . . . . . . . . . . . . . . . . . 37 85 4. Encrypting Keys in Configuration . . . . . . . . . . . . . . 40 86 5. Security Considerations . . . . . . . . . . . . . . . . . . . 44 87 5.1. Data at Rest . . . . . . . . . . . . . . . . . . . . . . 44 88 5.2. The "ietf-keystore" YANG Module . . . . . . . . . . . . . 44 89 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 45 90 6.1. The "IETF XML" Registry . . . . . . . . . . . . . . . . . 45 91 6.2. The "YANG Module Names" Registry . . . . . . . . . . . . 45 92 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 45 93 7.1. Normative References . . . . . . . . . . . . . . . . . . 45 94 7.2. Informative References . . . . . . . . . . . . . . . . . 46 96 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 48 97 A.1. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 48 98 A.2. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 48 99 A.3. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 48 100 A.4. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 48 101 A.5. 04 to 05 . . . . . . . . . . . . . . . . . . . . . . . . 49 102 A.6. 05 to 06 . . . . . . . . . . . . . . . . . . . . . . . . 49 103 A.7. 06 to 07 . . . . . . . . . . . . . . . . . . . . . . . . 49 104 A.8. 07 to 08 . . . . . . . . . . . . . . . . . . . . . . . . 49 105 A.9. 08 to 09 . . . . . . . . . . . . . . . . . . . . . . . . 49 106 A.10. 09 to 10 . . . . . . . . . . . . . . . . . . . . . . . . 50 107 A.11. 10 to 11 . . . . . . . . . . . . . . . . . . . . . . . . 50 108 A.12. 11 to 12 . . . . . . . . . . . . . . . . . . . . . . . . 50 109 A.13. 12 to 13 . . . . . . . . . . . . . . . . . . . . . . . . 51 110 A.14. 13 to 14 . . . . . . . . . . . . . . . . . . . . . . . . 51 111 A.15. 14 to 15 . . . . . . . . . . . . . . . . . . . . . . . . 51 112 A.16. 15 to 16 . . . . . . . . . . . . . . . . . . . . . . . . 51 113 A.17. 16 to 17 . . . . . . . . . . . . . . . . . . . . . . . . 51 114 A.18. 17 to 18 . . . . . . . . . . . . . . . . . . . . . . . . 52 115 A.19. 18 to 19 . . . . . . . . . . . . . . . . . . . . . . . . 52 116 A.20. 19 to 20 . . . . . . . . . . . . . . . . . . . . . . . . 52 117 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 52 118 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 52 120 1. Introduction 122 This document defines a YANG 1.1 [RFC7950] module called "ietf- 123 keystore" that enables centralized configuration of both symmetric 124 and asymmetric keys. The secret value for both key types may be 125 encrypted or hidden (see [I-D.ietf-netconf-crypto-types]. Asymmetric 126 keys may be associated with certificates. Notifications are sent 127 when certificates are about to expire. 129 The "ietf-keystore" module defines many "grouping" statements 130 intended for use by other modules that may import it. For instance, 131 there are groupings that define enabling a key to be either 132 configured locally (within the defining data model) or be a reference 133 to a key in the Keystore. 135 Special consideration has been given for systems that have 136 cryptographic hardware, such as a Trusted Platform Module (TPM). 137 These systems are unique in that the cryptographic hardware hides the 138 secret key values. Additionally, such hardware is commonly 139 initiailized when manufactured to protect a "built-in" asymmetric key 140 for which the public half is conveyed in an identity certificate 141 (e.g., an IDevID [Std-802.1AR-2009] certificate). Please see 142 Section 3 to see how built-in keys are supported. 144 This document intends to support existing practices; it does not 145 intend to define new behvior for systems to implement. To simplify 146 implementation, advanced key formats may be selectively implemented. 148 Implementations may utilize zero or more operating system level 149 keystore utilities and/or hardware security modules (HSMs). 151 1.1. Relation to other RFCs 153 This document presents one or more YANG modules [RFC7950] that are 154 part of a collection of RFCs that work together to define 155 configuration modules for clients and servers of both the NETCONF 156 [RFC6241] and RESTCONF [RFC8040] protocols. 158 The modules have been defined in a modular fashion to enable their 159 use by other efforts, some of which are known to be in progress at 160 the time of this writing, with many more expected to be defined in 161 time. 163 The normative dependency relationship between the various RFCs in the 164 collection is presented in the below diagram. The labels in the 165 diagram represent the primary purpose provided by each RFC. 166 Hyperlinks to each RFC are provided below the diagram. 168 crypto-types 169 ^ ^ 170 / \ 171 / \ 172 truststore keystore 173 ^ ^ ^ ^ 174 | +---------+ | | 175 | | | | 176 | +------------+ | 177 tcp-client-server | / | | 178 ^ ^ ssh-client-server | | 179 | | ^ tls-client-server 180 | | | ^ ^ http-client-server 181 | | | | | ^ 182 | | | +-----+ +---------+ | 183 | | | | | | 184 | +-----------|--------|--------------+ | | 185 | | | | | | 186 +-----------+ | | | | | 187 | | | | | | 188 | | | | | | 189 netconf-client-server restconf-client-server 191 +=======================+===========================================+ 192 | Label in Diagram | Originating RFC | 193 +=======================+===========================================+ 194 | crypto-types | [I-D.ietf-netconf-crypto-types] | 195 +-----------------------+-------------------------------------------+ 196 | truststore | [I-D.ietf-netconf-trust-anchors] | 197 +-----------------------+-------------------------------------------+ 198 | keystore | [I-D.ietf-netconf-keystore] | 199 +-----------------------+-------------------------------------------+ 200 | tcp-client-server | [I-D.ietf-netconf-tcp-client-server] | 201 +-----------------------+-------------------------------------------+ 202 | ssh-client-server | [I-D.ietf-netconf-ssh-client-server] | 203 +-----------------------+-------------------------------------------+ 204 | tls-client-server | [I-D.ietf-netconf-tls-client-server] | 205 +-----------------------+-------------------------------------------+ 206 | http-client-server | [I-D.ietf-netconf-http-client-server] | 207 +-----------------------+-------------------------------------------+ 208 | netconf-client-server | [I-D.ietf-netconf-netconf-client-server] | 209 +-----------------------+-------------------------------------------+ 210 |restconf-client-server | [I-D.ietf-netconf-restconf-client-server] | 211 +-----------------------+-------------------------------------------+ 213 Table 1: Label to RFC Mapping 215 1.2. Specification Language 217 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 218 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 219 "OPTIONAL" in this document are to be interpreted as described in BCP 220 14 [RFC2119] [RFC8174] when, and only when, they appear in all 221 capitals, as shown here. 223 1.3. Terminology 225 The terms "client" and "server" are defined in [RFC6241] and are not 226 redefined here. 228 The term "keystore" is defined in this draft as a mechanism that 229 intends safeguard secrets placed into it for protection. 231 The nomenclature "" and "" are defined in 232 [RFC8342]. 234 The sentence fragments "augmented" and "augmented in" are used herein 235 as the past tense verbified form of the "augment" statement defined 236 in Section 7.17 of [RFC7950]. 238 1.4. Adherence to the NMDA 240 This document is compliant with Network Management Datastore 241 Architecture (NMDA) [RFC8342]. For instance, keys and associated 242 certificates installed during manufacturing (e.g., for an IDevID 243 certificate) are expected to appear in (see Section 3). 245 2. The "ietf-keystore" Module 247 This section defines a YANG 1.1 [RFC7950] module called "ietf- 248 keystore". A high-level overview of the module is provided in 249 Section 2.1. Examples illustatrating the module's use are provided 250 in Examples (Section 2.2). The YANG module itself is defined in 251 Section 2.3. 253 2.1. Data Model Overview 255 This section provides an overview of the "ietf-keystore" module in 256 terms of its features, typedefs, groupings, and protocol-accessible 257 nodes. 259 2.1.1. Features 261 The following diagram lists all the "feature" statements defined in 262 the "ietf-keystore" module: 264 Features: 265 +-- keystore-supported 266 +-- local-definitions-supported 268 | The diagram above uses syntax that is similar to but not 269 | defined in [RFC8340]. 271 2.1.2. Typedefs 273 The following diagram lists the "typedef" statements defined in the 274 "ietf-keystore" module: 276 Typedefs: 277 leafref 278 +-- symmetric-key-ref 279 +-- asymmetric-key-ref 281 | The diagram above uses syntax that is similar to but not 282 | defined in [RFC8340]. 284 Comments: 286 * All of the typedefs defined in the "ietf-keystore" module extend 287 the base "leafref" type defined in [RFC7950]. 289 * The leafrefs refer to symmetric and asymmetric keys in the 290 keystore. These typedefs are provided primarily as an aid to 291 downstream modules that import the "ietf-keystore" module. 293 2.1.3. Groupings 295 The following diagram lists all the "grouping" statements defined in 296 the "ietf-keystore" module: 298 Groupings: 299 +-- encrypted-by-choice-grouping 300 +-- asymmetric-key-certificate-ref-grouping 301 +-- local-or-keystore-symmetric-key-grouping 302 +-- local-or-keystore-asymmetric-key-grouping 303 +-- local-or-keystore-asymmetric-key-with-certs-grouping 304 +-- local-or-keystore-end-entity-cert-with-key-grouping 305 +-- keystore-grouping 307 | The diagram above uses syntax that is similar to but not 308 | defined in [RFC8340]. 310 Each of these groupings are presented in the following subsections. 312 2.1.3.1. The "encrypted-by-choice-grouping" Grouping 314 The following tree diagram [RFC8340] illustrates the "encrypted-by- 315 choice-grouping" grouping: 317 | The grouping's name is intended to be parsed "(encrypted- 318 | by)-(choice)-(grouping)", not as "(encrypted)-(by- 319 | choice)-(grouping)". 321 grouping encrypted-by-choice-grouping 322 +-- (encrypted-by-choice) 323 +--:(symmetric-key-ref) 324 | +-- symmetric-key-ref? ks:symmetric-key-ref 325 +--:(asymmetric-key-ref) 326 +-- asymmetric-key-ref? ks:asymmetric-key-ref 328 Comments: 330 * This grouping defines a "choice" statement with options to 331 reference either a symmetric or an asymmetric key configured in 332 the keystore. 334 2.1.3.2. The "asymmetric-key-certificate-ref-grouping" Grouping 336 The following tree diagram [RFC8340] illustrates the "asymmetric-key- 337 certificate-ref-grouping" grouping: 339 grouping asymmetric-key-certificate-ref-grouping 340 +-- asymmetric-key? ks:asymmetric-key-ref 341 +-- certificate? leafref 343 Comments: 345 * This grouping defines a reference to a certificate in two parts: 346 the first being the name of the asymmetric key the certificate is 347 associated with, and the second being the name of the certificate 348 itself. 350 2.1.3.3. The "local-or-keystore-symmetric-key-grouping" Grouping 352 The following tree diagram [RFC8340] illustrates the "local-or- 353 keystore-symmetric-key-grouping" grouping: 355 grouping local-or-keystore-symmetric-key-grouping 356 +-- (local-or-keystore) 357 +--:(local) {local-definitions-supported}? 358 | +-- local-definition 359 | +---u ct:symmetric-key-grouping 360 +--:(keystore) {keystore-supported}? 361 +-- keystore-reference? ks:symmetric-key-ref 363 Comments: 365 * The "local-or-keystore-symmetric-key-grouping" grouping is 366 provided soley as convenience to downstream modules that wish to 367 offer an option for whether a symmetric key is defined locally or 368 as a reference to a symmetric key in the keystore. 370 * A "choice" statement is used to expose the various options. Each 371 option is enabled by a "feature" statement. Additional "case" 372 statements MAY be augmented in if, e.g., there is a need to 373 reference a symmetric key in an alternate location. 375 * For the "local-definition" option, the defintion uses the 376 "symmetric-key-grouping" grouping discussed in Section 2.1.4.3 of 377 [I-D.ietf-netconf-crypto-types]. 379 * For the "keystore" option, the "keystore-reference" is an instance 380 of the "symmetric-key-ref" discussed in Section 2.1.2. 382 2.1.3.4. The "local-or-keystore-asymmetric-key-grouping" Grouping 384 The following tree diagram [RFC8340] illustrates the "local-or- 385 keystore-asymmetric-key-grouping" grouping: 387 grouping local-or-keystore-asymmetric-key-grouping 388 +-- (local-or-keystore) 389 +--:(local) {local-definitions-supported}? 390 | +-- local-definition 391 | +---u ct:asymmetric-key-pair-grouping 392 +--:(keystore) {keystore-supported}? 393 +-- keystore-reference? ks:asymmetric-key-ref 395 Comments: 397 * The "local-or-keystore-asymmetric-key-grouping" grouping is 398 provided soley as convenience to downstream modules that wish to 399 offer an option for whether an asymmetric key is defined locally 400 or as a reference to an asymmetric key in the keystore. 402 * A "choice" statement is used to expose the various options. Each 403 option is enabled by a "feature" statement. Additional "case" 404 statements MAY be augmented in if, e.g., there is a need to 405 reference an asymmetric key in an alternate location. 407 * For the "local-definition" option, the defintion uses the 408 "asymmetric-key-pair-grouping" grouping discussed in 409 Section 2.1.4.5 of [I-D.ietf-netconf-crypto-types]. 411 * For the "keystore" option, the "keystore-reference" is an instance 412 of the "asymmetric-key-ref" typedef discussed in Section 2.1.2. 414 2.1.3.5. The "local-or-keystore-asymmetric-key-with-certs-grouping" 415 Grouping 417 The following tree diagram [RFC8340] illustrates the "local-or- 418 keystore-asymmetric-key-with-certs-grouping" grouping: 420 grouping local-or-keystore-asymmetric-key-with-certs-grouping 421 +-- (local-or-keystore) 422 +--:(local) {local-definitions-supported}? 423 | +-- local-definition 424 | +---u ct:asymmetric-key-pair-with-certs-grouping 425 +--:(keystore) {keystore-supported}? 426 +-- keystore-reference? ks:asymmetric-key-ref 428 Comments: 430 * The "local-or-keystore-asymmetric-key-with-certs-grouping" 431 grouping is provided soley as convenience to downstream modules 432 that wish to offer an option for whether an asymmetric key is 433 defined locally or as a reference to an asymmetric key in the 434 keystore. 436 * A "choice" statement is used to expose the various options. Each 437 option is enabled by a "feature" statement. Additional "case" 438 statements MAY be augmented in if, e.g., there is a need to 439 reference an asymmetric key in an alternate location. 441 * For the "local-definition" option, the defintion uses the 442 "asymmetric-key-pair-with-certs-grouping" grouping discussed in 443 Section 2.1.4.11 of [I-D.ietf-netconf-crypto-types]. 445 * For the "keystore" option, the "keystore-reference" is an instance 446 of the "asymmetric-key-ref" typedef discussed in Section 2.1.2. 448 2.1.3.6. The "local-or-keystore-end-entity-cert-with-key-grouping" 449 Grouping 451 The following tree diagram [RFC8340] illustrates the "local-or- 452 keystore-end-entity-cert-with-key-grouping" grouping: 454 grouping local-or-keystore-end-entity-cert-with-key-grouping 455 +-- (local-or-keystore) 456 +--:(local) {local-definitions-supported}? 457 | +-- local-definition 458 | +---u ct:asymmetric-key-pair-with-cert-grouping 459 +--:(keystore) {keystore-supported}? 460 +-- keystore-reference 461 +---u asymmetric-key-certificate-ref-grouping 463 Comments: 465 * The "local-or-keystore-end-entity-cert-with-key-grouping" grouping 466 is provided soley as convenience to downstream modules that wish 467 to offer an option for whether a symmetric key is defined locally 468 or as a reference to a symmetric key in the keystore. 470 * A "choice" statement is used to expose the various options. Each 471 option is enabled by a "feature" statement. Additional "case" 472 statements MAY be augmented in if, e.g., there is a need to 473 reference a symmetric key in an alternate location. 475 * For the "local-definition" option, the defintion uses the 476 "asymmetric-key-pair-with-certs-grouping" grouping discussed in 477 Section 2.1.4.11 of [I-D.ietf-netconf-crypto-types]. 479 * For the "keystore" option, the "keystore-reference" uses the 480 "asymmetric-key-certificate-ref-grouping" grouping discussed in 481 Section 2.1.3.2. 483 2.1.3.7. The "keystore-grouping" Grouping 485 The following tree diagram [RFC8340] illustrates the "keystore- 486 grouping" grouping: 488 grouping keystore-grouping 489 +-- asymmetric-keys 490 | +-- asymmetric-key* [name] 491 | +-- name? string 492 | +---u ct:asymmetric-key-pair-with-certs-grouping 493 +-- symmetric-keys 494 +-- symmetric-key* [name] 495 +-- name? string 496 +---u ct:symmetric-key-grouping 498 Comments: 500 * The "keystore-grouping" grouping defines a keystore instance as 501 being composed of symmetric and asymmetric keys. The stucture for 502 the symmetric and asymmetric keys is essentially the same, being a 503 "list" inside a "container". 505 * For asymmetric keys, each "asymmetric-key" uses the "asymmetric- 506 key-pair-with-certs-grouping" grouping discussed in 507 Section 2.1.4.11 of [I-D.ietf-netconf-crypto-types]. 509 * For symmetric keys, each "symmetric-key" uses the "symmetric-key- 510 grouping" grouping discussed in Section 2.1.4.3 of 511 [I-D.ietf-netconf-crypto-types]. 513 2.1.4. Protocol-accessible Nodes 515 The following tree diagram [RFC8340] lists all the protocol- 516 accessible nodes defined in the "ietf-keystore" module, without 517 expanding the "grouping" statements: 519 module: ietf-keystore 520 +--rw keystore 521 +---u keystore-grouping 523 grouping encrypted-by-choice-grouping 524 +-- (encrypted-by-choice) 525 +--:(symmetric-key-ref) 526 | +-- symmetric-key-ref? ks:symmetric-key-ref 527 +--:(asymmetric-key-ref) 528 +-- asymmetric-key-ref? ks:asymmetric-key-ref 529 grouping asymmetric-key-certificate-ref-grouping 530 +-- asymmetric-key? ks:asymmetric-key-ref 531 +-- certificate? leafref 532 grouping local-or-keystore-symmetric-key-grouping 533 +-- (local-or-keystore) 534 +--:(local) {local-definitions-supported}? 535 | +-- local-definition 536 | +---u ct:symmetric-key-grouping 537 +--:(keystore) {keystore-supported}? 538 +-- keystore-reference? ks:symmetric-key-ref 539 grouping local-or-keystore-asymmetric-key-grouping 540 +-- (local-or-keystore) 541 +--:(local) {local-definitions-supported}? 542 | +-- local-definition 543 | +---u ct:asymmetric-key-pair-grouping 544 +--:(keystore) {keystore-supported}? 545 +-- keystore-reference? ks:asymmetric-key-ref 546 grouping local-or-keystore-asymmetric-key-with-certs-grouping 547 +-- (local-or-keystore) 548 +--:(local) {local-definitions-supported}? 549 | +-- local-definition 550 | +---u ct:asymmetric-key-pair-with-certs-grouping 551 +--:(keystore) {keystore-supported}? 552 +-- keystore-reference? ks:asymmetric-key-ref 553 grouping local-or-keystore-end-entity-cert-with-key-grouping 554 +-- (local-or-keystore) 555 +--:(local) {local-definitions-supported}? 556 | +-- local-definition 557 | +---u ct:asymmetric-key-pair-with-cert-grouping 558 +--:(keystore) {keystore-supported}? 559 +-- keystore-reference 560 +---u asymmetric-key-certificate-ref-grouping 561 grouping keystore-grouping 562 +-- asymmetric-keys 563 | +-- asymmetric-key* [name] 564 | +-- name? string 565 | +---u ct:asymmetric-key-pair-with-certs-grouping 566 +-- symmetric-keys 567 +-- symmetric-key* [name] 568 +-- name? string 569 +---u ct:symmetric-key-grouping 571 The following tree diagram [RFC8340] lists all the protocol- 572 accessible nodes defined in the "ietf-keystore" module, with all 573 "grouping" statements expanded, enabling the keystore's full 574 structure to be seen: 576 module: ietf-keystore 577 +--rw keystore 578 +--rw asymmetric-keys 579 | +--rw asymmetric-key* [name] 580 | +--rw name string 581 | +--rw public-key-format identityref 582 | +--rw public-key binary 583 | +--rw private-key-format? identityref 584 | +--rw (private-key-type) 585 | | +--:(cleartext-private-key) 586 | | | +--rw cleartext-private-key? binary 587 | | +--:(hidden-private-key) 588 | | | +--rw hidden-private-key? empty 589 | | +--:(encrypted-private-key) {private-key-encryption}? 590 | | +--rw encrypted-private-key 591 | | +--rw encrypted-by 592 | | | +--rw (encrypted-by-choice) 593 | | | +--:(symmetric-key-ref) 594 | | | | +--rw symmetric-key-ref? 595 | | | | ks:symmetric-key-ref 596 | | | +--:(asymmetric-key-ref) 597 | | | +--rw asymmetric-key-ref? 598 | | | ks:asymmetric-key-ref 599 | | +--rw encrypted-value binary 600 | +--rw certificates 601 | | +--rw certificate* [name] 602 | | +--rw name string 603 | | +--rw cert-data end-entity-cert-cms 604 | | +---n certificate-expiration 605 | | {certificate-expiration-notification}? 606 | | +-- expiration-date yang:date-and-time 607 | +---x generate-certificate-signing-request 608 | {certificate-signing-request-generation}? 609 | +---w input 610 | | +---w csr-info ct:csr-info 611 | +--ro output 612 | +--ro certificate-signing-request ct:csr 613 +--rw symmetric-keys 614 +--rw symmetric-key* [name] 615 +--rw name string 616 +--rw key-format? identityref 617 +--rw (key-type) 618 +--:(cleartext-key) 619 | +--rw cleartext-key? binary 620 +--:(hidden-key) 621 | +--rw hidden-key? empty 622 +--:(encrypted-key) {symmetric-key-encryption}? 623 +--rw encrypted-key 624 +--rw encrypted-by 625 | +--rw (encrypted-by-choice) 626 | +--:(symmetric-key-ref) 627 | | +--rw symmetric-key-ref? 628 | | ks:symmetric-key-ref 629 | +--:(asymmetric-key-ref) 630 | +--rw asymmetric-key-ref? 631 | ks:asymmetric-key-ref 632 +--rw encrypted-value binary 634 grouping encrypted-by-choice-grouping 635 +-- (encrypted-by-choice) 636 +--:(symmetric-key-ref) 637 | +-- symmetric-key-ref? ks:symmetric-key-ref 638 +--:(asymmetric-key-ref) 639 +-- asymmetric-key-ref? ks:asymmetric-key-ref 640 grouping asymmetric-key-certificate-ref-grouping 641 +-- asymmetric-key? ks:asymmetric-key-ref 642 +-- certificate? leafref 643 grouping local-or-keystore-symmetric-key-grouping 644 +-- (local-or-keystore) 645 +--:(local) {local-definitions-supported}? 646 | +-- local-definition 647 | +-- key-format? identityref 648 | +-- (key-type) 649 | +--:(cleartext-key) 650 | | +-- cleartext-key? binary 651 | +--:(hidden-key) 652 | | +-- hidden-key? empty 653 | +--:(encrypted-key) {symmetric-key-encryption}? 654 | +-- encrypted-key 655 | +-- encrypted-by 656 | +-- encrypted-value binary 657 +--:(keystore) {keystore-supported}? 658 +-- keystore-reference? ks:symmetric-key-ref 659 grouping local-or-keystore-asymmetric-key-grouping 660 +-- (local-or-keystore) 661 +--:(local) {local-definitions-supported}? 662 | +-- local-definition 663 | +-- public-key-format identityref 664 | +-- public-key binary 665 | +-- private-key-format? identityref 666 | +-- (private-key-type) 667 | +--:(cleartext-private-key) 668 | | +-- cleartext-private-key? binary 669 | +--:(hidden-private-key) 670 | | +-- hidden-private-key? empty 671 | +--:(encrypted-private-key) {private-key-encryption}? 672 | +-- encrypted-private-key 673 | +-- encrypted-by 674 | +-- encrypted-value binary 675 +--:(keystore) {keystore-supported}? 676 +-- keystore-reference? ks:asymmetric-key-ref 677 grouping local-or-keystore-asymmetric-key-with-certs-grouping 678 +-- (local-or-keystore) 679 +--:(local) {local-definitions-supported}? 680 | +-- local-definition 681 | +-- public-key-format identityref 682 | +-- public-key binary 683 | +-- private-key-format? identityref 684 | +-- (private-key-type) 685 | | +--:(cleartext-private-key) 686 | | | +-- cleartext-private-key? binary 687 | | +--:(hidden-private-key) 688 | | | +-- hidden-private-key? empty 689 | | +--:(encrypted-private-key) {private-key-encryption}? 690 | | +-- encrypted-private-key 691 | | +-- encrypted-by 692 | | +-- encrypted-value binary 693 | +-- certificates 694 | | +-- certificate* [name] 695 | | +-- name? string 696 | | +-- cert-data end-entity-cert-cms 697 | | +---n certificate-expiration 698 | | {certificate-expiration-notification}? 699 | | +-- expiration-date yang:date-and-time 700 | +---x generate-certificate-signing-request 701 | {certificate-signing-request-generation}? 702 | +---w input 703 | | +---w csr-info ct:csr-info 704 | +--ro output 705 | +--ro certificate-signing-request ct:csr 706 +--:(keystore) {keystore-supported}? 707 +-- keystore-reference? ks:asymmetric-key-ref 708 grouping local-or-keystore-end-entity-cert-with-key-grouping 709 +-- (local-or-keystore) 710 +--:(local) {local-definitions-supported}? 711 | +-- local-definition 712 | +-- public-key-format identityref 713 | +-- public-key binary 714 | +-- private-key-format? identityref 715 | +-- (private-key-type) 716 | | +--:(cleartext-private-key) 717 | | | +-- cleartext-private-key? binary 718 | | +--:(hidden-private-key) 719 | | | +-- hidden-private-key? empty 720 | | +--:(encrypted-private-key) {private-key-encryption}? 721 | | +-- encrypted-private-key 722 | | +-- encrypted-by 723 | | +-- encrypted-value binary 724 | +-- cert-data? 725 | | end-entity-cert-cms 726 | +---n certificate-expiration 727 | | {certificate-expiration-notification}? 728 | | +-- expiration-date yang:date-and-time 729 | +---x generate-certificate-signing-request 730 | {certificate-signing-request-generation}? 731 | +---w input 732 | | +---w csr-info ct:csr-info 733 | +--ro output 734 | +--ro certificate-signing-request ct:csr 735 +--:(keystore) {keystore-supported}? 736 +-- keystore-reference 737 +-- asymmetric-key? ks:asymmetric-key-ref 738 +-- certificate? leafref 739 grouping keystore-grouping 740 +-- asymmetric-keys 741 | +-- asymmetric-key* [name] 742 | +-- name? string 743 | +-- public-key-format identityref 744 | +-- public-key binary 745 | +-- private-key-format? identityref 746 | +-- (private-key-type) 747 | | +--:(cleartext-private-key) 748 | | | +-- cleartext-private-key? binary 749 | | +--:(hidden-private-key) 750 | | | +-- hidden-private-key? empty 751 | | +--:(encrypted-private-key) {private-key-encryption}? 752 | | +-- encrypted-private-key 753 | | +-- encrypted-by 754 | | +-- encrypted-value binary 755 | +-- certificates 756 | | +-- certificate* [name] 757 | | +-- name? string 758 | | +-- cert-data end-entity-cert-cms 759 | | +---n certificate-expiration 760 | | {certificate-expiration-notification}? 761 | | +-- expiration-date yang:date-and-time 762 | +---x generate-certificate-signing-request 763 | {certificate-signing-request-generation}? 764 | +---w input 765 | | +---w csr-info ct:csr-info 766 | +--ro output 767 | +--ro certificate-signing-request ct:csr 768 +-- symmetric-keys 769 +-- symmetric-key* [name] 770 +-- name? string 771 +-- key-format? identityref 772 +-- (key-type) 773 +--:(cleartext-key) 774 | +-- cleartext-key? binary 775 +--:(hidden-key) 776 | +-- hidden-key? empty 777 +--:(encrypted-key) {symmetric-key-encryption}? 778 +-- encrypted-key 779 +-- encrypted-by 780 +-- encrypted-value binary 782 Comments: 784 * Protocol-accessible nodes are those nodes that are accessible when 785 the module is "implemented", as described in Section 5.6.5 of 786 [RFC7950]. 788 * The protcol-accessible nodes for the "ietf-keystore" module are an 789 instance of the "keystore-grouping" grouping discussed in 790 Section 2.1.3.7. 792 * The reason for why "keystore-grouping" exists separate from the 793 protocol-accessible nodes definition is so as to enable instances 794 of the keystore to be instantiated in other locations, as may be 795 needed or desired by some modules. 797 2.2. Example Usage 799 The examples in this section are encoded using XML, such as might be 800 the case when using the NETCONF protocol. Other encodings MAY be 801 used, such as JSON when using the RESTCONF protocol. 803 2.2.1. A Keystore Instance 805 The following example illustrates keys in . Please see 806 Section 3 for an example illustrating built-in values in 807 . 809 =============== NOTE: '\' line wrapping per RFC 8792 ================ 811 814 815 816 cleartext-symmetric-key 817 ct:octet-string-key-format 818 base64encodedvalue== 819 820 821 hidden-symmetric-key 822 823 824 825 encrypted-symmetric-key 826 827 ct:encrypted-one-symmetric-key-format 828 829 830 831 hidden-asymmetric-key 833 834 base64encodedvalue== 835 836 837 839 840 841 ssh-rsa-key 842 843 ct:ssh-public-key-format 844 845 base64encodedvalue== 846 847 ct:rsa-private-key-format 848 849 base64encodedvalue== 851 852 853 ssh-rsa-key-with-cert 854 855 ct:subject-public-key-info-format 856 857 base64encodedvalue== 858 859 ct:rsa-private-key-format 860 861 base64encodedvalue== 863 864 865 ex-rsa-cert2 866 base64encodedvalue== 867 868 869 870 871 raw-private-key 872 873 ct:subject-public-key-info-format 874 875 base64encodedvalue== 876 877 ct:rsa-private-key-format 878 879 base64encodedvalue== 881 882 883 rsa-asymmetric-key 884 885 ct:subject-public-key-info-format 886 887 base64encodedvalue== 888 889 ct:rsa-private-key-format 890 891 base64encodedvalue== 893 894 895 ex-rsa-cert 896 base64encodedvalue== 897 898 899 900 901 ec-asymmetric-key 902 903 ct:subject-public-key-info-format 904 905 base64encodedvalue== 906 907 ct:ec-private-key-format 908 909 base64encodedvalue== 911 912 913 ex-ec-cert 914 base64encodedvalue== 915 916 917 918 919 hidden-asymmetric-key 920 921 ct:subject-public-key-info-format 922 923 base64encodedvalue== 924 925 926 927 builtin-idevid-cert 928 base64encodedvalue== 929 930 931 my-ldevid-cert 932 base64encodedvalue== 933 934 935 936 937 encrypted-asymmetric-key 938 939 ct:subject-public-key-info-format 940 941 base64encodedvalue== 942 943 ct:encrypted-one-asymmetric-key-format 944 945 946 947 encrypted-symmetric-key 949 950 base64encodedvalue== 951 952 953 954 956 2.2.2. A Certificate Expiration Notification 958 The following example illustrates a "certificate-expiration" 959 notification for a certificate associated with a key configured in 960 the keystore. 962 =============== NOTE: '\' line wrapping per RFC 8792 ================ 964 966 2018-05-25T00:01:00Z 967 968 969 970 hidden-asymmetric-key 971 972 973 my-ldevid-cert 974 975 2018-08-05T14:18:53-05:00 977 978 979 980 981 982 983 985 2.2.3. The "Local or Keystore" Groupings 987 This section illustrates the various "local-or-keystore" groupings 988 defined in the "ietf-keystore" module, specifically the "local-or- 989 keystore-symmetric-key-grouping" (Section 2.1.3.3), "local-or- 990 keystore-asymmetric-key-grouping" (Section 2.1.3.4), "local-or- 991 keystore-asymmetric-key-with-certs-grouping" (Section 2.1.3.5), and 992 "local-or-keystore-end-entity-cert-with-key-grouping" 993 (Section 2.1.3.6) groupings. 995 These examples assume the existence of an example module called "ex- 996 keystore-usage" having the namespace "http://example.com/ns/example- 997 keystore-usage". 999 The ex-keystore-usage module is first presented using tree diagrams 1000 [RFC8340], followed by an instance example illustrating all the 1001 "local-or-keystore" groupings in use, followed by the YANG module 1002 itself. 1004 The following tree diagram illustrates "ex-keystore-usage" without 1005 expanding the "grouping" statements: 1007 module: ex-keystore-usage 1008 +--rw keystore-usage 1009 +--rw symmetric-key* [name] 1010 | +--rw name string 1011 | +---u ks:local-or-keystore-symmetric-key-grouping 1012 +--rw asymmetric-key* [name] 1013 | +--rw name string 1014 | +---u ks:local-or-keystore-asymmetric-key-grouping 1015 +--rw asymmetric-key-with-certs* [name] 1016 | +--rw name 1017 | | string 1018 | +---u ks:local-or-keystore-asymmetric-key-with-certs-grouping 1019 +--rw end-entity-cert-with-key* [name] 1020 +--rw name 1021 | string 1022 +---u ks:local-or-keystore-end-entity-cert-with-key-grouping 1024 The following tree diagram illustrates the "ex-keystore-usage" 1025 module, with all "grouping" statements expanded, enabling the 1026 keystore's full structure to be seen: 1028 module: ex-keystore-usage 1029 +--rw keystore-usage 1030 +--rw symmetric-key* [name] 1031 | +--rw name string 1032 | +--rw (local-or-keystore) 1033 | +--:(local) {local-definitions-supported}? 1034 | | +--rw local-definition 1035 | | +--rw key-format? identityref 1036 | | +--rw (key-type) 1037 | | +--:(cleartext-key) 1038 | | | +--rw cleartext-key? binary 1039 | | +--:(hidden-key) 1040 | | | +--rw hidden-key? empty 1041 | | +--:(encrypted-key) {symmetric-key-encryption}? 1042 | | +--rw encrypted-key 1043 | | +--rw encrypted-by 1044 | | +--rw encrypted-value binary 1045 | +--:(keystore) {keystore-supported}? 1046 | +--rw keystore-reference? ks:symmetric-key-ref 1047 +--rw asymmetric-key* [name] 1048 | +--rw name string 1049 | +--rw (local-or-keystore) 1050 | +--:(local) {local-definitions-supported}? 1051 | | +--rw local-definition 1052 | | +--rw public-key-format identityref 1053 | | +--rw public-key binary 1054 | | +--rw private-key-format? identityref 1055 | | +--rw (private-key-type) 1056 | | +--:(cleartext-private-key) 1057 | | | +--rw cleartext-private-key? binary 1058 | | +--:(hidden-private-key) 1059 | | | +--rw hidden-private-key? empty 1060 | | +--:(encrypted-private-key) 1061 | | {private-key-encryption}? 1062 | | +--rw encrypted-private-key 1063 | | +--rw encrypted-by 1064 | | +--rw encrypted-value binary 1065 | +--:(keystore) {keystore-supported}? 1066 | +--rw keystore-reference? ks:asymmetric-key-ref 1067 +--rw asymmetric-key-with-certs* [name] 1068 | +--rw name string 1069 | +--rw (local-or-keystore) 1070 | +--:(local) {local-definitions-supported}? 1071 | | +--rw local-definition 1072 | | +--rw public-key-format 1073 | | | identityref 1074 | | +--rw public-key binary 1075 | | +--rw private-key-format? 1076 | | | identityref 1077 | | +--rw (private-key-type) 1078 | | | +--:(cleartext-private-key) 1079 | | | | +--rw cleartext-private-key? binary 1080 | | | +--:(hidden-private-key) 1081 | | | | +--rw hidden-private-key? empty 1082 | | | +--:(encrypted-private-key) 1083 | | | {private-key-encryption}? 1084 | | | +--rw encrypted-private-key 1085 | | | +--rw encrypted-by 1086 | | | +--rw encrypted-value binary 1087 | | +--rw certificates 1088 | | | +--rw certificate* [name] 1089 | | | +--rw name string 1090 | | | +--rw cert-data 1091 | | | | end-entity-cert-cms 1092 | | | +---n certificate-expiration 1093 | | | {certificate-expiration-notification}? 1094 | | | +-- expiration-date yang:date-and-time 1095 | | +---x generate-certificate-signing-request 1096 | | {certificate-signing-request-generation}? 1097 | | +---w input 1098 | | | +---w csr-info ct:csr-info 1099 | | +--ro output 1100 | | +--ro certificate-signing-request ct:csr 1101 | +--:(keystore) {keystore-supported}? 1102 | +--rw keystore-reference? ks:asymmetric-key-ref 1103 +--rw end-entity-cert-with-key* [name] 1104 +--rw name string 1105 +--rw (local-or-keystore) 1106 +--:(local) {local-definitions-supported}? 1107 | +--rw local-definition 1108 | +--rw public-key-format 1109 | | identityref 1110 | +--rw public-key binary 1111 | +--rw private-key-format? 1112 | | identityref 1113 | +--rw (private-key-type) 1114 | | +--:(cleartext-private-key) 1115 | | | +--rw cleartext-private-key? binary 1116 | | +--:(hidden-private-key) 1117 | | | +--rw hidden-private-key? empty 1118 | | +--:(encrypted-private-key) 1119 | | {private-key-encryption}? 1120 | | +--rw encrypted-private-key 1121 | | +--rw encrypted-by 1122 | | +--rw encrypted-value binary 1123 | +--rw cert-data? 1124 | | end-entity-cert-cms 1125 | +---n certificate-expiration 1126 | | {certificate-expiration-notification}? 1127 | | +-- expiration-date yang:date-and-time 1128 | +---x generate-certificate-signing-request 1129 | {certificate-signing-request-generation}? 1130 | +---w input 1131 | | +---w csr-info ct:csr-info 1132 | +--ro output 1133 | +--ro certificate-signing-request ct:csr 1134 +--:(keystore) {keystore-supported}? 1135 +--rw keystore-reference 1136 +--rw asymmetric-key? ks:asymmetric-key-ref 1137 +--rw certificate? leafref 1139 The following example provides two equivalent instances of each 1140 grouping, the first being a reference to a keystore and the second 1141 being locally-defined. The instance having a reference to a keystore 1142 is consistent with the keystore defined in Section 2.2.1. The two 1143 instances are equivalent, as the locally-defined instance example 1144 contains the same values defined by the keystore instance referenced 1145 by its sibling example. 1147 =============== NOTE: '\' line wrapping per RFC 8792 ================ 1149 1153 1154 1156 1157 example 1a 1158 cleartext-symmetric-key 1159 1161 1162 example 1b 1163 1164 ct:octet-string-key-format 1165 base64encodedvalue== 1166 1167 1169 1170 1172 1173 example 2a 1174 rsa-asymmetric-key 1175 1177 1178 example 2b 1179 1180 1181 ct:subject-public-key-info-format 1182 1183 base64encodedvalue== 1184 1185 ct:rsa-private-key-format 1186 1187 base64encodedvalue== 1189 1190 1192 1193 1195 1196 example 3a 1197 rsa-asymmetric-key 1198 1200 1201 example 3b 1202 1203 1204 ct:subject-public-key-info-format 1205 1206 base64encodedvalue== 1207 1208 ct:rsa-private-key-format 1209 1210 base64encodedvalue== 1212 1213 1214 a locally-defined cert 1215 base64encodedvalue== 1216 1217 1218 1219 1221 1222 1224 1225 example 4a 1226 1227 rsa-asymmetric-key 1228 ex-rsa-cert 1229 1230 1232 1233 example 4b 1234 1235 1236 ct:subject-public-key-info-format 1237 1238 base64encodedvalue== 1239 1240 ct:rsa-private-key-format 1241 1242 base64encodedvalue== 1244 base64encodedvalue== 1245 1246 1248 1250 Following is the "ex-keystore-usage" module's YANG definition: 1252 module ex-keystore-usage { 1253 yang-version 1.1; 1255 namespace "http://example.com/ns/example-keystore-usage"; 1256 prefix "eku"; 1258 import ietf-keystore { 1259 prefix ks; 1260 reference 1261 "RFC CCCC: A YANG Data Model for a Keystore"; 1262 } 1264 organization 1265 "Example Corporation"; 1267 contact 1268 "Author: YANG Designer "; 1270 description 1271 "This module illustrates notable groupings defined in 1272 the 'ietf-keystore' module."; 1274 revision "2020-08-20" { 1275 description 1276 "Initial version"; 1277 reference 1278 "RFC CCCC: A YANG Data Model for a Keystore"; 1279 } 1281 container keystore-usage { 1282 description 1283 "An illustration of the various keystore groupings."; 1285 list symmetric-key { 1286 key name; 1287 leaf name { 1288 type string; 1289 description 1290 "An arbitrary name for this key."; 1291 } 1292 uses ks:local-or-keystore-symmetric-key-grouping; 1293 description 1294 "An symmetric key that may be configured locally or be a 1295 reference to a symmetric key in the keystore."; 1296 } 1298 list asymmetric-key { 1299 key name; 1300 leaf name { 1301 type string; 1302 description 1303 "An arbitrary name for this key."; 1304 } 1305 uses ks:local-or-keystore-asymmetric-key-grouping; 1306 description 1307 "An asymmetric key, with no certs, that may be configured 1308 locally or be a reference to an asymmetric key in the 1309 keystore. The intent is to reference just the asymmetric 1310 key, not any certificates that may also be associated 1311 with the asymmetric key."; 1312 } 1314 list asymmetric-key-with-certs { 1315 key name; 1316 leaf name { 1317 type string; 1318 description 1319 "An arbitrary name for this key."; 1320 } 1321 uses ks:local-or-keystore-asymmetric-key-with-certs-grouping; 1322 description 1323 "An asymmetric key and its associated certs, that may be 1324 configured locally or be a reference to an asymmetric key 1325 (and its associated certs) in the keystore."; 1326 } 1328 list end-entity-cert-with-key { 1329 key name; 1330 leaf name { 1331 type string; 1332 description 1333 "An arbitrary name for this key."; 1334 } 1335 uses ks:local-or-keystore-end-entity-cert-with-key-grouping; 1336 description 1337 "An end-entity certificate and its associated asymmetric 1338 key, that may be configured locally or be a reference 1339 to another certificate (and its associated asymmetric 1340 key) in the keystore."; 1341 } 1342 } 1344 } 1346 2.3. YANG Module 1348 This YANG module has normative references to [RFC8341] and 1349 [I-D.ietf-netconf-crypto-types]. 1351 file "ietf-keystore@2020-08-20.yang" 1353 module ietf-keystore { 1354 yang-version 1.1; 1355 namespace "urn:ietf:params:xml:ns:yang:ietf-keystore"; 1356 prefix ks; 1358 import ietf-netconf-acm { 1359 prefix nacm; 1360 reference 1361 "RFC 8341: Network Configuration Access Control Model"; 1362 } 1364 import ietf-crypto-types { 1365 prefix ct; 1366 reference 1367 "RFC AAAA: YANG Data Types and Groupings for Cryptography"; 1368 } 1370 organization 1371 "IETF NETCONF (Network Configuration) Working Group"; 1373 contact 1374 "WG Web: 1375 WG List: 1376 Author: Kent Watsen "; 1378 description 1379 "This module defines a Keystore to centralize management 1380 of security credentials. 1382 Copyright (c) 2020 IETF Trust and the persons identified 1383 as authors of the code. All rights reserved. 1385 Redistribution and use in source and binary forms, with 1386 or without modification, is permitted pursuant to, and 1387 subject to the license terms contained in, the Simplified 1388 BSD License set forth in Section 4.c of the IETF Trust's 1389 Legal Provisions Relating to IETF Documents 1390 (https://trustee.ietf.org/license-info). 1392 This version of this YANG module is part of RFC CCCC 1393 (https://www.rfc-editor.org/info/rfcCCCC); see the RFC 1394 itself for full legal notices. 1396 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1397 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 1398 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 1399 are to be interpreted as described in BCP 14 (RFC 2119) 1400 (RFC 8174) when, and only when, they appear in all 1401 capitals, as shown here."; 1403 revision 2020-08-20 { 1404 description 1405 "Initial version"; 1406 reference 1407 "RFC CCCC: A YANG Data Model for a Keystore"; 1408 } 1410 /****************/ 1411 /* Features */ 1412 /****************/ 1414 feature keystore-supported { 1415 description 1416 "The 'keystore-supported' feature indicates that the server 1417 supports the Keystore."; 1418 } 1420 feature local-definitions-supported { 1421 description 1422 "The 'local-definitions-supported' feature indicates that the 1423 server supports locally-defined keys."; 1424 } 1426 /****************/ 1427 /* Typedefs */ 1428 /****************/ 1430 typedef symmetric-key-ref { 1431 type leafref { 1432 path "/ks:keystore/ks:symmetric-keys/ks:symmetric-key" 1433 + "/ks:name"; 1434 } 1435 description 1436 "This typedef enables modules to easily define a reference 1437 to a symmetric key stored in the Keystore."; 1438 } 1440 typedef asymmetric-key-ref { 1441 type leafref { 1442 path "/ks:keystore/ks:asymmetric-keys/ks:asymmetric-key" 1443 + "/ks:name"; 1444 } 1445 description 1446 "This typedef enables modules to easily define a reference 1447 to an asymmetric key stored in the Keystore."; 1448 } 1450 /*****************/ 1451 /* Groupings */ 1452 /*****************/ 1454 grouping encrypted-by-choice-grouping { 1455 description 1456 "A grouping that defines a choice that can be augmented 1457 into the 'encrypted-by' node presented by the 1458 'symmetric-key-grouping' and 'asymmetric-key-pair-grouping' 1459 groupings defined in RFC AAAA."; 1460 choice encrypted-by-choice { 1461 nacm:default-deny-write; 1462 mandatory true; 1463 description 1464 "A choice amongst other symmetric or asymmetric keys."; 1465 case symmetric-key-ref { 1466 leaf symmetric-key-ref { 1467 type ks:symmetric-key-ref; 1468 description 1469 "Identifies the symmetric key used to encrypt the 1470 associated key."; 1471 } 1472 } 1473 case asymmetric-key-ref { 1474 leaf asymmetric-key-ref { 1475 type ks:asymmetric-key-ref; 1476 description 1477 "Identifies the asymmetric key whose public key 1478 encrypted the associated key."; 1479 } 1480 } 1482 } 1483 } 1485 grouping asymmetric-key-certificate-ref-grouping { 1486 description 1487 "This grouping defines a reference to a specific certificate 1488 associated with an asymmetric key stored in the Keystore."; 1489 leaf asymmetric-key { 1490 nacm:default-deny-write; 1491 type ks:asymmetric-key-ref; 1492 must '../certificate'; 1493 description 1494 "A reference to an asymmetric key in the Keystore."; 1495 } 1496 leaf certificate { 1497 nacm:default-deny-write; 1498 type leafref { 1499 path "/ks:keystore/ks:asymmetric-keys/ks:asymmetric-key[ks:" 1500 + "name = current()/../asymmetric-key]/ks:certificates" 1501 + "/ks:certificate/ks:name"; 1502 } 1503 must '../asymmetric-key'; 1504 description 1505 "A reference to a specific certificate of the 1506 asymmetric key in the Keystore."; 1507 } 1508 } 1510 // local-or-keystore-* groupings 1512 grouping local-or-keystore-symmetric-key-grouping { 1513 description 1514 "A grouping that expands to allow the symmetric key to be 1515 either stored locally, i.e., within the using data model, 1516 or a reference to a symmetric key stored in the Keystore."; 1517 choice local-or-keystore { 1518 nacm:default-deny-write; 1519 mandatory true; 1520 description 1521 "A choice between an inlined definition and a definition 1522 that exists in the Keystore."; 1523 case local { 1524 if-feature "local-definitions-supported"; 1525 container local-definition { 1526 description 1527 "Container to hold the local key definition."; 1528 uses ct:symmetric-key-grouping; 1530 } 1531 } 1532 case keystore { 1533 if-feature "keystore-supported"; 1534 leaf keystore-reference { 1535 type ks:symmetric-key-ref; 1536 description 1537 "A reference to an symmetric key that exists in 1538 the Keystore."; 1539 } 1540 } 1541 } 1542 } 1544 grouping local-or-keystore-asymmetric-key-grouping { 1545 description 1546 "A grouping that expands to allow the asymmetric key to be 1547 either stored locally, i.e., within the using data model, 1548 or a reference to an asymmetric key stored in the Keystore."; 1549 choice local-or-keystore { 1550 nacm:default-deny-write; 1551 mandatory true; 1552 description 1553 "A choice between an inlined definition and a definition 1554 that exists in the Keystore."; 1555 case local { 1556 if-feature "local-definitions-supported"; 1557 container local-definition { 1558 description 1559 "Container to hold the local key definition."; 1560 uses ct:asymmetric-key-pair-grouping; 1561 } 1562 } 1563 case keystore { 1564 if-feature "keystore-supported"; 1565 leaf keystore-reference { 1566 type ks:asymmetric-key-ref; 1567 description 1568 "A reference to an asymmetric key that exists in 1569 the Keystore. The intent is to reference just the 1570 asymmetric key without any regard for any certificates 1571 that may be associated with it."; 1572 } 1573 } 1574 } 1575 } 1577 grouping local-or-keystore-asymmetric-key-with-certs-grouping { 1578 description 1579 "A grouping that expands to allow an asymmetric key and 1580 its associated certificates to be either stored locally, 1581 i.e., within the using data model, or a reference to an 1582 asymmetric key (and its associated certificates) stored 1583 in the Keystore."; 1584 choice local-or-keystore { 1585 nacm:default-deny-write; 1586 mandatory true; 1587 description 1588 "A choice between an inlined definition and a definition 1589 that exists in the Keystore."; 1590 case local { 1591 if-feature "local-definitions-supported"; 1592 container local-definition { 1593 description 1594 "Container to hold the local key definition."; 1595 uses ct:asymmetric-key-pair-with-certs-grouping; 1596 } 1597 } 1598 case keystore { 1599 if-feature "keystore-supported"; 1600 leaf keystore-reference { 1601 type ks:asymmetric-key-ref; 1602 description 1603 "A reference to an asymmetric-key (and all of its 1604 associated certificates) in the Keystore."; 1605 } 1606 } 1607 } 1608 } 1610 grouping local-or-keystore-end-entity-cert-with-key-grouping { 1611 description 1612 "A grouping that expands to allow an end-entity certificate 1613 (and its associated asymmetric key pair) to be either stored 1614 locally, i.e., within the using data model, or a reference 1615 to a specific certificate in the Keystore."; 1616 choice local-or-keystore { 1617 nacm:default-deny-write; 1618 mandatory true; 1619 description 1620 "A choice between an inlined definition and a definition 1621 that exists in the Keystore."; 1622 case local { 1623 if-feature "local-definitions-supported"; 1624 container local-definition { 1625 description 1626 "Container to hold the local key definition."; 1627 uses ct:asymmetric-key-pair-with-cert-grouping; 1628 } 1629 } 1630 case keystore { 1631 if-feature "keystore-supported"; 1632 container keystore-reference { 1633 uses asymmetric-key-certificate-ref-grouping; 1634 description 1635 "A reference to a specific certificate associated with 1636 an asymmetric key stored in the Keystore."; 1637 } 1638 } 1639 } 1640 } 1642 grouping keystore-grouping { 1643 description 1644 "Grouping definition enables use in other contexts. If ever 1645 done, implementations SHOULD augment new 'case' statements 1646 into local-or-keystore 'choice' statements to supply leafrefs 1647 to the new location."; 1648 container asymmetric-keys { 1649 nacm:default-deny-write; 1650 description 1651 "A list of asymmetric keys."; 1652 list asymmetric-key { 1653 key "name"; 1654 description 1655 "An asymmetric key."; 1656 leaf name { 1657 type string; 1658 description 1659 "An arbitrary name for the asymmetric key."; 1660 } 1661 uses ct:asymmetric-key-pair-with-certs-grouping; 1662 } 1663 } 1664 container symmetric-keys { 1665 nacm:default-deny-write; 1666 description 1667 "A list of symmetric keys."; 1668 list symmetric-key { 1669 key "name"; 1670 description 1671 "A symmetric key."; 1672 leaf name { 1673 type string; 1674 description 1675 "An arbitrary name for the symmetric key."; 1676 } 1677 uses ct:symmetric-key-grouping; 1678 } 1679 } 1680 } // grouping keystore-grouping 1682 /*********************************/ 1683 /* Protocol accessible nodes */ 1684 /*********************************/ 1686 container keystore { 1687 description 1688 "The Keystore contains a list of symmetric keys and a list 1689 of asymmetric keys."; 1690 nacm:default-deny-write; 1691 uses keystore-grouping { 1692 augment "symmetric-keys/symmetric-key/key-type/encrypted-key/" 1693 + "encrypted-key/encrypted-by" { 1694 description 1695 "Augments in a choice statement enabling the encrypting 1696 key to be any other symmetric or asymmetric key in the 1697 keystore."; 1698 uses encrypted-by-choice-grouping; 1699 } 1700 augment "asymmetric-keys/asymmetric-key/private-key-type/" 1701 + "encrypted-private-key/encrypted-private-key/" 1702 + "encrypted-by" { 1703 description 1704 "Augments in a choice statement enabling the encrypting 1705 key to be any other symmetric or asymmetric key in the 1706 keystore."; 1707 uses encrypted-by-choice-grouping; 1708 } 1709 } 1710 } 1712 } 1714 1716 3. Support for Built-in Keys 1718 In some implementations, a server may support built-in keys. Built- 1719 in keys MAY be set during the manufacturing process or be dynamically 1720 generated the first time the server is booted or a particular service 1721 (e.g., SSH) is enabled. 1723 The primary characteristic of the built-in keys is that they are 1724 provided by the system, as opposed to configuration. As such, they 1725 are present in . The example below illustrates what the 1726 keystore in might look like for a server in its factory 1727 default state. 1729 1733 1734 1735 Manufacturer-Generated Hidden Key 1736 1737 ct:subject-public-key-info-format 1738 1739 base64encodedvalue== 1740 1741 1742 1743 Manufacturer-Generated IDevID Cert 1744 base64encodedvalue== 1745 1746 1747 1748 1749 1751 In order for the built-in keys (and/or their associated built-in 1752 certificates) to be referenced by configuration, the referenced keys 1753 MUST first be copied into . The keys SHOULD be copied into 1754 using the same value for the list's "key" substatement, so 1755 that the server can bind the references to the built-in entries. 1757 In addition to copying keys into the Keystore in , cleartext 1758 and encrypted keys may be copied into other parts of configuration, 1759 but they will lose their connection to having been a built-in value. 1760 Note that hidden keys cannot be copied into other parts of the 1761 configuration because doing would lose the key's connection to the 1762 built-in key, where the key's secret value is stored. Built-in 1763 "encrypted" keys MAY be copied into other parts of the configuration 1764 so long as the reference to the other built-in key that encrypted 1765 them is maintained. 1767 Only the referenced keys need to be copied; that is, the keys in 1768 MAY be a subset, including the whole of the set, of the 1769 built-in keys defined in . 1771 No new built-in keys may be added nor existing built-in changed, with 1772 exception for associating additional certificates to an existing 1773 built-in key. 1775 A server MUST reject attempts to modify any aspect of built-in keys, 1776 with exception for associating additional certificates to a built-in 1777 key. That these keys are "configured" in is an illusion, 1778 as they are strictly a read-only subset of that which must already 1779 exist in . 1781 The following example illustrates how a single built-in key 1782 definition from the previous example has been propagated to 1783 : 1785 1787 1788 1789 Manufacturer-Generated Hidden Key 1790 1791 ct:subject-public-key-info-format 1792 1793 base64encodedvalue== 1794 1795 1796 1797 Manufacturer-Generated IDevID Cert 1798 base64encodedvalue== 1799 1800 1801 Deployment-Specific LDevID Cert 1802 base64encodedvalue== 1803 1804 1805 1806 1807 1809 After the above configuration is applied, should appear 1810 as follows: 1812 1816 1817 1818 Manufacturer-Generated Hidden Key 1819 1820 ct:subject-public-key-info-format 1821 1822 base64encodedvalue== 1823 1824 1825 1826 Manufacturer-Generated IDevID Cert 1827 base64encodedvalue== 1828 1829 1830 Deployment-Specific LDevID Cert 1831 base64encodedvalue== 1832 1833 1834 1835 1836 1838 4. Encrypting Keys in Configuration 1840 This section describes an approach that enables both the symmetric 1841 and asymmetric keys on a server to be encrypted, such that 1842 traditional backup/restore procedures can be used without concern for 1843 the keys being compromised when in transit. 1845 4.1. Key Encryption Key 1847 The ability to encrypt configured keys is predicated on the existence 1848 of a "key encryption key" (KEK). There may be any number of KEKs in 1849 a system. A KEK, by its namesake, is a key that is used to encrypt 1850 other keys. A KEK MAY be either a symmetric key or an asymmetric 1851 key. 1853 If a KEK is a symmetric key, then the server MUST provide an API for 1854 administrators to encrypt other keys without needing to know the 1855 symmetric key's value. If the KEK is an asymmetric key, then the 1856 server MAY provide an API enabling the encryption of other keys or, 1857 alternatively, let the administrators do so themselves using the 1858 asymmetric key's public half. 1860 A server MUST possess (or be able to possess, in case the KEK has 1861 been encrypted by another KEK) a KEK's cleartext value so that it can 1862 decrypt the other keys in the configurion at runtime. 1864 4.2. Configuring Encrypted Keys 1866 Each time a new key is configured, it SHOULD be encrypted by a KEK. 1868 In "ietf-crypto-types" [I-D.ietf-netconf-crypto-types], the format 1869 for an encrypted symmetric key is described by the "encrypted-one- 1870 symmetric-key-format" identity, while the format for an encrypted 1871 asymmetric key is described by the "encrypted-one-asymmetric-key- 1872 format" identity 1874 Implementations SHOULD provide an API that simultaneously generates 1875 and encrypts a key (symmetric or asymmetric) using a KEK. Thusly 1876 newly generated key cleartext values are never known to the 1877 administrators generating the keys. 1879 In case the server implementation does not provide such an API, then 1880 the generating and encrypting steps MAY be performed outside the 1881 server, e.g., by an administrator with special access control rights 1882 (e.g., an organization's crypto officer). 1884 In either case, the encrypted key can be configured into the Keystore 1885 using either the "encrypted-key" (for symmetric keys) or the 1886 "encrypted-private-key" (for asymmetric keys) nodes. These two nodes 1887 contain both the encrypted value as well as a reference to the KEK 1888 that encrypted the key. 1890 4.3. Migrating Configuration to Another Server 1892 When a KEK is used to encrypt other keys, migrating the configuration 1893 to another server is only possible if the second server has the same 1894 KEK. How the second server comes to have the same KEK is discussed 1895 in this section. 1897 In some deployments, mechanisms outside the scope of this document 1898 may be used to migrate a KEK from one server to another. That said, 1899 beware that the ability to do so typically entails having access to 1900 the first server but, in many RMA scenarios, the first server may no 1901 longer be operational. 1903 In other deployments, an organization's crypto officer, possessing a 1904 KEK's cleartext value, configures the same KEK on the second server, 1905 presumably as a hidden key or a key protected by access-control 1906 (e.g., NACM's "default-deny-all), so that the cleartext value is not 1907 disclosed to regular administrators. However, this approach creates 1908 high-coupling to and dependency on the crypto officers that doesn't 1909 scale in production environments. 1911 In order to decouple the crypto officers from the regular 1912 administrators, a special KEK, called the "master key" (MK), may be 1913 used. 1915 A MK is commonly a globally-unique built-in (see Section 3) 1916 asymmetric key. The private key, due to its long lifetime, is hidden 1917 (i.e., "hidden-private-key" in Section 2.1.4.5. of 1918 [I-D.ietf-netconf-crypto-types]). The public key is often contained 1919 in an identity certificate (e.g., IDevID). How to configure a MK 1920 during the manufacturing process is outside the scope of this 1921 document. 1923 It is highly RECOMMENDED that MKs are built-in and hidden but, if 1924 this is not possible, MKs highly restricted access mechanisms SHOULD 1925 be used to limit access to the MK's secret data to only highly 1926 authorized clients (e.g., an organization's crypto officer). In this 1927 case, it is RECOMMENDED that the MK is not built-in and hence is, 1928 effectively, just like a KEK. 1930 Assuming the server has a MK, the MK can be used to encrypt a "shared 1931 KEK", which is then used to encrypt the keys configured by regular 1932 administrators. 1934 With this extra level of indirection, it is possible for a crypto 1935 officer to encrypt the same KEK for a multiplicity of servers offline 1936 using the public key contained in their identity certificates. The 1937 crypto officer can then safely handoff the encrypted KEKs to the 1938 regular administrators responsible for server installations, 1939 including migrations. 1941 In order to migrate the configuration from a first server, an 1942 administrator would need to make just a single modification to the 1943 configuration before loading it onto a second server, which is to 1944 replace the encrypted KEK Keystore entry from the first server with 1945 the encrypted KEK for the second server. Upon doing this, the 1946 configuration (containing many encrypted keys) can be loaded into the 1947 second server while enabling the second server to decrypt all the 1948 encrypted keys in the configuration. 1950 The following diagram illustrates this idea: 1952 +-------------+ +-------------+ 1953 | shared KEK | | shared KEK | 1954 |(unencrypted)|-------------------------------> | (encrypted) | 1955 +-------------+ encrypts offline using +-------------+ 1956 ^ each server's MK | 1957 | | 1958 | | 1959 | possesses \o | 1960 +-------------- |\ | 1961 / \ shares with | 1962 crypto +--------------------+ 1963 officer | 1964 | 1965 | 1966 +----------------------+ | +----------------------+ 1967 | server-1 | | | server-2 | 1968 | configuration | | | configuration | 1969 | | | | | 1970 | | | | | 1971 | +----------------+ | | | +----------------+ | 1972 | | MK-1 | | | | | MK-2 | | 1973 | | (hidden) | | | | | (hidden) | | 1974 | +----------------+ | | | +----------------+ | 1975 | ^ | | | ^ | 1976 | | | | | | | 1977 | | | | | | | 1978 | | encrypted | | | | encrypted | 1979 | | by | | | | by | 1980 | | | | | | | 1981 | | | | | | | 1982 | +----------------+ | | | +----------------+ | 1983 | | shared KEK | | | | | shared KEK | | 1984 | | (encrypted) | | v | | (encrypted) | | 1985 | +----------------+ | | +----------------+ | 1986 | ^ | regular | ^ | 1987 | | | admin | | | 1988 | | | | | | 1989 | | encrypted | \o | | encrypted | 1990 | | by | |\ | | by | 1991 | | | / \ | | | 1992 | | | | | | 1993 | +----------------+ |----------------->| +----------------+ | 1994 | | all other keys | | migrate | | all other keys | | 1995 | | (encrypted) | | configuration | | (encrypted) | | 1996 | +----------------+ | | +----------------+ | 1997 | | | | 1998 +----------------------+ +----------------------+ 2000 5. Security Considerations 2002 5.1. Data at Rest 2004 The YANG module defined in this document defines a mechanism called a 2005 "keystore" that, by its name, suggests that it will protect its 2006 contents from unauthorized disclosure and modification. 2008 Security controls for the API (i.e., data in motion) are discussed in 2009 Section 5.2, but controls for the data at rest cannot be specified by 2010 the YANG module. 2012 In order to satisfy the expectations of a "keystore", it is 2013 RECOMMENDED that implementations ensure that the keystore contents 2014 are encrypted when persisted to non-volatile memory. 2016 5.2. The "ietf-keystore" YANG Module 2018 The YANG module defined in this document is designed to be accessed 2019 via YANG based management protocols, such as NETCONF [RFC6241] and 2020 RESTCONF [RFC8040]. Both of these protocols have mandatory-to- 2021 implement secure transport layers (e.g., SSH, TLS) with mutual 2022 authentication. 2024 The NETCONF access control model (NACM) [RFC8341] provides the means 2025 to restrict access for particular users to a pre-configured subset of 2026 all available protocol operations and content. 2028 None of the readable data nodes defined in this YANG module are 2029 considered sensitive or vulnerable in network environments. The NACM 2030 "default-deny-all" extension has not been set for any data nodes 2031 defined in this module. 2033 | Please be aware that this module uses the "cleartext-key" and 2034 | "cleartext-private-key" nodes from the "ietf-crypto-types" 2035 | module [I-D.ietf-netconf-crypto-types], where said nodes have 2036 | the NACM extension "default-deny-all" set, thus preventing 2037 | uncontrolled read-access to the cleartext key values. 2039 All of the writable data nodes defined by this module, both in the 2040 "grouping" statements as well as the protocol-accessible "keystore" 2041 instance, may be considered sensitive or vulnerable in some network 2042 environments.. For instance, any modification to a key or reference 2043 to a key may dramatically alter the implemented security policy. For 2044 this reason, the NACM extension "default-deny-write" has been set for 2045 all data nodes defined in this module. 2047 This module does not define any RPCs, actions, or notifications, and 2048 thus the security consideration for such is not provided here. 2050 6. IANA Considerations 2052 6.1. The "IETF XML" Registry 2054 This document registers one URI in the "ns" subregistry of the IETF 2055 XML Registry [RFC3688]. Following the format in [RFC3688], the 2056 following registration is requested: 2058 URI: urn:ietf:params:xml:ns:yang:ietf-keystore 2059 Registrant Contact: The NETCONF WG of the IETF. 2060 XML: N/A, the requested URI is an XML namespace. 2062 6.2. The "YANG Module Names" Registry 2064 This document registers one YANG module in the YANG Module Names 2065 registry [RFC6020]. Following the format in [RFC6020], the following 2066 registration is requested: 2068 name: ietf-keystore 2069 namespace: urn:ietf:params:xml:ns:yang:ietf-keystore 2070 prefix: ks 2071 reference: RFC CCCC 2073 7. References 2075 7.1. Normative References 2077 [I-D.ietf-netconf-crypto-types] 2078 Watsen, K., "YANG Data Types and Groupings for 2079 Cryptography", Work in Progress, Internet-Draft, draft- 2080 ietf-netconf-crypto-types-17, 10 July 2020, 2081 . 2084 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2085 Requirement Levels", BCP 14, RFC 2119, 2086 DOI 10.17487/RFC2119, March 1997, 2087 . 2089 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 2090 the Network Configuration Protocol (NETCONF)", RFC 6020, 2091 DOI 10.17487/RFC6020, October 2010, 2092 . 2094 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2095 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2096 . 2098 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 2099 Access Control Model", STD 91, RFC 8341, 2100 DOI 10.17487/RFC8341, March 2018, 2101 . 2103 7.2. Informative References 2105 [I-D.ietf-netconf-http-client-server] 2106 Watsen, K., "YANG Groupings for HTTP Clients and HTTP 2107 Servers", Work in Progress, Internet-Draft, draft-ietf- 2108 netconf-http-client-server-04, 8 July 2020, 2109 . 2112 [I-D.ietf-netconf-keystore] 2113 Watsen, K., "A YANG Data Model for a Keystore", Work in 2114 Progress, Internet-Draft, draft-ietf-netconf-keystore-19, 2115 10 July 2020, . 2118 [I-D.ietf-netconf-netconf-client-server] 2119 Watsen, K., "NETCONF Client and Server Models", Work in 2120 Progress, Internet-Draft, draft-ietf-netconf-netconf- 2121 client-server-20, 8 July 2020, 2122 . 2125 [I-D.ietf-netconf-restconf-client-server] 2126 Watsen, K., "RESTCONF Client and Server Models", Work in 2127 Progress, Internet-Draft, draft-ietf-netconf-restconf- 2128 client-server-20, 8 July 2020, 2129 . 2132 [I-D.ietf-netconf-ssh-client-server] 2133 Watsen, K. and G. Wu, "YANG Groupings for SSH Clients and 2134 SSH Servers", Work in Progress, Internet-Draft, draft- 2135 ietf-netconf-ssh-client-server-21, 10 July 2020, 2136 . 2139 [I-D.ietf-netconf-tcp-client-server] 2140 Watsen, K. and M. Scharf, "YANG Groupings for TCP Clients 2141 and TCP Servers", Work in Progress, Internet-Draft, draft- 2142 ietf-netconf-tcp-client-server-07, 8 July 2020, 2143 . 2146 [I-D.ietf-netconf-tls-client-server] 2147 Watsen, K. and G. Wu, "YANG Groupings for TLS Clients and 2148 TLS Servers", Work in Progress, Internet-Draft, draft- 2149 ietf-netconf-tls-client-server-21, 10 July 2020, 2150 . 2153 [I-D.ietf-netconf-trust-anchors] 2154 Watsen, K., "A YANG Data Model for a Truststore", Work in 2155 Progress, Internet-Draft, draft-ietf-netconf-trust- 2156 anchors-12, 10 July 2020, . 2159 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2160 DOI 10.17487/RFC3688, January 2004, 2161 . 2163 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2164 and A. Bierman, Ed., "Network Configuration Protocol 2165 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2166 . 2168 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2169 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2170 . 2172 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2173 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2174 May 2017, . 2176 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 2177 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 2178 . 2180 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 2181 and R. Wilton, "Network Management Datastore Architecture 2182 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 2183 . 2185 [Std-802.1AR-2009] 2186 Group, W. -. H. L. L. P. W., "IEEE Standard for Local and 2187 metropolitan area networks - Secure Device Identity", 2188 December 2009, . 2191 Appendix A. Change Log 2193 This section is to be removed before publishing as an RFC. 2195 A.1. 00 to 01 2197 * Replaced the 'certificate-chain' structures with PKCS#7 2198 structures. (Issue #1) 2200 * Added 'private-key' as a configurable data node, and removed the 2201 'generate-private-key' and 'load-private-key' actions. (Issue #2) 2203 * Moved 'user-auth-credentials' to the ietf-ssh-client module. 2204 (Issues #4 and #5) 2206 A.2. 01 to 02 2208 * Added back 'generate-private-key' action. 2210 * Removed 'RESTRICTED' enum from the 'private-key' leaf type. 2212 * Fixed up a few description statements. 2214 A.3. 02 to 03 2216 * Changed draft's title. 2218 * Added missing references. 2220 * Collapsed sections and levels. 2222 * Added RFC 8174 to Requirements Language Section. 2224 * Renamed 'trusted-certificates' to 'pinned-certificates'. 2226 * Changed 'public-key' from config false to config true. 2228 * Switched 'host-key' from OneAsymmetricKey to definition from RFC 2229 4253. 2231 A.4. 03 to 04 2233 * Added typedefs around leafrefs to common keystore paths 2235 * Now tree diagrams reference ietf-netmod-yang-tree-diagrams 2237 * Removed Design Considerations section 2238 * Moved key and certificate definitions from data tree to groupings 2240 A.5. 04 to 05 2242 * Removed trust anchors (now in their own draft) 2244 * Added back global keystore structure 2246 * Added groupings enabling keys to either be locally defined or a 2247 reference to the keystore. 2249 A.6. 05 to 06 2251 * Added feature "local-keys-supported" 2253 * Added nacm:default-deny-all and nacm:default-deny-write 2255 * Renamed generate-asymmetric-key to generate-hidden-key 2257 * Added an install-hidden-key action 2259 * Moved actions inside fo the "asymmetric-key" container 2261 * Moved some groupings to draft-ietf-netconf-crypto-types 2263 A.7. 06 to 07 2265 * Removed a "require-instance false" 2267 * Clarified some description statements 2269 * Improved the keystore-usage examples 2271 A.8. 07 to 08 2273 * Added "local-definition" containers to avoid posibility of the 2274 action/notification statements being under a "case" statement. 2276 * Updated copyright date, boilerplate template, affiliation, folding 2277 algorithm, and reformatted the YANG module. 2279 A.9. 08 to 09 2281 * Added a 'description' statement to the 'must' in the /keystore/ 2282 asymmetric-key node explaining that the descendent values may 2283 exist in only, and that implementation MUST assert 2284 that the values are either configured or that they exist in 2285 . 2287 * Copied above 'must' statement (and description) into the local-or- 2288 keystore-asymmetric-key-grouping, local-or-keystore-asymmetric- 2289 key-with-certs-grouping, and local-or-keystore-end-entity-cert- 2290 with-key-grouping statements. 2292 A.10. 09 to 10 2294 * Updated draft title to match new truststore draft title 2296 * Moved everything under a top-level 'grouping' to enable use in 2297 other contexts. 2299 * Renamed feature from 'local-keys-supported' to 'local-definitions- 2300 supported' (same name used in truststore) 2302 * Removed the either-all-or-none 'must' expressions for the key's 2303 3-tuple values (since the values are now 'mandatory true' in 2304 crypto-types) 2306 * Example updated to reflect 'mandatory true' change in crypto-types 2307 draft 2309 A.11. 10 to 11 2311 * Replaced typedef asymmetric-key-certificate-ref with grouping 2312 asymmetric-key-certificate-ref-grouping. 2314 * Added feature feature 'key-generation'. 2316 * Cloned groupings symmetric-key-grouping, asymmetric-key-pair- 2317 grouping, asymmetric-key-pair-with-cert-grouping, and asymmetric- 2318 key-pair-with-certs-grouping from crypto-keys, augmenting into 2319 each new case statements for values that have been encrypted by 2320 other keys in the keystore. Refactored keystore model to use 2321 these groupings. 2323 * Added new 'symmetric-keys' lists, as a sibling to the existing 2324 'asymmetric-keys' list. 2326 * Added RPCs (not actions) 'generate-symmetric-key' and 'generate- 2327 asymmetric-key' to *return* a (potentially encrypted) key. 2329 A.12. 11 to 12 2331 * Updated to reflect crypto-type's draft using enumerations over 2332 identities. 2334 * Added examples for the 'generate-symmetric-key' and 'generate- 2335 asymmetric-key' RPCs. 2337 * Updated the Introduction section. 2339 A.13. 12 to 13 2341 * Updated examples to incorporate new "key-format" identities. 2343 * Made the two "generate-*-key" RPCs be "action" statements instead. 2345 A.14. 13 to 14 2347 * Updated YANG module and examples to incorporate the new 2348 iana-*-algorithm modules in the crypto-types draft.. 2350 A.15. 14 to 15 2352 * Added new "Support for Built-in Keys" section. 2354 * Added 'must' expressions asserting that the 'key-format' leaf 2355 whenever an encrypted key is specified. 2357 * Added local-or-keystore-symmetric-key-grouping for PSK support. 2359 A.16. 15 to 16 2361 * Moved the generate key actions to ietf-crypt-types as RPCs, which 2362 are augmented by ietf-keystore to support encrypted keys. 2363 Examples updated accordingly. 2365 * Added a SSH certificate-based key (RFC 6187) and a raw private key 2366 to the example instance document (partly so they could be 2367 referenced by examples in the SSH and TLS client/server drafts. 2369 A.17. 16 to 17 2371 * Removed augments to the "generate-symmetric-key" and "generate- 2372 asymmetric-key" groupings. 2374 * Removed "generate-symmetric-key" and "generate-asymmetric-key" 2375 examples. 2377 * Removed the "algorithm" nodes from remaining examples. 2379 * Updated the "Support for Built-in Keys" section. 2381 * Added new section "Encrypting Keys in Configuration". 2383 * Added a "Note to Reviewers" note to first page. 2385 A.18. 17 to 18 2387 * Removed dangling/unnecessary ref to RFC 8342. 2389 * r/MUST/SHOULD/ wrt strength of keys being configured over 2390 transports. 2392 * Added an example for the "certificate-expiration" notification. 2394 * Clarified that OS MAY have a multiplicity of underlying keystores 2395 and/or HSMs. 2397 * Clarified expected behavior for "built-in" keys in 2399 * Clarified the "Migrating Configuration to Another Server" section. 2401 * Expanded "Data Model Overview section(s) [remove "wall" of tree 2402 diagrams]. 2404 * Updated the Security Considerations section. 2406 A.19. 18 to 19 2408 * Updated examples to reflect new "cleartext-" prefix in the crypto- 2409 types draft. 2411 A.20. 19 to 20 2413 * Addressed SecDir comments from Magnus Nystroem and Sandra Murphy. 2415 Acknowledgements 2417 The authors would like to thank for following for lively discussions 2418 on list and in the halls (ordered by first name): Alan Luchuk, Andy 2419 Bierman, Benoit Claise, Bert Wijnen, Balazs Kovacs, David Lamparter, 2420 Eric Voit, Ladislav Lhotka, Liang Xia, Juergen Schoenwaelder, Mahesh 2421 Jethanandani, Magnus Nystroem, Martin Bjorklund, Mehmet Ersue, Phil 2422 Shafer, Radek Krejci, Ramkumar Dhanapal, Reshad Rahman, Sandra 2423 Murphy, Sean Turner, and Tom Petch. 2425 Author's Address 2427 Kent Watsen 2428 Watsen Networks 2430 Email: kent+ietf@watsen.net