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