idnits 2.17.1 draft-ietf-netconf-keystore-21.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 559 has weird spacing: '...-format ide...' == Line 567 has weird spacing: '...on-date yan...' == Line 571 has weird spacing: '...sr-info ct:...' == Line 573 has weird spacing: '...request ct:...' == Line 593 has weird spacing: '...-format ide...' == (10 more instances...) -- The document date (10 February 2021) is 1172 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-18 == Outdated reference: A later version (-20) exists of draft-ietf-netconf-http-client-server-05 == Outdated reference: A later version (-35) exists of draft-ietf-netconf-keystore-20 == Outdated reference: A later version (-36) exists of draft-ietf-netconf-netconf-client-server-21 == Outdated reference: A later version (-36) exists of draft-ietf-netconf-restconf-client-server-21 == Outdated reference: A later version (-40) exists of draft-ietf-netconf-ssh-client-server-22 == Outdated reference: A later version (-26) exists of draft-ietf-netconf-tcp-client-server-08 == Outdated reference: A later version (-41) exists of draft-ietf-netconf-tls-client-server-22 == Outdated reference: A later version (-28) exists of draft-ietf-netconf-trust-anchors-13 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 10 February 2021 5 Expires: 14 August 2021 7 A YANG Data Model for a Keystore 8 draft-ietf-netconf-keystore-21 10 Abstract 12 This document defines a YANG module called "ietf-keystore" that 13 enables centralized configuration of both symmetric and asymmetric 14 keys. The secret value for both key types may be encrypted or 15 hidden. Asymmetric keys may be associated with certificates. 16 Notifications are sent when certificates are about to expire. 18 Editorial Note (To be removed by RFC Editor) 20 This draft contains placeholder values that need to be replaced with 21 finalized values at the time of publication. This note summarizes 22 all of the substitutions that are needed. No other RFC Editor 23 instructions are specified elsewhere in this document. 25 Artwork in this document contains shorthand references to drafts in 26 progress. Please apply the following replacements: 28 * "AAAA" --> the assigned RFC value for draft-ietf-netconf-crypto- 29 types 31 * "CCCC" --> the assigned RFC value for this draft 33 Artwork in this document contains placeholder values for the date of 34 publication of this draft. Please apply the following replacement: 36 * "2021-02-10" --> 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 14 August 2021. 59 Copyright Notice 61 Copyright (c) 2021 IETF Trust and the persons identified as the 62 document authors. All rights reserved. 64 This document is subject to BCP 78 and the IETF Trust's Legal 65 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 66 license-info) in effect on the date of publication of this document. 67 Please review these documents carefully, as they describe your rights 68 and restrictions with respect to this document. Code Components 69 extracted from this document must include 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 . . . . . . . . . . . . . . . . . 6 78 1.3. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 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 . . . . . . . . . . . . . . . . . . . . . . 14 83 2.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 26 84 3. Support for Built-in Keys . . . . . . . . . . . . . . . . . . 34 85 4. Encrypting Keys in Configuration . . . . . . . . . . . . . . 37 86 5. Security Considerations . . . . . . . . . . . . . . . . . . . 41 87 5.1. Security of Data at Rest . . . . . . . . . . . . . . . . 41 88 5.2. Unconstrained Private Key Usage . . . . . . . . . . . . . 41 89 5.3. The "ietf-keystore" YANG Module . . . . . . . . . . . . . 41 90 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 42 91 6.1. The "IETF XML" Registry . . . . . . . . . . . . . . . . . 42 92 6.2. The "YANG Module Names" Registry . . . . . . . . . . . . 42 93 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 42 94 7.1. Normative References . . . . . . . . . . . . . . . . . . 42 95 7.2. Informative References . . . . . . . . . . . . . . . . . 43 96 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 45 97 A.1. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 45 98 A.2. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 45 99 A.3. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 45 100 A.4. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 46 101 A.5. 04 to 05 . . . . . . . . . . . . . . . . . . . . . . . . 46 102 A.6. 05 to 06 . . . . . . . . . . . . . . . . . . . . . . . . 46 103 A.7. 06 to 07 . . . . . . . . . . . . . . . . . . . . . . . . 46 104 A.8. 07 to 08 . . . . . . . . . . . . . . . . . . . . . . . . 47 105 A.9. 08 to 09 . . . . . . . . . . . . . . . . . . . . . . . . 47 106 A.10. 09 to 10 . . . . . . . . . . . . . . . . . . . . . . . . 47 107 A.11. 10 to 11 . . . . . . . . . . . . . . . . . . . . . . . . 47 108 A.12. 11 to 12 . . . . . . . . . . . . . . . . . . . . . . . . 48 109 A.13. 12 to 13 . . . . . . . . . . . . . . . . . . . . . . . . 48 110 A.14. 13 to 14 . . . . . . . . . . . . . . . . . . . . . . . . 48 111 A.15. 14 to 15 . . . . . . . . . . . . . . . . . . . . . . . . 48 112 A.16. 15 to 16 . . . . . . . . . . . . . . . . . . . . . . . . 48 113 A.17. 16 to 17 . . . . . . . . . . . . . . . . . . . . . . . . 49 114 A.18. 17 to 18 . . . . . . . . . . . . . . . . . . . . . . . . 49 115 A.19. 18 to 19 . . . . . . . . . . . . . . . . . . . . . . . . 49 116 A.20. 19 to 20 . . . . . . . . . . . . . . . . . . . . . . . . 49 117 A.21. 20 to 21 . . . . . . . . . . . . . . . . . . . . . . . . 50 118 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 50 119 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 50 121 1. Introduction 123 This document defines a YANG 1.1 [RFC7950] module called "ietf- 124 keystore" that enables centralized configuration of both symmetric 125 and asymmetric keys. The secret value for both key types may be 126 encrypted or hidden (see [I-D.ietf-netconf-crypto-types]. Asymmetric 127 keys may be associated with certificates. Notifications are sent 128 when certificates are about to expire. 130 The "ietf-keystore" module defines many "grouping" statements 131 intended for use by other modules that may import it. For instance, 132 there are groupings that define enabling a key to be either 133 configured locally (within the defining data model) or be a reference 134 to a key in the keystore. 136 Special consideration has been given for systems that have 137 cryptographic hardware, such as a Trusted Platform Module (TPM). 138 These systems are unique in that the cryptographic hardware hides the 139 secret key values. Additionally, such hardware is commonly 140 initiailized when manufactured to protect a "built-in" asymmetric key 141 for which the public half is conveyed in an identity certificate 142 (e.g., an IDevID [Std-802.1AR-2009] certificate). Please see 143 Section 3 to see how built-in keys are supported. 145 This document intends to support existing practices; it does not 146 intend to define new behvior for systems to implement. To simplify 147 implementation, advanced key formats may be selectively implemented. 149 Implementations may utilize zero or more operating system level 150 keystore utilities and/or hardware security modules (HSMs). 152 1.1. Relation to other RFCs 154 This document presents one or more YANG modules [RFC7950] that are 155 part of a collection of RFCs that work together to, ultimately, 156 enable the configuration of the clients and servers of both the 157 NETCONF [RFC6241] and RESTCONF [RFC8040] protocols. 159 The modules have been defined in a modular fashion to enable their 160 use by other efforts, some of which are known to be in progress at 161 the time of this writing, with many more expected to be defined in 162 time. 164 The normative dependency relationship between the various RFCs in the 165 collection is presented in the below diagram. The labels in the 166 diagram represent the primary purpose provided by each RFC. 167 Hyperlinks to each RFC are provided below the diagram. 169 crypto-types 170 ^ ^ 171 / \ 172 / \ 173 truststore keystore 174 ^ ^ ^ ^ 175 | +---------+ | | 176 | | | | 177 | +------------+ | 178 tcp-client-server | / | | 179 ^ ^ ssh-client-server | | 180 | | ^ tls-client-server 181 | | | ^ ^ http-client-server 182 | | | | | ^ 183 | | | +-----+ +---------+ | 184 | | | | | | 185 | +-----------|--------|--------------+ | | 186 | | | | | | 187 +-----------+ | | | | | 188 | | | | | | 189 | | | | | | 190 netconf-client-server restconf-client-server 192 +=======================+===========================================+ 193 |Label in Diagram | Originating RFC | 194 +=======================+===========================================+ 195 |crypto-types | [I-D.ietf-netconf-crypto-types] | 196 +-----------------------+-------------------------------------------+ 197 |truststore | [I-D.ietf-netconf-trust-anchors] | 198 +-----------------------+-------------------------------------------+ 199 |keystore | [I-D.ietf-netconf-keystore] | 200 +-----------------------+-------------------------------------------+ 201 |tcp-client-server | [I-D.ietf-netconf-tcp-client-server] | 202 +-----------------------+-------------------------------------------+ 203 |ssh-client-server | [I-D.ietf-netconf-ssh-client-server] | 204 +-----------------------+-------------------------------------------+ 205 |tls-client-server | [I-D.ietf-netconf-tls-client-server] | 206 +-----------------------+-------------------------------------------+ 207 |http-client-server | [I-D.ietf-netconf-http-client-server] | 208 +-----------------------+-------------------------------------------+ 209 |netconf-client-server | [I-D.ietf-netconf-netconf-client-server] | 210 +-----------------------+-------------------------------------------+ 211 |restconf-client-server | [I-D.ietf-netconf-restconf-client-server] | 212 +-----------------------+-------------------------------------------+ 214 Table 1: Label to RFC Mapping 216 1.2. Specification Language 218 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 219 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 220 "OPTIONAL" in this document are to be interpreted as described in BCP 221 14 [RFC2119] [RFC8174] when, and only when, they appear in all 222 capitals, as shown here. 224 1.3. Terminology 226 The terms "client" and "server" are defined in [RFC6241] and are not 227 redefined here. 229 The term "keystore" is defined in this draft as a mechanism that 230 intends safeguard secrets placed into it for protection. 232 The nomenclature "" and "" are defined in 233 [RFC8342]. 235 The sentence fragments "augmented" and "augmented in" are used herein 236 as the past tense verbified form of the "augment" statement defined 237 in Section 7.17 of [RFC7950]. 239 1.4. Adherence to the NMDA 241 This document is compliant with Network Management Datastore 242 Architecture (NMDA) [RFC8342]. For instance, keys and associated 243 certificates installed during manufacturing (e.g., for an IDevID 244 certificate) are expected to appear in (see Section 3). 246 2. The "ietf-keystore" Module 248 This section defines a YANG 1.1 [RFC7950] module called "ietf- 249 keystore". A high-level overview of the module is provided in 250 Section 2.1. Examples illustatrating the module's use are provided 251 in Section 2.2. The YANG module itself is defined in 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, when the keystore module is implemented. 292 * These typedefs are provided as an aid to downstream modules that 293 import the "ietf-keystore" module. 295 2.1.3. Groupings 297 The "ietf-keystore" module defines the following "grouping" 298 statements: 300 * encrypted-by-choice-grouping 301 * asymmetric-key-certificate-ref-grouping 302 * local-or-keystore-symmetric-key-grouping 303 * local-or-keystore-asymmetric-key-grouping 304 * local-or-keystore-asymmetric-key-with-certs-grouping 305 * local-or-keystore-end-entity-cert-with-key-grouping 306 * keystore-grouping 308 Each of these groupings are presented in the following subsections. 310 2.1.3.1. The "encrypted-by-choice-grouping" Grouping 312 The following tree diagram [RFC8340] illustrates the "encrypted-by- 313 choice-grouping" grouping: 315 | The grouping's name is intended to be parsed "(encrypted- 316 | by)-(choice)-(grouping)", not as "(encrypted)-(by- 317 | choice)-(grouping)". 319 grouping encrypted-by-choice-grouping 320 +-- (encrypted-by-choice) 321 +--:(symmetric-key-ref) 322 | +-- symmetric-key-ref? ks:symmetric-key-ref 323 +--:(asymmetric-key-ref) 324 +-- asymmetric-key-ref? ks:asymmetric-key-ref 326 Comments: 328 * This grouping defines a "choice" statement with options to 329 reference either a symmetric or an asymmetric key configured in 330 the keystore. 332 * This grouping is usable only when the keystore module is 333 implemented. Servers defining custom keystore locations MUST 334 augment in alternate "encrypted-by" references to the alternate 335 locations. 337 2.1.3.2. The "asymmetric-key-certificate-ref-grouping" Grouping 339 The following tree diagram [RFC8340] illustrates the "asymmetric-key- 340 certificate-ref-grouping" grouping: 342 grouping asymmetric-key-certificate-ref-grouping 343 +-- asymmetric-key? ks:asymmetric-key-ref 344 +-- certificate? leafref 346 Comments: 348 * This grouping defines a reference to a certificate in two parts: 349 the first being the name of the asymmetric key the certificate is 350 associated with, and the second being the name of the certificate 351 itself. 353 * This grouping is usable only when the keystore module is 354 implemented. Servers defining custom keystore locations MAY 355 define an alternate grouping for references to the alternate 356 locations. 358 2.1.3.3. The "local-or-keystore-symmetric-key-grouping" Grouping 360 The following tree diagram [RFC8340] illustrates the "local-or- 361 keystore-symmetric-key-grouping" grouping: 363 grouping local-or-keystore-symmetric-key-grouping 364 +-- (local-or-keystore) 365 +--:(local) {local-definitions-supported}? 366 | +-- local-definition 367 | +---u ct:symmetric-key-grouping 368 +--:(keystore) {keystore-supported}? 369 +-- keystore-reference? ks:symmetric-key-ref 371 Comments: 373 * The "local-or-keystore-symmetric-key-grouping" grouping is 374 provided soley as convenience to downstream modules that wish to 375 offer an option for whether a symmetric key is defined locally or 376 as a reference to a symmetric key in the keystore. 378 * A "choice" statement is used to expose the various options. Each 379 option is enabled by a "feature" statement. Additional "case" 380 statements MAY be augmented in if, e.g., there is a need to 381 reference a symmetric key in an alternate location. 383 * For the "local-definition" option, the defintion uses the 384 "symmetric-key-grouping" grouping discussed in Section 2.1.4.3 of 385 [I-D.ietf-netconf-crypto-types]. 387 * For the "keystore" option, the "keystore-reference" is an instance 388 of the "symmetric-key-ref" discussed in Section 2.1.2. 390 2.1.3.4. The "local-or-keystore-asymmetric-key-grouping" Grouping 392 The following tree diagram [RFC8340] illustrates the "local-or- 393 keystore-asymmetric-key-grouping" grouping: 395 grouping local-or-keystore-asymmetric-key-grouping 396 +-- (local-or-keystore) 397 +--:(local) {local-definitions-supported}? 398 | +-- local-definition 399 | +---u ct:asymmetric-key-pair-grouping 400 +--:(keystore) {keystore-supported}? 401 +-- keystore-reference? ks:asymmetric-key-ref 403 Comments: 405 * The "local-or-keystore-asymmetric-key-grouping" grouping is 406 provided soley as convenience to downstream modules that wish to 407 offer an option for whether an asymmetric key is defined locally 408 or as a reference to an asymmetric key in the keystore. 410 * A "choice" statement is used to expose the various options. Each 411 option is enabled by a "feature" statement. Additional "case" 412 statements MAY be augmented in if, e.g., there is a need to 413 reference an asymmetric key in an alternate location. 415 * For the "local-definition" option, the defintion uses the 416 "asymmetric-key-pair-grouping" grouping discussed in 417 Section 2.1.4.5 of [I-D.ietf-netconf-crypto-types]. 419 * For the "keystore" option, the "keystore-reference" is an instance 420 of the "asymmetric-key-ref" typedef discussed in Section 2.1.2. 422 2.1.3.5. The "local-or-keystore-asymmetric-key-with-certs-grouping" 423 Grouping 425 The following tree diagram [RFC8340] illustrates the "local-or- 426 keystore-asymmetric-key-with-certs-grouping" grouping: 428 grouping local-or-keystore-asymmetric-key-with-certs-grouping 429 +-- (local-or-keystore) 430 +--:(local) {local-definitions-supported}? 431 | +-- local-definition 432 | +---u ct:asymmetric-key-pair-with-certs-grouping 433 +--:(keystore) {keystore-supported}? 434 +-- keystore-reference? ks:asymmetric-key-ref 436 Comments: 438 * The "local-or-keystore-asymmetric-key-with-certs-grouping" 439 grouping is provided soley as convenience to downstream modules 440 that wish to offer an option for whether an asymmetric key is 441 defined locally or as a reference to an asymmetric key in the 442 keystore. 444 * A "choice" statement is used to expose the various options. Each 445 option is enabled by a "feature" statement. Additional "case" 446 statements MAY be augmented in if, e.g., there is a need to 447 reference an asymmetric key in an alternate location. 449 * For the "local-definition" option, the defintion uses the 450 "asymmetric-key-pair-with-certs-grouping" grouping discussed in 451 Section 2.1.4.11 of [I-D.ietf-netconf-crypto-types]. 453 * For the "keystore" option, the "keystore-reference" is an instance 454 of the "asymmetric-key-ref" typedef discussed in Section 2.1.2. 456 2.1.3.6. The "local-or-keystore-end-entity-cert-with-key-grouping" 457 Grouping 459 The following tree diagram [RFC8340] illustrates the "local-or- 460 keystore-end-entity-cert-with-key-grouping" grouping: 462 grouping local-or-keystore-end-entity-cert-with-key-grouping 463 +-- (local-or-keystore) 464 +--:(local) {local-definitions-supported}? 465 | +-- local-definition 466 | +---u ct:asymmetric-key-pair-with-cert-grouping 467 +--:(keystore) {keystore-supported}? 468 +-- keystore-reference 469 +---u asymmetric-key-certificate-ref-grouping 471 Comments: 473 * The "local-or-keystore-end-entity-cert-with-key-grouping" grouping 474 is provided soley as convenience to downstream modules that wish 475 to offer an option for whether a symmetric key is defined locally 476 or as a reference to a symmetric key in the keystore. 478 * A "choice" statement is used to expose the various options. Each 479 option is enabled by a "feature" statement. Additional "case" 480 statements MAY be augmented in if, e.g., there is a need to 481 reference a symmetric key in an alternate location. 483 * For the "local-definition" option, the defintion uses the 484 "asymmetric-key-pair-with-certs-grouping" grouping discussed in 485 Section 2.1.4.11 of [I-D.ietf-netconf-crypto-types]. 487 * For the "keystore" option, the "keystore-reference" uses the 488 "asymmetric-key-certificate-ref-grouping" grouping discussed in 489 Section 2.1.3.2. 491 2.1.3.7. The "keystore-grouping" Grouping 493 The following tree diagram [RFC8340] illustrates the "keystore- 494 grouping" grouping: 496 grouping keystore-grouping 497 +-- asymmetric-keys 498 | +-- asymmetric-key* [name] 499 | +-- name? string 500 | +---u ct:asymmetric-key-pair-with-certs-grouping 501 +-- symmetric-keys 502 +-- symmetric-key* [name] 503 +-- name? string 504 +---u ct:symmetric-key-grouping 506 Comments: 508 * The "keystore-grouping" grouping defines a keystore instance as 509 being composed of symmetric and asymmetric keys. The stucture for 510 the symmetric and asymmetric keys is essentially the same, being a 511 "list" inside a "container". 513 * For asymmetric keys, each "asymmetric-key" uses the "asymmetric- 514 key-pair-with-certs-grouping" grouping discussed in 515 Section 2.1.4.11 of [I-D.ietf-netconf-crypto-types]. 517 * For symmetric keys, each "symmetric-key" uses the "symmetric-key- 518 grouping" grouping discussed in Section 2.1.4.3 of 519 [I-D.ietf-netconf-crypto-types]. 521 2.1.4. Protocol-accessible Nodes 523 The following tree diagram [RFC8340] lists all the protocol- 524 accessible nodes defined in the "ietf-keystore" module, without 525 expanding the "grouping" statements: 527 module: ietf-keystore 528 +--rw keystore 529 +---u keystore-grouping 531 The following tree diagram [RFC8340] lists all the protocol- 532 accessible nodes defined in the "ietf-keystore" module, with all 533 "grouping" statements expanded, enabling the keystore's full 534 structure to be seen: 536 module: ietf-keystore 537 +--rw keystore 538 +--rw asymmetric-keys 539 | +--rw asymmetric-key* [name] 540 | +--rw name string 541 | +--rw public-key-format identityref 542 | +--rw public-key binary 543 | +--rw private-key-format? identityref 544 | +--rw (private-key-type) 545 | | +--:(cleartext-private-key) 546 | | | +--rw cleartext-private-key? binary 547 | | +--:(hidden-private-key) 548 | | | +--rw hidden-private-key? empty 549 | | +--:(encrypted-private-key) {private-key-encryption}? 550 | | +--rw encrypted-private-key 551 | | +--rw encrypted-by 552 | | | +--rw (encrypted-by-choice) 553 | | | +--:(symmetric-key-ref) 554 | | | | +--rw symmetric-key-ref? 555 | | | | ks:symmetric-key-ref 556 | | | +--:(asymmetric-key-ref) 557 | | | +--rw asymmetric-key-ref? 558 | | | ks:asymmetric-key-ref 559 | | +--rw encrypted-value-format identityref 560 | | +--rw encrypted-value binary 561 | +--rw certificates 562 | | +--rw certificate* [name] 563 | | +--rw name string 564 | | +--rw cert-data end-entity-cert-cms 565 | | +---n certificate-expiration 566 | | {certificate-expiration-notification}? 567 | | +-- expiration-date yang:date-and-time 568 | +---x generate-certificate-signing-request 569 | {certificate-signing-request-generation}? 570 | +---w input 571 | | +---w csr-info ct:csr-info 572 | +--ro output 573 | +--ro certificate-signing-request ct:csr 574 +--rw symmetric-keys 575 +--rw symmetric-key* [name] 576 +--rw name string 577 +--rw key-format? identityref 578 +--rw (key-type) 579 +--:(cleartext-key) 580 | +--rw cleartext-key? binary 581 +--:(hidden-key) 582 | +--rw hidden-key? empty 583 +--:(encrypted-key) {symmetric-key-encryption}? 584 +--rw encrypted-key 585 +--rw encrypted-by 586 | +--rw (encrypted-by-choice) 587 | +--:(symmetric-key-ref) 588 | | +--rw symmetric-key-ref? 589 | | ks:symmetric-key-ref 590 | +--:(asymmetric-key-ref) 591 | +--rw asymmetric-key-ref? 592 | ks:asymmetric-key-ref 593 +--rw encrypted-value-format identityref 594 +--rw encrypted-value binary 596 Comments: 598 * Protocol-accessible nodes are those nodes that are accessible when 599 the module is "implemented", as described in Section 5.6.5 of 600 [RFC7950]. 602 * The protcol-accessible nodes for the "ietf-keystore" module are an 603 instance of the "keystore-grouping" grouping discussed in 604 Section 2.1.3.7. 606 * The reason for why "keystore-grouping" exists separate from the 607 protocol-accessible nodes definition is so as to enable instances 608 of the keystore to be instantiated in other locations, as may be 609 needed or desired by some modules. 611 2.2. Example Usage 613 The examples in this section are encoded using XML, such as might be 614 the case when using the NETCONF protocol. Other encodings MAY be 615 used, such as JSON when using the RESTCONF protocol. 617 2.2.1. A Keystore Instance 619 The following example illustrates keys in . Please see 620 Section 3 for an example illustrating built-in values in 621 . 623 =============== NOTE: '\' line wrapping per RFC 8792 ================ 625 628 629 630 cleartext-symmetric-key 631 ct:octet-string-key-format 632 base64encodedvalue== 633 634 635 hidden-symmetric-key 636 637 638 639 encrypted-symmetric-key 640 ct:one-symmetric-key-format 641 642 643 hidden-asymmetric-key 645 646 647 ct:cms-enveloped-data-format 648 649 base64encodedvalue== 650 651 652 654 655 656 ssh-rsa-key 657 658 ct:ssh-public-key-format 659 660 base64encodedvalue== 661 662 ct:rsa-private-key-format 663 664 base64encodedvalue== 666 667 668 ssh-rsa-key-with-cert 669 670 ct:subject-public-key-info-format 671 672 base64encodedvalue== 673 674 ct:rsa-private-key-format 675 676 base64encodedvalue== 678 679 680 ex-rsa-cert2 681 base64encodedvalue== 682 683 684 685 686 raw-private-key 687 688 ct:subject-public-key-info-format 689 690 base64encodedvalue== 691 692 ct:rsa-private-key-format 693 694 base64encodedvalue== 696 697 698 rsa-asymmetric-key 699 700 ct:subject-public-key-info-format 701 702 base64encodedvalue== 703 704 ct:rsa-private-key-format 705 706 base64encodedvalue== 708 709 710 ex-rsa-cert 711 base64encodedvalue== 712 713 714 715 716 ec-asymmetric-key 717 718 ct:subject-public-key-info-format 719 720 base64encodedvalue== 721 722 ct:ec-private-key-format 723 724 base64encodedvalue== 726 727 728 ex-ec-cert 729 base64encodedvalue== 730 731 732 733 734 hidden-asymmetric-key 735 736 ct:subject-public-key-info-format 737 738 base64encodedvalue== 739 740 741 742 builtin-idevid-cert 743 base64encodedvalue== 744 745 746 my-ldevid-cert 747 base64encodedvalue== 748 749 750 751 752 encrypted-asymmetric-key 753 754 ct:subject-public-key-info-format 755 756 base64encodedvalue== 757 758 ct:one-asymmetric-key-format 759 760 761 762 encrypted-symmetric-key 764 765 766 ct:cms-encrypted-data-format 767 768 base64encodedvalue== 769 770 771 772 774 2.2.2. A Certificate Expiration Notification 776 The following example illustrates a "certificate-expiration" 777 notification for a certificate associated with a key configured in 778 the keystore. 780 =============== NOTE: '\' line wrapping per RFC 8792 ================ 782 784 2018-05-25T00:01:00Z 785 786 787 788 hidden-asymmetric-key 789 790 791 my-ldevid-cert 792 793 2018-08-05T14:18:53-05:00 795 796 797 798 799 800 801 803 2.2.3. The "Local or Keystore" Groupings 805 This section illustrates the various "local-or-keystore" groupings 806 defined in the "ietf-keystore" module, specifically the "local-or- 807 keystore-symmetric-key-grouping" (Section 2.1.3.3), "local-or- 808 keystore-asymmetric-key-grouping" (Section 2.1.3.4), "local-or- 809 keystore-asymmetric-key-with-certs-grouping" (Section 2.1.3.5), and 810 "local-or-keystore-end-entity-cert-with-key-grouping" 811 (Section 2.1.3.6) groupings. 813 These examples assume the existence of an example module called "ex- 814 keystore-usage" having the namespace "http://example.com/ns/example- 815 keystore-usage". 817 The ex-keystore-usage module is first presented using tree diagrams 818 [RFC8340], followed by an instance example illustrating all the 819 "local-or-keystore" groupings in use, followed by the YANG module 820 itself. 822 The following tree diagram illustrates "ex-keystore-usage" without 823 expanding the "grouping" statements: 825 module: ex-keystore-usage 826 +--rw keystore-usage 827 +--rw symmetric-key* [name] 828 | +--rw name string 829 | +---u ks:local-or-keystore-symmetric-key-grouping 830 +--rw asymmetric-key* [name] 831 | +--rw name string 832 | +---u ks:local-or-keystore-asymmetric-key-grouping 833 +--rw asymmetric-key-with-certs* [name] 834 | +--rw name 835 | | string 836 | +---u ks:local-or-keystore-asymmetric-key-with-certs-grouping 837 +--rw end-entity-cert-with-key* [name] 838 +--rw name 839 | string 840 +---u ks:local-or-keystore-end-entity-cert-with-key-grouping 842 The following tree diagram illustrates the "ex-keystore-usage" 843 module, with all "grouping" statements expanded, enabling the usage's 844 full structure to be seen: 846 module: ex-keystore-usage 847 +--rw keystore-usage 848 +--rw symmetric-key* [name] 849 | +--rw name string 850 | +--rw (local-or-keystore) 851 | +--:(local) {local-definitions-supported}? 852 | | +--rw local-definition 853 | | +--rw key-format? identityref 854 | | +--rw (key-type) 855 | | +--:(cleartext-key) 856 | | | +--rw cleartext-key? binary 857 | | +--:(hidden-key) 858 | | | +--rw hidden-key? empty 859 | | +--:(encrypted-key) {symmetric-key-encryption}? 860 | | +--rw encrypted-key 861 | | +--rw encrypted-by 862 | | +--rw encrypted-value-format identityref 863 | | +--rw encrypted-value binary 864 | +--:(keystore) {keystore-supported}? 865 | +--rw keystore-reference? ks:symmetric-key-ref 866 +--rw asymmetric-key* [name] 867 | +--rw name string 868 | +--rw (local-or-keystore) 869 | +--:(local) {local-definitions-supported}? 870 | | +--rw local-definition 871 | | +--rw public-key-format identityref 872 | | +--rw public-key binary 873 | | +--rw private-key-format? identityref 874 | | +--rw (private-key-type) 875 | | +--:(cleartext-private-key) 876 | | | +--rw cleartext-private-key? binary 877 | | +--:(hidden-private-key) 878 | | | +--rw hidden-private-key? empty 879 | | +--:(encrypted-private-key) 880 | | {private-key-encryption}? 881 | | +--rw encrypted-private-key 882 | | +--rw encrypted-by 883 | | +--rw encrypted-value-format identityref 884 | | +--rw encrypted-value binary 885 | +--:(keystore) {keystore-supported}? 886 | +--rw keystore-reference? ks:asymmetric-key-ref 887 +--rw asymmetric-key-with-certs* [name] 888 | +--rw name string 889 | +--rw (local-or-keystore) 890 | +--:(local) {local-definitions-supported}? 891 | | +--rw local-definition 892 | | +--rw public-key-format 893 | | | identityref 894 | | +--rw public-key binary 895 | | +--rw private-key-format? 896 | | | identityref 897 | | +--rw (private-key-type) 898 | | | +--:(cleartext-private-key) 899 | | | | +--rw cleartext-private-key? binary 900 | | | +--:(hidden-private-key) 901 | | | | +--rw hidden-private-key? empty 902 | | | +--:(encrypted-private-key) 903 | | | {private-key-encryption}? 904 | | | +--rw encrypted-private-key 905 | | | +--rw encrypted-by 906 | | | +--rw encrypted-value-format identityref 907 | | | +--rw encrypted-value binary 908 | | +--rw certificates 909 | | | +--rw certificate* [name] 910 | | | +--rw name string 911 | | | +--rw cert-data 912 | | | | end-entity-cert-cms 913 | | | +---n certificate-expiration 914 | | | {certificate-expiration-notification}? 915 | | | +-- expiration-date yang:date-and-time 916 | | +---x generate-certificate-signing-request 917 | | {certificate-signing-request-generation}? 918 | | +---w input 919 | | | +---w csr-info ct:csr-info 920 | | +--ro output 921 | | +--ro certificate-signing-request ct:csr 922 | +--:(keystore) {keystore-supported}? 923 | +--rw keystore-reference? ks:asymmetric-key-ref 924 +--rw end-entity-cert-with-key* [name] 925 +--rw name string 926 +--rw (local-or-keystore) 927 +--:(local) {local-definitions-supported}? 928 | +--rw local-definition 929 | +--rw public-key-format 930 | | identityref 931 | +--rw public-key binary 932 | +--rw private-key-format? 933 | | identityref 934 | +--rw (private-key-type) 935 | | +--:(cleartext-private-key) 936 | | | +--rw cleartext-private-key? binary 937 | | +--:(hidden-private-key) 938 | | | +--rw hidden-private-key? empty 939 | | +--:(encrypted-private-key) 940 | | {private-key-encryption}? 941 | | +--rw encrypted-private-key 942 | | +--rw encrypted-by 943 | | +--rw encrypted-value-format identityref 944 | | +--rw encrypted-value binary 945 | +--rw cert-data? 946 | | end-entity-cert-cms 947 | +---n certificate-expiration 948 | | {certificate-expiration-notification}? 949 | | +-- expiration-date yang:date-and-time 950 | +---x generate-certificate-signing-request 951 | {certificate-signing-request-generation}? 952 | +---w input 953 | | +---w csr-info ct:csr-info 954 | +--ro output 955 | +--ro certificate-signing-request ct:csr 956 +--:(keystore) {keystore-supported}? 957 +--rw keystore-reference 958 +--rw asymmetric-key? ks:asymmetric-key-ref 959 +--rw certificate? leafref 961 The following example provides two equivalent instances of each 962 grouping, the first being a reference to a keystore and the second 963 being locally-defined. The instance having a reference to a keystore 964 is consistent with the keystore defined in Section 2.2.1. The two 965 instances are equivalent, as the locally-defined instance example 966 contains the same values defined by the keystore instance referenced 967 by its sibling example. 969 =============== NOTE: '\' line wrapping per RFC 8792 ================ 971 975 976 978 979 example 1a 980 cleartext-symmetric-key 981 983 984 example 1b 985 986 ct:octet-string-key-format 987 base64encodedvalue== 988 989 991 992 994 995 example 2a 996 rsa-asymmetric-key 997 999 1000 example 2b 1001 1002 1003 ct:subject-public-key-info-format 1004 1005 base64encodedvalue== 1006 1007 ct:rsa-private-key-format 1008 1009 base64encodedvalue== 1011 1012 1014 1015 1017 1018 example 3a 1019 rsa-asymmetric-key 1020 1022 1023 example 3b 1024 1025 1026 ct:subject-public-key-info-format 1027 1028 base64encodedvalue== 1029 1030 ct:rsa-private-key-format 1031 1032 base64encodedvalue== 1034 1035 1036 a locally-defined cert 1037 base64encodedvalue== 1038 1039 1040 1041 1043 1044 1046 1047 example 4a 1048 1049 rsa-asymmetric-key 1050 ex-rsa-cert 1051 1052 1054 1055 example 4b 1056 1057 1058 ct:subject-public-key-info-format 1059 1060 base64encodedvalue== 1061 1062 ct:rsa-private-key-format 1063 1064 base64encodedvalue== 1066 base64encodedvalue== 1067 1068 1070 1072 Following is the "ex-keystore-usage" module's YANG definition: 1074 module ex-keystore-usage { 1075 yang-version 1.1; 1077 namespace "http://example.com/ns/example-keystore-usage"; 1078 prefix "eku"; 1080 import ietf-keystore { 1081 prefix ks; 1082 reference 1083 "RFC CCCC: A YANG Data Model for a Keystore"; 1084 } 1086 organization 1087 "Example Corporation"; 1089 contact 1090 "Author: YANG Designer "; 1092 description 1093 "This module illustrates notable groupings defined in 1094 the 'ietf-keystore' module."; 1096 revision "2021-02-10" { 1097 description 1098 "Initial version"; 1099 reference 1100 "RFC CCCC: A YANG Data Model for a Keystore"; 1101 } 1103 container keystore-usage { 1104 description 1105 "An illustration of the various keystore groupings."; 1107 list symmetric-key { 1108 key name; 1109 leaf name { 1110 type string; 1111 description 1112 "An arbitrary name for this key."; 1113 } 1114 uses ks:local-or-keystore-symmetric-key-grouping; 1115 description 1116 "An symmetric key that may be configured locally or be a 1117 reference to a symmetric key in the keystore."; 1118 } 1120 list asymmetric-key { 1121 key name; 1122 leaf name { 1123 type string; 1124 description 1125 "An arbitrary name for this key."; 1126 } 1127 uses ks:local-or-keystore-asymmetric-key-grouping; 1128 description 1129 "An asymmetric key, with no certs, that may be configured 1130 locally or be a reference to an asymmetric key in the 1131 keystore. The intent is to reference just the asymmetric 1132 key, not any certificates that may also be associated 1133 with the asymmetric key."; 1134 } 1136 list asymmetric-key-with-certs { 1137 key name; 1138 leaf name { 1139 type string; 1140 description 1141 "An arbitrary name for this key."; 1142 } 1143 uses ks:local-or-keystore-asymmetric-key-with-certs-grouping; 1144 description 1145 "An asymmetric key and its associated certs, that may be 1146 configured locally or be a reference to an asymmetric key 1147 (and its associated certs) in the keystore."; 1148 } 1150 list end-entity-cert-with-key { 1151 key name; 1152 leaf name { 1153 type string; 1154 description 1155 "An arbitrary name for this key."; 1156 } 1157 uses ks:local-or-keystore-end-entity-cert-with-key-grouping; 1158 description 1159 "An end-entity certificate and its associated asymmetric 1160 key, that may be configured locally or be a reference 1161 to another certificate (and its associated asymmetric 1162 key) in the keystore."; 1163 } 1164 } 1166 } 1168 2.3. YANG Module 1170 This YANG module has normative references to [RFC8341] and 1171 [I-D.ietf-netconf-crypto-types]. 1173 file "ietf-keystore@2021-02-10.yang" 1175 module ietf-keystore { 1176 yang-version 1.1; 1177 namespace "urn:ietf:params:xml:ns:yang:ietf-keystore"; 1178 prefix ks; 1180 import ietf-netconf-acm { 1181 prefix nacm; 1182 reference 1183 "RFC 8341: Network Configuration Access Control Model"; 1184 } 1186 import ietf-crypto-types { 1187 prefix ct; 1188 reference 1189 "RFC AAAA: YANG Data Types and Groupings for Cryptography"; 1190 } 1192 organization 1193 "IETF NETCONF (Network Configuration) Working Group"; 1195 contact 1196 "WG Web: 1197 WG List: 1198 Author: Kent Watsen "; 1200 description 1201 "This module defines a 'keystore' to centralize management 1202 of security credentials. 1204 Copyright (c) 2020 IETF Trust and the persons identified 1205 as authors of the code. All rights reserved. 1207 Redistribution and use in source and binary forms, with 1208 or without modification, is permitted pursuant to, and 1209 subject to the license terms contained in, the Simplified 1210 BSD License set forth in Section 4.c of the IETF Trust's 1211 Legal Provisions Relating to IETF Documents 1212 (https://trustee.ietf.org/license-info). 1214 This version of this YANG module is part of RFC CCCC 1215 (https://www.rfc-editor.org/info/rfcCCCC); see the RFC 1216 itself for full legal notices. 1218 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1219 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 1220 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 1221 are to be interpreted as described in BCP 14 (RFC 2119) 1222 (RFC 8174) when, and only when, they appear in all 1223 capitals, as shown here."; 1225 revision 2021-02-10 { 1226 description 1227 "Initial version"; 1228 reference 1229 "RFC CCCC: A YANG Data Model for a Keystore"; 1230 } 1232 /****************/ 1233 /* Features */ 1234 /****************/ 1236 feature keystore-supported { 1237 description 1238 "The 'keystore-supported' feature indicates that the server 1239 supports the keystore."; 1240 } 1242 feature local-definitions-supported { 1243 description 1244 "The 'local-definitions-supported' feature indicates that the 1245 server supports locally-defined keys."; 1246 } 1248 /****************/ 1249 /* Typedefs */ 1250 /****************/ 1252 typedef symmetric-key-ref { 1253 type leafref { 1254 path "/ks:keystore/ks:symmetric-keys/ks:symmetric-key" 1255 + "/ks:name"; 1256 } 1257 description 1258 "This typedef enables modules to easily define a reference 1259 to a symmetric key stored in the keystore, when this 1260 module is implemented."; 1261 } 1263 typedef asymmetric-key-ref { 1264 type leafref { 1265 path "/ks:keystore/ks:asymmetric-keys/ks:asymmetric-key" 1266 + "/ks:name"; 1267 } 1268 description 1269 "This typedef enables modules to easily define a reference 1270 to an asymmetric key stored in the keystore, when this 1271 module is implemented."; 1272 } 1274 /*****************/ 1275 /* Groupings */ 1276 /*****************/ 1278 grouping encrypted-by-choice-grouping { 1279 description 1280 "A grouping that defines a 'choice' statement that can be 1281 augmented into the 'encrypted-by' node, present in the 1282 'symmetric-key-grouping' and 'asymmetric-key-pair-grouping' 1283 groupings defined in RFC AAAA, enabling references to keys 1284 in the keystore, when this module is implemented."; 1285 choice encrypted-by-choice { 1286 nacm:default-deny-write; 1287 mandatory true; 1288 description 1289 "A choice amongst other symmetric or asymmetric keys."; 1290 case symmetric-key-ref { 1291 leaf symmetric-key-ref { 1292 type ks:symmetric-key-ref; 1293 description 1294 "Identifies the symmetric key used to encrypt the 1295 associated key."; 1296 } 1297 } 1298 case asymmetric-key-ref { 1299 leaf asymmetric-key-ref { 1300 type ks:asymmetric-key-ref; 1301 description 1302 "Identifies the asymmetric key whose public key 1303 encrypted the associated key."; 1304 } 1305 } 1306 } 1307 } 1309 grouping asymmetric-key-certificate-ref-grouping { 1310 description 1311 "This grouping defines a reference to a specific certificate 1312 associated with an asymmetric key stored in the keystore, 1313 when this module is implemented."; 1314 leaf asymmetric-key { 1315 nacm:default-deny-write; 1316 type ks:asymmetric-key-ref; 1317 must '../certificate'; 1318 description 1319 "A reference to an asymmetric key in the keystore."; 1320 } 1321 leaf certificate { 1322 nacm:default-deny-write; 1323 type leafref { 1324 path "/ks:keystore/ks:asymmetric-keys/ks:asymmetric-key[ks:" 1325 + "name = current()/../asymmetric-key]/ks:certificates" 1326 + "/ks:certificate/ks:name"; 1327 } 1328 must '../asymmetric-key'; 1329 description 1330 "A reference to a specific certificate of the 1331 asymmetric key in the keystore."; 1332 } 1333 } 1335 // local-or-keystore-* groupings 1337 grouping local-or-keystore-symmetric-key-grouping { 1338 description 1339 "A grouping that expands to allow the symmetric key to be 1340 either stored locally, i.e., within the using data model, 1341 or a reference to a symmetric key stored in the keystore. 1343 Servers that do not 'implement' this module, and hence 1344 'keystore-supported' is not defined, SHOULD augment in 1345 custom 'case' statements enabling references to the 1346 alternate keystore locations."; 1347 choice local-or-keystore { 1348 nacm:default-deny-write; 1349 mandatory true; 1350 description 1351 "A choice between an inlined definition and a definition 1352 that exists in the keystore."; 1353 case local { 1354 if-feature "local-definitions-supported"; 1355 container local-definition { 1356 description 1357 "Container to hold the local key definition."; 1358 uses ct:symmetric-key-grouping; 1359 } 1360 } 1361 case keystore { 1362 if-feature "keystore-supported"; 1363 leaf keystore-reference { 1364 type ks:symmetric-key-ref; 1365 description 1366 "A reference to an symmetric key that exists in 1367 the keystore, when this module is implmented."; 1368 } 1369 } 1370 } 1371 } 1373 grouping local-or-keystore-asymmetric-key-grouping { 1374 description 1375 "A grouping that expands to allow the asymmetric key to be 1376 either stored locally, i.e., within the using data model, 1377 or a reference to an asymmetric key stored in the keystore. 1379 Servers that do not 'implement' this module, and hence 1380 'keystore-supported' is not defined, SHOULD augment in 1381 custom 'case' statements enabling references to the 1382 alternate keystore locations."; 1383 choice local-or-keystore { 1384 nacm:default-deny-write; 1385 mandatory true; 1386 description 1387 "A choice between an inlined definition and a definition 1388 that exists in the keystore."; 1389 case local { 1390 if-feature "local-definitions-supported"; 1391 container local-definition { 1392 description 1393 "Container to hold the local key definition."; 1394 uses ct:asymmetric-key-pair-grouping; 1395 } 1396 } 1397 case keystore { 1398 if-feature "keystore-supported"; 1399 leaf keystore-reference { 1400 type ks:asymmetric-key-ref; 1401 description 1402 "A reference to an asymmetric key that exists in 1403 the keystore, when this module is implmented. The 1404 intent is to reference just the asymmetric key 1405 without any regard for any certificates that may 1406 be associated with it."; 1407 } 1408 } 1409 } 1410 } 1412 grouping local-or-keystore-asymmetric-key-with-certs-grouping { 1413 description 1414 "A grouping that expands to allow an asymmetric key and 1415 its associated certificates to be either stored locally, 1416 i.e., within the using data model, or a reference to an 1417 asymmetric key (and its associated certificates) stored 1418 in the keystore. 1420 Servers that do not 'implement' this module, and hence 1421 'keystore-supported' is not defined, SHOULD augment in 1422 custom 'case' statements enabling references to the 1423 alternate keystore locations."; 1424 choice local-or-keystore { 1425 nacm:default-deny-write; 1426 mandatory true; 1427 description 1428 "A choice between an inlined definition and a definition 1429 that exists in the keystore."; 1430 case local { 1431 if-feature "local-definitions-supported"; 1432 container local-definition { 1433 description 1434 "Container to hold the local key definition."; 1435 uses ct:asymmetric-key-pair-with-certs-grouping; 1436 } 1437 } 1438 case keystore { 1439 if-feature "keystore-supported"; 1440 leaf keystore-reference { 1441 type ks:asymmetric-key-ref; 1442 description 1443 "A reference to an asymmetric-key (and all of its 1444 associated certificates) in the keystore, when 1445 this module is implmented."; 1447 } 1448 } 1449 } 1450 } 1452 grouping local-or-keystore-end-entity-cert-with-key-grouping { 1453 description 1454 "A grouping that expands to allow an end-entity certificate 1455 (and its associated asymmetric key pair) to be either stored 1456 locally, i.e., within the using data model, or a reference 1457 to a specific certificate in the keystore. 1459 Servers that do not 'implement' this module, and hence 1460 'keystore-supported' is not defined, SHOULD augment in 1461 custom 'case' statements enabling references to the 1462 alternate keystore locations."; 1463 choice local-or-keystore { 1464 nacm:default-deny-write; 1465 mandatory true; 1466 description 1467 "A choice between an inlined definition and a definition 1468 that exists in the keystore."; 1469 case local { 1470 if-feature "local-definitions-supported"; 1471 container local-definition { 1472 description 1473 "Container to hold the local key definition."; 1474 uses ct:asymmetric-key-pair-with-cert-grouping; 1475 } 1476 } 1477 case keystore { 1478 if-feature "keystore-supported"; 1479 container keystore-reference { 1480 uses asymmetric-key-certificate-ref-grouping; 1481 description 1482 "A reference to a specific certificate associated with 1483 an asymmetric key stored in the keystore, when this 1484 module is implmented."; 1485 } 1486 } 1487 } 1488 } 1490 grouping keystore-grouping { 1491 description 1492 "Grouping definition enables use in other contexts. If ever 1493 done, implementations MUST augment new 'case' statements 1494 into the various local-or-keystore 'choice' statements to 1495 supply leafrefs to the model-specific location(s)."; 1496 container asymmetric-keys { 1497 nacm:default-deny-write; 1498 description 1499 "A list of asymmetric keys."; 1500 list asymmetric-key { 1501 key "name"; 1502 description 1503 "An asymmetric key."; 1504 leaf name { 1505 type string; 1506 description 1507 "An arbitrary name for the asymmetric key."; 1508 } 1509 uses ct:asymmetric-key-pair-with-certs-grouping; 1510 } 1511 } 1512 container symmetric-keys { 1513 nacm:default-deny-write; 1514 description 1515 "A list of symmetric keys."; 1516 list symmetric-key { 1517 key "name"; 1518 description 1519 "A symmetric key."; 1520 leaf name { 1521 type string; 1522 description 1523 "An arbitrary name for the symmetric key."; 1524 } 1525 uses ct:symmetric-key-grouping; 1526 } 1527 } 1528 } // grouping keystore-grouping 1530 /*********************************/ 1531 /* Protocol accessible nodes */ 1532 /*********************************/ 1534 container keystore { 1535 description 1536 "The keystore contains a list of symmetric keys and a list 1537 of asymmetric keys."; 1538 nacm:default-deny-write; 1539 uses keystore-grouping { 1540 augment "symmetric-keys/symmetric-key/key-type/encrypted-key/" 1541 + "encrypted-key/encrypted-by" { 1542 description 1543 "Augments in a choice statement enabling the encrypting 1544 key to be any other symmetric or asymmetric key in the 1545 keystore."; 1546 uses encrypted-by-choice-grouping; 1547 } 1548 augment "asymmetric-keys/asymmetric-key/private-key-type/" 1549 + "encrypted-private-key/encrypted-private-key/" 1550 + "encrypted-by" { 1551 description 1552 "Augments in a choice statement enabling the encrypting 1553 key to be any other symmetric or asymmetric key in the 1554 keystore."; 1555 uses encrypted-by-choice-grouping; 1556 } 1557 } 1558 } 1560 } 1562 1564 3. Support for Built-in Keys 1566 In some implementations, a server may support built-in keys. Built- 1567 in keys MAY be set during the manufacturing process or be dynamically 1568 generated the first time the server is booted or a particular service 1569 (e.g., SSH) is enabled. 1571 The primary characteristic of the built-in keys is that they are 1572 provided by the system, as opposed to configuration. As such, they 1573 are present in . The example below illustrates what the 1574 keystore in might look like for a server in its factory 1575 default state. 1577 1581 1582 1583 Manufacturer-Generated Hidden Key 1584 1585 ct:subject-public-key-info-format 1586 1587 base64encodedvalue== 1588 1589 1590 1591 Manufacturer-Generated IDevID Cert 1592 base64encodedvalue== 1593 1594 1595 1596 1597 1599 In order for the built-in keys (and their associated built-in 1600 certificates) to be referenced by configuration, the referenced keys 1601 and associated certificates MUST first be copied into . 1603 Built-in keys that are "hidden" MUST be copied into using 1604 the same key values, so that the server can bind them to the built-in 1605 entries. 1607 Built-in keys that are "encrypted" MAY be copied into other parts of 1608 the configuration so long as they are otherwise unmodified (e.g., the 1609 "encypted-by" reference cannot be altered). 1611 Built-in keys that are "cleartext" MAY be copied into other parts of 1612 the configuration but, by doing so, they lose their association to 1613 the built-in entries and any assurances afforded by knowing they are/ 1614 were built-in. 1616 The built-in keys and built-in associated certificates are immutable 1617 by configuration operations. With exception to additional/custom 1618 certificates associated to a built-in key, servers MUST ignore 1619 attempts to modify any aspect of built-in keys and/or built-in 1620 associated certificates. 1622 The following example illustrates how a single built-in key 1623 definition from the previous example has been propagated to 1624 : 1626 1628 1629 1630 Manufacturer-Generated Hidden Key 1631 1632 ct:subject-public-key-info-format 1633 1634 base64encodedvalue== 1635 1636 1637 1638 Manufacturer-Generated IDevID Cert 1639 base64encodedvalue== 1640 1641 1642 Deployment-Specific LDevID Cert 1643 base64encodedvalue== 1644 1645 1646 1647 1648 1650 After the above configuration is applied, should appear 1651 as follows: 1653 1657 1658 1659 Manufacturer-Generated Hidden Key 1660 1661 ct:subject-public-key-info-format 1662 1663 base64encodedvalue== 1664 1665 1666 1667 Manufacturer-Generated IDevID Cert 1668 base64encodedvalue== 1669 1670 1671 Deployment-Specific LDevID Cert 1672 base64encodedvalue== 1673 1674 1675 1676 1677 1679 4. Encrypting Keys in Configuration 1681 This section describes an approach that enables both the symmetric 1682 and asymmetric keys on a server to be encrypted, such that 1683 traditional backup/restore procedures can be used without concern for 1684 the keys being compromised when in transit. 1686 4.1. Key Encryption Key 1688 The ability to encrypt configured keys is predicated on the existence 1689 of a "key encryption key" (KEK). There may be any number of KEKs in 1690 a system. A KEK, by its namesake, is a key that is used to encrypt 1691 other keys. A KEK MAY be either a symmetric key or an asymmetric 1692 key. 1694 If a KEK is a symmetric key, then the server MUST provide an API for 1695 administrators to encrypt other keys without needing to know the 1696 symmetric key's value. If the KEK is an asymmetric key, then the 1697 server MAY provide an API enabling the encryption of other keys or, 1698 alternatively, let the administrators do so themselves using the 1699 asymmetric key's public half. 1701 A server MUST possess (or be able to possess, in case the KEK has 1702 been encrypted by another KEK) a KEK's cleartext value so that it can 1703 decrypt the other keys in the configurion at runtime. 1705 4.2. Configuring Encrypted Keys 1707 Each time a new key is configured, it SHOULD be encrypted by a KEK. 1709 In "ietf-crypto-types" [I-D.ietf-netconf-crypto-types], the format 1710 for encrytped values is described by identity statements derived from 1711 the "symmetrically-encrypted-value-format" and "symmetrically- 1712 encrypted-value-format" identity statements. 1714 Implementations SHOULD provide an API that simultaneously generates 1715 and encrypts a key (symmetric or asymmetric) using a KEK. Thusly 1716 newly generated key cleartext values may never known to the 1717 administrators generating the keys. 1719 In case the server implementation does not provide such an API, then 1720 the generating and encrypting steps MAY be performed outside the 1721 server, e.g., by an administrator with special access control rights 1722 (e.g., an organization's crypto officer). 1724 In either case, the encrypted key can be configured into the keystore 1725 using either the "encrypted-key" (for symmetric keys) or the 1726 "encrypted-private-key" (for asymmetric keys) nodes. These two nodes 1727 contain both the encrypted value as well as a reference to the KEK 1728 that encrypted the key. 1730 4.3. Migrating Configuration to Another Server 1732 When a KEK is used to encrypt other keys, migrating the configuration 1733 to another server is only possible if the second server has the same 1734 KEK. How the second server comes to have the same KEK is discussed 1735 in this section. 1737 In some deployments, mechanisms outside the scope of this document 1738 may be used to migrate a KEK from one server to another. That said, 1739 beware that the ability to do so typically entails having access to 1740 the first server but, in many scenarios, the first server may no 1741 longer be operational. 1743 In other deployments, an organization's crypto officer, possessing a 1744 KEK's cleartext value, configures the same KEK on the second server, 1745 presumably as a hidden key or a key protected by access-control 1746 (e.g., NACM's "default-deny-all"), so that the cleartext value is not 1747 disclosed to regular administrators. However, this approach creates 1748 high-coupling to and dependency on the crypto officers that doesn't 1749 scale in production environments. 1751 In order to decouple the crypto officers from the regular 1752 administrators, a special KEK, called the "master key" (MK), may be 1753 used. 1755 A MK is commonly a globally-unique built-in (see Section 3) 1756 asymmetric key. The private key, due to its long lifetime, is hidden 1757 (i.e., "hidden-private-key" in Section 2.1.4.5. of 1758 [I-D.ietf-netconf-crypto-types]). The public key is often contained 1759 in an identity certificate (e.g., IDevID). How to configure a MK 1760 during the manufacturing process is outside the scope of this 1761 document. 1763 It is highly RECOMMENDED that MKs are built-in and hidden but, if 1764 this is not possible, highly restricted access mechanisms SHOULD be 1765 used to limit access to the MK's secret data to only highly 1766 authorized clients (e.g., an organization's crypto officer). In this 1767 case, it is RECOMMENDED that the MK is not built-in and hence is, 1768 effectively, just like a KEK. 1770 Assuming the server has a MK, the MK can be used to encrypt a "shared 1771 KEK", which is then used to encrypt the keys configured by regular 1772 administrators. 1774 With this extra level of indirection, it is possible for a crypto 1775 officer to encrypt the same KEK for a multiplicity of servers offline 1776 using the public key contained in their identity certificates. The 1777 crypto officer can then safely handoff the encrypted KEKs to the 1778 regular administrators responsible for server installations, 1779 including migrations. 1781 In order to migrate the configuration from a first server, an 1782 administrator would need to make just a single modification to the 1783 configuration before loading it onto a second server, which is to 1784 replace the encrypted KEK keystore entry from the first server with 1785 the encrypted KEK for the second server. Upon doing this, the 1786 configuration (containing many encrypted keys) can be loaded into the 1787 second server while enabling the second server to decrypt all the 1788 encrypted keys in the configuration. 1790 The following diagram illustrates this idea: 1792 +-------------+ +-------------+ 1793 | shared KEK | | shared KEK | 1794 |(unencrypted)|-------------------------------> | (encrypted) | 1795 +-------------+ encrypts offline using +-------------+ 1796 ^ each server's MK | 1797 | | 1798 | | 1799 | possesses \o | 1800 +-------------- |\ | 1801 / \ shares with | 1802 crypto +--------------------+ 1803 officer | 1804 | 1805 | 1806 +----------------------+ | +----------------------+ 1807 | server-1 | | | server-2 | 1808 | configuration | | | configuration | 1809 | | | | | 1810 | | | | | 1811 | +----------------+ | | | +----------------+ | 1812 | | MK-1 | | | | | MK-2 | | 1813 | | (hidden) | | | | | (hidden) | | 1814 | +----------------+ | | | +----------------+ | 1815 | ^ | | | ^ | 1816 | | | | | | | 1817 | | | | | | | 1818 | | encrypted | | | | encrypted | 1819 | | by | | | | by | 1820 | | | | | | | 1821 | | | | | | | 1822 | +----------------+ | | | +----------------+ | 1823 | | shared KEK | | | | | shared KEK | | 1824 | | (encrypted) | | v | | (encrypted) | | 1825 | +----------------+ | | +----------------+ | 1826 | ^ | regular | ^ | 1827 | | | admin | | | 1828 | | | | | | 1829 | | encrypted | \o | | encrypted | 1830 | | by | |\ | | by | 1831 | | | / \ | | | 1832 | | | | | | 1833 | +----------------+ |----------------->| +----------------+ | 1834 | | all other keys | | migrate | | all other keys | | 1835 | | (encrypted) | | configuration | | (encrypted) | | 1836 | +----------------+ | | +----------------+ | 1837 | | | | 1838 +----------------------+ +----------------------+ 1840 5. Security Considerations 1842 5.1. Security of Data at Rest 1844 The YANG module defined in this document defines a mechanism called a 1845 "keystore" that, by its name, suggests that it will protect its 1846 contents from unauthorized disclosure and modification. 1848 Security controls for the API (i.e., data in motion) are discussed in 1849 Section 5.3, but controls for the data at rest cannot be specified by 1850 the YANG module. 1852 In order to satisfy the expectations of a "keystore", it is 1853 RECOMMENDED that implementations ensure that the keystore contents 1854 are encrypted when persisted to non-volatile memory. 1856 5.2. Unconstrained Private Key Usage 1858 This module enables the configuration of private keys without 1859 constraints on their usage, e.g., what operations the key is allowed 1860 to be used for (e.g., signature, decryption, both). 1862 This module also does not constrain the usage of the associated 1863 public keys, other than in the context of a configured certificate 1864 (e.g., an identity certificate), in which case the key usage is 1865 constrained by the certificate. 1867 5.3. The "ietf-keystore" YANG Module 1869 The YANG module defined in this document is designed to be accessed 1870 via YANG based management protocols, such as NETCONF [RFC6241] and 1871 RESTCONF [RFC8040]. Both of these protocols have mandatory-to- 1872 implement secure transport layers (e.g., SSH, TLS) with mutual 1873 authentication. 1875 The NETCONF access control model (NACM) [RFC8341] provides the means 1876 to restrict access for particular users to a pre-configured subset of 1877 all available protocol operations and content. 1879 None of the readable data nodes defined in this YANG module are 1880 considered sensitive or vulnerable in network environments. The NACM 1881 "default-deny-all" extension has not been set for any data nodes 1882 defined in this module. 1884 | Please be aware that this module uses the "cleartext-key" and 1885 | "cleartext-private-key" nodes from the "ietf-crypto-types" 1886 | module [I-D.ietf-netconf-crypto-types], where said nodes have 1887 | the NACM extension "default-deny-all" set, thus preventing 1888 | uncontrolled read-access to the cleartext key values. 1890 All of the writable data nodes defined by this module, both in the 1891 "grouping" statements as well as the protocol-accessible "keystore" 1892 instance, may be considered sensitive or vulnerable in some network 1893 environments.. For instance, any modification to a key or reference 1894 to a key may dramatically alter the implemented security policy. For 1895 this reason, the NACM extension "default-deny-write" has been set for 1896 all data nodes defined in this module. 1898 This module does not define any "rpc" or "action" statements, and 1899 thus the security considerations for such is not provided here. 1901 6. IANA Considerations 1903 6.1. The "IETF XML" Registry 1905 This document registers one URI in the "ns" subregistry of the IETF 1906 XML Registry [RFC3688]. Following the format in [RFC3688], the 1907 following registration is requested: 1909 URI: urn:ietf:params:xml:ns:yang:ietf-keystore 1910 Registrant Contact: The IESG 1911 XML: N/A, the requested URI is an XML namespace. 1913 6.2. The "YANG Module Names" Registry 1915 This document registers one YANG module in the YANG Module Names 1916 registry [RFC6020]. Following the format in [RFC6020], the following 1917 registration is requested: 1919 name: ietf-keystore 1920 namespace: urn:ietf:params:xml:ns:yang:ietf-keystore 1921 prefix: ks 1922 reference: RFC CCCC 1924 7. References 1926 7.1. Normative References 1928 [I-D.ietf-netconf-crypto-types] 1929 Watsen, K., "YANG Data Types and Groupings for 1930 Cryptography", Work in Progress, Internet-Draft, draft- 1931 ietf-netconf-crypto-types-18, 20 August 2020, 1932 . 1935 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1936 Requirement Levels", BCP 14, RFC 2119, 1937 DOI 10.17487/RFC2119, March 1997, 1938 . 1940 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1941 the Network Configuration Protocol (NETCONF)", RFC 6020, 1942 DOI 10.17487/RFC6020, October 2010, 1943 . 1945 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1946 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1947 . 1949 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 1950 Access Control Model", STD 91, RFC 8341, 1951 DOI 10.17487/RFC8341, March 2018, 1952 . 1954 7.2. Informative References 1956 [I-D.ietf-netconf-http-client-server] 1957 Watsen, K., "YANG Groupings for HTTP Clients and HTTP 1958 Servers", Work in Progress, Internet-Draft, draft-ietf- 1959 netconf-http-client-server-05, 20 August 2020, 1960 . 1963 [I-D.ietf-netconf-keystore] 1964 Watsen, K., "A YANG Data Model for a Keystore", Work in 1965 Progress, Internet-Draft, draft-ietf-netconf-keystore-20, 1966 20 August 2020, . 1969 [I-D.ietf-netconf-netconf-client-server] 1970 Watsen, K., "NETCONF Client and Server Models", Work in 1971 Progress, Internet-Draft, draft-ietf-netconf-netconf- 1972 client-server-21, 20 August 2020, 1973 . 1976 [I-D.ietf-netconf-restconf-client-server] 1977 Watsen, K., "RESTCONF Client and Server Models", Work in 1978 Progress, Internet-Draft, draft-ietf-netconf-restconf- 1979 client-server-21, 20 August 2020, 1980 . 1983 [I-D.ietf-netconf-ssh-client-server] 1984 Watsen, K., "YANG Groupings for SSH Clients and SSH 1985 Servers", Work in Progress, Internet-Draft, draft-ietf- 1986 netconf-ssh-client-server-22, 20 August 2020, 1987 . 1990 [I-D.ietf-netconf-tcp-client-server] 1991 Watsen, K. and M. Scharf, "YANG Groupings for TCP Clients 1992 and TCP Servers", Work in Progress, Internet-Draft, draft- 1993 ietf-netconf-tcp-client-server-08, 20 August 2020, 1994 . 1997 [I-D.ietf-netconf-tls-client-server] 1998 Watsen, K., "YANG Groupings for TLS Clients and TLS 1999 Servers", Work in Progress, Internet-Draft, draft-ietf- 2000 netconf-tls-client-server-22, 20 August 2020, 2001 . 2004 [I-D.ietf-netconf-trust-anchors] 2005 Watsen, K., "A YANG Data Model for a Truststore", Work in 2006 Progress, Internet-Draft, draft-ietf-netconf-trust- 2007 anchors-13, 20 August 2020, . 2010 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2011 DOI 10.17487/RFC3688, January 2004, 2012 . 2014 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2015 and A. Bierman, Ed., "Network Configuration Protocol 2016 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2017 . 2019 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2020 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2021 . 2023 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2024 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2025 May 2017, . 2027 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 2028 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 2029 . 2031 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 2032 and R. Wilton, "Network Management Datastore Architecture 2033 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 2034 . 2036 [Std-802.1AR-2009] 2037 Group, W. -. H. L. L. P. W., "IEEE Standard for Local and 2038 metropolitan area networks - Secure Device Identity", 2039 December 2009, . 2042 Appendix A. Change Log 2044 This section is to be removed before publishing as an RFC. 2046 A.1. 00 to 01 2048 * Replaced the 'certificate-chain' structures with PKCS#7 2049 structures. (Issue #1) 2051 * Added 'private-key' as a configurable data node, and removed the 2052 'generate-private-key' and 'load-private-key' actions. (Issue #2) 2054 * Moved 'user-auth-credentials' to the ietf-ssh-client module. 2055 (Issues #4 and #5) 2057 A.2. 01 to 02 2059 * Added back 'generate-private-key' action. 2061 * Removed 'RESTRICTED' enum from the 'private-key' leaf type. 2063 * Fixed up a few description statements. 2065 A.3. 02 to 03 2067 * Changed draft's title. 2069 * Added missing references. 2071 * Collapsed sections and levels. 2073 * Added RFC 8174 to Requirements Language Section. 2075 * Renamed 'trusted-certificates' to 'pinned-certificates'. 2077 * Changed 'public-key' from config false to config true. 2079 * Switched 'host-key' from OneAsymmetricKey to definition from RFC 2080 4253. 2082 A.4. 03 to 04 2084 * Added typedefs around leafrefs to common keystore paths 2086 * Now tree diagrams reference ietf-netmod-yang-tree-diagrams 2088 * Removed Design Considerations section 2090 * Moved key and certificate definitions from data tree to groupings 2092 A.5. 04 to 05 2094 * Removed trust anchors (now in their own draft) 2096 * Added back global keystore structure 2098 * Added groupings enabling keys to either be locally defined or a 2099 reference to the keystore. 2101 A.6. 05 to 06 2103 * Added feature "local-keys-supported" 2105 * Added nacm:default-deny-all and nacm:default-deny-write 2107 * Renamed generate-asymmetric-key to generate-hidden-key 2109 * Added an install-hidden-key action 2111 * Moved actions inside fo the "asymmetric-key" container 2113 * Moved some groupings to draft-ietf-netconf-crypto-types 2115 A.7. 06 to 07 2117 * Removed a "require-instance false" 2118 * Clarified some description statements 2120 * Improved the keystore-usage examples 2122 A.8. 07 to 08 2124 * Added "local-definition" containers to avoid posibility of the 2125 action/notification statements being under a "case" statement. 2127 * Updated copyright date, boilerplate template, affiliation, folding 2128 algorithm, and reformatted the YANG module. 2130 A.9. 08 to 09 2132 * Added a 'description' statement to the 'must' in the /keystore/ 2133 asymmetric-key node explaining that the descendent values may 2134 exist in only, and that implementation MUST assert 2135 that the values are either configured or that they exist in 2136 . 2138 * Copied above 'must' statement (and description) into the local-or- 2139 keystore-asymmetric-key-grouping, local-or-keystore-asymmetric- 2140 key-with-certs-grouping, and local-or-keystore-end-entity-cert- 2141 with-key-grouping statements. 2143 A.10. 09 to 10 2145 * Updated draft title to match new truststore draft title 2147 * Moved everything under a top-level 'grouping' to enable use in 2148 other contexts. 2150 * Renamed feature from 'local-keys-supported' to 'local-definitions- 2151 supported' (same name used in truststore) 2153 * Removed the either-all-or-none 'must' expressions for the key's 2154 3-tuple values (since the values are now 'mandatory true' in 2155 crypto-types) 2157 * Example updated to reflect 'mandatory true' change in crypto-types 2158 draft 2160 A.11. 10 to 11 2162 * Replaced typedef asymmetric-key-certificate-ref with grouping 2163 asymmetric-key-certificate-ref-grouping. 2165 * Added feature feature 'key-generation'. 2167 * Cloned groupings symmetric-key-grouping, asymmetric-key-pair- 2168 grouping, asymmetric-key-pair-with-cert-grouping, and asymmetric- 2169 key-pair-with-certs-grouping from crypto-keys, augmenting into 2170 each new case statements for values that have been encrypted by 2171 other keys in the keystore. Refactored keystore model to use 2172 these groupings. 2174 * Added new 'symmetric-keys' lists, as a sibling to the existing 2175 'asymmetric-keys' list. 2177 * Added RPCs (not actions) 'generate-symmetric-key' and 'generate- 2178 asymmetric-key' to *return* a (potentially encrypted) key. 2180 A.12. 11 to 12 2182 * Updated to reflect crypto-type's draft using enumerations over 2183 identities. 2185 * Added examples for the 'generate-symmetric-key' and 'generate- 2186 asymmetric-key' RPCs. 2188 * Updated the Introduction section. 2190 A.13. 12 to 13 2192 * Updated examples to incorporate new "key-format" identities. 2194 * Made the two "generate-*-key" RPCs be "action" statements instead. 2196 A.14. 13 to 14 2198 * Updated YANG module and examples to incorporate the new 2199 iana-*-algorithm modules in the crypto-types draft.. 2201 A.15. 14 to 15 2203 * Added new "Support for Built-in Keys" section. 2205 * Added 'must' expressions asserting that the 'key-format' leaf 2206 whenever an encrypted key is specified. 2208 * Added local-or-keystore-symmetric-key-grouping for PSK support. 2210 A.16. 15 to 16 2212 * Moved the generate key actions to ietf-crypt-types as RPCs, which 2213 are augmented by ietf-keystore to support encrypted keys. 2214 Examples updated accordingly. 2216 * Added a SSH certificate-based key (RFC 6187) and a raw private key 2217 to the example instance document (partly so they could be 2218 referenced by examples in the SSH and TLS client/server drafts. 2220 A.17. 16 to 17 2222 * Removed augments to the "generate-symmetric-key" and "generate- 2223 asymmetric-key" groupings. 2225 * Removed "generate-symmetric-key" and "generate-asymmetric-key" 2226 examples. 2228 * Removed the "algorithm" nodes from remaining examples. 2230 * Updated the "Support for Built-in Keys" section. 2232 * Added new section "Encrypting Keys in Configuration". 2234 * Added a "Note to Reviewers" note to first page. 2236 A.18. 17 to 18 2238 * Removed dangling/unnecessary ref to RFC 8342. 2240 * r/MUST/SHOULD/ wrt strength of keys being configured over 2241 transports. 2243 * Added an example for the "certificate-expiration" notification. 2245 * Clarified that OS MAY have a multiplicity of underlying keystores 2246 and/or HSMs. 2248 * Clarified expected behavior for "built-in" keys in 2250 * Clarified the "Migrating Configuration to Another Server" section. 2252 * Expanded "Data Model Overview section(s) [remove "wall" of tree 2253 diagrams]. 2255 * Updated the Security Considerations section. 2257 A.19. 18 to 19 2259 * Updated examples to reflect new "cleartext-" prefix in the crypto- 2260 types draft. 2262 A.20. 19 to 20 2263 * Addressed SecDir comments from Magnus Nystroem and Sandra Murphy. 2265 A.21. 20 to 21 2267 * Added a "Unconstrained Private Key Usage" Security Consideration 2268 to address concern raised by SecDir. 2270 * (Editorial) Removed the output of "grouping" statements in the 2271 tree diagrams for the "ietf-keystore" and "ex-keystore-usage" 2272 modules. 2274 * Addressed comments raised by YANG Doctor. 2276 Acknowledgements 2278 The authors would like to thank for following for lively discussions 2279 on list and in the halls (ordered by first name): Alan Luchuk, Andy 2280 Bierman, Benoit Claise, Bert Wijnen, Balazs Kovacs, David Lamparter, 2281 Eric Voit, Ladislav Lhotka, Liang Xia, Juergen Schoenwaelder, Mahesh 2282 Jethanandani, Magnus Nystroem, Martin Bjorklund, Mehmet Ersue, Phil 2283 Shafer, Radek Krejci, Ramkumar Dhanapal, Reshad Rahman, Sandra 2284 Murphy, Sean Turner, and Tom Petch. 2286 Author's Address 2288 Kent Watsen 2289 Watsen Networks 2291 Email: kent+ietf@watsen.net