idnits 2.17.1 draft-ietf-netconf-keystore-18.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 505 has weird spacing: '...d-value bin...' == Line 511 has weird spacing: '...on-date yan...' == Line 515 has weird spacing: '...sr-info ct:...' == Line 517 has weird spacing: '...request ct:...' == Line 535 has weird spacing: '...d-value bin...' == (10 more instances...) -- The document date (8 July 2020) is 1387 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-15 == Outdated reference: A later version (-20) exists of draft-ietf-netconf-http-client-server-03 == Outdated reference: A later version (-35) exists of draft-ietf-netconf-keystore-17 == Outdated reference: A later version (-36) exists of draft-ietf-netconf-netconf-client-server-19 == Outdated reference: A later version (-36) exists of draft-ietf-netconf-restconf-client-server-19 == Outdated reference: A later version (-40) exists of draft-ietf-netconf-ssh-client-server-19 == Outdated reference: A later version (-26) exists of draft-ietf-netconf-tcp-client-server-06 == Outdated reference: A later version (-41) exists of draft-ietf-netconf-tls-client-server-19 == Outdated reference: A later version (-28) exists of draft-ietf-netconf-trust-anchors-10 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 8 July 2020 5 Expires: 9 January 2021 7 A YANG Data Model for a Keystore 8 draft-ietf-netconf-keystore-18 10 Abstract 12 This document defines a YANG 1.1 module called "ietf-keystore" that 13 enables centralized configuration of both symmetric and asymmetric 14 keys. The secret value for both key types may be encrypted. 15 Asymmetric keys may be associated with certificates. Notifications 16 are sent when certificates are about to expire. 18 Editorial Note (To be removed by RFC Editor) 20 This draft contains placeholder values that need to be replaced with 21 finalized values at the time of publication. This note summarizes 22 all of the substitutions that are needed. No other RFC Editor 23 instructions are specified elsewhere in this document. 25 Artwork in this document contains shorthand references to drafts in 26 progress. Please apply the following replacements: 28 * "AAAA" --> the assigned RFC value for draft-ietf-netconf-crypto- 29 types 31 * "CCCC" --> the assigned RFC value for this draft 33 Artwork in this document contains placeholder values for the date of 34 publication of this draft. Please apply the following replacement: 36 * "2020-07-08" --> 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 9 January 2021. 59 Copyright Notice 61 Copyright (c) 2020 IETF Trust and the persons identified as the 62 document authors. All rights reserved. 64 This document is subject to BCP 78 and the IETF Trust's Legal 65 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 66 license-info) in effect on the date of publication of this document. 67 Please review these documents carefully, as they describe your rights 68 and restrictions with respect to this document. Code Components 69 extracted from this document must include Simplified BSD License text 70 as described in Section 4.e of the Trust Legal Provisions and are 71 provided without warranty as described in the Simplified BSD License. 73 Table of Contents 75 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 76 1.1. Relation to other RFCs . . . . . . . . . . . . . . . . . 4 77 1.2. Specification Language . . . . . . . . . . . . . . . . . 5 78 1.3. Adherence to the NMDA . . . . . . . . . . . . . . . . . . 5 79 2. The "ietf-keystore" Module . . . . . . . . . . . . . . . . . 5 80 2.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 5 81 2.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 12 82 2.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 23 83 3. Support for Built-in Keys . . . . . . . . . . . . . . . . . . 31 84 4. Encrypting Keys in Configuration . . . . . . . . . . . . . . 34 85 5. Security Considerations . . . . . . . . . . . . . . . . . . . 38 86 5.1. Data at Rest . . . . . . . . . . . . . . . . . . . . . . 38 87 5.2. The "ietf-keystore" YANG Module . . . . . . . . . . . . . 38 88 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 39 89 6.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 39 90 6.2. The YANG Module Names Registry . . . . . . . . . . . . . 39 91 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 39 92 7.1. Normative References . . . . . . . . . . . . . . . . . . 39 93 7.2. Informative References . . . . . . . . . . . . . . . . . 40 94 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 42 95 A.1. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 42 96 A.2. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 42 97 A.3. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 42 98 A.4. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 42 99 A.5. 04 to 05 . . . . . . . . . . . . . . . . . . . . . . . . 43 100 A.6. 05 to 06 . . . . . . . . . . . . . . . . . . . . . . . . 43 101 A.7. 06 to 07 . . . . . . . . . . . . . . . . . . . . . . . . 43 102 A.8. 07 to 08 . . . . . . . . . . . . . . . . . . . . . . . . 43 103 A.9. 08 to 09 . . . . . . . . . . . . . . . . . . . . . . . . 43 104 A.10. 09 to 10 . . . . . . . . . . . . . . . . . . . . . . . . 44 105 A.11. 10 to 11 . . . . . . . . . . . . . . . . . . . . . . . . 44 106 A.12. 11 to 12 . . . . . . . . . . . . . . . . . . . . . . . . 44 107 A.13. 12 to 13 . . . . . . . . . . . . . . . . . . . . . . . . 45 108 A.14. 13 to 14 . . . . . . . . . . . . . . . . . . . . . . . . 45 109 A.15. 14 to 15 . . . . . . . . . . . . . . . . . . . . . . . . 45 110 A.16. 15 to 16 . . . . . . . . . . . . . . . . . . . . . . . . 45 111 A.17. 16 to 17 . . . . . . . . . . . . . . . . . . . . . . . . 45 112 A.18. 17 to 18 . . . . . . . . . . . . . . . . . . . . . . . . 46 113 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 46 114 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 46 116 1. Introduction 118 This document defines a YANG 1.1 [RFC7950] module called "ietf- 119 keystore" that enables centralized configuration of both symmetric 120 and asymmetric keys. The secret value for both key types may be 121 encrypted. Asymmetric keys may be associated with certificates. 122 Notifications are sent when certificates are about to expire. 124 The "ietf-keystore" module defines many "grouping" statements 125 intended for use by other modules that may import it. For instance, 126 there are groupings that defined enabling a key to be either 127 configured locally (within the defining data model) or be a reference 128 to a key in the Keystore. 130 Special consideration has been given for systems that have 131 cryptographic hardware, such as a Trusted Protection Module (TPM). 132 These systems are unique in that the cryptographic hardware hides the 133 secret key values. To support such hardware, symmetric keys may have 134 the value "hidden-key" and asymmetric keys may have the value 135 "hidden-private-key". While how such keys are created or destroyed 136 is outside the scope of this document, the Keystore can contain 137 entries for such keys, enabling them to be referenced by other 138 configuration elements. 140 It is not required that a system has an operating system level 141 keystore utility, with or without HSM backing, to implement this 142 module. It is also possible that a system implementing the module to 143 possess a multiplicity of operating system level keystore utilities 144 and/or a multiplicity of HSMs. 146 1.1. Relation to other RFCs 148 This document presents one or more YANG modules [RFC7950] that are 149 part of a collection of RFCs that work together to define 150 configuration modules for clients and servers of both the NETCONF 151 [RFC6241] and RESTCONF [RFC8040] protocols. 153 The modules have been defined in a modular fashion to enable their 154 use by other efforts, some of which are known to be in progress at 155 the time of this writing, with many more expected to be defined in 156 time. 158 The relationship between the various RFCs in the collection is 159 presented in the below diagram. The labels in the diagram represent 160 the primary purpose provided by each RFC. Links the each RFC are 161 provided below the diagram. 163 crypto-types 164 ^ ^ 165 / \ 166 / \ 167 truststore keystore 168 ^ ^ ^ ^ 169 | +---------+ | | 170 | | | | 171 | +------------+ | 172 tcp-client-server | / | | 173 ^ ^ ssh-client-server | | 174 | | ^ tls-client-server 175 | | | ^ ^ http-client-server 176 | | | | | ^ 177 | | | +-----+ +---------+ | 178 | | | | | | 179 | +-----------|--------|--------------+ | | 180 | | | | | | 181 +-----------+ | | | | | 182 | | | | | | 183 | | | | | | 184 netconf-client-server restconf-client-server 186 +=======================+===========================================+ 187 | Label in Diagram | Originating RFC | 188 +=======================+===========================================+ 189 | crypto-types | [I-D.ietf-netconf-crypto-types] | 190 +-----------------------+-------------------------------------------+ 191 | truststore | [I-D.ietf-netconf-trust-anchors] | 192 +-----------------------+-------------------------------------------+ 193 | keystore | [I-D.ietf-netconf-keystore] | 194 +-----------------------+-------------------------------------------+ 195 | tcp-client-server | [I-D.ietf-netconf-tcp-client-server] | 196 +-----------------------+-------------------------------------------+ 197 | ssh-client-server | [I-D.ietf-netconf-ssh-client-server] | 198 +-----------------------+-------------------------------------------+ 199 | tls-client-server | [I-D.ietf-netconf-tls-client-server] | 200 +-----------------------+-------------------------------------------+ 201 | http-client-server | [I-D.ietf-netconf-http-client-server] | 202 +-----------------------+-------------------------------------------+ 203 | netconf-client-server | [I-D.ietf-netconf-netconf-client-server] | 204 +-----------------------+-------------------------------------------+ 205 |restconf-client-server | [I-D.ietf-netconf-restconf-client-server] | 206 +-----------------------+-------------------------------------------+ 208 Table 1: Label to RFC Mapping 210 1.2. Specification Language 212 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 213 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 214 "OPTIONAL" in this document are to be interpreted as described in BCP 215 14 [RFC2119] [RFC8174] when, and only when, they appear in all 216 capitals, as shown here. 218 1.3. Adherence to the NMDA 220 This document in compliant with Network Management Datastore 221 Architecture (NMDA) [RFC8342]. For instance, keys and associated 222 certificates installed during manufacturing (e.g., for an IDevID 223 [Std-802.1AR-2009] certificate) are expected to appear in 224 (see Section 3). 226 2. The "ietf-keystore" Module 228 This section defines a YANG 1.1 [RFC7950] module that defines a 229 "keystore" and groupings supporting downstream modules to reference 230 the keystore or have locally-defined definitions. 232 2.1. Data Model Overview 233 2.1.1. Features 235 The following diagram lists all the "feature" statements defined in 236 the "ietf-keystore" module: 238 Features: 239 +-- keystore-supported 240 +-- local-definitions-supported 242 2.1.2. Typedefs 244 The following diagram lists the "typedef" statements defined in the 245 "ietf-keystore" module: 247 Typedefs: 248 leafref 249 +-- symmetric-key-ref 250 +-- asymmetric-key-ref 252 Comments: 254 * All of the typedefs defined in the "ietf-keystore" module extend 255 the base "leafref" type defined in [RFC7950]. 257 * The leafrefs refer to symmetric and asymmetric keys in the 258 keystore. These typedefs are provided primarily as an aid to 259 downstream modules that import the "ietf-keystore" module. 261 2.1.3. Groupings 263 The following diagram lists all the "grouping" statements defined in 264 the "ietf-keystore" module: 266 Groupings: 267 +-- encrypted-by-choice-grouping 268 +-- asymmetric-key-certificate-ref-grouping 269 +-- local-or-keystore-symmetric-key-grouping 270 +-- local-or-keystore-asymmetric-key-grouping 271 +-- local-or-keystore-asymmetric-key-with-certs-grouping 272 +-- local-or-keystore-end-entity-cert-with-key-grouping 273 +-- keystore-grouping 275 Each of these groupings are presented in the following subsections. 277 2.1.3.1. The "encrypted-by-choice-grouping" Grouping 279 The following tree diagram [RFC8340] illustrates the "encrypted-by- 280 choice-grouping" grouping: 282 | The grouping's name is intended to be parsed "(encrypted-by)- 283 | (choice-grouping)", not as "(encrypted)-(by- 284 | choice)-(grouping)". 286 grouping encrypted-by-choice-grouping 287 +-- (encrypted-by-choice) 288 +--:(symmetric-key-ref) 289 | +-- symmetric-key-ref? 290 | -> /keystore/symmetric-keys/symmetric-key/name 291 +--:(asymmetric-key-ref) 292 +-- asymmetric-key-ref? 293 -> /keystore/asymmetric-keys/asymmetric-key/name 295 Comments: 297 * This grouping defines a "choice" statement with options to 298 reference either a symmetric or an asymmetric key configured in 299 the keystore. 301 2.1.3.2. The "asymmetric-key-certificate-ref-grouping" Grouping 303 The following tree diagram [RFC8340] illustrates the "asymmetric-key- 304 certificate-ref-grouping" grouping: 306 grouping asymmetric-key-certificate-ref-grouping 307 +-- asymmetric-key? ks:asymmetric-key-ref 308 +-- certificate? leafref 310 Comments: 312 * This grouping defines a reference to a certificate in two parts: 313 the first being the name of the asymmetric key the certificate is 314 associated with, and the second being the name of the certificate 315 itself. 317 2.1.3.3. The "local-or-keystore-symmetric-key-grouping" Grouping 319 The following tree diagram [RFC8340] illustrates the "local-or- 320 keystore-symmetric-key-grouping" grouping: 322 grouping local-or-keystore-symmetric-key-grouping 323 +-- (local-or-keystore) 324 +--:(local) {local-definitions-supported}? 325 | +-- local-definition 326 | +---u ct:symmetric-key-grouping 327 +--:(keystore) {keystore-supported}? 328 +-- keystore-reference? ks:symmetric-key-ref 330 Comments: 332 * The "local-or-keystore-symmetric-key-grouping" grouping is 333 provided soley as convenience to downstream modules that wish to 334 offer an option as to if an symmetric key is defined locally or as 335 a reference to a symmetric key in the keystore. 337 * A "choice" statement is used to expose the various options. Each 338 option is enabled by a "feature" statement. Additional "case" 339 statements MAY be augmented in if, e.g., there is a need to 340 reference a symmetric key in an alternate location. 342 * For the "local-definition" option, the defintion uses the 343 "symmetric-key-grouping" grouping discussed in Section 2.1.3.2 of 344 [I-D.ietf-netconf-crypto-types]. 346 * For the "keystore" option, the "keystore-reference" is an instance 347 of the "symmetric-key-ref" discussed in Section 2.1.2. 349 2.1.3.4. The "local-or-keystore-asymmetric-key-grouping" Grouping 351 The following tree diagram [RFC8340] illustrates the "local-or- 352 keystore-asymmetric-key-grouping" grouping: 354 grouping local-or-keystore-asymmetric-key-grouping 355 +-- (local-or-keystore) 356 +--:(local) {local-definitions-supported}? 357 | +-- local-definition 358 | +---u ct:asymmetric-key-pair-grouping 359 +--:(keystore) {keystore-supported}? 360 +-- keystore-reference? ks:asymmetric-key-ref 362 Comments: 364 * The "local-or-keystore-asymmetric-key-grouping" grouping is 365 provided soley as convenience to downstream modules that wish to 366 offer an option as to if an asymmetric key is defined locally or 367 as a reference to a asymmetric key in the keystore. 369 * A "choice" statement is used to expose the various options. Each 370 option is enabled by a "feature" statement. Additional "case" 371 statements MAY be augmented in if, e.g., there is a need to 372 reference a asymmetric key in an alternate location. 374 * For the "local-definition" option, the defintion uses the 375 "asymmetric-key-pair-grouping" grouping discussed in 376 Section 2.1.3.4 of [I-D.ietf-netconf-crypto-types]. 378 * For the "keystore" option, the "keystore-reference" is an instance 379 of the "asymmetric-key-ref" typedef discussed in Section 2.1.2. 381 2.1.3.5. The "local-or-keystore-asymmetric-key-with-certs-grouping" 382 Grouping 384 The following tree diagram [RFC8340] illustrates the "local-or- 385 keystore-asymmetric-key-with-certs-grouping" grouping: 387 grouping local-or-keystore-asymmetric-key-with-certs-grouping 388 +-- (local-or-keystore) 389 +--:(local) {local-definitions-supported}? 390 | +-- local-definition 391 | +---u ct:asymmetric-key-pair-with-certs-grouping 392 +--:(keystore) {keystore-supported}? 393 +-- keystore-reference? ks:asymmetric-key-ref 395 Comments: 397 * The "local-or-keystore-asymmetric-key-with-certs-grouping" 398 grouping is provided soley as convenience to downstream modules 399 that wish to offer an option as to if an asymmetric key is defined 400 locally or as a reference to a asymmetric key in the keystore. 402 * A "choice" statement is used to expose the various options. Each 403 option is enabled by a "feature" statement. Additional "case" 404 statements MAY be augmented in if, e.g., there is a need to 405 reference a asymmetric key in an alternate location. 407 * For the "local-definition" option, the defintion uses the 408 "asymmetric-key-pair-with-certs-grouping" grouping discussed in 409 Section 2.1.3.10 of [I-D.ietf-netconf-crypto-types]. 411 * For the "keystore" option, the "keystore-reference" is an instance 412 of the "asymmetric-key-ref" typedef discussed in Section 2.1.2. 414 2.1.3.6. The "local-or-keystore-end-entity-cert-with-key-grouping" 415 Grouping 417 The following tree diagram [RFC8340] illustrates the "local-or- 418 keystore-end-entity-cert-with-key-grouping" grouping: 420 grouping local-or-keystore-end-entity-cert-with-key-grouping 421 +-- (local-or-keystore) 422 +--:(local) {local-definitions-supported}? 423 | +-- local-definition 424 | +---u ct:asymmetric-key-pair-with-cert-grouping 425 +--:(keystore) {keystore-supported}? 426 +-- keystore-reference 427 +---u asymmetric-key-certificate-ref-grouping 429 Comments: 431 * The "local-or-keystore-end-entity-cert-with-key-grouping" grouping 432 is provided soley as convenience to downstream modules that wish 433 to offer an option as to if an symmetric key is defined locally or 434 as a reference to a symmetric key in the keystore. 436 * A "choice" statement is used to expose the various options. Each 437 option is enabled by a "feature" statement. Additional "case" 438 statements MAY be augmented in if, e.g., there is a need to 439 reference a symmetric key in an alternate location. 441 * For the "local-definition" option, the defintion uses the 442 "asymmetric-key-pair-with-certs-grouping" grouping discussed in 443 Section 2.1.3.10 of [I-D.ietf-netconf-crypto-types]. 445 * For the "keystore" option, the "keystore-reference" uses the 446 "asymmetric-key-certificate-ref-grouping" grouping discussed in 447 Section 2.1.3.2. 449 2.1.3.7. The "keystore-grouping" Grouping 451 The following tree diagram [RFC8340] illustrates the "keystore- 452 grouping" grouping: 454 grouping keystore-grouping 455 +-- asymmetric-keys 456 | +-- asymmetric-key* [name] 457 | +-- name? string 458 | +---u ct:asymmetric-key-pair-with-certs-grouping 459 +-- symmetric-keys 460 +-- symmetric-key* [name] 461 +-- name? string 462 +---u ct:symmetric-key-grouping 464 Comments: 466 * The "keystore-grouping" grouping is defines a keystore instance as 467 being composed of symmetric and asymmetric keys. The stucture for 468 the symmetric and asymmetric keys is essentially the same, being a 469 "list" inside a "container". 471 * For asymmetric keys, each "asymmetric-key" uses the "asymmetric- 472 key-pair-with-certs-grouping" grouping discussed Section 2.1.3.10 473 of [I-D.ietf-netconf-crypto-types]. 475 * For symmetric keys, each "symmetric-key" uses the "symmetric-key- 476 grouping" grouping discussed Section 2.1.3.2 of 477 [I-D.ietf-netconf-crypto-types]. 479 2.1.4. Protocol-accessible Nodes 481 The following diagram lists all the protocol-accessible nodes defined 482 in the "ietf-keystore" module: 484 module: ietf-keystore 485 +--rw keystore 486 +--rw asymmetric-keys 487 | +--rw asymmetric-key* [name] 488 | +--rw name string 489 | +--rw public-key-format identityref 490 | +--rw public-key binary 491 | +--rw private-key-format? identityref 492 | +--rw (private-key-type) 493 | | +--:(private-key) 494 | | | +--rw private-key? binary 495 | | +--:(hidden-private-key) 496 | | | +--rw hidden-private-key? empty 497 | | +--:(encrypted-private-key) 498 | | +--rw encrypted-private-key 499 | | +--rw encrypted-by 500 | | | +--rw (encrypted-by-choice) 501 | | | +--:(symmetric-key-ref) 502 | | | | +--rw symmetric-key-ref? leafref 503 | | | +--:(asymmetric-key-ref) 504 | | | +--rw asymmetric-key-ref? leafref 505 | | +--rw encrypted-value binary 506 | +--rw certificates 507 | | +--rw certificate* [name] 508 | | +--rw name string 509 | | +--rw cert-data end-entity-cert-cms 510 | | +---n certificate-expiration 511 | | +-- expiration-date yang:date-and-time 512 | +---x generate-certificate-signing-request 513 | {certificate-signing-request-generation}? 514 | +---w input 515 | | +---w csr-info ct:csr-info 516 | +--ro output 517 | +--ro certificate-signing-request ct:csr 518 +--rw symmetric-keys 519 +--rw symmetric-key* [name] 520 +--rw name string 521 +--rw key-format? identityref 522 +--rw (key-type) 523 +--:(key) 524 | +--rw key? binary 525 +--:(hidden-key) 526 | +--rw hidden-key? empty 527 +--:(encrypted-key) 528 +--rw encrypted-key 529 +--rw encrypted-by 530 | +--rw (encrypted-by-choice) 531 | +--:(symmetric-key-ref) 532 | | +--rw symmetric-key-ref? leafref 533 | +--:(asymmetric-key-ref) 534 | +--rw asymmetric-key-ref? leafref 535 +--rw encrypted-value binary 537 Comments: 539 * Protocol-accessible nodes are those nodes that are accessible when 540 the module is "implemented", as described in Section 5.6.5 of 541 [RFC7950]. 543 * For the "ietf-keystore" module, the protcol-accessible nodes are 544 an instance of the "keystore-grouping" discussed in 545 Section 2.1.3.7 grouping. Note that, in this diagram, all the 546 used groupings have been expanded, enabling the keystore's full 547 structure to be seen. 549 * The reason for why "keystore-grouping" exists separate from the 550 protocol-accessible nodes definition is so as to enable instances 551 of the keystore to be instantiated in other locations, as may be 552 needed or desired by some modules. 554 2.2. Example Usage 556 The examples in this section are encoded using XML, such as might be 557 the case when using the NETCONF protocol. Other encodings MAY be 558 used, such as JSON when using the RESTCONF protocol. 560 2.2.1. A Keystore Instance 562 The following example illustrates keys in . Please see 563 Section 3 for an example illustrating built-in values in 564 . 566 =============== NOTE: '\' line wrapping per RFC 8792 ================ 568 571 572 573 cleartext-symmetric-key 574 ct:octet-string-key-format 575 base64encodedvalue== 576 577 578 hidden-symmetric-key 579 580 581 582 encrypted-symmetric-key 583 584 ct:encrypted-one-symmetric-key-format 585 586 587 588 hidden-asymmetric-key 590 591 base64encodedvalue== 592 593 594 596 597 598 ssh-rsa-key 599 600 ct:ssh-public-key-format 601 602 base64encodedvalue== 603 604 ct:rsa-private-key-format 605 606 base64encodedvalue== 607 608 609 ssh-rsa-key-with-cert 610 611 ct:subject-public-key-info-format 612 613 base64encodedvalue== 614 615 ct:rsa-private-key-format 616 617 base64encodedvalue== 618 619 620 ex-rsa-cert2 621 base64encodedvalue== 622 623 624 625 626 raw-private-key 627 628 ct:subject-public-key-info-format 629 630 base64encodedvalue== 631 632 ct:rsa-private-key-format 633 634 base64encodedvalue== 635 636 637 rsa-asymmetric-key 638 639 ct:subject-public-key-info-format 640 641 base64encodedvalue== 642 643 ct:rsa-private-key-format 644 645 base64encodedvalue== 646 647 648 ex-rsa-cert 649 base64encodedvalue== 650 651 652 653 654 ec-asymmetric-key 655 656 ct:subject-public-key-info-format 657 658 base64encodedvalue== 659 660 ct:ec-private-key-format 661 662 base64encodedvalue== 663 664 665 ex-ec-cert 666 base64encodedvalue== 667 668 669 670 671 hidden-asymmetric-key 672 673 ct:subject-public-key-info-format 674 675 base64encodedvalue== 676 677 678 679 builtin-idevid-cert 680 base64encodedvalue== 681 682 683 my-ldevid-cert 684 base64encodedvalue== 685 686 687 688 689 encrypted-asymmetric-key 690 691 ct:subject-public-key-info-format 692 693 base64encodedvalue== 694 695 ct:encrypted-one-asymmetric-key-format 696 697 698 699 encrypted-symmetric-key 701 702 base64encodedvalue== 703 705 706 707 709 2.2.2. A Certificate Expiration Notification 711 The following example illustrates a "certificate-expiration" 712 notification for a certificate associated with a key configured in 713 the keystore. 715 =============== NOTE: '\' line wrapping per RFC 8792 ================ 717 719 2018-05-25T00:01:00Z 720 721 722 723 hidden-asymmetric-key 724 725 726 my-ldevid-cert 727 728 2018-08-05T14:18:53-05:00 730 731 732 733 734 735 736 738 2.2.3. The "Local or Keystore" Groupings 740 This section illustrates the various "local-or-keystore" groupings 741 defined in the "ietf-keystore" module, specifically the "local-or- 742 keystore-symmetric-key-grouping" (Section 2.1.3.3), "local-or- 743 keystore-asymmetric-key-grouping" (Section 2.1.3.4), "local-or- 744 keystore-asymmetric-key-with-certs-grouping" (Section 2.1.3.5), and 745 "local-or-keystore-end-entity-cert-with-key-grouping" 746 (Section 2.1.3.6) groupings. 748 The following non-normative module is defined to illustrate these 749 groupings: 751 module ex-keystore-usage { 752 yang-version 1.1; 754 namespace "http://example.com/ns/example-keystore-usage"; 755 prefix "eku"; 757 import ietf-keystore { 758 prefix ks; 759 reference 760 "RFC CCCC: A YANG Data Model for a Keystore"; 761 } 763 organization 764 "Example Corporation"; 766 contact 767 "Author: YANG Designer "; 769 description 770 "This module illustrates notable groupings defined in 771 the 'ietf-keystore' module."; 773 revision "2020-07-08" { 774 description 775 "Initial version"; 776 reference 777 "RFC CCCC: A YANG Data Model for a Keystore"; 778 } 780 container keystore-usage { 781 description 782 "An illustration of the various keystore groupings."; 784 list symmetric-key { 785 key name; 786 leaf name { 787 type string; 788 description 789 "An arbitrary name for this key."; 790 } 791 uses ks:local-or-keystore-symmetric-key-grouping; 792 description 793 "An symmetric key that may be configured locally or be a 794 reference to a symmetric key in the keystore."; 795 } 797 list asymmetric-key { 798 key name; 799 leaf name { 800 type string; 801 description 802 "An arbitrary name for this key."; 803 } 804 uses ks:local-or-keystore-asymmetric-key-grouping; 805 description 806 "An asymmetric key, with no certs, that may be configured 807 locally or be a reference to an asymmetric key in the 808 keystore. The intent is to reference just the asymmetric 809 key, not any certificates that may also be associated 810 with the asymmetric key."; 811 } 813 list asymmetric-key-with-certs { 814 key name; 815 leaf name { 816 type string; 817 description 818 "An arbitrary name for this key."; 819 } 820 uses ks:local-or-keystore-asymmetric-key-with-certs-grouping; 821 description 822 "An asymmetric key and its associated certs, that may be 823 configured locally or be a reference to an asymmetric key 824 (and its associated certs) in the keystore."; 825 } 827 list end-entity-cert-with-key { 828 key name; 829 leaf name { 830 type string; 831 description 832 "An arbitrary name for this key."; 833 } 834 uses ks:local-or-keystore-end-entity-cert-with-key-grouping; 835 description 836 "An end-entity certificate, and its associated private key, 837 that may be configured locally or be a reference to a 838 specific certificate (and its associated private key) in 839 the keystore."; 840 } 841 } 843 } 845 The tree diagram [RFC8340] for this example module follows: 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 | | +--:(key) 857 | | | +--rw key? binary 858 | | +--:(hidden-key) 859 | | | +--rw hidden-key? empty 860 | | +--:(encrypted-key) 861 | | +--rw encrypted-key 862 | | +--rw encrypted-by 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 | | +--:(private-key) 876 | | | +--rw private-key? binary 877 | | +--:(hidden-private-key) 878 | | | +--rw hidden-private-key? empty 879 | | +--:(encrypted-private-key) 880 | | +--rw encrypted-private-key 881 | | +--rw encrypted-by 882 | | +--rw encrypted-value binary 883 | +--:(keystore) {keystore-supported}? 884 | +--rw keystore-reference? ks:asymmetric-key-ref 885 +--rw asymmetric-key-with-certs* [name] 886 | +--rw name string 887 | +--rw (local-or-keystore) 888 | +--:(local) {local-definitions-supported}? 889 | | +--rw local-definition 890 | | +--rw public-key-format 891 | | | identityref 892 | | +--rw public-key binary 893 | | +--rw private-key-format? 894 | | | identityref 895 | | +--rw (private-key-type) 896 | | | +--:(private-key) 897 | | | | +--rw private-key? binary 898 | | | +--:(hidden-private-key) 899 | | | | +--rw hidden-private-key? empty 900 | | | +--:(encrypted-private-key) 901 | | | +--rw encrypted-private-key 902 | | | +--rw encrypted-by 903 | | | +--rw encrypted-value binary 904 | | +--rw certificates 905 | | | +--rw certificate* [name] 906 | | | +--rw name string 907 | | | +--rw cert-data 908 | | | | end-entity-cert-cms 909 | | | +---n certificate-expiration 910 | | | +-- expiration-date yang:date-and-time 911 | | +---x generate-certificate-signing-request 912 | | {certificate-signing-request-generation}? 913 | | +---w input 914 | | | +---w csr-info ct:csr-info 915 | | +--ro output 916 | | +--ro certificate-signing-request ct:csr 917 | +--:(keystore) {keystore-supported}? 918 | +--rw keystore-reference? ks:asymmetric-key-ref 919 +--rw end-entity-cert-with-key* [name] 920 +--rw name string 921 +--rw (local-or-keystore) 922 +--:(local) {local-definitions-supported}? 923 | +--rw local-definition 924 | +--rw public-key-format 925 | | identityref 926 | +--rw public-key binary 927 | +--rw private-key-format? 928 | | identityref 929 | +--rw (private-key-type) 930 | | +--:(private-key) 931 | | | +--rw private-key? binary 932 | | +--:(hidden-private-key) 933 | | | +--rw hidden-private-key? empty 934 | | +--:(encrypted-private-key) 935 | | +--rw encrypted-private-key 936 | | +--rw encrypted-by 937 | | +--rw encrypted-value binary 938 | +--rw cert-data? 939 | | end-entity-cert-cms 940 | +---n certificate-expiration 941 | | +-- expiration-date yang:date-and-time 942 | +---x generate-certificate-signing-request 943 | {certificate-signing-request-generation}? 944 | +---w input 945 | | +---w csr-info ct:csr-info 946 | +--ro output 947 | +--ro certificate-signing-request ct:csr 948 +--:(keystore) {keystore-supported}? 949 +--rw keystore-reference 950 +--rw asymmetric-key? ks:asymmetric-key-ref 951 +--rw certificate? leafref 953 The following example provides two equivalent instances of each 954 grouping, the first being a reference to a keystore and the second 955 being locally-defined. The instance having a reference to a keystore 956 is consistent with the keystore defined in Section 2.2.1. The two 957 instances are equivalent, as the locally-defined instance example 958 contains the same values defined by the keystore instance referenced 959 by its sibling example. 961 965 966 968 969 example 1a 970 cleartext-symmetric-key 971 973 974 example 1b 975 976 ct:octet-string-key-format 977 base64encodedvalue== 978 979 981 982 984 985 example 2a 986 rsa-asymmetric-key 987 989 990 example 2b 991 992 993 ct:subject-public-key-info-format 994 995 base64encodedvalue== 996 997 ct:rsa-private-key-format 998 999 base64encodedvalue== 1000 1001 1003 1004 1006 1007 example 3a 1008 rsa-asymmetric-key 1009 1011 1012 example 3b 1013 1014 1015 ct:subject-public-key-info-format 1016 1017 base64encodedvalue== 1018 1019 ct:rsa-private-key-format 1020 1021 base64encodedvalue== 1022 1023 1024 a locally-defined cert 1025 base64encodedvalue== 1026 1027 1028 1029 1031 1032 1034 1035 example 4a 1036 1037 rsa-asymmetric-key 1038 ex-rsa-cert 1039 1040 1042 1043 example 4b 1044 1045 1046 ct:subject-public-key-info-format 1047 1048 base64encodedvalue== 1049 1050 ct:rsa-private-key-format 1051 1052 base64encodedvalue== 1053 base64encodedvalue== 1054 1055 1057 1059 2.3. YANG Module 1061 This YANG module has normative references to [RFC8341] and 1062 [I-D.ietf-netconf-crypto-types]. 1064 file "ietf-keystore@2020-07-08.yang" 1066 module ietf-keystore { 1067 yang-version 1.1; 1068 namespace "urn:ietf:params:xml:ns:yang:ietf-keystore"; 1069 prefix ks; 1071 import ietf-netconf-acm { 1072 prefix nacm; 1073 reference 1074 "RFC 8341: Network Configuration Access Control Model"; 1075 } 1077 import ietf-crypto-types { 1078 prefix ct; 1079 reference 1080 "RFC AAAA: YANG Data Types and Groupings for Cryptography"; 1081 } 1083 organization 1084 "IETF NETCONF (Network Configuration) Working Group"; 1086 contact 1087 "WG Web: 1088 WG List: 1089 Author: Kent Watsen "; 1091 description 1092 "This module defines a Keystore to centralize management 1093 of security credentials. 1095 Copyright (c) 2020 IETF Trust and the persons identified 1096 as authors of the code. All rights reserved. 1098 Redistribution and use in source and binary forms, with 1099 or without modification, is permitted pursuant to, and 1100 subject to the license terms contained in, the Simplified 1101 BSD License set forth in Section 4.c of the IETF Trust's 1102 Legal Provisions Relating to IETF Documents 1103 (https://trustee.ietf.org/license-info). 1105 This version of this YANG module is part of RFC CCCC 1106 (https://www.rfc-editor.org/info/rfcCCCC); see the RFC 1107 itself for full legal notices. 1109 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1110 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 1111 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 1112 are to be interpreted as described in BCP 14 (RFC 2119) 1113 (RFC 8174) when, and only when, they appear in all 1114 capitals, as shown here."; 1116 revision 2020-07-08 { 1117 description 1118 "Initial version"; 1119 reference 1120 "RFC CCCC: A YANG Data Model for a Keystore"; 1121 } 1123 /****************/ 1124 /* Features */ 1125 /****************/ 1127 feature keystore-supported { 1128 description 1129 "The 'keystore-supported' feature indicates that the server 1130 supports the Keystore."; 1131 } 1132 feature local-definitions-supported { 1133 description 1134 "The 'local-definitions-supported' feature indicates that the 1135 server supports locally-defined keys."; 1136 } 1138 /****************/ 1139 /* Typedefs */ 1140 /****************/ 1142 typedef symmetric-key-ref { 1143 type leafref { 1144 path "/ks:keystore/ks:symmetric-keys/ks:symmetric-key" 1145 + "/ks:name"; 1146 } 1147 description 1148 "This typedef enables modules to easily define a reference 1149 to a symmetric key stored in the Keystore."; 1150 } 1152 typedef asymmetric-key-ref { 1153 type leafref { 1154 path "/ks:keystore/ks:asymmetric-keys/ks:asymmetric-key" 1155 + "/ks:name"; 1156 } 1157 description 1158 "This typedef enables modules to easily define a reference 1159 to an asymmetric key stored in the Keystore."; 1160 } 1162 /*****************/ 1163 /* Groupings */ 1164 /*****************/ 1166 grouping encrypted-by-choice-grouping { 1167 description 1168 "A grouping that defines a choice enabling references 1169 to other keys."; 1170 choice encrypted-by-choice { 1171 nacm:default-deny-write; 1172 mandatory true; 1173 description 1174 "A choice amongst other symmetric or asymmetric keys."; 1175 case symmetric-key-ref { 1176 leaf symmetric-key-ref { 1177 type leafref { 1178 path "/ks:keystore/ks:symmetric-keys/" 1179 + "ks:symmetric-key/ks:name"; 1181 } 1182 description 1183 "Identifies the symmetric key used to encrypt this key."; 1184 } 1185 } 1186 case asymmetric-key-ref { 1187 leaf asymmetric-key-ref { 1188 type leafref { 1189 path "/ks:keystore/ks:asymmetric-keys/" 1190 + "ks:asymmetric-key/ks:name"; 1191 } 1192 description 1193 "Identifies the asymmetric key used to encrypt this key."; 1194 } 1195 } 1196 } 1197 } 1199 grouping asymmetric-key-certificate-ref-grouping { 1200 description 1201 "This grouping defines a reference to a specific certificate 1202 associated with an asymmetric key stored in the Keystore."; 1203 leaf asymmetric-key { 1204 nacm:default-deny-write; 1205 type ks:asymmetric-key-ref; 1206 must '../certificate'; 1207 description 1208 "A reference to an asymmetric key in the Keystore."; 1209 } 1210 leaf certificate { 1211 nacm:default-deny-write; 1212 type leafref { 1213 path "/ks:keystore/ks:asymmetric-keys/ks:asymmetric-key[ks:" 1214 + "name = current()/../asymmetric-key]/ks:certificates" 1215 + "/ks:certificate/ks:name"; 1216 } 1217 must '../asymmetric-key'; 1218 description 1219 "A reference to a specific certificate of the 1220 asymmetric key in the Keystore."; 1221 } 1222 } 1224 // local-or-keystore-* groupings 1226 grouping local-or-keystore-symmetric-key-grouping { 1227 description 1228 "A grouping that expands to allow the symmetric key to be 1229 either stored locally, within the using data model, or be 1230 a reference to a symmetric key stored in the Keystore."; 1231 choice local-or-keystore { 1232 nacm:default-deny-write; 1233 mandatory true; 1234 description 1235 "A choice between an inlined definition and a definition 1236 that exists in the Keystore."; 1237 case local { 1238 if-feature "local-definitions-supported"; 1239 container local-definition { 1240 description 1241 "Container to hold the local key definition."; 1242 uses ct:symmetric-key-grouping; 1243 } 1244 } 1245 case keystore { 1246 if-feature "keystore-supported"; 1247 leaf keystore-reference { 1248 type ks:symmetric-key-ref; 1249 description 1250 "A reference to an symmetric key that exists in 1251 the Keystore."; 1252 } 1253 } 1254 } 1255 } 1257 grouping local-or-keystore-asymmetric-key-grouping { 1258 description 1259 "A grouping that expands to allow the asymmetric key to be 1260 either stored locally, within the using data model, or be 1261 a reference to an asymmetric key stored in the Keystore."; 1262 choice local-or-keystore { 1263 nacm:default-deny-write; 1264 mandatory true; 1265 case local { 1266 if-feature "local-definitions-supported"; 1267 container local-definition { 1268 description 1269 "Container to hold the local key definition."; 1270 uses ct:asymmetric-key-pair-grouping; 1271 } 1272 } 1273 case keystore { 1274 if-feature "keystore-supported"; 1275 leaf keystore-reference { 1276 type ks:asymmetric-key-ref; 1277 description 1278 "A reference to an asymmetric key that exists in 1279 the Keystore. The intent is to reference just the 1280 asymmetric key without any regard for any certificates 1281 that may be associated with it."; 1282 } 1283 } 1284 description 1285 "A choice between an inlined definition and a definition 1286 that exists in the Keystore."; 1287 } 1288 } 1290 grouping local-or-keystore-asymmetric-key-with-certs-grouping { 1291 description 1292 "A grouping that expands to allow an asymmetric key and its 1293 associated certificates to be either stored locally, within 1294 the using data model, or be a reference to an asymmetric key 1295 (and its associated certificates) stored in the Keystore."; 1296 choice local-or-keystore { 1297 nacm:default-deny-write; 1298 mandatory true; 1299 case local { 1300 if-feature "local-definitions-supported"; 1301 container local-definition { 1302 description 1303 "Container to hold the local key definition."; 1304 uses ct:asymmetric-key-pair-with-certs-grouping; 1305 } 1306 } 1307 case keystore { 1308 if-feature "keystore-supported"; 1309 leaf keystore-reference { 1310 type ks:asymmetric-key-ref; 1311 description 1312 "A reference to an asymmetric-key (and all of its 1313 associated certificates) in the Keystore."; 1314 } 1315 } 1316 description 1317 "A choice between an inlined definition and a definition 1318 that exists in the Keystore."; 1319 } 1320 } 1322 grouping local-or-keystore-end-entity-cert-with-key-grouping { 1323 description 1324 "A grouping that expands to allow an end-entity certificate 1325 (and its associated private key) to be either stored locally, 1326 within the using data model, or be a reference to a specific 1327 certificate in the Keystore."; 1328 choice local-or-keystore { 1329 nacm:default-deny-write; 1330 mandatory true; 1331 case local { 1332 if-feature "local-definitions-supported"; 1333 container local-definition { 1334 description 1335 "Container to hold the local key definition."; 1336 uses ct:asymmetric-key-pair-with-cert-grouping; 1337 } 1338 } 1339 case keystore { 1340 if-feature "keystore-supported"; 1341 container keystore-reference { 1342 uses asymmetric-key-certificate-ref-grouping; 1343 description 1344 "A reference to a specific certificate (and its 1345 associated private key) in the Keystore."; 1346 } 1347 } 1348 description 1349 "A choice between an inlined definition and a definition 1350 that exists in the Keystore."; 1351 } 1352 } 1354 grouping keystore-grouping { 1355 description 1356 "Grouping definition enables use in other contexts. If ever 1357 done, implementations SHOULD augment new 'case' statements 1358 into local-or-keystore 'choice' statements to supply leafrefs 1359 to the new location."; 1360 container asymmetric-keys { 1361 nacm:default-deny-write; 1362 description 1363 "A list of asymmetric keys."; 1364 list asymmetric-key { 1365 key "name"; 1366 description 1367 "An asymmetric key."; 1368 leaf name { 1369 type string; 1370 description 1371 "An arbitrary name for the asymmetric key."; 1373 } 1374 uses ct:asymmetric-key-pair-with-certs-grouping; 1375 } 1376 } 1377 container symmetric-keys { 1378 nacm:default-deny-write; 1379 description 1380 "A list of symmetric keys."; 1381 list symmetric-key { 1382 key "name"; 1383 description 1384 "A symmetric key."; 1385 leaf name { 1386 type string; 1387 description 1388 "An arbitrary name for the symmetric key."; 1389 } 1390 uses ct:symmetric-key-grouping; 1391 } 1392 } 1393 } // grouping keystore-grouping 1395 /*********************************/ 1396 /* Protocol accessible nodes */ 1397 /*********************************/ 1399 container keystore { 1400 description 1401 "The Keystore contains a list of symmetric keys and a list 1402 of asymmetric keys."; 1403 nacm:default-deny-write; 1404 uses keystore-grouping { 1405 augment "symmetric-keys/symmetric-key/key-type/encrypted-key/" 1406 + "encrypted-key/encrypted-by" { 1407 description 1408 "Augments in a choice statement enabling the encrypting 1409 key to be any other symmetric or asymmetric key in the 1410 keystore."; 1411 uses encrypted-by-choice-grouping; 1412 } 1413 augment "asymmetric-keys/asymmetric-key/private-key-type/" 1414 + "encrypted-private-key/encrypted-private-key/" 1415 + "encrypted-by" { 1416 description 1417 "Augments in a choice statement enabling the encrypting 1418 key to be any other symmetric or asymmetric key in the 1419 keystore."; 1420 uses encrypted-by-choice-grouping; 1421 } 1422 } 1423 } 1425 } 1427 1429 3. Support for Built-in Keys 1431 In some implementations, a server may support built-in keys. Built- 1432 in built-in keys MAY be set during the manufacturing process or be 1433 dynamically generated the first time the server is booted or a 1434 particular service (e.g., SSH) is enabled. 1436 The key characteristic of the built-in keys is that they are provided 1437 by the system, as opposed to configuration. As such, they are 1438 present in . The example below illustrates what the 1439 keystore in might look like for a server in its factory 1440 default state. 1442 1446 1447 1448 Manufacturer-Generated Hidden Key 1449 1450 ct:subject-public-key-info-format 1451 1452 base64encodedvalue== 1453 1454 1455 1456 Manufacturer-Generated IDevID Cert 1457 base64encodedvalue== 1458 1459 1460 1461 1462 1463 In order for the built-in keys (and/or their associated built-in 1464 certificates) to be referenced by configuration, the referenced keys 1465 MUST first be copied into . The keys SHOULD be copied into 1466 using the same "key" values, so that the server can bind 1467 the references to the built-in entries. 1469 Built-in "hidden" keys cannot be copied into other parts of the 1470 configuration because their private parts are hidden, and therefore 1471 impossible to replicate. Built-in "encrypted" keys MAY be copied 1472 into other parts of the configuration so long as they maintain their 1473 reference to the other built-in key that encrypted them. 1475 Only the referenced keys need to be copied; that is, the keys in 1476 MAY be a subset of the built-in keys define in 1477 . No keys may be added or changed (with exception to 1478 associating additional certificates to a built-in key); that is, the 1479 keys in MUST be a subset (which includes the whole of the 1480 set) of the built-in keys define in . 1482 A server MUST reject attempts to modify any aspect of built-in keys, 1483 with exception to associating additional certificates to a built-in 1484 key. That these keys are "configured" in is an illusion, 1485 as they are strictly a read-only subset of that which must already 1486 exist in . 1488 The following example illustrates how a single built-in key 1489 definition from the previous example has been propagated to 1490 : 1492 1494 1495 1496 Manufacturer-Generated Hidden Key 1497 1498 ct:subject-public-key-info-format 1499 1500 base64encodedvalue== 1501 1502 1503 1504 Manufacturer-Generated IDevID Cert 1505 base64encodedvalue== 1506 1507 1508 Deployment-Specific LDevID Cert 1509 base64encodedvalue== 1510 1511 1512 1513 1514 1516 After the above configuration is applied, should appear 1517 as follows: 1519 1523 1524 1525 Manufacturer-Generated Hidden Key 1526 1527 ct:subject-public-key-info-format 1528 1529 base64encodedvalue== 1530 1531 1532 1533 Manufacturer-Generated IDevID Cert 1534 base64encodedvalue== 1535 1536 1537 Deployment-Specific LDevID Cert 1538 base64encodedvalue== 1539 1540 1541 1542 1543 1545 4. Encrypting Keys in Configuration 1547 This section describes an approach that enables all the private keys 1548 on a server to be encrypted, such that traditional backup/restore 1549 procedures can be used without concern for keys being compromised 1550 when in transit. 1552 4.1. Root Key 1554 The cornerstone to this solution is the existence of a "root" key 1555 that can be used to encrypt all the other keys. The server MUST be 1556 able to use this key to decrypt the other keys in the configuration. 1558 The root key SHOULD be a hidden key, i.e., one whose private data has 1559 no presence in or (see "hidden-key" and 1560 "hidden-private-key" in "ietf-crypto-types" 1561 [I-D.ietf-netconf-crypto-types]). If the server implementation does 1562 not support hidden keys, then the private data part of key MUST be 1563 protected by access control with access granted only to an 1564 administrator with special access control rights (e.g., an 1565 organization's crypto officer). Given the long lifetime of built-in 1566 keys (see Section 3), built-in keys MUST be hidden. 1568 A hidden root key MAY be either a symmetric key or an asymmetric key. 1569 If the hidden root key is symmetric, then the server MUST provide 1570 APIs enabling other keys (ideally generated by the server) to be 1571 encrypted. If the hidden root key is asymmetric, then the server 1572 SHOULD provide APIs enabling other keys to be both generated and 1573 encrypted by it, but MAY alternatively enable administrators with 1574 special access control rights to generate and encrypt the other keys 1575 themselves, using the hidden key's public part. For practical 1576 reasons, an unhidden root key SHOULD be asymmetric, so that its 1577 public part can be accessed by other administrators without concern. 1579 4.2. Configuring Encrypting Keys 1581 Each time a new key is to be configured, it SHOULD be encrypted by 1582 the root key. 1584 In "ietf-crypto-types" [I-D.ietf-netconf-crypto-types], the format 1585 for an encrypted symmetric key is described by the "encrypted-one- 1586 symmetric-key-format" identity, while the format for an encrypted 1587 asymmetric key is described by the "encrypted-one-asymmetric-key- 1588 format" identity 1590 Ideally, the server implementation provides an API to generate a 1591 symmetric or asymmetric key, and encrypt the generated key using 1592 another key known to the system (e.g., the root key). Thusly 1593 administrators can safely call this API to configure new keys. 1595 In case the server implementation does not provide such an API, then 1596 the generating and encrypting steps MAY be performed outside the 1597 server, e.g., by an administrator with special access control rights. 1599 In either case, the encrypted key can be configured into the Keystore 1600 using either the "encrypted-key" (for symmetric keys) or the 1601 "encrypted-private-key" (for asymmetric keys) nodes. These two nodes 1602 contain both the encrypted value as well as a reference to the other 1603 key in the Keystore that it was encrypted by. 1605 4.3. Migrating Configuration to Another Server 1607 In the case a server's root key is used to encrypt other keys, 1608 migrating the configuration to another server may entail additional 1609 effort, assuming the second server has a different root key than the 1610 first server, in order for the second server to decrypt the other 1611 encrypted keys. 1613 In some deployments, mechanisms outside the scope of this document 1614 may be used to migrate the root key from one server to another. That 1615 said, beware that the ability to do so typically entails having 1616 access to the first server but, in many RMA scenarios, the first 1617 server may no longer be operational. 1619 Another option is to introduce a "shared root" key that acts as a 1620 portable intermediate root key. This shared root key would only need 1621 to be known to an organization's crypto officer. The shared root key 1622 SHOULD be encrypted offline by the crypto officer using each server's 1623 public key, which may be, e.g., in the server's IDevID certificate. 1624 The crypto officer can then safely handoff the encrypted shared key 1625 to other administrators responsible for server installations, 1626 including migrations. In order to migrate configuration from a first 1627 server, an administrator would need to make just a single 1628 modification to the configuration before loading it onto a second 1629 server, which is to replace the shared key's Keystore entry from the 1630 first server (an encrypted key), with the shared key encrypted by the 1631 second server's root key. The following diagram illustrates this 1632 idea: 1634 +-------------+ +---------------+ 1635 | shared key | |shared root key| 1636 |(unencrypted)|-------------------------------> | (encrypted) | 1637 +-------------+ encrypts offline using +---------------+ 1638 ^ each server's root key | 1639 | | 1640 | | 1641 | possesses \o | 1642 +-------------- |\ | 1643 / \ shares with | 1644 crypto +--------------------+ 1645 officer | 1646 | 1647 | 1648 +----------------------+ | +----------------------+ 1649 | server-1 | | | server-2 | 1650 | configuration | | | configuration | 1651 | | | | | 1652 | | | | | 1653 | +----------------+ | | | +----------------+ | 1654 | | root key-1 | | | | | root key-2 | | 1655 | | (hidden) | | | | | (hidden) | | 1656 | +----------------+ | | | +----------------+ | 1657 | ^ | | | ^ | 1658 | | | | | | | 1659 | | | | | | | 1660 | | encrypted | | | | encrypted | 1661 | | by | | | | by | 1662 | | | | | | | 1663 | | | | | | | 1664 | +----------------+ | | | +----------------+ | 1665 | |shared root key | | | | |shared root key | | 1666 | | (encrypted) | | v | | (encrypted) | | 1667 | +----------------+ | | +----------------+ | 1668 | ^ | regular | ^ | 1669 | | | admin | | | 1670 | | | | | | 1671 | | encrypted | \o | | encrypted | 1672 | | by | |\ | | by | 1673 | | | / \ | | | 1674 | | | | | | 1675 | +----------------+ |----------------->| +----------------+ | 1676 | | all other keys | | migrate | | all other keys | | 1677 | | (encrypted) | | configuration | | (encrypted) | | 1678 | +----------------+ | | +----------------+ | 1679 | | | | 1680 +----------------------+ +----------------------+ 1682 5. Security Considerations 1684 5.1. Data at Rest 1686 The YANG module defined in this document defines a mechanism called a 1687 "keystore" that, by its name, suggests that it will protect its 1688 contents from unauthorized disclosure and modification. 1690 Security controls for the API (i.e., data in motion) are discussed in 1691 Section 5.2, but controls for the data at rest cannot be specified by 1692 the YANG module. 1694 In order to satisfy the expectations of a "keystore", it is 1695 RECOMMENDED that implementations ensure that the keystore contents 1696 are encrypted when persisted to non-volatile memory. 1698 5.2. The "ietf-keystore" YANG Module 1700 The YANG module defined in this document is designed to be accessed 1701 via YANG based management protocols, such as NETCONF [RFC6241] and 1702 RESTCONF [RFC8040]. Both of these protocols have mandatory-to- 1703 implement secure transport layers (e.g., SSH, TLS) with mutual 1704 authentication. 1706 The NETCONF access control model (NACM) [RFC8341] provides the means 1707 to restrict access for particular users to a pre-configured subset of 1708 all available protocol operations and content. 1710 None of the readable data nodes defined in this YANG module are 1711 considered sensitive or vulnerable in network environments. The NACM 1712 "default-deny-all" extension has not been set for any data nodes 1713 defined in this module. 1715 | Please be aware that this module uses the "key" and "private- 1716 | key" nodes from the "ietf-crypto-types" module 1717 | [I-D.ietf-netconf-crypto-types], where said nodes have the NACM 1718 | extension "default-deny-all" set, thus preventing unrestricted 1719 | read-access to the cleartext key values. 1721 All of the writable data nodes defined by this module, both in the 1722 "grouping" statements as well as the protocol-accessible "keystore" 1723 instance, may be considered sensitive or vulnerable in some network 1724 environments.. For instance, any modification to a key or reference 1725 to a key may dramatically alter the implemented security policy. For 1726 this reason, the NACM extension "default-deny-write" has been set for 1727 all data nodes defined in this module. 1729 This module does not define any RPCs, actions, or notifications, and 1730 thus the security consideration for such is not provided here. 1732 6. IANA Considerations 1734 6.1. The IETF XML Registry 1736 This document registers one URI in the "ns" subregistry of the IETF 1737 XML Registry [RFC3688]. Following the format in [RFC3688], the 1738 following registration is requested: 1740 URI: urn:ietf:params:xml:ns:yang:ietf-keystore 1741 Registrant Contact: The NETCONF WG of the IETF. 1742 XML: N/A, the requested URI is an XML namespace. 1744 6.2. The YANG Module Names Registry 1746 This document registers one YANG module in the YANG Module Names 1747 registry [RFC6020]. Following the format in [RFC6020], the the 1748 following registration is requested: 1750 name: ietf-keystore 1751 namespace: urn:ietf:params:xml:ns:yang:ietf-keystore 1752 prefix: ks 1753 reference: RFC CCCC 1755 7. References 1757 7.1. Normative References 1759 [I-D.ietf-netconf-crypto-types] 1760 Watsen, K., "Common YANG Data Types for Cryptography", 1761 Work in Progress, Internet-Draft, draft-ietf-netconf- 1762 crypto-types-15, 20 May 2020, 1763 . 1766 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1767 Requirement Levels", BCP 14, RFC 2119, 1768 DOI 10.17487/RFC2119, March 1997, 1769 . 1771 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1772 the Network Configuration Protocol (NETCONF)", RFC 6020, 1773 DOI 10.17487/RFC6020, October 2010, 1774 . 1776 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1777 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1778 . 1780 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 1781 Access Control Model", STD 91, RFC 8341, 1782 DOI 10.17487/RFC8341, March 2018, 1783 . 1785 7.2. Informative References 1787 [I-D.ietf-netconf-http-client-server] 1788 Watsen, K., "YANG Groupings for HTTP Clients and HTTP 1789 Servers", Work in Progress, Internet-Draft, draft-ietf- 1790 netconf-http-client-server-03, 20 May 2020, 1791 . 1794 [I-D.ietf-netconf-keystore] 1795 Watsen, K., "A YANG Data Model for a Keystore", Work in 1796 Progress, Internet-Draft, draft-ietf-netconf-keystore-17, 1797 20 May 2020, . 1800 [I-D.ietf-netconf-netconf-client-server] 1801 Watsen, K., "NETCONF Client and Server Models", Work in 1802 Progress, Internet-Draft, draft-ietf-netconf-netconf- 1803 client-server-19, 20 May 2020, 1804 . 1807 [I-D.ietf-netconf-restconf-client-server] 1808 Watsen, K., "RESTCONF Client and Server Models", Work in 1809 Progress, Internet-Draft, draft-ietf-netconf-restconf- 1810 client-server-19, 20 May 2020, 1811 . 1814 [I-D.ietf-netconf-ssh-client-server] 1815 Watsen, K. and G. Wu, "YANG Groupings for SSH Clients and 1816 SSH Servers", Work in Progress, Internet-Draft, draft- 1817 ietf-netconf-ssh-client-server-19, 20 May 2020, 1818 . 1821 [I-D.ietf-netconf-tcp-client-server] 1822 Watsen, K. and M. Scharf, "YANG Groupings for TCP Clients 1823 and TCP Servers", Work in Progress, Internet-Draft, draft- 1824 ietf-netconf-tcp-client-server-06, 16 June 2020, 1825 . 1828 [I-D.ietf-netconf-tls-client-server] 1829 Watsen, K. and G. Wu, "YANG Groupings for TLS Clients and 1830 TLS Servers", Work in Progress, Internet-Draft, draft- 1831 ietf-netconf-tls-client-server-19, 20 May 2020, 1832 . 1835 [I-D.ietf-netconf-trust-anchors] 1836 Watsen, K., "A YANG Data Model for a Truststore", Work in 1837 Progress, Internet-Draft, draft-ietf-netconf-trust- 1838 anchors-10, 20 May 2020, . 1841 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1842 DOI 10.17487/RFC3688, January 2004, 1843 . 1845 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1846 and A. Bierman, Ed., "Network Configuration Protocol 1847 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1848 . 1850 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1851 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1852 . 1854 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1855 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1856 May 2017, . 1858 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 1859 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 1860 . 1862 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1863 and R. Wilton, "Network Management Datastore Architecture 1864 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 1865 . 1867 [Std-802.1AR-2009] 1868 Group, W. -. H. L. L. P. W., "IEEE Standard for Local and 1869 metropolitan area networks - Secure Device Identity", 1870 December 2009, . 1873 Appendix A. Change Log 1875 This section is to be removed before publishing as an RFC. 1877 A.1. 00 to 01 1879 * Replaced the 'certificate-chain' structures with PKCS#7 1880 structures. (Issue #1) 1882 * Added 'private-key' as a configurable data node, and removed the 1883 'generate-private-key' and 'load-private-key' actions. (Issue #2) 1885 * Moved 'user-auth-credentials' to the ietf-ssh-client module. 1886 (Issues #4 and #5) 1888 A.2. 01 to 02 1890 * Added back 'generate-private-key' action. 1892 * Removed 'RESTRICTED' enum from the 'private-key' leaf type. 1894 * Fixed up a few description statements. 1896 A.3. 02 to 03 1898 * Changed draft's title. 1900 * Added missing references. 1902 * Collapsed sections and levels. 1904 * Added RFC 8174 to Requirements Language Section. 1906 * Renamed 'trusted-certificates' to 'pinned-certificates'. 1908 * Changed 'public-key' from config false to config true. 1910 * Switched 'host-key' from OneAsymmetricKey to definition from RFC 1911 4253. 1913 A.4. 03 to 04 1915 * Added typedefs around leafrefs to common keystore paths 1917 * Now tree diagrams reference ietf-netmod-yang-tree-diagrams 1919 * Removed Design Considerations section 1920 * Moved key and certificate definitions from data tree to groupings 1922 A.5. 04 to 05 1924 * Removed trust anchors (now in their own draft) 1926 * Added back global keystore structure 1928 * Added groupings enabling keys to either be locally defined or a 1929 reference to the keystore. 1931 A.6. 05 to 06 1933 * Added feature "local-keys-supported" 1935 * Added nacm:default-deny-all and nacm:default-deny-write 1937 * Renamed generate-asymmetric-key to generate-hidden-key 1939 * Added an install-hidden-key action 1941 * Moved actions inside fo the "asymmetric-key" container 1943 * Moved some groupings to draft-ietf-netconf-crypto-types 1945 A.7. 06 to 07 1947 * Removed a "require-instance false" 1949 * Clarified some description statements 1951 * Improved the keystore-usage examples 1953 A.8. 07 to 08 1955 * Added "local-definition" containers to avoid posibility of the 1956 action/notification statements being under a "case" statement. 1958 * Updated copyright date, boilerplate template, affiliation, folding 1959 algorithm, and reformatted the YANG module. 1961 A.9. 08 to 09 1963 * Added a 'description' statement to the 'must' in the /keystore/ 1964 asymmetric-key node explaining that the descendent values may 1965 exist in only, and that implementation MUST assert 1966 that the values are either configured or that they exist in 1967 . 1969 * Copied above 'must' statement (and description) into the local-or- 1970 keystore-asymmetric-key-grouping, local-or-keystore-asymmetric- 1971 key-with-certs-grouping, and local-or-keystore-end-entity-cert- 1972 with-key-grouping statements. 1974 A.10. 09 to 10 1976 * Updated draft title to match new truststore draft title 1978 * Moved everything under a top-level 'grouping' to enable use in 1979 other contexts. 1981 * Renamed feature from 'local-keys-supported' to 'local-definitions- 1982 supported' (same name used in truststore) 1984 * Removed the either-all-or-none 'must' expressions for the key's 1985 3-tuple values (since the values are now 'mandatory true' in 1986 crypto-types) 1988 * Example updated to reflect 'mandatory true' change in crypto-types 1989 draft 1991 A.11. 10 to 11 1993 * Replaced typedef asymmetric-key-certificate-ref with grouping 1994 asymmetric-key-certificate-ref-grouping. 1996 * Added feature feature 'key-generation'. 1998 * Cloned groupings symmetric-key-grouping, asymmetric-key-pair- 1999 grouping, asymmetric-key-pair-with-cert-grouping, and asymmetric- 2000 key-pair-with-certs-grouping from crypto-keys, augmenting into 2001 each new case statements for values that have been encrypted by 2002 other keys in the keystore. Refactored keystore model to use 2003 these groupings. 2005 * Added new 'symmetric-keys' lists, as a sibling to the existing 2006 'asymmetric-keys' list. 2008 * Added RPCs (not actions) 'generate-symmetric-key' and 'generate- 2009 asymmetric-key' to *return* a (potentially encrypted) key. 2011 A.12. 11 to 12 2013 * Updated to reflect crypto-type's draft using enumerations over 2014 identities. 2016 * Added examples for the 'generate-symmetric-key' and 'generate- 2017 asymmetric-key' RPCs. 2019 * Updated the Introduction section. 2021 A.13. 12 to 13 2023 * Updated examples to incorporate new "key-format" identities. 2025 * Made the two "generate-*-key" RPCs be "action" statements instead. 2027 A.14. 13 to 14 2029 * Updated YANG module and examples to incorporate the new 2030 iana-*-algorithm modules in the crypto-types draft.. 2032 A.15. 14 to 15 2034 * Added new "Support for Built-in Keys" section. 2036 * Added 'must' expressions asserting that the 'key-format' leaf 2037 whenever an encrypted key is specified. 2039 * Added local-or-keystore-symmetric-key-grouping for PSK support. 2041 A.16. 15 to 16 2043 * Moved the generate key actions to ietf-crypt-types as RPCs, which 2044 are augmented by ietf-keystore to support encrypted keys. 2045 Examples updated accordingly. 2047 * Added a SSH certificate-based key (RFC 6187) and a raw private key 2048 to the example instance document (partly so they could be 2049 referenced by examples in the SSH and TLS client/server drafts. 2051 A.17. 16 to 17 2053 * Removed augments to the "generate-symmetric-key" and "generate- 2054 asymmetric-key" groupings. 2056 * Removed "generate-symmetric-key" and "generate-asymmetric-key" 2057 examples. 2059 * Removed the "algorithm" nodes from remaining examples. 2061 * Updated the "Support for Built-in Keys" section. 2063 * Added new section "Encrypting Keys in Configuration". 2065 * Added a "Note to Reviewers" note to first page. 2067 A.18. 17 to 18 2069 * Removed dangling/unnecessary ref to RFC 8342. 2071 * r/MUST/SHOULD/ wrt strength of keys being configured over 2072 transports. 2074 * Added an example for the "certificate-expiration" notification. 2076 * Clarified that OS MAY have a multiplicity of underlying keystores 2077 and/or HSMs. 2079 * Clarified expected behavior for "built-in" keys in 2081 * Clarified the "Migrating Configuration to Another Server" section. 2083 * Expanded "Data Model Overview section(s) [remove "wall" of tree 2084 diagrams]. 2086 * Updated the Security Considerations section. 2088 Acknowledgements 2090 The authors would like to thank for following for lively discussions 2091 on list and in the halls (ordered by first name): Alan Luchuk, Andy 2092 Bierman, Benoit Claise, Bert Wijnen, Balazs Kovacs, David Lamparter, 2093 Eric Voit, Ladislav Lhotka, Liang Xia, Juergen Schoenwaelder, Mahesh 2094 Jethanandani, Martin Bjorklund, Mehmet Ersue, Phil Shafer, Radek 2095 Krejci, Ramkumar Dhanapal, Reshad Rahman, Sean Turner, and Tom Petch. 2097 Author's Address 2099 Kent Watsen 2100 Watsen Networks 2102 Email: kent+ietf@watsen.net