idnits 2.17.1 draft-ietf-netconf-keystore-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 173 has weird spacing: '...request bin...' == Line 177 has weird spacing: '...gorithm ct:...' == Line 213 has weird spacing: '...request bin...' == Line 218 has weird spacing: '...-- cert ct:...' == Line 222 has weird spacing: '...ate-key uni...' == (3 more instances...) -- The document date (June 4, 2018) is 2152 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-00 -- Possible downref: Non-RFC (?) normative reference: ref. 'ITU.X690.2015' ** Downref: Normative reference to an Informational RFC: RFC 2986 ** Obsolete normative reference: RFC 3447 (Obsoleted by RFC 8017) ** Downref: Normative reference to an Informational RFC: RFC 5915 ** Obsolete normative reference: RFC 6536 (Obsoleted by RFC 8341) -- Obsolete informational reference (is this intentional?): RFC 6125 (Obsoleted by RFC 9525) Summary: 4 errors (**), 0 flaws (~~), 8 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF Working Group K. Watsen 3 Internet-Draft Juniper Networks 4 Intended status: Standards Track June 4, 2018 5 Expires: December 6, 2018 7 YANG Data Model for a Centralized Keystore Mechanism 8 draft-ietf-netconf-keystore-05 10 Abstract 12 This document defines a YANG 1.1 module called "ietf-keystore" that 13 enables centralized configuration of asymmetric keys and their 14 associated certificates, and notification for when configured 15 certificates are about to expire. 17 Editorial Note (To be removed by RFC Editor) 19 This draft contains many placeholder values that need to be replaced 20 with finalized values at the time of publication. This note 21 summarizes all of the substitutions that are needed. No other RFC 22 Editor instructions are specified elsewhere in this document. 24 Artwork in this document contains shorthand references to drafts in 25 progress. Please apply the following replacements: 27 o "VVVV" --> the assigned RFC value for this draft 29 Artwork in this document contains placeholder values for the date of 30 publication of this draft. Please apply the following replacement: 32 o "2018-06-04" --> the publication date of this draft 34 The following Appendix section is to be removed prior to publication: 36 o Appendix A. Change Log 38 Status of This Memo 40 This Internet-Draft is submitted in full conformance with the 41 provisions of BCP 78 and BCP 79. 43 Internet-Drafts are working documents of the Internet Engineering 44 Task Force (IETF). Note that other groups may also distribute 45 working documents as Internet-Drafts. The list of current Internet- 46 Drafts is at https://datatracker.ietf.org/drafts/current/. 48 Internet-Drafts are draft documents valid for a maximum of six months 49 and may be updated, replaced, or obsoleted by other documents at any 50 time. It is inappropriate to use Internet-Drafts as reference 51 material or to cite them other than as "work in progress." 53 This Internet-Draft will expire on December 6, 2018. 55 Copyright Notice 57 Copyright (c) 2018 IETF Trust and the persons identified as the 58 document authors. All rights reserved. 60 This document is subject to BCP 78 and the IETF Trust's Legal 61 Provisions Relating to IETF Documents 62 (https://trustee.ietf.org/license-info) in effect on the date of 63 publication of this document. Please review these documents 64 carefully, as they describe your rights and restrictions with respect 65 to this document. Code Components extracted from this document must 66 include Simplified BSD License text as described in Section 4.e of 67 the Trust Legal Provisions and are provided without warranty as 68 described in the Simplified BSD License. 70 Table of Contents 72 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 73 2. Requirements Language . . . . . . . . . . . . . . . . . . . . 3 74 3. The Keystore Model . . . . . . . . . . . . . . . . . . . . . 4 75 3.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 4 76 3.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 6 77 3.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 12 78 4. Security Considerations . . . . . . . . . . . . . . . . . . . 21 79 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 80 5.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 23 81 5.2. The YANG Module Names Registry . . . . . . . . . . . . . 23 82 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 23 83 6.1. Normative References . . . . . . . . . . . . . . . . . . 23 84 6.2. Informative References . . . . . . . . . . . . . . . . . 24 85 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 26 86 A.1. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 26 87 A.2. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 26 88 A.3. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 26 89 A.4. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 26 90 A.5. 04 to 05 . . . . . . . . . . . . . . . . . . . . . . . . 27 91 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 27 92 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 27 94 1. Introduction 96 This document defines a YANG 1.1 [RFC7950] module called "ietf- 97 keystore" that enables centralized configuration of asymmetric keys 98 and their associated certificates, and notification for when 99 configured certificates are about to expire. 101 This module also defines Six groupings designed for maximum reuse. 102 These groupings include one for the public half of an asymmetric key, 103 one for both the public and private halves of an asymmetric key, one 104 for both halves of an asymmetric key and a list of associated 105 certificates, one for an asymmetric key that may be configured 106 locally or via a reference to an asymmetric key in the keystore, one 107 for a trust anchor certificate and, lastly, one for an end entity 108 certificate. 110 Special consideration has been given for systems that have 111 cryptographic hardware, such as a Trusted Protection Module (TPM). 112 These systems are unique in that the cryptographic hardware 113 completely hides the private keys and must perform all private key 114 operations. To support such hardware, the "private-key" can be the 115 special value "hardware-protected" and the actions "generate-private- 116 key" and "generate-certificate-signing-request" can be used to direct 117 these operations to the hardware . 119 This document in compliant with Network Management Datastore 120 Architecture (NMDA) [RFC8342]. For instance, to support keys and 121 associated certificates installed during manufacturing (e.g., for a 122 IDevID [Std-802.1AR-2009] certificate), it is expected that such data 123 may appear only in . 125 While only asymmetric keys are currently supported, the module has 126 been designed to enable other key types to be introduced in the 127 future. 129 The module does not support protecting the contents of the keystore 130 (e.g., via encryption), though it could be extended to do so in the 131 future. 133 It is not required that a system has an operating system level 134 keystore utility to implement this module. 136 2. Requirements Language 138 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 139 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 140 "OPTIONAL" in this document are to be interpreted as described in BCP 141 14 [RFC2119] [RFC8174] when, and only when, they appear in all 142 capitals, as shown here. 144 3. The Keystore Model 146 3.1. Tree Diagram 148 This section provides a tree diagrams [RFC8340] for the "ietf- 149 keystore" module that presents both the protocol-accessible 150 "keystore" as well the all the groupings intended for external usage. 152 module: ietf-keystore 153 +--rw keystore 154 +--rw asymmetric-keys 155 +--rw asymmetric-key* [name] 156 | +--rw name string 157 | +--rw algorithm 158 | | ct:key-algorithm-ref 159 | +--rw public-key binary 160 | +--rw private-key union 161 | +--rw certificates 162 | | +--rw certificate* [name] 163 | | +--rw name string 164 | | +--rw cert 165 | | | ct:end-entity-cert-cms 166 | | +---n certificate-expiration 167 | | +-- expiration-date? yang:date-and-time 168 | +---x generate-certificate-signing-request 169 | +---w input 170 | | +---w subject binary 171 | | +---w attributes? binary 172 | +--ro output 173 | +--ro certificate-signing-request binary 174 +---x generate-asymmetric-key 175 +---w input 176 +---w name string 177 +---w algorithm ct:key-algorithm-ref 179 grouping end-entity-cert-grouping 180 +-- cert ct:end-entity-cert-cms 181 +---n certificate-expiration 182 +-- expiration-date? yang:date-and-time 183 grouping local-or-keystore-end-entity-certificate-grouping 184 +-- (local-or-keystore) 185 +--:(local) 186 | +-- algorithm ct:key-algorithm-ref 187 | +-- public-key binary 188 | +-- private-key union 189 | +-- cert ct:end-entity-cert-cms 190 | +---n certificate-expiration 191 | +-- expiration-date? yang:date-and-time 192 +--:(keystore) {keystore-implemented}? 193 +-- reference 194 ks:asymmetric-key-certificate-ref 195 grouping local-or-keystore-asymmetric-key-with-certs-grouping 196 +-- (local-or-keystore) 197 +--:(local) 198 | +-- algorithm 199 | | ct:key-algorithm-ref 200 | +-- public-key binary 201 | +-- private-key union 202 | +-- certificates 203 | | +-- certificate* [name] 204 | | +-- name? string 205 | | +-- cert ct:end-entity-cert-cms 206 | | +---n certificate-expiration 207 | | +-- expiration-date? yang:date-and-time 208 | +---x generate-certificate-signing-request 209 | +---w input 210 | | +---w subject binary 211 | | +---w attributes? binary 212 | +--ro output 213 | +--ro certificate-signing-request binary 214 +--:(keystore) {keystore-implemented}? 215 +-- reference 216 ks:asymmetric-key-ref 217 grouping trust-anchor-cert-grouping 218 +-- cert ct:trust-anchor-cert-cms 219 grouping asymmetric-key-pair-grouping 220 +-- algorithm ct:key-algorithm-ref 221 +-- public-key binary 222 +-- private-key union 223 grouping public-key-grouping 224 +-- algorithm ct:key-algorithm-ref 225 +-- public-key binary 226 grouping asymmetric-key-pair-with-certs-grouping 227 +-- algorithm ct:key-algorithm-ref 228 +-- public-key binary 229 +-- private-key union 230 +-- certificates 231 | +-- certificate* [name] 232 | +-- name? string 233 | +-- cert ct:end-entity-cert-cms 234 | +---n certificate-expiration 235 | +-- expiration-date? yang:date-and-time 236 +---x generate-certificate-signing-request 237 +---w input 238 | +---w subject binary 239 | +---w attributes? binary 240 +--ro output 241 +--ro certificate-signing-request binary 242 grouping local-or-keystore-asymmetric-key-grouping 243 +-- (local-or-keystore) 244 +--:(local) 245 | +-- algorithm ct:key-algorithm-ref 246 | +-- public-key binary 247 | +-- private-key union 248 +--:(keystore) {keystore-implemented}? 249 +-- reference ks:asymmetric-key-ref 251 3.2. Example Usage 253 The following example illustrates what a fully configured keystore 254 might look like in , as described by Section 5.3 in 255 [RFC8342]. This datastore view illustrates data set by the 256 manufacturing process alongside conventional configuration. This 257 keystore instance has three keys, two having one associated 258 certificate and one having two associated certificates. 260 263 265 266 ex-rsa-key 267 ct:rsa1024 268 base64encodedvalue== 269 base64encodedvalue== 270 271 272 ex-rsa-cert 273 base64encodedvalue== 274 275 276 278 279 tls-ec-key 280 ct:secp256r1 281 base64encodedvalue== 282 base64encodedvalue== 283 284 285 tls-ec-cert 286 base64encodedvalue== 287 288 289 291 292 tpm-protected-key 293 ct:rsa2048 294 hardware-protected 295 base64encodedvalue== 296 297 298 builtin-idevid-cert 299 base64encodedvalue== 300 301 302 my-ldevid-cert 303 base64encodedvalue== 304 305 306 308 309 311 The following example illustrates the "generate-private-key" action 312 in use with the NETCONF protocol. 314 REQUEST 315 ------- 316 318 319 320 321 322 ex-key-sect571r1 323 325 ct:secp521r1 326 327 328 329 330 331 333 RESPONSE 334 -------- 335 337 338 340 The following example illustrates the "generate-certificate-signing- 341 request" action in use with the NETCONF protocol. 343 REQUEST 344 ------- 345 347 348 349 350 351 ex-key-sect571r1 352 353 base64encodedvalue== 354 base64encodedvalue== 355 356 357 358 359 360 362 RESPONSE 363 -------- 364 366 368 base64encodedvalue== 369 370 372 The following example illustrates the "certificate-expiration" 373 notification in use with the NETCONF protocol. 375 377 2018-05-25T00:01:00Z 378 379 380 381 tpm-protected-key 382 383 384 my-ldevid-cert 385 386 387 2018-08-05T14:18:53-05:00 388 389 390 391 392 393 394 395 397 The following example module has been constructed to illustrate the 398 "local-or-keystore-asymmetric-key-grouping" grouping defined in the 399 "ietf-keystore" module. 401 module ex-keystore-usage { 402 yang-version 1.1; 404 namespace "http://example.com/ns/example-keystore-usage"; 405 prefix "eku"; 407 import ietf-keystore { 408 prefix ks; 409 reference 410 "RFC VVVV: YANG Data Model for a 'Keystore' Mechanism"; 411 } 413 organization 414 "Example Corporation"; 416 contact 417 "Author: YANG Designer "; 419 description 420 "This module illustrates the grouping defined in the keystore 421 draft called 'local-or-keystore-asymmetric-key-grouping'."; 423 revision "YYYY-MM-DD" { 424 description 425 "Initial version"; 426 reference 427 "RFC XXXX: YANG Data Model for a 'Keystore' Mechanism"; 428 } 430 container keys { 431 description 432 "A container of keys."; 433 list key { 434 key name; 435 leaf name { 436 type string; 437 description 438 "An arbitrary name for this key."; 439 } 440 uses ks:local-or-keystore-asymmetric-key-grouping; 441 description 442 "A key which may be configured locally or be a reference to 443 a key in the keystore."; 444 } 445 } 446 } 447 The following example illustrates what two configured keys, one local 448 and the other remote, might look like. This example consistent with 449 other examples above (i.e., the referenced key is in an example 450 above). 452 453 454 locally-defined key 455 457 ct:secp521r1 458 459 base64encodedvalue== 460 base64encodedvalue== 461 462 463 keystore-defined key 464 ex-rsa-key 465 466 468 3.3. YANG Module 470 This YANG module imports modules defined in [RFC6536], [RFC6991], and 471 [I-D.ietf-netconf-crypto-types]. This module uses data types defined 472 in [RFC2986], [RFC3447], [RFC5652], [RFC5915], [RFC6125], and 473 [ITU.X690.2015]. 475 file "ietf-keystore@2018-06-04.yang" 476 module ietf-keystore { 477 yang-version 1.1; 479 namespace "urn:ietf:params:xml:ns:yang:ietf-keystore"; 480 prefix "ks"; 482 import ietf-yang-types { 483 prefix yang; 484 reference 485 "RFC 6991: Common YANG Data Types"; 486 } 488 import ietf-crypto-types { 489 prefix ct; 490 reference 491 "RFC CCCC: Common YANG Data Types for Cryptography"; 492 } 494 organization 495 "IETF NETCONF (Network Configuration) Working Group"; 497 contact 498 "WG Web: 499 WG List: 501 Author: Kent Watsen 502 "; 504 description 505 "This module defines a keystore to centralize management 506 of security credentials. 508 Copyright (c) 2018 IETF Trust and the persons identified 509 as authors of the code. All rights reserved. 511 Redistribution and use in source and binary forms, with 512 or without modification, is permitted pursuant to, and 513 subject to the license terms contained in, the Simplified 514 BSD License set forth in Section 4.c of the IETF Trust's 515 Legal Provisions Relating to IETF Documents 516 (http://trustee.ietf.org/license-info). 518 This version of this YANG module is part of RFC VVVV; see 519 the RFC itself for full legal notices."; 521 revision "2018-06-04" { 522 description 523 "Initial version"; 524 reference 525 "RFC VVVV: YANG Data Model for a 'Keystore' Mechanism"; 526 } 528 // Features 530 feature keystore-implemented { 531 description 532 "The 'keystore-implemented' feature indicates that the server 533 implements the keystore, and therefore groupings defined in 534 this module that reference the keystore are usable."; 535 } 537 // Typedefs 539 typedef asymmetric-key-ref { 540 type leafref { 541 path "/ks:keystore/ks:asymmetric-keys/ks:asymmetric-key" 542 + "/ks:name"; 543 require-instance false; 544 } 545 description 546 "This typedef enables modules to easily define a reference 547 to an asymmetric key stored in the keystore. The require 548 instance attribute is false to enable the referencing of 549 asymmetric keys that exist only in ."; 550 reference 551 "RFC 8342: Network Management Datastore Architecture (NMDA)"; 552 } 554 typedef asymmetric-key-certificate-ref { 555 type leafref { 556 path "/ks:keystore/ks:asymmetric-keys/ks:asymmetric-key" 557 + "/ks:certificates/ks:certificate/ks:name"; 558 require-instance false; 559 } 560 description 561 "This typedef enables modules to easily define a reference 562 to a specific certificate associated with an asymmetric key 563 stored in the keystore. The require instance attribute is 564 false to enable the referencing of certificates that exist 565 only in ."; 566 reference 567 "RFC 8342: Network Management Datastore Architecture (NMDA)"; 568 } 570 // Groupings 571 // 572 // These groupings are factored out more than needed for 573 // reusability purposes. 575 grouping public-key-grouping { 576 description 577 "A public key."; 578 leaf algorithm { 579 type ct:key-algorithm-ref; 580 mandatory true; 581 description 582 "Identifies the key's algorithm. More specifically, 583 this leaf specifies how the 'public-key' binary leaf 584 is encoded."; 585 reference 586 "RFC CCCC: Common YANG Data Types for Cryptography"; 587 } 588 leaf public-key { 589 type binary; 590 mandatory true; 591 description 592 "A binary that contains the value of the public key. The 593 interpretation of the content is defined by the key 594 algorithm. For example, a DSA key is an integer, an RSA 595 key is represented as RSAPublicKey as defined in 596 RFC 3447, and an Elliptic Curve Cryptography (ECC) key 597 is represented using the 'publicKey' described in 598 RFC 5915."; 599 reference 600 "RFC 3447: Public-Key Cryptography Standards (PKCS) #1: 601 RSA Cryptography Specifications Version 2.1. 602 RFC 5915: Elliptic Curve Private Key Structure."; 603 } 604 } 606 grouping asymmetric-key-pair-grouping { 607 description 608 "A private/public key pair."; 609 uses public-key-grouping; 610 leaf private-key { 611 type union { 612 type binary; 613 type enumeration { 614 enum "hardware-protected" { 615 description 616 "The private key is inaccessible due to being 617 protected by a cryptographic hardware module 618 (e.g., a TPM)."; 619 } 620 } 621 } 622 mandatory true; 623 description 624 "A binary that contains the value of the private key. The 625 interpretation of the content is defined by the key 626 algorithm. For example, a DSA key is an integer, an RSA 627 key is represented as RSAPrivateKey as defined in 628 RFC 3447, and an Elliptic Curve Cryptography (ECC) key 629 is represented as ECPrivateKey as defined in RFC 5915."; 630 reference 631 "RFC 3447: Public-Key Cryptography Standards (PKCS) #1: 632 RSA Cryptography Specifications Version 2.1. 633 RFC 5915: Elliptic Curve Private Key Structure."; 634 } 635 } 636 grouping trust-anchor-cert-grouping { 637 description 638 "A certificate, and a notification for when it might expire."; 639 leaf cert { 640 type ct:trust-anchor-cert-cms; 641 mandatory true; 642 description 643 "The binary certificate data for this certificate."; 644 reference 645 "RFC YYYY: Common YANG Data Types for Cryptography"; 646 } 647 } 649 grouping end-entity-cert-grouping { 650 description 651 "A certificate, and a notification for when it might expire."; 652 leaf cert { 653 type ct:end-entity-cert-cms; 654 mandatory true; 655 description 656 "The binary certificate data for this certificate."; 657 reference 658 "RFC YYYY: Common YANG Data Types for Cryptography"; 659 } 660 notification certificate-expiration { 661 description 662 "A notification indicating that the configured certificate 663 is either about to expire or has already expired. When to 664 send notifications is an implementation specific decision, 665 but it is RECOMMENDED that a notification be sent once a 666 month for 3 months, then once a week for four weeks, and 667 then once a day thereafter until the issue is resolved."; 668 leaf expiration-date { 669 type yang:date-and-time; 670 //mandatory true; 671 description 672 "Identifies the expiration date on the certificate."; 673 } 674 } 675 } 677 grouping asymmetric-key-pair-with-certs-grouping { 678 description 679 "A private/public key pair and associated certificates."; 680 uses asymmetric-key-pair-grouping; 681 container certificates { 682 description 683 "Certificates associated with this asymmetric key. 685 More than one certificate supports, for instance, 686 a TPM-protected asymmetric key that has both IDevID 687 and LDevID certificates associated."; 688 list certificate { 689 key name; 690 description 691 "A certificate for this asymmetric key."; 692 leaf name { 693 type string; 694 description 695 "An arbitrary name for the certificate."; 696 } 697 uses end-entity-cert-grouping; 698 } // end certifcate 699 } // end certificates 700 action generate-certificate-signing-request { 701 description 702 "Generates a certificate signing request structure for 703 the associated asymmetric key using the passed subject 704 and attribute values. The specified assertions need 705 to be appropriate for the certificate's use. For 706 example, an entity certificate for a TLS server 707 SHOULD have values that enable clients to satisfy 708 RFC 6125 processing."; 709 input { 710 leaf subject { 711 type binary; 712 mandatory true; 713 description 714 "The 'subject' field per the CertificationRequestInfo 715 structure as specified by RFC 2986, Section 4.1 716 encoded using the ASN.1 distinguished encoding 717 rules (DER), as specified in ITU-T X.690."; 718 reference 719 "RFC 2986: 720 PKCS #10: Certification Request Syntaxi 721 Specification Version 1.7. 722 ITU-T X.690: 723 Information technology - ASN.1 encoding rules: 724 Specification of Basic Encoding Rules (BER), 725 Canonical Encoding Rules (CER) and Distinguished 726 Encoding Rules (DER)."; 727 } 728 leaf attributes { 729 type binary; 730 description 731 "The 'attributes' field from the structure 732 CertificationRequestInfo as specified by RFC 2986, 733 Section 4.1 encoded using the ASN.1 distinguished 734 encoding rules (DER), as specified in ITU-T X.690."; 735 reference 736 "RFC 2986: 737 PKCS #10: Certification Request Syntax 738 Specification Version 1.7. 739 ITU-T X.690: 740 Information technology - ASN.1 encoding rules: 741 Specification of Basic Encoding Rules (BER), 742 Canonical Encoding Rules (CER) and Distinguished 743 Encoding Rules (DER)."; 744 } 745 } 746 output { 747 leaf certificate-signing-request { 748 type binary; 749 mandatory true; 750 description 751 "A CertificationRequest structure as specified by 752 RFC 2986, Section 4.2 encoded using the ASN.1 753 distinguished encoding rules (DER), as specified 754 in ITU-T X.690."; 755 reference 756 "RFC 2986: 757 PKCS #10: Certification Request Syntax 758 Specification Version 1.7. 759 ITU-T X.690: 760 Information technology - ASN.1 encoding rules: 761 Specification of Basic Encoding Rules (BER), 762 Canonical Encoding Rules (CER) and Distinguished 763 Encoding Rules (DER)."; 765 } 766 } // end output 767 } // end generate-certificate-signing-request 768 } 770 grouping local-or-keystore-asymmetric-key-grouping { 771 description 772 "A grouping that expands to allow the key to be either stored 773 locally within the using data model, or be a reference to an 774 asymmetric key stored in the keystore."; 775 choice local-or-keystore { 776 mandatory true; 777 case local { 778 uses asymmetric-key-pair-grouping; 779 } 780 case keystore { 781 if-feature "keystore-implemented"; 782 leaf reference { 783 type ks:asymmetric-key-ref; 784 mandatory true; 785 description 786 "A reference to a value that exists in the keystore."; 787 } 788 } 789 description 790 "A choice between an inlined definition and a definition 791 that exists in the keystore."; 792 } 793 } 795 grouping local-or-keystore-asymmetric-key-with-certs-grouping { 796 description 797 "A grouping that expands to allow the key to be either stored 798 locally within the using data model, or be a reference to an 799 asymmetric key stored in the keystore."; 800 choice local-or-keystore { 801 mandatory true; 802 case local { 803 uses asymmetric-key-pair-with-certs-grouping; 804 } 805 case keystore { 806 if-feature "keystore-implemented"; 807 leaf reference { 808 type ks:asymmetric-key-ref; 809 mandatory true; 810 description 811 "A reference to a value that exists in the keystore."; 812 } 813 } 814 description 815 "A choice between an inlined definition and a definition 816 that exists in the keystore."; 817 } 818 } 820 grouping local-or-keystore-end-entity-certificate-grouping { 821 description 822 "A grouping that expands to allow the end-entity certificate 823 (and the associated private key) to be either stored locally 824 within the using data model, or be a reference to a specific 825 certificate in the keystore."; 826 choice local-or-keystore { 827 mandatory true; 828 case local { 829 uses ks:asymmetric-key-pair-grouping; 830 uses ks:end-entity-cert-grouping; 831 } 832 case keystore { 833 if-feature "keystore-implemented"; 834 leaf reference { 835 type ks:asymmetric-key-certificate-ref; 836 mandatory true; 837 description 838 "A reference to a value that exists in the keystore."; 839 } 840 } 841 description 842 "A choice between an inlined definition and a definition 843 that exists in the keystore."; 844 } 845 } 847 // protocol accessible nodes 849 container keystore { 850 description 851 "The keystore contains a list of keys."; 853 container asymmetric-keys { 854 description 855 "A list of asymmetric keys."; 856 list asymmetric-key { 857 key name; 858 description 859 "An asymmetric key."; 860 leaf name { 861 type string; 862 description 863 "An arbitrary name for the asymmetric key."; 864 } 865 uses asymmetric-key-pair-with-certs-grouping; 866 } // end asymmetric-key 868 action generate-asymmetric-key { 869 description 870 "Requests the device to generate an asymmetric key using 871 the specified asymmetric key algorithm. This action is 872 primarily to support cryptographic processors that must 873 generate the asymmetric key themselves. The resulting 874 asymmetric key is considered operational state and hence 875 present only in ."; 877 input { 878 leaf name { 879 type string; 880 mandatory true; 881 description 882 "The name the asymmetric key should have when listed 883 in /keystore/asymmetric-keys/asymmetric-key, in 884 ."; 885 } 886 leaf algorithm { 887 type ct:key-algorithm-ref; 888 mandatory true; 889 description 890 "The algorithm to be used when generating the 891 asymmetric key."; 892 reference 893 "RFC CCCC: Common YANG Data Types for Cryptography"; 894 } 895 } 896 } // end generate-asymmetric-key 897 } // end asymmetric-keys 898 } // end keystore 900 } 901 903 4. Security Considerations 905 The YANG module defined in this document is designed to be accessed 906 via YANG based management protocols, such as NETCONF [RFC6241] and 907 RESTCONF [RFC8040]. Both of these protocols have mandatory-to- 908 implement secure transport layers (e.g., SSH, TLS) with mutual 909 authentication. 911 The NETCONF access control model (NACM) [RFC6536] provides the means 912 to restrict access for particular users to a pre-configured subset of 913 all available protocol operations and content. 915 There are a number of data nodes defined in this YANG module that are 916 writable/creatable/deletable (i.e., config true, which is the 917 default). These data nodes may be considered sensitive or vulnerable 918 in some network environments. Write operations (e.g., edit-config) 919 to these data nodes without proper protection can have a negative 920 effect on network operations. These are the subtrees and data nodes 921 and their sensitivity/vulnerability: 923 /: The entire data tree defined by this module is sensitive to 924 write operations. For instance, the addition or removal of 925 keys, certificates, trusted anchors, etc., can dramatically 926 alter the implemented security policy. However, no NACM 927 annotations are applied as the data SHOULD be editable by users 928 other than a designated 'recovery session'. 930 /keystore/asymmetric-keys/asymmetric-key/private-key: When 931 writing this node, implementations MUST ensure that the 932 strength of the key being configured is not greater than the 933 strength of the underlying secure transport connection over 934 which it is communicated. Implementations SHOULD fail the 935 write-request if ever the strength of the private key is 936 greater then the strength of the underlying transport, and 937 alert the client that the strength of the key may have been 938 compromised. Additionally, when deleting this node, 939 implementations SHOULD automatically (without explicit request) 940 zeroize these keys in the most secure manner available, so as 941 to prevent the remnants of their persisted storage locations 942 from being analyzed in any meaningful way. 944 Some of the readable data nodes in this YANG module may be considered 945 sensitive or vulnerable in some network environments. It is thus 946 important to control read access (e.g., via get, get-config, or 947 notification) to these data nodes. These are the subtrees and data 948 nodes and their sensitivity/vulnerability: 950 /keystore/asymmetric-keys/asymmetric-key/private-key: This node 951 is additionally sensitive to read operations such that, in 952 normal use cases, it should never be returned to a client. The 953 best reason for returning this node is to support backup/ 954 restore type workflows. However, no NACM annotations are 955 applied as the data SHOULD be editable by users other than a 956 designated 'recovery session'. 958 Some of the operations in this YANG module may be considered 959 sensitive or vulnerable in some network environments. It is thus 960 important to control access to these operations. These are the 961 operations and their sensitivity/vulnerability: 963 generate-certificate-signing-request: For this action, it is 964 RECOMMENDED that implementations assert channel binding 965 [RFC5056], so as to ensure that the application layer that sent 966 the request is the same as the device authenticated when the 967 secure transport layer was established. 969 This document uses PKCS #10 [RFC2986] for the "generate-certificate- 970 signing-request" action. The use of Certificate Request Message 971 Format (CRMF) [RFC4211] was considered, but is was unclear if there 972 was market demand for it. If it is desired to support CRMF in the 973 future, placing a "choice" statement in both the input and output 974 statements, along with an "if-feature" statement on the CRMF option, 975 would enable a backwards compatible solution. 977 5. IANA Considerations 979 5.1. The IETF XML Registry 981 This document registers one URI in the IETF XML registry [RFC3688]. 982 Following the format in [RFC3688], the following registration is 983 requested: 985 URI: urn:ietf:params:xml:ns:yang:ietf-keystore 986 Registrant Contact: The NETCONF WG of the IETF. 987 XML: N/A, the requested URI is an XML namespace. 989 5.2. The YANG Module Names Registry 991 This document registers one YANG module in the YANG Module Names 992 registry [RFC6020]. Following the format in [RFC6020], the the 993 following registration is requested: 995 name: ietf-keystore 996 namespace: urn:ietf:params:xml:ns:yang:ietf-keystore 997 prefix: ks 998 reference: RFC VVVV 1000 6. References 1002 6.1. Normative References 1004 [I-D.ietf-netconf-crypto-types] 1005 Watsen, K., "Common YANG Data Types for Cryptography", 1006 draft-ietf-netconf-crypto-types-00 (work in progress), 1007 June 2018. 1009 [ITU.X690.2015] 1010 International Telecommunication Union, "Information 1011 Technology - ASN.1 encoding rules: Specification of Basic 1012 Encoding Rules (BER), Canonical Encoding Rules (CER) and 1013 Distinguished Encoding Rules (DER)", ITU-T Recommendation 1014 X.690, ISO/IEC 8825-1, August 2015, 1015 . 1017 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1018 Requirement Levels", BCP 14, RFC 2119, 1019 DOI 10.17487/RFC2119, March 1997, 1020 . 1022 [RFC2986] Nystrom, M. and B. Kaliski, "PKCS #10: Certification 1023 Request Syntax Specification Version 1.7", RFC 2986, 1024 DOI 10.17487/RFC2986, November 2000, 1025 . 1027 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 1028 Standards (PKCS) #1: RSA Cryptography Specifications 1029 Version 2.1", RFC 3447, DOI 10.17487/RFC3447, February 1030 2003, . 1032 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 1033 RFC 5652, DOI 10.17487/RFC5652, September 2009, 1034 . 1036 [RFC5915] Turner, S. and D. Brown, "Elliptic Curve Private Key 1037 Structure", RFC 5915, DOI 10.17487/RFC5915, June 2010, 1038 . 1040 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1041 the Network Configuration Protocol (NETCONF)", RFC 6020, 1042 DOI 10.17487/RFC6020, October 2010, 1043 . 1045 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 1046 Protocol (NETCONF) Access Control Model", RFC 6536, 1047 DOI 10.17487/RFC6536, March 2012, 1048 . 1050 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 1051 RFC 6991, DOI 10.17487/RFC6991, July 2013, 1052 . 1054 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1055 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1056 . 1058 6.2. Informative References 1060 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1061 DOI 10.17487/RFC3688, January 2004, 1062 . 1064 [RFC4211] Schaad, J., "Internet X.509 Public Key Infrastructure 1065 Certificate Request Message Format (CRMF)", RFC 4211, 1066 DOI 10.17487/RFC4211, September 2005, 1067 . 1069 [RFC5056] Williams, N., "On the Use of Channel Bindings to Secure 1070 Channels", RFC 5056, DOI 10.17487/RFC5056, November 2007, 1071 . 1073 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 1074 Verification of Domain-Based Application Service Identity 1075 within Internet Public Key Infrastructure Using X.509 1076 (PKIX) Certificates in the Context of Transport Layer 1077 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 1078 2011, . 1080 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1081 and A. Bierman, Ed., "Network Configuration Protocol 1082 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1083 . 1085 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1086 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1087 . 1089 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1090 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1091 May 2017, . 1093 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 1094 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 1095 . 1097 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1098 and R. Wilton, "Network Management Datastore Architecture 1099 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 1100 . 1102 [Std-802.1AR-2009] 1103 IEEE SA-Standards Board, "IEEE Standard for Local and 1104 metropolitan area networks - Secure Device Identity", 1105 December 2009, . 1108 Appendix A. Change Log 1110 A.1. 00 to 01 1112 o Replaced the 'certificate-chain' structures with PKCS#7 1113 structures. (Issue #1) 1115 o Added 'private-key' as a configurable data node, and removed the 1116 'generate-private-key' and 'load-private-key' actions. (Issue #2) 1118 o Moved 'user-auth-credentials' to the ietf-ssh-client module. 1119 (Issues #4 and #5) 1121 A.2. 01 to 02 1123 o Added back 'generate-private-key' action. 1125 o Removed 'RESTRICTED' enum from the 'private-key' leaf type. 1127 o Fixed up a few description statements. 1129 A.3. 02 to 03 1131 o Changed draft's title. 1133 o Added missing references. 1135 o Collapsed sections and levels. 1137 o Added RFC 8174 to Requirements Language Section. 1139 o Renamed 'trusted-certificates' to 'pinned-certificates'. 1141 o Changed 'public-key' from config false to config true. 1143 o Switched 'host-key' from OneAsymmetricKey to definition from RFC 1144 4253. 1146 A.4. 03 to 04 1148 o Added typedefs around leafrefs to common keystore paths 1150 o Now tree diagrams reference ietf-netmod-yang-tree-diagrams 1152 o Removed Design Considerations section 1154 o Moved key and certificate definitions from data tree to groupings 1156 A.5. 04 to 05 1158 o FIXME 1160 o FIXME 1162 o FIXME 1164 Acknowledgements 1166 The authors would like to thank for following for lively discussions 1167 on list and in the halls (ordered by last name): Andy Bierman, Martin 1168 Bjorklund, Benoit Claise, Mehmet Ersue, Balazs Kovacs, David 1169 Lamparter, Alan Luchuk, Ladislav Lhotka, Mahesh Jethanandani, Radek 1170 Krejci, Reshad Rahman, Tom Petch, Juergen Schoenwaelder, Phil Shafer, 1171 Sean Turner, Eric Voit, Bert Wijnen, and Liang Xia. 1173 Author's Address 1175 Kent Watsen 1176 Juniper Networks 1178 EMail: kwatsen@juniper.net