idnits 2.17.1 draft-ietf-netconf-keystore-03.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 : ---------------------------------------------------------------------------- ** There are 2 instances of too long lines in the document, the longest one being 37 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 233 has weird spacing: '...request bin...' == Line 237 has weird spacing: '...gorithm ide...' == Line 242 has weird spacing: '...rw name str...' == Line 243 has weird spacing: '...rw data bin...' == Line 248 has weird spacing: '...rw name str...' == (3 more instances...) -- The document date (October 17, 2017) is 2383 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: 'RFC5958' is defined on line 1118, 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) Summary: 6 errors (**), 0 flaws (~~), 8 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 17, 2017 5 Expires: April 20, 2018 7 YANG Data Model for a "Keystore" Mechanism 8 draft-ietf-netconf-keystore-03 10 Abstract 12 This document defines a YANG module for a system-level mechanism, 13 called a "keystore", containing security-sensitive data including 14 private keys, pinned certificates, and pinned SSH host-keys. 16 Editorial Note (To be removed by RFC Editor) 18 This draft contains many placeholder values that need to be replaced 19 with finalized values at the time of publication. This note 20 summarizes all of the substitutions that are needed. No other RFC 21 Editor instructions are specified elsewhere in this document. 23 Artwork in this document contains shorthand references to drafts in 24 progress. Please apply the following replacements: 26 o "VVVV" --> the assigned RFC value for this draft 28 Artwork in this document contains placeholder values for the date of 29 publication of this draft. Please apply the following replacement: 31 o "2017-10-18" --> the publication date of this draft 33 The following Appendix section is to be removed prior to publication: 35 o Appendix A. Change Log 37 Status of This Memo 39 This Internet-Draft is submitted in full conformance with the 40 provisions of BCP 78 and BCP 79. 42 Internet-Drafts are working documents of the Internet Engineering 43 Task Force (IETF). Note that other groups may also distribute 44 working documents as Internet-Drafts. The list of current Internet- 45 Drafts is at https://datatracker.ietf.org/drafts/current/. 47 Internet-Drafts are draft documents valid for a maximum of six months 48 and may be updated, replaced, or obsoleted by other documents at any 49 time. It is inappropriate to use Internet-Drafts as reference 50 material or to cite them other than as "work in progress." 52 This Internet-Draft will expire on April 20, 2018. 54 Copyright Notice 56 Copyright (c) 2017 IETF Trust and the persons identified as the 57 document authors. All rights reserved. 59 This document is subject to BCP 78 and the IETF Trust's Legal 60 Provisions Relating to IETF Documents 61 (https://trustee.ietf.org/license-info) in effect on the date of 62 publication of this document. Please review these documents 63 carefully, as they describe your rights and restrictions with respect 64 to this document. Code Components extracted from this document must 65 include Simplified BSD License text as described in Section 4.e of 66 the Trust Legal Provisions and are provided without warranty as 67 described in the Simplified BSD License. 69 Table of Contents 71 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 72 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 4 73 1.2. Tree Diagram Notation . . . . . . . . . . . . . . . . . . 4 74 2. Design Considerations . . . . . . . . . . . . . . . . . . . . 4 75 3. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . . . 5 76 4. Example Usage . . . . . . . . . . . . . . . . . . . . . . . . 6 77 5. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 11 78 6. Security Considerations . . . . . . . . . . . . . . . . . . . 22 79 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 80 7.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 23 81 7.2. The YANG Module Names Registry . . . . . . . . . . . . . 23 82 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 24 83 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 24 84 9.1. Normative References . . . . . . . . . . . . . . . . . . 24 85 9.2. Informative References . . . . . . . . . . . . . . . . . 25 86 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 27 87 A.1. server-model-09 to 00 . . . . . . . . . . . . . . . . . . 27 88 A.2. keychain-00 to keystore-00 . . . . . . . . . . . . . . . 27 89 A.3. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 27 90 A.4. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 27 91 A.5. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 27 92 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 28 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 configurable list of keys, each a public/private key pair. If a 103 key is used to sign a certificate signing request (CSR), which is 104 then signed by a certificate authority (CA), then the resulting 105 certificate may be configured as being associated with the key. 106 Keys are expected to be configured using standard configuration 107 mechanisms, however, to support hardware that generates keys, the 108 key may also be created via an action called 'generate-private- 109 key" action. Keys may also be preinstalled (e.g., a key 110 associated to an IDevID [Std-802.1AR-2009] certificate). 112 o An unordered list of pinned certificate sets, where each pinned 113 certificate set contains an unordered list of pinned certificates. 114 This structure enables a server to use specific sets of pinned 115 certificates on a case-by-case basis. For instance, one set of 116 pinned certificates might be used by an HTTPS-client when 117 connecting to particular HTTPS servers, while another set of 118 pinned certificates might be used by a server when authenticating 119 client connections (e.g., certificate-based client 120 authentication). 122 o An unordered list of pinned SSH host key sets, where each pinned 123 SSH host key set contains an unordered list of pinned SSH host 124 keys. This enables a server to use specific sets of pinned SSH 125 host-keys on a case-by-case basis. For instance, SSH clients can 126 be configured to use different sets of pinned SSH host keys when 127 connecting to different SSH servers. 129 o An action to request the server to generate a new key using the 130 specified algorithm. The resulting key is present in 131 . 133 o An action to request the server to generate a certificate signing 134 request for an existing key. Passed into the action are the 135 subject and attributes to be used, and returned is the CSR 136 (certificate signing request) structure, signed by the key 137 protected by the keystore. The CSR can be signed by an external 138 certificate authority (CA). The signed certificate returned by 139 the CA can be associated with the key in the keystore, using a 140 standard configuration operation (). 142 o A notification to indicate when a certificate is about to expire. 144 Special consideration has been given for systems that have Trusted 145 Protection Modules (TPMs). These systems are unique in that the TPM 146 must be directed to generate new keys (it is not possible to load a 147 key into a TPM) and it is not possible to backup/restore the TPM's 148 private keys as configuration. 150 It is not required that a system has an operating system level 151 keystore utility to implement this module. 153 1.1. Requirements Language 155 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 156 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 157 "OPTIONAL" in this document are to be interpreted as described in BCP 158 14 [RFC2119] [RFC8174] when, and only when, they appear in all 159 capitals, as shown here. 161 1.2. Tree Diagram Notation 163 A simplified graphical representation of the data models is used in 164 this document. The meaning of the symbols in these diagrams is as 165 follows: 167 o Brackets "[" and "]" enclose list keys. 169 o Braces "{" and "}" enclose feature names, and indicate that the 170 named feature must be present for the subtree to be present. 172 o Abbreviations before data node names: "rw" means configuration 173 (read-write) and "ro" state data (read-only). 175 o Symbols after data node names: "?" means an optional node, "!" 176 means a presence container, and "*" denotes a list and leaf-list. 178 o Parentheses enclose choice and case nodes, and case nodes are also 179 marked with a colon (":"). 181 o Ellipsis ("...") stands for contents of subtrees that are not 182 shown. 184 2. Design Considerations 186 This document uses PKCS #10 [RFC2986] for the "generate-certificate- 187 signing-request" action. The use of Certificate Request Message 188 Format (CRMF) [RFC4211] was considered, but is was unclear if there 189 was market demand for it, and so support for CRMF has been left out 190 of this specification. If it is desired to support CRMF in the 191 future, placing a "choice" statement in both the input and output 192 statements, along with an "if-feature" statement on the CRMF option, 193 would enable a backwards compatible solution. 195 In order to use YANG identities for algorithm identifiers, only the 196 most commonly used RSA key lengths are supported for the RSA 197 algorithm. Additional key lengths can be defined in another module 198 or added into a future version of this document. 200 This document limits the number of elliptical curves supported. This 201 was done to match industry trends and IETF best practice (e.g., 202 matching work being done in TLS 1.3). If additional algorithms are 203 needed, they can be defined by another module or added into a future 204 version of this document. 206 For the trusted-certificates list, Trust Anchor Format [RFC5914] was 207 evaluated and deemed inappropriate due to this document's need to 208 also support pinning. That is, pinning a client-certificate to 209 support NETCONF over TLS client authentication. 211 3. Tree Diagram 213 The keystore module has the following tree diagram. Please see 214 Section 1.2 for information on how to interpret this diagram. 216 module: ietf-keystore 217 +--rw keystore 218 +--rw keys 219 | +--rw key* [name] 220 | | +--rw name string 221 | | +--rw algorithm identityref 222 | | +--rw private-key union 223 | | +--rw public-key binary 224 | | +--rw certificates 225 | | | +--rw certificate* [name] 226 | | | +--rw name string 227 | | | +--rw value? binary 228 | | +---x generate-certificate-signing-request 229 | | +---w input 230 | | | +---w subject binary 231 | | | +---w attributes? binary 232 | | +--ro output 233 | | +--ro certificate-signing-request binary 234 | +---x generate-private-key 235 | +---w input 236 | +---w name string 237 | +---w algorithm identityref 238 +--rw pinned-certificates* [name] 239 | +--rw name string 240 | +--rw description? string 241 | +--rw pinned-certificate* [name] 242 | +--rw name string 243 | +--rw data binary 244 +--rw pinned-host-keys* [name] 245 +--rw name string 246 +--rw description? string 247 +--rw pinned-host-key* [name] 248 +--rw name string 249 +--rw data binary 251 notifications: 252 +---n certificate-expiration 253 +--ro certificate instance-identifier 254 +--ro expiration-date yang:date-and-time 256 4. Example Usage 258 The following example illustrates what a fully configured keystore 259 might look like. This keystore has three keys, four sets of trusted 260 certificates, and one set of trusted host keys. 262 263 264 265 266 ex-rsa-key 267 rsa1024 268 base64encodedvalue== 269 base64encodedvalue== 270 271 272 ex-rsa-cert 273 base64encodedvalue== 274 275 276 278 279 tls-ec-key 280 secp256r1 281 base64encodedvalue== 282 base64encodedvalue== 283 284 285 tls-ec-cert 286 base64encodedvalue== 287 288 289 291 292 tpm-protected-key 293 rsa2048 294 base64encodedvalue== 295 base64encodedvalue== 296 297 298 builtin-idevid-cert 299 base64encodedvalue== 300 301 302 my-ldevid-cert 303 base64encodedvalue== 304 305 306 307 309 310 311 manufacturers-root-ca-certs 312 313 Certificates built into the device for authenticating 314 manufacturer-signed objects, such as TLS server certificates, 315 vouchers, etc.. Note, though listed here, these are not 316 configurable; any attempt to do so will be denied. 317 318 319 Manufacturer Root CA cert 1 320 base64encodedvalue== 321 322 323 Manufacturer Root CA cert 2 324 base64encodedvalue== 325 326 328 329 330 explicitly-trusted-client-certs 331 332 Specific client authentication certificates for explicitly 333 trusted clients. These are needed for client certificates 334 that are not signed by a pinned CA. 335 336 337 George Jetson 338 base64encodedvalue== 339 340 342 343 344 explicitly-trusted-server-certs 345 346 Specific server authentication certificates for explicitly 347 trusted servers. These are needed for server certificates 348 that are not signed by a pinned CA. 349 350 351 Fred Flintstone 352 base64encodedvalue== 353 354 356 357 358 deployment-specific-ca-certs 359 360 Trust anchors (i.e. CA certs) that are used to authenticate 361 client connections. Clients are authenticated if their 362 certificate has a chain of trust to one of these configured 363 CA certificates. 364 365 366 ca.example.com 367 base64encodedvalue== 368 369 371 372 373 common-ca-certs 374 375 Trusted certificates to authenticate common HTTPS servers. 376 These certificates are similar to those that might be 377 shipped with a web browser. 378 379 380 ex-certificate-authority 381 base64encodedvalue== 382 383 385 386 387 explicitly-trusted-ssh-host-keys 388 389 Trusted SSH host keys used to authenticate SSH servers. 390 These host keys would be analogous to those stored in 391 a known_hosts file in OpenSSH. 392 393 394 corp-fw1 395 base64encodedvalue== 396 397 399 401 The following example illustrates the "generate-certificate-signing- 402 request" action in use with the NETCONF protocol. 404 REQUEST 405 ------- 406 407 408 409 410 411 ex-key-sect571r1 412 413 base64encodedvalue== 414 base64encodedvalue== 415 416 417 418 419 420 422 RESPONSE 423 -------- 424 426 428 base64encodedvalue== 429 430 432 The following example illustrates the "generate-private-key" action 433 in use with the NETCONF protocol. 435 REQUEST 436 ------- 437 438 439 440 441 442 ex-key-sect571r1 443 ks:secp521r1 444 445 446 447 448 450 RESPONSE 451 -------- 452 454 455 457 The following example illustrates the "certificate-expiration" 458 notification in use with the NETCONF protocol. 460 ['\' line wrapping added for formatting only] 462 464 2016-07-08T00:01:00Z 465 467 468 /ks:keystore/ks:keys/ks:key[ks:name='ex-rsa-key']/ks:certificates/ks:certificate[ks:name='ex-rsa-cert'] 469 470 2016-08-08T14:18:53-05:00 471 472 474 5. YANG Module 476 This YANG module imports modules defined in [RFC6536] and [RFC6991]. 477 This module uses data types defined in [RFC2315], [RFC2986], 478 [RFC3447], [RFC4253], [RFC5280], [RFC5915], and [ITU.X690.1994]. 479 This module uses algorithms defined in [RFC3447] and [RFC5480]. 481 file "ietf-keystore@2017-10-18.yang" 482 module ietf-keystore { 483 yang-version 1.1; 485 namespace "urn:ietf:params:xml:ns:yang:ietf-keystore"; 486 prefix "ks"; 488 import ietf-yang-types { 489 prefix yang; 490 reference 491 "RFC 6991: Common YANG Data Types"; 492 } 494 import ietf-netconf-acm { 495 prefix nacm; 496 reference 497 "RFC 6536: Network Configuration Protocol (NETCONF) Access 498 Control Model"; 499 } 501 organization 502 "IETF NETCONF (Network Configuration) Working Group"; 504 contact 505 "WG Web: 506 WG List: 508 Author: Kent Watsen 509 "; 511 description 512 "This module defines a keystore to centralize management 513 of security credentials. 515 Copyright (c) 2017 IETF Trust and the persons identified 516 as authors of the code. All rights reserved. 518 Redistribution and use in source and binary forms, with 519 or without modification, is permitted pursuant to, and 520 subject to the license terms contained in, the Simplified 521 BSD License set forth in Section 4.c of the IETF Trust's 522 Legal Provisions Relating to IETF Documents 523 (http://trustee.ietf.org/license-info). 525 This version of this YANG module is part of RFC VVVV; see 526 the RFC itself for full legal notices."; 528 revision "2017-10-18" { 529 description 530 "Initial version"; 531 reference 532 "RFC VVVV: YANG Data Model for a 'Keystore' Mechanism"; 533 } 535 // Identities 537 identity key-algorithm { 538 description 539 "Base identity from which all key-algorithms are derived."; 540 } 542 identity rsa1024 { 543 base key-algorithm; 544 description 545 "The RSA algorithm using a 1024-bit key."; 546 reference 547 "RFC3447: Public-Key Cryptography Standards (PKCS) #1: 548 RSA Cryptography Specifications Version 2.1."; 549 } 551 identity rsa2048 { 552 base key-algorithm; 553 description 554 "The RSA algorithm using a 2048-bit key."; 555 reference 556 "RFC3447: Public-Key Cryptography Standards (PKCS) #1: 557 RSA Cryptography Specifications Version 2.1."; 558 } 560 identity rsa3072 { 561 base key-algorithm; 562 description 563 "The RSA algorithm using a 3072-bit key."; 564 reference 565 "RFC3447: Public-Key Cryptography Standards (PKCS) #1: 566 RSA Cryptography Specifications Version 2.1."; 567 } 569 identity rsa4096 { 570 base key-algorithm; 571 description 572 "The RSA algorithm using a 4096-bit key."; 573 reference 574 "RFC3447: Public-Key Cryptography Standards (PKCS) #1: 575 RSA Cryptography Specifications Version 2.1."; 576 } 577 identity rsa7680 { 578 base key-algorithm; 579 description 580 "The RSA algorithm using a 7680-bit key."; 581 reference 582 "RFC3447: Public-Key Cryptography Standards (PKCS) #1: 583 RSA Cryptography Specifications Version 2.1."; 584 } 586 identity rsa15360 { 587 base key-algorithm; 588 description 589 "The RSA algorithm using a 15360-bit key."; 590 reference 591 "RFC3447: Public-Key Cryptography Standards (PKCS) #1: 592 RSA Cryptography Specifications Version 2.1."; 593 } 595 identity secp192r1 { 596 base key-algorithm; 597 description 598 "The secp192r1 algorithm."; 599 reference 600 "RFC5480: 601 Elliptic Curve Cryptography Subject Public Key Information."; 602 } 604 identity secp256r1 { 605 base key-algorithm; 606 description 607 "The secp256r1 algorithm."; 608 reference 609 "RFC5480: 610 Elliptic Curve Cryptography Subject Public Key Information."; 611 } 613 identity secp384r1 { 614 base key-algorithm; 615 description 616 "The secp384r1 algorithm."; 617 reference 618 "RFC5480: 619 Elliptic Curve Cryptography Subject Public Key Information."; 620 } 622 identity secp521r1 { 623 base key-algorithm; 624 description 625 "The secp521r1 algorithm."; 626 reference 627 "RFC5480: 628 Elliptic Curve Cryptography Subject Public Key Information."; 629 } 631 // protocol accessible nodes 633 container keystore { 634 nacm:default-deny-write; 635 description 636 "The keystore contains private keys, X.509 certificates, and 637 SSH host keys."; 639 container keys { 640 description 641 "A list of public-private key pairs."; 642 list key { 643 key name; 644 description 645 "A public-private key pair."; 646 leaf name { 647 type string; 648 description 649 "An arbitrary name for the key."; 650 } 651 leaf algorithm { 652 type identityref { 653 base "key-algorithm"; 654 } 655 mandatory true; 656 description 657 "Identifies the key's algorithm. More specifically, this 658 leaf specifies how the 'private-key' and 'public-key' 659 binary leafs are encoded."; 660 } 661 leaf private-key { 662 nacm:default-deny-all; 663 type union { 664 type binary; 665 type enumeration { 666 enum "hardware-protected" { 667 description 668 "The private key is inaccessible due to being 669 protected by a cryptographic hardware module 670 (e.g., a TPM)."; 671 } 672 } 674 } 675 mandatory true; 676 description 677 "A binary that contains the value of the private key. The 678 interpretation of the content is defined by the key 679 algorithm. For example, a DSA key is an integer, an RSA 680 key is represented as RSAPrivateKey as defined in 681 [RFC3447], and an Elliptic Curve Cryptography (ECC) key 682 is represented as ECPrivateKey as defined in [RFC5915]"; 683 reference 684 "RFC 3447: Public-Key Cryptography Standards (PKCS) #1: 685 RSA Cryptography Specifications Version 2.1. 686 RFC 5915: Elliptic Curve Private Key Structure."; 687 } 688 leaf public-key { 689 type binary; 690 mandatory true; 691 description 692 "A binary that contains the value of the public key. The 693 interpretation of the content is defined by the key 694 algorithm. For example, a DSA key is an integer, an RSA 695 key is represented as RSAPublicKey as defined in 696 [RFC3447], and an Elliptic Curve Cryptography (ECC) key 697 is represented using the 'publicKey' described in 698 [RFC5915]"; 699 reference 700 "RFC 3447: Public-Key Cryptography Standards (PKCS) #1: 701 RSA Cryptography Specifications Version 2.1. 702 RFC 5915: Elliptic Curve Private Key Structure."; 703 } 704 container certificates { 705 description 706 "Certificates associated with this private key. More 707 than one certificate per key is enabled to support, 708 for instance, a TPM-protected key that has associated 709 both IDevID and LDevID certificates."; 710 list certificate { 711 key name; 712 description 713 "A certificate for this private key."; 714 leaf name { 715 type string; 716 description 717 "An arbitrary name for the certificate. The name 718 must be unique across all keys, not just within 719 this key, as otherwise leafrefs to a certificate 720 might be ambiguous."; 721 } 722 leaf value { 723 type binary; 724 description 725 "A PKCS #7 SignedData structure, as specified by 726 Section 9.1 in RFC 2315, containing just certificates 727 (no content, signatures, or CRLs), encoded using ASN.1 728 distinguished encoding rules (DER), as specified in 729 ITU-T X.690. 731 This structure contains the certificate itself as well 732 as any intermediate certificates leading up to a trust 733 anchor certificate. The trust anchor certificate MAY 734 be included as well."; 735 reference 736 "RFC 2315: 737 PKCS #7: Cryptographic Message Syntax Version 1.5. 738 ITU-T X.690: 739 Information technology - ASN.1 encoding rules: 740 Specification of Basic Encoding Rules (BER), 741 Canonical Encoding Rules (CER) and Distinguished 742 Encoding Rules (DER)."; 743 } 744 } 745 } 746 action generate-certificate-signing-request { 747 description 748 "Generates a certificate signing request structure for 749 the associated private key using the passed subject and 750 attribute values. The specified assertions need to be 751 appropriate for the certificate's use. For example, 752 an entity certificate for a TLS server SHOULD have 753 values that enable clients to satisfy RFC 6125 754 processing."; 755 input { 756 leaf subject { 757 type binary; 758 mandatory true; 759 description 760 "The 'subject' 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: 771 Specification of Basic Encoding Rules (BER), 772 Canonical Encoding Rules (CER) and Distinguished 773 Encoding Rules (DER)."; 774 } 775 leaf attributes { 776 type binary; 777 description 778 "The 'attributes' field from the CertificationRequestInfo 779 structure as specified by RFC 2986, Section 4.1 encoded 780 using the ASN.1 distinguished encoding rules (DER), as 781 specified in ITU-T X.690."; 782 reference 783 "RFC 2986: 784 PKCS #10: Certification Request Syntax Specification 785 Version 1.7. 786 ITU-T X.690: 787 Information technology - ASN.1 encoding rules: 788 Specification of Basic Encoding Rules (BER), 789 Canonical Encoding Rules (CER) and Distinguished 790 Encoding Rules (DER)."; 791 } 792 } 793 output { 794 leaf certificate-signing-request { 795 type binary; 796 mandatory true; 797 description 798 "A CertificationRequest structure as specified by RFC 799 2986, Section 4.1 encoded using the ASN.1 distinguished 800 encoding rules (DER), as specified in ITU-T X.690."; 801 reference 802 "RFC 2986: 803 PKCS #10: Certification Request Syntax Specification 804 Version 1.7. 805 ITU-T X.690: 806 Information technology - ASN.1 encoding rules: 807 Specification of Basic Encoding Rules (BER), 808 Canonical Encoding Rules (CER) and Distinguished 809 Encoding Rules (DER)."; 811 } 812 } 813 } 814 } // end key 816 action generate-private-key { 817 description 818 "Requests the device to generate a private key using the 819 specified key algorithm. This action is primarily to 820 support cryptographic processors that must generate 821 the private key themselves. The resulting key is 822 considered operational state and hence only present 823 in the ."; 824 input { 825 leaf name { 826 type string; 827 mandatory true; 828 description 829 "The name the key should have when listed in 830 /keys/key, in ."; 831 } 832 leaf algorithm { 833 type identityref { 834 base "key-algorithm"; 835 } 836 mandatory true; 837 description 838 "The algorithm to be used when generating the key."; 839 } 840 } 841 } // end generate-private-key 842 } // end keys 844 list pinned-certificates { 845 key name; 846 description 847 "A list of pinned certificates. These certificates can be 848 used by a server to authenticate clients, or by clients to 849 authenticate servers. Each list of pinned certificates 850 SHOULD be specific to a purpose, as the list as a whole 851 may be referenced by other modules. For instance, a 852 NETCONF server's configuration might use a specific list 853 of pinned certificates for when authenticating NETCONF 854 client connections."; 855 leaf name { 856 type string; 857 description 858 "An arbitrary name for this list of pinned certificates."; 859 } 860 leaf description { 861 type string; 862 description 863 "An arbitrary description for this list of pinned 864 certificates."; 865 } 866 list pinned-certificate { 867 key name; 868 description 869 "A pinned certificate."; 870 leaf name { 871 type string; 872 description 873 "An arbitrary name for this pinned certificate. The 874 name must be unique across all lists of pinned 875 certificates (not just this list) so that leafrefs 876 from another module can resolve to unique values."; 877 } 878 leaf data { 879 type binary; 880 mandatory true; 881 description 882 "An X.509 v3 certificate structure as specified by RFC 883 5280, Section 4 encoded using the ASN.1 distinguished 884 encoding rules (DER), as specified in ITU-T X.690."; 885 reference 886 "RFC 5280: 887 Internet X.509 Public Key Infrastructure Certificate 888 and Certificate Revocation List (CRL) Profile. 889 ITU-T X.690: 890 Information technology - ASN.1 encoding rules: 891 Specification of Basic Encoding Rules (BER), 892 Canonical Encoding Rules (CER) and Distinguished 893 Encoding Rules (DER)."; 894 } 895 } 896 } 898 list pinned-host-keys { 899 key name; 900 description 901 "A list of pinned host keys. These pinned host-keys can 902 be used by clients to authenticate SSH servers. Each 903 list of pinned host keys SHOULD be specific to a purpose, 904 so the list as a whole may be referenced by other modules. 905 For instance, a NETCONF client's configuration might 906 point to a specific list of pinned host keys for when 907 authenticating specific SSH servers."; 908 leaf name { 909 type string; 910 description 911 "An arbitrary name for this list of pinned SSH host keys."; 912 } 913 leaf description { 914 type string; 915 description 916 "An arbitrary description for this list of pinned SSH host 917 keys."; 918 } 919 list pinned-host-key { 920 key name; 921 description 922 "A pinned host key."; 923 leaf name { 924 type string; 925 description 926 "An arbitrary name for this pinned host-key. Must be 927 unique across all lists of pinned host-keys (not just 928 this list) so that a leafref to it from another module 929 can resolve to unique values."; 930 } 931 leaf data { 932 type binary; 933 mandatory true; 934 description 935 "The binary public key data for this SSH key, as 936 specified by RFC 4253, Section 6.6, i.e.: 938 string certificate or public key format 939 identifier 940 byte[n] key/certificate data."; 941 reference 942 "RFC 4253: The Secure Shell (SSH) Transport Layer 943 Protocol"; 944 } 945 } 946 } 947 } 949 notification certificate-expiration { 950 description 951 "A notification indicating that a configured certificate is 952 either about to expire or has already expired. When to send 953 notifications is an implementation specific decision, but 954 it is RECOMMENDED that a notification be sent once a month 955 for 3 months, then once a week for four weeks, and then once 956 a day thereafter."; 957 leaf certificate { 958 type instance-identifier; 959 mandatory true; 960 description 961 "Identifies which certificate is expiring or is expired."; 962 } 963 leaf expiration-date { 964 type yang:date-and-time; 965 mandatory true; 966 description 967 "Identifies the expiration date on the certificate."; 968 } 969 } 971 } 972 974 6. Security Considerations 976 The YANG module defined in this document is designed to be accessed 977 via YANG based management protocols, such as NETCONF [RFC6241] and 978 RESTCONF [RFC8040]. Both of these protocols have mandatory-to- 979 implement secure transport layers (e.g., SSH, TLS) with mutual 980 authentication. 982 The NETCONF access control model (NACM) [RFC6536] provides the means 983 to restrict access for particular users to a pre-configured subset of 984 all available protocol operations and content. 986 There are a number of data nodes defined in this YANG module that are 987 writable/creatable/deletable (i.e., config true, which is the 988 default). These data nodes may be considered sensitive or vulnerable 989 in some network environments. Write operations (e.g., edit-config) 990 to these data nodes without proper protection can have a negative 991 effect on network operations. These are the subtrees and data nodes 992 and their sensitivity/vulnerability: 994 /: The entire data tree defined by this module is sensitive to 995 write operations. For instance, the addition or removal of 996 keys, certificates, trusted anchors, etc., can dramatically 997 alter the implemented security policy. This being the case, 998 the top-level node in this module is marked with the NACM value 999 'default-deny-write'. 1001 /keystore/keys/key/private-key: When writing this node, 1002 implementations MUST ensure that the strength of the key being 1003 configured is not greater than the strength of the underlying 1004 secure transport connection over which it is communicated. 1005 Implementations SHOULD fail the write-request if ever the 1006 strength of the private key is greater then the strength of the 1007 underlying transport, and alert the client that the strength of 1008 the key may have been compromised. Additionally, when deleting 1009 this node, implementations SHOULD automatically (without 1010 explicit request) zeroize these keys in the most secure manner 1011 available, so as to prevent the remnants of their persisted 1012 storage locations from being analyzed in any meaningful way. 1014 Some of the readable data nodes in this YANG module may be considered 1015 sensitive or vulnerable in some network environments. It is thus 1016 important to control read access (e.g., via get, get-config, or 1017 notification) to these data nodes. These are the subtrees and data 1018 nodes and their sensitivity/vulnerability: 1020 /keystore/keys/key/private-key: This node is additionally 1021 sensitive to read operations such that, in normal use cases, it 1022 should never be returned to a client. The best reason for 1023 returning this node is to support backup/restore type 1024 workflows. This being the case, this node is marked with the 1025 NACM value 'default-deny-all'. 1027 Some of the operations in this YANG module may be considered 1028 sensitive or vulnerable in some network environments. It is thus 1029 important to control access to these operations. These are the 1030 operations and their sensitivity/vulnerability: 1032 generate-certificate-signing-request: For this action, it is 1033 RECOMMENDED that implementations assert channel binding 1034 [RFC5056], so as to ensure that the application layer that sent 1035 the request is the same as the device authenticated when the 1036 secure transport layer was established. 1038 7. IANA Considerations 1040 7.1. The IETF XML Registry 1042 This document registers one URI in the IETF XML registry [RFC3688]. 1043 Following the format in [RFC3688], the following registration is 1044 requested: 1046 URI: urn:ietf:params:xml:ns:yang:ietf-keystore 1047 Registrant Contact: The NETCONF WG of the IETF. 1048 XML: N/A, the requested URI is an XML namespace. 1050 7.2. The YANG Module Names Registry 1052 This document registers one YANG module in the YANG Module Names 1053 registry [RFC6020]. Following the format in [RFC6020], the the 1054 following registration is requested: 1056 name: ietf-keystore 1057 namespace: urn:ietf:params:xml:ns:yang:ietf-keystore 1058 prefix: ks 1059 reference: RFC VVVV 1061 8. Acknowledgements 1063 The authors would like to thank for following for lively discussions 1064 on list and in the halls (ordered by last name): Andy Bierman, Martin 1065 Bjorklund, Benoit Claise, Mehmet Ersue, Balazs Kovacs, David 1066 Lamparter, Alan Luchuk, Ladislav Lhotka, Radek Krejci, Tom Petch, 1067 Juergen Schoenwaelder; Phil Shafer, Sean Turner, and Bert Wijnen. 1069 9. References 1071 9.1. Normative References 1073 [ITU.X690.1994] 1074 International Telecommunications Union, "Information 1075 Technology - ASN.1 encoding rules: Specification of Basic 1076 Encoding Rules (BER), Canonical Encoding Rules (CER) and 1077 Distinguished Encoding Rules (DER)", ITU-T Recommendation 1078 X.690, 1994. 1080 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1081 Requirement Levels", BCP 14, RFC 2119, 1082 DOI 10.17487/RFC2119, March 1997, 1083 . 1085 [RFC2315] Kaliski, B., "PKCS #7: Cryptographic Message Syntax 1086 Version 1.5", RFC 2315, DOI 10.17487/RFC2315, March 1998, 1087 . 1089 [RFC2986] Nystrom, M. and B. Kaliski, "PKCS #10: Certification 1090 Request Syntax Specification Version 1.7", RFC 2986, 1091 DOI 10.17487/RFC2986, November 2000, 1092 . 1094 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 1095 Standards (PKCS) #1: RSA Cryptography Specifications 1096 Version 2.1", RFC 3447, DOI 10.17487/RFC3447, February 1097 2003, . 1099 [RFC4253] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) 1100 Transport Layer Protocol", RFC 4253, DOI 10.17487/RFC4253, 1101 January 2006, . 1103 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1104 Housley, R., and W. Polk, "Internet X.509 Public Key 1105 Infrastructure Certificate and Certificate Revocation List 1106 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 1107 . 1109 [RFC5480] Turner, S., Brown, D., Yiu, K., Housley, R., and T. Polk, 1110 "Elliptic Curve Cryptography Subject Public Key 1111 Information", RFC 5480, DOI 10.17487/RFC5480, March 2009, 1112 . 1114 [RFC5915] Turner, S. and D. Brown, "Elliptic Curve Private Key 1115 Structure", RFC 5915, DOI 10.17487/RFC5915, June 2010, 1116 . 1118 [RFC5958] Turner, S., "Asymmetric Key Packages", RFC 5958, 1119 DOI 10.17487/RFC5958, August 2010, 1120 . 1122 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1123 the Network Configuration Protocol (NETCONF)", RFC 6020, 1124 DOI 10.17487/RFC6020, October 2010, 1125 . 1127 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 1128 Protocol (NETCONF) Access Control Model", RFC 6536, 1129 DOI 10.17487/RFC6536, March 2012, 1130 . 1132 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 1133 RFC 6991, DOI 10.17487/RFC6991, July 2013, 1134 . 1136 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1137 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1138 . 1140 9.2. Informative References 1142 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1143 DOI 10.17487/RFC3688, January 2004, 1144 . 1146 [RFC4211] Schaad, J., "Internet X.509 Public Key Infrastructure 1147 Certificate Request Message Format (CRMF)", RFC 4211, 1148 DOI 10.17487/RFC4211, September 2005, 1149 . 1151 [RFC5056] Williams, N., "On the Use of Channel Bindings to Secure 1152 Channels", RFC 5056, DOI 10.17487/RFC5056, November 2007, 1153 . 1155 [RFC5914] Housley, R., Ashmore, S., and C. Wallace, "Trust Anchor 1156 Format", RFC 5914, DOI 10.17487/RFC5914, June 2010, 1157 . 1159 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1160 and A. Bierman, Ed., "Network Configuration Protocol 1161 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1162 . 1164 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1165 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1166 . 1168 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1169 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1170 May 2017, . 1172 [Std-802.1AR-2009] 1173 IEEE SA-Standards Board, "IEEE Standard for Local and 1174 metropolitan area networks - Secure Device Identity", 1175 December 2009, . 1178 Appendix A. Change Log 1180 A.1. server-model-09 to 00 1182 o This draft was split out from draft-ietf-netconf-server-model-09. 1184 o Removed key-usage parameter from generate-private-key action. 1186 o Now /private-keys/private-key/certificates/certificate/name must 1187 be globally unique (unique across all private keys). 1189 o Added top-level 'trusted-ssh-host-keys' and 'user-auth- 1190 credentials' to support SSH client modules. 1192 A.2. keychain-00 to keystore-00 1194 o Renamed module from "keychain" to "keystore" (Issue #3) 1196 A.3. 00 to 01 1198 o Replaced the 'certificate-chain' structures with PKCS#7 1199 structures. (Issue #1) 1201 o Added 'private-key' as a configurable data node, and removed the 1202 'generate-private-key' and 'load-private-key' actions. (Issue #2) 1204 o Moved 'user-auth-credentials' to the ietf-ssh-client module. 1205 (Issues #4 and #5) 1207 A.4. 01 to 02 1209 o Added back 'generate-private-key' action. 1211 o Removed 'RESTRICTED' enum from the 'private-key' leaf type. 1213 o Fixed up a few description statements. 1215 A.5. 02 to 03 1217 o Changed draft's title. 1219 o Added missing references. 1221 o Collapsed sections and levels. 1223 o Added RFC 8174 to Requirements Language Section. 1225 o Renamed 'trusted-certificates' to 'pinned-certificates'. 1227 o Changed 'public-key' from config false to config true. 1229 o Switched 'host-key' from OneAsymmetricKey to definition from RFC 1230 4253. 1232 Author's Address 1234 Kent Watsen 1235 Juniper Networks 1237 EMail: kwatsen@juniper.net