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