idnits 2.17.1
draft-ietf-netconf-tls-client-server-06.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
-- The document date (June 4, 2018) is 2153 days in the past. Is this
intentional?
Checking references for intended status: Proposed Standard
----------------------------------------------------------------------------
(See RFCs 3967 and 4897 for information about using normative references
to lower-maturity documents in RFCs)
== Outdated reference: A later version (-35) exists of
draft-ietf-netconf-keystore-04
== Outdated reference: A later version (-28) exists of
draft-ietf-netconf-trust-anchors-00
** Obsolete normative reference: RFC 2246 (Obsoleted by RFC 4346)
** Obsolete normative reference: RFC 4346 (Obsoleted by RFC 5246)
** Obsolete normative reference: RFC 4492 (Obsoleted by RFC 8422)
** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446)
** Obsolete normative reference: RFC 6536 (Obsoleted by RFC 8341)
-- Obsolete informational reference (is this intentional?): RFC 2818
(Obsoleted by RFC 9110)
Summary: 5 errors (**), 0 flaws (~~), 3 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 G. Wu
5 Expires: December 6, 2018 Cisco Systems
6 June 4, 2018
8 YANG Groupings for TLS Clients and TLS Servers
9 draft-ietf-netconf-tls-client-server-06
11 Abstract
13 This document defines three YANG modules: the first defines groupings
14 for a generic TLS client, the second defines groupings for a generic
15 TLS server, and the third defines common identities and groupings
16 used by both the client and the server. It is intended that these
17 groupings will be used by applications using the TLS protocol.
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 This document contains references to other drafts in progress, both
27 in the Normative References section, as well as in body text
28 throughout. Please update the following references to reflect their
29 final RFC assignments:
31 o I-D.ietf-netconf-trust-anchors
33 o I-D.ietf-netconf-keystore
35 Artwork in this document contains shorthand references to drafts in
36 progress. Please apply the following replacements:
38 o "XXXX" --> the assigned RFC value for this draft
40 o "YYYY" --> the assigned RFC value for I-D.ietf-netconf-trust-
41 anchors
43 o "ZZZZ" --> the assigned RFC value for I-D.ietf-netconf-keystore
45 Artwork in this document contains placeholder values for the date of
46 publication of this draft. Please apply the following replacement:
48 o "2018-06-04" --> the publication date of this draft
49 The following Appendix section is to be removed prior to publication:
51 o Appendix A. Change Log
53 Status of This Memo
55 This Internet-Draft is submitted in full conformance with the
56 provisions of BCP 78 and BCP 79.
58 Internet-Drafts are working documents of the Internet Engineering
59 Task Force (IETF). Note that other groups may also distribute
60 working documents as Internet-Drafts. The list of current Internet-
61 Drafts is at https://datatracker.ietf.org/drafts/current/.
63 Internet-Drafts are draft documents valid for a maximum of six months
64 and may be updated, replaced, or obsoleted by other documents at any
65 time. It is inappropriate to use Internet-Drafts as reference
66 material or to cite them other than as "work in progress."
68 This Internet-Draft will expire on December 6, 2018.
70 Copyright Notice
72 Copyright (c) 2018 IETF Trust and the persons identified as the
73 document authors. All rights reserved.
75 This document is subject to BCP 78 and the IETF Trust's Legal
76 Provisions Relating to IETF Documents
77 (https://trustee.ietf.org/license-info) in effect on the date of
78 publication of this document. Please review these documents
79 carefully, as they describe your rights and restrictions with respect
80 to this document. Code Components extracted from this document must
81 include Simplified BSD License text as described in Section 4.e of
82 the Trust Legal Provisions and are provided without warranty as
83 described in the Simplified BSD License.
85 Table of Contents
87 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
88 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4
89 3. The TLS Client Model . . . . . . . . . . . . . . . . . . . . 4
90 3.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 4
91 3.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 5
92 3.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 7
93 4. The TLS Server Model . . . . . . . . . . . . . . . . . . . . 10
94 4.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 10
95 4.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 11
96 4.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 13
98 5. The TLS Common Model . . . . . . . . . . . . . . . . . . . . 16
99 5.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 16
100 5.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 17
101 5.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 17
102 6. Security Considerations . . . . . . . . . . . . . . . . . . . 25
103 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26
104 7.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 26
105 7.2. The YANG Module Names Registry . . . . . . . . . . . . . 27
106 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 27
107 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 27
108 9.1. Normative References . . . . . . . . . . . . . . . . . . 27
109 9.2. Informative References . . . . . . . . . . . . . . . . . 29
110 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 30
111 A.1. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 30
112 A.2. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 30
113 A.3. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 30
114 A.4. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 30
115 A.5. 04 to 05 . . . . . . . . . . . . . . . . . . . . . . . . 31
116 A.6. 05 to 06 . . . . . . . . . . . . . . . . . . . . . . . . 31
117 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 31
119 1. Introduction
121 This document defines three YANG 1.1 [RFC7950] modules: the first
122 defines a grouping for a generic TLS client, the second defines a
123 grouping for a generic TLS server, and the third defines identities
124 and groupings common to both the client and the server (TLS is
125 defined in [RFC5246]). It is intended that these groupings will be
126 used by applications using the TLS protocol. For instance, these
127 groupings could be used to help define the data model for an HTTPS
128 [RFC2818] server or a NETCONF over TLS [RFC7589] based server.
130 The client and server YANG modules in this document each define one
131 grouping, which is focused on just TLS-specific configuration, and
132 specifically avoids any transport-level configuration, such as what
133 ports to listen-on or connect-to. This affords applications the
134 opportunity to define their own strategy for how the underlying TCP
135 connection is established. For instance, applications supporting
136 NETCONF Call Home [RFC8071] could use the "ssh-server-grouping"
137 grouping for the TLS parts it provides, while adding data nodes for
138 the TCP-level call-home configuration.
140 The modules defined in this document uses groupings defined in
141 [I-D.ietf-netconf-keystore] enabling keys to be either locally
142 defined or a reference to globally configured values.
144 2. Terminology
146 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
147 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
148 "OPTIONAL" in this document are to be interpreted as described in BCP
149 14 [RFC2119] [RFC8174] when, and only when, they appear in all
150 capitals, as shown here.
152 3. The TLS Client Model
154 3.1. Tree Diagram
156 This section provides two tree diagrams [RFC8340] for the "ietf-tls-
157 client" module, the first with used groupings expanded and the second
158 with used groupings not expanded.
160 The following tree diagram has used groupings expanded:
162 module: ietf-tls-client
164 grouping tls-client-grouping
165 +-- client-identity
166 | +-- (auth-type)?
167 | +--:(certificate)
168 | +-- certificate
169 | +-- (local-or-keystore)
170 | +--:(local)
171 | | +-- algorithm
172 | | | ct:key-algorithm-ref
173 | | +-- public-key binary
174 | | +-- private-key union
175 | | +-- cert
176 | | | ct:end-entity-cert-cms
177 | | +---n certificate-expiration
178 | | +-- expiration-date? yang:date-and-time
179 | +--:(keystore) {keystore-implemented}?
180 | +-- reference
181 | ks:asymmetric-key-certificate-ref
182 +-- server-auth
183 | +-- pinned-ca-certs? ta:pinned-certificates-ref
184 | +-- pinned-server-certs? ta:pinned-certificates-ref
185 +-- hello-params {tls-client-hello-params-config}?
186 +-- tls-versions
187 | +-- tls-version* identityref
188 +-- cipher-suites
189 +-- cipher-suite* identityref
191 The following tree diagram does not have the groupings expanded:
193 [Note: '\' line wrapping for formatting only]
195 module: ietf-tls-client
197 grouping tls-client-grouping
198 +-- client-identity
199 | +-- (auth-type)?
200 | +--:(certificate)
201 | +-- certificate
202 | +---u ks:local-or-keystore-end-entity-certificate-gr\
203 ouping
204 +-- server-auth
205 | +-- pinned-ca-certs? ta:pinned-certificates-ref
206 | +-- pinned-server-certs? ta:pinned-certificates-ref
207 +-- hello-params {tls-client-hello-params-config}?
208 +---u tlscmn:hello-params-grouping
210 3.2. Example Usage
212 This section presents two examples showing the tls-client-grouping
213 populated with some data. These examples are effectively the same
214 except the first configures the client identity using a local key
215 while the second uses a key configured in a keystore. Both examples
216 are consistent with the examples presented in Section 3 of
217 [I-D.ietf-netconf-trust-anchors] and Section 3.2 of
218 [I-D.ietf-netconf-keystore].
220 The following example configures the client identity using a local
221 key:
223 [Note: '\' line wrapping for formatting only]
225
227
228
229
230 ct:rsa1024
232 base64encodedvalue==
233 base64encodedvalue==
234 base64encodedvalue==
235
236
238
239
240 explicitly-trusted-server-ca-certs
242 explicitly-trusted-server-certs
244
246
248 The following example configures the client identity using a key from
249 the keystore:
251 [Note: '\' line wrapping for formatting only]
253
255
256
257
258 ex-rsa-cert
259
260
262
263
264 explicitly-trusted-server-ca-certs
266 explicitly-trusted-server-certs
268
270
272 3.3. YANG Module
274 This YANG module has normative references to
275 [I-D.ietf-netconf-trust-anchors] and [I-D.ietf-netconf-keystore].
277 file "ietf-tls-client@2018-06-04.yang"
278 module ietf-tls-client {
279 yang-version 1.1;
281 namespace "urn:ietf:params:xml:ns:yang:ietf-tls-client";
282 prefix "tlsc";
284 import ietf-tls-common {
285 prefix tlscmn;
286 revision-date 2018-06-04; // stable grouping definitions
287 reference
288 "RFC XXXX: YANG Groupings for TLS Clients and TLS Servers";
289 }
291 import ietf-trust-anchors {
292 prefix ta;
293 reference
294 "RFC YYYY: YANG Data Model for Global Trust Anchors";
295 }
297 import ietf-keystore {
298 prefix ks;
299 reference
300 "RFC ZZZZ: YANG Data Model for a 'Keystore' Mechanism";
301 }
303 organization
304 "IETF NETCONF (Network Configuration) Working Group";
306 contact
307 "WG Web:
308 WG List:
310 Author: Kent Watsen
311
313 Author: Gary Wu
314 ";
316 description
317 "This module defines a reusable grouping for a TLS client that
318 can be used as a basis for specific TLS client instances.
320 Copyright (c) 2018 IETF Trust and the persons identified as
321 authors of the code. All rights reserved.
323 Redistribution and use in source and binary forms, with or
324 without modification, is permitted pursuant to, and subject
325 to the license terms contained in, the Simplified BSD
326 License set forth in Section 4.c of the IETF Trust's
327 Legal Provisions Relating to IETF Documents
328 (http://trustee.ietf.org/license-info).
330 This version of this YANG module is part of RFC XXXX; see
331 the RFC itself for full legal notices.";
333 revision "2018-06-04" {
334 description
335 "Initial version";
336 reference
337 "RFC XXXX: YANG Groupings for TLS Clients and TLS Servers";
338 }
340 // features
342 feature tls-client-hello-params-config {
343 description
344 "TLS hello message parameters are configurable on a TLS
345 client.";
347 }
349 // groupings
351 grouping tls-client-grouping {
352 description
353 "A reusable grouping for configuring a TLS client without
354 any consideration for how an underlying TCP session is
355 established.";
357 container client-identity {
358 description
359 "The credentials used by the client to authenticate to
360 the TLS server.";
362 choice auth-type {
363 description
364 "The authentication type.";
365 container certificate {
366 uses ks:local-or-keystore-end-entity-certificate-grouping;
367 description
368 "A locally-defined or referenced certificate
369 to be used for client authentication.";
370 reference
371 "RFC ZZZZ: YANG Data Model for a 'Keystore' Mechanism";
372 }
373 }
374 } // end client-identity
376 container server-auth {
377 must 'pinned-ca-certs or pinned-server-certs';
378 description
379 "Trusted server identities.";
380 leaf pinned-ca-certs {
381 type ta:pinned-certificates-ref;
382 description
383 "A reference to a list of certificate authority (CA)
384 certificates used by the TLS client to authenticate
385 TLS server certificates. A server certificate is
386 authenticated if it has a valid chain of trust to
387 a configured pinned CA certificate.";
388 }
390 leaf pinned-server-certs {
391 type ta:pinned-certificates-ref;
392 description
393 "A reference to a list of server certificates used by
394 the TLS client to authenticate TLS server certificates.
396 A server certificate is authenticated if it is an
397 exact match to a configured pinned server certificate.";
398 }
399 }
401 container hello-params {
402 if-feature tls-client-hello-params-config;
403 uses tlscmn:hello-params-grouping;
404 description
405 "Configurable parameters for the TLS hello message.";
406 }
408 } // end tls-client-grouping
410 }
411
413 4. The TLS Server Model
415 4.1. Tree Diagram
417 This section provides two tree diagrams [RFC8340] for the "ietf-tls-
418 server" module, the first with used groupings expanded and the second
419 with used groupings not expanded.
421 The following tree diagram has used groupings expanded:
423 module: ietf-tls-server
425 grouping tls-server-grouping
426 +-- server-identity
427 | +-- (local-or-keystore)
428 | +--:(local)
429 | | +-- algorithm ct:key-algorithm-ref
430 | | +-- public-key binary
431 | | +-- private-key union
432 | | +-- cert ct:end-entity-cert-cms
433 | | +---n certificate-expiration
434 | | +-- expiration-date? yang:date-and-time
435 | +--:(keystore) {keystore-implemented}?
436 | +-- reference
437 | ks:asymmetric-key-certificate-ref
438 +-- client-auth
439 | +-- pinned-ca-certs? ta:pinned-certificates-ref
440 | +-- pinned-client-certs? ta:pinned-certificates-ref
441 +-- hello-params {tls-server-hello-params-config}?
442 +-- tls-versions
443 | +-- tls-version* identityref
444 +-- cipher-suites
445 +-- cipher-suite* identityref
447 The following tree diagram does not have the used groupings expanded:
449 module: ietf-tls-server
451 grouping tls-server-grouping
452 +-- server-identity
453 | +---u ks:local-or-keystore-end-entity-certificate-grouping
454 +-- client-auth
455 | +-- pinned-ca-certs? ta:pinned-certificates-ref
456 | +-- pinned-client-certs? ta:pinned-certificates-ref
457 +-- hello-params {tls-server-hello-params-config}?
458 +---u tlscmn:hello-params-grouping
460 4.2. Example Usage
462 This section presents two examples showing the tls-server-grouping
463 populated with some data. These examples are effectively the same
464 except the first configures the server identity using a local key
465 while the second uses a key configured in a keystore. Both examples
466 are consistent with the examples presented in Section 3 of
467 [I-D.ietf-netconf-trust-anchors] and Section 3.2 of
468 [I-D.ietf-netconf-keystore].
470 The following example configures the server identity using a local
471 key:
473 [Note: '\' line wrapping for formatting only]
475
477
478
479 ct:rsa1024
481 base64encodedvalue==
482 base64encodedvalue==
483 base64encodedvalue==
484
486
487
488 explicitly-trusted-client-ca-certs
490 explicitly-trusted-client-certs
492
494
496 The following example configures the server identity using a key from
497 the keystore:
499 [Note: '\' line wrapping for formatting only]
501
503
504
505 ex-rsa-cert
506
508
509
510 explicitly-trusted-client-ca-certs
512 explicitly-trusted-client-certs
514
516
518 4.3. YANG Module
520 This YANG module has a normative references to [RFC5246],
521 [I-D.ietf-netconf-trust-anchors] and [I-D.ietf-netconf-keystore].
523 file "ietf-tls-server@2018-06-04.yang"
524 module ietf-tls-server {
525 yang-version 1.1;
527 namespace "urn:ietf:params:xml:ns:yang:ietf-tls-server";
528 prefix "tlss";
530 import ietf-tls-common {
531 prefix tlscmn;
532 revision-date 2018-06-04; // stable grouping definitions
533 reference
534 "RFC XXXX: YANG Groupings for TLS Clients and TLS Servers";
535 }
537 import ietf-trust-anchors {
538 prefix ta;
539 reference
540 "RFC YYYY: YANG Data Model for Global Trust Anchors";
541 }
543 import ietf-keystore {
544 prefix ks;
545 reference
546 "RFC ZZZZ: YANG Data Model for a 'Keystore' Mechanism";
548 }
550 organization
551 "IETF NETCONF (Network Configuration) Working Group";
553 contact
554 "WG Web:
555 WG List:
557 Author: Kent Watsen
558
560 Author: Gary Wu
561 ";
563 description
564 "This module defines a reusable grouping for a TLS server that
565 can be used as a basis for specific TLS server instances.
567 Copyright (c) 2018 IETF Trust and the persons identified as
568 authors of the code. All rights reserved.
570 Redistribution and use in source and binary forms, with or
571 without modification, is permitted pursuant to, and subject
572 to the license terms contained in, the Simplified BSD
573 License set forth in Section 4.c of the IETF Trust's
574 Legal Provisions Relating to IETF Documents
575 (http://trustee.ietf.org/license-info).
577 This version of this YANG module is part of RFC XXXX; see
578 the RFC itself for full legal notices.";
580 revision "2018-06-04" {
581 description
582 "Initial version";
583 reference
584 "RFC XXXX: YANG Groupings for TLS Clients and TLS Servers";
585 }
587 // features
589 feature tls-server-hello-params-config {
590 description
591 "TLS hello message parameters are configurable on a TLS
592 server.";
593 }
594 // groupings
596 grouping tls-server-grouping {
597 description
598 "A reusable grouping for configuring a TLS server without
599 any consideration for how underlying TCP sessions are
600 established.";
602 container server-identity {
603 description
604 "A locally-defined or referenced end-entity certificate,
605 including any configured intermediate certificates, the
606 TLS server will present when establishing a TLS connection
607 in its Certificate message, as defined in Section 7.4.2
608 in RFC 5246.";
609 reference
610 "RFC 5246:
611 The Transport Layer Security (TLS) Protocol Version 1.2
612 RFC ZZZZ:
613 YANG Data Model for a 'Keystore' Mechanism";
614 uses ks:local-or-keystore-end-entity-certificate-grouping;
615 }
617 container client-auth {
618 description
619 "A reference to a list of pinned certificate authority (CA)
620 certificates and a reference to a list of pinned client
621 certificates.";
622 leaf pinned-ca-certs {
623 type ta:pinned-certificates-ref;
624 description
625 "A reference to a list of certificate authority (CA)
626 certificates used by the TLS server to authenticate
627 TLS client certificates. A client certificate is
628 authenticated if it has a valid chain of trust to
629 a configured pinned CA certificate.";
630 reference
631 "RFC YYYY: YANG Data Model for Global Trust Anchors";
632 }
633 leaf pinned-client-certs {
634 type ta:pinned-certificates-ref;
635 description
636 "A reference to a list of client certificates used by
637 the TLS server to authenticate TLS client certificates.
638 A clients certificate is authenticated if it is an
639 exact match to a configured pinned client certificate.";
640 reference
641 "RFC YYYY: YANG Data Model for Global Trust Anchors";
643 }
644 }
646 container hello-params {
647 if-feature tls-server-hello-params-config;
648 uses tlscmn:hello-params-grouping;
649 description
650 "Configurable parameters for the TLS hello message.";
651 }
653 } // end tls-server-grouping
655 }
656
658 5. The TLS Common Model
660 The TLS common model presented in this section contains identities
661 and groupings common to both TLS clients and TLS servers. The hello-
662 params-grouping can be used to configure the list of TLS algorithms
663 permitted by the TLS client or TLS server. The lists of algorithms
664 are ordered such that, if multiple algorithms are permitted by the
665 client, the algorithm that appears first in its list that is also
666 permitted by the server is used for the TLS transport layer
667 connection. The ability to restrict the the algorithms allowed is
668 provided in this grouping for TLS clients and TLS servers that are
669 capable of doing so and may serve to make TLS clients and TLS servers
670 compliant with security policies.
672 Features are defined for algorithms that are OPTIONAL or are not
673 widely supported by popular implementations. Note that the list of
674 algorithms is not exhaustive.
676 5.1. Tree Diagram
678 The following tree diagram [RFC8340] provides an overview of the data
679 model for the "ietf-tls-common" module.
681 module: ietf-tls-common
683 grouping hello-params-grouping
684 +-- tls-versions
685 | +-- tls-version* identityref
686 +-- cipher-suites
687 +-- cipher-suite* identityref
689 5.2. Example Usage
691 This section shows how it would appear if the transport-params-
692 grouping were populated with some data.
694
697
698 tlscmn:tls-1.1
699 tlscmn:tls-1.2
700
701
702 tlscmn:dhe-rsa-with-aes-128-cbc-sha
703 tlscmn:rsa-with-aes-128-cbc-sha
704 tlscmn:rsa-with-3des-ede-cbc-sha
705
706
708 5.3. YANG Module
710 This YANG module has a normative references to [RFC2246], [RFC4346],
711 [RFC4492], [RFC5246], [RFC5288], and [RFC5289].
713 file "ietf-tls-common@2018-06-04.yang"
714 module ietf-tls-common {
715 yang-version 1.1;
717 namespace "urn:ietf:params:xml:ns:yang:ietf-tls-common";
718 prefix "tlscmn";
720 organization
721 "IETF NETCONF (Network Configuration) Working Group";
723 contact
724 "WG Web:
725 WG List:
727 Author: Kent Watsen
728
730 Author: Gary Wu
731 ";
733 description
734 "This module defines a common features, identities, and groupings
735 for Transport Layer Security (TLS).
737 Copyright (c) 2018 IETF Trust and the persons identified as
738 authors of the code. All rights reserved.
740 Redistribution and use in source and binary forms, with or
741 without modification, is permitted pursuant to, and subject
742 to the license terms contained in, the Simplified BSD
743 License set forth in Section 4.c of the IETF Trust's
744 Legal Provisions Relating to IETF Documents
745 (http://trustee.ietf.org/license-info).
747 This version of this YANG module is part of RFC XXXX; see
748 the RFC itself for full legal notices.";
750 revision "2018-06-04" {
751 description
752 "Initial version";
753 reference
754 "RFC XXXX: YANG Groupings for TLS Clients and TLS Servers";
755 }
757 // features
759 feature tls-1_0 {
760 description
761 "TLS Protocol Version 1.0 is supported.";
762 reference
763 "RFC 2246: The TLS Protocol Version 1.0";
764 }
766 feature tls-1_1 {
767 description
768 "TLS Protocol Version 1.1 is supported.";
769 reference
770 "RFC 4346: The Transport Layer Security (TLS) Protocol
771 Version 1.1";
772 }
774 feature tls-1_2 {
775 description
776 "TLS Protocol Version 1.2 is supported.";
777 reference
778 "RFC 5246: The Transport Layer Security (TLS) Protocol
779 Version 1.2";
780 }
782 feature tls-ecc {
783 description
784 "Elliptic Curve Cryptography (ECC) is supported for TLS.";
786 reference
787 "RFC 4492: Elliptic Curve Cryptography (ECC) Cipher Suites
788 for Transport Layer Security (TLS)";
789 }
791 feature tls-dhe {
792 description
793 "Ephemeral Diffie-Hellman key exchange is supported for TLS.";
794 reference
795 "RFC 5246: The Transport Layer Security (TLS) Protocol
796 Version 1.2";
797 }
799 feature tls-3des {
800 description
801 "The Triple-DES block cipher is supported for TLS.";
802 reference
803 "RFC 5246: The Transport Layer Security (TLS) Protocol
804 Version 1.2";
805 }
807 feature tls-gcm {
808 description
809 "The Galois/Counter Mode authenticated encryption mode is
810 supported for TLS.";
811 reference
812 "RFC 5288: AES Galois Counter Mode (GCM) Cipher Suites for
813 TLS";
814 }
816 feature tls-sha2 {
817 description
818 "The SHA2 family of cryptographic hash functions is supported
819 for TLS.";
820 reference
821 "FIPS PUB 180-4: Secure Hash Standard (SHS)";
822 }
824 // identities
826 identity tls-version-base {
827 description
828 "Base identity used to identify TLS protocol versions.";
829 }
831 identity tls-1.0 {
832 base tls-version-base;
833 if-feature tls-1_0;
834 description
835 "TLS Protocol Version 1.0.";
836 reference
837 "RFC 2246: The TLS Protocol Version 1.0";
838 }
840 identity tls-1.1 {
841 base tls-version-base;
842 if-feature tls-1_1;
843 description
844 "TLS Protocol Version 1.1.";
845 reference
846 "RFC 4346: The Transport Layer Security (TLS) Protocol
847 Version 1.1";
848 }
850 identity tls-1.2 {
851 base tls-version-base;
852 if-feature tls-1_2;
853 description
854 "TLS Protocol Version 1.2.";
855 reference
856 "RFC 5246: The Transport Layer Security (TLS) Protocol
857 Version 1.2";
858 }
860 identity cipher-suite-base {
861 description
862 "Base identity used to identify TLS cipher suites.";
863 }
865 identity rsa-with-aes-128-cbc-sha {
866 base cipher-suite-base;
867 description
868 "Cipher suite TLS_RSA_WITH_AES_128_CBC_SHA.";
869 reference
870 "RFC 5246: The Transport Layer Security (TLS) Protocol
871 Version 1.2";
872 }
874 identity rsa-with-aes-256-cbc-sha {
875 base cipher-suite-base;
876 description
877 "Cipher suite TLS_RSA_WITH_AES_256_CBC_SHA.";
878 reference
879 "RFC 5246: The Transport Layer Security (TLS) Protocol
880 Version 1.2";
881 }
882 identity rsa-with-aes-128-cbc-sha256 {
883 base cipher-suite-base;
884 if-feature tls-sha2;
885 description
886 "Cipher suite TLS_RSA_WITH_AES_128_CBC_SHA256.";
887 reference
888 "RFC 5246: The Transport Layer Security (TLS) Protocol
889 Version 1.2";
890 }
892 identity rsa-with-aes-256-cbc-sha256 {
893 base cipher-suite-base;
894 if-feature tls-sha2;
895 description
896 "Cipher suite TLS_RSA_WITH_AES_256_CBC_SHA256.";
897 reference
898 "RFC 5246: The Transport Layer Security (TLS) Protocol
899 Version 1.2";
900 }
902 identity dhe-rsa-with-aes-128-cbc-sha {
903 base cipher-suite-base;
904 if-feature tls-dhe;
905 description
906 "Cipher suite TLS_DHE_RSA_WITH_AES_128_CBC_SHA.";
907 reference
908 "RFC 5246: The Transport Layer Security (TLS) Protocol
909 Version 1.2";
910 }
912 identity dhe-rsa-with-aes-256-cbc-sha {
913 base cipher-suite-base;
914 if-feature tls-dhe;
915 description
916 "Cipher suite TLS_DHE_RSA_WITH_AES_256_CBC_SHA.";
917 reference
918 "RFC 5246: The Transport Layer Security (TLS) Protocol
919 Version 1.2";
920 }
922 identity dhe-rsa-with-aes-128-cbc-sha256 {
923 base cipher-suite-base;
924 if-feature "tls-dhe and tls-sha2";
925 description
926 "Cipher suite TLS_DHE_RSA_WITH_AES_128_CBC_SHA256.";
927 reference
928 "RFC 5246: The Transport Layer Security (TLS) Protocol
929 Version 1.2";
931 }
933 identity dhe-rsa-with-aes-256-cbc-sha256 {
934 base cipher-suite-base;
935 if-feature "tls-dhe and tls-sha2";
936 description
937 "Cipher suite TLS_DHE_RSA_WITH_AES_256_CBC_SHA256.";
938 reference
939 "RFC 5246: The Transport Layer Security (TLS) Protocol
940 Version 1.2";
941 }
943 identity ecdhe-ecdsa-with-aes-128-cbc-sha256 {
944 base cipher-suite-base;
945 if-feature "tls-ecc and tls-sha2";
946 description
947 "Cipher suite TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256.";
948 reference
949 "RFC 5289: TLS Elliptic Curve Cipher Suites with
950 SHA-256/384 and AES Galois Counter Mode (GCM)";
951 }
953 identity ecdhe-ecdsa-with-aes-256-cbc-sha384 {
954 base cipher-suite-base;
955 if-feature "tls-ecc and tls-sha2";
956 description
957 "Cipher suite TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384.";
958 reference
959 "RFC 5289: TLS Elliptic Curve Cipher Suites with
960 SHA-256/384 and AES Galois Counter Mode (GCM)";
961 }
963 identity ecdhe-rsa-with-aes-128-cbc-sha256 {
964 base cipher-suite-base;
965 if-feature "tls-ecc and tls-sha2";
966 description
967 "Cipher suite TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256.";
968 reference
969 "RFC 5289: TLS Elliptic Curve Cipher Suites with
970 SHA-256/384 and AES Galois Counter Mode (GCM)";
971 }
973 identity ecdhe-rsa-with-aes-256-cbc-sha384 {
974 base cipher-suite-base;
975 if-feature "tls-ecc and tls-sha2";
976 description
977 "Cipher suite TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384.";
978 reference
979 "RFC 5289: TLS Elliptic Curve Cipher Suites with
980 SHA-256/384 and AES Galois Counter Mode (GCM)";
981 }
983 identity ecdhe-ecdsa-with-aes-128-gcm-sha256 {
984 base cipher-suite-base;
985 if-feature "tls-ecc and tls-gcm and tls-sha2";
986 description
987 "Cipher suite TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256.";
988 reference
989 "RFC 5289: TLS Elliptic Curve Cipher Suites with
990 SHA-256/384 and AES Galois Counter Mode (GCM)";
991 }
993 identity ecdhe-ecdsa-with-aes-256-gcm-sha384 {
994 base cipher-suite-base;
995 if-feature "tls-ecc and tls-gcm and tls-sha2";
996 description
997 "Cipher suite TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384.";
998 reference
999 "RFC 5289: TLS Elliptic Curve Cipher Suites with
1000 SHA-256/384 and AES Galois Counter Mode (GCM)";
1001 }
1003 identity ecdhe-rsa-with-aes-128-gcm-sha256 {
1004 base cipher-suite-base;
1005 if-feature "tls-ecc and tls-gcm and tls-sha2";
1006 description
1007 "Cipher suite TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256.";
1008 reference
1009 "RFC 5289: TLS Elliptic Curve Cipher Suites with
1010 SHA-256/384 and AES Galois Counter Mode (GCM)";
1011 }
1013 identity ecdhe-rsa-with-aes-256-gcm-sha384 {
1014 base cipher-suite-base;
1015 if-feature "tls-ecc and tls-gcm and tls-sha2";
1016 description
1017 "Cipher suite TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384.";
1018 reference
1019 "RFC 5289: TLS Elliptic Curve Cipher Suites with
1020 SHA-256/384 and AES Galois Counter Mode (GCM)";
1021 }
1023 identity rsa-with-3des-ede-cbc-sha {
1024 base cipher-suite-base;
1025 if-feature tls-3des;
1026 description
1027 "Cipher suite TLS_RSA_WITH_3DES_EDE_CBC_SHA.";
1028 reference
1029 "RFC 5246: The Transport Layer Security (TLS) Protocol
1030 Version 1.2";
1031 }
1033 identity ecdhe-rsa-with-3des-ede-cbc-sha {
1034 base cipher-suite-base;
1035 if-feature "tls-ecc and tls-3des";
1036 description
1037 "Cipher suite TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA.";
1038 reference
1039 "RFC 4492: Elliptic Curve Cryptography (ECC) Cipher Suites
1040 for Transport Layer Security (TLS)";
1041 }
1043 identity ecdhe-rsa-with-aes-128-cbc-sha {
1044 base cipher-suite-base;
1045 if-feature "tls-ecc";
1046 description
1047 "Cipher suite TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA.";
1048 reference
1049 "RFC 4492: Elliptic Curve Cryptography (ECC) Cipher Suites
1050 for Transport Layer Security (TLS)";
1051 }
1053 identity ecdhe-rsa-with-aes-256-cbc-sha {
1054 base cipher-suite-base;
1055 if-feature "tls-ecc";
1056 description
1057 "Cipher suite TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA.";
1058 reference
1059 "RFC 4492: Elliptic Curve Cryptography (ECC) Cipher Suites
1060 for Transport Layer Security (TLS)";
1061 }
1063 // groupings
1065 grouping hello-params-grouping {
1066 description
1067 "A reusable grouping for TLS hello message parameters.";
1068 reference
1069 "RFC 5246: The Transport Layer Security (TLS) Protocol
1070 Version 1.2";
1072 container tls-versions {
1073 description
1074 "Parameters regarding TLS versions.";
1076 leaf-list tls-version {
1077 type identityref {
1078 base tls-version-base;
1079 }
1080 description
1081 "Acceptable TLS protocol versions.
1083 If this leaf-list is not configured (has zero elements)
1084 the acceptable TLS protocol versions are implementation-
1085 defined.";
1086 }
1087 }
1088 container cipher-suites {
1089 description
1090 "Parameters regarding cipher suites.";
1091 leaf-list cipher-suite {
1092 type identityref {
1093 base cipher-suite-base;
1094 }
1095 ordered-by user;
1096 description
1097 "Acceptable cipher suites in order of descending
1098 preference.
1100 If this leaf-list is not configured (has zero elements)
1101 the acceptable cipher suites are implementation-
1102 defined.";
1103 }
1104 }
1106 } // end hello-params-grouping
1108 }
1109
1111 6. Security Considerations
1113 The YANG modules defined in this document are designed to be accessed
1114 via YANG based management protocols, such as NETCONF [RFC6241] and
1115 RESTCONF [RFC8040]. Both of these protocols have mandatory-to-
1116 implement secure transport layers (e.g., SSH, TLS) with mutual
1117 authentication.
1119 The NETCONF access control model (NACM) [RFC6536] provides the means
1120 to restrict access for particular users to a pre-configured subset of
1121 all available protocol operations and content.
1123 Since the modules defined in this document only define groupings,
1124 these considerations are primarily for the designers of other modules
1125 that use these groupings.
1127 There are a number of data nodes defined in the YANG modules that are
1128 writable/creatable/deletable (i.e., config true, which is the
1129 default). These data nodes may be considered sensitive or vulnerable
1130 in some network environments. Write operations (e.g., edit-config)
1131 to these data nodes without proper protection can have a negative
1132 effect on network operations. These are the subtrees and data nodes
1133 and their sensitivity/vulnerability:
1135 /: The entire data tree of all the groupings defined in this draft
1136 is sensitive to write operations. For instance, the addition
1137 or removal of references to keys, certificates, trusted
1138 anchors, etc., can dramatically alter the implemented security
1139 policy. However, no NACM annotations are applied as the data
1140 SHOULD be editable by users other than a designated 'recovery
1141 session'.
1143 Some of the readable data nodes in the YANG modules may be considered
1144 sensitive or vulnerable in some network environments. It is thus
1145 important to control read access (e.g., via get, get-config, or
1146 notification) to these data nodes. These are the subtrees and data
1147 nodes and their sensitivity/vulnerability:
1149 NONE
1151 Some of the RPC operations in this YANG module may be considered
1152 sensitive or vulnerable in some network environments. It is thus
1153 important to control access to these operations. These are the
1154 operations and their sensitivity/vulnerability:
1156 NONE
1158 7. IANA Considerations
1160 7.1. The IETF XML Registry
1162 This document registers three URIs in the IETF XML registry
1163 [RFC3688]. Following the format in [RFC3688], the following
1164 registrations are requested:
1166 URI: urn:ietf:params:xml:ns:yang:ietf-tls-client
1167 Registrant Contact: The NETCONF WG of the IETF.
1168 XML: N/A, the requested URI is an XML namespace.
1170 URI: urn:ietf:params:xml:ns:yang:ietf-tls-server
1171 Registrant Contact: The NETCONF WG of the IETF.
1172 XML: N/A, the requested URI is an XML namespace.
1174 URI: urn:ietf:params:xml:ns:yang:ietf-tls-common
1175 Registrant Contact: The NETCONF WG of the IETF.
1176 XML: N/A, the requested URI is an XML namespace.
1178 7.2. The YANG Module Names Registry
1180 This document registers three YANG modules in the YANG Module Names
1181 registry [RFC7950]. Following the format in [RFC7950], the the
1182 following registrations are requested:
1184 name: ietf-tls-client
1185 namespace: urn:ietf:params:xml:ns:yang:ietf-tls-client
1186 prefix: tlsc
1187 reference: RFC XXXX
1189 name: ietf-tls-server
1190 namespace: urn:ietf:params:xml:ns:yang:ietf-tls-server
1191 prefix: tlss
1192 reference: RFC XXXX
1194 name: ietf-tls-common
1195 namespace: urn:ietf:params:xml:ns:yang:ietf-tls-common
1196 prefix: tlscmn
1197 reference: RFC XXXX
1199 8. Acknowledgements
1201 The authors would like to thank for following for lively discussions
1202 on list and in the halls (ordered by last name): Andy Bierman, Martin
1203 Bjorklund, Benoit Claise, Mehmet Ersue, Balazs Kovacs, David
1204 Lamparter, Alan Luchuk, Ladislav Lhotka, Radek Krejci, Tom Petch,
1205 Juergen Schoenwaelder, Phil Shafer, Sean Turner, and Bert Wijnen.
1207 9. References
1209 9.1. Normative References
1211 [I-D.ietf-netconf-keystore]
1212 Watsen, K., "YANG Data Model for a "Keystore" Mechanism",
1213 draft-ietf-netconf-keystore-04 (work in progress), October
1214 2017.
1216 [I-D.ietf-netconf-trust-anchors]
1217 Watsen, K., "YANG Data Model for Global Trust Anchors",
1218 draft-ietf-netconf-trust-anchors-00 (work in progress),
1219 June 2018.
1221 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
1222 Requirement Levels", BCP 14, RFC 2119,
1223 DOI 10.17487/RFC2119, March 1997,
1224 .
1226 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0",
1227 RFC 2246, DOI 10.17487/RFC2246, January 1999,
1228 .
1230 [RFC4346] Dierks, T. and E. Rescorla, "The Transport Layer Security
1231 (TLS) Protocol Version 1.1", RFC 4346,
1232 DOI 10.17487/RFC4346, April 2006,
1233 .
1235 [RFC4492] Blake-Wilson, S., Bolyard, N., Gupta, V., Hawk, C., and B.
1236 Moeller, "Elliptic Curve Cryptography (ECC) Cipher Suites
1237 for Transport Layer Security (TLS)", RFC 4492,
1238 DOI 10.17487/RFC4492, May 2006,
1239 .
1241 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
1242 (TLS) Protocol Version 1.2", RFC 5246,
1243 DOI 10.17487/RFC5246, August 2008,
1244 .
1246 [RFC5288] Salowey, J., Choudhury, A., and D. McGrew, "AES Galois
1247 Counter Mode (GCM) Cipher Suites for TLS", RFC 5288,
1248 DOI 10.17487/RFC5288, August 2008,
1249 .
1251 [RFC5289] Rescorla, E., "TLS Elliptic Curve Cipher Suites with SHA-
1252 256/384 and AES Galois Counter Mode (GCM)", RFC 5289,
1253 DOI 10.17487/RFC5289, August 2008,
1254 .
1256 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration
1257 Protocol (NETCONF) Access Control Model", RFC 6536,
1258 DOI 10.17487/RFC6536, March 2012,
1259 .
1261 [RFC7589] Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the
1262 NETCONF Protocol over Transport Layer Security (TLS) with
1263 Mutual X.509 Authentication", RFC 7589,
1264 DOI 10.17487/RFC7589, June 2015,
1265 .
1267 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
1268 RFC 7950, DOI 10.17487/RFC7950, August 2016,
1269 .
1271 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
1272 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
1273 May 2017, .
1275 9.2. Informative References
1277 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818,
1278 DOI 10.17487/RFC2818, May 2000,
1279 .
1281 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
1282 DOI 10.17487/RFC3688, January 2004,
1283 .
1285 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
1286 and A. Bierman, Ed., "Network Configuration Protocol
1287 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
1288 .
1290 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
1291 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
1292 .
1294 [RFC8071] Watsen, K., "NETCONF Call Home and RESTCONF Call Home",
1295 RFC 8071, DOI 10.17487/RFC8071, February 2017,
1296 .
1298 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams",
1299 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018,
1300 .
1302 Appendix A. Change Log
1304 A.1. 00 to 01
1306 o Noted that '0.0.0.0' and '::' might have special meanings.
1308 o Renamed "keychain" to "keystore".
1310 A.2. 01 to 02
1312 o Removed the groupings containing transport-level configuration.
1313 Now modules contain only the transport-independent groupings.
1315 o Filled in previously incomplete 'ietf-tls-client' module.
1317 o Added cipher suites for various algorithms into new 'ietf-tls-
1318 common' module.
1320 A.3. 02 to 03
1322 o Added a 'must' statement to container 'server-auth' asserting that
1323 at least one of the various auth mechanisms must be specified.
1325 o Fixed description statement for leaf 'trusted-ca-certs'.
1327 A.4. 03 to 04
1329 o Updated title to "YANG Groupings for TLS Clients and TLS Servers"
1331 o Updated leafref paths to point to new keystore path
1333 o Changed the YANG prefix for ietf-tls-common from 'tlscom' to
1334 'tlscmn'.
1336 o Added TLS protocol verions 1.0 and 1.1.
1338 o Made author lists consistent
1340 o Now tree diagrams reference ietf-netmod-yang-tree-diagrams
1342 o Updated YANG to use typedefs around leafrefs to common keystore
1343 paths
1345 o Now inlines key and certificates (no longer a leafref to keystore)
1347 A.5. 04 to 05
1349 o Merged changes from co-author.
1351 A.6. 05 to 06
1353 o Updated to use trust anchors from trust-anchors draft (was
1354 keystore draft)
1356 o Now Uses new keystore grouping enabling asymmetric key to be
1357 either locally defined or a reference to the keystore.
1359 Authors' Addresses
1361 Kent Watsen
1362 Juniper Networks
1364 EMail: kwatsen@juniper.net
1366 Gary Wu
1367 Cisco Systems
1369 EMail: garywu@cisco.com