idnits 2.17.1 draft-ietf-netconf-keystore-04.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 157 has weird spacing: '...rw name str...' == Line 158 has weird spacing: '...rw data bin...' == Line 163 has weird spacing: '...rw name str...' == Line 164 has weird spacing: '...rw data bin...' == Line 169 has weird spacing: '...on-date yan...' == (3 more instances...) -- The document date (October 30, 2017) is 2362 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) == Unused Reference: 'RFC4211' is defined on line 1108, but no explicit reference was found in the text == Unused Reference: 'RFC5914' is defined on line 1117, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'ITU.X690.1994' ** Downref: Normative reference to an Informational RFC: RFC 2315 ** 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) == Outdated reference: A later version (-06) exists of draft-ietf-netmod-yang-tree-diagrams-02 Summary: 5 errors (**), 0 flaws (~~), 10 warnings (==), 2 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 October 30, 2017 5 Expires: May 3, 2018 7 YANG Data Model for a "Keystore" Mechanism 8 draft-ietf-netconf-keystore-04 10 Abstract 12 This document defines a YANG module called a "keystore", containing 13 pinned certificates and pinned SSH host-keys. The module also 14 defines a grouping for configuring public key pairs and a grouping 15 for configuring certificates. The module also defines a notification 16 that a system can use when one of its configured certificates is 17 about to expire. 19 Editorial Note (To be removed by RFC Editor) 21 This draft contains many placeholder values that need to be replaced 22 with finalized values at the time of publication. This note 23 summarizes all of the substitutions that are needed. No other RFC 24 Editor instructions are specified elsewhere in this document. 26 Artwork in this document contains shorthand references to drafts in 27 progress. Please apply the following replacements: 29 o "VVVV" --> the assigned RFC value for this draft 31 Artwork in this document contains placeholder values for the date of 32 publication of this draft. Please apply the following replacement: 34 o "2017-10-30" --> the publication date of this draft 36 The following Appendix section is to be removed prior to publication: 38 o Appendix A. Change Log 40 Status of This Memo 42 This Internet-Draft is submitted in full conformance with the 43 provisions of BCP 78 and BCP 79. 45 Internet-Drafts are working documents of the Internet Engineering 46 Task Force (IETF). Note that other groups may also distribute 47 working documents as Internet-Drafts. The list of current Internet- 48 Drafts is at https://datatracker.ietf.org/drafts/current/. 50 Internet-Drafts are draft documents valid for a maximum of six months 51 and may be updated, replaced, or obsoleted by other documents at any 52 time. It is inappropriate to use Internet-Drafts as reference 53 material or to cite them other than as "work in progress." 55 This Internet-Draft will expire on May 3, 2018. 57 Copyright Notice 59 Copyright (c) 2017 IETF Trust and the persons identified as the 60 document authors. All rights reserved. 62 This document is subject to BCP 78 and the IETF Trust's Legal 63 Provisions Relating to IETF Documents 64 (https://trustee.ietf.org/license-info) in effect on the date of 65 publication of this document. Please review these documents 66 carefully, as they describe your rights and restrictions with respect 67 to this document. Code Components extracted from this document must 68 include Simplified BSD License text as described in Section 4.e of 69 the Trust Legal Provisions and are provided without warranty as 70 described in the Simplified BSD License. 72 Table of Contents 74 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 75 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 3 76 2. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . . . 4 77 3. Example Usage . . . . . . . . . . . . . . . . . . . . . . . . 5 78 4. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 10 79 5. Security Considerations . . . . . . . . . . . . . . . . . . . 21 80 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 81 6.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 22 82 6.2. The YANG Module Names Registry . . . . . . . . . . . . . 22 83 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 23 84 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 23 85 8.1. Normative References . . . . . . . . . . . . . . . . . . 23 86 8.2. Informative References . . . . . . . . . . . . . . . . . 24 87 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 26 88 A.1. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 26 89 A.2. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 26 90 A.3. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 26 91 A.4. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 26 92 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 27 94 1. Introduction 96 This document defines a YANG [RFC7950] module for a system-level 97 mechanism, herein called a "keystore". The keystore provides a 98 centralized location for security sensitive data, as described below. 100 This module has the following characteristics: 102 o A 'grouping' for a public/private key pair, and an 'action' for 103 requesting the system to generate a new private key. 105 o A 'grouping' for a list of certificates that might be associated 106 with a public/private key pair, and an 'action' the requesting a 107 system to generate a certificate signing request. 109 o An unordered list of pinned certificate sets, where each pinned 110 certificate set contains an unordered list of pinned certificates. 111 This structure enables a server to use specific sets of pinned 112 certificates on a case-by-case basis. For instance, one set of 113 pinned certificates might be used by an HTTPS-client when 114 connecting to particular HTTPS servers, while another set of 115 pinned certificates might be used by a server when authenticating 116 client connections (e.g., certificate-based client 117 authentication). 119 o An unordered list of pinned SSH host key sets, where each pinned 120 SSH host key set contains an unordered list of pinned SSH host 121 keys. This structure enables a server to use specific sets of 122 pinned SSH host-keys on a case-by-case basis. For instance, SSH 123 clients can be configured to use different sets of pinned SSH host 124 keys when connecting to different SSH servers. 126 o A notification to indicate when a certificate is about to expire. 128 Special consideration has been given for systems that have Trusted 129 Protection Modules (TPMs). These systems are unique in that the TPM 130 must be directed to generate new keys (it is not possible to load a 131 key into a TPM) and it is not possible to backup/restore the TPM's 132 private keys as configuration. 134 It is not required that a system has an operating system level 135 keystore utility to implement this module. 137 1.1. Requirements Language 139 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 140 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 141 "OPTIONAL" in this document are to be interpreted as described in BCP 142 14 [RFC2119] [RFC8174] when, and only when, they appear in all 143 capitals, as shown here. 145 2. Tree Diagram 147 The following tree diagram [I-D.ietf-netmod-yang-tree-diagrams] 148 provides an overview of the data model for the "ietf-keystore" 149 module. 151 module: ietf-keystore 152 +--rw keystore 153 +--rw pinned-certificates* [name] 154 | +--rw name string 155 | +--rw description? string 156 | +--rw pinned-certificate* [name] 157 | +--rw name string 158 | +--rw data binary 159 +--rw pinned-host-keys* [name] 160 +--rw name string 161 +--rw description? string 162 +--rw pinned-host-key* [name] 163 +--rw name string 164 +--rw data binary 166 notifications: 167 +---n certificate-expiration 168 +--ro certificate instance-identifier 169 +--ro expiration-date yang:date-and-time 171 grouping certificate-grouping 172 +---- certificates 173 | +---- certificate* [name] 174 | +---- name? string 175 | +---- value? binary 176 +---x generate-certificate-signing-request 177 +---w input 178 | +---w subject binary 179 | +---w attributes? binary 180 +--ro output 181 +--ro certificate-signing-request binary 182 grouping private-key-grouping 183 +---- algorithm? identityref 184 +---- private-key? union 185 +---- public-key? binary 186 +---x generate-private-key 187 +---w input 188 +---w algorithm identityref 190 3. Example Usage 192 The following example illustrates what a configured keystore might 193 look like. 195 197 198 199 manufacturers-root-ca-certs 200 201 Certificates built into the device for authenticating 202 manufacturer-signed objects, such as TLS server certificates, 203 vouchers, etc.. Note, though listed here, these are not 204 configurable; any attempt to do so will be denied. 205 206 207 Manufacturer Root CA cert 1 208 base64encodedvalue== 209 210 211 Manufacturer Root CA cert 2 212 base64encodedvalue== 213 214 216 217 218 explicitly-trusted-client-certs 219 220 Specific client authentication certificates for explicitly 221 trusted clients. These are needed for client certificates 222 that are not signed by a pinned CA. 223 224 225 George Jetson 226 base64encodedvalue== 227 228 230 231 232 explicitly-trusted-server-certs 233 234 Specific server authentication certificates for explicitly 235 trusted servers. These are needed for server certificates 236 that are not signed by a pinned CA. 237 238 239 Fred Flintstone 240 base64encodedvalue== 241 242 244 245 246 deployment-specific-ca-certs 247 248 Trust anchors (i.e. CA certs) that are used to authenticate 249 client connections. Clients are authenticated if their 250 certificate has a chain of trust to one of these configured 251 CA certificates. 252 253 254 ca.example.com 255 base64encodedvalue== 256 257 259 260 261 common-ca-certs 262 263 Trusted certificates to authenticate common HTTPS servers. 264 These certificates are similar to those that might be 265 shipped with a web browser. 266 267 268 ex-certificate-authority 269 base64encodedvalue== 270 271 273 274 275 explicitly-trusted-ssh-host-keys 276 277 Trusted SSH host keys used to authenticate SSH servers. 278 These host keys would be analogous to those stored in 279 a known_hosts file in OpenSSH. 280 281 282 corp-fw1 283 base64encodedvalue== 284 285 287 289 The following example illustrates the "certificate-expiration" 290 notification in use with the NETCONF protocol. 292 [ note: '\' line wrapping for formatting only] 294 296 2016-07-08T00:01:00Z 297 299 301 /ks:keystore/ks:keys/ks:key[ks:name='ex-rsa-key']/ks:certifica\ 302 tes/ks:certificate[ks:name='ex-rsa-cert'] 303 304 2016-08-08T14:18:53-05:00 305 306 308 The following example module has been constructed to illustrate the 309 groupings defined in the "ietf-keystore" module. 311 module ex-keystore-usage { 312 yang-version 1.1; 314 namespace "http://example.com/ns/example-keystore-usage"; 315 prefix "eku"; 317 import ietf-keystore { 318 prefix ks; 319 reference 320 "RFC VVVV: YANG Data Model for a 'Keystore' Mechanism"; 321 } 323 organization 324 "IETF NETCONF (Network Configuration) Working Group"; 326 contact 327 "WG Web: 328 WG List: 329 Author: Kent Watsen "; 331 description 332 "This module uses the groupings defines the keystore draft 333 for illustration."; 335 revision "YYYY-MM-DD" { 336 description 337 "Initial version"; 338 } 340 container key { 341 uses ks:private-key-grouping; 342 uses ks:certificate-grouping; 343 description 344 "A container of certificates, and an action to generate 345 a certificate signing request."; 346 } 347 } 349 The following example illustrates what a configured key might look 350 like. This example uses the "ex-keystore-usage" module above. 352 [ note: '\' line wrapping for formatting only] 354 355 ks:\ 356 secp521r1 357 base64encodedvalue== 358 base64encodedvalue== 359 360 361 domain certificate 362 base64encodedvalue== 363 364 365 367 The following example illustrates the "generate-certificate-signing- 368 request" action in use with the NETCONF protocol. This example uses 369 the "ex-keystore-usage" module above. 371 REQUEST 372 ------- 373 374 375 376 377 base64encodedvalue== 378 base64encodedvalue== 379 380 381 382 384 RESPONSE 385 -------- 386 388 390 base64encodedvalue== 391 392 394 The following example illustrates the "generate-private-key" action 395 in use with the NETCONF protocol. This example uses the "ex- 396 keystore-usage" module above. 398 REQUEST 399 ------- 400 [ note: '\' line wrapping for formatting only] 402 404 405 406 407 ks:secp521r1 409 410 411 412 414 RESPONSE 415 -------- 416 418 419 421 4. YANG Module 423 This YANG module imports modules defined in [RFC6536] and [RFC6991]. 424 This module uses data types defined in [RFC2315], [RFC2986], 425 [RFC3447], [RFC4253], [RFC5280], [RFC5915], and [ITU.X690.1994]. 426 This module uses algorithms defined in [RFC3447] and [RFC5480]. 428 file "ietf-keystore@2017-10-30.yang" 429 module ietf-keystore { 430 yang-version 1.1; 432 namespace "urn:ietf:params:xml:ns:yang:ietf-keystore"; 433 prefix "ks"; 435 import ietf-yang-types { 436 prefix yang; 437 reference 438 "RFC 6991: Common YANG Data Types"; 439 } 441 import ietf-netconf-acm { 442 prefix nacm; 443 reference 444 "RFC 6536: Network Configuration Protocol (NETCONF) Access 445 Control Model"; 447 } 449 organization 450 "IETF NETCONF (Network Configuration) Working Group"; 452 contact 453 "WG Web: 454 WG List: 456 Author: Kent Watsen 457 "; 459 description 460 "This module defines a keystore to centralize management 461 of security credentials. 463 Copyright (c) 2017 IETF Trust and the persons identified 464 as authors of the code. All rights reserved. 466 Redistribution and use in source and binary forms, with 467 or without modification, is permitted pursuant to, and 468 subject to the license terms contained in, the Simplified 469 BSD License set forth in Section 4.c of the IETF Trust's 470 Legal Provisions Relating to IETF Documents 471 (http://trustee.ietf.org/license-info). 473 This version of this YANG module is part of RFC VVVV; see 474 the RFC itself for full legal notices."; 476 revision "2017-10-30" { 477 description 478 "Initial version"; 479 reference 480 "RFC VVVV: YANG Data Model for a 'Keystore' Mechanism"; 481 } 483 // Identities 485 identity key-algorithm { 486 description 487 "Base identity from which all key-algorithms are derived."; 488 } 490 identity rsa1024 { 491 base key-algorithm; 492 description 493 "The RSA algorithm using a 1024-bit key."; 495 reference 496 "RFC3447: Public-Key Cryptography Standards (PKCS) #1: 497 RSA Cryptography Specifications Version 2.1."; 498 } 500 identity rsa2048 { 501 base key-algorithm; 502 description 503 "The RSA algorithm using a 2048-bit key."; 504 reference 505 "RFC3447: Public-Key Cryptography Standards (PKCS) #1: 506 RSA Cryptography Specifications Version 2.1."; 507 } 509 identity rsa3072 { 510 base key-algorithm; 511 description 512 "The RSA algorithm using a 3072-bit key."; 513 reference 514 "RFC3447: Public-Key Cryptography Standards (PKCS) #1: 515 RSA Cryptography Specifications Version 2.1."; 516 } 518 identity rsa4096 { 519 base key-algorithm; 520 description 521 "The RSA algorithm using a 4096-bit key."; 522 reference 523 "RFC3447: Public-Key Cryptography Standards (PKCS) #1: 524 RSA Cryptography Specifications Version 2.1."; 525 } 527 identity rsa7680 { 528 base key-algorithm; 529 description 530 "The RSA algorithm using a 7680-bit key."; 531 reference 532 "RFC3447: Public-Key Cryptography Standards (PKCS) #1: 533 RSA Cryptography Specifications Version 2.1."; 534 } 536 identity rsa15360 { 537 base key-algorithm; 538 description 539 "The RSA algorithm using a 15360-bit key."; 540 reference 541 "RFC3447: Public-Key Cryptography Standards (PKCS) #1: 542 RSA Cryptography Specifications Version 2.1."; 544 } 546 identity secp192r1 { 547 base key-algorithm; 548 description 549 "The secp192r1 algorithm."; 550 reference 551 "RFC5480: 552 Elliptic Curve Cryptography Subject Public Key Information."; 553 } 555 identity secp256r1 { 556 base key-algorithm; 557 description 558 "The secp256r1 algorithm."; 559 reference 560 "RFC5480: 561 Elliptic Curve Cryptography Subject Public Key Information."; 562 } 564 identity secp384r1 { 565 base key-algorithm; 566 description 567 "The secp384r1 algorithm."; 568 reference 569 "RFC5480: 570 Elliptic Curve Cryptography Subject Public Key Information."; 571 } 573 identity secp521r1 { 574 base key-algorithm; 575 description 576 "The secp521r1 algorithm."; 577 reference 578 "RFC5480: 579 Elliptic Curve Cryptography Subject Public Key Information."; 580 } 582 // typedefs 584 typedef pinned-certificates { 585 type leafref { 586 path "/ks:keystore/ks:pinned-certificates/ks:name"; 587 } 588 description 589 "This typedef enables importing modules to easily define a 590 reference to pinned-certificates. Use of this type also 591 impacts the YANG tree diagram output."; 592 reference 593 "I-D.ietf-netmod-yang-tree-diagrams: YANG Tree Diagrams"; 594 } 596 typedef pinned-host-keys { 597 type leafref { 598 path "/ks:keystore/ks:pinned-host-keys/ks:name"; 599 } 600 description 601 "This typedef enables importing modules to easily define a 602 reference to pinned-host-keys. Use of this type also 603 impacts the YANG tree diagram output."; 604 reference 605 "I-D.ietf-netmod-yang-tree-diagrams: YANG Tree Diagrams"; 606 } 608 // groupings 610 grouping private-key-grouping { 611 description 612 "A private/public key pair, and an action to request the 613 system to generate a private key."; 614 leaf algorithm { 615 type identityref { 616 base "key-algorithm"; 617 } 618 description 619 "Identifies the key's algorithm. More specifically, this 620 leaf specifies how the 'private-key' and 'public-key' 621 binary leafs are encoded."; 622 } 623 leaf private-key { 624 nacm:default-deny-all; 625 type union { 626 type binary; 627 type enumeration { 628 enum "hardware-protected" { 629 description 630 "The private key is inaccessible due to being 631 protected by a cryptographic hardware module 632 (e.g., a TPM)."; 633 } 634 } 635 } 636 must "../algorithm"; 637 description 638 "A binary that contains the value of the private key. The 639 interpretation of the content is defined by the key 640 algorithm. For example, a DSA key is an integer, an RSA 641 key is represented as RSAPrivateKey as defined in 642 [RFC3447], and an Elliptic Curve Cryptography (ECC) key 643 is represented as ECPrivateKey as defined in [RFC5915]"; 644 reference 645 "RFC 3447: Public-Key Cryptography Standards (PKCS) #1: 646 RSA Cryptography Specifications Version 2.1. 647 RFC 5915: Elliptic Curve Private Key Structure."; 648 } 649 leaf public-key { 650 type binary; 651 must "../algorithm"; 652 must "../private-key"; 653 description 654 "A binary that contains the value of the public key. The 655 interpretation of the content is defined by the key 656 algorithm. For example, a DSA key is an integer, an RSA 657 key is represented as RSAPublicKey as defined in 658 [RFC3447], and an Elliptic Curve Cryptography (ECC) key 659 is represented using the 'publicKey' described in 660 [RFC5915]"; 661 reference 662 "RFC 3447: Public-Key Cryptography Standards (PKCS) #1: 663 RSA Cryptography Specifications Version 2.1. 664 RFC 5915: Elliptic Curve Private Key Structure."; 665 } 666 action generate-private-key { 667 description 668 "Requests the device to generate a private key using the 669 specified key algorithm. This action is primarily to 670 support cryptographic processors that must generate 671 the private key themselves. The resulting key is 672 considered operational state and hence only present 673 in the ."; 674 input { 675 leaf algorithm { 676 type identityref { 677 base "key-algorithm"; 678 } 679 mandatory true; 680 description 681 "The algorithm to be used when generating the key."; 682 } 683 } 684 } // end generate-private-key 685 } 686 grouping certificate-grouping { 687 description 688 "A container of certificates, and an action to generate 689 a certificate signing request."; 690 container certificates { 691 description 692 "Certificates associated with this key. More than one 693 certificate supports, for instance, a TPM-protected 694 key that has both IDevID and LDevID certificates 695 associated."; 696 list certificate { 697 key name; 698 description 699 "A certificate for this private key."; 700 leaf name { 701 type string; 702 description 703 "An arbitrary name for the certificate."; 704 } 705 leaf value { 706 type binary; 707 description 708 "A PKCS #7 SignedData structure, as specified by 709 Section 9.1 in RFC 2315, containing just certificates 710 (no content, signatures, or CRLs), encoded using ASN.1 711 distinguished encoding rules (DER), as specified in 712 ITU-T X.690. 714 This structure contains the certificate itself as well 715 as any intermediate certificates leading up to a trust 716 anchor certificate. The trust anchor certificate MAY 717 be included as well."; 718 reference 719 "RFC 2315: 720 PKCS #7: Cryptographic Message Syntax Version 1.5. 721 ITU-T X.690: 722 Information technology - ASN.1 encoding rules: 723 Specification of Basic Encoding Rules (BER), 724 Canonical Encoding Rules (CER) and Distinguished 725 Encoding Rules (DER)."; 726 } 727 } 728 } 729 action generate-certificate-signing-request { 730 description 731 "Generates a certificate signing request structure for 732 the associated private key using the passed subject and 733 attribute values. The specified assertions need to be 734 appropriate for the certificate's use. For example, 735 an entity certificate for a TLS server SHOULD have 736 values that enable clients to satisfy RFC 6125 737 processing."; 738 input { 739 leaf subject { 740 type binary; 741 mandatory true; 742 description 743 "The 'subject' field from the CertificationRequestInfo 744 structure as specified by RFC 2986, Section 4.1 encoded 745 using the ASN.1 distinguished encoding rules (DER), as 746 specified in ITU-T X.690."; 747 reference 748 "RFC 2986: 749 PKCS #10: Certification Request Syntax Specification 750 Version 1.7. 751 ITU-T X.690: 752 Information technology - ASN.1 encoding rules: 753 Specification of Basic Encoding Rules (BER), 754 Canonical Encoding Rules (CER) and Distinguished 755 Encoding Rules (DER)."; 756 } 757 leaf attributes { 758 type binary; 759 description 760 "The 'attributes' field from the CertificationRequestInfo 761 structure as specified by RFC 2986, Section 4.1 encoded 762 using the ASN.1 distinguished encoding rules (DER), as 763 specified in ITU-T X.690."; 764 reference 765 "RFC 2986: 766 PKCS #10: Certification Request Syntax Specification 767 Version 1.7. 768 ITU-T X.690: 769 Information technology - ASN.1 encoding rules: 770 Specification of Basic Encoding Rules (BER), 771 Canonical Encoding Rules (CER) and Distinguished 772 Encoding Rules (DER)."; 773 } 774 } 775 output { 776 leaf certificate-signing-request { 777 type binary; 778 mandatory true; 779 description 780 "A CertificationRequest structure as specified by RFC 781 2986, Section 4.1 encoded using the ASN.1 distinguished 782 encoding rules (DER), as specified in ITU-T X.690."; 783 reference 784 "RFC 2986: 785 PKCS #10: Certification Request Syntax Specification 786 Version 1.7. 787 ITU-T X.690: 788 Information technology - ASN.1 encoding rules: 789 Specification of Basic Encoding Rules (BER), 790 Canonical Encoding Rules (CER) and Distinguished 791 Encoding Rules (DER)."; 793 } 794 } 795 } 796 } 798 // protocol accessible nodes 800 container keystore { 801 nacm:default-deny-write; 802 description 803 "The keystore contains X.509 certificates and SSH host keys."; 805 list pinned-certificates { 806 key name; 807 description 808 "A list of pinned certificates. These certificates can be 809 used by a server to authenticate clients, or by clients to 810 authenticate servers. Each list of pinned certificates 811 SHOULD be specific to a purpose, as the list as a whole 812 may be referenced by other modules. For instance, a 813 NETCONF server's configuration might use a specific list 814 of pinned certificates for when authenticating NETCONF 815 client connections."; 816 leaf name { 817 type string; 818 description 819 "An arbitrary name for this list of pinned certificates."; 820 } 821 leaf description { 822 type string; 823 description 824 "An arbitrary description for this list of pinned 825 certificates."; 826 } 827 list pinned-certificate { 828 key name; 829 description 830 "A pinned certificate."; 831 leaf name { 832 type string; 833 description 834 "An arbitrary name for this pinned certificate. The 835 name must be unique across all lists of pinned 836 certificates (not just this list) so that leafrefs 837 from another module can resolve to unique values."; 838 } 839 leaf data { 840 type binary; 841 mandatory true; 842 description 843 "An X.509 v3 certificate structure as specified by RFC 844 5280, Section 4 encoded using the ASN.1 distinguished 845 encoding rules (DER), as specified in ITU-T X.690."; 846 reference 847 "RFC 5280: 848 Internet X.509 Public Key Infrastructure Certificate 849 and Certificate Revocation List (CRL) Profile. 850 ITU-T X.690: 851 Information technology - ASN.1 encoding rules: 852 Specification of Basic Encoding Rules (BER), 853 Canonical Encoding Rules (CER) and Distinguished 854 Encoding Rules (DER)."; 855 } 856 } 857 } 859 list pinned-host-keys { 860 key name; 861 description 862 "A list of pinned host keys. These pinned host-keys can 863 be used by clients to authenticate SSH servers. Each 864 list of pinned host keys SHOULD be specific to a purpose, 865 so the list as a whole may be referenced by other modules. 866 For instance, a NETCONF client's configuration might 867 point to a specific list of pinned host keys for when 868 authenticating specific SSH servers."; 869 leaf name { 870 type string; 871 description 872 "An arbitrary name for this list of pinned SSH host keys."; 873 } 874 leaf description { 875 type string; 876 description 877 "An arbitrary description for this list of pinned SSH host 878 keys."; 879 } 880 list pinned-host-key { 881 key name; 882 description 883 "A pinned host key."; 884 leaf name { 885 type string; 886 description 887 "An arbitrary name for this pinned host-key. Must be 888 unique across all lists of pinned host-keys (not just 889 this list) so that a leafref to it from another module 890 can resolve to unique values."; 891 } 892 leaf data { 893 type binary; 894 mandatory true; 895 description 896 "The binary public key data for this SSH key, as 897 specified by RFC 4253, Section 6.6, i.e.: 899 string certificate or public key format 900 identifier 901 byte[n] key/certificate data."; 902 reference 903 "RFC 4253: The Secure Shell (SSH) Transport Layer 904 Protocol"; 905 } 906 } 907 } 908 } 910 notification certificate-expiration { 911 description 912 "A notification indicating that a configured certificate is 913 either about to expire or has already expired. When to send 914 notifications is an implementation specific decision, but 915 it is RECOMMENDED that a notification be sent once a month 916 for 3 months, then once a week for four weeks, and then once 917 a day thereafter."; 918 leaf certificate { 919 type instance-identifier; 920 mandatory true; 921 description 922 "Identifies which certificate is expiring or is expired."; 923 } 924 leaf expiration-date { 925 type yang:date-and-time; 926 mandatory true; 927 description 928 "Identifies the expiration date on the certificate."; 929 } 930 } 932 } 933 935 5. Security Considerations 937 The YANG module defined in this document is designed to be accessed 938 via YANG based management protocols, such as NETCONF [RFC6241] and 939 RESTCONF [RFC8040]. Both of these protocols have mandatory-to- 940 implement secure transport layers (e.g., SSH, TLS) with mutual 941 authentication. 943 The NETCONF access control model (NACM) [RFC6536] provides the means 944 to restrict access for particular users to a pre-configured subset of 945 all available protocol operations and content. 947 There are a number of data nodes defined in this YANG module that are 948 writable/creatable/deletable (i.e., config true, which is the 949 default). These data nodes may be considered sensitive or vulnerable 950 in some network environments. Write operations (e.g., edit-config) 951 to these data nodes without proper protection can have a negative 952 effect on network operations. These are the subtrees and data nodes 953 and their sensitivity/vulnerability: 955 /: The entire data tree defined by this module is sensitive to 956 write operations. For instance, the addition or removal of 957 keys, certificates, trusted anchors, etc., can dramatically 958 alter the implemented security policy. This being the case, 959 the top-level node in this module is marked with the NACM value 960 'default-deny-write'. 962 /keystore/keys/key/private-key: When writing this node, 963 implementations MUST ensure that the strength of the key being 964 configured is not greater than the strength of the underlying 965 secure transport connection over which it is communicated. 966 Implementations SHOULD fail the write-request if ever the 967 strength of the private key is greater then the strength of the 968 underlying transport, and alert the client that the strength of 969 the key may have been compromised. Additionally, when deleting 970 this node, implementations SHOULD automatically (without 971 explicit request) zeroize these keys in the most secure manner 972 available, so as to prevent the remnants of their persisted 973 storage locations from being analyzed in any meaningful way. 975 Some of the readable data nodes in this YANG module may be considered 976 sensitive or vulnerable in some network environments. It is thus 977 important to control read access (e.g., via get, get-config, or 978 notification) to these data nodes. These are the subtrees and data 979 nodes and their sensitivity/vulnerability: 981 /keystore/keys/key/private-key: This node is additionally 982 sensitive to read operations such that, in normal use cases, it 983 should never be returned to a client. The best reason for 984 returning this node is to support backup/restore type 985 workflows. This being the case, this node is marked with the 986 NACM value 'default-deny-all'. 988 Some of the operations in this YANG module may be considered 989 sensitive or vulnerable in some network environments. It is thus 990 important to control access to these operations. These are the 991 operations and their sensitivity/vulnerability: 993 generate-certificate-signing-request: For this action, it is 994 RECOMMENDED that implementations assert channel binding 995 [RFC5056], so as to ensure that the application layer that sent 996 the request is the same as the device authenticated when the 997 secure transport layer was established. 999 6. IANA Considerations 1001 6.1. The IETF XML Registry 1003 This document registers one URI in the IETF XML registry [RFC3688]. 1004 Following the format in [RFC3688], the following registration is 1005 requested: 1007 URI: urn:ietf:params:xml:ns:yang:ietf-keystore 1008 Registrant Contact: The NETCONF WG of the IETF. 1009 XML: N/A, the requested URI is an XML namespace. 1011 6.2. The YANG Module Names Registry 1013 This document registers one YANG module in the YANG Module Names 1014 registry [RFC6020]. Following the format in [RFC6020], the the 1015 following registration is requested: 1017 name: ietf-keystore 1018 namespace: urn:ietf:params:xml:ns:yang:ietf-keystore 1019 prefix: ks 1020 reference: RFC VVVV 1022 7. Acknowledgements 1024 The authors would like to thank for following for lively discussions 1025 on list and in the halls (ordered by last name): Andy Bierman, Martin 1026 Bjorklund, Benoit Claise, Mehmet Ersue, Balazs Kovacs, David 1027 Lamparter, Alan Luchuk, Ladislav Lhotka, Radek Krejci, Tom Petch, 1028 Juergen Schoenwaelder; Phil Shafer, Sean Turner, and Bert Wijnen. 1030 8. References 1032 8.1. Normative References 1034 [ITU.X690.1994] 1035 International Telecommunications Union, "Information 1036 Technology - ASN.1 encoding rules: Specification of Basic 1037 Encoding Rules (BER), Canonical Encoding Rules (CER) and 1038 Distinguished Encoding Rules (DER)", ITU-T Recommendation 1039 X.690, 1994. 1041 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1042 Requirement Levels", BCP 14, RFC 2119, 1043 DOI 10.17487/RFC2119, March 1997, 1044 . 1046 [RFC2315] Kaliski, B., "PKCS #7: Cryptographic Message Syntax 1047 Version 1.5", RFC 2315, DOI 10.17487/RFC2315, March 1998, 1048 . 1050 [RFC2986] Nystrom, M. and B. Kaliski, "PKCS #10: Certification 1051 Request Syntax Specification Version 1.7", RFC 2986, 1052 DOI 10.17487/RFC2986, November 2000, 1053 . 1055 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 1056 Standards (PKCS) #1: RSA Cryptography Specifications 1057 Version 2.1", RFC 3447, DOI 10.17487/RFC3447, February 1058 2003, . 1060 [RFC4253] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) 1061 Transport Layer Protocol", RFC 4253, DOI 10.17487/RFC4253, 1062 January 2006, . 1064 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1065 Housley, R., and W. Polk, "Internet X.509 Public Key 1066 Infrastructure Certificate and Certificate Revocation List 1067 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 1068 . 1070 [RFC5480] Turner, S., Brown, D., Yiu, K., Housley, R., and T. Polk, 1071 "Elliptic Curve Cryptography Subject Public Key 1072 Information", RFC 5480, DOI 10.17487/RFC5480, March 2009, 1073 . 1075 [RFC5915] Turner, S. and D. Brown, "Elliptic Curve Private Key 1076 Structure", RFC 5915, DOI 10.17487/RFC5915, June 2010, 1077 . 1079 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1080 the Network Configuration Protocol (NETCONF)", RFC 6020, 1081 DOI 10.17487/RFC6020, October 2010, 1082 . 1084 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 1085 Protocol (NETCONF) Access Control Model", RFC 6536, 1086 DOI 10.17487/RFC6536, March 2012, 1087 . 1089 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 1090 RFC 6991, DOI 10.17487/RFC6991, July 2013, 1091 . 1093 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1094 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1095 . 1097 8.2. Informative References 1099 [I-D.ietf-netmod-yang-tree-diagrams] 1100 Bjorklund, M. and L. Berger, "YANG Tree Diagrams", draft- 1101 ietf-netmod-yang-tree-diagrams-02 (work in progress), 1102 October 2017. 1104 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1105 DOI 10.17487/RFC3688, January 2004, 1106 . 1108 [RFC4211] Schaad, J., "Internet X.509 Public Key Infrastructure 1109 Certificate Request Message Format (CRMF)", RFC 4211, 1110 DOI 10.17487/RFC4211, September 2005, 1111 . 1113 [RFC5056] Williams, N., "On the Use of Channel Bindings to Secure 1114 Channels", RFC 5056, DOI 10.17487/RFC5056, November 2007, 1115 . 1117 [RFC5914] Housley, R., Ashmore, S., and C. Wallace, "Trust Anchor 1118 Format", RFC 5914, DOI 10.17487/RFC5914, June 2010, 1119 . 1121 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1122 and A. Bierman, Ed., "Network Configuration Protocol 1123 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1124 . 1126 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1127 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1128 . 1130 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1131 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1132 May 2017, . 1134 [Std-802.1AR-2009] 1135 IEEE SA-Standards Board, "IEEE Standard for Local and 1136 metropolitan area networks - Secure Device Identity", 1137 December 2009, . 1140 Appendix A. Change Log 1142 A.1. 00 to 01 1144 o Replaced the 'certificate-chain' structures with PKCS#7 1145 structures. (Issue #1) 1147 o Added 'private-key' as a configurable data node, and removed the 1148 'generate-private-key' and 'load-private-key' actions. (Issue #2) 1150 o Moved 'user-auth-credentials' to the ietf-ssh-client module. 1151 (Issues #4 and #5) 1153 A.2. 01 to 02 1155 o Added back 'generate-private-key' action. 1157 o Removed 'RESTRICTED' enum from the 'private-key' leaf type. 1159 o Fixed up a few description statements. 1161 A.3. 02 to 03 1163 o Changed draft's title. 1165 o Added missing references. 1167 o Collapsed sections and levels. 1169 o Added RFC 8174 to Requirements Language Section. 1171 o Renamed 'trusted-certificates' to 'pinned-certificates'. 1173 o Changed 'public-key' from config false to config true. 1175 o Switched 'host-key' from OneAsymmetricKey to definition from RFC 1176 4253. 1178 A.4. 03 to 04 1180 o Added typedefs around leafrefs to common keystore paths 1182 o Now tree diagrams reference ietf-netmod-yang-tree-diagrams 1184 o Removed Design Considerations section 1186 o Moved key and certificate definitions from data tree to groupings 1188 Author's Address 1190 Kent Watsen 1191 Juniper Networks 1193 EMail: kwatsen@juniper.net