idnits 2.17.1 draft-ietf-netconf-keystore-17.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 : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([2], [3], [4], [5], [6], [7], [8], [9], [1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 248 has weird spacing: '...on-date yan...' == Line 255 has weird spacing: '...request ct:...' == Line 354 has weird spacing: '...on-date yan...' == Line 361 has weird spacing: '...request ct:...' == Line 386 has weird spacing: '...on-date yan...' == (7 more instances...) -- The document date (May 20, 2020) is 1431 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) -- Looks like a reference, but probably isn't: '1' on line 1662 -- Looks like a reference, but probably isn't: '2' on line 1664 -- Looks like a reference, but probably isn't: '3' on line 1666 -- Looks like a reference, but probably isn't: '4' on line 1668 -- Looks like a reference, but probably isn't: '5' on line 1670 -- Looks like a reference, but probably isn't: '6' on line 1672 -- Looks like a reference, but probably isn't: '7' on line 1674 -- Looks like a reference, but probably isn't: '8' on line 1676 -- Looks like a reference, but probably isn't: '9' on line 1679 == Outdated reference: A later version (-34) exists of draft-ietf-netconf-crypto-types-14 Summary: 1 error (**), 0 flaws (~~), 8 warnings (==), 10 comments (--). 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 May 20, 2020 5 Expires: November 21, 2020 7 A YANG Data Model for a Keystore 8 draft-ietf-netconf-keystore-17 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 o "AAAA" --> the assigned RFC value for draft-ietf-netconf-crypto- 29 types 31 o "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 o "2020-05-20" --> the publication date of this draft 38 The following Appendix section is to be removed prior to publication: 40 o Appendix A. Change Log 42 Note to Reviewers (To be removed by RFC Editor) 44 This document presents a YANG module or modules that is/are part of a 45 collection of drafts that work together to produce the ultimate goal 46 of the NETCONF WG: to define configuration modules for NETCONF client 47 and servers, and RESTCONF client and servers. 49 The relationship between the various drafts in the collection is 50 presented in the below diagram. 52 crypto-types 53 ^ ^ 54 / \ 55 / \ 56 trust-anchors keystore 57 ^ ^ ^ ^ 58 | +---------+ | | 59 | | | | 60 | +------------+ | 61 tcp-client-server | / | | 62 ^ ^ ssh-client-server | | 63 | | ^ tls-client-server 64 | | | ^ ^ http-client-server 65 | | | | | ^ 66 | | | +-----+ +---------+ | 67 | | | | | | 68 | +-----------|--------|--------------+ | | 69 | | | | | | 70 +-----------+ | | | | | 71 | | | | | | 72 | | | | | | 73 netconf-client-server restconf-client-server 75 Full draft names and link to drafts: 77 o draft-ietf-netconf-crypto-types (html [1]) 79 o draft-ietf-netconf-trust-anchors (html [2]) 81 o draft-ietf-netconf-keystore (html [3]) 83 o draft-ietf-netconf-tcp-client-server (html [4]) 85 o draft-ietf-netconf-ssh-client-server (html [5]) 87 o draft-ietf-netconf-tls-client-server (html [6]) 89 o draft-ietf-netconf-http-client-server (html [7]) 91 o draft-ietf-netconf-netconf-client-server (html [8]) 93 o draft-ietf-netconf-restconf-client-server (html [9]) 95 Status of This Memo 97 This Internet-Draft is submitted in full conformance with the 98 provisions of BCP 78 and BCP 79. 100 Internet-Drafts are working documents of the Internet Engineering 101 Task Force (IETF). Note that other groups may also distribute 102 working documents as Internet-Drafts. The list of current Internet- 103 Drafts is at https://datatracker.ietf.org/drafts/current/. 105 Internet-Drafts are draft documents valid for a maximum of six months 106 and may be updated, replaced, or obsoleted by other documents at any 107 time. It is inappropriate to use Internet-Drafts as reference 108 material or to cite them other than as "work in progress." 110 This Internet-Draft will expire on November 21, 2020. 112 Copyright Notice 114 Copyright (c) 2020 IETF Trust and the persons identified as the 115 document authors. All rights reserved. 117 This document is subject to BCP 78 and the IETF Trust's Legal 118 Provisions Relating to IETF Documents 119 (https://trustee.ietf.org/license-info) in effect on the date of 120 publication of this document. Please review these documents 121 carefully, as they describe your rights and restrictions with respect 122 to this document. Code Components extracted from this document must 123 include Simplified BSD License text as described in Section 4.e of 124 the Trust Legal Provisions and are provided without warranty as 125 described in the Simplified BSD License. 127 Table of Contents 129 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 130 2. Requirements Language . . . . . . . . . . . . . . . . . . . . 5 131 3. The Keystore Model . . . . . . . . . . . . . . . . . . . . . 5 132 3.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 5 133 3.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 13 134 3.2.1. A Keystore Instance . . . . . . . . . . . . . . . . . 13 135 3.2.2. Notable Keystore Groupings . . . . . . . . . . . . . 16 136 3.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 19 137 4. Support for Built-in Keys . . . . . . . . . . . . . . . . . . 28 138 5. Encrypting Keys in Configuration . . . . . . . . . . . . . . 31 139 5.1. Root Key . . . . . . . . . . . . . . . . . . . . . . . . 31 140 5.2. Configuring Encrypting Keys . . . . . . . . . . . . . . . 32 141 5.3. Migrating Configuration to Another Server . . . . . . . . 32 142 6. Security Considerations . . . . . . . . . . . . . . . . . . . 33 143 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 34 144 7.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 34 145 7.2. The YANG Module Names Registry . . . . . . . . . . . . . 35 146 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 35 147 8.1. Normative References . . . . . . . . . . . . . . . . . . 35 148 8.2. Informative References . . . . . . . . . . . . . . . . . 35 149 8.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 36 150 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 38 151 A.1. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 38 152 A.2. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 38 153 A.3. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 38 154 A.4. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 38 155 A.5. 04 to 05 . . . . . . . . . . . . . . . . . . . . . . . . 39 156 A.6. 05 to 06 . . . . . . . . . . . . . . . . . . . . . . . . 39 157 A.7. 06 to 07 . . . . . . . . . . . . . . . . . . . . . . . . 39 158 A.8. 07 to 08 . . . . . . . . . . . . . . . . . . . . . . . . 39 159 A.9. 08 to 09 . . . . . . . . . . . . . . . . . . . . . . . . 39 160 A.10. 09 to 10 . . . . . . . . . . . . . . . . . . . . . . . . 40 161 A.11. 10 to 11 . . . . . . . . . . . . . . . . . . . . . . . . 40 162 A.12. 11 to 12 . . . . . . . . . . . . . . . . . . . . . . . . 40 163 A.13. 12 to 13 . . . . . . . . . . . . . . . . . . . . . . . . 41 164 A.14. 13 to 14 . . . . . . . . . . . . . . . . . . . . . . . . 41 165 A.15. 14 to 15 . . . . . . . . . . . . . . . . . . . . . . . . 41 166 A.16. 15 to 16 . . . . . . . . . . . . . . . . . . . . . . . . 41 167 A.17. 16 to 17 . . . . . . . . . . . . . . . . . . . . . . . . 41 168 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 42 169 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 42 171 1. Introduction 173 This document defines a YANG 1.1 [RFC7950] module called "ietf- 174 keystore" that enables centralized configuration of both symmetric 175 and asymmetric keys. The secret value for both key types may be 176 encrypted. Asymmetric keys may be associated with certificates. 177 Notifications are sent when certificates are about to expire. 179 The "ietf-keystore" module defines many "grouping" statements 180 intended for use by other modules that may import it. For instance, 181 there are groupings that defined enabling a key to be either 182 configured locally (within the defining data model) or be a reference 183 to a key in the Keystore. 185 Special consideration has been given for systems that have 186 cryptographic hardware, such as a Trusted Protection Module (TPM). 187 These systems are unique in that the cryptographic hardware hides the 188 secret key values. To support such hardware, symmetric keys may have 189 the value "hidden-key" and asymmetric keys may have the value 190 "hidden-private-key". While how such keys are created or destroyed 191 is outside the scope of this document, the Keystore can contain 192 entries for such keys, enabling them to be referenced by other 193 configuration elements. 195 This document in compliant with Network Management Datastore 196 Architecture (NMDA) [RFC8342]. For instance, keys and associated 197 certificates installed during manufacturing (e.g., for a IDevID 198 [Std-802.1AR-2009] certificate), are expected to appear in 199 (see Section 4). 201 It is not required that a system has an operating system level 202 Keystore utility to implement this module. 204 2. Requirements Language 206 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 207 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 208 "OPTIONAL" in this document are to be interpreted as described in BCP 209 14 [RFC2119] [RFC8174] when, and only when, they appear in all 210 capitals, as shown here. 212 3. The Keystore Model 214 3.1. Tree Diagram 216 This section provides a tree diagrams [RFC8340] for the "ietf- 217 keystore" module that presents both the protocol-accessible 218 "keystore" as well the all the groupings intended for external usage. 220 module: ietf-keystore 221 +--rw keystore 222 +--rw asymmetric-keys 223 | +--rw asymmetric-key* [name] 224 | +--rw name string 225 | +--rw public-key-format identityref 226 | +--rw public-key binary 227 | +--rw private-key-format? identityref 228 | +--rw (private-key-type) 229 | | +--:(private-key) 230 | | | +--rw private-key? binary 231 | | +--:(hidden-private-key) 232 | | | +--rw hidden-private-key? empty 233 | | +--:(encrypted-private-key) 234 | | +--rw encrypted-private-key 235 | | +--rw (key-type) 236 | | | +--:(symmetric-key-ref) 237 | | | | +--rw symmetric-key-ref? leafref 238 | | | | {keystore-supported}? 239 | | | +--:(asymmetric-key-ref) 240 | | | +--rw asymmetric-key-ref? leafref 241 | | | {keystore-supported}? 242 | | +--rw value? binary 243 | +--rw certificates 244 | | +--rw certificate* [name] 245 | | +--rw name string 246 | | +--rw cert end-entity-cert-cms 247 | | +---n certificate-expiration 248 | | +-- expiration-date yang:date-and-time 249 | +---x generate-certificate-signing-request 250 | {certificate-signing-request-generation}? 251 | +---w input 252 | | +---w subject binary 253 | | +---w attributes? binary 254 | +--ro output 255 | +--ro certificate-signing-request ct:csr 256 +--rw symmetric-keys 257 +--rw symmetric-key* [name] 258 +--rw name string 259 +--rw key-format? identityref 260 +--rw (key-type) 261 +--:(key) 262 | +--rw key? binary 263 +--:(hidden-key) 264 | +--rw hidden-key? empty 265 +--:(encrypted-key) 266 +--rw encrypted-key 267 +--rw (key-type) 268 | +--:(symmetric-key-ref) 269 | | +--rw symmetric-key-ref? leafref 270 | | {keystore-supported}? 271 | +--:(asymmetric-key-ref) 272 | +--rw asymmetric-key-ref? leafref 273 | {keystore-supported}? 274 +--rw value? binary 276 grouping key-reference-type-grouping 277 +-- (key-type) 278 +--:(symmetric-key-ref) 279 | +-- symmetric-key-ref? 280 | -> /keystore/symmetric-keys/symmetric-key/name 281 | {keystore-supported}? 282 +--:(asymmetric-key-ref) 283 +-- asymmetric-key-ref? 284 -> /keystore/asymmetric-keys/asymmetric-key/name 285 {keystore-supported}? 286 grouping encrypted-value-grouping 287 +-- (key-type) 288 | +--:(symmetric-key-ref) 289 | | +-- symmetric-key-ref? 290 | | -> /keystore/symmetric-keys/symmetric-key/name 291 | | {keystore-supported}? 292 | +--:(asymmetric-key-ref) 293 | +-- asymmetric-key-ref? 294 | -> /keystore/asymmetric-keys/asymmetric-key/name 295 | {keystore-supported}? 296 +-- value? binary 297 grouping symmetric-key-grouping 298 +-- key-format? identityref 299 +-- (key-type) 300 +--:(key) 301 | +-- key? binary 302 +--:(hidden-key) 303 | +-- hidden-key? empty 304 +--:(encrypted-key) 305 +-- encrypted-key 306 +-- (key-type) 307 | +--:(symmetric-key-ref) 308 | | +-- symmetric-key-ref? leafref 309 | | {keystore-supported}? 310 | +--:(asymmetric-key-ref) 311 | +-- asymmetric-key-ref? leafref 312 | {keystore-supported}? 313 +-- value? binary 314 grouping asymmetric-key-pair-grouping 315 +-- public-key-format identityref 316 +-- public-key binary 317 +-- private-key-format? identityref 318 +-- (private-key-type) 319 +--:(private-key) 320 | +-- private-key? binary 321 +--:(hidden-private-key) 322 | +-- hidden-private-key? empty 323 +--:(encrypted-private-key) 324 +-- encrypted-private-key 325 +-- (key-type) 326 | +--:(symmetric-key-ref) 327 | | +-- symmetric-key-ref? leafref 328 | | {keystore-supported}? 329 | +--:(asymmetric-key-ref) 330 | +-- asymmetric-key-ref? leafref 331 | {keystore-supported}? 332 +-- value? binary 333 grouping asymmetric-key-pair-with-cert-grouping 334 +-- public-key-format identityref 335 +-- public-key binary 336 +-- private-key-format? identityref 337 +-- (private-key-type) 338 | +--:(private-key) 339 | | +-- private-key? binary 340 | +--:(hidden-private-key) 341 | | +-- hidden-private-key? empty 342 | +--:(encrypted-private-key) 343 | +-- encrypted-private-key 344 | +-- (key-type) 345 | | +--:(symmetric-key-ref) 346 | | | +-- symmetric-key-ref? leafref 347 | | | {keystore-supported}? 348 | | +--:(asymmetric-key-ref) 349 | | +-- asymmetric-key-ref? leafref 350 | | {keystore-supported}? 351 | +-- value? binary 352 +-- cert? end-entity-cert-cms 353 +---n certificate-expiration 354 | +-- expiration-date yang:date-and-time 355 +---x generate-certificate-signing-request 356 {certificate-signing-request-generation}? 357 +---w input 358 | +---w subject binary 359 | +---w attributes? binary 360 +--ro output 361 +--ro certificate-signing-request ct:csr 362 grouping asymmetric-key-pair-with-certs-grouping 363 +-- public-key-format identityref 364 +-- public-key binary 365 +-- private-key-format? identityref 366 +-- (private-key-type) 367 | +--:(private-key) 368 | | +-- private-key? binary 369 | +--:(hidden-private-key) 370 | | +-- hidden-private-key? empty 371 | +--:(encrypted-private-key) 372 | +-- encrypted-private-key 373 | +-- (key-type) 374 | | +--:(symmetric-key-ref) 375 | | | +-- symmetric-key-ref? leafref 376 | | | {keystore-supported}? 377 | | +--:(asymmetric-key-ref) 378 | | +-- asymmetric-key-ref? leafref 379 | | {keystore-supported}? 380 | +-- value? binary 381 +-- certificates 382 | +-- certificate* [name] 383 | +-- name? string 384 | +-- cert end-entity-cert-cms 385 | +---n certificate-expiration 386 | +-- expiration-date yang:date-and-time 387 +---x generate-certificate-signing-request 388 {certificate-signing-request-generation}? 389 +---w input 390 | +---w subject binary 391 | +---w attributes? binary 392 +--ro output 393 +--ro certificate-signing-request ct:csr 394 grouping asymmetric-key-certificate-ref-grouping 395 +-- asymmetric-key? ks:asymmetric-key-ref 396 +-- certificate? leafref 397 grouping local-or-keystore-symmetric-key-grouping 398 +-- (local-or-keystore) 399 +--:(local) {local-definitions-supported}? 400 | +-- local-definition 401 | +-- key-format? identityref 402 | +-- (key-type) 403 | +--:(key) 404 | | +-- key? binary 405 | +--:(hidden-key) 406 | | +-- hidden-key? empty 407 | +--:(encrypted-key) 408 | +-- encrypted-key 409 | +-- (key-type) 410 | | +--:(symmetric-key-ref) 411 | | | +-- symmetric-key-ref? leafref 412 | | | {keystore-supported}? 413 | | +--:(asymmetric-key-ref) 414 | | +-- asymmetric-key-ref? leafref 415 | | {keystore-supported}? 416 | +-- value? binary 417 +--:(keystore) {keystore-supported}? 418 +-- keystore-reference? ks:symmetric-key-ref 419 grouping local-or-keystore-asymmetric-key-grouping 420 +-- (local-or-keystore) 421 +--:(local) {local-definitions-supported}? 422 | +-- local-definition 423 | +-- public-key-format identityref 424 | +-- public-key binary 425 | +-- private-key-format? identityref 426 | +-- (private-key-type) 427 | +--:(private-key) 428 | | +-- private-key? binary 429 | +--:(hidden-private-key) 430 | | +-- hidden-private-key? empty 431 | +--:(encrypted-private-key) 432 | +-- encrypted-private-key 433 | +-- (key-type) 434 | | +--:(symmetric-key-ref) 435 | | | +-- symmetric-key-ref? leafref 436 | | | {keystore-supported}? 437 | | +--:(asymmetric-key-ref) 438 | | +-- asymmetric-key-ref? leafref 439 | | {keystore-supported}? 440 | +-- value? binary 441 +--:(keystore) {keystore-supported}? 442 +-- keystore-reference? ks:asymmetric-key-ref 443 grouping local-or-keystore-asymmetric-key-with-certs-grouping 444 +-- (local-or-keystore) 445 +--:(local) {local-definitions-supported}? 446 | +-- local-definition 447 | +-- public-key-format identityref 448 | +-- public-key binary 449 | +-- private-key-format? identityref 450 | +-- (private-key-type) 451 | | +--:(private-key) 452 | | | +-- private-key? binary 453 | | +--:(hidden-private-key) 454 | | | +-- hidden-private-key? empty 455 | | +--:(encrypted-private-key) 456 | | +-- encrypted-private-key 457 | | +-- (key-type) 458 | | | +--:(symmetric-key-ref) 459 | | | | +-- symmetric-key-ref? leafref 460 | | | | {keystore-supported}? 461 | | | +--:(asymmetric-key-ref) 462 | | | +-- asymmetric-key-ref? leafref 463 | | | {keystore-supported}? 464 | | +-- value? binary 465 | +-- certificates 466 | | +-- certificate* [name] 467 | | +-- name? string 468 | | +-- cert end-entity-cert-cms 469 | | +---n certificate-expiration 470 | | +-- expiration-date yang:date-and-time 471 | +---x generate-certificate-signing-request 472 | {certificate-signing-request-generation}? 473 | +---w input 474 | | +---w subject binary 475 | | +---w attributes? binary 476 | +--ro output 477 | +--ro certificate-signing-request ct:csr 478 +--:(keystore) {keystore-supported}? 479 +-- keystore-reference? ks:asymmetric-key-ref 480 grouping local-or-keystore-end-entity-cert-with-key-grouping 481 +-- (local-or-keystore) 482 +--:(local) {local-definitions-supported}? 483 | +-- local-definition 484 | +-- public-key-format identityref 485 | +-- public-key binary 486 | +-- private-key-format? identityref 487 | +-- (private-key-type) 488 | | +--:(private-key) 489 | | | +-- private-key? binary 490 | | +--:(hidden-private-key) 491 | | | +-- hidden-private-key? empty 492 | | +--:(encrypted-private-key) 493 | | +-- encrypted-private-key 494 | | +-- (key-type) 495 | | | +--:(symmetric-key-ref) 496 | | | | +-- symmetric-key-ref? leafref 497 | | | | {keystore-supported}? 498 | | | +--:(asymmetric-key-ref) 499 | | | +-- asymmetric-key-ref? leafref 500 | | | {keystore-supported}? 501 | | +-- value? binary 502 | +-- cert? 503 | | end-entity-cert-cms 504 | +---n certificate-expiration 505 | | +-- expiration-date yang:date-and-time 506 | +---x generate-certificate-signing-request 507 | {certificate-signing-request-generation}? 508 | +---w input 509 | | +---w subject binary 510 | | +---w attributes? binary 511 | +--ro output 512 | +--ro certificate-signing-request ct:csr 513 +--:(keystore) {keystore-supported}? 514 +-- keystore-reference 515 +-- asymmetric-key? ks:asymmetric-key-ref 516 +-- certificate? leafref 517 grouping keystore-grouping 518 +-- asymmetric-keys 519 | +-- asymmetric-key* [name] 520 | +-- name? string 521 | +-- public-key-format identityref 522 | +-- public-key binary 523 | +-- private-key-format? identityref 524 | +-- (private-key-type) 525 | | +--:(private-key) 526 | | | +-- private-key? binary 527 | | +--:(hidden-private-key) 528 | | | +-- hidden-private-key? empty 529 | | +--:(encrypted-private-key) 530 | | +-- encrypted-private-key 531 | | +-- (key-type) 532 | | | +--:(symmetric-key-ref) 533 | | | | +-- symmetric-key-ref? leafref 534 | | | | {keystore-supported}? 535 | | | +--:(asymmetric-key-ref) 536 | | | +-- asymmetric-key-ref? leafref 537 | | | {keystore-supported}? 538 | | +-- value? binary 539 | +-- certificates 540 | | +-- certificate* [name] 541 | | +-- name? string 542 | | +-- cert end-entity-cert-cms 543 | | +---n certificate-expiration 544 | | +-- expiration-date yang:date-and-time 545 | +---x generate-certificate-signing-request 546 | {certificate-signing-request-generation}? 547 | +---w input 548 | | +---w subject binary 549 | | +---w attributes? binary 550 | +--ro output 551 | +--ro certificate-signing-request ct:csr 552 +-- symmetric-keys 553 +-- symmetric-key* [name] 554 +-- name? string 555 +-- key-format? identityref 556 +-- (key-type) 557 +--:(key) 558 | +-- key? binary 559 +--:(hidden-key) 560 | +-- hidden-key? empty 561 +--:(encrypted-key) 562 +-- encrypted-key 563 +-- (key-type) 564 | +--:(symmetric-key-ref) 565 | | +-- symmetric-key-ref? leafref 566 | | {keystore-supported}? 567 | +--:(asymmetric-key-ref) 568 | +-- asymmetric-key-ref? leafref 569 | {keystore-supported}? 570 +-- value? binary 572 3.2. Example Usage 574 3.2.1. A Keystore Instance 576 The following example illustrates keys in . Please see 577 Section 4 for an example illustrating built-in values in 578 . 580 ========== NOTE: '\' line wrapping per BCP XXX (RFC XXXX) =========== 582 584 586 587 cleartext-symmetric-key 588 ct:octet-string-key-format 589 base64encodedvalue== 590 592 593 hidden-symmetric-key 594 595 597 598 encrypted-symmetric-key 599 ct:encrypted-one-symmetric-key-format 600 601 hidden-asymmetric-key 603 base64encodedvalue== 604 605 607 608 610 611 ssh-rsa-key 612 ct:ssh-public-key-format 613 base64encodedvalue== 614 ct:rsa-private-key-format 616 base64encodedvalue== 617 619 620 ssh-rsa-key-with-cert 621 ct:subject-public-key-info-format 623 base64encodedvalue== 624 ct:rsa-private-key-format 626 base64encodedvalue== 627 628 629 ex-rsa-cert2 630 base64encodedvalue== 631 632 633 635 636 raw-private-key 637 ct:subject-public-key-info-format 639 base64encodedvalue== 640 ct:rsa-private-key-format 642 base64encodedvalue== 643 645 646 rsa-asymmetric-key 647 ct:subject-public-key-info-format 649 base64encodedvalue== 650 ct:rsa-private-key-format 652 base64encodedvalue== 653 654 655 ex-rsa-cert 656 base64encodedvalue== 657 658 659 661 662 ec-asymmetric-key 663 ct:subject-public-key-info-format 665 base64encodedvalue== 666 ct:ec-private-key-format 668 base64encodedvalue== 669 670 671 ex-ec-cert 672 base64encodedvalue== 673 674 675 677 678 hidden-asymmetric-key 679 ct:subject-public-key-info-format 681 base64encodedvalue== 682 683 684 685 builtin-idevid-cert 686 base64encodedvalue== 687 688 689 my-ldevid-cert 690 base64encodedvalue== 691 692 693 695 696 encrypted-asymmetric-key 697 ct:subject-public-key-info-format 699 base64encodedvalue== 700 ct:encrypted-one-asymmetric-key-format 702 703 encrypted-symmetric-key 705 base64encodedvalue== 706 707 709 710 712 3.2.2. Notable Keystore Groupings 714 The following non-normative module is used by subsequent examples to 715 illustrate groupings defined in the ietf-keystore module. 717 module ex-keystore-usage { 718 yang-version 1.1; 720 namespace "http://example.com/ns/example-keystore-usage"; 721 prefix "eku"; 723 import ietf-keystore { 724 prefix ks; 725 reference 726 "RFC XXXX: YANG Data Model for a 'Keystore' Mechanism"; 727 } 729 organization 730 "Example Corporation"; 732 contact 733 "Author: YANG Designer "; 735 description 736 "This module illustrates the grouping in the keystore draft called 737 'local-or-keystore-asymmetric-key-with-certs-grouping'."; 739 revision "YYYY-MM-DD" { 740 description 741 "Initial version"; 742 reference 743 "RFC XXXX: YANG Data Model for a 'Keystore' Mechanism"; 744 } 746 container keystore-usage { 747 description 748 "An illustration of the various keystore groupings."; 750 list just-a-key { 751 key name; 752 leaf name { 753 type string; 754 description 755 "An arbitrary name for this key."; 756 } 757 uses ks:local-or-keystore-asymmetric-key-grouping; 758 description 759 "An asymmetric key, with no certs, that may be configured 760 locally or be a reference to an asymmetric key in the 761 keystore. The intent is to reference just the asymmetric 762 key, not any certificates that may also be associated 763 with the asymmetric key."; 764 } 766 list key-with-certs { 767 key name; 768 leaf name { 769 type string; 770 description 771 "An arbitrary name for this key."; 772 } 773 uses ks:local-or-keystore-asymmetric-key-with-certs-grouping; 774 description 775 "An asymmetric key and its associated certs, that may be 776 configured locally or be a reference to an asymmetric key 777 (and its associated certs) in the keystore."; 778 } 780 list end-entity-cert-with-key { 781 key name; 782 leaf name { 783 type string; 784 description 785 "An arbitrary name for this key."; 786 } 787 uses ks:local-or-keystore-end-entity-cert-with-key-grouping; 788 description 789 "An end-entity certificate, and its associated private key, 790 that may be configured locally or be a reference to a 791 specific certificate (and its associated private key) in 792 the keystore."; 793 } 794 } 796 } 798 The following example illustrates what two configured keys, one local 799 and the other remote, might look like. This example consistent with 800 other examples above (i.e., the referenced key is in an example 801 above). 803 ========== NOTE: '\' line wrapping per BCP XXX (RFC XXXX) =========== 805 807 809 810 a locally-defined key 811 812 ct:subject-public-key-info-format 814 base64encodedvalue== 815 ct:rsa-private-key-format 817 base64encodedvalue== 818 819 821 822 a keystore-defined key (and its associated certs) 823 rsa-asymmetric-key 824 826 828 829 a locally-defined key with certs 830 831 ct:subject-public-key-info-format 833 base64encodedvalue== 834 ct:rsa-private-key-format 836 base64encodedvalue== 837 838 839 a locally-defined cert 840 base64encodedvalue== 841 842 843 844 846 847 a keystore-defined key (and its associated certs) 848 rsa-asymmetric-key 849 851 853 854 a locally-defined end-entity cert with key 855 856 ct:subject-public-key-info-format 858 base64encodedvalue== 859 ct:rsa-private-key-format 861 base64encodedvalue== 862 base64encodedvalue== 863 864 866 867 a keystore-defined certificate (and its associated key) 869 870 rsa-asymmetric-key 871 ex-rsa-cert 872 873 875 877 3.3. YANG Module 879 This YANG module has normative references to [RFC8341] and 880 [I-D.ietf-netconf-crypto-types], and an informative reference to 881 [RFC8342]. 883 file "ietf-keystore@2020-05-20.yang" 885 module ietf-keystore { 886 yang-version 1.1; 887 namespace "urn:ietf:params:xml:ns:yang:ietf-keystore"; 888 prefix ks; 890 import ietf-netconf-acm { 891 prefix nacm; 892 reference 893 "RFC 8341: Network Configuration Access Control Model"; 894 } 896 import ietf-crypto-types { 897 prefix ct; 898 reference 899 "RFC AAAA: Common YANG Data Types for Cryptography"; 900 } 902 organization 903 "IETF NETCONF (Network Configuration) Working Group"; 905 contact 906 "WG Web: 907 WG List: 908 Author: Kent Watsen "; 910 description 911 "This module defines a Keystore to centralize management 912 of security credentials. 914 Copyright (c) 2020 IETF Trust and the persons identified 915 as authors of the code. All rights reserved. 917 Redistribution and use in source and binary forms, with 918 or without modification, is permitted pursuant to, and 919 subject to the license terms contained in, the Simplified 920 BSD License set forth in Section 4.c of the IETF Trust's 921 Legal Provisions Relating to IETF Documents 922 (https://trustee.ietf.org/license-info). 924 This version of this YANG module is part of RFC CCCC 925 (https://www.rfc-editor.org/info/rfcCCCC); see the RFC 926 itself for full legal notices. 928 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 929 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 930 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 931 are to be interpreted as described in BCP 14 (RFC 2119) 932 (RFC 8174) when, and only when, they appear in all 933 capitals, as shown here."; 935 revision 2020-05-20 { 936 description 937 "Initial version"; 938 reference 939 "RFC CCCC: A YANG Data Model for a Keystore"; 940 } 942 /****************/ 943 /* Features */ 944 /****************/ 946 feature keystore-supported { 947 description 948 "The 'keystore-supported' feature indicates that the server 949 supports the Keystore."; 950 } 951 feature local-definitions-supported { 952 description 953 "The 'local-definitions-supported' feature indicates that the 954 server supports locally-defined keys."; 955 } 957 /****************/ 958 /* Typedefs */ 959 /****************/ 961 typedef symmetric-key-ref { 962 type leafref { 963 path "/ks:keystore/ks:symmetric-keys/ks:symmetric-key" 964 + "/ks:name"; 965 } 966 description 967 "This typedef enables modules to easily define a reference 968 to a symmetric key stored in the Keystore."; 969 } 971 typedef asymmetric-key-ref { 972 type leafref { 973 path "/ks:keystore/ks:asymmetric-keys/ks:asymmetric-key" 974 + "/ks:name"; 975 } 976 description 977 "This typedef enables modules to easily define a reference 978 to an asymmetric key stored in the Keystore."; 979 } 981 /*****************/ 982 /* Groupings */ 983 /*****************/ 985 grouping key-reference-type-grouping { 986 description 987 "A reusable grouping for a choice for the type of key 988 referenced in the Keystore."; 989 choice key-type { 990 mandatory true; 991 description 992 "A choice between a reference to a symmetric or asymmetric 993 key in the Keystore."; 994 leaf symmetric-key-ref { 995 if-feature "keystore-supported"; 996 type leafref { 997 path "/ks:keystore/ks:symmetric-keys/ks:symmetric-key/" 998 + "ks:name"; 999 } 1000 description 1001 "Identifies a symmetric key used to encrypt this key."; 1002 } 1003 leaf asymmetric-key-ref { 1004 if-feature "keystore-supported"; 1005 type leafref { 1006 path "/ks:keystore/ks:asymmetric-keys/ks:asymmetric-key/" 1007 + "ks:name"; 1008 } 1009 description 1010 "Identifies an asymmetric key used to encrypt this key."; 1011 } 1012 } 1013 } 1015 grouping encrypted-value-grouping { 1016 description 1017 "A reusable grouping for a value that has been encrypted by 1018 a symmetric or asymmetric key in the Keystore."; 1019 uses "key-reference-type-grouping"; 1020 leaf value { 1021 type binary; 1022 description 1023 "The private key, encrypted using the specified symmetric 1024 or asymmetric key."; 1025 } 1026 } 1028 grouping symmetric-key-grouping { 1029 description 1030 "This grouping is identical to the one in ietf-crypto-types 1031 except that it adds a case statement enabling the key 1032 value to be encrypted by a symmetric or an asymmetric 1033 key known to the Keystore."; 1034 uses ct:symmetric-key-grouping { 1035 augment "key-type" { 1036 description 1037 "Augments a new 'case' statement into the 'choice' 1038 statement defined by the ietf-crypto-types module."; 1039 container encrypted-key { 1040 must "../key-format"; 1041 description 1042 "A container for the encrypted symmetric key value."; 1043 uses encrypted-value-grouping; 1044 } 1045 } 1047 } 1048 } 1050 grouping asymmetric-key-pair-grouping { 1051 description 1052 "This grouping is identical to the one in ietf-crypto-types 1053 except that it adds a case statement enabling the key 1054 value to be encrypted by a symmetric or an asymmetric 1055 key known to the Keystore."; 1056 uses ct:asymmetric-key-pair-grouping { 1057 augment "private-key-type" { 1058 description 1059 "Augments a new 'case' statement into the 'choice' 1060 statement defined by the ietf-crypto-types module."; 1061 container encrypted-private-key { 1062 must "../private-key-format"; 1063 description 1064 "A container for the encrypted asymmetric private 1065 key value."; 1066 uses encrypted-value-grouping; 1067 } 1068 } 1069 } 1070 } 1072 grouping asymmetric-key-pair-with-cert-grouping { 1073 description 1074 "This grouping is identical to the one in ietf-crypto-types 1075 except that it adds a case statement enabling the key 1076 value to be encrypted by a symmetric or an asymmetric 1077 key known to the Keystore."; 1078 uses ct:asymmetric-key-pair-with-cert-grouping { 1079 augment "private-key-type" { 1080 description 1081 "Augments a new 'case' statement into the 'choice' 1082 statement defined by the ietf-crypto-types module."; 1083 container encrypted-private-key { 1084 must "../private-key-format"; 1085 description 1086 "A container for the encrypted asymmetric private 1087 key value."; 1088 uses encrypted-value-grouping; 1089 } 1090 } 1091 } 1092 } 1094 grouping asymmetric-key-pair-with-certs-grouping { 1095 description 1096 "This grouping is identical to the one in ietf-crypto-types 1097 except that it adds a case statement enabling the key 1098 value to be encrypted by a symmetric or an asymmetric 1099 key known to the Keystore."; 1100 uses ct:asymmetric-key-pair-with-certs-grouping { 1101 augment "private-key-type" { 1102 description 1103 "Augments a new 'case' statement into the 'choice' 1104 statement defined by the ietf-crypto-types module."; 1105 container encrypted-private-key { 1106 must "../private-key-format"; 1107 description 1108 "A container for the encrypted asymmetric private 1109 key value."; 1110 uses encrypted-value-grouping; 1111 } 1112 } 1113 } 1114 } 1116 grouping asymmetric-key-certificate-ref-grouping { 1117 leaf asymmetric-key { 1118 type ks:asymmetric-key-ref; 1119 must '../certificate'; 1120 description 1121 "A reference to an asymmetric key in the Keystore."; 1122 } 1123 leaf certificate { 1124 type leafref { 1125 path "/ks:keystore/ks:asymmetric-keys/ks:asymmetric-key[ks:" 1126 + "name = current()/../asymmetric-key]/ks:certificates" 1127 + "/ks:certificate/ks:name"; 1128 } 1129 must '../asymmetric-key'; 1130 description 1131 "A reference to a specific certificate of the 1132 asymmetric key in the Keystore."; 1133 } 1134 description 1135 "This grouping defines a reference to a specific certificate 1136 associated with an asymmetric key stored in the Keystore."; 1137 } 1139 // local-or-keystore-* groupings 1141 grouping local-or-keystore-symmetric-key-grouping { 1142 description 1143 "A grouping that expands to allow the symmetric key to be 1144 either stored locally, within the using data model, or be 1145 a reference to a symmetric key stored in the Keystore."; 1146 choice local-or-keystore { 1147 mandatory true; 1148 case local { 1149 if-feature "local-definitions-supported"; 1150 container local-definition { 1151 description 1152 "Container to hold the local key definition."; 1153 uses symmetric-key-grouping; 1154 } 1155 } 1156 case keystore { 1157 if-feature "keystore-supported"; 1158 leaf keystore-reference { 1159 type ks:symmetric-key-ref; 1160 description 1161 "A reference to an symmetric key that exists in 1162 the Keystore."; 1163 } 1164 } 1165 description 1166 "A choice between an inlined definition and a definition 1167 that exists in the Keystore."; 1168 } 1169 } 1171 grouping local-or-keystore-asymmetric-key-grouping { 1172 description 1173 "A grouping that expands to allow the asymmetric key to be 1174 either stored locally, within the using data model, or be 1175 a reference to an asymmetric key stored in the Keystore."; 1176 choice local-or-keystore { 1177 mandatory true; 1178 case local { 1179 if-feature "local-definitions-supported"; 1180 container local-definition { 1181 description 1182 "Container to hold the local key definition."; 1183 uses asymmetric-key-pair-grouping; 1184 } 1185 } 1186 case keystore { 1187 if-feature "keystore-supported"; 1188 leaf keystore-reference { 1189 type ks:asymmetric-key-ref; 1190 description 1191 "A reference to an asymmetric key that exists in 1192 the Keystore. The intent is to reference just the 1193 asymmetric key without any regard for any certificates 1194 that may be associated with it."; 1195 } 1196 } 1197 description 1198 "A choice between an inlined definition and a definition 1199 that exists in the Keystore."; 1200 } 1201 } 1203 grouping local-or-keystore-asymmetric-key-with-certs-grouping { 1204 description 1205 "A grouping that expands to allow an asymmetric key and its 1206 associated certificates to be either stored locally, within 1207 the using data model, or be a reference to an asymmetric key 1208 (and its associated certificates) stored in the Keystore."; 1209 choice local-or-keystore { 1210 mandatory true; 1211 case local { 1212 if-feature "local-definitions-supported"; 1213 container local-definition { 1214 description 1215 "Container to hold the local key definition."; 1216 uses asymmetric-key-pair-with-certs-grouping; 1217 } 1218 } 1219 case keystore { 1220 if-feature "keystore-supported"; 1221 leaf keystore-reference { 1222 type ks:asymmetric-key-ref; 1223 description 1224 "A reference to an asymmetric-key (and all of its 1225 associated certificates) in the Keystore."; 1226 } 1227 } 1228 description 1229 "A choice between an inlined definition and a definition 1230 that exists in the Keystore."; 1231 } 1232 } 1234 grouping local-or-keystore-end-entity-cert-with-key-grouping { 1235 description 1236 "A grouping that expands to allow an end-entity certificate 1237 (and its associated private key) to be either stored locally, 1238 within the using data model, or be a reference to a specific 1239 certificate in the Keystore."; 1240 choice local-or-keystore { 1241 mandatory true; 1242 case local { 1243 if-feature "local-definitions-supported"; 1244 container local-definition { 1245 description 1246 "Container to hold the local key definition."; 1247 uses asymmetric-key-pair-with-cert-grouping; 1248 } 1249 } 1250 case keystore { 1251 if-feature "keystore-supported"; 1252 container keystore-reference { 1253 uses asymmetric-key-certificate-ref-grouping; 1254 description 1255 "A reference to a specific certificate (and its 1256 associated private key) in the Keystore."; 1257 } 1258 } 1259 description 1260 "A choice between an inlined definition and a definition 1261 that exists in the Keystore."; 1262 } 1263 } 1265 grouping keystore-grouping { 1266 description 1267 "Grouping definition enables use in other contexts. If ever 1268 done, implementations SHOULD augment new 'case' statements 1269 into local-or-keystore 'choice' statements to supply leafrefs 1270 to the new location."; 1271 container asymmetric-keys { 1272 description 1273 "A list of asymmetric keys."; 1274 list asymmetric-key { 1275 key "name"; 1276 description 1277 "An asymmetric key."; 1278 leaf name { 1279 type string; 1280 description 1281 "An arbitrary name for the asymmetric key."; 1282 } 1283 uses ks:asymmetric-key-pair-with-certs-grouping; 1284 } 1285 } 1286 container symmetric-keys { 1287 description 1288 "A list of symmetric keys."; 1289 list symmetric-key { 1290 key "name"; 1291 description 1292 "A symmetric key."; 1293 leaf name { 1294 type string; 1295 description 1296 "An arbitrary name for the symmetric key."; 1297 } 1298 uses ks:symmetric-key-grouping; 1299 } 1300 } 1301 } // grouping keystore-grouping 1303 /*********************************/ 1304 /* Protocol accessible nodes */ 1305 /*********************************/ 1307 container keystore { 1308 nacm:default-deny-write; 1309 description 1310 "The Keystore contains a list of symmetric keys and a list 1311 of asymmetric keys."; 1312 uses keystore-grouping; 1313 } 1315 } 1317 1319 4. Support for Built-in Keys 1321 In some implementations, a server may support built-in keys. Built- 1322 in built-in keys MAY be set during the manufacturing process or be 1323 dynamically generated the first time the server is booted or a 1324 particular service (e.g., SSH) is enabled. 1326 The key characteristic of the built-in keys is that they are provided 1327 by the system, as opposed to configuration. As such, they are 1328 present in . The example below illustrates what the 1329 truststore in might look like for a server in its 1330 factory default state. 1332 ========== NOTE: '\' line wrapping per BCP XXX (RFC XXXX) =========== 1334 1338 1339 1340 Manufacturer-Generated Hidden Key 1341 ct:subject-public-key-info-format 1343 base64encodedvalue== 1344 1345 1346 1347 Manufacturer-Generated IDevID Cert 1348 base64encodedvalue== 1349 1350 1351 1352 1353 1355 In order for the built-in keys to be referenced by configuration, the 1356 referenced nodes MUST first be copied into . They SHOULD be 1357 copied into using the same "key" values, so that the system 1358 can bind the references to the built-in entries. Only the referenced 1359 nodes need to be copied. When using the same key values as in 1360 no new values can be added and no existing values can 1361 be changed; that which is in can only be a subset of that 1362 which is in . 1364 For instance, the following example illustrates how a single built-in 1365 key definition from the previous example has been propagated to 1366 : 1368 ========== NOTE: '\' line wrapping per BCP XXX (RFC XXXX) =========== 1370 1372 1373 1374 Manufacturer-Generated Hidden Key 1375 ct:subject-public-key-info-format 1377 base64encodedvalue== 1378 1379 1380 1381 Manufacturer-Generated IDevID Cert 1382 base64encodedvalue== 1383 1384 1385 Deployment-Specific LDevID Cert 1386 base64encodedvalue== 1387 1388 1389 1390 1391 1393 After the above configuration is applied, should appear 1394 as follows: 1396 ========== NOTE: '\' line wrapping per BCP XXX (RFC XXXX) =========== 1398 1402 1403 1404 Manufacturer-Generated Hidden Key 1405 ct:subject-public-key-info-format 1407 base64encodedvalue== 1408 1409 1410 1411 Manufacturer-Generated IDevID Cert 1412 base64encodedvalue== 1413 1414 1415 Deployment-Specific LDevID Cert 1416 base64encodedvalue== 1417 1418 1419 1420 1421 1423 5. Encrypting Keys in Configuration 1425 This section describes an approach that enables all the private keys 1426 on a server to be encrypted, such that traditional backup/restore 1427 procedures can be used without concern for keys being compromised 1428 when in transit. 1430 5.1. Root Key 1432 The cornerstone to this solution is the existence of a "root" key 1433 that can be used to encrypt all the other keys. The server MUST be 1434 able to use this key to decrypt the other keys in the configuration. 1436 The root key SHOULD be a hidden key, i.e., one whose private data has 1437 no presence in or (see "hidden-key" and 1438 "hidden-private-key" in "ietf-crypto-types" 1439 [I-D.ietf-netconf-crypto-types]). If the server implementation does 1440 not support hidden keys, then the private data part of key MUST be 1441 protected by access control with access granted only to an 1442 administrator with special access control rights (e.g., an 1443 organization's crypto officer). Given the long lifetime of built-in 1444 keys (see Section 4), built-in keys MUST be hidden. 1446 A hidden root key MAY be either a symmetric key or an asymmetric key. 1447 If the hidden root key is symmetric, then the server MUST provide 1448 APIs enabling other keys (ideally generated by the server) to be 1449 encrypted. If the hidden root key is asymmetric, then the server 1450 SHOULD provide APIs enabling other keys to be both generated and 1451 encrypted by it, but MAY alternatively enable administrators with 1452 special access control rights to generate and encrypt the other keys 1453 themselves, using the hidden key's public part. For practical 1454 reasons, an unhidden root key SHOULD be asymmetric, so that its 1455 public part can be accessed by other administrators without concern. 1457 5.2. Configuring Encrypting Keys 1459 Each time a new key is to be configured, it SHOULD be encrypted by 1460 the root key. 1462 In "ietf-crypto-types" [I-D.ietf-netconf-crypto-types], the format 1463 for an encrypted symmetric key is described by the "encrypted-one- 1464 symmetric-key-format" identity, while the format for an encrypted 1465 asymmetric key is described by the "encrypted-one-asymmetric-key- 1466 format" identity 1468 Ideally, the server implementation provides an API to generate a 1469 symmetric or asymmetric key, and encrypt the generated key using 1470 another key known to the system (e.g., the root key). Thusly 1471 administrators can safely call this API to configure new keys. 1473 In case the server implementation does not provide such an API, then 1474 the generating and encrypting steps MAY be performed outside the 1475 server, e.g., by an administrator with special access control rights. 1477 In either case, the encrypted key can be configured into the Keystore 1478 using either the "encrypted-key" (for symmetric keys) or the 1479 "encrypted-private-key" (for asymmetric keys) nodes. These two nodes 1480 contain both the encrypted value as well as a reference to the other 1481 key in the Keystore that it was encrypted by. 1483 5.3. Migrating Configuration to Another Server 1485 One concern that arose during discourse was how it could be possible 1486 migrate configuration from one server to another server, if both 1487 servers used different root keys (e.g., a TPM-protected built-in 1488 key). It was noted that, in this case, the second server would be 1489 unable to decrypt any of the keys encrypted by the first server. 1491 The solution to this issue is simply to ensure that the same key is 1492 known to both servers. How this is achieved may vary. If the first 1493 server is still accessible, it may be possible to ask it to encrypt 1494 the key using the second server's root key. That said, a common 1495 scenario for needing to migrate configuration to another server is 1496 because the first server is no longer available. Thus it is more 1497 likely the case that the shared root key is known to administrators 1498 with special access control rights (an organization's crypto 1499 officer), such that the shared key can be provided to the second 1500 server to unlock all the other keys in the configuration. 1502 For systems that have a built-in key protected by hardware, the 1503 shared root key SHOULD be encrypted by the built-in key. In this 1504 way, at least from the system's perspective, it is more like an 1505 intermediate key than a root key. 1507 As a concrete example, assuming both servers have built-in asymmetric 1508 keys, the shared key could be a symmetric key that an organization's 1509 crypto officer encrypts offline knowing each server's public key, 1510 which may be, e.g., in the server's IDevID certificate. The crypto 1511 officer can then safely handoff the encrypted shared key to other 1512 administrators responsible for server installations, including 1513 migrations. 1515 In order to migrate a configuration, the administrator would need to 1516 make just a single modification to the configuration before loading 1517 it onto the second server, which is to replace the shared key's 1518 Keystore entry from the first server (an encrypted key), with the 1519 shared key encrypted by the second server's built-in key. 1521 6. Security Considerations 1523 The YANG module defined in this document is designed to be accessed 1524 via YANG based management protocols, such as NETCONF [RFC6241] and 1525 RESTCONF [RFC8040]. Both of these protocols have mandatory-to- 1526 implement secure transport layers (e.g., SSH, TLS) with mutual 1527 authentication. 1529 The NETCONF access control model (NACM) [RFC8341] provides the means 1530 to restrict access for particular users to a pre-configured subset of 1531 all available protocol operations and content. 1533 There are a number of data nodes defined in this YANG module that are 1534 writable/creatable/deletable (i.e., config true, which is the 1535 default). These data nodes may be considered sensitive or vulnerable 1536 in some network environments. Write operations (e.g., edit-config) 1537 to these data nodes without proper protection can have a negative 1538 effect on network operations. These are the subtrees and data nodes 1539 and their sensitivity/vulnerability: 1541 /: The entire data tree defined by this module is sensitive to 1542 write operations. For instance, the addition or removal of 1543 keys, certificates, etc., can dramatically alter the 1544 implemented security policy. For this reason, the NACM 1545 extension "default-deny-write" has been set for the entire data 1546 tree. 1548 /keystore/asymmetric-keys/asymmetric-key/private-key: When 1549 writing this node, implementations MUST ensure that the 1550 strength of the key being configured is not greater than the 1551 strength of the underlying secure transport connection over 1552 which it is communicated. Implementations SHOULD fail the 1553 write-request if ever the strength of the private key is 1554 greater then the strength of the underlying transport, and 1555 alert the client that the strength of the key may have been 1556 compromised. Additionally, when deleting this node, 1557 implementations SHOULD automatically (without explicit request) 1558 zeroize these keys in the most secure manner available, so as 1559 to prevent the remnants of their persisted storage locations 1560 from being analyzed in any meaningful way. 1562 Some of the readable data nodes in this YANG module may be considered 1563 sensitive or vulnerable in some network environments. It is thus 1564 important to control read access (e.g., via get, get-config, or 1565 notification) to these data nodes. These are the subtrees and data 1566 nodes and their sensitivity/vulnerability: 1568 /keystore/asymmetric-keys/asymmetric-key/private-key: This node 1569 is additionally sensitive to read operations such that, in 1570 normal use cases, it should never be returned to a client. The 1571 best reason for returning this node is to support backup/ 1572 restore type workflows. For this reason, the NACM extension 1573 "default-deny-all" has been set for this data node. 1575 7. IANA Considerations 1577 7.1. The IETF XML Registry 1579 This document registers one URI in the "ns" subregistry of the IETF 1580 XML Registry [RFC3688]. Following the format in [RFC3688], the 1581 following registration is requested: 1583 URI: urn:ietf:params:xml:ns:yang:ietf-keystore 1584 Registrant Contact: The NETCONF WG of the IETF. 1585 XML: N/A, the requested URI is an XML namespace. 1587 7.2. The YANG Module Names Registry 1589 This document registers one YANG module in the YANG Module Names 1590 registry [RFC6020]. Following the format in [RFC6020], the the 1591 following registration is requested: 1593 name: ietf-keystore 1594 namespace: urn:ietf:params:xml:ns:yang:ietf-keystore 1595 prefix: ks 1596 reference: RFC CCCC 1598 8. References 1600 8.1. Normative References 1602 [I-D.ietf-netconf-crypto-types] 1603 Watsen, K. and H. Wang, "Common YANG Data Types for 1604 Cryptography", draft-ietf-netconf-crypto-types-14 (work in 1605 progress), March 2020. 1607 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1608 Requirement Levels", BCP 14, RFC 2119, 1609 DOI 10.17487/RFC2119, March 1997, 1610 . 1612 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1613 the Network Configuration Protocol (NETCONF)", RFC 6020, 1614 DOI 10.17487/RFC6020, October 2010, 1615 . 1617 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1618 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1619 . 1621 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 1622 Access Control Model", STD 91, RFC 8341, 1623 DOI 10.17487/RFC8341, March 2018, 1624 . 1626 8.2. Informative References 1628 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1629 DOI 10.17487/RFC3688, January 2004, 1630 . 1632 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1633 and A. Bierman, Ed., "Network Configuration Protocol 1634 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1635 . 1637 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1638 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1639 . 1641 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1642 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1643 May 2017, . 1645 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 1646 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 1647 . 1649 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1650 and R. Wilton, "Network Management Datastore Architecture 1651 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 1652 . 1654 [Std-802.1AR-2009] 1655 Group, W. -. H. L. L. P. W., "IEEE Standard for Local and 1656 metropolitan area networks - Secure Device Identity", 1657 December 2009, . 1660 8.3. URIs 1662 [1] https://tools.ietf.org/html/draft-ietf-netconf-crypto-types 1664 [2] https://tools.ietf.org/html/draft-ietf-netconf-trust-anchors 1666 [3] https://tools.ietf.org/html/draft-ietf-netconf-keystore 1668 [4] https://tools.ietf.org/html/draft-ietf-netconf-tcp-client-server 1670 [5] https://tools.ietf.org/html/draft-ietf-netconf-ssh-client-server 1672 [6] https://tools.ietf.org/html/draft-ietf-netconf-tls-client-server 1674 [7] https://tools.ietf.org/html/draft-ietf-netconf-http-client-server 1676 [8] https://tools.ietf.org/html/draft-ietf-netconf-netconf-client- 1677 server 1679 [9] https://tools.ietf.org/html/draft-ietf-netconf-restconf-client- 1680 server 1682 Appendix A. Change Log 1684 A.1. 00 to 01 1686 o Replaced the 'certificate-chain' structures with PKCS#7 1687 structures. (Issue #1) 1689 o Added 'private-key' as a configurable data node, and removed the 1690 'generate-private-key' and 'load-private-key' actions. (Issue #2) 1692 o Moved 'user-auth-credentials' to the ietf-ssh-client module. 1693 (Issues #4 and #5) 1695 A.2. 01 to 02 1697 o Added back 'generate-private-key' action. 1699 o Removed 'RESTRICTED' enum from the 'private-key' leaf type. 1701 o Fixed up a few description statements. 1703 A.3. 02 to 03 1705 o Changed draft's title. 1707 o Added missing references. 1709 o Collapsed sections and levels. 1711 o Added RFC 8174 to Requirements Language Section. 1713 o Renamed 'trusted-certificates' to 'pinned-certificates'. 1715 o Changed 'public-key' from config false to config true. 1717 o Switched 'host-key' from OneAsymmetricKey to definition from RFC 1718 4253. 1720 A.4. 03 to 04 1722 o Added typedefs around leafrefs to common keystore paths 1724 o Now tree diagrams reference ietf-netmod-yang-tree-diagrams 1726 o Removed Design Considerations section 1728 o Moved key and certificate definitions from data tree to groupings 1730 A.5. 04 to 05 1732 o Removed trust anchors (now in their own draft) 1734 o Added back global keystore structure 1736 o Added groupings enabling keys to either be locally defined or a 1737 reference to the keystore. 1739 A.6. 05 to 06 1741 o Added feature "local-keys-supported" 1743 o Added nacm:default-deny-all and nacm:default-deny-write 1745 o Renamed generate-asymmetric-key to generate-hidden-key 1747 o Added an install-hidden-key action 1749 o Moved actions inside fo the "asymmetric-key" container 1751 o Moved some groupings to draft-ietf-netconf-crypto-types 1753 A.7. 06 to 07 1755 o Removed a "require-instance false" 1757 o Clarified some description statements 1759 o Improved the keystore-usage examples 1761 A.8. 07 to 08 1763 o Added "local-definition" containers to avoid posibility of the 1764 action/notification statements being under a "case" statement. 1766 o Updated copyright date, boilerplate template, affiliation, folding 1767 algorithm, and reformatted the YANG module. 1769 A.9. 08 to 09 1771 o Added a 'description' statement to the 'must' in the /keystore/ 1772 asymmetric-key node explaining that the descendent values may 1773 exist in only, and that implementation MUST assert 1774 that the values are either configured or that they exist in 1775 . 1777 o Copied above 'must' statement (and description) into the local-or- 1778 keystore-asymmetric-key-grouping, local-or-keystore-asymmetric- 1779 key-with-certs-grouping, and local-or-keystore-end-entity-cert- 1780 with-key-grouping statements. 1782 A.10. 09 to 10 1784 o Updated draft title to match new truststore draft title 1786 o Moved everything under a top-level 'grouping' to enable use in 1787 other contexts. 1789 o Renamed feature from 'local-keys-supported' to 'local-definitions- 1790 supported' (same name used in truststore) 1792 o Removed the either-all-or-none 'must' expressions for the key's 1793 3-tuple values (since the values are now 'mandatory true' in 1794 crypto-types) 1796 o Example updated to reflect 'mandatory true' change in crypto-types 1797 draft 1799 A.11. 10 to 11 1801 o Replaced typedef asymmetric-key-certificate-ref with grouping 1802 asymmetric-key-certificate-ref-grouping. 1804 o Added feature feature 'key-generation'. 1806 o Cloned groupings symmetric-key-grouping, asymmetric-key-pair- 1807 grouping, asymmetric-key-pair-with-cert-grouping, and asymmetric- 1808 key-pair-with-certs-grouping from crypto-keys, augmenting into 1809 each new case statements for values that have been encrypted by 1810 other keys in the keystore. Refactored keystore model to use 1811 these groupings. 1813 o Added new 'symmetric-keys' lists, as a sibling to the existing 1814 'asymmetric-keys' list. 1816 o Added RPCs (not actions) 'generate-symmetric-key' and 'generate- 1817 asymmetric-key' to *return* a (potentially encrypted) key. 1819 A.12. 11 to 12 1821 o Updated to reflect crypto-type's draft using enumerations over 1822 identities. 1824 o Added examples for the 'generate-symmetric-key' and 'generate- 1825 asymmetric-key' RPCs. 1827 o Updated the Introduction section. 1829 A.13. 12 to 13 1831 o Updated examples to incorporate new "key-format" identities. 1833 o Made the two "generate-*-key" RPCs be "action" statements instead. 1835 A.14. 13 to 14 1837 o Updated YANG module and examples to incorporate the new 1838 iana-*-algorithm modules in the crypto-types draft.. 1840 A.15. 14 to 15 1842 o Added new "Support for Built-in Trust Anchors" section. 1844 o Added 'must' expressions asserting that the 'key-format' leaf 1845 whenever an encrypted key is specified. 1847 o Added local-or-keystore-symmetric-key-grouping for PSK support. 1849 A.16. 15 to 16 1851 o Moved the generate key actions to ietf-crypt-types as RPCs, which 1852 are augmented by ietf-keystore to support encrypted keys. 1853 Examples updated accordingly. 1855 o Added a SSH certificate-based key (RFC 6187) and a raw private key 1856 to the example instance document (partly so they could be 1857 referenced by examples in the SSH and TLS client/server drafts. 1859 A.17. 16 to 17 1861 o Removed augments to the "generate-symmetric-key" and "generate- 1862 asymmetric-key" groupings. 1864 o Removed "generate-symmetric-key" and "generate-asymmetric-key" 1865 examples. 1867 o Removed the "algorithm" nodes from remaining examples. 1869 o Renamed/updated the "Support for Built-in Keys" section. 1871 o Added new section "Encrypting Keys in Configuration". 1873 o Added a "Note to Reviewers" note to first page. 1875 Acknowledgements 1877 The authors would like to thank for following for lively discussions 1878 on list and in the halls (ordered by first name): Alan Luchuk, Andy 1879 Bierman, Benoit Claise, Bert Wijnen, Balazs Kovacs, David Lamparter, 1880 Eric Voit, Ladislav Lhotka, Liang Xia, Juergen Schoenwaelder, Mahesh 1881 Jethanandani, Martin Bjorklund, Mehmet Ersue, Phil Shafer, Radek 1882 Krejci, Ramkumar Dhanapal, Reshad Rahman, Sean Turner, and Tom Petch. 1884 Author's Address 1886 Kent Watsen 1887 Watsen Networks 1889 EMail: kent+ietf@watsen.net