idnits 2.17.1 draft-ietf-netconf-keystore-24.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 580 has weird spacing: '...-format ide...' == Line 588 has weird spacing: '...on-date yan...' == Line 592 has weird spacing: '...sr-info ct:...' == Line 594 has weird spacing: '...request ct:...' == Line 618 has weird spacing: '...-format ide...' == (10 more instances...) -- The document date (7 March 2022) is 753 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-21 == Outdated reference: A later version (-20) exists of draft-ietf-netconf-http-client-server-08 == Outdated reference: A later version (-35) exists of draft-ietf-netconf-keystore-23 == Outdated reference: A later version (-36) exists of draft-ietf-netconf-netconf-client-server-24 == Outdated reference: A later version (-36) exists of draft-ietf-netconf-restconf-client-server-24 == Outdated reference: A later version (-40) exists of draft-ietf-netconf-ssh-client-server-26 == Outdated reference: A later version (-24) exists of draft-ietf-netconf-tcp-client-server-11 == Outdated reference: A later version (-41) exists of draft-ietf-netconf-tls-client-server-26 == Outdated reference: A later version (-28) exists of draft-ietf-netconf-trust-anchors-16 == Outdated reference: A later version (-05) exists of draft-ma-netmod-with-system-02 Summary: 0 errors (**), 0 flaws (~~), 17 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 7 March 2022 5 Expires: 8 September 2022 7 A YANG Data Model for a Keystore 8 draft-ietf-netconf-keystore-24 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 * 2022-03-07 --> 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 8 September 2022. 59 Copyright Notice 61 Copyright (c) 2022 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 . . . . . . . . . . . . . . . . . . 35 86 4. Encrypting Keys in Configuration . . . . . . . . . . . . . . 37 87 5. Security Considerations . . . . . . . . . . . . . . . . . . . 41 88 5.1. Security of Data at Rest . . . . . . . . . . . . . . . . 41 89 5.2. Unconstrained Private Key Usage . . . . . . . . . . . . . 41 90 5.3. The "ietf-keystore" YANG Module . . . . . . . . . . . . . 41 91 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 42 92 6.1. The "IETF XML" Registry . . . . . . . . . . . . . . . . . 42 93 6.2. The "YANG Module Names" Registry . . . . . . . . . . . . 42 94 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 42 95 7.1. Normative References . . . . . . . . . . . . . . . . . . 42 96 7.2. Informative References . . . . . . . . . . . . . . . . . 43 97 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 45 98 A.1. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 45 99 A.2. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 45 100 A.3. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 46 101 A.4. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 46 102 A.5. 04 to 05 . . . . . . . . . . . . . . . . . . . . . . . . 46 103 A.6. 05 to 06 . . . . . . . . . . . . . . . . . . . . . . . . 46 104 A.7. 06 to 07 . . . . . . . . . . . . . . . . . . . . . . . . 47 105 A.8. 07 to 08 . . . . . . . . . . . . . . . . . . . . . . . . 47 106 A.9. 08 to 09 . . . . . . . . . . . . . . . . . . . . . . . . 47 107 A.10. 09 to 10 . . . . . . . . . . . . . . . . . . . . . . . . 47 108 A.11. 10 to 11 . . . . . . . . . . . . . . . . . . . . . . . . 48 109 A.12. 11 to 12 . . . . . . . . . . . . . . . . . . . . . . . . 48 110 A.13. 12 to 13 . . . . . . . . . . . . . . . . . . . . . . . . 48 111 A.14. 13 to 14 . . . . . . . . . . . . . . . . . . . . . . . . 48 112 A.15. 14 to 15 . . . . . . . . . . . . . . . . . . . . . . . . 48 113 A.16. 15 to 16 . . . . . . . . . . . . . . . . . . . . . . . . 49 114 A.17. 16 to 17 . . . . . . . . . . . . . . . . . . . . . . . . 49 115 A.18. 17 to 18 . . . . . . . . . . . . . . . . . . . . . . . . 49 116 A.19. 18 to 19 . . . . . . . . . . . . . . . . . . . . . . . . 50 117 A.20. 19 to 20 . . . . . . . . . . . . . . . . . . . . . . . . 50 118 A.21. 20 to 21 . . . . . . . . . . . . . . . . . . . . . . . . 50 119 A.22. 21 to 22 . . . . . . . . . . . . . . . . . . . . . . . . 50 120 A.23. 22 to 23 . . . . . . . . . . . . . . . . . . . . . . . . 50 121 A.24. 23 to 24 . . . . . . . . . . . . . . . . . . . . . . . . 51 122 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 51 123 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 51 125 1. Introduction 127 This document defines a YANG 1.1 [RFC7950] module called "ietf- 128 keystore" that enables centralized configuration of both symmetric 129 and asymmetric keys. The secret value for both key types may be 130 encrypted or hidden (see [I-D.ietf-netconf-crypto-types]. Asymmetric 131 keys may be associated with certificates. Notifications are sent 132 when certificates are about to expire. 134 The "ietf-keystore" module defines many "grouping" statements 135 intended for use by other modules that may import it. For instance, 136 there are groupings that define enabling a key to be either 137 configured locally (within the defining data model) or be a reference 138 to a key in the keystore. 140 Special consideration has been given for systems that have 141 cryptographic hardware, such as a Trusted Platform Module (TPM). 142 These systems are unique in that the cryptographic hardware hides the 143 secret key values. Additionally, such hardware is commonly 144 initialized when manufactured to protect a "built-in" asymmetric key 145 for which the public half is conveyed in an identity certificate 146 (e.g., an IDevID [Std-802.1AR-2018] certificate). Please see 147 Section 3 to see how built-in keys are supported. 149 This document intends to support existing practices; it does not 150 intend to define new behavior for systems to implement. To simplify 151 implementation, advanced key formats may be selectively implemented. 153 Implementations may utilize zero or more operating system level 154 keystore utilities and/or hardware security modules (HSMs). 156 1.1. Relation to other RFCs 158 This document presents one or more YANG modules [RFC7950] that are 159 part of a collection of RFCs that work together to, ultimately, 160 enable the configuration of the clients and servers of both the 161 NETCONF [RFC6241] and RESTCONF [RFC8040] protocols. 163 The modules have been defined in a modular fashion to enable their 164 use by other efforts, some of which are known to be in progress at 165 the time of this writing, with many more expected to be defined in 166 time. 168 The normative dependency relationship between the various RFCs in the 169 collection is presented in the below diagram. The labels in the 170 diagram represent the primary purpose provided by each RFC. 171 Hyperlinks to each RFC are provided below the diagram. 173 crypto-types 174 ^ ^ 175 / \ 176 / \ 177 truststore keystore 178 ^ ^ ^ ^ 179 | +---------+ | | 180 | | | | 181 | +------------+ | 182 tcp-client-server | / | | 183 ^ ^ ssh-client-server | | 184 | | ^ tls-client-server 185 | | | ^ ^ http-client-server 186 | | | | | ^ 187 | | | +-----+ +---------+ | 188 | | | | | | 189 | +-----------|--------|--------------+ | | 190 | | | | | | 191 +-----------+ | | | | | 192 | | | | | | 193 | | | | | | 194 netconf-client-server restconf-client-server 196 +=======================+===========================================+ 197 |Label in Diagram | Originating RFC | 198 +=======================+===========================================+ 199 |crypto-types | [I-D.ietf-netconf-crypto-types] | 200 +-----------------------+-------------------------------------------+ 201 |truststore | [I-D.ietf-netconf-trust-anchors] | 202 +-----------------------+-------------------------------------------+ 203 |keystore | [I-D.ietf-netconf-keystore] | 204 +-----------------------+-------------------------------------------+ 205 |tcp-client-server | [I-D.ietf-netconf-tcp-client-server] | 206 +-----------------------+-------------------------------------------+ 207 |ssh-client-server | [I-D.ietf-netconf-ssh-client-server] | 208 +-----------------------+-------------------------------------------+ 209 |tls-client-server | [I-D.ietf-netconf-tls-client-server] | 210 +-----------------------+-------------------------------------------+ 211 |http-client-server | [I-D.ietf-netconf-http-client-server] | 212 +-----------------------+-------------------------------------------+ 213 |netconf-client-server | [I-D.ietf-netconf-netconf-client-server] | 214 +-----------------------+-------------------------------------------+ 215 |restconf-client-server | [I-D.ietf-netconf-restconf-client-server] | 216 +-----------------------+-------------------------------------------+ 218 Table 1: Label to RFC Mapping 220 1.2. Specification Language 222 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 223 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 224 "OPTIONAL" in this document are to be interpreted as described in BCP 225 14 [RFC2119] [RFC8174] when, and only when, they appear in all 226 capitals, as shown here. 228 1.3. Terminology 230 The terms "client" and "server" are defined in [RFC6241] and are not 231 redefined here. 233 The term "keystore" is defined in this draft as a mechanism that 234 intends safeguard secrets placed into it for protection. 236 The nomenclature "" and "" are defined in 237 [RFC8342]. 239 The sentence fragments "augmented" and "augmented in" are used herein 240 as the past tense verbified form of the "augment" statement defined 241 in Section 7.17 of [RFC7950]. 243 1.4. Adherence to the NMDA 245 This document is compliant with Network Management Datastore 246 Architecture (NMDA) [RFC8342]. For instance, keys and associated 247 certificates installed during manufacturing (e.g., for an IDevID 248 certificate) are expected to appear in (see Section 3). 250 1.5. Conventions 252 Various examples used in this document use a placeholder value for 253 binary data that has been base64 encoded (e.g., "BASE64VALUE="). 254 This placeholder value is used as real base64 encoded structures are 255 often many lines long and hence distracting to the example being 256 presented. 258 2. The "ietf-keystore" Module 260 This section defines a YANG 1.1 [RFC7950] module called "ietf- 261 keystore". A high-level overview of the module is provided in 262 Section 2.1. Examples illustrating the module's use are provided in 263 Section 2.2. The YANG module itself is defined in Section 2.3. 265 2.1. Data Model Overview 267 This section provides an overview of the "ietf-keystore" module in 268 terms of its features, typedefs, groupings, and protocol-accessible 269 nodes. 271 2.1.1. Features 273 The following diagram lists all the "feature" statements defined in 274 the "ietf-keystore" module: 276 Features: 277 +-- central-keystore-supported 278 +-- local-definitions-supported 280 | The diagram above uses syntax that is similar to but not 281 | defined in [RFC8340]. 283 2.1.2. Typedefs 285 The following diagram lists the "typedef" statements defined in the 286 "ietf-keystore" module: 288 Typedefs: 289 leafref 290 +-- symmetric-key-ref 291 +-- asymmetric-key-ref 293 | The diagram above uses syntax that is similar to but not 294 | defined in [RFC8340]. 296 Comments: 298 * All the typedefs defined in the "ietf-keystore" module extend the 299 base "leafref" type defined in [RFC7950]. 301 * The leafrefs refer to symmetric and asymmetric keys in the central 302 keystore, when this module is implemented. 304 * These typedefs are provided as an aid to downstream modules that 305 import the "ietf-keystore" module. 307 2.1.3. Groupings 309 The "ietf-keystore" module defines the following "grouping" 310 statements: 312 * encrypted-by-choice-grouping 313 * asymmetric-key-certificate-ref-grouping 314 * local-or-keystore-symmetric-key-grouping 315 * local-or-keystore-asymmetric-key-grouping 316 * local-or-keystore-asymmetric-key-with-certs-grouping 317 * local-or-keystore-end-entity-cert-with-key-grouping 318 * keystore-grouping 320 Each of these groupings are presented in the following subsections. 322 2.1.3.1. The "encrypted-by-choice-grouping" Grouping 324 The following tree diagram [RFC8340] illustrates the "encrypted-by- 325 choice-grouping" grouping: 327 | The grouping's name is intended to be parsed "(encrypted- 328 | by)-(choice)-(grouping)", not as "(encrypted)-(by- 329 | choice)-(grouping)". 331 grouping encrypted-by-choice-grouping 332 +-- (encrypted-by-choice) 333 +--:(symmetric-key-ref) 334 | {central-keystore-supported,symmetric-keys}? 335 | +-- symmetric-key-ref? ks:symmetric-key-ref 336 +--:(asymmetric-key-ref) 337 {central-keystore-supported,asymmetric-keys}? 338 +-- asymmetric-key-ref? ks:asymmetric-key-ref 340 Comments: 342 * This grouping defines a "choice" statement with options to 343 reference either a symmetric or an asymmetric key configured in 344 the keystore. 346 * This grouping is usable only when the keystore module is 347 implemented. Servers defining custom keystore locations MUST 348 augment in alternate "encrypted-by" references to the alternate 349 locations. 351 2.1.3.2. The "asymmetric-key-certificate-ref-grouping" Grouping 353 The following tree diagram [RFC8340] illustrates the "asymmetric-key- 354 certificate-ref-grouping" grouping: 356 grouping asymmetric-key-certificate-ref-grouping 357 +-- asymmetric-key? ks:asymmetric-key-ref 358 | {central-keystore-supported,asymmetric-keys}? 359 +-- certificate? leafref 361 Comments: 363 * This grouping defines a reference to a certificate in two parts: 364 the first being the name of the asymmetric key the certificate is 365 associated with, and the second being the name of the certificate 366 itself. 368 * This grouping is usable only when the keystore module is 369 implemented. Servers defining custom keystore locations MAY 370 define an alternate grouping for references to the alternate 371 locations. 373 2.1.3.3. The "local-or-keystore-symmetric-key-grouping" Grouping 375 The following tree diagram [RFC8340] illustrates the "local-or- 376 keystore-symmetric-key-grouping" grouping: 378 grouping local-or-keystore-symmetric-key-grouping 379 +-- (local-or-keystore) 380 +--:(local) {local-definitions-supported,symmetric-keys}? 381 | +-- local-definition 382 | +---u ct:symmetric-key-grouping 383 +--:(keystore) {central-keystore-supported,symmetric-keys}? 384 +-- keystore-reference? ks:symmetric-key-ref 386 Comments: 388 * The "local-or-keystore-symmetric-key-grouping" grouping is 389 provided soley as convenience to downstream modules that wish to 390 offer an option for whether a symmetric key is defined locally or 391 as a reference to a symmetric key in the keystore. 393 * A "choice" statement is used to expose the various options. Each 394 option is enabled by a "feature" statement. Additional "case" 395 statements MAY be augmented in if, e.g., there is a need to 396 reference a symmetric key in an alternate location. 398 * For the "local-definition" option, the definition uses the 399 "symmetric-key-grouping" grouping discussed in Section 2.1.4.3 of 400 [I-D.ietf-netconf-crypto-types]. 402 * For the "keystore" option, the "keystore-reference" is an instance 403 of the "symmetric-key-ref" discussed in Section 2.1.2. 405 2.1.3.4. The "local-or-keystore-asymmetric-key-grouping" Grouping 407 The following tree diagram [RFC8340] illustrates the "local-or- 408 keystore-asymmetric-key-grouping" grouping: 410 grouping local-or-keystore-asymmetric-key-grouping 411 +-- (local-or-keystore) 412 +--:(local) {local-definitions-supported,asymmetric-keys}? 413 | +-- local-definition 414 | +---u ct:asymmetric-key-pair-grouping 415 +--:(keystore) {central-keystore-supported,asymmetric-keys}? 416 +-- keystore-reference? ks:asymmetric-key-ref 418 Comments: 420 * The "local-or-keystore-asymmetric-key-grouping" grouping is 421 provided soley as convenience to downstream modules that wish to 422 offer an option for whether an asymmetric key is defined locally 423 or as a reference to an asymmetric key in the keystore. 425 * A "choice" statement is used to expose the various options. Each 426 option is enabled by a "feature" statement. Additional "case" 427 statements MAY be augmented in if, e.g., there is a need to 428 reference an asymmetric key in an alternate location. 430 * For the "local-definition" option, the definition uses the 431 "asymmetric-key-pair-grouping" grouping discussed in 432 Section 2.1.4.5 of [I-D.ietf-netconf-crypto-types]. 434 * For the "keystore" option, the "keystore-reference" is an instance 435 of the "asymmetric-key-ref" typedef discussed in Section 2.1.2. 437 2.1.3.5. The "local-or-keystore-asymmetric-key-with-certs-grouping" 438 Grouping 440 The following tree diagram [RFC8340] illustrates the "local-or- 441 keystore-asymmetric-key-with-certs-grouping" grouping: 443 grouping local-or-keystore-asymmetric-key-with-certs-grouping 444 +-- (local-or-keystore) 445 +--:(local) {local-definitions-supported,asymmetric-keys}? 446 | +-- local-definition 447 | +---u ct:asymmetric-key-pair-with-certs-grouping 448 +--:(keystore) {central-keystore-supported,asymmetric-keys}? 449 +-- keystore-reference? ks:asymmetric-key-ref 451 Comments: 453 * The "local-or-keystore-asymmetric-key-with-certs-grouping" 454 grouping is provided soley as convenience to downstream modules 455 that wish to offer an option for whether an asymmetric key is 456 defined locally or as a reference to an asymmetric key in the 457 keystore. 459 * A "choice" statement is used to expose the various options. Each 460 option is enabled by a "feature" statement. Additional "case" 461 statements MAY be augmented in if, e.g., there is a need to 462 reference an asymmetric key in an alternate location. 464 * For the "local-definition" option, the definition uses the 465 "asymmetric-key-pair-with-certs-grouping" grouping discussed in 466 Section 2.1.4.11 of [I-D.ietf-netconf-crypto-types]. 468 * For the "keystore" option, the "keystore-reference" is an instance 469 of the "asymmetric-key-ref" typedef discussed in Section 2.1.2. 471 2.1.3.6. The "local-or-keystore-end-entity-cert-with-key-grouping" 472 Grouping 474 The following tree diagram [RFC8340] illustrates the "local-or- 475 keystore-end-entity-cert-with-key-grouping" grouping: 477 grouping local-or-keystore-end-entity-cert-with-key-grouping 478 +-- (local-or-keystore) 479 +--:(local) {local-definitions-supported,asymmetric-keys}? 480 | +-- local-definition 481 | +---u ct:asymmetric-key-pair-with-cert-grouping 482 +--:(keystore) {central-keystore-supported,asymmetric-keys}? 483 +-- keystore-reference 484 +---u asymmetric-key-certificate-ref-grouping 486 Comments: 488 * The "local-or-keystore-end-entity-cert-with-key-grouping" grouping 489 is provided soley as convenience to downstream modules that wish 490 to offer an option for whether a symmetric key is defined locally 491 or as a reference to a symmetric key in the keystore. 493 * A "choice" statement is used to expose the various options. Each 494 option is enabled by a "feature" statement. Additional "case" 495 statements MAY be augmented in if, e.g., there is a need to 496 reference a symmetric key in an alternate location. 498 * For the "local-definition" option, the definition uses the 499 "asymmetric-key-pair-with-certs-grouping" grouping discussed in 500 Section 2.1.4.11 of [I-D.ietf-netconf-crypto-types]. 502 * For the "keystore" option, the "keystore-reference" uses the 503 "asymmetric-key-certificate-ref-grouping" grouping discussed in 504 Section 2.1.3.2. 506 2.1.3.7. The "keystore-grouping" Grouping 508 The following tree diagram [RFC8340] illustrates the "keystore- 509 grouping" grouping: 511 grouping keystore-grouping 512 +-- asymmetric-keys {asymmetric-keys}? 513 | +-- asymmetric-key* [name] 514 | +-- name? string 515 | +---u ct:asymmetric-key-pair-with-certs-grouping 516 +-- symmetric-keys {symmetric-keys}? 517 +-- symmetric-key* [name] 518 +-- name? string 519 +---u ct:symmetric-key-grouping 521 Comments: 523 * The "keystore-grouping" grouping defines a keystore instance as 524 being composed of symmetric and asymmetric keys. The structure 525 for the symmetric and asymmetric keys is essentially the same, 526 being a "list" inside a "container". 528 * For asymmetric keys, each "asymmetric-key" uses the "asymmetric- 529 key-pair-with-certs-grouping" grouping discussed in 530 Section 2.1.4.11 of [I-D.ietf-netconf-crypto-types]. 532 * For symmetric keys, each "symmetric-key" uses the "symmetric-key- 533 grouping" grouping discussed in Section 2.1.4.3 of 534 [I-D.ietf-netconf-crypto-types]. 536 2.1.4. Protocol-accessible Nodes 538 The following tree diagram [RFC8340] lists all the protocol- 539 accessible nodes defined in the "ietf-keystore" module, without 540 expanding the "grouping" statements: 542 module: ietf-keystore 543 +--rw keystore 544 +---u keystore-grouping 546 The following tree diagram [RFC8340] lists all the protocol- 547 accessible nodes defined in the "ietf-keystore" module, with all 548 "grouping" statements expanded, enabling the keystore's full 549 structure to be seen: 551 =============== NOTE: '\' line wrapping per RFC 8792 ================ 553 module: ietf-keystore 554 +--rw keystore 555 +--rw asymmetric-keys {asymmetric-keys}? 556 | +--rw asymmetric-key* [name] 557 | +--rw name string 558 | +--rw public-key-format identityref 559 | +--rw public-key binary 560 | +--rw private-key-format? identityref 561 | +--rw (private-key-type) 562 | | +--:(cleartext-private-key) 563 | | | +--rw cleartext-private-key? binary 564 | | +--:(hidden-private-key) {hidden-keys}? 565 | | | +--rw hidden-private-key? empty 566 | | +--:(encrypted-private-key) {private-key-encryption}? 567 | | +--rw encrypted-private-key 568 | | +--rw encrypted-by 569 | | | +--rw (encrypted-by-choice) 570 | | | +--:(symmetric-key-ref) 571 | | | | {central-keystore-supported,symme\ 572 tric-keys}? 573 | | | | +--rw symmetric-key-ref? 574 | | | | ks:symmetric-key-ref 575 | | | +--:(asymmetric-key-ref) 576 | | | {central-keystore-supported,asymm\ 577 etric-keys}? 578 | | | +--rw asymmetric-key-ref? 579 | | | ks:asymmetric-key-ref 580 | | +--rw encrypted-value-format identityref 581 | | +--rw encrypted-value binary 582 | +--rw certificates 583 | | +--rw certificate* [name] 584 | | +--rw name string 585 | | +--rw cert-data end-entity-cert-cms 586 | | +---n certificate-expiration 587 | | {certificate-expiration-notification}? 588 | | +-- expiration-date yang:date-and-time 589 | +---x generate-certificate-signing-request 590 | {certificate-signing-request-generation}? 591 | +---w input 592 | | +---w csr-info ct:csr-info 593 | +--ro output 594 | +--ro certificate-signing-request ct:csr 595 +--rw symmetric-keys {symmetric-keys}? 596 +--rw symmetric-key* [name] 597 +--rw name string 598 +--rw key-format? identityref 599 +--rw (key-type) 600 +--:(cleartext-key) 601 | +--rw cleartext-key? binary 602 +--:(hidden-key) {hidden-keys}? 603 | +--rw hidden-key? empty 604 +--:(encrypted-key) {symmetric-key-encryption}? 605 +--rw encrypted-key 606 +--rw encrypted-by 607 | +--rw (encrypted-by-choice) 608 | +--:(symmetric-key-ref) 609 | | {central-keystore-supported,symme\ 610 tric-keys}? 611 | | +--rw symmetric-key-ref? 612 | | ks:symmetric-key-ref 613 | +--:(asymmetric-key-ref) 614 | {central-keystore-supported,asymm\ 615 etric-keys}? 616 | +--rw asymmetric-key-ref? 617 | ks:asymmetric-key-ref 618 +--rw encrypted-value-format identityref 619 +--rw encrypted-value binary 621 Comments: 623 * Protocol-accessible nodes are those nodes that are accessible when 624 the module is "implemented", as described in Section 5.6.5 of 625 [RFC7950]. 627 * The protocol-accessible nodes for the "ietf-keystore" module are 628 an instance of the "keystore-grouping" grouping discussed in 629 Section 2.1.3.7. 631 * The reason for why "keystore-grouping" exists separate from the 632 protocol-accessible nodes definition is so as to enable instances 633 of the keystore to be instantiated in other locations, as may be 634 needed or desired by some modules. 636 2.2. Example Usage 638 The examples in this section are encoded using XML, such as might be 639 the case when using the NETCONF protocol. Other encodings MAY be 640 used, such as JSON when using the RESTCONF protocol. 642 2.2.1. A Keystore Instance 644 The following example illustrates keys in . Please see 645 Section 3 for an example illustrating built-in values in 646 . 648 =============== NOTE: '\' line wrapping per RFC 8792 ================ 650 654 655 656 cleartext-symmetric-key 657 ct:octet-string-key-format 658 BASE64VALUE= 659 660 661 hidden-symmetric-key 662 663 664 665 encrypted-symmetric-key 666 ct:one-symmetric-key-format 667 668 669 hidden-asymmetric-key 671 672 673 ct:cms-enveloped-data-format 674 675 BASE64VALUE= 676 677 678 680 681 682 ssh-rsa-key 683 684 ct:ssh-public-key-format 685 686 BASE64VALUE= 687 688 ct:rsa-private-key-format 689 690 BASE64VALUE= 691 692 693 ssh-rsa-key-with-cert 694 695 ct:subject-public-key-info-format 697 698 BASE64VALUE= 699 700 ct:rsa-private-key-format 701 702 BASE64VALUE= 703 704 705 ex-rsa-cert2 706 BASE64VALUE= 707 708 709 710 711 raw-private-key 712 713 ct:subject-public-key-info-format 714 715 BASE64VALUE= 716 717 ct:rsa-private-key-format 718 719 BASE64VALUE= 720 721 722 rsa-asymmetric-key 723 724 ct:subject-public-key-info-format 725 726 BASE64VALUE= 727 728 ct:rsa-private-key-format 729 730 BASE64VALUE= 731 732 733 ex-rsa-cert 734 BASE64VALUE= 735 736 737 738 739 ec-asymmetric-key 740 741 ct:subject-public-key-info-format 742 743 BASE64VALUE= 744 745 ct:ec-private-key-format 746 747 BASE64VALUE= 748 749 750 ex-ec-cert 751 BASE64VALUE= 752 753 754 755 756 hidden-asymmetric-key 757 758 ct:subject-public-key-info-format 759 760 BASE64VALUE= 761 762 763 764 builtin-idevid-cert 765 BASE64VALUE= 766 767 768 my-ldevid-cert 769 BASE64VALUE= 770 771 772 773 774 encrypted-asymmetric-key 775 776 ct:subject-public-key-info-format 777 778 BASE64VALUE= 779 780 ct:one-asymmetric-key-format 781 782 783 784 encrypted-symmetric-key 786 787 788 ct:cms-encrypted-data-format 789 790 BASE64VALUE= 791 792 794 795 797 2.2.2. A Certificate Expiration Notification 799 The following example illustrates a "certificate-expiration" 800 notification for a certificate associated with a key configured in 801 the keystore. 803 =============== NOTE: '\' line wrapping per RFC 8792 ================ 805 807 2018-05-25T00:01:00Z 808 809 810 811 hidden-asymmetric-key 812 813 814 my-ldevid-cert 815 816 2018-08-05T14:18:53-05:00 818 819 820 821 822 823 824 826 2.2.3. The "Local or Keystore" Groupings 828 This section illustrates the various "local-or-keystore" groupings 829 defined in the "ietf-keystore" module, specifically the "local-or- 830 keystore-symmetric-key-grouping" (Section 2.1.3.3), "local-or- 831 keystore-asymmetric-key-grouping" (Section 2.1.3.4), "local-or- 832 keystore-asymmetric-key-with-certs-grouping" (Section 2.1.3.5), and 833 "local-or-keystore-end-entity-cert-with-key-grouping" 834 (Section 2.1.3.6) groupings. 836 These examples assume the existence of an example module called "ex- 837 keystore-usage" having the namespace "http://example.com/ns/example- 838 keystore-usage". 840 The ex-keystore-usage module is first presented using tree diagrams 841 [RFC8340], followed by an instance example illustrating all the 842 "local-or-keystore" groupings in use, followed by the YANG module 843 itself. 845 The following tree diagram illustrates "ex-keystore-usage" without 846 expanding the "grouping" statements: 848 module: ex-keystore-usage 849 +--rw keystore-usage 850 +--rw symmetric-key* [name] 851 | +--rw name string 852 | +---u ks:local-or-keystore-symmetric-key-grouping 853 +--rw asymmetric-key* [name] 854 | +--rw name string 855 | +---u ks:local-or-keystore-asymmetric-key-grouping 856 +--rw asymmetric-key-with-certs* [name] 857 | +--rw name 858 | | string 859 | +---u ks:local-or-keystore-asymmetric-key-with-certs-grouping 860 +--rw end-entity-cert-with-key* [name] 861 +--rw name 862 | string 863 +---u ks:local-or-keystore-end-entity-cert-with-key-grouping 865 The following tree diagram illustrates the "ex-keystore-usage" 866 module, with all "grouping" statements expanded, enabling the usage's 867 full structure to be seen: 869 =============== NOTE: '\' line wrapping per RFC 8792 ================ 871 module: ex-keystore-usage 872 +--rw keystore-usage 873 +--rw symmetric-key* [name] 874 | +--rw name string 875 | +--rw (local-or-keystore) 876 | +--:(local) {local-definitions-supported,symmetric-keys}? 877 | | +--rw local-definition 878 | | +--rw key-format? identityref 879 | | +--rw (key-type) 880 | | +--:(cleartext-key) 881 | | | +--rw cleartext-key? binary 882 | | +--:(hidden-key) {hidden-keys}? 883 | | | +--rw hidden-key? empty 884 | | +--:(encrypted-key) {symmetric-key-encryption}? 885 | | +--rw encrypted-key 886 | | +--rw encrypted-by 887 | | +--rw encrypted-value-format identityref 888 | | +--rw encrypted-value binary 889 | +--:(keystore) 890 | {central-keystore-supported,symmetric-keys}? 891 | +--rw keystore-reference? ks:symmetric-key-ref 892 +--rw asymmetric-key* [name] 893 | +--rw name string 894 | +--rw (local-or-keystore) 895 | +--:(local) {local-definitions-supported,asymmetric-keys}? 896 | | +--rw local-definition 897 | | +--rw public-key-format identityref 898 | | +--rw public-key binary 899 | | +--rw private-key-format? identityref 900 | | +--rw (private-key-type) 901 | | +--:(cleartext-private-key) 902 | | | +--rw cleartext-private-key? binary 903 | | +--:(hidden-private-key) {hidden-keys}? 904 | | | +--rw hidden-private-key? empty 905 | | +--:(encrypted-private-key) 906 | | {private-key-encryption}? 907 | | +--rw encrypted-private-key 908 | | +--rw encrypted-by 909 | | +--rw encrypted-value-format identityref 910 | | +--rw encrypted-value binary 911 | +--:(keystore) 912 | {central-keystore-supported,asymmetric-keys}? 913 | +--rw keystore-reference? ks:asymmetric-key-ref 914 +--rw asymmetric-key-with-certs* [name] 915 | +--rw name string 916 | +--rw (local-or-keystore) 917 | +--:(local) {local-definitions-supported,asymmetric-keys}? 918 | | +--rw local-definition 919 | | +--rw public-key-format 920 | | | identityref 921 | | +--rw public-key binary 922 | | +--rw private-key-format? 923 | | | identityref 924 | | +--rw (private-key-type) 925 | | | +--:(cleartext-private-key) 926 | | | | +--rw cleartext-private-key? binary 927 | | | +--:(hidden-private-key) {hidden-keys}? 928 | | | | +--rw hidden-private-key? empty 929 | | | +--:(encrypted-private-key) 930 | | | {private-key-encryption}? 931 | | | +--rw encrypted-private-key 932 | | | +--rw encrypted-by 933 | | | +--rw encrypted-value-format identityref 934 | | | +--rw encrypted-value binary 935 | | +--rw certificates 936 | | | +--rw certificate* [name] 937 | | | +--rw name string 938 | | | +--rw cert-data 939 | | | | end-entity-cert-cms 940 | | | +---n certificate-expiration 941 | | | {certificate-expiration-notification}? 942 | | | +-- expiration-date yang:date-and-time 943 | | +---x generate-certificate-signing-request 944 | | {certificate-signing-request-generation}? 945 | | +---w input 946 | | | +---w csr-info ct:csr-info 947 | | +--ro output 948 | | +--ro certificate-signing-request ct:csr 949 | +--:(keystore) 950 | {central-keystore-supported,asymmetric-keys}? 951 | +--rw keystore-reference? ks:asymmetric-key-ref 952 +--rw end-entity-cert-with-key* [name] 953 +--rw name string 954 +--rw (local-or-keystore) 955 +--:(local) {local-definitions-supported,asymmetric-keys}? 956 | +--rw local-definition 957 | +--rw public-key-format 958 | | identityref 959 | +--rw public-key binary 960 | +--rw private-key-format? 961 | | identityref 962 | +--rw (private-key-type) 963 | | +--:(cleartext-private-key) 964 | | | +--rw cleartext-private-key? binary 965 | | +--:(hidden-private-key) {hidden-keys}? 966 | | | +--rw hidden-private-key? empty 967 | | +--:(encrypted-private-key) 968 | | {private-key-encryption}? 969 | | +--rw encrypted-private-key 970 | | +--rw encrypted-by 971 | | +--rw encrypted-value-format identityref 972 | | +--rw encrypted-value binary 973 | +--rw cert-data? 974 | | end-entity-cert-cms 975 | +---n certificate-expiration 976 | | {certificate-expiration-notification}? 977 | | +-- expiration-date yang:date-and-time 978 | +---x generate-certificate-signing-request 979 | {certificate-signing-request-generation}? 980 | +---w input 981 | | +---w csr-info ct:csr-info 982 | +--ro output 983 | +--ro certificate-signing-request ct:csr 984 +--:(keystore) 985 {central-keystore-supported,asymmetric-keys}? 986 +--rw keystore-reference 987 +--rw asymmetric-key? ks:asymmetric-key-ref 988 | {central-keystore-supported,asymmetric-keys\ 989 }? 990 +--rw certificate? leafref 992 The following example provides two equivalent instances of each 993 grouping, the first being a reference to a keystore and the second 994 being locally-defined. The instance having a reference to a keystore 995 is consistent with the keystore defined in Section 2.2.1. The two 996 instances are equivalent, as the locally-defined instance example 997 contains the same values defined by the keystore instance referenced 998 by its sibling example. 1000 1004 1005 1007 1008 example 1a 1009 cleartext-symmetric-key 1010 1012 1013 example 1b 1014 1015 ct:octet-string-key-format 1016 BASE64VALUE= 1017 1018 1020 1021 1023 1024 example 2a 1025 rsa-asymmetric-key 1026 1028 1029 example 2b 1030 1031 1032 ct:subject-public-key-info-format 1033 1034 BASE64VALUE= 1035 1036 ct:rsa-private-key-format 1037 1038 BASE64VALUE= 1039 1040 1042 1043 1045 1046 example 3a 1047 rsa-asymmetric-key 1048 1050 1051 example 3b 1052 1053 1054 ct:subject-public-key-info-format 1055 1056 BASE64VALUE= 1057 1058 ct:rsa-private-key-format 1059 1060 BASE64VALUE= 1061 1062 1063 a locally-defined cert 1064 BASE64VALUE= 1065 1066 1067 1068 1070 1071 1073 1074 example 4a 1075 1076 rsa-asymmetric-key 1077 ex-rsa-cert 1078 1079 1081 1082 example 4b 1083 1084 1085 ct:subject-public-key-info-format 1086 1087 BASE64VALUE= 1088 1089 ct:rsa-private-key-format 1090 1091 BASE64VALUE= 1092 BASE64VALUE= 1093 1094 1096 1098 Following is the "ex-keystore-usage" module's YANG definition: 1100 module ex-keystore-usage { 1101 yang-version 1.1; 1102 namespace "http://example.com/ns/example-keystore-usage"; 1103 prefix eku; 1105 import ietf-keystore { 1106 prefix ks; 1107 reference 1108 "RFC CCCC: A YANG Data Model for a Keystore"; 1109 } 1111 organization 1112 "Example Corporation"; 1114 contact 1115 "Author: YANG Designer "; 1117 description 1118 "This module illustrates notable groupings defined in 1119 the 'ietf-keystore' module."; 1121 revision 2022-03-07 { 1122 description 1123 "Initial version"; 1124 reference 1125 "RFC CCCC: A YANG Data Model for a Keystore"; 1126 } 1128 container keystore-usage { 1129 description 1130 "An illustration of the various keystore groupings."; 1131 list symmetric-key { 1132 key "name"; 1133 leaf name { 1134 type string; 1135 description 1136 "An arbitrary name for this key."; 1137 } 1138 uses ks:local-or-keystore-symmetric-key-grouping; 1139 description 1140 "An symmetric key that may be configured locally or be a 1141 reference to a symmetric key in the keystore."; 1142 } 1143 list asymmetric-key { 1144 key "name"; 1145 leaf name { 1146 type string; 1147 description 1148 "An arbitrary name for this key."; 1149 } 1150 uses ks:local-or-keystore-asymmetric-key-grouping; 1151 description 1152 "An asymmetric key, with no certs, that may be configured 1153 locally or be a reference to an asymmetric key in the 1154 keystore. The intent is to reference just the asymmetric 1155 key, not any certificates that may also be associated 1156 with the asymmetric key."; 1157 } 1158 list asymmetric-key-with-certs { 1159 key "name"; 1160 leaf name { 1161 type string; 1162 description 1163 "An arbitrary name for this key."; 1164 } 1165 uses ks:local-or-keystore-asymmetric-key-with-certs-grouping; 1166 description 1167 "An asymmetric key and its associated certs, that may be 1168 configured locally or be a reference to an asymmetric key 1169 (and its associated certs) in the keystore."; 1170 } 1171 list end-entity-cert-with-key { 1172 key "name"; 1173 leaf name { 1174 type string; 1175 description 1176 "An arbitrary name for this key."; 1177 } 1178 uses ks:local-or-keystore-end-entity-cert-with-key-grouping; 1179 description 1180 "An end-entity certificate and its associated asymmetric 1181 key, that may be configured locally or be a reference 1182 to another certificate (and its associated asymmetric 1183 key) in the keystore."; 1184 } 1185 } 1186 } 1188 2.3. YANG Module 1190 This YANG module has normative references to [RFC8341] and 1191 [I-D.ietf-netconf-crypto-types]. 1193 file "ietf-keystore@2022-03-07.yang" 1195 module ietf-keystore { 1196 yang-version 1.1; 1197 namespace "urn:ietf:params:xml:ns:yang:ietf-keystore"; 1198 prefix ks; 1200 import ietf-netconf-acm { 1201 prefix nacm; 1202 reference 1203 "RFC 8341: Network Configuration Access Control Model"; 1204 } 1206 import ietf-crypto-types { 1207 prefix ct; 1208 reference 1209 "RFC AAAA: YANG Data Types and Groupings for Cryptography"; 1210 } 1212 organization 1213 "IETF NETCONF (Network Configuration) Working Group"; 1215 contact 1216 "WG Web: https://datatracker.ietf.org/wg/netconf 1217 WG List: NETCONF WG list 1218 Author: Kent Watsen "; 1220 description 1221 "This module defines a 'keystore' to centralize management 1222 of security credentials. 1224 Copyright (c) 2021 IETF Trust and the persons identified 1225 as authors of the code. All rights reserved. 1227 Redistribution and use in source and binary forms, with 1228 or without modification, is permitted pursuant to, and 1229 subject to the license terms contained in, the Revised 1230 BSD License set forth in Section 4.c of the IETF Trust's 1231 Legal Provisions Relating to IETF Documents 1232 (https://trustee.ietf.org/license-info). 1234 This version of this YANG module is part of RFC CCCC 1235 (https://www.rfc-editor.org/info/rfcCCCC); see the RFC 1236 itself for full legal notices. 1238 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1239 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 1240 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 1241 are to be interpreted as described in BCP 14 (RFC 2119) 1242 (RFC 8174) when, and only when, they appear in all 1243 capitals, as shown here."; 1245 revision 2022-03-07 { 1246 description 1247 "Initial version"; 1248 reference 1249 "RFC CCCC: A YANG Data Model for a Keystore"; 1250 } 1252 /****************/ 1253 /* Features */ 1254 /****************/ 1256 feature central-keystore-supported { 1257 description 1258 "The 'central-keystore-supported' feature indicates that 1259 the server supports the keystore (i.e., implements the 1260 'ietf-keystore' module)."; 1261 } 1263 feature local-definitions-supported { 1264 description 1265 "The 'local-definitions-supported' feature indicates that 1266 the server supports locally-defined keys."; 1267 } 1268 feature asymmetric-keys { 1269 description 1270 "The 'asymmetric-keys' feature indicates that the server 1271 supports asymmetric keys in keystores."; 1272 } 1274 feature symmetric-keys { 1275 description 1276 "The 'symmetric-keys' feature indicates that the server 1277 supports symmetric keys in keystores."; 1278 } 1280 /****************/ 1281 /* Typedefs */ 1282 /****************/ 1284 typedef symmetric-key-ref { 1285 type leafref { 1286 path "/ks:keystore/ks:symmetric-keys/ks:symmetric-key" 1287 + "/ks:name"; 1288 } 1289 description 1290 "This typedef enables modules to easily define a reference 1291 to a symmetric key stored in the keystore, when this 1292 module is implemented."; 1293 } 1295 typedef asymmetric-key-ref { 1296 type leafref { 1297 path "/ks:keystore/ks:asymmetric-keys/ks:asymmetric-key" 1298 + "/ks:name"; 1299 } 1300 description 1301 "This typedef enables modules to easily define a reference 1302 to an asymmetric key stored in the keystore, when this 1303 module is implemented."; 1304 } 1306 /*****************/ 1307 /* Groupings */ 1308 /*****************/ 1310 grouping encrypted-by-choice-grouping { 1311 description 1312 "A grouping that defines a 'choice' statement that can be 1313 augmented into the 'encrypted-by' node, present in the 1314 'symmetric-key-grouping' and 'asymmetric-key-pair-grouping' 1315 groupings defined in RFC AAAA, enabling references to keys 1316 in the keystore, when this module is implemented."; 1317 choice encrypted-by-choice { 1318 nacm:default-deny-write; 1319 mandatory true; 1320 description 1321 "A choice amongst other symmetric or asymmetric keys."; 1322 case symmetric-key-ref { 1323 if-feature "central-keystore-supported"; 1324 if-feature "symmetric-keys"; 1325 leaf symmetric-key-ref { 1326 type ks:symmetric-key-ref; 1327 description 1328 "Identifies the symmetric key used to encrypt the 1329 associated key."; 1330 } 1331 } 1332 case asymmetric-key-ref { 1333 if-feature "central-keystore-supported"; 1334 if-feature "asymmetric-keys"; 1335 leaf asymmetric-key-ref { 1336 type ks:asymmetric-key-ref; 1337 description 1338 "Identifies the asymmetric key whose public key 1339 encrypted the associated key."; 1340 } 1341 } 1342 } 1343 } 1345 grouping asymmetric-key-certificate-ref-grouping { 1346 description 1347 "This grouping defines a reference to a specific certificate 1348 associated with an asymmetric key stored in the keystore, 1349 when this module is implemented."; 1350 leaf asymmetric-key { 1351 nacm:default-deny-write; 1352 if-feature "central-keystore-supported"; 1353 if-feature "asymmetric-keys"; 1354 type ks:asymmetric-key-ref; 1355 must '../certificate'; 1356 description 1357 "A reference to an asymmetric key in the keystore."; 1358 } 1359 leaf certificate { 1360 nacm:default-deny-write; 1361 type leafref { 1362 path "/ks:keystore/ks:asymmetric-keys/ks:asymmetric-key" 1363 + "[ks:name = current()/../asymmetric-key]/" 1364 + "ks:certificates/ks:certificate/ks:name"; 1365 } 1366 must '../asymmetric-key'; 1367 description 1368 "A reference to a specific certificate of the 1369 asymmetric key in the keystore."; 1370 } 1371 } 1373 // local-or-keystore-* groupings 1375 grouping local-or-keystore-symmetric-key-grouping { 1376 description 1377 "A grouping that expands to allow the symmetric key to be 1378 either stored locally, i.e., within the using data model, 1379 or a reference to a symmetric key stored in the keystore. 1381 Servers that do not 'implement' this module, and hence 1382 'central-keystore-supported' is not defined, SHOULD 1383 augment in custom 'case' statements enabling references 1384 to the alternate keystore locations."; 1385 choice local-or-keystore { 1386 nacm:default-deny-write; 1387 mandatory true; 1388 description 1389 "A choice between an inlined definition and a definition 1390 that exists in the keystore."; 1391 case local { 1392 if-feature "local-definitions-supported"; 1393 if-feature "symmetric-keys"; 1394 container local-definition { 1395 description 1396 "Container to hold the local key definition."; 1397 uses ct:symmetric-key-grouping; 1398 } 1399 } 1400 case keystore { 1401 if-feature "central-keystore-supported"; 1402 if-feature "symmetric-keys"; 1403 leaf keystore-reference { 1404 type ks:symmetric-key-ref; 1405 description 1406 "A reference to an symmetric key that exists in 1407 the keystore, when this module is implemented."; 1408 } 1409 } 1410 } 1411 } 1412 grouping local-or-keystore-asymmetric-key-grouping { 1413 description 1414 "A grouping that expands to allow the asymmetric key to be 1415 either stored locally, i.e., within the using data model, 1416 or a reference to an asymmetric key stored in the keystore. 1418 Servers that do not 'implement' this module, and hence 1419 'central-keystore-supported' is not defined, SHOULD 1420 augment in custom 'case' statements enabling references 1421 to the alternate keystore locations."; 1422 choice local-or-keystore { 1423 nacm:default-deny-write; 1424 mandatory true; 1425 description 1426 "A choice between an inlined definition and a definition 1427 that exists in the keystore."; 1428 case local { 1429 if-feature "local-definitions-supported"; 1430 if-feature "asymmetric-keys"; 1431 container local-definition { 1432 description 1433 "Container to hold the local key definition."; 1434 uses ct:asymmetric-key-pair-grouping; 1435 } 1436 } 1437 case keystore { 1438 if-feature "central-keystore-supported"; 1439 if-feature "asymmetric-keys"; 1440 leaf keystore-reference { 1441 type ks:asymmetric-key-ref; 1442 description 1443 "A reference to an asymmetric key that exists in 1444 the keystore, when this module is implemented. The 1445 intent is to reference just the asymmetric key 1446 without any regard for any certificates that may 1447 be associated with it."; 1448 } 1449 } 1450 } 1451 } 1453 grouping local-or-keystore-asymmetric-key-with-certs-grouping { 1454 description 1455 "A grouping that expands to allow an asymmetric key and 1456 its associated certificates to be either stored locally, 1457 i.e., within the using data model, or a reference to an 1458 asymmetric key (and its associated certificates) stored 1459 in the keystore. 1461 Servers that do not 'implement' this module, and hence 1462 'central-keystore-supported' is not defined, SHOULD 1463 augment in custom 'case' statements enabling references 1464 to the alternate keystore locations."; 1465 choice local-or-keystore { 1466 nacm:default-deny-write; 1467 mandatory true; 1468 description 1469 "A choice between an inlined definition and a definition 1470 that exists in the keystore."; 1471 case local { 1472 if-feature "local-definitions-supported"; 1473 if-feature "asymmetric-keys"; 1474 container local-definition { 1475 description 1476 "Container to hold the local key definition."; 1477 uses ct:asymmetric-key-pair-with-certs-grouping; 1478 } 1479 } 1480 case keystore { 1481 if-feature "central-keystore-supported"; 1482 if-feature "asymmetric-keys"; 1483 leaf keystore-reference { 1484 type ks:asymmetric-key-ref; 1485 description 1486 "A reference to an asymmetric-key (and all of its 1487 associated certificates) in the keystore, when 1488 this module is implemented."; 1489 } 1490 } 1491 } 1492 } 1494 grouping local-or-keystore-end-entity-cert-with-key-grouping { 1495 description 1496 "A grouping that expands to allow an end-entity certificate 1497 (and its associated asymmetric key pair) to be either stored 1498 locally, i.e., within the using data model, or a reference 1499 to a specific certificate in the keystore. 1501 Servers that do not 'implement' this module, and hence 1502 'central-keystore-supported' is not defined, SHOULD 1503 augment in custom 'case' statements enabling references 1504 to the alternate keystore locations."; 1505 choice local-or-keystore { 1506 nacm:default-deny-write; 1507 mandatory true; 1508 description 1509 "A choice between an inlined definition and a definition 1510 that exists in the keystore."; 1511 case local { 1512 if-feature "local-definitions-supported"; 1513 if-feature "asymmetric-keys"; 1514 container local-definition { 1515 description 1516 "Container to hold the local key definition."; 1517 uses ct:asymmetric-key-pair-with-cert-grouping; 1518 } 1519 } 1520 case keystore { 1521 if-feature "central-keystore-supported"; 1522 if-feature "asymmetric-keys"; 1523 container keystore-reference { 1524 uses asymmetric-key-certificate-ref-grouping; 1525 description 1526 "A reference to a specific certificate associated with 1527 an asymmetric key stored in the keystore, when this 1528 module is implemented."; 1529 } 1530 } 1531 } 1532 } 1534 grouping keystore-grouping { 1535 description 1536 "Grouping definition enables use in other contexts. If ever 1537 done, implementations MUST augment new 'case' statements 1538 into the various local-or-keystore 'choice' statements to 1539 supply leafrefs to the model-specific location(s)."; 1540 container asymmetric-keys { 1541 nacm:default-deny-write; 1542 if-feature "asymmetric-keys"; 1543 description 1544 "A list of asymmetric keys."; 1545 list asymmetric-key { 1546 key "name"; 1547 description 1548 "An asymmetric key."; 1549 leaf name { 1550 type string; 1551 description 1552 "An arbitrary name for the asymmetric key."; 1553 } 1554 uses ct:asymmetric-key-pair-with-certs-grouping; 1555 } 1556 } 1557 container symmetric-keys { 1558 nacm:default-deny-write; 1559 if-feature "symmetric-keys"; 1560 description 1561 "A list of symmetric keys."; 1562 list symmetric-key { 1563 key "name"; 1564 description 1565 "A symmetric key."; 1566 leaf name { 1567 type string; 1568 description 1569 "An arbitrary name for the symmetric key."; 1570 } 1571 uses ct:symmetric-key-grouping; 1572 } 1573 } 1574 } 1576 /*********************************/ 1577 /* Protocol accessible nodes */ 1578 /*********************************/ 1580 container keystore { 1581 description 1582 "A central keystore containing a list of symmetric keys and 1583 a list of asymmetric keys."; 1584 nacm:default-deny-write; 1585 uses keystore-grouping { 1586 augment "symmetric-keys/symmetric-key/key-type/encrypted-key/" 1587 + "encrypted-key/encrypted-by" { 1588 description 1589 "Augments in a choice statement enabling the encrypting 1590 key to be any other symmetric or asymmetric key in the 1591 central keystore."; 1592 uses encrypted-by-choice-grouping; 1593 } 1594 augment "asymmetric-keys/asymmetric-key/private-key-type/" 1595 + "encrypted-private-key/encrypted-private-key/" 1596 + "encrypted-by" { 1597 description 1598 "Augments in a choice statement enabling the encrypting 1599 key to be any other symmetric or asymmetric key in the 1600 central keystore."; 1601 uses encrypted-by-choice-grouping; 1602 } 1603 } 1604 } 1606 } 1608 1610 3. Support for Built-in Keys 1612 In some implementations, a server may support built-in keys. Built- 1613 in keys MAY be set during the manufacturing process or be dynamically 1614 generated the first time the server is booted or a particular service 1615 (e.g., SSH) is enabled. 1617 The primary characteristic of the built-in keys is that they are 1618 provided by the system, as opposed to configuration. As such, they 1619 are present in (and 1620 [I-D.ma-netmod-with-system], if used). The example below illustrates 1621 what the keystore in might look like for a server in 1622 its factory default state. 1624 1628 1629 1630 Manufacturer-Generated Hidden Key 1631 1632 ct:subject-public-key-info-format 1633 1634 BASE64VALUE= 1635 1636 1637 1638 Manufacturer-Generated IDevID Cert 1639 BASE64VALUE= 1640 1641 1642 1643 1644 1646 In order for the built-in keys (and their associated built-in 1647 certificates) to be referenced by configuration, the referenced keys 1648 and associated certificates MUST first be copied into . 1650 Built-in keys that are "hidden" MUST be copied into using 1651 the same key values, so that the server can bind them to the built-in 1652 entries. 1654 Built-in keys that are "encrypted" MAY be copied into other parts of 1655 the configuration so long as they are otherwise unmodified (e.g., the 1656 "encrypted-by" reference cannot be altered). 1658 Built-in keys that are "cleartext" MAY be copied into other parts of 1659 the configuration but, by doing so, they lose their association to 1660 the built-in entries and any assurances afforded by knowing they are/ 1661 were built-in. 1663 The built-in keys and built-in associated certificates are immutable 1664 by configuration operations. With exception to additional/custom 1665 certificates associated to a built-in key, servers MUST ignore 1666 attempts to modify any aspect of built-in keys and/or built-in 1667 associated certificates. 1669 The following example illustrates how a single built-in key 1670 definition from the previous example has been propagated to 1671 : 1673 1675 1676 1677 Manufacturer-Generated Hidden Key 1678 1679 ct:subject-public-key-info-format 1680 1681 BASE64VALUE= 1682 1683 1684 1685 Manufacturer-Generated IDevID Cert 1686 BASE64VALUE= 1687 1688 1689 Deployment-Specific LDevID Cert 1690 BASE64VALUE= 1691 1692 1693 1694 1695 1697 After the above configuration is applied, should appear 1698 as follows: 1700 1704 1705 1706 Manufacturer-Generated Hidden Key 1707 1708 ct:subject-public-key-info-format 1709 1710 BASE64VALUE= 1711 1712 1713 1714 Manufacturer-Generated IDevID Cert 1715 BASE64VALUE= 1716 1717 1718 Deployment-Specific LDevID Cert 1719 BASE64VALUE= 1720 1721 1722 1723 1724 1726 4. Encrypting Keys in Configuration 1728 This section describes an approach that enables both the symmetric 1729 and asymmetric keys on a server to be encrypted, such that 1730 traditional backup/restore procedures can be used without concern for 1731 the keys being compromised when in transit. 1733 4.1. Key Encryption Key 1735 The ability to encrypt configured keys is predicated on the existence 1736 of a "key encryption key" (KEK). There may be any number of KEKs in 1737 a system. A KEK, by its namesake, is a key that is used to encrypt 1738 other keys. A KEK MAY be either a symmetric key or an asymmetric 1739 key. 1741 If a KEK is a symmetric key, then the server MUST provide an API for 1742 administrators to encrypt other keys without needing to know the 1743 symmetric key's value. If the KEK is an asymmetric key, then the 1744 server MAY provide an API enabling the encryption of other keys or, 1745 alternatively, let the administrators do so themselves using the 1746 asymmetric key's public half. 1748 A server MUST possess (or be able to possess, in case the KEK has 1749 been encrypted by another KEK) a KEK's cleartext value so that it can 1750 decrypt the other keys in the configuration at runtime. 1752 4.2. Configuring Encrypted Keys 1754 Each time a new key is configured, it SHOULD be encrypted by a KEK. 1756 In "ietf-crypto-types" [I-D.ietf-netconf-crypto-types], the format 1757 for encrypted values is described by identity statements derived from 1758 the "symmetrically-encrypted-value-format" and "symmetrically- 1759 encrypted-value-format" identity statements. 1761 Implementations SHOULD provide an API that simultaneously generates 1762 and encrypts a key (symmetric or asymmetric) using a KEK. Thusly 1763 newly generated key cleartext values may never known to the 1764 administrators generating the keys. 1766 In case the server implementation does not provide such an API, then 1767 the generating and encrypting steps MAY be performed outside the 1768 server, e.g., by an administrator with special access control rights 1769 (e.g., an organization's crypto officer). 1771 In either case, the encrypted key can be configured into the keystore 1772 using either the "encrypted-key" (for symmetric keys) or the 1773 "encrypted-private-key" (for asymmetric keys) nodes. These two nodes 1774 contain both the encrypted value as well as a reference to the KEK 1775 that encrypted the key. 1777 4.3. Migrating Configuration to Another Server 1779 When a KEK is used to encrypt other keys, migrating the configuration 1780 to another server is only possible if the second server has the same 1781 KEK. How the second server comes to have the same KEK is discussed 1782 in this section. 1784 In some deployments, mechanisms outside the scope of this document 1785 may be used to migrate a KEK from one server to another. That said, 1786 beware that the ability to do so typically entails having access to 1787 the first server but, in many scenarios, the first server may no 1788 longer be operational. 1790 In other deployments, an organization's crypto officer, possessing a 1791 KEK's cleartext value, configures the same KEK on the second server, 1792 presumably as a hidden key or a key protected by access-control 1793 (e.g., NACM's "default-deny-all"), so that the cleartext value is not 1794 disclosed to regular administrators. However, this approach creates 1795 high-coupling to and dependency on the crypto officers that does not 1796 scale in production environments. 1798 In order to decouple the crypto officers from the regular 1799 administrators, a special KEK, called the "master key" (MK), may be 1800 used. 1802 A MK is commonly a globally-unique built-in (see Section 3) 1803 asymmetric key. The private key, due to its long lifetime, is hidden 1804 (i.e., "hidden-private-key" in Section 2.1.4.5. of 1805 [I-D.ietf-netconf-crypto-types]). The public key is often contained 1806 in an identity certificate (e.g., IDevID). How to configure a MK 1807 during the manufacturing process is outside the scope of this 1808 document. 1810 It is RECOMMENDED that MKs are built-in and hidden but, if this is 1811 not possible, access control mechanisms like NACM SHOULD be used to 1812 limit access to the MK's secret data only to the most trusted 1813 authorized clients (e.g., an organization's crypto officer). In this 1814 case, it is RECOMMENDED that the MK is not built-in and hence is, 1815 effectively, just like a KEK. 1817 Assuming the server has a MK, the MK can be used to encrypt a "shared 1818 KEK", which is then used to encrypt the keys configured by regular 1819 administrators. 1821 With this extra level of indirection, it is possible for a crypto 1822 officer to encrypt the same KEK for a multiplicity of servers offline 1823 using the public key contained in their identity certificates. The 1824 crypto officer can then safely handoff the encrypted KEKs to the 1825 regular administrators responsible for server installations, 1826 including migrations. 1828 In order to migrate the configuration from a first server, an 1829 administrator would need to make just a single modification to the 1830 configuration before loading it onto a second server, which is to 1831 replace the encrypted KEK keystore entry from the first server with 1832 the encrypted KEK for the second server. Upon doing this, the 1833 configuration (containing many encrypted keys) can be loaded into the 1834 second server while enabling the second server to decrypt all the 1835 encrypted keys in the configuration. 1837 The following diagram illustrates this idea: 1839 +-------------+ +-------------+ 1840 | shared KEK | | shared KEK | 1841 |(unencrypted)|-------------------------------> | (encrypted) | 1842 +-------------+ encrypts offline using +-------------+ 1843 ^ each server's MK | 1844 | | 1845 | | 1846 | possesses \o | 1847 +-------------- |\ | 1848 / \ shares with | 1849 crypto +--------------------+ 1850 officer | 1851 | 1852 | 1853 +----------------------+ | +----------------------+ 1854 | server-1 | | | server-2 | 1855 | configuration | | | configuration | 1856 | | | | | 1857 | | | | | 1858 | +----------------+ | | | +----------------+ | 1859 | | MK-1 | | | | | MK-2 | | 1860 | | (hidden) | | | | | (hidden) | | 1861 | +----------------+ | | | +----------------+ | 1862 | ^ | | | ^ | 1863 | | | | | | | 1864 | | | | | | | 1865 | | encrypted | | | | encrypted | 1866 | | by | | | | by | 1867 | | | | | | | 1868 | | | | | | | 1869 | +----------------+ | | | +----------------+ | 1870 | | shared KEK | | | | | shared KEK | | 1871 | | (encrypted) | | v | | (encrypted) | | 1872 | +----------------+ | | +----------------+ | 1873 | ^ | regular | ^ | 1874 | | | admin | | | 1875 | | | | | | 1876 | | encrypted | \o | | encrypted | 1877 | | by | |\ | | by | 1878 | | | / \ | | | 1879 | | | | | | 1880 | +----------------+ |----------------->| +----------------+ | 1881 | | all other keys | | migrate | | all other keys | | 1882 | | (encrypted) | | configuration | | (encrypted) | | 1883 | +----------------+ | | +----------------+ | 1884 | | | | 1885 +----------------------+ +----------------------+ 1887 5. Security Considerations 1889 5.1. Security of Data at Rest 1891 The YANG module defined in this document defines a mechanism called a 1892 "keystore" that, by its name, suggests that it will protect its 1893 contents from unauthorized disclosure and modification. 1895 Security controls for the API (i.e., data in motion) are discussed in 1896 Section 5.3, but controls for the data at rest cannot be specified by 1897 the YANG module. 1899 In order to satisfy the expectations of a "keystore", it is 1900 RECOMMENDED that implementations ensure that the keystore contents 1901 are encrypted when persisted to non-volatile memory. 1903 5.2. Unconstrained Private Key Usage 1905 This module enables the configuration of private keys without 1906 constraints on their usage, e.g., what operations the key is allowed 1907 to be used for (e.g., signature, decryption, both). 1909 This module also does not constrain the usage of the associated 1910 public keys, other than in the context of a configured certificate 1911 (e.g., an identity certificate), in which case the key usage is 1912 constrained by the certificate. 1914 5.3. The "ietf-keystore" YANG Module 1916 The YANG module defined in this document is designed to be accessed 1917 via YANG based management protocols, such as NETCONF [RFC6241] and 1918 RESTCONF [RFC8040]. Both of these protocols have mandatory-to- 1919 implement secure transport layers (e.g., SSH, TLS) with mutual 1920 authentication. 1922 The NETCONF access control model (NACM) [RFC8341] provides the means 1923 to restrict access for particular users to a pre-configured subset of 1924 all available protocol operations and content. 1926 None of the readable data nodes defined in this YANG module are 1927 considered sensitive or vulnerable in network environments. The NACM 1928 "default-deny-all" extension has not been set for any data nodes 1929 defined in this module. 1931 | Please be aware that this module uses the "cleartext-key" and 1932 | "cleartext-private-key" nodes from the "ietf-crypto-types" 1933 | module [I-D.ietf-netconf-crypto-types], where said nodes have 1934 | the NACM extension "default-deny-all" set, thus preventing 1935 | uncontrolled read-access to the cleartext key values. 1937 All the writable data nodes defined by this module, both in the 1938 "grouping" statements as well as the protocol-accessible "keystore" 1939 instance, may be considered sensitive or vulnerable in some network 1940 environments.. For instance, any modification to a key or reference 1941 to a key may dramatically alter the implemented security policy. For 1942 this reason, the NACM extension "default-deny-write" has been set for 1943 all data nodes defined in this module. 1945 This module does not define any "rpc" or "action" statements, and 1946 thus the security considerations for such is not provided here. 1948 6. IANA Considerations 1950 6.1. The "IETF XML" Registry 1952 This document registers one URI in the "ns" subregistry of the IETF 1953 XML Registry [RFC3688]. Following the format in [RFC3688], the 1954 following registration is requested: 1956 URI: urn:ietf:params:xml:ns:yang:ietf-keystore 1957 Registrant Contact: The IESG 1958 XML: N/A, the requested URI is an XML namespace. 1960 6.2. The "YANG Module Names" Registry 1962 This document registers one YANG module in the YANG Module Names 1963 registry [RFC6020]. Following the format in [RFC6020], the following 1964 registration is requested: 1966 name: ietf-keystore 1967 namespace: urn:ietf:params:xml:ns:yang:ietf-keystore 1968 prefix: ks 1969 reference: RFC CCCC 1971 7. References 1973 7.1. Normative References 1975 [I-D.ietf-netconf-crypto-types] 1976 Watsen, K., "YANG Data Types and Groupings for 1977 Cryptography", Work in Progress, Internet-Draft, draft- 1978 ietf-netconf-crypto-types-21, 14 September 2021, 1979 . 1982 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1983 Requirement Levels", BCP 14, RFC 2119, 1984 DOI 10.17487/RFC2119, March 1997, 1985 . 1987 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1988 the Network Configuration Protocol (NETCONF)", RFC 6020, 1989 DOI 10.17487/RFC6020, October 2010, 1990 . 1992 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1993 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1994 . 1996 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 1997 Access Control Model", STD 91, RFC 8341, 1998 DOI 10.17487/RFC8341, March 2018, 1999 . 2001 7.2. Informative References 2003 [I-D.ietf-netconf-http-client-server] 2004 Watsen, K., "YANG Groupings for HTTP Clients and HTTP 2005 Servers", Work in Progress, Internet-Draft, draft-ietf- 2006 netconf-http-client-server-08, 14 December 2021, 2007 . 2010 [I-D.ietf-netconf-keystore] 2011 Watsen, K., "A YANG Data Model for a Keystore", Work in 2012 Progress, Internet-Draft, draft-ietf-netconf-keystore-23, 2013 14 December 2021, . 2016 [I-D.ietf-netconf-netconf-client-server] 2017 Watsen, K., "NETCONF Client and Server Models", Work in 2018 Progress, Internet-Draft, draft-ietf-netconf-netconf- 2019 client-server-24, 14 December 2021, 2020 . 2023 [I-D.ietf-netconf-restconf-client-server] 2024 Watsen, K., "RESTCONF Client and Server Models", Work in 2025 Progress, Internet-Draft, draft-ietf-netconf-restconf- 2026 client-server-24, 14 December 2021, 2027 . 2030 [I-D.ietf-netconf-ssh-client-server] 2031 Watsen, K., "YANG Groupings for SSH Clients and SSH 2032 Servers", Work in Progress, Internet-Draft, draft-ietf- 2033 netconf-ssh-client-server-26, 14 December 2021, 2034 . 2037 [I-D.ietf-netconf-tcp-client-server] 2038 Watsen, K. and M. Scharf, "YANG Groupings for TCP Clients 2039 and TCP Servers", Work in Progress, Internet-Draft, draft- 2040 ietf-netconf-tcp-client-server-11, 14 December 2021, 2041 . 2044 [I-D.ietf-netconf-tls-client-server] 2045 Watsen, K., "YANG Groupings for TLS Clients and TLS 2046 Servers", Work in Progress, Internet-Draft, draft-ietf- 2047 netconf-tls-client-server-26, 14 December 2021, 2048 . 2051 [I-D.ietf-netconf-trust-anchors] 2052 Watsen, K., "A YANG Data Model for a Truststore", Work in 2053 Progress, Internet-Draft, draft-ietf-netconf-trust- 2054 anchors-16, 14 December 2021, 2055 . 2058 [I-D.ma-netmod-with-system] 2059 Ma, Q., Watsen, K., Wu, Q., Chong, F., and J. Lindblad, 2060 "System-defined Configuration", Work in Progress, 2061 Internet-Draft, draft-ma-netmod-with-system-02, 14 2062 February 2022, . 2065 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2066 DOI 10.17487/RFC3688, January 2004, 2067 . 2069 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2070 and A. Bierman, Ed., "Network Configuration Protocol 2071 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2072 . 2074 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2075 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2076 . 2078 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2079 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2080 May 2017, . 2082 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 2083 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 2084 . 2086 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 2087 and R. Wilton, "Network Management Datastore Architecture 2088 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 2089 . 2091 [Std-802.1AR-2018] 2092 IEEE SA-Standards Board, "IEEE Standard for Local and 2093 metropolitan area networks - Secure Device Identity", 2094 August 2018, 2095 . 2097 Appendix A. Change Log 2099 This section is to be removed before publishing as an RFC. 2101 A.1. 00 to 01 2103 * Replaced the 'certificate-chain' structures with PKCS#7 2104 structures. (Issue #1) 2106 * Added 'private-key' as a configurable data node, and removed the 2107 'generate-private-key' and 'load-private-key' actions. (Issue #2) 2109 * Moved 'user-auth-credentials' to the ietf-ssh-client module. 2110 (Issues #4 and #5) 2112 A.2. 01 to 02 2114 * Added back 'generate-private-key' action. 2116 * Removed 'RESTRICTED' enum from the 'private-key' leaf type. 2118 * Fixed up a few description statements. 2120 A.3. 02 to 03 2122 * Changed draft's title. 2124 * Added missing references. 2126 * Collapsed sections and levels. 2128 * Added RFC 8174 to Requirements Language Section. 2130 * Renamed 'trusted-certificates' to 'pinned-certificates'. 2132 * Changed 'public-key' from config false to config true. 2134 * Switched 'host-key' from OneAsymmetricKey to definition from RFC 2135 4253. 2137 A.4. 03 to 04 2139 * Added typedefs around leafrefs to common keystore paths 2141 * Now tree diagrams reference ietf-netmod-yang-tree-diagrams 2143 * Removed Design Considerations section 2145 * Moved key and certificate definitions from data tree to groupings 2147 A.5. 04 to 05 2149 * Removed trust anchors (now in their own draft) 2151 * Added back global keystore structure 2153 * Added groupings enabling keys to either be locally defined or a 2154 reference to the keystore. 2156 A.6. 05 to 06 2158 * Added feature "local-keys-supported" 2160 * Added nacm:default-deny-all and nacm:default-deny-write 2162 * Renamed generate-asymmetric-key to generate-hidden-key 2164 * Added an install-hidden-key action 2165 * Moved actions inside fo the "asymmetric-key" container 2167 * Moved some groupings to draft-ietf-netconf-crypto-types 2169 A.7. 06 to 07 2171 * Removed a "require-instance false" 2173 * Clarified some description statements 2175 * Improved the keystore-usage examples 2177 A.8. 07 to 08 2179 * Added "local-definition" containers to avoid posibility of the 2180 action/notification statements being under a "case" statement. 2182 * Updated copyright date, boilerplate template, affiliation, folding 2183 algorithm, and reformatted the YANG module. 2185 A.9. 08 to 09 2187 * Added a 'description' statement to the 'must' in the /keystore/ 2188 asymmetric-key node explaining that the descendant values may 2189 exist in only, and that implementation MUST assert 2190 that the values are either configured or that they exist in 2191 . 2193 * Copied above 'must' statement (and description) into the local-or- 2194 keystore-asymmetric-key-grouping, local-or-keystore-asymmetric- 2195 key-with-certs-grouping, and local-or-keystore-end-entity-cert- 2196 with-key-grouping statements. 2198 A.10. 09 to 10 2200 * Updated draft title to match new truststore draft title 2202 * Moved everything under a top-level 'grouping' to enable use in 2203 other contexts. 2205 * Renamed feature from 'local-keys-supported' to 'local-definitions- 2206 supported' (same name used in truststore) 2208 * Removed the either-all-or-none 'must' expressions for the key's 2209 3-tuple values (since the values are now 'mandatory true' in 2210 crypto-types) 2212 * Example updated to reflect 'mandatory true' change in crypto-types 2213 draft 2215 A.11. 10 to 11 2217 * Replaced typedef asymmetric-key-certificate-ref with grouping 2218 asymmetric-key-certificate-ref-grouping. 2220 * Added feature feature 'key-generation'. 2222 * Cloned groupings symmetric-key-grouping, asymmetric-key-pair- 2223 grouping, asymmetric-key-pair-with-cert-grouping, and asymmetric- 2224 key-pair-with-certs-grouping from crypto-keys, augmenting into 2225 each new case statements for values that have been encrypted by 2226 other keys in the keystore. Refactored keystore model to use 2227 these groupings. 2229 * Added new 'symmetric-keys' lists, as a sibling to the existing 2230 'asymmetric-keys' list. 2232 * Added RPCs (not actions) 'generate-symmetric-key' and 'generate- 2233 asymmetric-key' to *return* a (potentially encrypted) key. 2235 A.12. 11 to 12 2237 * Updated to reflect crypto-type's draft using enumerations over 2238 identities. 2240 * Added examples for the 'generate-symmetric-key' and 'generate- 2241 asymmetric-key' RPCs. 2243 * Updated the Introduction section. 2245 A.13. 12 to 13 2247 * Updated examples to incorporate new "key-format" identities. 2249 * Made the two "generate-*-key" RPCs be "action" statements instead. 2251 A.14. 13 to 14 2253 * Updated YANG module and examples to incorporate the new 2254 iana-*-algorithm modules in the crypto-types draft.. 2256 A.15. 14 to 15 2258 * Added new "Support for Built-in Keys" section. 2260 * Added 'must' expressions asserting that the 'key-format' leaf 2261 whenever an encrypted key is specified. 2263 * Added local-or-keystore-symmetric-key-grouping for PSK support. 2265 A.16. 15 to 16 2267 * Moved the generate key actions to ietf-crypt-types as RPCs, which 2268 are augmented by ietf-keystore to support encrypted keys. 2269 Examples updated accordingly. 2271 * Added a SSH certificate-based key (RFC 6187) and a raw private key 2272 to the example instance document (partly so they could be 2273 referenced by examples in the SSH and TLS client/server drafts. 2275 A.17. 16 to 17 2277 * Removed augments to the "generate-symmetric-key" and "generate- 2278 asymmetric-key" groupings. 2280 * Removed "generate-symmetric-key" and "generate-asymmetric-key" 2281 examples. 2283 * Removed the "algorithm" nodes from remaining examples. 2285 * Updated the "Support for Built-in Keys" section. 2287 * Added new section "Encrypting Keys in Configuration". 2289 * Added a "Note to Reviewers" note to first page. 2291 A.18. 17 to 18 2293 * Removed dangling/unnecessary ref to RFC 8342. 2295 * r/MUST/SHOULD/ wrt strength of keys being configured over 2296 transports. 2298 * Added an example for the "certificate-expiration" notification. 2300 * Clarified that OS MAY have a multiplicity of underlying keystores 2301 and/or HSMs. 2303 * Clarified expected behavior for "built-in" keys in 2305 * Clarified the "Migrating Configuration to Another Server" section. 2307 * Expanded "Data Model Overview section(s) [remove "wall" of tree 2308 diagrams]. 2310 * Updated the Security Considerations section. 2312 A.19. 18 to 19 2314 * Updated examples to reflect new "cleartext-" prefix in the crypto- 2315 types draft. 2317 A.20. 19 to 20 2319 * Addressed SecDir comments from Magnus Nystroem and Sandra Murphy. 2321 A.21. 20 to 21 2323 * Added a "Unconstrained Private Key Usage" Security Consideration 2324 to address concern raised by SecDir. 2326 * (Editorial) Removed the output of "grouping" statements in the 2327 tree diagrams for the "ietf-keystore" and "ex-keystore-usage" 2328 modules. 2330 * Addressed comments raised by YANG Doctor. 2332 A.22. 21 to 22 2334 * Added prefixes to 'path' statements per trust-anchors/issues/1 2336 * Renamed feature "keystore-supported" to "central-keystore- 2337 supported". 2339 * Associated with above, generally moved text to refer to a 2340 "central" keystore. 2342 * Aligned modules with `pyang -f` formatting. 2344 * Fixed nits found by YANG Doctor reviews. 2346 A.23. 22 to 23 2348 * Updated 802.1AR ref to latest version 2350 * Replaced "base64encodedvalue==" with "BASE64VALUE=" in examples. 2352 * Minor editorial nits 2354 A.24. 23 to 24 2356 * Added features "asymmetric-keys" and "symmetric-keys" 2358 * fixup the 'WG Web' and 'WG List' lines in YANG module(s) 2360 * fixup copyright (i.e., s/Simplified/Revised/) in YANG module(s) 2362 * Added Informative reference to ma-netmod-with-system 2364 Acknowledgements 2366 The authors would like to thank for following for lively discussions 2367 on list and in the halls (ordered by first name): Alan Luchuk, Andy 2368 Bierman, Benoit Claise, Bert Wijnen, Balazs Kovacs, David Lamparter, 2369 Eric Voit, Ladislav Lhotka, Liang Xia, Juergen Schoenwaelder, Mahesh 2370 Jethanandani, Magnus Nystroem, Martin Bjoerklund, Mehmet Ersue, Phil 2371 Shafer, Radek Krejci, Ramkumar Dhanapal, Reshad Rahman, Sandra 2372 Murphy, Sean Turner, and Tom Petch. 2374 Author's Address 2376 Kent Watsen 2377 Watsen Networks 2378 Email: kent+ietf@watsen.net