idnits 2.17.1 draft-ietf-netconf-keystore-22.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 560 has weird spacing: '...-format ide...' == Line 568 has weird spacing: '...on-date yan...' == Line 572 has weird spacing: '...sr-info ct:...' == Line 574 has weird spacing: '...request ct:...' == Line 594 has weird spacing: '...-format ide...' == (10 more instances...) -- The document date (18 May 2021) is 1074 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-19 == Outdated reference: A later version (-20) exists of draft-ietf-netconf-http-client-server-06 == Outdated reference: A later version (-35) exists of draft-ietf-netconf-keystore-21 == Outdated reference: A later version (-36) exists of draft-ietf-netconf-netconf-client-server-22 == Outdated reference: A later version (-36) exists of draft-ietf-netconf-restconf-client-server-22 == Outdated reference: A later version (-40) exists of draft-ietf-netconf-ssh-client-server-23 == Outdated reference: A later version (-26) exists of draft-ietf-netconf-tcp-client-server-09 == Outdated reference: A later version (-41) exists of draft-ietf-netconf-tls-client-server-23 == Outdated reference: A later version (-28) exists of draft-ietf-netconf-trust-anchors-14 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 18 May 2021 5 Expires: 19 November 2021 7 A YANG Data Model for a Keystore 8 draft-ietf-netconf-keystore-22 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-05-18" --> 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 19 November 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 A.22. 21 to 22 . . . . . . . . . . . . . . . . . . . . . . . . 50 119 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 50 120 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 50 122 1. Introduction 124 This document defines a YANG 1.1 [RFC7950] module called "ietf- 125 keystore" that enables centralized configuration of both symmetric 126 and asymmetric keys. The secret value for both key types may be 127 encrypted or hidden (see [I-D.ietf-netconf-crypto-types]. Asymmetric 128 keys may be associated with certificates. Notifications are sent 129 when certificates are about to expire. 131 The "ietf-keystore" module defines many "grouping" statements 132 intended for use by other modules that may import it. For instance, 133 there are groupings that define enabling a key to be either 134 configured locally (within the defining data model) or be a reference 135 to a key in the keystore. 137 Special consideration has been given for systems that have 138 cryptographic hardware, such as a Trusted Platform Module (TPM). 139 These systems are unique in that the cryptographic hardware hides the 140 secret key values. Additionally, such hardware is commonly 141 initialized when manufactured to protect a "built-in" asymmetric key 142 for which the public half is conveyed in an identity certificate 143 (e.g., an IDevID [Std-802.1AR-2009] certificate). Please see 144 Section 3 to see how built-in keys are supported. 146 This document intends to support existing practices; it does not 147 intend to define new behavior for systems to implement. To simplify 148 implementation, advanced key formats may be selectively implemented. 150 Implementations may utilize zero or more operating system level 151 keystore utilities and/or hardware security modules (HSMs). 153 1.1. Relation to other RFCs 155 This document presents one or more YANG modules [RFC7950] that are 156 part of a collection of RFCs that work together to, ultimately, 157 enable the configuration of the clients and servers of both the 158 NETCONF [RFC6241] and RESTCONF [RFC8040] protocols. 160 The modules have been defined in a modular fashion to enable their 161 use by other efforts, some of which are known to be in progress at 162 the time of this writing, with many more expected to be defined in 163 time. 165 The normative dependency relationship between the various RFCs in the 166 collection is presented in the below diagram. The labels in the 167 diagram represent the primary purpose provided by each RFC. 168 Hyperlinks to each RFC are provided below the diagram. 170 crypto-types 171 ^ ^ 172 / \ 173 / \ 174 truststore keystore 175 ^ ^ ^ ^ 176 | +---------+ | | 177 | | | | 178 | +------------+ | 179 tcp-client-server | / | | 180 ^ ^ ssh-client-server | | 181 | | ^ tls-client-server 182 | | | ^ ^ http-client-server 183 | | | | | ^ 184 | | | +-----+ +---------+ | 185 | | | | | | 186 | +-----------|--------|--------------+ | | 187 | | | | | | 188 +-----------+ | | | | | 189 | | | | | | 190 | | | | | | 191 netconf-client-server restconf-client-server 193 +=======================+===========================================+ 194 |Label in Diagram | Originating RFC | 195 +=======================+===========================================+ 196 |crypto-types | [I-D.ietf-netconf-crypto-types] | 197 +-----------------------+-------------------------------------------+ 198 |truststore | [I-D.ietf-netconf-trust-anchors] | 199 +-----------------------+-------------------------------------------+ 200 |keystore | [I-D.ietf-netconf-keystore] | 201 +-----------------------+-------------------------------------------+ 202 |tcp-client-server | [I-D.ietf-netconf-tcp-client-server] | 203 +-----------------------+-------------------------------------------+ 204 |ssh-client-server | [I-D.ietf-netconf-ssh-client-server] | 205 +-----------------------+-------------------------------------------+ 206 |tls-client-server | [I-D.ietf-netconf-tls-client-server] | 207 +-----------------------+-------------------------------------------+ 208 |http-client-server | [I-D.ietf-netconf-http-client-server] | 209 +-----------------------+-------------------------------------------+ 210 |netconf-client-server | [I-D.ietf-netconf-netconf-client-server] | 211 +-----------------------+-------------------------------------------+ 212 |restconf-client-server | [I-D.ietf-netconf-restconf-client-server] | 213 +-----------------------+-------------------------------------------+ 215 Table 1: Label to RFC Mapping 217 1.2. Specification Language 219 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 220 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 221 "OPTIONAL" in this document are to be interpreted as described in BCP 222 14 [RFC2119] [RFC8174] when, and only when, they appear in all 223 capitals, as shown here. 225 1.3. Terminology 227 The terms "client" and "server" are defined in [RFC6241] and are not 228 redefined here. 230 The term "keystore" is defined in this draft as a mechanism that 231 intends safeguard secrets placed into it for protection. 233 The nomenclature "" and "" are defined in 234 [RFC8342]. 236 The sentence fragments "augmented" and "augmented in" are used herein 237 as the past tense verbified form of the "augment" statement defined 238 in Section 7.17 of [RFC7950]. 240 1.4. Adherence to the NMDA 242 This document is compliant with Network Management Datastore 243 Architecture (NMDA) [RFC8342]. For instance, keys and associated 244 certificates installed during manufacturing (e.g., for an IDevID 245 certificate) are expected to appear in (see Section 3). 247 2. The "ietf-keystore" Module 249 This section defines a YANG 1.1 [RFC7950] module called "ietf- 250 keystore". A high-level overview of the module is provided in 251 Section 2.1. Examples illustrating the module's use are provided in 252 Section 2.2. The YANG module itself is defined in Section 2.3. 254 2.1. Data Model Overview 256 This section provides an overview of the "ietf-keystore" module in 257 terms of its features, typedefs, groupings, and protocol-accessible 258 nodes. 260 2.1.1. Features 262 The following diagram lists all the "feature" statements defined in 263 the "ietf-keystore" module: 265 Features: 266 +-- central-keystore-supported 267 +-- local-definitions-supported 269 | The diagram above uses syntax that is similar to but not 270 | defined in [RFC8340]. 272 2.1.2. Typedefs 274 The following diagram lists the "typedef" statements defined in the 275 "ietf-keystore" module: 277 Typedefs: 278 leafref 279 +-- symmetric-key-ref 280 +-- asymmetric-key-ref 282 | The diagram above uses syntax that is similar to but not 283 | defined in [RFC8340]. 285 Comments: 287 * All of the typedefs defined in the "ietf-keystore" module extend 288 the base "leafref" type defined in [RFC7950]. 290 * The leafrefs refer to symmetric and asymmetric keys in the central 291 keystore, when this module is implemented. 293 * These typedefs are provided as an aid to downstream modules that 294 import the "ietf-keystore" module. 296 2.1.3. Groupings 298 The "ietf-keystore" module defines the following "grouping" 299 statements: 301 * encrypted-by-choice-grouping 302 * asymmetric-key-certificate-ref-grouping 303 * local-or-keystore-symmetric-key-grouping 304 * local-or-keystore-asymmetric-key-grouping 305 * local-or-keystore-asymmetric-key-with-certs-grouping 306 * local-or-keystore-end-entity-cert-with-key-grouping 307 * keystore-grouping 309 Each of these groupings are presented in the following subsections. 311 2.1.3.1. The "encrypted-by-choice-grouping" Grouping 313 The following tree diagram [RFC8340] illustrates the "encrypted-by- 314 choice-grouping" grouping: 316 | The grouping's name is intended to be parsed "(encrypted- 317 | by)-(choice)-(grouping)", not as "(encrypted)-(by- 318 | choice)-(grouping)". 320 grouping encrypted-by-choice-grouping 321 +-- (encrypted-by-choice) 322 +--:(symmetric-key-ref) 323 | +-- symmetric-key-ref? ks:symmetric-key-ref 324 +--:(asymmetric-key-ref) 325 +-- asymmetric-key-ref? ks:asymmetric-key-ref 327 Comments: 329 * This grouping defines a "choice" statement with options to 330 reference either a symmetric or an asymmetric key configured in 331 the keystore. 333 * This grouping is usable only when the keystore module is 334 implemented. Servers defining custom keystore locations MUST 335 augment in alternate "encrypted-by" references to the alternate 336 locations. 338 2.1.3.2. The "asymmetric-key-certificate-ref-grouping" Grouping 340 The following tree diagram [RFC8340] illustrates the "asymmetric-key- 341 certificate-ref-grouping" grouping: 343 grouping asymmetric-key-certificate-ref-grouping 344 +-- asymmetric-key? ks:asymmetric-key-ref 345 +-- certificate? leafref 347 Comments: 349 * This grouping defines a reference to a certificate in two parts: 350 the first being the name of the asymmetric key the certificate is 351 associated with, and the second being the name of the certificate 352 itself. 354 * This grouping is usable only when the keystore module is 355 implemented. Servers defining custom keystore locations MAY 356 define an alternate grouping for references to the alternate 357 locations. 359 2.1.3.3. The "local-or-keystore-symmetric-key-grouping" Grouping 361 The following tree diagram [RFC8340] illustrates the "local-or- 362 keystore-symmetric-key-grouping" grouping: 364 grouping local-or-keystore-symmetric-key-grouping 365 +-- (local-or-keystore) 366 +--:(local) {local-definitions-supported}? 367 | +-- local-definition 368 | +---u ct:symmetric-key-grouping 369 +--:(keystore) {central-keystore-supported}? 370 +-- keystore-reference? ks:symmetric-key-ref 372 Comments: 374 * The "local-or-keystore-symmetric-key-grouping" grouping is 375 provided soley as convenience to downstream modules that wish to 376 offer an option for whether a symmetric key is defined locally or 377 as a reference to a symmetric key in the keystore. 379 * A "choice" statement is used to expose the various options. Each 380 option is enabled by a "feature" statement. Additional "case" 381 statements MAY be augmented in if, e.g., there is a need to 382 reference a symmetric key in an alternate location. 384 * For the "local-definition" option, the definition uses the 385 "symmetric-key-grouping" grouping discussed in Section 2.1.4.3 of 386 [I-D.ietf-netconf-crypto-types]. 388 * For the "keystore" option, the "keystore-reference" is an instance 389 of the "symmetric-key-ref" discussed in Section 2.1.2. 391 2.1.3.4. The "local-or-keystore-asymmetric-key-grouping" Grouping 393 The following tree diagram [RFC8340] illustrates the "local-or- 394 keystore-asymmetric-key-grouping" grouping: 396 grouping local-or-keystore-asymmetric-key-grouping 397 +-- (local-or-keystore) 398 +--:(local) {local-definitions-supported}? 399 | +-- local-definition 400 | +---u ct:asymmetric-key-pair-grouping 401 +--:(keystore) {central-keystore-supported}? 402 +-- keystore-reference? ks:asymmetric-key-ref 404 Comments: 406 * The "local-or-keystore-asymmetric-key-grouping" grouping is 407 provided soley as convenience to downstream modules that wish to 408 offer an option for whether an asymmetric key is defined locally 409 or as a reference to an asymmetric key in the keystore. 411 * A "choice" statement is used to expose the various options. Each 412 option is enabled by a "feature" statement. Additional "case" 413 statements MAY be augmented in if, e.g., there is a need to 414 reference an asymmetric key in an alternate location. 416 * For the "local-definition" option, the definition uses the 417 "asymmetric-key-pair-grouping" grouping discussed in 418 Section 2.1.4.5 of [I-D.ietf-netconf-crypto-types]. 420 * For the "keystore" option, the "keystore-reference" is an instance 421 of the "asymmetric-key-ref" typedef discussed in Section 2.1.2. 423 2.1.3.5. The "local-or-keystore-asymmetric-key-with-certs-grouping" 424 Grouping 426 The following tree diagram [RFC8340] illustrates the "local-or- 427 keystore-asymmetric-key-with-certs-grouping" grouping: 429 grouping local-or-keystore-asymmetric-key-with-certs-grouping 430 +-- (local-or-keystore) 431 +--:(local) {local-definitions-supported}? 432 | +-- local-definition 433 | +---u ct:asymmetric-key-pair-with-certs-grouping 434 +--:(keystore) {central-keystore-supported}? 435 +-- keystore-reference? ks:asymmetric-key-ref 437 Comments: 439 * The "local-or-keystore-asymmetric-key-with-certs-grouping" 440 grouping is provided soley as convenience to downstream modules 441 that wish to offer an option for whether an asymmetric key is 442 defined locally or as a reference to an asymmetric key in the 443 keystore. 445 * A "choice" statement is used to expose the various options. Each 446 option is enabled by a "feature" statement. Additional "case" 447 statements MAY be augmented in if, e.g., there is a need to 448 reference an asymmetric key in an alternate location. 450 * For the "local-definition" option, the definition uses the 451 "asymmetric-key-pair-with-certs-grouping" grouping discussed in 452 Section 2.1.4.11 of [I-D.ietf-netconf-crypto-types]. 454 * For the "keystore" option, the "keystore-reference" is an instance 455 of the "asymmetric-key-ref" typedef discussed in Section 2.1.2. 457 2.1.3.6. The "local-or-keystore-end-entity-cert-with-key-grouping" 458 Grouping 460 The following tree diagram [RFC8340] illustrates the "local-or- 461 keystore-end-entity-cert-with-key-grouping" grouping: 463 grouping local-or-keystore-end-entity-cert-with-key-grouping 464 +-- (local-or-keystore) 465 +--:(local) {local-definitions-supported}? 466 | +-- local-definition 467 | +---u ct:asymmetric-key-pair-with-cert-grouping 468 +--:(keystore) {central-keystore-supported}? 469 +-- keystore-reference 470 +---u asymmetric-key-certificate-ref-grouping 472 Comments: 474 * The "local-or-keystore-end-entity-cert-with-key-grouping" grouping 475 is provided soley as convenience to downstream modules that wish 476 to offer an option for whether a symmetric key is defined locally 477 or as a reference to a symmetric key in the keystore. 479 * A "choice" statement is used to expose the various options. Each 480 option is enabled by a "feature" statement. Additional "case" 481 statements MAY be augmented in if, e.g., there is a need to 482 reference a symmetric key in an alternate location. 484 * For the "local-definition" option, the definition uses the 485 "asymmetric-key-pair-with-certs-grouping" grouping discussed in 486 Section 2.1.4.11 of [I-D.ietf-netconf-crypto-types]. 488 * For the "keystore" option, the "keystore-reference" uses the 489 "asymmetric-key-certificate-ref-grouping" grouping discussed in 490 Section 2.1.3.2. 492 2.1.3.7. The "keystore-grouping" Grouping 494 The following tree diagram [RFC8340] illustrates the "keystore- 495 grouping" grouping: 497 grouping keystore-grouping 498 +-- asymmetric-keys 499 | +-- asymmetric-key* [name] 500 | +-- name? string 501 | +---u ct:asymmetric-key-pair-with-certs-grouping 502 +-- symmetric-keys 503 +-- symmetric-key* [name] 504 +-- name? string 505 +---u ct:symmetric-key-grouping 507 Comments: 509 * The "keystore-grouping" grouping defines a keystore instance as 510 being composed of symmetric and asymmetric keys. The structure 511 for the symmetric and asymmetric keys is essentially the same, 512 being a "list" inside a "container". 514 * For asymmetric keys, each "asymmetric-key" uses the "asymmetric- 515 key-pair-with-certs-grouping" grouping discussed in 516 Section 2.1.4.11 of [I-D.ietf-netconf-crypto-types]. 518 * For symmetric keys, each "symmetric-key" uses the "symmetric-key- 519 grouping" grouping discussed in Section 2.1.4.3 of 520 [I-D.ietf-netconf-crypto-types]. 522 2.1.4. Protocol-accessible Nodes 524 The following tree diagram [RFC8340] lists all the protocol- 525 accessible nodes defined in the "ietf-keystore" module, without 526 expanding the "grouping" statements: 528 module: ietf-keystore 529 +--rw keystore 530 +---u keystore-grouping 532 The following tree diagram [RFC8340] lists all the protocol- 533 accessible nodes defined in the "ietf-keystore" module, with all 534 "grouping" statements expanded, enabling the keystore's full 535 structure to be seen: 537 module: ietf-keystore 538 +--rw keystore 539 +--rw asymmetric-keys 540 | +--rw asymmetric-key* [name] 541 | +--rw name string 542 | +--rw public-key-format identityref 543 | +--rw public-key binary 544 | +--rw private-key-format? identityref 545 | +--rw (private-key-type) 546 | | +--:(cleartext-private-key) 547 | | | +--rw cleartext-private-key? binary 548 | | +--:(hidden-private-key) 549 | | | +--rw hidden-private-key? empty 550 | | +--:(encrypted-private-key) {private-key-encryption}? 551 | | +--rw encrypted-private-key 552 | | +--rw encrypted-by 553 | | | +--rw (encrypted-by-choice) 554 | | | +--:(symmetric-key-ref) 555 | | | | +--rw symmetric-key-ref? 556 | | | | ks:symmetric-key-ref 557 | | | +--:(asymmetric-key-ref) 558 | | | +--rw asymmetric-key-ref? 559 | | | ks:asymmetric-key-ref 560 | | +--rw encrypted-value-format identityref 561 | | +--rw encrypted-value binary 562 | +--rw certificates 563 | | +--rw certificate* [name] 564 | | +--rw name string 565 | | +--rw cert-data end-entity-cert-cms 566 | | +---n certificate-expiration 567 | | {certificate-expiration-notification}? 568 | | +-- expiration-date yang:date-and-time 569 | +---x generate-certificate-signing-request 570 | {certificate-signing-request-generation}? 571 | +---w input 572 | | +---w csr-info ct:csr-info 573 | +--ro output 574 | +--ro certificate-signing-request ct:csr 575 +--rw symmetric-keys 576 +--rw symmetric-key* [name] 577 +--rw name string 578 +--rw key-format? identityref 579 +--rw (key-type) 580 +--:(cleartext-key) 581 | +--rw cleartext-key? binary 582 +--:(hidden-key) 583 | +--rw hidden-key? empty 584 +--:(encrypted-key) {symmetric-key-encryption}? 585 +--rw encrypted-key 586 +--rw encrypted-by 587 | +--rw (encrypted-by-choice) 588 | +--:(symmetric-key-ref) 589 | | +--rw symmetric-key-ref? 590 | | ks:symmetric-key-ref 591 | +--:(asymmetric-key-ref) 592 | +--rw asymmetric-key-ref? 593 | ks:asymmetric-key-ref 594 +--rw encrypted-value-format identityref 595 +--rw encrypted-value binary 597 Comments: 599 * Protocol-accessible nodes are those nodes that are accessible when 600 the module is "implemented", as described in Section 5.6.5 of 601 [RFC7950]. 603 * The protocol-accessible nodes for the "ietf-keystore" module are 604 an instance of the "keystore-grouping" grouping discussed in 605 Section 2.1.3.7. 607 * The reason for why "keystore-grouping" exists separate from the 608 protocol-accessible nodes definition is so as to enable instances 609 of the keystore to be instantiated in other locations, as may be 610 needed or desired by some modules. 612 2.2. Example Usage 614 The examples in this section are encoded using XML, such as might be 615 the case when using the NETCONF protocol. Other encodings MAY be 616 used, such as JSON when using the RESTCONF protocol. 618 2.2.1. A Keystore Instance 620 The following example illustrates keys in . Please see 621 Section 3 for an example illustrating built-in values in 622 . 624 =============== NOTE: '\' line wrapping per RFC 8792 ================ 626 629 630 631 cleartext-symmetric-key 632 ct:octet-string-key-format 633 base64encodedvalue== 634 635 636 hidden-symmetric-key 637 638 639 640 encrypted-symmetric-key 641 ct:one-symmetric-key-format 642 643 644 hidden-asymmetric-key 646 647 648 ct:cms-enveloped-data-format 649 650 base64encodedvalue== 651 652 653 655 656 657 ssh-rsa-key 658 659 ct:ssh-public-key-format 660 661 base64encodedvalue== 662 663 ct:rsa-private-key-format 664 665 base64encodedvalue== 667 668 669 ssh-rsa-key-with-cert 670 671 ct:subject-public-key-info-format 672 673 base64encodedvalue== 674 675 ct:rsa-private-key-format 676 677 base64encodedvalue== 679 680 681 ex-rsa-cert2 682 base64encodedvalue== 683 684 685 686 687 raw-private-key 688 689 ct:subject-public-key-info-format 690 691 base64encodedvalue== 692 693 ct:rsa-private-key-format 694 695 base64encodedvalue== 697 698 699 rsa-asymmetric-key 700 701 ct:subject-public-key-info-format 702 703 base64encodedvalue== 704 705 ct:rsa-private-key-format 706 707 base64encodedvalue== 709 710 711 ex-rsa-cert 712 base64encodedvalue== 713 714 715 716 717 ec-asymmetric-key 718 719 ct:subject-public-key-info-format 720 721 base64encodedvalue== 722 723 ct:ec-private-key-format 724 725 base64encodedvalue== 727 728 729 ex-ec-cert 730 base64encodedvalue== 731 732 733 734 735 hidden-asymmetric-key 736 737 ct:subject-public-key-info-format 738 739 base64encodedvalue== 740 741 742 743 builtin-idevid-cert 744 base64encodedvalue== 745 746 747 my-ldevid-cert 748 base64encodedvalue== 749 750 751 752 753 encrypted-asymmetric-key 754 755 ct:subject-public-key-info-format 756 757 base64encodedvalue== 758 759 ct:one-asymmetric-key-format 760 761 762 763 encrypted-symmetric-key 765 766 767 ct:cms-encrypted-data-format 768 769 base64encodedvalue== 770 771 772 773 775 2.2.2. A Certificate Expiration Notification 777 The following example illustrates a "certificate-expiration" 778 notification for a certificate associated with a key configured in 779 the keystore. 781 =============== NOTE: '\' line wrapping per RFC 8792 ================ 783 785 2018-05-25T00:01:00Z 786 787 788 789 hidden-asymmetric-key 790 791 792 my-ldevid-cert 793 794 2018-08-05T14:18:53-05:00 796 797 798 799 800 801 802 804 2.2.3. The "Local or Keystore" Groupings 806 This section illustrates the various "local-or-keystore" groupings 807 defined in the "ietf-keystore" module, specifically the "local-or- 808 keystore-symmetric-key-grouping" (Section 2.1.3.3), "local-or- 809 keystore-asymmetric-key-grouping" (Section 2.1.3.4), "local-or- 810 keystore-asymmetric-key-with-certs-grouping" (Section 2.1.3.5), and 811 "local-or-keystore-end-entity-cert-with-key-grouping" 812 (Section 2.1.3.6) groupings. 814 These examples assume the existence of an example module called "ex- 815 keystore-usage" having the namespace "http://example.com/ns/example- 816 keystore-usage". 818 The ex-keystore-usage module is first presented using tree diagrams 819 [RFC8340], followed by an instance example illustrating all the 820 "local-or-keystore" groupings in use, followed by the YANG module 821 itself. 823 The following tree diagram illustrates "ex-keystore-usage" without 824 expanding the "grouping" statements: 826 module: ex-keystore-usage 827 +--rw keystore-usage 828 +--rw symmetric-key* [name] 829 | +--rw name string 830 | +---u ks:local-or-keystore-symmetric-key-grouping 831 +--rw asymmetric-key* [name] 832 | +--rw name string 833 | +---u ks:local-or-keystore-asymmetric-key-grouping 834 +--rw asymmetric-key-with-certs* [name] 835 | +--rw name 836 | | string 837 | +---u ks:local-or-keystore-asymmetric-key-with-certs-grouping 838 +--rw end-entity-cert-with-key* [name] 839 +--rw name 840 | string 841 +---u ks:local-or-keystore-end-entity-cert-with-key-grouping 843 The following tree diagram illustrates the "ex-keystore-usage" 844 module, with all "grouping" statements expanded, enabling the usage's 845 full structure to be seen: 847 module: ex-keystore-usage 848 +--rw keystore-usage 849 +--rw symmetric-key* [name] 850 | +--rw name string 851 | +--rw (local-or-keystore) 852 | +--:(local) {local-definitions-supported}? 853 | | +--rw local-definition 854 | | +--rw key-format? identityref 855 | | +--rw (key-type) 856 | | +--:(cleartext-key) 857 | | | +--rw cleartext-key? binary 858 | | +--:(hidden-key) 859 | | | +--rw hidden-key? empty 860 | | +--:(encrypted-key) {symmetric-key-encryption}? 861 | | +--rw encrypted-key 862 | | +--rw encrypted-by 863 | | +--rw encrypted-value-format identityref 864 | | +--rw encrypted-value binary 865 | +--:(keystore) {central-keystore-supported}? 866 | +--rw keystore-reference? ks:symmetric-key-ref 867 +--rw asymmetric-key* [name] 868 | +--rw name string 869 | +--rw (local-or-keystore) 870 | +--:(local) {local-definitions-supported}? 871 | | +--rw local-definition 872 | | +--rw public-key-format identityref 873 | | +--rw public-key binary 874 | | +--rw private-key-format? identityref 875 | | +--rw (private-key-type) 876 | | +--:(cleartext-private-key) 877 | | | +--rw cleartext-private-key? binary 878 | | +--:(hidden-private-key) 879 | | | +--rw hidden-private-key? empty 880 | | +--:(encrypted-private-key) 881 | | {private-key-encryption}? 882 | | +--rw encrypted-private-key 883 | | +--rw encrypted-by 884 | | +--rw encrypted-value-format identityref 885 | | +--rw encrypted-value binary 886 | +--:(keystore) {central-keystore-supported}? 887 | +--rw keystore-reference? ks:asymmetric-key-ref 888 +--rw asymmetric-key-with-certs* [name] 889 | +--rw name string 890 | +--rw (local-or-keystore) 891 | +--:(local) {local-definitions-supported}? 892 | | +--rw local-definition 893 | | +--rw public-key-format 894 | | | identityref 895 | | +--rw public-key binary 896 | | +--rw private-key-format? 897 | | | identityref 898 | | +--rw (private-key-type) 899 | | | +--:(cleartext-private-key) 900 | | | | +--rw cleartext-private-key? binary 901 | | | +--:(hidden-private-key) 902 | | | | +--rw hidden-private-key? empty 903 | | | +--:(encrypted-private-key) 904 | | | {private-key-encryption}? 905 | | | +--rw encrypted-private-key 906 | | | +--rw encrypted-by 907 | | | +--rw encrypted-value-format identityref 908 | | | +--rw encrypted-value binary 909 | | +--rw certificates 910 | | | +--rw certificate* [name] 911 | | | +--rw name string 912 | | | +--rw cert-data 913 | | | | end-entity-cert-cms 914 | | | +---n certificate-expiration 915 | | | {certificate-expiration-notification}? 916 | | | +-- expiration-date yang:date-and-time 917 | | +---x generate-certificate-signing-request 918 | | {certificate-signing-request-generation}? 919 | | +---w input 920 | | | +---w csr-info ct:csr-info 921 | | +--ro output 922 | | +--ro certificate-signing-request ct:csr 923 | +--:(keystore) {central-keystore-supported}? 924 | +--rw keystore-reference? ks:asymmetric-key-ref 925 +--rw end-entity-cert-with-key* [name] 926 +--rw name string 927 +--rw (local-or-keystore) 928 +--:(local) {local-definitions-supported}? 929 | +--rw local-definition 930 | +--rw public-key-format 931 | | identityref 932 | +--rw public-key binary 933 | +--rw private-key-format? 934 | | identityref 935 | +--rw (private-key-type) 936 | | +--:(cleartext-private-key) 937 | | | +--rw cleartext-private-key? binary 938 | | +--:(hidden-private-key) 939 | | | +--rw hidden-private-key? empty 940 | | +--:(encrypted-private-key) 941 | | {private-key-encryption}? 942 | | +--rw encrypted-private-key 943 | | +--rw encrypted-by 944 | | +--rw encrypted-value-format identityref 945 | | +--rw encrypted-value binary 946 | +--rw cert-data? 947 | | end-entity-cert-cms 948 | +---n certificate-expiration 949 | | {certificate-expiration-notification}? 950 | | +-- expiration-date yang:date-and-time 951 | +---x generate-certificate-signing-request 952 | {certificate-signing-request-generation}? 953 | +---w input 954 | | +---w csr-info ct:csr-info 955 | +--ro output 956 | +--ro certificate-signing-request ct:csr 957 +--:(keystore) {central-keystore-supported}? 958 +--rw keystore-reference 959 +--rw asymmetric-key? ks:asymmetric-key-ref 960 +--rw certificate? leafref 962 The following example provides two equivalent instances of each 963 grouping, the first being a reference to a keystore and the second 964 being locally-defined. The instance having a reference to a keystore 965 is consistent with the keystore defined in Section 2.2.1. The two 966 instances are equivalent, as the locally-defined instance example 967 contains the same values defined by the keystore instance referenced 968 by its sibling example. 970 =============== NOTE: '\' line wrapping per RFC 8792 ================ 972 976 977 979 980 example 1a 981 cleartext-symmetric-key 982 984 985 example 1b 986 987 ct:octet-string-key-format 988 base64encodedvalue== 989 990 992 993 995 996 example 2a 997 rsa-asymmetric-key 998 1000 1001 example 2b 1002 1003 1004 ct:subject-public-key-info-format 1005 1006 base64encodedvalue== 1007 1008 ct:rsa-private-key-format 1009 1010 base64encodedvalue== 1012 1013 1015 1016 1018 1019 example 3a 1020 rsa-asymmetric-key 1021 1023 1024 example 3b 1025 1026 1027 ct:subject-public-key-info-format 1028 1029 base64encodedvalue== 1030 1031 ct:rsa-private-key-format 1032 1033 base64encodedvalue== 1035 1036 1037 a locally-defined cert 1038 base64encodedvalue== 1039 1040 1041 1042 1044 1045 1047 1048 example 4a 1049 1050 rsa-asymmetric-key 1051 ex-rsa-cert 1052 1053 1055 1056 example 4b 1057 1058 1059 ct:subject-public-key-info-format 1060 1061 base64encodedvalue== 1062 1063 ct:rsa-private-key-format 1064 1065 base64encodedvalue== 1067 base64encodedvalue== 1068 1069 1071 1073 Following is the "ex-keystore-usage" module's YANG definition: 1075 module ex-keystore-usage { 1076 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-05-18 { 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."; 1106 list symmetric-key { 1107 key "name"; 1108 leaf name { 1109 type string; 1110 description 1111 "An arbitrary name for this key."; 1112 } 1113 uses ks:local-or-keystore-symmetric-key-grouping; 1114 description 1115 "An symmetric key that may be configured locally or be a 1116 reference to a symmetric key in the keystore."; 1117 } 1118 list asymmetric-key { 1119 key "name"; 1120 leaf name { 1121 type string; 1122 description 1123 "An arbitrary name for this key."; 1124 } 1125 uses ks:local-or-keystore-asymmetric-key-grouping; 1126 description 1127 "An asymmetric key, with no certs, that may be configured 1128 locally or be a reference to an asymmetric key in the 1129 keystore. The intent is to reference just the asymmetric 1130 key, not any certificates that may also be associated 1131 with the asymmetric key."; 1132 } 1133 list asymmetric-key-with-certs { 1134 key "name"; 1135 leaf name { 1136 type string; 1137 description 1138 "An arbitrary name for this key."; 1139 } 1140 uses ks:local-or-keystore-asymmetric-key-with-certs-grouping; 1141 description 1142 "An asymmetric key and its associated certs, that may be 1143 configured locally or be a reference to an asymmetric key 1144 (and its associated certs) in the keystore."; 1145 } 1146 list end-entity-cert-with-key { 1147 key "name"; 1148 leaf name { 1149 type string; 1150 description 1151 "An arbitrary name for this key."; 1152 } 1153 uses ks:local-or-keystore-end-entity-cert-with-key-grouping; 1154 description 1155 "An end-entity certificate and its associated asymmetric 1156 key, that may be configured locally or be a reference 1157 to another certificate (and its associated asymmetric 1158 key) in the keystore."; 1160 } 1161 } 1162 } 1164 2.3. YANG Module 1166 This YANG module has normative references to [RFC8341] and 1167 [I-D.ietf-netconf-crypto-types]. 1169 file "ietf-keystore@2021-05-18.yang" 1171 module ietf-keystore { 1172 yang-version 1.1; 1173 namespace "urn:ietf:params:xml:ns:yang:ietf-keystore"; 1174 prefix ks; 1176 import ietf-netconf-acm { 1177 prefix nacm; 1178 reference 1179 "RFC 8341: Network Configuration Access Control Model"; 1180 } 1182 import ietf-crypto-types { 1183 prefix ct; 1184 reference 1185 "RFC AAAA: YANG Data Types and Groupings for Cryptography"; 1186 } 1188 organization 1189 "IETF NETCONF (Network Configuration) Working Group"; 1191 contact 1192 "WG Web: 1193 WG List: 1194 Author: Kent Watsen "; 1196 description 1197 "This module defines a 'keystore' to centralize management 1198 of security credentials. 1200 Copyright (c) 2021 IETF Trust and the persons identified 1201 as authors of the code. All rights reserved. 1203 Redistribution and use in source and binary forms, with 1204 or without modification, is permitted pursuant to, and 1205 subject to the license terms contained in, the Simplified 1206 BSD License set forth in Section 4.c of the IETF Trust's 1207 Legal Provisions Relating to IETF Documents 1208 (https://trustee.ietf.org/license-info). 1210 This version of this YANG module is part of RFC CCCC 1211 (https://www.rfc-editor.org/info/rfcCCCC); see the RFC 1212 itself for full legal notices. 1214 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1215 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 1216 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 1217 are to be interpreted as described in BCP 14 (RFC 2119) 1218 (RFC 8174) when, and only when, they appear in all 1219 capitals, as shown here."; 1221 revision 2021-05-18 { 1222 description 1223 "Initial version"; 1224 reference 1225 "RFC CCCC: A YANG Data Model for a Keystore"; 1226 } 1228 /****************/ 1229 /* Features */ 1230 /****************/ 1232 feature central-keystore-supported { 1233 description 1234 "The 'central-keystore-supported' feature indicates that 1235 the server supports the keystore."; 1236 } 1238 feature local-definitions-supported { 1239 description 1240 "The 'local-definitions-supported' feature indicates that 1241 the server supports locally-defined keys."; 1242 } 1244 /****************/ 1245 /* Typedefs */ 1246 /****************/ 1248 typedef symmetric-key-ref { 1249 type leafref { 1250 path "/ks:keystore/ks:symmetric-keys/ks:symmetric-key" 1251 + "/ks:name"; 1252 } 1253 description 1254 "This typedef enables modules to easily define a reference 1255 to a symmetric key stored in the keystore, when this 1256 module is implemented."; 1257 } 1259 typedef asymmetric-key-ref { 1260 type leafref { 1261 path "/ks:keystore/ks:asymmetric-keys/ks:asymmetric-key" 1262 + "/ks:name"; 1263 } 1264 description 1265 "This typedef enables modules to easily define a reference 1266 to an asymmetric key stored in the keystore, when this 1267 module is implemented."; 1268 } 1270 /*****************/ 1271 /* Groupings */ 1272 /*****************/ 1274 grouping encrypted-by-choice-grouping { 1275 description 1276 "A grouping that defines a 'choice' statement that can be 1277 augmented into the 'encrypted-by' node, present in the 1278 'symmetric-key-grouping' and 'asymmetric-key-pair-grouping' 1279 groupings defined in RFC AAAA, enabling references to keys 1280 in the keystore, when this module is implemented."; 1281 choice encrypted-by-choice { 1282 nacm:default-deny-write; 1283 mandatory true; 1284 description 1285 "A choice amongst other symmetric or asymmetric keys."; 1286 case symmetric-key-ref { 1287 leaf symmetric-key-ref { 1288 type ks:symmetric-key-ref; 1289 description 1290 "Identifies the symmetric key used to encrypt the 1291 associated key."; 1292 } 1293 } 1294 case asymmetric-key-ref { 1295 leaf asymmetric-key-ref { 1296 type ks:asymmetric-key-ref; 1297 description 1298 "Identifies the asymmetric key whose public key 1299 encrypted the associated key."; 1300 } 1301 } 1302 } 1303 } 1304 grouping asymmetric-key-certificate-ref-grouping { 1305 description 1306 "This grouping defines a reference to a specific certificate 1307 associated with an asymmetric key stored in the keystore, 1308 when this module is implemented."; 1309 leaf asymmetric-key { 1310 nacm:default-deny-write; 1311 type ks:asymmetric-key-ref; 1312 must '../certificate'; 1313 description 1314 "A reference to an asymmetric key in the keystore."; 1315 } 1316 leaf certificate { 1317 nacm:default-deny-write; 1318 type leafref { 1319 path "/ks:keystore/ks:asymmetric-keys/ks:asymmetric-key" 1320 + "[ks:name = current()/../asymmetric-key]/" 1321 + "ks:certificates/ks:certificate/ks:name"; 1322 } 1323 must '../asymmetric-key'; 1324 description 1325 "A reference to a specific certificate of the 1326 asymmetric key in the keystore."; 1327 } 1328 } 1330 // local-or-keystore-* groupings 1332 grouping local-or-keystore-symmetric-key-grouping { 1333 description 1334 "A grouping that expands to allow the symmetric key to be 1335 either stored locally, i.e., within the using data model, 1336 or a reference to a symmetric key stored in the keystore. 1338 Servers that do not 'implement' this module, and hence 1339 'central-keystore-supported' is not defined, SHOULD 1340 augment in custom 'case' statements enabling references 1341 to the alternate keystore locations."; 1342 choice local-or-keystore { 1343 nacm:default-deny-write; 1344 mandatory true; 1345 description 1346 "A choice between an inlined definition and a definition 1347 that exists in the keystore."; 1348 case local { 1349 if-feature "local-definitions-supported"; 1350 container local-definition { 1351 description 1352 "Container to hold the local key definition."; 1353 uses ct:symmetric-key-grouping; 1354 } 1355 } 1356 case keystore { 1357 if-feature "central-keystore-supported"; 1358 leaf keystore-reference { 1359 type ks:symmetric-key-ref; 1360 description 1361 "A reference to an symmetric key that exists in 1362 the keystore, when this module is implemented."; 1363 } 1364 } 1365 } 1366 } 1368 grouping local-or-keystore-asymmetric-key-grouping { 1369 description 1370 "A grouping that expands to allow the asymmetric key to be 1371 either stored locally, i.e., within the using data model, 1372 or a reference to an asymmetric key stored in the keystore. 1374 Servers that do not 'implement' this module, and hence 1375 'central-keystore-supported' is not defined, SHOULD 1376 augment in custom 'case' statements enabling references 1377 to the alternate keystore locations."; 1378 choice local-or-keystore { 1379 nacm:default-deny-write; 1380 mandatory true; 1381 description 1382 "A choice between an inlined definition and a definition 1383 that exists in the keystore."; 1384 case local { 1385 if-feature "local-definitions-supported"; 1386 container local-definition { 1387 description 1388 "Container to hold the local key definition."; 1389 uses ct:asymmetric-key-pair-grouping; 1390 } 1391 } 1392 case keystore { 1393 if-feature "central-keystore-supported"; 1394 leaf keystore-reference { 1395 type ks:asymmetric-key-ref; 1396 description 1397 "A reference to an asymmetric key that exists in 1398 the keystore, when this module is implemented. The 1399 intent is to reference just the asymmetric key 1400 without any regard for any certificates that may 1401 be associated with it."; 1402 } 1403 } 1404 } 1405 } 1407 grouping local-or-keystore-asymmetric-key-with-certs-grouping { 1408 description 1409 "A grouping that expands to allow an asymmetric key and 1410 its associated certificates to be either stored locally, 1411 i.e., within the using data model, or a reference to an 1412 asymmetric key (and its associated certificates) stored 1413 in the keystore. 1415 Servers that do not 'implement' this module, and hence 1416 'central-keystore-supported' is not defined, SHOULD 1417 augment in custom 'case' statements enabling references 1418 to the alternate keystore locations."; 1419 choice local-or-keystore { 1420 nacm:default-deny-write; 1421 mandatory true; 1422 description 1423 "A choice between an inlined definition and a definition 1424 that exists in the keystore."; 1425 case local { 1426 if-feature "local-definitions-supported"; 1427 container local-definition { 1428 description 1429 "Container to hold the local key definition."; 1430 uses ct:asymmetric-key-pair-with-certs-grouping; 1431 } 1432 } 1433 case keystore { 1434 if-feature "central-keystore-supported"; 1435 leaf keystore-reference { 1436 type ks:asymmetric-key-ref; 1437 description 1438 "A reference to an asymmetric-key (and all of its 1439 associated certificates) in the keystore, when 1440 this module is implemented."; 1441 } 1442 } 1443 } 1444 } 1446 grouping local-or-keystore-end-entity-cert-with-key-grouping { 1447 description 1448 "A grouping that expands to allow an end-entity certificate 1449 (and its associated asymmetric key pair) to be either stored 1450 locally, i.e., within the using data model, or a reference 1451 to a specific certificate in the keystore. 1453 Servers that do not 'implement' this module, and hence 1454 'central-keystore-supported' is not defined, SHOULD 1455 augment in custom 'case' statements enabling references 1456 to the alternate keystore locations."; 1457 choice local-or-keystore { 1458 nacm:default-deny-write; 1459 mandatory true; 1460 description 1461 "A choice between an inlined definition and a definition 1462 that exists in the keystore."; 1463 case local { 1464 if-feature "local-definitions-supported"; 1465 container local-definition { 1466 description 1467 "Container to hold the local key definition."; 1468 uses ct:asymmetric-key-pair-with-cert-grouping; 1469 } 1470 } 1471 case keystore { 1472 if-feature "central-keystore-supported"; 1473 container keystore-reference { 1474 uses asymmetric-key-certificate-ref-grouping; 1475 description 1476 "A reference to a specific certificate associated with 1477 an asymmetric key stored in the keystore, when this 1478 module is implemented."; 1479 } 1480 } 1481 } 1482 } 1484 grouping keystore-grouping { 1485 description 1486 "Grouping definition enables use in other contexts. If ever 1487 done, implementations MUST augment new 'case' statements 1488 into the various local-or-keystore 'choice' statements to 1489 supply leafrefs to the model-specific location(s)."; 1490 container asymmetric-keys { 1491 nacm:default-deny-write; 1492 description 1493 "A list of asymmetric keys."; 1494 list asymmetric-key { 1495 key "name"; 1496 description 1497 "An asymmetric key."; 1498 leaf name { 1499 type string; 1500 description 1501 "An arbitrary name for the asymmetric key."; 1502 } 1503 uses ct:asymmetric-key-pair-with-certs-grouping; 1504 } 1505 } 1506 container symmetric-keys { 1507 nacm:default-deny-write; 1508 description 1509 "A list of symmetric keys."; 1510 list symmetric-key { 1511 key "name"; 1512 description 1513 "A symmetric key."; 1514 leaf name { 1515 type string; 1516 description 1517 "An arbitrary name for the symmetric key."; 1518 } 1519 uses ct:symmetric-key-grouping; 1520 } 1521 } 1522 } 1524 /*********************************/ 1525 /* Protocol accessible nodes */ 1526 /*********************************/ 1528 container keystore { 1529 description 1530 "A central keystore containing a list of symmetric keys and 1531 a list of asymmetric keys."; 1532 nacm:default-deny-write; 1533 uses keystore-grouping { 1534 augment "symmetric-keys/symmetric-key/key-type/encrypted-key/" 1535 + "encrypted-key/encrypted-by" { 1536 description 1537 "Augments in a choice statement enabling the encrypting 1538 key to be any other symmetric or asymmetric key in the 1539 central keystore."; 1540 uses encrypted-by-choice-grouping; 1541 } 1542 augment "asymmetric-keys/asymmetric-key/private-key-type/" 1543 + "encrypted-private-key/encrypted-private-key/" 1544 + "encrypted-by" { 1545 description 1546 "Augments in a choice statement enabling the encrypting 1547 key to be any other symmetric or asymmetric key in the 1548 central keystore."; 1549 uses encrypted-by-choice-grouping; 1550 } 1551 } 1552 } 1553 } 1555 1557 3. Support for Built-in Keys 1559 In some implementations, a server may support built-in keys. Built- 1560 in keys MAY be set during the manufacturing process or be dynamically 1561 generated the first time the server is booted or a particular service 1562 (e.g., SSH) is enabled. 1564 The primary characteristic of the built-in keys is that they are 1565 provided by the system, as opposed to configuration. As such, they 1566 are present in . The example below illustrates what the 1567 keystore in might look like for a server in its factory 1568 default state. 1570 1574 1575 1576 Manufacturer-Generated Hidden Key 1577 1578 ct:subject-public-key-info-format 1579 1580 base64encodedvalue== 1581 1582 1583 1584 Manufacturer-Generated IDevID Cert 1585 base64encodedvalue== 1586 1587 1588 1589 1590 1591 In order for the built-in keys (and their associated built-in 1592 certificates) to be referenced by configuration, the referenced keys 1593 and associated certificates MUST first be copied into . 1595 Built-in keys that are "hidden" MUST be copied into using 1596 the same key values, so that the server can bind them to the built-in 1597 entries. 1599 Built-in keys that are "encrypted" MAY be copied into other parts of 1600 the configuration so long as they are otherwise unmodified (e.g., the 1601 "encrypted-by" reference cannot be altered). 1603 Built-in keys that are "cleartext" MAY be copied into other parts of 1604 the configuration but, by doing so, they lose their association to 1605 the built-in entries and any assurances afforded by knowing they are/ 1606 were built-in. 1608 The built-in keys and built-in associated certificates are immutable 1609 by configuration operations. With exception to additional/custom 1610 certificates associated to a built-in key, servers MUST ignore 1611 attempts to modify any aspect of built-in keys and/or built-in 1612 associated certificates. 1614 The following example illustrates how a single built-in key 1615 definition from the previous example has been propagated to 1616 : 1618 1620 1621 1622 Manufacturer-Generated Hidden Key 1623 1624 ct:subject-public-key-info-format 1625 1626 base64encodedvalue== 1627 1628 1629 1630 Manufacturer-Generated IDevID Cert 1631 base64encodedvalue== 1632 1633 1634 Deployment-Specific LDevID Cert 1635 base64encodedvalue== 1636 1637 1638 1639 1640 1642 After the above configuration is applied, should appear 1643 as follows: 1645 1649 1650 1651 Manufacturer-Generated Hidden Key 1652 1653 ct:subject-public-key-info-format 1654 1655 base64encodedvalue== 1656 1657 1658 1659 Manufacturer-Generated IDevID Cert 1660 base64encodedvalue== 1661 1662 1663 Deployment-Specific LDevID Cert 1664 base64encodedvalue== 1665 1666 1667 1668 1669 1671 4. Encrypting Keys in Configuration 1673 This section describes an approach that enables both the symmetric 1674 and asymmetric keys on a server to be encrypted, such that 1675 traditional backup/restore procedures can be used without concern for 1676 the keys being compromised when in transit. 1678 4.1. Key Encryption Key 1680 The ability to encrypt configured keys is predicated on the existence 1681 of a "key encryption key" (KEK). There may be any number of KEKs in 1682 a system. A KEK, by its namesake, is a key that is used to encrypt 1683 other keys. A KEK MAY be either a symmetric key or an asymmetric 1684 key. 1686 If a KEK is a symmetric key, then the server MUST provide an API for 1687 administrators to encrypt other keys without needing to know the 1688 symmetric key's value. If the KEK is an asymmetric key, then the 1689 server MAY provide an API enabling the encryption of other keys or, 1690 alternatively, let the administrators do so themselves using the 1691 asymmetric key's public half. 1693 A server MUST possess (or be able to possess, in case the KEK has 1694 been encrypted by another KEK) a KEK's cleartext value so that it can 1695 decrypt the other keys in the configuration at runtime. 1697 4.2. Configuring Encrypted Keys 1699 Each time a new key is configured, it SHOULD be encrypted by a KEK. 1701 In "ietf-crypto-types" [I-D.ietf-netconf-crypto-types], the format 1702 for encrypted values is described by identity statements derived from 1703 the "symmetrically-encrypted-value-format" and "symmetrically- 1704 encrypted-value-format" identity statements. 1706 Implementations SHOULD provide an API that simultaneously generates 1707 and encrypts a key (symmetric or asymmetric) using a KEK. Thusly 1708 newly generated key cleartext values may never known to the 1709 administrators generating the keys. 1711 In case the server implementation does not provide such an API, then 1712 the generating and encrypting steps MAY be performed outside the 1713 server, e.g., by an administrator with special access control rights 1714 (e.g., an organization's crypto officer). 1716 In either case, the encrypted key can be configured into the keystore 1717 using either the "encrypted-key" (for symmetric keys) or the 1718 "encrypted-private-key" (for asymmetric keys) nodes. These two nodes 1719 contain both the encrypted value as well as a reference to the KEK 1720 that encrypted the key. 1722 4.3. Migrating Configuration to Another Server 1724 When a KEK is used to encrypt other keys, migrating the configuration 1725 to another server is only possible if the second server has the same 1726 KEK. How the second server comes to have the same KEK is discussed 1727 in this section. 1729 In some deployments, mechanisms outside the scope of this document 1730 may be used to migrate a KEK from one server to another. That said, 1731 beware that the ability to do so typically entails having access to 1732 the first server but, in many scenarios, the first server may no 1733 longer be operational. 1735 In other deployments, an organization's crypto officer, possessing a 1736 KEK's cleartext value, configures the same KEK on the second server, 1737 presumably as a hidden key or a key protected by access-control 1738 (e.g., NACM's "default-deny-all"), so that the cleartext value is not 1739 disclosed to regular administrators. However, this approach creates 1740 high-coupling to and dependency on the crypto officers that doesn't 1741 scale in production environments. 1743 In order to decouple the crypto officers from the regular 1744 administrators, a special KEK, called the "master key" (MK), may be 1745 used. 1747 A MK is commonly a globally-unique built-in (see Section 3) 1748 asymmetric key. The private key, due to its long lifetime, is hidden 1749 (i.e., "hidden-private-key" in Section 2.1.4.5. of 1750 [I-D.ietf-netconf-crypto-types]). The public key is often contained 1751 in an identity certificate (e.g., IDevID). How to configure a MK 1752 during the manufacturing process is outside the scope of this 1753 document. 1755 It is RECOMMENDED that MKs are built-in and hidden but, if this is 1756 not possible, access control mechanisms like NACM SHOULD be used to 1757 limit access to the MK's secret data only to the most trusted 1758 authorized clients (e.g., an organization's crypto officer). In this 1759 case, it is RECOMMENDED that the MK is not built-in and hence is, 1760 effectively, just like a KEK. 1762 Assuming the server has a MK, the MK can be used to encrypt a "shared 1763 KEK", which is then used to encrypt the keys configured by regular 1764 administrators. 1766 With this extra level of indirection, it is possible for a crypto 1767 officer to encrypt the same KEK for a multiplicity of servers offline 1768 using the public key contained in their identity certificates. The 1769 crypto officer can then safely handoff the encrypted KEKs to the 1770 regular administrators responsible for server installations, 1771 including migrations. 1773 In order to migrate the configuration from a first server, an 1774 administrator would need to make just a single modification to the 1775 configuration before loading it onto a second server, which is to 1776 replace the encrypted KEK keystore entry from the first server with 1777 the encrypted KEK for the second server. Upon doing this, the 1778 configuration (containing many encrypted keys) can be loaded into the 1779 second server while enabling the second server to decrypt all the 1780 encrypted keys in the configuration. 1782 The following diagram illustrates this idea: 1784 +-------------+ +-------------+ 1785 | shared KEK | | shared KEK | 1786 |(unencrypted)|-------------------------------> | (encrypted) | 1787 +-------------+ encrypts offline using +-------------+ 1788 ^ each server's MK | 1789 | | 1790 | | 1791 | possesses \o | 1792 +-------------- |\ | 1793 / \ shares with | 1794 crypto +--------------------+ 1795 officer | 1796 | 1797 | 1798 +----------------------+ | +----------------------+ 1799 | server-1 | | | server-2 | 1800 | configuration | | | configuration | 1801 | | | | | 1802 | | | | | 1803 | +----------------+ | | | +----------------+ | 1804 | | MK-1 | | | | | MK-2 | | 1805 | | (hidden) | | | | | (hidden) | | 1806 | +----------------+ | | | +----------------+ | 1807 | ^ | | | ^ | 1808 | | | | | | | 1809 | | | | | | | 1810 | | encrypted | | | | encrypted | 1811 | | by | | | | by | 1812 | | | | | | | 1813 | | | | | | | 1814 | +----------------+ | | | +----------------+ | 1815 | | shared KEK | | | | | shared KEK | | 1816 | | (encrypted) | | v | | (encrypted) | | 1817 | +----------------+ | | +----------------+ | 1818 | ^ | regular | ^ | 1819 | | | admin | | | 1820 | | | | | | 1821 | | encrypted | \o | | encrypted | 1822 | | by | |\ | | by | 1823 | | | / \ | | | 1824 | | | | | | 1825 | +----------------+ |----------------->| +----------------+ | 1826 | | all other keys | | migrate | | all other keys | | 1827 | | (encrypted) | | configuration | | (encrypted) | | 1828 | +----------------+ | | +----------------+ | 1829 | | | | 1830 +----------------------+ +----------------------+ 1832 5. Security Considerations 1834 5.1. Security of Data at Rest 1836 The YANG module defined in this document defines a mechanism called a 1837 "keystore" that, by its name, suggests that it will protect its 1838 contents from unauthorized disclosure and modification. 1840 Security controls for the API (i.e., data in motion) are discussed in 1841 Section 5.3, but controls for the data at rest cannot be specified by 1842 the YANG module. 1844 In order to satisfy the expectations of a "keystore", it is 1845 RECOMMENDED that implementations ensure that the keystore contents 1846 are encrypted when persisted to non-volatile memory. 1848 5.2. Unconstrained Private Key Usage 1850 This module enables the configuration of private keys without 1851 constraints on their usage, e.g., what operations the key is allowed 1852 to be used for (e.g., signature, decryption, both). 1854 This module also does not constrain the usage of the associated 1855 public keys, other than in the context of a configured certificate 1856 (e.g., an identity certificate), in which case the key usage is 1857 constrained by the certificate. 1859 5.3. The "ietf-keystore" YANG Module 1861 The YANG module defined in this document is designed to be accessed 1862 via YANG based management protocols, such as NETCONF [RFC6241] and 1863 RESTCONF [RFC8040]. Both of these protocols have mandatory-to- 1864 implement secure transport layers (e.g., SSH, TLS) with mutual 1865 authentication. 1867 The NETCONF access control model (NACM) [RFC8341] provides the means 1868 to restrict access for particular users to a pre-configured subset of 1869 all available protocol operations and content. 1871 None of the readable data nodes defined in this YANG module are 1872 considered sensitive or vulnerable in network environments. The NACM 1873 "default-deny-all" extension has not been set for any data nodes 1874 defined in this module. 1876 | Please be aware that this module uses the "cleartext-key" and 1877 | "cleartext-private-key" nodes from the "ietf-crypto-types" 1878 | module [I-D.ietf-netconf-crypto-types], where said nodes have 1879 | the NACM extension "default-deny-all" set, thus preventing 1880 | uncontrolled read-access to the cleartext key values. 1882 All of the writable data nodes defined by this module, both in the 1883 "grouping" statements as well as the protocol-accessible "keystore" 1884 instance, may be considered sensitive or vulnerable in some network 1885 environments.. For instance, any modification to a key or reference 1886 to a key may dramatically alter the implemented security policy. For 1887 this reason, the NACM extension "default-deny-write" has been set for 1888 all data nodes defined in this module. 1890 This module does not define any "rpc" or "action" statements, and 1891 thus the security considerations for such is not provided here. 1893 6. IANA Considerations 1895 6.1. The "IETF XML" Registry 1897 This document registers one URI in the "ns" subregistry of the IETF 1898 XML Registry [RFC3688]. Following the format in [RFC3688], the 1899 following registration is requested: 1901 URI: urn:ietf:params:xml:ns:yang:ietf-keystore 1902 Registrant Contact: The IESG 1903 XML: N/A, the requested URI is an XML namespace. 1905 6.2. The "YANG Module Names" Registry 1907 This document registers one YANG module in the YANG Module Names 1908 registry [RFC6020]. Following the format in [RFC6020], the following 1909 registration is requested: 1911 name: ietf-keystore 1912 namespace: urn:ietf:params:xml:ns:yang:ietf-keystore 1913 prefix: ks 1914 reference: RFC CCCC 1916 7. References 1918 7.1. Normative References 1920 [I-D.ietf-netconf-crypto-types] 1921 Watsen, K., "YANG Data Types and Groupings for 1922 Cryptography", Work in Progress, Internet-Draft, draft- 1923 ietf-netconf-crypto-types-19, 10 February 2021, 1924 . 1927 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1928 Requirement Levels", BCP 14, RFC 2119, 1929 DOI 10.17487/RFC2119, March 1997, 1930 . 1932 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1933 the Network Configuration Protocol (NETCONF)", RFC 6020, 1934 DOI 10.17487/RFC6020, October 2010, 1935 . 1937 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1938 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1939 . 1941 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 1942 Access Control Model", STD 91, RFC 8341, 1943 DOI 10.17487/RFC8341, March 2018, 1944 . 1946 7.2. Informative References 1948 [I-D.ietf-netconf-http-client-server] 1949 Watsen, K., "YANG Groupings for HTTP Clients and HTTP 1950 Servers", Work in Progress, Internet-Draft, draft-ietf- 1951 netconf-http-client-server-06, 10 February 2021, 1952 . 1955 [I-D.ietf-netconf-keystore] 1956 Watsen, K., "A YANG Data Model for a Keystore", Work in 1957 Progress, Internet-Draft, draft-ietf-netconf-keystore-21, 1958 10 February 2021, . 1961 [I-D.ietf-netconf-netconf-client-server] 1962 Watsen, K., "NETCONF Client and Server Models", Work in 1963 Progress, Internet-Draft, draft-ietf-netconf-netconf- 1964 client-server-22, 10 February 2021, 1965 . 1968 [I-D.ietf-netconf-restconf-client-server] 1969 Watsen, K., "RESTCONF Client and Server Models", Work in 1970 Progress, Internet-Draft, draft-ietf-netconf-restconf- 1971 client-server-22, 10 February 2021, 1972 . 1975 [I-D.ietf-netconf-ssh-client-server] 1976 Watsen, K., "YANG Groupings for SSH Clients and SSH 1977 Servers", Work in Progress, Internet-Draft, draft-ietf- 1978 netconf-ssh-client-server-23, 10 February 2021, 1979 . 1982 [I-D.ietf-netconf-tcp-client-server] 1983 Watsen, K. and M. Scharf, "YANG Groupings for TCP Clients 1984 and TCP Servers", Work in Progress, Internet-Draft, draft- 1985 ietf-netconf-tcp-client-server-09, 10 February 2021, 1986 . 1989 [I-D.ietf-netconf-tls-client-server] 1990 Watsen, K., "YANG Groupings for TLS Clients and TLS 1991 Servers", Work in Progress, Internet-Draft, draft-ietf- 1992 netconf-tls-client-server-23, 10 February 2021, 1993 . 1996 [I-D.ietf-netconf-trust-anchors] 1997 Watsen, K., "A YANG Data Model for a Truststore", Work in 1998 Progress, Internet-Draft, draft-ietf-netconf-trust- 1999 anchors-14, 10 February 2021, 2000 . 2003 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2004 DOI 10.17487/RFC3688, January 2004, 2005 . 2007 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2008 and A. Bierman, Ed., "Network Configuration Protocol 2009 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2010 . 2012 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2013 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2014 . 2016 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2017 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2018 May 2017, . 2020 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 2021 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 2022 . 2024 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 2025 and R. Wilton, "Network Management Datastore Architecture 2026 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 2027 . 2029 [Std-802.1AR-2009] 2030 Group, W. -. H. L. L. P. W., "IEEE Standard for Local and 2031 metropolitan area networks - Secure Device Identity", 2032 December 2009, . 2035 Appendix A. Change Log 2037 This section is to be removed before publishing as an RFC. 2039 A.1. 00 to 01 2041 * Replaced the 'certificate-chain' structures with PKCS#7 2042 structures. (Issue #1) 2044 * Added 'private-key' as a configurable data node, and removed the 2045 'generate-private-key' and 'load-private-key' actions. (Issue #2) 2047 * Moved 'user-auth-credentials' to the ietf-ssh-client module. 2048 (Issues #4 and #5) 2050 A.2. 01 to 02 2052 * Added back 'generate-private-key' action. 2054 * Removed 'RESTRICTED' enum from the 'private-key' leaf type. 2056 * Fixed up a few description statements. 2058 A.3. 02 to 03 2060 * Changed draft's title. 2062 * Added missing references. 2064 * Collapsed sections and levels. 2066 * Added RFC 8174 to Requirements Language Section. 2068 * Renamed 'trusted-certificates' to 'pinned-certificates'. 2070 * Changed 'public-key' from config false to config true. 2072 * Switched 'host-key' from OneAsymmetricKey to definition from RFC 2073 4253. 2075 A.4. 03 to 04 2077 * Added typedefs around leafrefs to common keystore paths 2079 * Now tree diagrams reference ietf-netmod-yang-tree-diagrams 2081 * Removed Design Considerations section 2083 * Moved key and certificate definitions from data tree to groupings 2085 A.5. 04 to 05 2087 * Removed trust anchors (now in their own draft) 2089 * Added back global keystore structure 2091 * Added groupings enabling keys to either be locally defined or a 2092 reference to the keystore. 2094 A.6. 05 to 06 2096 * Added feature "local-keys-supported" 2098 * Added nacm:default-deny-all and nacm:default-deny-write 2100 * Renamed generate-asymmetric-key to generate-hidden-key 2102 * Added an install-hidden-key action 2104 * Moved actions inside fo the "asymmetric-key" container 2106 * Moved some groupings to draft-ietf-netconf-crypto-types 2108 A.7. 06 to 07 2110 * Removed a "require-instance false" 2111 * Clarified some description statements 2113 * Improved the keystore-usage examples 2115 A.8. 07 to 08 2117 * Added "local-definition" containers to avoid posibility of the 2118 action/notification statements being under a "case" statement. 2120 * Updated copyright date, boilerplate template, affiliation, folding 2121 algorithm, and reformatted the YANG module. 2123 A.9. 08 to 09 2125 * Added a 'description' statement to the 'must' in the /keystore/ 2126 asymmetric-key node explaining that the descendent values may 2127 exist in only, and that implementation MUST assert 2128 that the values are either configured or that they exist in 2129 . 2131 * Copied above 'must' statement (and description) into the local-or- 2132 keystore-asymmetric-key-grouping, local-or-keystore-asymmetric- 2133 key-with-certs-grouping, and local-or-keystore-end-entity-cert- 2134 with-key-grouping statements. 2136 A.10. 09 to 10 2138 * Updated draft title to match new truststore draft title 2140 * Moved everything under a top-level 'grouping' to enable use in 2141 other contexts. 2143 * Renamed feature from 'local-keys-supported' to 'local-definitions- 2144 supported' (same name used in truststore) 2146 * Removed the either-all-or-none 'must' expressions for the key's 2147 3-tuple values (since the values are now 'mandatory true' in 2148 crypto-types) 2150 * Example updated to reflect 'mandatory true' change in crypto-types 2151 draft 2153 A.11. 10 to 11 2155 * Replaced typedef asymmetric-key-certificate-ref with grouping 2156 asymmetric-key-certificate-ref-grouping. 2158 * Added feature feature 'key-generation'. 2160 * Cloned groupings symmetric-key-grouping, asymmetric-key-pair- 2161 grouping, asymmetric-key-pair-with-cert-grouping, and asymmetric- 2162 key-pair-with-certs-grouping from crypto-keys, augmenting into 2163 each new case statements for values that have been encrypted by 2164 other keys in the keystore. Refactored keystore model to use 2165 these groupings. 2167 * Added new 'symmetric-keys' lists, as a sibling to the existing 2168 'asymmetric-keys' list. 2170 * Added RPCs (not actions) 'generate-symmetric-key' and 'generate- 2171 asymmetric-key' to *return* a (potentially encrypted) key. 2173 A.12. 11 to 12 2175 * Updated to reflect crypto-type's draft using enumerations over 2176 identities. 2178 * Added examples for the 'generate-symmetric-key' and 'generate- 2179 asymmetric-key' RPCs. 2181 * Updated the Introduction section. 2183 A.13. 12 to 13 2185 * Updated examples to incorporate new "key-format" identities. 2187 * Made the two "generate-*-key" RPCs be "action" statements instead. 2189 A.14. 13 to 14 2191 * Updated YANG module and examples to incorporate the new 2192 iana-*-algorithm modules in the crypto-types draft.. 2194 A.15. 14 to 15 2196 * Added new "Support for Built-in Keys" section. 2198 * Added 'must' expressions asserting that the 'key-format' leaf 2199 whenever an encrypted key is specified. 2201 * Added local-or-keystore-symmetric-key-grouping for PSK support. 2203 A.16. 15 to 16 2205 * Moved the generate key actions to ietf-crypt-types as RPCs, which 2206 are augmented by ietf-keystore to support encrypted keys. 2207 Examples updated accordingly. 2209 * Added a SSH certificate-based key (RFC 6187) and a raw private key 2210 to the example instance document (partly so they could be 2211 referenced by examples in the SSH and TLS client/server drafts. 2213 A.17. 16 to 17 2215 * Removed augments to the "generate-symmetric-key" and "generate- 2216 asymmetric-key" groupings. 2218 * Removed "generate-symmetric-key" and "generate-asymmetric-key" 2219 examples. 2221 * Removed the "algorithm" nodes from remaining examples. 2223 * Updated the "Support for Built-in Keys" section. 2225 * Added new section "Encrypting Keys in Configuration". 2227 * Added a "Note to Reviewers" note to first page. 2229 A.18. 17 to 18 2231 * Removed dangling/unnecessary ref to RFC 8342. 2233 * r/MUST/SHOULD/ wrt strength of keys being configured over 2234 transports. 2236 * Added an example for the "certificate-expiration" notification. 2238 * Clarified that OS MAY have a multiplicity of underlying keystores 2239 and/or HSMs. 2241 * Clarified expected behavior for "built-in" keys in 2243 * Clarified the "Migrating Configuration to Another Server" section. 2245 * Expanded "Data Model Overview section(s) [remove "wall" of tree 2246 diagrams]. 2248 * Updated the Security Considerations section. 2250 A.19. 18 to 19 2252 * Updated examples to reflect new "cleartext-" prefix in the crypto- 2253 types draft. 2255 A.20. 19 to 20 2256 * Addressed SecDir comments from Magnus Nystroem and Sandra Murphy. 2258 A.21. 20 to 21 2260 * Added a "Unconstrained Private Key Usage" Security Consideration 2261 to address concern raised by SecDir. 2263 * (Editorial) Removed the output of "grouping" statements in the 2264 tree diagrams for the "ietf-keystore" and "ex-keystore-usage" 2265 modules. 2267 * Addressed comments raised by YANG Doctor. 2269 A.22. 21 to 22 2271 * Added prefixes to 'path' statements per trust-anchors/issues/1 2273 * Renamed feature "keystore-supported" to "central-keystore- 2274 supported". 2276 * Associated with above, generally moved text to refer to a 2277 "central" keystore. 2279 * Aligned modules with `pyang -f` formatting. 2281 * Fixed nits found by YANG Doctor reviews. 2283 Acknowledgements 2285 The authors would like to thank for following for lively discussions 2286 on list and in the halls (ordered by first name): Alan Luchuk, Andy 2287 Bierman, Benoit Claise, Bert Wijnen, Balazs Kovacs, David Lamparter, 2288 Eric Voit, Ladislav Lhotka, Liang Xia, Juergen Schoenwaelder, Mahesh 2289 Jethanandani, Magnus Nystroem, Martin Bjoerklund, Mehmet Ersue, Phil 2290 Shafer, Radek Krejci, Ramkumar Dhanapal, Reshad Rahman, Sandra 2291 Murphy, Sean Turner, and Tom Petch. 2293 Author's Address 2295 Kent Watsen 2296 Watsen Networks 2298 Email: kent+ietf@watsen.net