idnits 2.17.1 draft-ietf-netconf-keystore-15.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 ([I-D.ietf-netconf-crypto-types]), 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 192 has weird spacing: '...on-date yan...' == Line 198 has weird spacing: '...request bin...' == Line 364 has weird spacing: '...on-date yan...' == Line 370 has weird spacing: '...request bin...' == Line 397 has weird spacing: '...on-date yan...' == (7 more instances...) -- The document date (November 20, 2019) is 1618 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-12 Summary: 1 error (**), 0 flaws (~~), 8 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 November 20, 2019 5 Expires: May 23, 2020 7 A YANG Data Model for a Keystore 8 draft-ietf-netconf-keystore-15 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 many placeholder values that need to be replaced 21 with finalized values at the time of publication. This note 22 summarizes all of the substitutions that are needed. No other RFC 23 Editor 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 29 [I-D.ietf-netconf-crypto-types]. 31 o "XXXX" --> 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 "2019-11-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 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 May 23, 2020. 59 Copyright Notice 61 Copyright (c) 2019 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 66 (https://trustee.ietf.org/license-info) in effect on the date of 67 publication of this document. Please review these documents 68 carefully, as they describe your rights and restrictions with respect 69 to this document. Code Components extracted from this document must 70 include Simplified BSD License text as described in Section 4.e of 71 the Trust Legal Provisions and are provided without warranty as 72 described in the Simplified BSD License. 74 Table of Contents 76 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 77 2. Requirements Language . . . . . . . . . . . . . . . . . . . . 4 78 3. The Keystore Model . . . . . . . . . . . . . . . . . . . . . 4 79 3.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 4 80 3.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 14 81 3.2.1. A Keystore Instance . . . . . . . . . . . . . . . . . 14 82 3.2.2. The "generate-symmetric-key" RPC . . . . . . . . . . 16 83 3.2.3. The "generate-asymmetric-key" RPC . . . . . . . . . . 17 84 3.2.4. Notable Keystore Groupings . . . . . . . . . . . . . 18 85 3.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 22 86 4. Support for Built-in Keys . . . . . . . . . . . . . . . . . . 33 87 5. Security Considerations . . . . . . . . . . . . . . . . . . . 34 88 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 35 89 6.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 35 90 6.2. The YANG Module Names Registry . . . . . . . . . . . . . 35 91 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 35 92 7.1. Normative References . . . . . . . . . . . . . . . . . . 35 93 7.2. Informative References . . . . . . . . . . . . . . . . . 36 94 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 37 95 A.1. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 37 96 A.2. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 37 97 A.3. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 37 98 A.4. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 37 99 A.5. 04 to 05 . . . . . . . . . . . . . . . . . . . . . . . . 38 100 A.6. 05 to 06 . . . . . . . . . . . . . . . . . . . . . . . . 38 101 A.7. 06 to 07 . . . . . . . . . . . . . . . . . . . . . . . . 38 102 A.8. 07 to 08 . . . . . . . . . . . . . . . . . . . . . . . . 38 103 A.9. 08 to 09 . . . . . . . . . . . . . . . . . . . . . . . . 38 104 A.10. 09 to 10 . . . . . . . . . . . . . . . . . . . . . . . . 39 105 A.11. 10 to 11 . . . . . . . . . . . . . . . . . . . . . . . . 39 106 A.12. 11 to 12 . . . . . . . . . . . . . . . . . . . . . . . . 39 107 A.13. 12 to 13 . . . . . . . . . . . . . . . . . . . . . . . . 40 108 A.14. 13 to 14 . . . . . . . . . . . . . . . . . . . . . . . . 40 109 A.15. 14 to 15 . . . . . . . . . . . . . . . . . . . . . . . . 40 110 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 40 111 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 40 113 1. Introduction 115 This document defines a YANG 1.1 [RFC7950] module called "ietf- 116 keystore" that enables centralized configuration of both symmetric 117 and asymmetric keys. The secret value for both key types may be 118 encrypted. Asymmetric keys may be associated with certificates. 119 Notifications are sent when certificates are about to expire. 121 The "ietf-keystore" module defines many "grouping" statements 122 intended for use by other modules that may import it. For instance, 123 there are groupings that defined enabling a key to be either 124 configured locally (within the defining data model) or be a reference 125 to a key in the keystore. 127 Special consideration has been given for systems that have 128 cryptographic hardware, such as a Trusted Protection Module (TPM). 129 These systems are unique in that the cryptographic hardware hides the 130 secret key values. To support such hardware, symmetric keys may have 131 the value "hidden-key" and asymmetric keys may have the value 132 "hidden-private-key". While how such keys are created or destroyed 133 is outside the scope of this document, the keystore can contain 134 entries for such keys, enabling them to be reference by other 135 configuration elements. 137 This document in compliant with Network Management Datastore 138 Architecture (NMDA) [RFC8342]. For instance, keys and associated 139 certificates installed during manufacturing (e.g., for a IDevID 140 [Std-802.1AR-2009] certificate), are expected to appear in 141 (see Section 4). 143 It is not required that a system has an operating system level 144 keystore utility to implement this module. 146 2. Requirements Language 148 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 149 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 150 "OPTIONAL" in this document are to be interpreted as described in BCP 151 14 [RFC2119] [RFC8174] when, and only when, they appear in all 152 capitals, as shown here. 154 3. The Keystore Model 156 3.1. Tree Diagram 158 This section provides a tree diagrams [RFC8340] for the "ietf- 159 keystore" module that presents both the protocol-accessible 160 "keystore" as well the all the groupings intended for external usage. 162 module: ietf-keystore 163 +--rw keystore 164 +--rw asymmetric-keys 165 | +--rw asymmetric-key* [name] 166 | | +--rw name string 167 | | +--rw algorithm 168 | | | iasa:asymmetric-algorithm-type 169 | | +--rw public-key-format? identityref 170 | | +--rw public-key binary 171 | | +--rw private-key-format? identityref 172 | | +--rw (private-key-type) 173 | | | +--:(private-key) 174 | | | | +--rw private-key? binary 175 | | | +--:(hidden-private-key) 176 | | | | +--rw hidden-private-key? empty 177 | | | +--:(encrypted-private-key) 178 | | | +--rw encrypted-private-key 179 | | | +--rw (key-type) 180 | | | | +--:(symmetric-key-ref) 181 | | | | | +--rw symmetric-key-ref? leafref 182 | | | | | {keystore-supported}? 183 | | | | +--:(asymmetric-key-ref) 184 | | | | +--rw asymmetric-key-ref? leafref 185 | | | | {keystore-supported}? 186 | | | +--rw value? binary 187 | | +--rw certificates 188 | | | +--rw certificate* [name] 189 | | | +--rw name string 190 | | | +--rw cert? end-entity-cert-cms 191 | | | +---n certificate-expiration 192 | | | +-- expiration-date yang:date-and-time 193 | | +---x generate-certificate-signing-request 194 | | +---w input 195 | | | +---w subject binary 196 | | | +---w attributes? binary 197 | | +--ro output 198 | | +--ro certificate-signing-request binary 199 | +---x generate-asymmetric-key 200 | +---w input 201 | | +---w algorithm iasa:asymmetric-algorithm-type 202 | | +---w encrypt-with! 203 | | +---w (key-type) 204 | | +--:(symmetric-key-ref) 205 | | | +---w symmetric-key-ref? leafref 206 | | | {keystore-supported}? 207 | | +--:(asymmetric-key-ref) 208 | | +---w asymmetric-key-ref? leafref 209 | | {keystore-supported}? 210 | +--ro output 211 | +--ro algorithm 212 | | iasa:asymmetric-algorithm-type 213 | +--ro public-key-format? identityref 214 | +--ro public-key binary 215 | +--ro private-key-format? identityref 216 | +--ro (private-key-type) 217 | +--:(private-key) 218 | | +--ro private-key? binary 219 | +--:(hidden-private-key) 220 | | +--ro hidden-private-key? empty 221 | +--:(encrypted-private-key) 222 | +--ro encrypted-private-key 223 | +--ro (key-type) 224 | | +--:(symmetric-key-ref) 225 | | | +--ro symmetric-key-ref? leafref 226 | | | {keystore-supported}? 227 | | +--:(asymmetric-key-ref) 228 | | +--ro asymmetric-key-ref? leafref 229 | | {keystore-supported}? 230 | +--ro value? binary 231 +--rw symmetric-keys 232 +--rw symmetric-key* [name] 233 | +--rw name string 234 | +--rw algorithm isa:symmetric-algorithm-type 235 | +--rw key-format? identityref 236 | +--rw (key-type) 237 | +--:(key) 238 | | +--rw key? binary 239 | +--:(hidden-key) 240 | | +--rw hidden-key? empty 241 | +--:(encrypted-key) 242 | +--rw encrypted-key 243 | +--rw (key-type) 244 | | +--:(symmetric-key-ref) 245 | | | +--rw symmetric-key-ref? leafref 246 | | | {keystore-supported}? 247 | | +--:(asymmetric-key-ref) 248 | | +--rw asymmetric-key-ref? leafref 249 | | {keystore-supported}? 250 | +--rw value? binary 251 +---x generate-symmetric-key 252 +---w input 253 | +---w algorithm isa:symmetric-algorithm-type 254 | +---w encrypt-with! 255 | +---w (key-type) 256 | +--:(symmetric-key-ref) 257 | | +---w symmetric-key-ref? leafref 258 | | {keystore-supported}? 259 | +--:(asymmetric-key-ref) 260 | +---w asymmetric-key-ref? leafref 261 | {keystore-supported}? 262 +--ro output 263 +--ro algorithm 264 | isa:symmetric-algorithm-type 265 +--ro key-format? identityref 266 +--ro (key-type) 267 +--:(key) 268 | +--ro key? binary 269 +--:(hidden-key) 270 | +--ro hidden-key? empty 271 +--:(encrypted-key) 272 +--ro encrypted-key 273 +--ro (key-type) 274 | +--:(symmetric-key-ref) 275 | | +--ro symmetric-key-ref? leafref 276 | | {keystore-supported}? 277 | +--:(asymmetric-key-ref) 278 | +--ro asymmetric-key-ref? leafref 279 | {keystore-supported}? 280 +--ro value? binary 282 grouping key-reference-type-grouping 283 +-- (key-type) 284 +--:(symmetric-key-ref) 285 | +-- symmetric-key-ref? 286 | -> /keystore/symmetric-keys/symmetric-key/name 287 | {keystore-supported}? 288 +--:(asymmetric-key-ref) 289 +-- asymmetric-key-ref? 290 -> /keystore/asymmetric-keys/asymmetric-key/name 291 {keystore-supported}? 292 grouping encrypted-value-grouping 293 +-- (key-type) 294 | +--:(symmetric-key-ref) 295 | | +-- symmetric-key-ref? 296 | | -> /keystore/symmetric-keys/symmetric-key/name 297 | | {keystore-supported}? 298 | +--:(asymmetric-key-ref) 299 | +-- asymmetric-key-ref? 300 | -> /keystore/asymmetric-keys/asymmetric-key/name 301 | {keystore-supported}? 302 +-- value? binary 303 grouping symmetric-key-grouping 304 +-- algorithm isa:symmetric-algorithm-type 305 +-- key-format? identityref 306 +-- (key-type) 307 +--:(key) 308 | +-- key? binary 309 +--:(hidden-key) 310 | +-- hidden-key? empty 311 +--:(encrypted-key) 312 +-- encrypted-key 313 +-- (key-type) 314 | +--:(symmetric-key-ref) 315 | | +-- symmetric-key-ref? leafref 316 | | {keystore-supported}? 317 | +--:(asymmetric-key-ref) 318 | +-- asymmetric-key-ref? leafref 319 | {keystore-supported}? 320 +-- value? binary 321 grouping asymmetric-key-pair-grouping 322 +-- algorithm iasa:asymmetric-algorithm-type 323 +-- public-key-format? identityref 324 +-- public-key binary 325 +-- private-key-format? identityref 326 +-- (private-key-type) 327 +--:(private-key) 328 | +-- private-key? binary 329 +--:(hidden-private-key) 330 | +-- hidden-private-key? empty 331 +--:(encrypted-private-key) 332 +-- encrypted-private-key 333 +-- (key-type) 334 | +--:(symmetric-key-ref) 335 | | +-- symmetric-key-ref? leafref 336 | | {keystore-supported}? 337 | +--:(asymmetric-key-ref) 338 | +-- asymmetric-key-ref? leafref 339 | {keystore-supported}? 340 +-- value? binary 341 grouping asymmetric-key-pair-with-cert-grouping 342 +-- algorithm 343 | iasa:asymmetric-algorithm-type 344 +-- public-key-format? identityref 345 +-- public-key binary 346 +-- private-key-format? identityref 347 +-- (private-key-type) 348 | +--:(private-key) 349 | | +-- private-key? binary 350 | +--:(hidden-private-key) 351 | | +-- hidden-private-key? empty 352 | +--:(encrypted-private-key) 353 | +-- encrypted-private-key 354 | +-- (key-type) 355 | | +--:(symmetric-key-ref) 356 | | | +-- symmetric-key-ref? leafref 357 | | | {keystore-supported}? 358 | | +--:(asymmetric-key-ref) 359 | | +-- asymmetric-key-ref? leafref 360 | | {keystore-supported}? 361 | +-- value? binary 362 +-- cert? end-entity-cert-cms 363 +---n certificate-expiration 364 | +-- expiration-date yang:date-and-time 365 +---x generate-certificate-signing-request 366 +---w input 367 | +---w subject binary 368 | +---w attributes? binary 369 +--ro output 370 +--ro certificate-signing-request binary 371 grouping asymmetric-key-pair-with-certs-grouping 372 +-- algorithm 373 | iasa:asymmetric-algorithm-type 374 +-- public-key-format? identityref 375 +-- public-key binary 376 +-- private-key-format? identityref 377 +-- (private-key-type) 378 | +--:(private-key) 379 | | +-- private-key? binary 380 | +--:(hidden-private-key) 381 | | +-- hidden-private-key? empty 382 | +--:(encrypted-private-key) 383 | +-- encrypted-private-key 384 | +-- (key-type) 385 | | +--:(symmetric-key-ref) 386 | | | +-- symmetric-key-ref? leafref 387 | | | {keystore-supported}? 388 | | +--:(asymmetric-key-ref) 389 | | +-- asymmetric-key-ref? leafref 390 | | {keystore-supported}? 391 | +-- value? binary 392 +-- certificates 393 | +-- certificate* [name] 394 | +-- name? string 395 | +-- cert? end-entity-cert-cms 396 | +---n certificate-expiration 397 | +-- expiration-date yang:date-and-time 398 +---x generate-certificate-signing-request 399 +---w input 400 | +---w subject binary 401 | +---w attributes? binary 402 +--ro output 403 +--ro certificate-signing-request binary 404 grouping asymmetric-key-certificate-ref-grouping 405 +-- asymmetric-key? ks:asymmetric-key-ref 406 +-- certificate? leafref 407 grouping local-or-keystore-symmetric-key-grouping 408 +-- (local-or-keystore) 409 +--:(local) {local-definitions-supported}? 410 | +-- local-definition 411 | +-- algorithm isa:symmetric-algorithm-type 412 | +-- key-format? identityref 413 | +-- (key-type) 414 | +--:(key) 415 | | +-- key? binary 416 | +--:(hidden-key) 417 | | +-- hidden-key? empty 418 | +--:(encrypted-key) 419 | +-- encrypted-key 420 | +-- (key-type) 421 | | +--:(symmetric-key-ref) 422 | | | +-- symmetric-key-ref? leafref 423 | | | {keystore-supported}? 424 | | +--:(asymmetric-key-ref) 425 | | +-- asymmetric-key-ref? leafref 426 | | {keystore-supported}? 427 | +-- value? binary 428 +--:(keystore) {keystore-supported}? 429 +-- keystore-reference? ks:symmetric-key-ref 430 grouping local-or-keystore-asymmetric-key-grouping 431 +-- (local-or-keystore) 432 +--:(local) {local-definitions-supported}? 433 | +-- local-definition 434 | +-- algorithm 435 | | iasa:asymmetric-algorithm-type 436 | +-- public-key-format? identityref 437 | +-- public-key binary 438 | +-- private-key-format? identityref 439 | +-- (private-key-type) 440 | +--:(private-key) 441 | | +-- private-key? binary 442 | +--:(hidden-private-key) 443 | | +-- hidden-private-key? empty 444 | +--:(encrypted-private-key) 445 | +-- encrypted-private-key 446 | +-- (key-type) 447 | | +--:(symmetric-key-ref) 448 | | | +-- symmetric-key-ref? leafref 449 | | | {keystore-supported}? 450 | | +--:(asymmetric-key-ref) 451 | | +-- asymmetric-key-ref? leafref 452 | | {keystore-supported}? 453 | +-- value? binary 454 +--:(keystore) {keystore-supported}? 455 +-- keystore-reference? ks:asymmetric-key-ref 456 grouping local-or-keystore-asymmetric-key-with-certs-grouping 457 +-- (local-or-keystore) 458 +--:(local) {local-definitions-supported}? 459 | +-- local-definition 460 | +-- algorithm 461 | | iasa:asymmetric-algorithm-type 462 | +-- public-key-format? identityref 463 | +-- public-key binary 464 | +-- private-key-format? identityref 465 | +-- (private-key-type) 466 | | +--:(private-key) 467 | | | +-- private-key? binary 468 | | +--:(hidden-private-key) 469 | | | +-- hidden-private-key? empty 470 | | +--:(encrypted-private-key) 471 | | +-- encrypted-private-key 472 | | +-- (key-type) 473 | | | +--:(symmetric-key-ref) 474 | | | | +-- symmetric-key-ref? leafref 475 | | | | {keystore-supported}? 476 | | | +--:(asymmetric-key-ref) 477 | | | +-- asymmetric-key-ref? leafref 478 | | | {keystore-supported}? 479 | | +-- value? binary 480 | +-- certificates 481 | | +-- certificate* [name] 482 | | +-- name? string 483 | | +-- cert? end-entity-cert-cms 484 | | +---n certificate-expiration 485 | | +-- expiration-date yang:date-and-time 486 | +---x generate-certificate-signing-request 487 | +---w input 488 | | +---w subject binary 489 | | +---w attributes? binary 490 | +--ro output 491 | +--ro certificate-signing-request binary 492 +--:(keystore) {keystore-supported}? 493 +-- keystore-reference? ks:asymmetric-key-ref 494 grouping local-or-keystore-end-entity-cert-with-key-grouping 495 +-- (local-or-keystore) 496 +--:(local) {local-definitions-supported}? 497 | +-- local-definition 498 | +-- algorithm 499 | | iasa:asymmetric-algorithm-type 500 | +-- public-key-format? identityref 501 | +-- public-key binary 502 | +-- private-key-format? identityref 503 | +-- (private-key-type) 504 | | +--:(private-key) 505 | | | +-- private-key? binary 506 | | +--:(hidden-private-key) 507 | | | +-- hidden-private-key? empty 508 | | +--:(encrypted-private-key) 509 | | +-- encrypted-private-key 510 | | +-- (key-type) 511 | | | +--:(symmetric-key-ref) 512 | | | | +-- symmetric-key-ref? leafref 513 | | | | {keystore-supported}? 514 | | | +--:(asymmetric-key-ref) 515 | | | +-- asymmetric-key-ref? leafref 516 | | | {keystore-supported}? 517 | | +-- value? binary 518 | +-- cert? 519 | | end-entity-cert-cms 520 | +---n certificate-expiration 521 | | +-- expiration-date yang:date-and-time 522 | +---x generate-certificate-signing-request 523 | +---w input 524 | | +---w subject binary 525 | | +---w attributes? binary 526 | +--ro output 527 | +--ro certificate-signing-request binary 528 +--:(keystore) {keystore-supported}? 529 +-- keystore-reference 530 +-- asymmetric-key? ks:asymmetric-key-ref 531 +-- certificate? leafref 532 grouping keystore-grouping 533 +-- asymmetric-keys 534 | +-- asymmetric-key* [name] 535 | | +-- name? string 536 | | +-- algorithm 537 | | | iasa:asymmetric-algorithm-type 538 | | +-- public-key-format? identityref 539 | | +-- public-key binary 540 | | +-- private-key-format? identityref 541 | | +-- (private-key-type) 542 | | | +--:(private-key) 543 | | | | +-- private-key? binary 544 | | | +--:(hidden-private-key) 545 | | | | +-- hidden-private-key? empty 546 | | | +--:(encrypted-private-key) 547 | | | +-- encrypted-private-key 548 | | | +-- (key-type) 549 | | | | +--:(symmetric-key-ref) 550 | | | | | +-- symmetric-key-ref? leafref 551 | | | | | {keystore-supported}? 552 | | | | +--:(asymmetric-key-ref) 553 | | | | +-- asymmetric-key-ref? leafref 554 | | | | {keystore-supported}? 555 | | | +-- value? binary 556 | | +-- certificates 557 | | | +-- certificate* [name] 558 | | | +-- name? string 559 | | | +-- cert? end-entity-cert-cms 560 | | | +---n certificate-expiration 561 | | | +-- expiration-date yang:date-and-time 562 | | +---x generate-certificate-signing-request 563 | | +---w input 564 | | | +---w subject binary 565 | | | +---w attributes? binary 566 | | +--ro output 567 | | +--ro certificate-signing-request binary 568 | +---x generate-asymmetric-key 569 | +---w input 570 | | +---w algorithm iasa:asymmetric-algorithm-type 571 | | +---w encrypt-with! 572 | | +---w (key-type) 573 | | +--:(symmetric-key-ref) 574 | | | +---w symmetric-key-ref? leafref 575 | | | {keystore-supported}? 576 | | +--:(asymmetric-key-ref) 577 | | +---w asymmetric-key-ref? leafref 578 | | {keystore-supported}? 579 | +--ro output 580 | +--ro algorithm 581 | | iasa:asymmetric-algorithm-type 582 | +--ro public-key-format? identityref 583 | +--ro public-key binary 584 | +--ro private-key-format? identityref 585 | +--ro (private-key-type) 586 | +--:(private-key) 587 | | +--ro private-key? binary 588 | +--:(hidden-private-key) 589 | | +--ro hidden-private-key? empty 590 | +--:(encrypted-private-key) 591 | +--ro encrypted-private-key 592 | +--ro (key-type) 593 | | +--:(symmetric-key-ref) 594 | | | +--ro symmetric-key-ref? leafref 595 | | | {keystore-supported}? 596 | | +--:(asymmetric-key-ref) 597 | | +--ro asymmetric-key-ref? leafref 598 | | {keystore-supported}? 599 | +--ro value? binary 600 +-- symmetric-keys 601 +-- symmetric-key* [name] 602 | +-- name? string 603 | +-- algorithm isa:symmetric-algorithm-type 604 | +-- key-format? identityref 605 | +-- (key-type) 606 | +--:(key) 607 | | +-- key? binary 608 | +--:(hidden-key) 609 | | +-- hidden-key? empty 610 | +--:(encrypted-key) 611 | +-- encrypted-key 612 | +-- (key-type) 613 | | +--:(symmetric-key-ref) 614 | | | +-- symmetric-key-ref? leafref 615 | | | {keystore-supported}? 616 | | +--:(asymmetric-key-ref) 617 | | +-- asymmetric-key-ref? leafref 618 | | {keystore-supported}? 619 | +-- value? binary 620 +---x generate-symmetric-key 621 +---w input 622 | +---w algorithm isa:symmetric-algorithm-type 623 | +---w encrypt-with! 624 | +---w (key-type) 625 | +--:(symmetric-key-ref) 626 | | +---w symmetric-key-ref? leafref 627 | | {keystore-supported}? 628 | +--:(asymmetric-key-ref) 629 | +---w asymmetric-key-ref? leafref 630 | {keystore-supported}? 631 +--ro output 632 +--ro algorithm 633 | isa:symmetric-algorithm-type 634 +--ro key-format? identityref 635 +--ro (key-type) 636 +--:(key) 637 | +--ro key? binary 638 +--:(hidden-key) 639 | +--ro hidden-key? empty 640 +--:(encrypted-key) 641 +--ro encrypted-key 642 +--ro (key-type) 643 | +--:(symmetric-key-ref) 644 | | +--ro symmetric-key-ref? leafref 645 | | {keystore-supported}? 646 | +--:(asymmetric-key-ref) 647 | +--ro asymmetric-key-ref? leafref 648 | {keystore-supported}? 649 +--ro value? binary 651 3.2. Example Usage 653 3.2.1. A Keystore Instance 655 The following example illustrates keys in . Please see 656 Section 4 for an example illustrating built-in values in 657 . 659 ========== NOTE: '\' line wrapping per BCP XXX (RFC XXXX) =========== 661 663 665 666 cleartext-symmetric-key 667 aes-256-cbc 668 ct:octet-string-key-format 669 base64encodedvalue== 670 672 673 hidden-symmetric-key 674 aes-256-cbc 675 676 678 679 encrypted-symmetric-key 680 aes-256-cbc 681 ct:encrypted-one-symmetric-key-format 682 683 hidden-asymmetric-key 685 base64encodedvalue== 686 687 689 690 692 693 rsa-asymmetric-key 694 rsa2048 695 ct:subject-public-key-info-format 697 base64encodedvalue== 698 ct:rsa-private-key-format 700 base64encodedvalue== 701 702 703 ex-rsa-cert 704 base64encodedvalue== 705 706 707 709 710 ec-asymmetric-key 711 secp256r1 712 ct:subject-public-key-info-format 714 base64encodedvalue== 715 ct:ec-private-key-format 717 base64encodedvalue== 718 719 720 ex-ec-cert 721 base64encodedvalue== 723 724 725 727 728 hidden-asymmetric-key 729 rsa2048 730 ct:subject-public-key-info-format 732 base64encodedvalue== 733 734 735 736 builtin-idevid-cert 737 738 739 my-ldevid-cert 740 base64encodedvalue== 741 742 743 745 746 encrypted-asymmetric-key 747 secp256r1 748 ct:subject-public-key-info-format 750 base64encodedvalue== 751 ct:encrypted-one-asymmetric-key-format 753 754 encrypted-symmetric-key 756 base64encodedvalue== 757 758 760 761 763 3.2.2. The "generate-symmetric-key" RPC 765 The following example illustrates the "generate-symmetric-key" RPC. 766 The key being referenced is defined in the keystore example above. 768 ========== NOTE: '\' line wrapping per BCP XXX (RFC XXXX) =========== 770 772 773 774 775 776 aes-256-cbc 777 778 hidden-asymmetric-key 780 781 782 783 784 785 787 Following is the complimentary RPC-reply. 789 ========== NOTE: '\' line wrapping per BCP XXX (RFC XXXX) =========== 791 795 796 aes-256-cbc 797 ct:encrypted-one-symmetric-key-format 799 800 hidden-asymmetric-key 802 base64encodedvalue== 803 804 805 807 3.2.3. The "generate-asymmetric-key" RPC 809 The following example illustrates the "generate-asymmetric-key" RPC. 810 The key being referenced is defined in the keystore example above. 812 ========== NOTE: '\' line wrapping per BCP XXX (RFC XXXX) =========== 814 816 817 818 819 820 secp256r1 821 822 encrypted-symmetric-key 824 825 826 827 828 829 831 Following is the complimentary RPC-reply. 833 ========== NOTE: '\' line wrapping per BCP XXX (RFC XXXX) =========== 835 839 840 secp256r1 841 ct:subject-public-key-info-format 843 base64encodedvalue== 844 ct:encrypted-one-asymmetric-key-format 846 847 encrypted-symmetric-key 849 base64encodedvalue== 850 851 852 854 3.2.4. Notable Keystore Groupings 856 The following non-normative module is used by subsequent examples to 857 illustrate groupings defined in the ietf-crypto-types module. 859 module ex-keystore-usage { 860 yang-version 1.1; 862 namespace "http://example.com/ns/example-keystore-usage"; 863 prefix "eku"; 865 import ietf-keystore { 866 prefix ks; 867 reference 868 "RFC XXXX: YANG Data Model for a 'Keystore' Mechanism"; 869 } 871 organization 872 "Example Corporation"; 874 contact 875 "Author: YANG Designer "; 877 description 878 "This module illustrates the grouping in the keystore draft called 879 'local-or-keystore-asymmetric-key-with-certs-grouping'."; 881 revision "YYYY-MM-DD" { 882 description 883 "Initial version"; 884 reference 885 "RFC XXXX: YANG Data Model for a 'Keystore' Mechanism"; 886 } 888 container keystore-usage { 889 description 890 "An illustration of the various keystore groupings."; 892 list just-a-key { 893 key name; 894 leaf name { 895 type string; 896 description 897 "An arbitrary name for this key."; 898 } 899 uses ks:local-or-keystore-asymmetric-key-grouping; 900 description 901 "An asymmetric key, with no certs, that may be configured 902 locally or be a reference to an asymmetric key in the 903 keystore. The intent is to reference just the asymmetric 904 key, not any certificates that may also be associated 905 with the asymmetric key."; 906 } 907 list key-with-certs { 908 key name; 909 leaf name { 910 type string; 911 description 912 "An arbitrary name for this key."; 913 } 914 uses ks:local-or-keystore-asymmetric-key-with-certs-grouping; 915 description 916 "An asymmetric key and its associated certs, that may be 917 configured locally or be a reference to an asymmetric key 918 (and its associated certs) in the keystore."; 919 } 921 list end-entity-cert-with-key { 922 key name; 923 leaf name { 924 type string; 925 description 926 "An arbitrary name for this key."; 927 } 928 uses ks:local-or-keystore-end-entity-cert-with-key-grouping; 929 description 930 "An end-entity certificate, and its associated private key, 931 that may be configured locally or be a reference to a 932 specific certificate (and its associated private key) in 933 the keystore."; 934 } 935 } 937 } 939 The following example illustrates what two configured keys, one local 940 and the other remote, might look like. This example consistent with 941 other examples above (i.e., the referenced key is in an example 942 above). 944 ========== NOTE: '\' line wrapping per BCP XXX (RFC XXXX) =========== 946 949 951 952 a locally-defined key 953 954 rsa2048 955 ct:subject-public-key-info-format 957 base64encodedvalue== 958 ct:rsa-private-key-format 960 base64encodedvalue== 961 962 964 965 a keystore-defined key (and its associated certs) 966 rsa-asymmetric-key 967 969 971 972 a locally-defined key with certs 973 974 rsa2048 975 ct:subject-public-key-info-format 977 base64encodedvalue== 978 ct:rsa-private-key-format 980 base64encodedvalue== 981 982 983 a locally-defined cert 984 base64encodedvalue== 985 986 987 988 990 991 a keystore-defined key (and its associated certs) 992 rsa-asymmetric-key 993 995 997 998 a locally-defined end-entity cert with key 999 1000 rsa2048 1001 ct:subject-public-key-info-format 1003 base64encodedvalue== 1004 ct:rsa-private-key-format 1006 base64encodedvalue== 1007 base64encodedvalue== 1008 1009 1011 1012 a keystore-defined certificate (and its associated key) 1014 1015 rsa-asymmetric-key 1016 ex-rsa-cert 1017 1018 1020 1022 3.3. YANG Module 1024 This YANG module has normative references to [RFC8341] and 1025 [I-D.ietf-netconf-crypto-types], and an informative reference to 1026 [RFC8342]. 1028 file "ietf-keystore@2019-11-20.yang" 1030 module ietf-keystore { 1031 yang-version 1.1; 1032 namespace "urn:ietf:params:xml:ns:yang:ietf-keystore"; 1033 prefix ks; 1035 import ietf-netconf-acm { 1036 prefix nacm; 1037 reference 1038 "RFC 8341: Network Configuration Access Control Model"; 1039 } 1041 import ietf-crypto-types { 1042 prefix ct; 1043 reference 1044 "RFC AAAA: Common YANG Data Types for Cryptography"; 1045 } 1047 //import iana-hash-algs { 1048 // prefix iha; 1049 // reference 1050 // "RFC AAAA: Common YANG Data Types for Cryptography"; 1051 //} 1053 import iana-symmetric-algs { 1054 prefix isa; 1055 reference 1056 "RFC AAAA: Common YANG Data Types for Cryptography"; 1057 } 1059 import iana-asymmetric-algs { 1060 prefix iasa; 1061 reference 1062 "RFC AAAA: Common YANG Data Types for Cryptography"; 1063 } 1065 organization 1066 "IETF NETCONF (Network Configuration) Working Group"; 1068 contact 1069 "WG Web: 1070 WG List: 1071 Author: Kent Watsen "; 1073 description 1074 "This module defines a keystore to centralize management 1075 of security credentials. 1077 Copyright (c) 2019 IETF Trust and the persons identified 1078 as authors of the code. All rights reserved. 1080 Redistribution and use in source and binary forms, with 1081 or without modification, is permitted pursuant to, and 1082 subject to the license terms contained in, the Simplified 1083 BSD License set forth in Section 4.c of the IETF Trust's 1084 Legal Provisions Relating to IETF Documents 1085 (https://trustee.ietf.org/license-info). 1087 This version of this YANG module is part of RFC XXXX 1088 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC 1089 itself for full legal notices. 1091 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1092 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 1093 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 1094 are to be interpreted as described in BCP 14 (RFC 2119) 1095 (RFC 8174) when, and only when, they appear in all 1096 capitals, as shown here."; 1098 revision 2019-11-20 { 1099 description 1100 "Initial version"; 1101 reference 1102 "RFC XXXX: A YANG Data Model for a Keystore"; 1103 } 1105 /****************/ 1106 /* Features */ 1107 /****************/ 1109 feature keystore-supported { 1110 description 1111 "The 'keystore-supported' feature indicates that the server 1112 supports the keystore."; 1113 } 1115 feature local-definitions-supported { 1116 description 1117 "The 'local-definitions-supported' feature indicates that the 1118 server supports locally-defined keys."; 1119 } 1121 feature key-generation { 1122 description 1123 "Indicates that the server supports the actions related to 1124 the life cycling keys in . To be used by 1125 configuration, keys in must be copied to 1126 ."; 1127 } 1129 /****************/ 1130 /* Typedefs */ 1131 /****************/ 1133 typedef symmetric-key-ref { 1134 type leafref { 1135 path "/ks:keystore/ks:symmetric-keys/ks:symmetric-key" 1136 + "/ks:name"; 1137 } 1138 description 1139 "This typedef enables modules to easily define a reference 1140 to a symmetric key stored in the keystore."; 1141 } 1143 typedef asymmetric-key-ref { 1144 type leafref { 1145 path "/ks:keystore/ks:asymmetric-keys/ks:asymmetric-key" 1146 + "/ks:name"; 1148 } 1149 description 1150 "This typedef enables modules to easily define a reference 1151 to an asymmetric key stored in the keystore."; 1152 } 1154 /*****************/ 1155 /* Groupings */ 1156 /*****************/ 1158 grouping key-reference-type-grouping { 1159 description 1160 "A reusable grouping for a choice for the type of key 1161 referenced in the keystore."; 1162 choice key-type { 1163 mandatory true; 1164 description 1165 "A choice between a reference to a symmetric or asymmetric 1166 key in the keystore."; 1167 leaf symmetric-key-ref { 1168 if-feature "keystore-supported"; 1169 type leafref { 1170 path "/ks:keystore/ks:symmetric-keys/ks:symmetric-key/" 1171 + "ks:name"; 1172 } 1173 description 1174 "Identifies a symmetric key used to encrypt this key."; 1175 } 1176 leaf asymmetric-key-ref { 1177 if-feature "keystore-supported"; 1178 type leafref { 1179 path "/ks:keystore/ks:asymmetric-keys/ks:asymmetric-key/" 1180 + "ks:name"; 1181 } 1182 description 1183 "Identifies an asymmetric key used to encrypt this key."; 1184 } 1185 } 1186 } 1188 grouping encrypted-value-grouping { 1189 description 1190 "A reusable grouping for a value that has been encrypted by 1191 a symmetric or asymmetric key in the keystore."; 1192 uses "key-reference-type-grouping"; 1193 leaf value { 1194 type binary; 1195 description 1196 "The private key, encrypted using the specified symmetric 1197 or asymmetric key."; 1198 } 1199 } 1201 grouping symmetric-key-grouping { 1202 description 1203 "This grouping is identical to the one in ietf-crypto-types 1204 except that it adds a case statement enabling the key 1205 value to be encrypted by a symmetric or an asymmetric 1206 key known to the keystore."; 1207 uses ct:symmetric-key-grouping { 1208 augment "key-type" { 1209 description 1210 "Augments a new 'case' statement into the 'choice' 1211 statement defined by the ietf-crypto-types module."; 1212 container encrypted-key { 1213 must "../key-format"; 1214 description 1215 "A container for the encrypted symmetric key value."; 1216 uses encrypted-value-grouping; 1217 } 1218 } 1219 } 1220 } 1222 grouping asymmetric-key-pair-grouping { 1223 description 1224 "This grouping is identical to the one in ietf-crypto-types 1225 except that it adds a case statement enabling the key 1226 value to be encrypted by a symmetric or an asymmetric 1227 key known to the keystore."; 1228 uses ct:asymmetric-key-pair-grouping { 1229 augment "private-key-type" { 1230 description 1231 "Augments a new 'case' statement into the 'choice' 1232 statement defined by the ietf-crypto-types module."; 1233 container encrypted-private-key { 1234 must "../private-key-format"; 1235 description 1236 "A container for the encrypted asymmetric private 1237 key value."; 1238 uses encrypted-value-grouping; 1239 } 1240 } 1241 } 1242 } 1243 grouping asymmetric-key-pair-with-cert-grouping { 1244 description 1245 "This grouping is identical to the one in ietf-crypto-types 1246 except that it adds a case statement enabling the key 1247 value to be encrypted by a symmetric or an asymmetric 1248 key known to the keystore."; 1249 uses ct:asymmetric-key-pair-with-cert-grouping { 1250 augment "private-key-type" { 1251 description 1252 "Augments a new 'case' statement into the 'choice' 1253 statement defined by the ietf-crypto-types module."; 1254 container encrypted-private-key { 1255 must "../private-key-format"; 1256 description 1257 "A container for the encrypted asymmetric private 1258 key value."; 1259 uses encrypted-value-grouping; 1260 } 1261 } 1262 } 1263 } 1265 grouping asymmetric-key-pair-with-certs-grouping { 1266 description 1267 "This grouping is identical to the one in ietf-crypto-types 1268 except that it adds a case statement enabling the key 1269 value to be encrypted by a symmetric or an asymmetric 1270 key known to the keystore."; 1271 uses ct:asymmetric-key-pair-with-certs-grouping { 1272 augment "private-key-type" { 1273 description 1274 "Augments a new 'case' statement into the 'choice' 1275 statement defined by the ietf-crypto-types module."; 1276 container encrypted-private-key { 1277 must "../private-key-format"; 1278 description 1279 "A container for the encrypted asymmetric private 1280 key value."; 1281 uses encrypted-value-grouping; 1282 } 1283 } 1284 } 1285 } 1287 grouping asymmetric-key-certificate-ref-grouping { 1288 leaf asymmetric-key { 1289 type ks:asymmetric-key-ref; 1290 must '../certificate'; 1291 description 1292 "A reference to an asymmetric key in the keystore."; 1293 } 1294 leaf certificate { 1295 type leafref { 1296 path "/ks:keystore/ks:asymmetric-keys/ks:asymmetric-key[ks:" 1297 + "name = current()/../asymmetric-key]/ks:certificates" 1298 + "/ks:certificate/ks:name"; 1299 } 1300 must '../asymmetric-key'; 1301 description 1302 "A reference to a specific certificate of the 1303 asymmetric key in the keystore."; 1304 } 1305 description 1306 "This grouping defines a reference to a specific certificate 1307 associated with an asymmetric key stored in the keystore."; 1308 } 1310 // local-or-keystore-* groupings 1312 grouping local-or-keystore-symmetric-key-grouping { 1313 description 1314 "A grouping that expands to allow the symmetric key to be 1315 either stored locally, within the using data model, or be 1316 a reference to an symmetric key stored in the keystore."; 1317 choice local-or-keystore { 1318 mandatory true; 1319 case local { 1320 if-feature "local-definitions-supported"; 1321 container local-definition { 1322 description 1323 "Container to hold the local key definition."; 1324 uses symmetric-key-grouping; 1325 } 1326 } 1327 case keystore { 1328 if-feature "keystore-supported"; 1329 leaf keystore-reference { 1330 type ks:symmetric-key-ref; 1331 description 1332 "A reference to an symmetric key that exists in 1333 the keystore."; 1334 } 1335 } 1336 description 1337 "A choice between an inlined definition and a definition 1338 that exists in the keystore."; 1339 } 1340 } 1342 grouping local-or-keystore-asymmetric-key-grouping { 1343 description 1344 "A grouping that expands to allow the asymmetric key to be 1345 either stored locally, within the using data model, or be 1346 a reference to an asymmetric key stored in the keystore."; 1347 choice local-or-keystore { 1348 mandatory true; 1349 case local { 1350 if-feature "local-definitions-supported"; 1351 container local-definition { 1352 description 1353 "Container to hold the local key definition."; 1354 uses asymmetric-key-pair-grouping; 1355 } 1356 } 1357 case keystore { 1358 if-feature "keystore-supported"; 1359 leaf keystore-reference { 1360 type ks:asymmetric-key-ref; 1361 description 1362 "A reference to an asymmetric key that exists in 1363 the keystore. The intent is to reference just the 1364 asymmetric key without any regard for any certificates 1365 that may be associated with it."; 1366 } 1367 } 1368 description 1369 "A choice between an inlined definition and a definition 1370 that exists in the keystore."; 1371 } 1372 } 1374 grouping local-or-keystore-asymmetric-key-with-certs-grouping { 1375 description 1376 "A grouping that expands to allow an asymmetric key and its 1377 associated certificates to be either stored locally, within 1378 the using data model, or be a reference to an asymmetric key 1379 (and its associated certificates) stored in the keystore."; 1380 choice local-or-keystore { 1381 mandatory true; 1382 case local { 1383 if-feature "local-definitions-supported"; 1384 container local-definition { 1385 description 1386 "Container to hold the local key definition."; 1387 uses asymmetric-key-pair-with-certs-grouping; 1388 } 1389 } 1390 case keystore { 1391 if-feature "keystore-supported"; 1392 leaf keystore-reference { 1393 type ks:asymmetric-key-ref; 1394 description 1395 "A reference to an asymmetric-key (and all of its 1396 associated certificates) in the keystore."; 1397 } 1398 } 1399 description 1400 "A choice between an inlined definition and a definition 1401 that exists in the keystore."; 1402 } 1403 } 1405 grouping local-or-keystore-end-entity-cert-with-key-grouping { 1406 description 1407 "A grouping that expands to allow an end-entity certificate 1408 (and its associated private key) to be either stored locally, 1409 within the using data model, or be a reference to a specific 1410 certificate in the keystore."; 1411 choice local-or-keystore { 1412 mandatory true; 1413 case local { 1414 if-feature "local-definitions-supported"; 1415 container local-definition { 1416 description 1417 "Container to hold the local key definition."; 1418 uses asymmetric-key-pair-with-cert-grouping; 1419 } 1420 } 1421 case keystore { 1422 if-feature "keystore-supported"; 1423 container keystore-reference { 1424 uses asymmetric-key-certificate-ref-grouping; 1425 description 1426 "A reference to a specific certificate (and its 1427 associated private key) in the keystore."; 1428 } 1429 } 1430 description 1431 "A choice between an inlined definition and a definition 1432 that exists in the keystore."; 1433 } 1435 } 1437 grouping keystore-grouping { 1438 description 1439 "Grouping definition enables use in other contexts. If ever 1440 done, implementations SHOULD augment new 'case' statements 1441 into local-or-keystore 'choice' statements to supply leafrefs 1442 to the new location."; 1443 container asymmetric-keys { 1444 description 1445 "A list of asymmetric keys."; 1446 list asymmetric-key { 1447 key "name"; 1448 description 1449 "An asymmetric key."; 1450 leaf name { 1451 type string; 1452 description 1453 "An arbitrary name for the asymmetric key."; 1454 } 1455 uses ks:asymmetric-key-pair-with-certs-grouping; 1456 } 1457 action generate-asymmetric-key { 1458 //nacm:default-deny-all; 1459 description 1460 "Requests the device to generate an asymmetric key using 1461 the specified key algorithm, optionally encrypted using 1462 a key in the keystore. The output is this RPC can be 1463 used as input to a subsequent configuration request."; 1464 input { 1465 leaf algorithm { 1466 type iasa:asymmetric-algorithm-type; 1467 mandatory true; 1468 description 1469 "The algorithm to be used when generating the key."; 1470 reference 1471 "RFC AAAA: Common YANG Data Types for Cryptography"; 1472 } 1473 container encrypt-with { 1474 presence 1475 "Indicates that the key should be encrypted using 1476 the specified symmetric or asymmetric key. If not 1477 specified, then the private key is not encrypted 1478 when returned."; 1479 description 1480 "A container for the 'key-type' choice."; 1481 uses key-reference-type-grouping; 1482 } 1484 } 1485 output { 1486 uses ks:asymmetric-key-pair-grouping; 1487 } 1488 } // end generate-asymmetric-key 1489 } 1490 container symmetric-keys { 1491 description 1492 "A list of symmetric keys."; 1493 list symmetric-key { 1494 key "name"; 1495 description 1496 "A symmetric key."; 1497 leaf name { 1498 type string; 1499 description 1500 "An arbitrary name for the symmetric key."; 1501 } 1502 uses ks:symmetric-key-grouping; 1503 } 1504 action generate-symmetric-key { 1505 //nacm:default-deny-all; 1506 description 1507 "Requests the device to generate an symmetric key using 1508 the specified key algorithm, optionally encrypted using 1509 a key in the keystore. The output is this RPC can be 1510 used as input to a subsequent configuration request."; 1511 input { 1512 leaf algorithm { 1513 type isa:symmetric-algorithm-type; 1514 mandatory true; 1515 description 1516 "The algorithm to be used when generating the key."; 1517 reference 1518 "RFC AAAA: Common YANG Data Types for Cryptography"; 1519 } 1520 container encrypt-with { 1521 presence 1522 "Indicates that the key should be encrypted using 1523 the specified symmetric or asymmetric key. If not 1524 specified, then the private key is not encrypted 1525 when returned."; 1526 description 1527 "A container for the 'key-type' choice."; 1528 uses key-reference-type-grouping; 1529 } 1530 } 1531 output { 1532 uses ks:symmetric-key-grouping; 1533 } 1534 } // end generate-symmetric-key 1535 } 1536 } // grouping keystore-grouping 1538 /*********************************/ 1539 /* Protocol accessible nodes */ 1540 /*********************************/ 1542 container keystore { 1543 nacm:default-deny-write; 1544 description 1545 "The keystore contains a list of keys."; 1546 uses keystore-grouping; 1547 } 1549 } 1551 1553 4. Support for Built-in Keys 1555 In some implementations, a device's hardware may define some built-in 1556 keys set during the manufacturing process, and/or the operating 1557 system the device runs may dynamically generate some "hidden" keys 1558 upon first boot. As an example, a built-in key may exist in 1559 conjunction with a secure device identity certificate (e.g., an 1560 IDevID certificate). 1562 Built-in keys are expected to be set by a vendor-specific process. 1563 Any ability for operators to modify the built-in keys is outside the 1564 scope of this docuemnt. 1566 As built-in keys are provided by the system (not configuration), they 1567 are present in . The following example illustrates 1568 built-in keys in . 1570 (FIXME: add illustration with origin="system" here) 1572 In order for the built-in keys to be referenced by configuration, 1573 they must first be copied into as the example in 1574 Section 3.2 illustrates for the built-in keys above. Note that this 1575 strategy is chosen, rather then setting "require-instance false" for 1576 the various leafrefs, as built-in keys are relatively few in number 1577 and hence not worth relaxing the validation for. 1579 5. Security Considerations 1581 The YANG module defined in this document is designed to be accessed 1582 via YANG based management protocols, such as NETCONF [RFC6241] and 1583 RESTCONF [RFC8040]. Both of these protocols have mandatory-to- 1584 implement secure transport layers (e.g., SSH, TLS) with mutual 1585 authentication. 1587 The NETCONF access control model (NACM) [RFC8341] provides the means 1588 to restrict access for particular users to a pre-configured subset of 1589 all available protocol operations and content. 1591 There are a number of data nodes defined in this YANG module that are 1592 writable/creatable/deletable (i.e., config true, which is the 1593 default). These data nodes may be considered sensitive or vulnerable 1594 in some network environments. Write operations (e.g., edit-config) 1595 to these data nodes without proper protection can have a negative 1596 effect on network operations. These are the subtrees and data nodes 1597 and their sensitivity/vulnerability: 1599 /: The entire data tree defined by this module is sensitive to 1600 write operations. For instance, the addition or removal of 1601 keys, certificates, etc., can dramatically alter the 1602 implemented security policy. For this reason, the NACM 1603 extension "default-deny-write" has been set for the entire data 1604 tree. 1606 /keystore/asymmetric-keys/asymmetric-key/private-key: When 1607 writing this node, implementations MUST ensure that the 1608 strength of the key being configured is not greater than the 1609 strength of the underlying secure transport connection over 1610 which it is communicated. Implementations SHOULD fail the 1611 write-request if ever the strength of the private key is 1612 greater then the strength of the underlying transport, and 1613 alert the client that the strength of the key may have been 1614 compromised. Additionally, when deleting this node, 1615 implementations SHOULD automatically (without explicit request) 1616 zeroize these keys in the most secure manner available, so as 1617 to prevent the remnants of their persisted storage locations 1618 from being analyzed in any meaningful way. 1620 Some of the readable data nodes in this YANG module may be considered 1621 sensitive or vulnerable in some network environments. It is thus 1622 important to control read access (e.g., via get, get-config, or 1623 notification) to these data nodes. These are the subtrees and data 1624 nodes and their sensitivity/vulnerability: 1626 /keystore/asymmetric-keys/asymmetric-key/private-key: This node 1627 is additionally sensitive to read operations such that, in 1628 normal use cases, it should never be returned to a client. The 1629 best reason for returning this node is to support backup/ 1630 restore type workflows. For this reason, the NACM extension 1631 "default-deny-all" has been set for this data node. 1633 6. IANA Considerations 1635 6.1. The IETF XML Registry 1637 This document registers one URI in the "ns" subregistry of the IETF 1638 XML Registry [RFC3688]. Following the format in [RFC3688], the 1639 following registration is requested: 1641 URI: urn:ietf:params:xml:ns:yang:ietf-keystore 1642 Registrant Contact: The NETCONF WG of the IETF. 1643 XML: N/A, the requested URI is an XML namespace. 1645 6.2. The YANG Module Names Registry 1647 This document registers one YANG module in the YANG Module Names 1648 registry [RFC6020]. Following the format in [RFC6020], the the 1649 following registration is requested: 1651 name: ietf-keystore 1652 namespace: urn:ietf:params:xml:ns:yang:ietf-keystore 1653 prefix: ks 1654 reference: RFC XXXX 1656 7. References 1658 7.1. Normative References 1660 [I-D.ietf-netconf-crypto-types] 1661 Watsen, K. and H. Wang, "Common YANG Data Types for 1662 Cryptography", draft-ietf-netconf-crypto-types-12 (work in 1663 progress), November 2019. 1665 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1666 Requirement Levels", BCP 14, RFC 2119, 1667 DOI 10.17487/RFC2119, March 1997, 1668 . 1670 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1671 the Network Configuration Protocol (NETCONF)", RFC 6020, 1672 DOI 10.17487/RFC6020, October 2010, 1673 . 1675 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1676 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1677 . 1679 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 1680 Access Control Model", STD 91, RFC 8341, 1681 DOI 10.17487/RFC8341, March 2018, 1682 . 1684 7.2. Informative References 1686 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1687 DOI 10.17487/RFC3688, January 2004, 1688 . 1690 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1691 and A. Bierman, Ed., "Network Configuration Protocol 1692 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1693 . 1695 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1696 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1697 . 1699 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1700 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1701 May 2017, . 1703 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 1704 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 1705 . 1707 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1708 and R. Wilton, "Network Management Datastore Architecture 1709 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 1710 . 1712 [Std-802.1AR-2009] 1713 Group, W. -. H. L. L. P. W., "IEEE Standard for Local and 1714 metropolitan area networks - Secure Device Identity", 1715 December 2009, . 1718 Appendix A. Change Log 1720 A.1. 00 to 01 1722 o Replaced the 'certificate-chain' structures with PKCS#7 1723 structures. (Issue #1) 1725 o Added 'private-key' as a configurable data node, and removed the 1726 'generate-private-key' and 'load-private-key' actions. (Issue #2) 1728 o Moved 'user-auth-credentials' to the ietf-ssh-client module. 1729 (Issues #4 and #5) 1731 A.2. 01 to 02 1733 o Added back 'generate-private-key' action. 1735 o Removed 'RESTRICTED' enum from the 'private-key' leaf type. 1737 o Fixed up a few description statements. 1739 A.3. 02 to 03 1741 o Changed draft's title. 1743 o Added missing references. 1745 o Collapsed sections and levels. 1747 o Added RFC 8174 to Requirements Language Section. 1749 o Renamed 'trusted-certificates' to 'pinned-certificates'. 1751 o Changed 'public-key' from config false to config true. 1753 o Switched 'host-key' from OneAsymmetricKey to definition from RFC 1754 4253. 1756 A.4. 03 to 04 1758 o Added typedefs around leafrefs to common keystore paths 1760 o Now tree diagrams reference ietf-netmod-yang-tree-diagrams 1762 o Removed Design Considerations section 1764 o Moved key and certificate definitions from data tree to groupings 1766 A.5. 04 to 05 1768 o Removed trust anchors (now in their own draft) 1770 o Added back global keystore structure 1772 o Added groupings enabling keys to either be locally defined or a 1773 reference to the keystore. 1775 A.6. 05 to 06 1777 o Added feature "local-keys-supported" 1779 o Added nacm:default-deny-all and nacm:default-deny-write 1781 o Renamed generate-asymmetric-key to generate-hidden-key 1783 o Added an install-hidden-key action 1785 o Moved actions inside fo the "asymmetric-key" container 1787 o Moved some groupings to draft-ietf-netconf-crypto-types 1789 A.7. 06 to 07 1791 o Removed a "require-instance false" 1793 o Clarified some description statements 1795 o Improved the keystore-usage examples 1797 A.8. 07 to 08 1799 o Added "local-definition" containers to avoid posibility of the 1800 action/notification statements being under a "case" statement. 1802 o Updated copyright date, boilerplate template, affiliation, folding 1803 algorithm, and reformatted the YANG module. 1805 A.9. 08 to 09 1807 o Added a 'description' statement to the 'must' in the /keystore/ 1808 asymmetric-key node explaining that the descendent values may 1809 exist in only, and that implementation MUST assert 1810 that the values are either configured or that they exist in 1811 . 1813 o Copied above 'must' statement (and description) into the local-or- 1814 keystore-asymmetric-key-grouping, local-or-keystore-asymmetric- 1815 key-with-certs-grouping, and local-or-keystore-end-entity-cert- 1816 with-key-grouping statements. 1818 A.10. 09 to 10 1820 o Updated draft title to match new truststore draft title 1822 o Moved everything under a top-level 'grouping' to enable use in 1823 other contexts. 1825 o Renamed feature from 'local-keys-supported' to 'local-definitions- 1826 supported' (same name used in truststore) 1828 o Removed the either-all-or-none 'must' expressions for the key's 1829 3-tuple values (since the values are now 'mandatory true' in 1830 crypto-types) 1832 o Example updated to reflect 'mandatory true' change in crypto-types 1833 draft 1835 A.11. 10 to 11 1837 o Replaced typedef asymmetric-key-certificate-ref with grouping 1838 asymmetric-key-certificate-ref-grouping. 1840 o Added feature feature 'key-generation'. 1842 o Cloned groupings symmetric-key-grouping, asymmetric-key-pair- 1843 grouping, asymmetric-key-pair-with-cert-grouping, and asymmetric- 1844 key-pair-with-certs-grouping from crypto-keys, augmenting into 1845 each new case statements for values that have been encrypted by 1846 other keys in the keystore. Refactored keystore model to use 1847 these groupings. 1849 o Added new 'symmetric-keys' lists, as a sibling to the existing 1850 'asymmetric-keys' list. 1852 o Added RPCs (not actions) 'generate-symmetric-key' and 'generate- 1853 asymmetric-key' to *return* a (potentially encrypted) key. 1855 A.12. 11 to 12 1857 o Updated to reflect crypto-type's draft using enumerations over 1858 identities. 1860 o Added examples for the 'generate-symmetric-key' and 'generate- 1861 asymmetric-key' RPCs. 1863 o Updated the Introduction section. 1865 A.13. 12 to 13 1867 o Updated examples to incorporate new "key-format" identities. 1869 o Made the two "generate-*-key" RPCs be "action" statements instead. 1871 A.14. 13 to 14 1873 o Updated YANG module and examples to incorporate the new 1874 iana-*-algorithm modules in the crypto-types draft.. 1876 A.15. 14 to 15 1878 o Added new "Support for Built-in Trust Anchors" section. 1880 o Added 'must' expressions asserting that the 'key-format' leaf 1881 whenever an encrypted key is specified. 1883 Acknowledgements 1885 The authors would like to thank for following for lively discussions 1886 on list and in the halls (ordered by first name): Alan Luchuk, Andy 1887 Bierman, Benoit Claise, Bert Wijnen, Balazs Kovacs, David Lamparter, 1888 Eric Voit, Ladislav Lhotka, Liang Xia, Juergen Schoenwaelder, Mahesh 1889 Jethanandani, Martin Bjorklund, Mehmet Ersue, Phil Shafer, Radek 1890 Krejci, Ramkumar Dhanapal, Reshad Rahman, Sean Turner, and Tom Petch. 1892 Author's Address 1894 Kent Watsen 1895 Watsen Networks 1897 EMail: kent+ietf@watsen.net