idnits 2.17.1 draft-ietf-netconf-tls-client-server-23.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 (10 February 2021) is 1168 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 (-34) exists of draft-ietf-netconf-crypto-types-18 == Outdated reference: A later version (-35) exists of draft-ietf-netconf-keystore-20 == Outdated reference: A later version (-28) exists of draft-ietf-netconf-trust-anchors-13 == Outdated reference: A later version (-20) exists of draft-ietf-netconf-http-client-server-05 == Outdated reference: A later version (-36) exists of draft-ietf-netconf-netconf-client-server-21 == Outdated reference: A later version (-36) exists of draft-ietf-netconf-restconf-client-server-21 == Outdated reference: A later version (-40) exists of draft-ietf-netconf-ssh-client-server-22 == Outdated reference: A later version (-26) exists of draft-ietf-netconf-tcp-client-server-08 == Outdated reference: A later version (-41) exists of draft-ietf-netconf-tls-client-server-22 -- Obsolete informational reference (is this intentional?): RFC 2246 (Obsoleted by RFC 4346) -- Obsolete informational reference (is this intentional?): RFC 2818 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 4346 (Obsoleted by RFC 5246) -- Obsolete informational reference (is this intentional?): RFC 5246 (Obsoleted by RFC 8446) Summary: 0 errors (**), 0 flaws (~~), 10 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF Working Group K. Watsen 3 Internet-Draft Watsen Networks 4 Intended status: Standards Track 10 February 2021 5 Expires: 14 August 2021 7 YANG Groupings for TLS Clients and TLS Servers 8 draft-ietf-netconf-tls-client-server-23 10 Abstract 12 This document defines three YANG modules: the first defines groupings 13 for a generic TLS client, the second defines groupings for a generic 14 TLS server, and the third defines common identities and groupings 15 used by both the client and the server. It is intended that these 16 groupings will be used by applications using the TLS protocol. 18 Editorial Note (To be removed by RFC Editor) 20 This draft contains placeholder values that need to be replaced with 21 finalized values at the time of publication. This note summarizes 22 all of the substitutions that are needed. No other RFC Editor 23 instructions are specified elsewhere in this document. 25 Artwork in this document contains shorthand references to drafts in 26 progress. Please apply the following replacements: 28 * "AAAA" --> the assigned RFC value for draft-ietf-netconf-crypto- 29 types 31 * "BBBB" --> the assigned RFC value for draft-ietf-netconf-trust- 32 anchors 34 * "CCCC" --> the assigned RFC value for draft-ietf-netconf-keystore 36 * "DDDD" --> the assigned RFC value for draft-ietf-netconf-tcp- 37 client-server 39 * "FFFF" --> the assigned RFC value for this draft 41 Artwork in this document contains placeholder values for the date of 42 publication of this draft. Please apply the following replacement: 44 * "2021-02-10" --> the publication date of this draft 46 The following Appendix section is to be removed prior to publication: 48 * Appendix A. Change Log 50 Status of This Memo 52 This Internet-Draft is submitted in full conformance with the 53 provisions of BCP 78 and BCP 79. 55 Internet-Drafts are working documents of the Internet Engineering 56 Task Force (IETF). Note that other groups may also distribute 57 working documents as Internet-Drafts. The list of current Internet- 58 Drafts is at https://datatracker.ietf.org/drafts/current/. 60 Internet-Drafts are draft documents valid for a maximum of six months 61 and may be updated, replaced, or obsoleted by other documents at any 62 time. It is inappropriate to use Internet-Drafts as reference 63 material or to cite them other than as "work in progress." 65 This Internet-Draft will expire on 14 August 2021. 67 Copyright Notice 69 Copyright (c) 2021 IETF Trust and the persons identified as the 70 document authors. All rights reserved. 72 This document is subject to BCP 78 and the IETF Trust's Legal 73 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 74 license-info) in effect on the date of publication of this document. 75 Please review these documents carefully, as they describe your rights 76 and restrictions with respect to this document. Code Components 77 extracted from this document must include Simplified BSD License text 78 as described in Section 4.e of the Trust Legal Provisions and are 79 provided without warranty as described in the Simplified BSD License. 81 Table of Contents 83 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 84 1.1. Relation to other RFCs . . . . . . . . . . . . . . . . . 4 85 1.2. Specification Language . . . . . . . . . . . . . . . . . 6 86 1.3. Adherence to the NMDA . . . . . . . . . . . . . . . . . . 6 87 2. The "ietf-tls-common" Module . . . . . . . . . . . . . . . . 6 88 2.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 7 89 2.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 10 90 2.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 10 91 3. The "ietf-tls-client" Module . . . . . . . . . . . . . . . . 19 92 3.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 19 93 3.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 21 94 3.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 24 95 4. The "ietf-tls-server" Module . . . . . . . . . . . . . . . . 32 96 4.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 32 97 4.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 35 98 4.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 39 99 5. Security Considerations . . . . . . . . . . . . . . . . . . . 46 100 5.1. The "ietf-tls-common" YANG Module . . . . . . . . . . . . 46 101 5.2. The "ietf-tls-client" YANG Module . . . . . . . . . . . . 47 102 5.3. The "ietf-tls-server" YANG Module . . . . . . . . . . . . 48 103 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 48 104 6.1. The "IETF XML" Registry . . . . . . . . . . . . . . . . . 48 105 6.2. The "YANG Module Names" Registry . . . . . . . . . . . . 49 106 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 49 107 7.1. Normative References . . . . . . . . . . . . . . . . . . 49 108 7.2. Informative References . . . . . . . . . . . . . . . . . 51 109 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 53 110 A.1. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 53 111 A.2. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 53 112 A.3. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 53 113 A.4. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 53 114 A.5. 04 to 05 . . . . . . . . . . . . . . . . . . . . . . . . 54 115 A.6. 05 to 06 . . . . . . . . . . . . . . . . . . . . . . . . 54 116 A.7. 06 to 07 . . . . . . . . . . . . . . . . . . . . . . . . 54 117 A.8. 07 to 08 . . . . . . . . . . . . . . . . . . . . . . . . 54 118 A.9. 08 to 09 . . . . . . . . . . . . . . . . . . . . . . . . 54 119 A.10. 09 to 10 . . . . . . . . . . . . . . . . . . . . . . . . 55 120 A.11. 10 to 11 . . . . . . . . . . . . . . . . . . . . . . . . 55 121 A.12. 11 to 12 . . . . . . . . . . . . . . . . . . . . . . . . 55 122 A.13. 12 to 13 . . . . . . . . . . . . . . . . . . . . . . . . 55 123 A.14. 12 to 13 . . . . . . . . . . . . . . . . . . . . . . . . 56 124 A.15. 13 to 14 . . . . . . . . . . . . . . . . . . . . . . . . 56 125 A.16. 14 to 15 . . . . . . . . . . . . . . . . . . . . . . . . 56 126 A.17. 15 to 16 . . . . . . . . . . . . . . . . . . . . . . . . 56 127 A.18. 16 to 17 . . . . . . . . . . . . . . . . . . . . . . . . 56 128 A.19. 17 to 18 . . . . . . . . . . . . . . . . . . . . . . . . 57 129 A.20. 18 to 19 . . . . . . . . . . . . . . . . . . . . . . . . 57 130 A.21. 19 to 20 . . . . . . . . . . . . . . . . . . . . . . . . 57 131 A.22. 20 to 21 . . . . . . . . . . . . . . . . . . . . . . . . 58 132 A.23. 21 to 22 . . . . . . . . . . . . . . . . . . . . . . . . 58 133 A.24. 22 to 23 . . . . . . . . . . . . . . . . . . . . . . . . 58 134 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 58 135 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 59 137 1. Introduction 139 This document defines three YANG 1.1 [RFC7950] modules: the first 140 defines a grouping for a generic TLS client, the second defines a 141 grouping for a generic TLS server, and the third defines identities 142 and groupings common to both the client and the server (TLS is 143 defined in [RFC5246]). It is intended that these groupings will be 144 used by applications using the TLS protocol. For instance, these 145 groupings could be used to help define the data model for an HTTPS 146 [RFC2818] server or a NETCONF over TLS [RFC7589] based server. 148 The client and server YANG modules in this document each define one 149 grouping, which is focused on just TLS-specific configuration, and 150 specifically avoids any transport-level configuration, such as what 151 ports to listen-on or connect-to. This affords applications the 152 opportunity to define their own strategy for how the underlying TCP 153 connection is established. For instance, applications supporting 154 NETCONF Call Home [RFC8071] could use the "ssh-server-grouping" 155 grouping for the TLS parts it provides, while adding data nodes for 156 the TCP-level call-home configuration. 158 1.1. Relation to other RFCs 160 This document presents one or more YANG modules [RFC7950] that are 161 part of a collection of RFCs that work together to, ultimately, 162 enable the configuration of the clients and servers of both the 163 NETCONF [RFC6241] and RESTCONF [RFC8040] protocols. 165 The modules have been defined in a modular fashion to enable their 166 use by other efforts, some of which are known to be in progress at 167 the time of this writing, with many more expected to be defined in 168 time. 170 The normative dependency relationship between the various RFCs in the 171 collection is presented in the below diagram. The labels in the 172 diagram represent the primary purpose provided by each RFC. 173 Hyperlinks to each RFC are provided below the diagram. 175 crypto-types 176 ^ ^ 177 / \ 178 / \ 179 truststore keystore 180 ^ ^ ^ ^ 181 | +---------+ | | 182 | | | | 183 | +------------+ | 184 tcp-client-server | / | | 185 ^ ^ ssh-client-server | | 186 | | ^ tls-client-server 187 | | | ^ ^ http-client-server 188 | | | | | ^ 189 | | | +-----+ +---------+ | 190 | | | | | | 191 | +-----------|--------|--------------+ | | 192 | | | | | | 193 +-----------+ | | | | | 194 | | | | | | 195 | | | | | | 196 netconf-client-server restconf-client-server 198 +=======================+===========================================+ 199 |Label in Diagram | Originating RFC | 200 +=======================+===========================================+ 201 |crypto-types | [I-D.ietf-netconf-crypto-types] | 202 +-----------------------+-------------------------------------------+ 203 |truststore | [I-D.ietf-netconf-trust-anchors] | 204 +-----------------------+-------------------------------------------+ 205 |keystore | [I-D.ietf-netconf-keystore] | 206 +-----------------------+-------------------------------------------+ 207 |tcp-client-server | [I-D.ietf-netconf-tcp-client-server] | 208 +-----------------------+-------------------------------------------+ 209 |ssh-client-server | [I-D.ietf-netconf-ssh-client-server] | 210 +-----------------------+-------------------------------------------+ 211 |tls-client-server | [I-D.ietf-netconf-tls-client-server] | 212 +-----------------------+-------------------------------------------+ 213 |http-client-server | [I-D.ietf-netconf-http-client-server] | 214 +-----------------------+-------------------------------------------+ 215 |netconf-client-server | [I-D.ietf-netconf-netconf-client-server] | 216 +-----------------------+-------------------------------------------+ 217 |restconf-client-server | [I-D.ietf-netconf-restconf-client-server] | 218 +-----------------------+-------------------------------------------+ 220 Table 1: Label to RFC Mapping 222 1.2. Specification Language 224 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 225 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 226 "OPTIONAL" in this document are to be interpreted as described in BCP 227 14 [RFC2119] [RFC8174] when, and only when, they appear in all 228 capitals, as shown here. 230 1.3. Adherence to the NMDA 232 This document in compliant with the Network Management Datastore 233 Architecture (NMDA) [RFC8342]. For instance, as described in 234 [I-D.ietf-netconf-trust-anchors] and [I-D.ietf-netconf-keystore], 235 trust anchors and keys installed during manufacturing are expected to 236 appear in . 238 2. The "ietf-tls-common" Module 240 The TLS common model presented in this section contains identities 241 and groupings common to both TLS clients and TLS servers. The 242 "hello-params-grouping" grouping can be used to configure the list of 243 TLS algorithms permitted by the TLS client or TLS server. The lists 244 of algorithms are ordered such that, if multiple algorithms are 245 permitted by the client, the algorithm that appears first in its list 246 that is also permitted by the server is used for the TLS transport 247 layer connection. The ability to restrict the algorithms allowed is 248 provided in this grouping for TLS clients and TLS servers that are 249 capable of doing so and may serve to make TLS clients and TLS servers 250 compliant with local security policies. This model supports both 251 TLS1.2 [RFC5246] and TLS 1.3 [RFC8446]. 253 TLS 1.2 and TLS 1.3 have different ways defining their own supported 254 cryptographic algorithms, see TLS and DTLS IANA registries page 255 (https://www.iana.org/assignments/tls-parameters/tls- 256 parameters.xhtml): 258 * TLS 1.2 defines four categories of registries for cryptographic 259 algorithms: TLS Cipher Suites, TLS SignatureAlgorithm, TLS 260 HashAlgorithm, TLS Supported Groups. TLS Cipher Suites plays the 261 role of combining all of them into one set, as each value of the 262 set represents a unique and feasible combination of all the 263 cryptographic algorithms, and thus the other three registry 264 categories do not need to be considered here. In this document, 265 the TLS common model only chooses those TLS1.2 algorithms in TLS 266 Cipher Suites which are marked as recommended: 267 TLS_DHE_RSA_WITH_AES_128_GCM_SHA256, 268 TLS_DHE_RSA_WITH_AES_256_GCM_SHA384, 269 TLS_DHE_PSK_WITH_AES_128_GCM_SHA256, 270 TLS_DHE_PSK_WITH_AES_256_GCM_SHA384, and so on. All chosen 271 algorithms are enumerated in Table 1-1 below; 273 * TLS 1.3 defines its supported algorithms differently. Firstly, it 274 defines three categories of registries for cryptographic 275 algorithms: TLS Cipher Suites, TLS SignatureScheme, TLS Supported 276 Groups. Secondly, all three of these categories are useful, since 277 they represent different parts of all the supported algorithms 278 respectively. Thus, all of these registries categories are 279 considered here. In this draft, the TLS common model chooses only 280 those TLS1.3 algorithms specified in B.4, 4.2.3, 4.2.7 of 281 [RFC8446]. 283 Thus, in order to support both TLS1.2 and TLS1.3, the cipher-suites 284 part of the "hello-params-grouping" grouping should include three 285 parameters for configuring its permitted TLS algorithms, which are: 286 TLS Cipher Suites, TLS SignatureScheme, TLS Supported Groups. Note 287 that TLS1.2 only uses TLS Cipher Suites. 289 Features are defined for algorithms that are OPTIONAL or are not 290 widely supported by popular implementations. Note that the list of 291 algorithms is not exhaustive. 293 2.1. Data Model Overview 295 This section provides an overview of the "ietf-tls-common" module in 296 terms of its features, identitiesm and groupings. 298 2.1.1. Features 300 The following diagram lists all the "feature" statements defined in 301 the "ietf-tls-common" module: 303 Features: 304 +-- tls-1_0 305 +-- tls-1_1 306 +-- tls-1_2 307 +-- tls-1_3 308 +-- tls-ecc 309 +-- tls-dhe 310 +-- tls-3des 311 +-- tls-gcm 312 +-- tls-sha2 314 | The diagram above uses syntax that is similar to but not 315 | defined in [RFC8340]. 317 2.1.2. Identities 319 The following diagram illustrates the relationship amongst the 320 "identity" statements defined in the "ietf-tls-common" module: 322 Identities: 323 +-- tls-version-base 324 | +-- tls-1.0 325 | +-- tls-1.1 326 | +-- tls-1.2 327 +-- cipher-suite-base 328 +-- rsa-with-aes-128-cbc-sha 329 +-- rsa-with-aes-256-cbc-sha 330 +-- rsa-with-aes-128-cbc-sha256 331 +-- rsa-with-aes-256-cbc-sha256 332 +-- dhe-rsa-with-aes-128-cbc-sha 333 +-- dhe-rsa-with-aes-256-cbc-sha 334 +-- dhe-rsa-with-aes-128-cbc-sha256 335 +-- dhe-rsa-with-aes-256-cbc-sha256 336 +-- ecdhe-ecdsa-with-aes-128-cbc-sha256 337 +-- ecdhe-ecdsa-with-aes-256-cbc-sha384 338 +-- ecdhe-rsa-with-aes-128-cbc-sha256 339 +-- ecdhe-rsa-with-aes-256-cbc-sha384 340 +-- ecdhe-ecdsa-with-aes-128-gcm-sha256 341 +-- ecdhe-ecdsa-with-aes-256-gcm-sha384 342 +-- ecdhe-rsa-with-aes-128-gcm-sha256 343 +-- ecdhe-rsa-with-aes-256-gcm-sha384 344 +-- rsa-with-3des-ede-cbc-sha 345 +-- ecdhe-rsa-with-3des-ede-cbc-sha 346 +-- ecdhe-rsa-with-aes-128-cbc-sha 347 +-- ecdhe-rsa-with-aes-256-cbc-sha 349 | The diagram above uses syntax that is similar to but not 350 | defined in [RFC8340]. 352 Comments: 354 * The diagram shows that there are two base identities. 355 * One base identity is used to specific TLS versions, while the 356 other is used to specify cipher-suites. 357 * These base identities are "abstract", in the object orientied 358 programming sense, in that they only define a "class" of things, 359 rather than a specific thing. 361 2.1.3. Groupings 363 The "ietf-tls-common" module defines the following "grouping" 364 statement: 366 * hello-params-grouping 368 This grouping is presented in the following subsection. 370 2.1.3.1. The "hello-params-grouping" Grouping 372 The following tree diagram [RFC8340] illustrates the "hello-params- 373 grouping" grouping: 375 grouping hello-params-grouping 376 +-- tls-versions 377 | +-- tls-version* identityref 378 +-- cipher-suites 379 +-- cipher-suite* identityref 381 Comments: 383 * This grouping is used by both the "tls-client-grouping" and the 384 "tls-server-grouping" groupings defined in Section 3.1.2.1 and 385 Section 4.1.2.1, respectively. 387 * This grouping enables client and server configurations to specify 388 the TLS versions and cipher suites that are to be used when 389 establishing TLS sessions. 391 * The "cipher-suites" list is "ordered-by user". 393 2.1.4. Protocol-accessible Nodes 395 The "ietf-tls-common" module does not contain any protocol-accessible 396 nodes, but the module needs to be "implemented", as described in 397 Section 5.6.5 of [RFC7950], in order for the identities in 398 Section 2.1.2 to be defined. 400 2.2. Example Usage 402 This section shows how it would appear if the "hello-params-grouping" 403 grouping were populated with some data. 405 408 409 tlscmn:tls-1.1 410 tlscmn:tls-1.2 411 412 413 tlscmn:dhe-rsa-with-aes-128-cbc-sha 414 tlscmn:rsa-with-aes-128-cbc-sha 415 tlscmn:rsa-with-3des-ede-cbc-sha 416 417 419 2.3. YANG Module 421 This YANG module has a normative references to [RFC4346], [RFC5246], 422 [RFC5288], [RFC5289], and [RFC8422]. 424 This YANG module has a informative references to [RFC2246], 425 [RFC4346], [RFC5246], and [RFC8446]. 427 file "ietf-tls-common@2021-02-10.yang" 429 module ietf-tls-common { 430 yang-version 1.1; 431 namespace "urn:ietf:params:xml:ns:yang:ietf-tls-common"; 432 prefix tlscmn; 434 organization 435 "IETF NETCONF (Network Configuration) Working Group"; 437 contact 438 "WG Web: 439 WG List: 440 Author: Kent Watsen 441 Author: Gary Wu "; 443 description 444 "This module defines a common features, identities, and 445 groupings for Transport Layer Security (TLS). 447 Copyright (c) 2020 IETF Trust and the persons identified 448 as authors of the code. All rights reserved. 450 Redistribution and use in source and binary forms, with 451 or without modification, is permitted pursuant to, and 452 subject to the license terms contained in, the Simplified 453 BSD License set forth in Section 4.c of the IETF Trust's 454 Legal Provisions Relating to IETF Documents 455 (https://trustee.ietf.org/license-info). 457 This version of this YANG module is part of RFC FFFF 458 (https://www.rfc-editor.org/info/rfcFFFF); see the RFC 459 itself for full legal notices. 461 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 462 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 463 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 464 are to be interpreted as described in BCP 14 (RFC 2119) 465 (RFC 8174) when, and only when, they appear in all 466 capitals, as shown here."; 468 revision 2021-02-10 { 469 description 470 "Initial version"; 471 reference 472 "RFC FFFF: YANG Groupings for TLS Clients and TLS Servers"; 473 } 475 // Features 477 feature tls-1_0 { 478 description 479 "TLS Protocol Version 1.0 is supported."; 480 reference 481 "RFC 2246: The TLS Protocol Version 1.0"; 482 } 484 feature tls-1_1 { 485 description 486 "TLS Protocol Version 1.1 is supported."; 487 reference 488 "RFC 4346: The Transport Layer Security (TLS) Protocol 489 Version 1.1"; 490 } 492 feature tls-1_2 { 493 description 494 "TLS Protocol Version 1.2 is supported."; 495 reference 496 "RFC 5246: The Transport Layer Security (TLS) Protocol 497 Version 1.2"; 498 } 500 feature tls-1_3 { 501 description 502 "TLS Protocol Version 1.2 is supported."; 503 reference 504 "RFC 8446: The Transport Layer Security (TLS) Protocol 505 Version 1.3"; 506 } 508 feature tls-ecc { 509 description 510 "Elliptic Curve Cryptography (ECC) is supported for TLS."; 511 reference 512 "RFC 8422: Elliptic Curve Cryptography (ECC) Cipher Suites 513 for Transport Layer Security (TLS)"; 514 } 516 feature tls-dhe { 517 description 518 "Ephemeral Diffie-Hellman key exchange is supported for TLS."; 519 reference 520 "RFC 5246: The Transport Layer Security (TLS) Protocol 521 Version 1.2"; 522 } 524 feature tls-3des { 525 description 526 "The Triple-DES block cipher is supported for TLS."; 527 reference 528 "RFC 5246: The Transport Layer Security (TLS) Protocol 529 Version 1.2"; 530 } 532 feature tls-gcm { 533 description 534 "The Galois/Counter Mode authenticated encryption mode is 535 supported for TLS."; 536 reference 537 "RFC 5288: AES Galois Counter Mode (GCM) Cipher Suites for 538 TLS"; 539 } 541 feature tls-sha2 { 542 description 543 "The SHA2 family of cryptographic hash functions is supported 544 for TLS."; 545 reference 546 "FIPS PUB 180-4: Secure Hash Standard (SHS)"; 547 } 549 // Identities 551 identity tls-version-base { 552 description 553 "Base identity used to identify TLS protocol versions."; 554 } 556 identity tls-1.0 { 557 if-feature "tls-1_0"; 558 base tls-version-base; 559 description 560 "TLS Protocol Version 1.0."; 561 reference 562 "RFC 2246: The TLS Protocol Version 1.0"; 563 } 565 identity tls-1.1 { 566 if-feature "tls-1_1"; 567 base tls-version-base; 568 description 569 "TLS Protocol Version 1.1."; 570 reference 571 "RFC 4346: The Transport Layer Security (TLS) Protocol 572 Version 1.1"; 573 } 575 identity tls-1.2 { 576 if-feature "tls-1_2"; 577 base tls-version-base; 578 description 579 "TLS Protocol Version 1.2."; 580 reference 581 "RFC 5246: The Transport Layer Security (TLS) Protocol 582 Version 1.2"; 583 } 585 identity cipher-suite-base { 586 description 587 "Base identity used to identify TLS cipher suites."; 588 } 590 identity rsa-with-aes-128-cbc-sha { 591 base cipher-suite-base; 592 description 593 "Cipher suite TLS_RSA_WITH_AES_128_CBC_SHA."; 594 reference 595 "RFC 5246: The Transport Layer Security (TLS) Protocol 596 Version 1.2"; 597 } 599 identity rsa-with-aes-256-cbc-sha { 600 base cipher-suite-base; 601 description 602 "Cipher suite TLS_RSA_WITH_AES_256_CBC_SHA."; 603 reference 604 "RFC 5246: The Transport Layer Security (TLS) Protocol 605 Version 1.2"; 606 } 608 identity rsa-with-aes-128-cbc-sha256 { 609 if-feature "tls-sha2"; 610 base cipher-suite-base; 611 description 612 "Cipher suite TLS_RSA_WITH_AES_128_CBC_SHA256."; 613 reference 614 "RFC 5246: The Transport Layer Security (TLS) Protocol 615 Version 1.2"; 616 } 618 identity rsa-with-aes-256-cbc-sha256 { 619 if-feature "tls-sha2"; 620 base cipher-suite-base; 621 description 622 "Cipher suite TLS_RSA_WITH_AES_256_CBC_SHA256."; 623 reference 624 "RFC 5246: The Transport Layer Security (TLS) Protocol 625 Version 1.2"; 626 } 628 identity dhe-rsa-with-aes-128-cbc-sha { 629 if-feature "tls-dhe"; 630 base cipher-suite-base; 631 description 632 "Cipher suite TLS_DHE_RSA_WITH_AES_128_CBC_SHA."; 633 reference 634 "RFC 5246: The Transport Layer Security (TLS) Protocol 635 Version 1.2"; 636 } 638 identity dhe-rsa-with-aes-256-cbc-sha { 639 if-feature "tls-dhe"; 640 base cipher-suite-base; 641 description 642 "Cipher suite TLS_DHE_RSA_WITH_AES_256_CBC_SHA."; 643 reference 644 "RFC 5246: The Transport Layer Security (TLS) Protocol 645 Version 1.2"; 646 } 648 identity dhe-rsa-with-aes-128-cbc-sha256 { 649 if-feature "tls-dhe and tls-sha2"; 650 base cipher-suite-base; 651 description 652 "Cipher suite TLS_DHE_RSA_WITH_AES_128_CBC_SHA256."; 653 reference 654 "RFC 5246: The Transport Layer Security (TLS) Protocol 655 Version 1.2"; 656 } 658 identity dhe-rsa-with-aes-256-cbc-sha256 { 659 if-feature "tls-dhe and tls-sha2"; 660 base cipher-suite-base; 661 description 662 "Cipher suite TLS_DHE_RSA_WITH_AES_256_CBC_SHA256."; 663 reference 664 "RFC 5246: The Transport Layer Security (TLS) Protocol 665 Version 1.2"; 666 } 668 identity ecdhe-ecdsa-with-aes-128-cbc-sha256 { 669 if-feature "tls-ecc and tls-sha2"; 670 base cipher-suite-base; 671 description 672 "Cipher suite TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256."; 673 reference 674 "RFC 5289: TLS Elliptic Curve Cipher Suites with 675 SHA-256/384 and AES Galois Counter Mode (GCM)"; 676 } 678 identity ecdhe-ecdsa-with-aes-256-cbc-sha384 { 679 if-feature "tls-ecc and tls-sha2"; 680 base cipher-suite-base; 681 description 682 "Cipher suite TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384."; 683 reference 684 "RFC 5289: TLS Elliptic Curve Cipher Suites with 685 SHA-256/384 and AES Galois Counter Mode (GCM)"; 686 } 687 identity ecdhe-rsa-with-aes-128-cbc-sha256 { 688 if-feature "tls-ecc and tls-sha2"; 689 base cipher-suite-base; 690 description 691 "Cipher suite TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256."; 692 reference 693 "RFC 5289: TLS Elliptic Curve Cipher Suites with 694 SHA-256/384 and AES Galois Counter Mode (GCM)"; 695 } 697 identity ecdhe-rsa-with-aes-256-cbc-sha384 { 698 if-feature "tls-ecc and tls-sha2"; 699 base cipher-suite-base; 700 description 701 "Cipher suite TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384."; 702 reference 703 "RFC 5289: TLS Elliptic Curve Cipher Suites with 704 SHA-256/384 and AES Galois Counter Mode (GCM)"; 705 } 707 identity ecdhe-ecdsa-with-aes-128-gcm-sha256 { 708 if-feature "tls-ecc and tls-gcm and tls-sha2"; 709 base cipher-suite-base; 710 description 711 "Cipher suite TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256."; 712 reference 713 "RFC 5289: TLS Elliptic Curve Cipher Suites with 714 SHA-256/384 and AES Galois Counter Mode (GCM)"; 715 } 717 identity ecdhe-ecdsa-with-aes-256-gcm-sha384 { 718 if-feature "tls-ecc and tls-gcm and tls-sha2"; 719 base cipher-suite-base; 720 description 721 "Cipher suite TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384."; 722 reference 723 "RFC 5289: TLS Elliptic Curve Cipher Suites with 724 SHA-256/384 and AES Galois Counter Mode (GCM)"; 725 } 727 identity ecdhe-rsa-with-aes-128-gcm-sha256 { 728 if-feature "tls-ecc and tls-gcm and tls-sha2"; 729 base cipher-suite-base; 730 description 731 "Cipher suite TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256."; 732 reference 733 "RFC 5289: TLS Elliptic Curve Cipher Suites with 734 SHA-256/384 and AES Galois Counter Mode (GCM)"; 736 } 738 identity ecdhe-rsa-with-aes-256-gcm-sha384 { 739 if-feature "tls-ecc and tls-gcm and tls-sha2"; 740 base cipher-suite-base; 741 description 742 "Cipher suite TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384."; 743 reference 744 "RFC 5289: TLS Elliptic Curve Cipher Suites with 745 SHA-256/384 and AES Galois Counter Mode (GCM)"; 746 } 748 identity rsa-with-3des-ede-cbc-sha { 749 if-feature "tls-3des"; 750 base cipher-suite-base; 751 description 752 "Cipher suite TLS_RSA_WITH_3DES_EDE_CBC_SHA."; 753 reference 754 "RFC 5246: The Transport Layer Security (TLS) Protocol 755 Version 1.2"; 756 } 758 identity ecdhe-rsa-with-3des-ede-cbc-sha { 759 if-feature "tls-ecc and tls-3des"; 760 base cipher-suite-base; 761 description 762 "Cipher suite TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA."; 763 reference 764 "RFC 8422: Elliptic Curve Cryptography (ECC) Cipher Suites 765 for Transport Layer Security (TLS)"; 766 } 768 identity ecdhe-rsa-with-aes-128-cbc-sha { 769 if-feature "tls-ecc"; 770 base cipher-suite-base; 771 description 772 "Cipher suite TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA."; 773 reference 774 "RFC 8422: Elliptic Curve Cryptography (ECC) Cipher Suites 775 for Transport Layer Security (TLS)"; 776 } 778 identity ecdhe-rsa-with-aes-256-cbc-sha { 779 if-feature "tls-ecc"; 780 base cipher-suite-base; 781 description 782 "Cipher suite TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA."; 783 reference 784 "RFC 8422: Elliptic Curve Cryptography (ECC) Cipher Suites 785 for Transport Layer Security (TLS)"; 786 } 788 // Groupings 790 grouping hello-params-grouping { 791 description 792 "A reusable grouping for TLS hello message parameters."; 793 reference 794 "RFC 5246: The Transport Layer Security (TLS) Protocol 795 Version 1.2"; 796 container tls-versions { 797 description 798 "Parameters regarding TLS versions."; 799 leaf-list tls-version { 800 type identityref { 801 base tls-version-base; 802 } 803 description 804 "Acceptable TLS protocol versions. 806 If this leaf-list is not configured (has zero elements) 807 the acceptable TLS protocol versions are implementation- 808 defined."; 809 } 810 } 811 container cipher-suites { 812 description 813 "Parameters regarding cipher suites."; 814 leaf-list cipher-suite { 815 type identityref { 816 base cipher-suite-base; 817 } 818 ordered-by user; 819 description 820 "Acceptable cipher suites in order of descending 821 preference. The configured host key algorithms should 822 be compatible with the algorithm used by the configured 823 private key. Please see Section 5 of RFC FFFF for 824 valid combinations. 826 If this leaf-list is not configured (has zero elements) 827 the acceptable cipher suites are implementation- 828 defined."; 829 reference 830 "RFC FFFF: YANG Groupings for TLS Clients and TLS Servers"; 831 } 833 } 834 } 835 } 837 839 3. The "ietf-tls-client" Module 841 This section defines a YANG 1.1 [RFC7950] module called "ietf-tls- 842 client". A high-level overview of the module is provided in 843 Section 3.1. Examples illustatrating the module's use are provided 844 in Examples (Section 3.2). The YANG module itself is defined in 845 Section 3.3. 847 3.1. Data Model Overview 849 This section provides an overview of the "ietf-tls-client" module in 850 terms of its features and groupings. 852 3.1.1. Features 854 The following diagram lists all the "feature" statements defined in 855 the "ietf-tls-client" module: 857 Features: 858 +-- tls-client-hello-params-config 859 +-- tls-client-keepalives 860 +-- x509-certificate-auth 861 +-- raw-public-key-auth 862 +-- psk-auth 864 | The diagram above uses syntax that is similar to but not 865 | defined in [RFC8340]. 867 3.1.2. Groupings 869 The "ietf-tls-client" module defines the following "grouping" 870 statement: 872 * tls-client-grouping 874 This grouping is presented in the following subsection. 876 3.1.2.1. The "tls-client-grouping" Grouping 878 The following tree diagram [RFC8340] illustrates the "tls-client- 879 grouping" grouping: 881 =============== NOTE: '\' line wrapping per RFC 8792 ================ 883 grouping tls-client-grouping 884 +-- client-identity! 885 | +-- (auth-type) 886 | +--:(certificate) {x509-certificate-auth}? 887 | | +-- certificate 888 | | +---u ks:local-or-keystore-end-entity-cert-with-key-\ 889 grouping 890 | +--:(raw-public-key) {raw-public-key-auth}? 891 | | +-- raw-private-key 892 | | +---u ks:local-or-keystore-asymmetric-key-grouping 893 | +--:(psk) {psk-auth}? 894 | +-- psk 895 | +---u ks:local-or-keystore-symmetric-key-grouping 896 | +-- id? 897 | string 898 +-- server-authentication 899 | +-- ca-certs! {x509-certificate-auth}? 900 | | +---u ts:local-or-truststore-certs-grouping 901 | +-- ee-certs! {x509-certificate-auth}? 902 | | +---u ts:local-or-truststore-certs-grouping 903 | +-- raw-public-keys! {raw-public-key-auth}? 904 | | +---u ts:local-or-truststore-public-keys-grouping 905 | +-- psks? empty {psk-auth}? 906 +-- hello-params {tls-client-hello-params-config}? 907 | +---u tlscmn:hello-params-grouping 908 +-- keepalives {tls-client-keepalives}? 909 +-- peer-allowed-to-send? empty 910 +-- test-peer-aliveness! 911 +-- max-wait? uint16 912 +-- max-attempts? uint8 914 Comments: 916 * The "client-identity" node, which is optionally configured (as 917 client authentication MAY occur at a higher protocol layer), 918 configures identity credentials, each enabled by a "feature" 919 statement defined in Section 3.1.1. 921 * The "server-authentication" node configures trust anchors for 922 authenticating the TLS server, with each option enabled by a 923 "feature" statement. 925 * The "hello-params" node , which must be enabled by a feature, 926 configures parameters for the TLS sessions established by this 927 configuration. 929 * The "keepalives" node, which must be enabled by a feature, 930 configures a "presence" container for testing the aliveness of the 931 TLS server. The aliveness-test occurs at the TLS protocol layer. 933 * For the referenced grouping statement(s): 935 - The "local-or-keystore-end-entity-cert-with-key-grouping" 936 grouping is discussed in Section 2.1.3.6 of 937 [I-D.ietf-netconf-keystore]. 938 - The "local-or-keystore-asymmetric-key-grouping" grouping is 939 discussed in Section 2.1.3.4 of [I-D.ietf-netconf-keystore]. 940 - The "local-or-keystore-symmetric-key-grouping" grouping is 941 discussed in Section 2.1.3.3 of [I-D.ietf-netconf-keystore]. 942 - The "local-or-truststore-certs-grouping" grouping is discussed 943 in Section 2.1.3.1 of [I-D.ietf-netconf-trust-anchors]. 944 - The "local-or-truststore-public-keys-grouping" grouping is 945 discussed in Section 2.1.3.2 of 946 [I-D.ietf-netconf-trust-anchors]. 947 - The "hello-params-grouping" grouping is discussed in 948 Section 2.1.3.1 in this document. 950 3.1.3. Protocol-accessible Nodes 952 The "ietf-tls-client" module does not contain any protocol-accessible 953 nodes. 955 3.2. Example Usage 957 This section presents two examples showing the "tls-client-grouping" 958 grouping populated with some data. These examples are effectively 959 the same except the first configures the client identity using a 960 local key while the second uses a key configured in a keystore. Both 961 examples are consistent with the examples presented in Section 2 of 962 [I-D.ietf-netconf-trust-anchors] and Section 3.2 of 963 [I-D.ietf-netconf-keystore]. 965 The following configuration example uses local-definitions for the 966 client identity and server authentication: 968 =============== NOTE: '\' line wrapping per RFC 8792 ================ 970 974 975 976 977 978 ct:subject-public-key-info-format 980 base64encodedvalue== 981 ct:rsa-private-key-format 983 base64encodedvalue== 985 base64encodedvalue== 986 987 988 1007 1009 1010 1011 1012 1013 1014 Server Cert Issuer #1 1015 base64encodedvalue== 1016 1017 1018 Server Cert Issuer #2 1019 base64encodedvalue== 1020 1021 1022 1023 1024 1025 1026 My Application #1 1027 base64encodedvalue== 1028 1029 1030 My Application #2 1031 base64encodedvalue== 1032 1033 1034 1035 1036 1037 1038 corp-fw1 1039 ct:subject-public-key-info-format 1041 base64encodedvalue== 1042 1043 1044 corp-fw1 1045 ct:subject-public-key-info-format 1047 base64encodedvalue== 1048 1049 1050 1051 1052 1054 1055 1056 30 1057 3 1058 1059 1061 1063 The following configuration example uses keystore-references for the 1064 client identity and truststore-references for server authentication: 1065 from the keystore: 1067 =============== NOTE: '\' line wrapping per RFC 8792 ================ 1069 1071 1072 1073 1074 1075 rsa-asymmetric-key 1076 ex-rsa-cert 1077 1078 1079 1088 1090 1091 1092 1093 trusted-server-ca-certs 1095 1096 1097 trusted-server-ee-certs 1099 1100 1101 Raw Public Keys for TLS Servers 1103 1104 1105 1107 1108 1109 30 1110 3 1111 1112 1114 1116 3.3. YANG Module 1118 This YANG module has normative references to 1119 [I-D.ietf-netconf-trust-anchors] and [I-D.ietf-netconf-keystore]. 1121 file "ietf-tls-client@2021-02-10.yang" 1123 module ietf-tls-client { 1124 yang-version 1.1; 1125 namespace "urn:ietf:params:xml:ns:yang:ietf-tls-client"; 1126 prefix tlsc; 1128 import ietf-netconf-acm { 1129 prefix nacm; 1130 reference 1131 "RFC 8341: Network Configuration Access Control Model"; 1132 } 1134 import ietf-crypto-types { 1135 prefix ct; 1136 reference 1137 "RFC AAAA: YANG Data Types and Groupings for Cryptography"; 1138 } 1140 import ietf-truststore { 1141 prefix ts; 1142 reference 1143 "RFC BBBB: A YANG Data Model for a Truststore"; 1144 } 1146 import ietf-keystore { 1147 prefix ks; 1148 reference 1149 "RFC CCCC: A YANG Data Model for a Keystore"; 1150 } 1152 import ietf-tls-common { 1153 prefix tlscmn; 1154 revision-date 2021-02-10; // stable grouping definitions 1155 reference 1156 "RFC FFFF: YANG Groupings for TLS Clients and TLS Servers"; 1157 } 1159 organization 1160 "IETF NETCONF (Network Configuration) Working Group"; 1162 contact 1163 "WG Web: 1164 WG List: 1165 Author: Kent Watsen 1166 Author: Gary Wu "; 1168 description 1169 "This module defines reusable groupings for TLS clients that 1170 can be used as a basis for specific TLS client instances. 1172 Copyright (c) 2020 IETF Trust and the persons identified 1173 as authors of the code. All rights reserved. 1175 Redistribution and use in source and binary forms, with 1176 or without modification, is permitted pursuant to, and 1177 subject to the license terms contained in, the Simplified 1178 BSD License set forth in Section 4.c of the IETF Trust's 1179 Legal Provisions Relating to IETF Documents 1180 (https://trustee.ietf.org/license-info). 1182 This version of this YANG module is part of RFC FFFF 1183 (https://www.rfc-editor.org/info/rfcFFFF); see the RFC 1184 itself for full legal notices. 1186 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1187 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 1188 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 1189 are to be interpreted as described in BCP 14 (RFC 2119) 1190 (RFC 8174) when, and only when, they appear in all 1191 capitals, as shown here."; 1193 revision 2021-02-10 { 1194 description 1195 "Initial version"; 1196 reference 1197 "RFC FFFF: YANG Groupings for TLS Clients and TLS Servers"; 1198 } 1200 // Features 1202 feature tls-client-hello-params-config { 1203 description 1204 "TLS hello message parameters are configurable on a TLS 1205 client."; 1206 } 1208 feature tls-client-keepalives { 1209 description 1210 "Per socket TLS keepalive parameters are configurable for 1211 TLS clients on the server implementing this feature."; 1212 } 1214 feature x509-certificate-auth { 1215 description 1216 "Indicates that the client supports authenticating servers 1217 using X.509 certificates."; 1218 } 1220 feature raw-public-key-auth { 1221 description 1222 "Indicates that the client supports authenticating servers 1223 using ray public keys."; 1224 } 1226 feature psk-auth { 1227 description 1228 "Indicates that the client supports authenticating servers 1229 using PSKs (pre-shared or pairwise-symmetric keys)."; 1230 } 1232 // Groupings 1234 grouping tls-client-grouping { 1235 description 1236 "A reusable grouping for configuring a TLS client without 1237 any consideration for how an underlying TCP session is 1238 established. 1240 Note that this grouping uses fairly typical descendent 1241 node names such that a stack of 'uses' statements will 1242 have name conflicts. It is intended that the consuming 1243 data model will resolve the issue (e.g., by wrapping 1244 the 'uses' statement in a container called 1245 'tls-client-parameters'). This model purposely does 1246 not do this itself so as to provide maximum flexibility 1247 to consuming models."; 1249 container client-identity { 1250 nacm:default-deny-write; 1251 presence 1252 "Indicates that TLS-level client authentication 1253 is sent. Present so that the 'choice' node's 1254 mandatory true doesn't imply that a client 1255 identity must be configured."; 1256 description 1257 "Identity credentials the TLS client MAY present when 1258 establishing a connection to a TLS server. If not 1259 configured, then client authentication is presumed to 1260 occur a protocol layer above TLS. When configured, 1261 and requested by the TLS server when establishing a 1262 TLS session, these credentials are passed in the 1263 Certificate message defined in Section 7.4.2 of 1264 RFC 5246."; 1265 reference 1266 "RFC 5246: The Transport Layer Security (TLS) Protocol 1267 Version 1.2 1268 RFC CCCC: A YANG Data Model for a Keystore"; 1269 choice auth-type { 1270 mandatory true; 1271 description 1272 "A choice amongst available authentication types."; 1273 case certificate { 1274 if-feature x509-certificate-auth; 1275 container certificate { 1276 description 1277 "Specifies the client identity using a certificate."; 1278 uses 1279 ks:local-or-keystore-end-entity-cert-with-key-grouping{ 1280 refine "local-or-keystore/local/local-definition" { 1281 must 'public-key-format' 1282 + ' = "ct:subject-public-key-info-format"'; 1283 } 1284 refine "local-or-keystore/keystore/keystore-reference" 1285 + "/asymmetric-key" { 1286 must 'deref(.)/../ks:public-key-format' 1287 + ' = "ct:subject-public-key-info-format"'; 1288 } 1289 } 1290 } 1291 } 1292 case raw-public-key { 1293 if-feature raw-public-key-auth; 1294 container raw-private-key { 1295 description 1296 "Specifies the client identity using a raw 1297 private key."; 1298 uses ks:local-or-keystore-asymmetric-key-grouping { 1299 refine "local-or-keystore/local/local-definition" { 1300 must 'public-key-format' 1301 + ' = "ct:subject-public-key-info-format"'; 1302 } 1303 refine "local-or-keystore/keystore" 1304 + "/keystore-reference" { 1305 must 'deref(.)/../ks:public-key-format' 1306 + ' = "ct:subject-public-key-info-format"'; 1307 } 1308 } 1309 } 1310 } 1311 case psk { 1312 if-feature psk-auth; 1313 container psk { 1314 description 1315 "Specifies the client identity using a PSK (pre-shared 1316 or pairwise-symmetric key)."; 1317 uses ks:local-or-keystore-symmetric-key-grouping; 1318 leaf id { 1319 type string; 1320 description 1321 "The key 'psk_identity' value used in the TLS 1322 'ClientKeyExchange' message."; 1323 reference 1324 "RFC 4279: Pre-Shared Key Ciphersuites for 1325 Transport Layer Security (TLS)"; 1326 } 1327 } 1328 } 1329 } 1330 } // container client-identity 1332 container server-authentication { 1333 nacm:default-deny-write; 1334 must 'ca-certs or ee-certs or raw-public-keys or psks'; 1335 description 1336 "Specifies how the TLS client can authenticate TLS servers. 1337 Any combination of credentials is additive and unordered. 1339 Note that no configuration is required for PSK (pre-shared 1340 or pairwise-symmetric key) based authentication as the key 1341 is necessarily the same as configured in the '../client- 1342 identity' node."; 1343 container ca-certs { 1344 if-feature "x509-certificate-auth"; 1345 presence 1346 "Indicates that the TLS client can authenticate TLS servers 1347 using configured certificate authority certificates."; 1348 description 1349 "A set of certificate authority (CA) certificates used by 1350 the TLS client to authenticate TLS server certificates. 1351 A server certificate is authenticated if it has a valid 1352 chain of trust to a configured CA certificate."; 1353 reference 1354 "RFC BBBB: A YANG Data Model for a Truststore"; 1355 uses ts:local-or-truststore-certs-grouping; 1356 } 1357 container ee-certs { 1358 if-feature "x509-certificate-auth"; 1359 presence 1360 "Indicates that the TLS client can authenticate TLS 1361 servers using configured server certificates."; 1362 description 1363 "A set of server certificates (i.e., end entity 1364 certificates) used by the TLS client to authenticate 1365 certificates presented by TLS servers. A server 1366 certificate is authenticated if it is an exact 1367 match to a configured server certificate."; 1368 reference 1369 "RFC BBBB: A YANG Data Model for a Truststore"; 1370 uses ts:local-or-truststore-certs-grouping; 1371 } 1372 container raw-public-keys { 1373 if-feature "raw-public-key-auth"; 1374 presence 1375 "Indicates that the TLS client can authenticate TLS 1376 servers using configured server certificates."; 1377 description 1378 "A set of raw public keys used by the TLS client to 1379 authenticate raw public keys presented by the TLS 1380 server. A raw public key is authenticated if it 1381 is an exact match to a configured raw public key."; 1382 reference 1383 "RFC BBBB: A YANG Data Model for a Truststore"; 1384 uses ts:local-or-truststore-public-keys-grouping { 1385 refine "local-or-truststore/local/local-definition" 1386 + "/public-key" { 1387 must 'public-key-format' 1388 + ' = "ct:subject-public-key-info-format"'; 1389 } 1390 refine "local-or-truststore/truststore" 1391 + "/truststore-reference" { 1392 must 'deref(.)/../*/ts:public-key-format' 1393 + ' = "ct:subject-public-key-info-format"'; 1394 } 1395 } 1396 } 1397 leaf psks { 1398 if-feature "psk-auth"; 1399 type empty; 1400 description 1401 "Indicates that the TLS client can authenticate TLS servers 1402 using configure PSKs (pre-shared or pairwise-symmetric 1403 keys). 1405 No configuration is required since the PSK value is the 1406 same as PSK value configured in the 'client-identity' 1407 node."; 1408 } 1409 } // container server-authentication 1411 container hello-params { 1412 nacm:default-deny-write; 1413 if-feature "tls-client-hello-params-config"; 1414 uses tlscmn:hello-params-grouping; 1415 description 1416 "Configurable parameters for the TLS hello message."; 1417 } // container hello-params 1419 container keepalives { 1420 nacm:default-deny-write; 1421 if-feature "tls-client-keepalives"; 1422 description 1423 "Configures the keepalive policy for the TLS client."; 1424 leaf peer-allowed-to-send { 1425 type empty; 1426 description 1427 "Indicates that the remote TLS server is allowed to send 1428 HeartbeatRequest messages, as defined by RFC 6520 1429 to this TLS client."; 1430 reference 1431 "RFC 6520: Transport Layer Security (TLS) and Datagram 1432 Transport Layer Security (DTLS) Heartbeat Extension"; 1433 } 1434 container test-peer-aliveness { 1435 presence 1436 "Indicates that the TLS client proactively tests the 1437 aliveness of the remote TLS server."; 1438 description 1439 "Configures the keep-alive policy to proactively test 1440 the aliveness of the TLS server. An unresponsive 1441 TLS server is dropped after approximately max-wait 1442 * max-attempts seconds. The TLS client MUST send 1443 HeartbeatRequest messages, as defined by RFC 6520."; 1444 reference 1445 "RFC 6520: Transport Layer Security (TLS) and Datagram 1446 Transport Layer Security (DTLS) Heartbeat Extension"; 1447 leaf max-wait { 1448 type uint16 { 1449 range "1..max"; 1450 } 1451 units "seconds"; 1452 default "30"; 1453 description 1454 "Sets the amount of time in seconds after which if 1455 no data has been received from the TLS server, a 1456 TLS-level message will be sent to test the 1457 aliveness of the TLS server."; 1458 } 1459 leaf max-attempts { 1460 type uint8; 1461 default "3"; 1462 description 1463 "Sets the maximum number of sequential keep-alive 1464 messages that can fail to obtain a response from 1465 the TLS server before assuming the TLS server is 1466 no longer alive."; 1467 } 1468 } 1469 } 1470 } // grouping tls-client-grouping 1471 } // module ietf-tls-client 1473 1475 4. The "ietf-tls-server" Module 1477 This section defines a YANG 1.1 [RFC7950] module called "ietf-tls- 1478 server". A high-level overview of the module is provided in 1479 Section 4.1. Examples illustatrating the module's use are provided 1480 in Examples (Section 4.2). The YANG module itself is defined in 1481 Section 4.3. 1483 4.1. Data Model Overview 1485 This section provides an overview of the "ietf-tls-server" module in 1486 terms of its features and groupings. 1488 4.1.1. Features 1490 The following diagram lists all the "feature" statements defined in 1491 the "ietf-tls-server" module: 1493 Features: 1494 +-- tls-server-hello-params-config 1495 +-- tls-server-keepalives 1496 +-- client-auth-config-supported 1497 +-- x509-certificate-auth 1498 +-- raw-public-key-auth 1499 +-- psk-auth 1501 | The diagram above uses syntax that is similar to but not 1502 | defined in [RFC8340]. 1504 4.1.2. Groupings 1506 The "ietf-tls-server" module defines the following "grouping" 1507 statement: 1509 * tls-server-grouping 1511 This grouping is presented in the following subsection. 1513 4.1.2.1. The "tls-server-grouping" Grouping 1515 The following tree diagram [RFC8340] illustrates the "tls-server- 1516 grouping" grouping: 1518 =============== NOTE: '\' line wrapping per RFC 8792 ================ 1520 grouping tls-server-grouping 1521 +-- server-identity 1522 | +-- (auth-type) 1523 | +--:(certificate) {x509-certificate-auth}? 1524 | | +-- certificate 1525 | | +---u ks:local-or-keystore-end-entity-cert-with-key-\ 1526 grouping 1527 | +--:(raw-private-key) {raw-public-key-auth}? 1528 | | +-- raw-private-key 1529 | | +---u ks:local-or-keystore-asymmetric-key-grouping 1530 | +--:(psk) {psk-auth}? 1531 | +-- psk 1532 | +---u ks:local-or-keystore-symmetric-key-grouping 1533 | +-- id_hint? 1534 | string 1535 +-- client-authentication! {client-auth-config-supported}? 1536 | +-- ca-certs! {x509-certificate-auth}? 1537 | | +---u ts:local-or-truststore-certs-grouping 1538 | +-- ee-certs! {x509-certificate-auth}? 1539 | | +---u ts:local-or-truststore-certs-grouping 1540 | +-- raw-public-keys! {raw-public-key-auth}? 1541 | | +---u ts:local-or-truststore-public-keys-grouping 1542 | +-- psks? empty {psk-auth}? 1543 +-- hello-params {tls-server-hello-params-config}? 1544 | +---u tlscmn:hello-params-grouping 1545 +-- keepalives {tls-server-keepalives}? 1546 +-- peer-allowed-to-send? empty 1547 +-- test-peer-aliveness! 1548 +-- max-wait? uint16 1549 +-- max-attempts? uint8 1551 Comments: 1553 * The "server-identity" node configures identity credentials, each 1554 of which is enabled by a "feature". 1556 * The "client-authentication" node, which is optionally configured 1557 (as client authentication MAY occur at a higher protocol layer), 1558 configures trust anchors for authenticating the TLS client, with 1559 each option enabled by a "feature" statement. 1561 * The "hello-params" node, which must be enabled by a feature, 1562 configures parameters for the TLS sessions established by this 1563 configuration. 1565 * The "keepalives" node, which must be enabled by a feature, 1566 configures a flag enabling the TLS client to test the aliveness of 1567 the TLS server, as well as a "presence" container for testing the 1568 aliveness of the TLSi client. The aliveness-tests occurs at the 1569 TLS protocol layer. 1571 * For the referenced grouping statement(s): 1573 - The "local-or-keystore-end-entity-cert-with-key-grouping" 1574 grouping is discussed in Section 2.1.3.6 of 1575 [I-D.ietf-netconf-keystore]. 1576 - The "local-or-keystore-asymmetric-key-grouping" grouping is 1577 discussed in Section 2.1.3.4 of [I-D.ietf-netconf-keystore]. 1578 - The "local-or-keystore-symmetric-key-grouping" grouping is 1579 discussed in Section 2.1.3.3 of [I-D.ietf-netconf-keystore]. 1580 - The "local-or-truststore-public-keys-grouping" grouping is 1581 discussed in Section 2.1.3.2 of 1582 [I-D.ietf-netconf-trust-anchors]. 1583 - The "local-or-truststore-certs-grouping" grouping is discussed 1584 in Section 2.1.3.1 of [I-D.ietf-netconf-trust-anchors]. 1585 - The "hello-params-grouping" grouping is discussed in 1586 Section 2.1.3.1 in this document. 1588 4.1.3. Protocol-accessible Nodes 1590 The "ietf-tls-server" module does not contain any protocol-accessible 1591 nodes. 1593 4.2. Example Usage 1595 This section presents two examples showing the "tls-server-grouping" 1596 grouping populated with some data. These examples are effectively 1597 the same except the first configures the server identity using a 1598 local key while the second uses a key configured in a keystore. Both 1599 examples are consistent with the examples presented in Section 2 of 1600 [I-D.ietf-netconf-trust-anchors] and Section 3.2 of 1601 [I-D.ietf-netconf-keystore]. 1603 The following configuration example uses local-definitions for the 1604 server identity and client authentication: 1606 =============== NOTE: '\' line wrapping per RFC 8792 ================ 1608 1612 1613 1614 1615 1616 ct:subject-public-key-info-format 1618 base64encodedvalue== 1619 ct:rsa-private-key-format 1621 base64encodedvalue== 1623 base64encodedvalue== 1624 1625 1626 1645 1647 1648 1649 1650 1651 1652 Identity Cert Issuer #1 1653 base64encodedvalue== 1654 1655 1656 Identity Cert Issuer #2 1657 base64encodedvalue== 1658 1659 1660 1661 1662 1663 1664 Application #1 1665 base64encodedvalue== 1666 1667 1668 Application #2 1669 base64encodedvalue== 1670 1671 1672 1673 1674 1675 1676 User A 1677 ct:subject-public-key-info-format 1679 base64encodedvalue== 1680 1681 1682 User B 1683 ct:subject-public-key-info-format 1685 base64encodedvalue== 1686 1687 1688 1689 1690 1692 1693 1694 1696 1698 The following configuration example uses keystore-references for the 1699 server identity and truststore-references for client authentication: 1700 from the keystore: 1702 =============== NOTE: '\' line wrapping per RFC 8792 ================ 1704 1706 1707 1708 1709 1710 rsa-asymmetric-key 1711 ex-rsa-cert 1712 1713 1714 1723 1725 1726 1727 1728 trusted-client-ca-certs 1730 1731 1732 trusted-client-ee-certs 1734 1735 1736 Raw Public Keys for TLS Clients 1738 1739 1740 1742 1743 1744 1746 1748 4.3. YANG Module 1750 This YANG module has a normative references to [RFC5246], 1751 [I-D.ietf-netconf-trust-anchors] and [I-D.ietf-netconf-keystore]. 1753 file "ietf-tls-server@2021-02-10.yang" 1755 module ietf-tls-server { 1756 yang-version 1.1; 1757 namespace "urn:ietf:params:xml:ns:yang:ietf-tls-server"; 1758 prefix tlss; 1760 import ietf-netconf-acm { 1761 prefix nacm; 1762 reference 1763 "RFC 8341: Network Configuration Access Control Model"; 1764 } 1766 import ietf-crypto-types { 1767 prefix ct; 1768 reference 1769 "RFC AAAA: YANG Data Types and Groupings for Cryptography"; 1770 } 1772 import ietf-truststore { 1773 prefix ts; 1774 reference 1775 "RFC BBBB: A YANG Data Model for a Truststore"; 1776 } 1778 import ietf-keystore { 1779 prefix ks; 1780 reference 1781 "RFC CCCC: A YANG Data Model for a Keystore"; 1782 } 1784 import ietf-tls-common { 1785 prefix tlscmn; 1786 revision-date 2021-02-10; // stable grouping definitions 1787 reference 1788 "RFC FFFF: YANG Groupings for TLS Clients and TLS Servers"; 1789 } 1791 organization 1792 "IETF NETCONF (Network Configuration) Working Group"; 1794 contact 1795 "WG Web: 1796 WG List: 1797 Author: Kent Watsen 1798 Author: Gary Wu "; 1800 description 1801 "This module defines reusable groupings for TLS servers that 1802 can be used as a basis for specific TLS server instances. 1804 Copyright (c) 2020 IETF Trust and the persons identified 1805 as authors of the code. All rights reserved. 1807 Redistribution and use in source and binary forms, with 1808 or without modification, is permitted pursuant to, and 1809 subject to the license terms contained in, the Simplified 1810 BSD License set forth in Section 4.c of the IETF Trust's 1811 Legal Provisions Relating to IETF Documents 1812 (https://trustee.ietf.org/license-info). 1814 This version of this YANG module is part of RFC FFFF 1815 (https://www.rfc-editor.org/info/rfcFFFF); see the RFC 1816 itself for full legal notices. 1818 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1819 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 1820 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 1821 are to be interpreted as described in BCP 14 (RFC 2119) 1822 (RFC 8174) when, and only when, they appear in all 1823 capitals, as shown here."; 1825 revision 2021-02-10 { 1826 description 1827 "Initial version"; 1828 reference 1829 "RFC FFFF: YANG Groupings for TLS Clients and TLS Servers"; 1830 } 1832 // Features 1834 feature tls-server-hello-params-config { 1835 description 1836 "TLS hello message parameters are configurable on a TLS 1837 server."; 1838 } 1840 feature tls-server-keepalives { 1841 description 1842 "Per socket TLS keepalive parameters are configurable for 1843 TLS servers on the server implementing this feature."; 1845 } 1847 feature client-auth-config-supported { 1848 description 1849 "Indicates that the configuration for how to authenticate 1850 clients can be configured herein, as opposed to in an 1851 application specific location. That is, to support the 1852 consuming data models that prefer to place client 1853 authentication with client definitions, rather then 1854 in a data model principally concerned with configuring 1855 the transport."; 1856 } 1858 feature x509-certificate-auth { 1859 description 1860 "Indicates that the server supports authenticating clients 1861 using X.509 certificates."; 1862 } 1864 feature raw-public-key-auth { 1865 description 1866 "Indicates that the server supports authenticating clients 1867 using ray public keys."; 1868 } 1870 feature psk-auth { 1871 description 1872 "Indicates that the server supports authenticating clients 1873 using PSKs (pre-shared or pairwise-symmetric keys)."; 1874 } 1876 // Groupings 1878 grouping tls-server-grouping { 1879 description 1880 "A reusable grouping for configuring a TLS server without 1881 any consideration for how underlying TCP sessions are 1882 established. 1884 Note that this grouping uses fairly typical descendent 1885 node names such that a stack of 'uses' statements will 1886 have name conflicts. It is intended that the consuming 1887 data model will resolve the issue (e.g., by wrapping 1888 the 'uses' statement in a container called 1889 'tls-server-parameters'). This model purposely does 1890 not do this itself so as to provide maximum flexibility 1891 to consuming models."; 1893 container server-identity { 1894 nacm:default-deny-write; 1895 description 1896 "A locally-defined or referenced end-entity certificate, 1897 including any configured intermediate certificates, the 1898 TLS server will present when establishing a TLS connection 1899 in its Certificate message, as defined in Section 7.4.2 1900 in RFC 5246."; 1901 reference 1902 "RFC 5246: The Transport Layer Security (TLS) Protocol 1903 Version 1.2 1904 RFC CCCC: A YANG Data Model for a Keystore"; 1905 choice auth-type { 1906 mandatory true; 1907 description 1908 "A choice amongst authentication types."; 1909 case certificate { 1910 if-feature x509-certificate-auth; 1911 container certificate { 1912 description 1913 "Specifies the server identity using a certificate."; 1914 uses 1915 ks:local-or-keystore-end-entity-cert-with-key-grouping{ 1916 refine "local-or-keystore/local/local-definition" { 1917 must 'public-key-format' 1918 + ' = "ct:subject-public-key-info-format"'; 1919 } 1920 refine "local-or-keystore/keystore/keystore-reference" 1921 + "/asymmetric-key" { 1922 must 'deref(.)/../ks:public-key-format' 1923 + ' = "ct:subject-public-key-info-format"'; 1924 } 1925 } 1926 } 1927 } 1928 case raw-private-key { 1929 if-feature raw-public-key-auth; 1930 container raw-private-key { 1931 description 1932 "Specifies the server identity using a raw 1933 private key."; 1934 uses ks:local-or-keystore-asymmetric-key-grouping { 1935 refine "local-or-keystore/local/local-definition" { 1936 must 'public-key-format' 1937 + ' = "ct:subject-public-key-info-format"'; 1939 } 1940 refine "local-or-keystore/keystore/keystore-reference"{ 1941 must 'deref(.)/../ks:public-key-format' 1942 + ' = "ct:subject-public-key-info-format"'; 1943 } 1944 } 1945 } 1946 } 1947 case psk { 1948 if-feature psk-auth; 1949 container psk { 1950 description 1951 "Specifies the server identity using a PSK (pre-shared 1952 or pairwise-symmetric key)."; 1953 uses ks:local-or-keystore-symmetric-key-grouping; 1954 leaf id_hint { 1955 type string; 1956 description 1957 "The key 'psk_identity_hint' value used in the TLS 1958 'ServerKeyExchange' message."; 1959 reference 1960 "RFC 4279: Pre-Shared Key Ciphersuites for 1961 Transport Layer Security (TLS)"; 1962 } 1963 } 1964 } 1965 } 1966 } // container server-identity 1968 container client-authentication { 1969 if-feature "client-auth-config-supported"; 1970 nacm:default-deny-write; 1971 must 'ca-certs or ee-certs or raw-public-keys or psks'; 1972 presence 1973 "Indicates that client authentication is supported (i.e., 1974 that the server will request clients send certificates). 1975 If not configured, the TLS server SHOULD NOT request the 1976 TLS clients provide authentication credentials."; 1977 description 1978 "Specifies how the TLS server can authenticate TLS clients. 1979 Any combination of credentials is additive and unordered. 1981 Note that no configuration is required for PSK (pre-shared 1982 or pairwise-symmetric key) based authentication as the key 1983 is necessarily the same as configured in the '../server- 1984 identity' node."; 1985 container ca-certs { 1986 if-feature "x509-certificate-auth"; 1987 presence 1988 "Indicates that the TLS server can authenticate TLS clients 1989 using configured certificate authority certificates."; 1990 description 1991 "A set of certificate authority (CA) certificates used by 1992 the TLS server to authenticate TLS client certificates. A 1993 client certificate is authenticated if it has a valid 1994 chain of trust to a configured CA certificate."; 1995 reference 1996 "RFC BBBB: A YANG Data Model for a Truststore"; 1997 uses ts:local-or-truststore-certs-grouping; 1998 } 1999 container ee-certs { 2000 if-feature "x509-certificate-auth"; 2001 presence 2002 "Indicates that the TLS server can authenticate TLS 2003 clients using configured client certificates."; 2004 description 2005 "A set of client certificates (i.e., end entity 2006 certificates) used by the TLS server to authenticate 2007 certificates presented by TLS clients. A client 2008 certificate is authenticated if it is an exact 2009 match to a configured client certificate."; 2010 reference 2011 "RFC BBBB: A YANG Data Model for a Truststore"; 2012 uses ts:local-or-truststore-certs-grouping; 2013 } 2014 container raw-public-keys { 2015 if-feature "raw-public-key-auth"; 2016 presence 2017 "Indicates that the TLS server can authenticate TLS 2018 clients using raw public keys."; 2019 description 2020 "A set of raw public keys used by the TLS server to 2021 authenticate raw public keys presented by the TLS 2022 client. A raw public key is authenticated if it 2023 is an exact match to a configured raw public key."; 2024 reference 2025 "RFC BBBB: A YANG Data Model for a Truststore"; 2026 uses ts:local-or-truststore-public-keys-grouping { 2027 refine "local-or-truststore/local/local-definition" 2028 + "/public-key" { 2029 must 'public-key-format' 2030 + ' = "ct:subject-public-key-info-format"'; 2031 } 2032 refine "local-or-truststore/truststore" 2033 + "/truststore-reference" { 2034 must 'deref(.)/../*/ts:public-key-format' 2035 + ' = "ct:subject-public-key-info-format"'; 2036 } 2037 } 2038 } 2039 leaf psks { 2040 if-feature "psk-auth"; 2041 type empty; 2042 description 2043 "Indicates that the TLS server can authenticate TLS clients 2044 using configured PSKs (pre-shared or pairwise-symmetric 2045 keys). 2047 No configuration is required since the PSK value is the 2048 same as PSK value configured in the 'server-identity' 2049 node."; 2050 } 2051 } // container client-authentication 2053 container hello-params { 2054 nacm:default-deny-write; 2055 if-feature "tls-server-hello-params-config"; 2056 uses tlscmn:hello-params-grouping; 2057 description 2058 "Configurable parameters for the TLS hello message."; 2059 } // container hello-params 2061 container keepalives { 2062 nacm:default-deny-write; 2063 if-feature "tls-server-keepalives"; 2064 description 2065 "Configures the keepalive policy for the TLS server."; 2066 leaf peer-allowed-to-send { 2067 type empty; 2068 description 2069 "Indicates that the remote TLS client is allowed to send 2070 HeartbeatRequest messages, as defined by RFC 6520 2071 to this TLS server."; 2072 reference 2073 "RFC 6520: Transport Layer Security (TLS) and Datagram 2074 Transport Layer Security (DTLS) Heartbeat Extension"; 2075 } 2076 container test-peer-aliveness { 2077 presence 2078 "Indicates that the TLS server proactively tests the 2079 aliveness of the remote TLS client."; 2080 description 2081 "Configures the keep-alive policy to proactively test 2082 the aliveness of the TLS client. An unresponsive 2083 TLS client is dropped after approximately max-wait 2084 * max-attempts seconds."; 2085 leaf max-wait { 2086 type uint16 { 2087 range "1..max"; 2088 } 2089 units "seconds"; 2090 default "30"; 2091 description 2092 "Sets the amount of time in seconds after which if 2093 no data has been received from the TLS client, a 2094 TLS-level message will be sent to test the 2095 aliveness of the TLS client."; 2096 } 2097 leaf max-attempts { 2098 type uint8; 2099 default "3"; 2100 description 2101 "Sets the maximum number of sequential keep-alive 2102 messages that can fail to obtain a response from 2103 the TLS client before assuming the TLS client is 2104 no longer alive."; 2105 } 2106 } 2107 } // container keepalives 2108 } // grouping tls-server-grouping 2109 } // module ietf-tls-server 2111 2113 5. Security Considerations 2115 5.1. The "ietf-tls-common" YANG Module 2117 The "ietf-tls-common" YANG module defines "grouping" statements that 2118 are designed to be accessed via YANG based management protocols, such 2119 as NETCONF [RFC6241] and RESTCONF [RFC8040]. Both of these protocols 2120 have mandatory-to-implement secure transport layers (e.g., SSH, TLS) 2121 with mutual authentication. 2123 The NETCONF access control model (NACM) [RFC8341] provides the means 2124 to restrict access for particular users to a pre-configured subset of 2125 all available protocol operations and content. 2127 Since the module in this document only define groupings, these 2128 considerations are primarily for the designers of other modules that 2129 use these groupings. 2131 None of the readable data nodes defined in this YANG module are 2132 considered sensitive or vulnerable in network environments. The NACM 2133 "default-deny-all" extension has not been set for any data nodes 2134 defined in this module. 2136 None of the writable data nodes defined in this YANG module are 2137 considered sensitive or vulnerable in network environments. The NACM 2138 "default-deny-write" extension has not been set for any data nodes 2139 defined in this module. 2141 This module does not define any RPCs, actions, or notifications, and 2142 thus the security consideration for such is not provided here. 2144 5.2. The "ietf-tls-client" YANG Module 2146 The "ietf-tls-client" YANG module defines "grouping" statements that 2147 are designed to be accessed via YANG based management protocols, such 2148 as NETCONF [RFC6241] and RESTCONF [RFC8040]. Both of these protocols 2149 have mandatory-to-implement secure transport layers (e.g., SSH, TLS) 2150 with mutual authentication. 2152 The NETCONF access control model (NACM) [RFC8341] provides the means 2153 to restrict access for particular users to a pre-configured subset of 2154 all available protocol operations and content. 2156 Since the module in this document only define groupings, these 2157 considerations are primarily for the designers of other modules that 2158 use these groupings. 2160 None of the readable data nodes defined in this YANG module are 2161 considered sensitive or vulnerable in network environments. The NACM 2162 "default-deny-all" extension has not been set for any data nodes 2163 defined in this module. 2165 | Please be aware that this module uses the "key" and "private- 2166 | key" nodes from the "ietf-crypto-types" module 2167 | [I-D.ietf-netconf-crypto-types], where said nodes have the NACM 2168 | extension "default-deny-all" set, thus preventing unrestricted 2169 | read-access to the cleartext key values. 2171 All of the writable data nodes defined by this module may be 2172 considered sensitive or vulnerable in some network environments. For 2173 instance, any modification to a key or reference to a key may 2174 dramatically alter the implemented security policy. For this reason, 2175 the NACM extension "default-deny-write" has been set for all data 2176 nodes defined in this module. 2178 This module does not define any RPCs, actions, or notifications, and 2179 thus the security consideration for such is not provided here. 2181 5.3. The "ietf-tls-server" YANG Module 2183 The "ietf-tls-server" YANG module defines "grouping" statements that 2184 are designed to be accessed via YANG based management protocols, such 2185 as NETCONF [RFC6241] and RESTCONF [RFC8040]. Both of these protocols 2186 have mandatory-to-implement secure transport layers (e.g., SSH, TLS) 2187 with mutual authentication. 2189 The NETCONF access control model (NACM) [RFC8341] provides the means 2190 to restrict access for particular users to a pre-configured subset of 2191 all available protocol operations and content. 2193 Since the module in this document only define groupings, these 2194 considerations are primarily for the designers of other modules that 2195 use these groupings. 2197 None of the readable data nodes defined in this YANG module are 2198 considered sensitive or vulnerable in network environments. The NACM 2199 "default-deny-all" extension has not been set for any data nodes 2200 defined in this module. 2202 | Please be aware that this module uses the "key" and "private- 2203 | key" nodes from the "ietf-crypto-types" module 2204 | [I-D.ietf-netconf-crypto-types], where said nodes have the NACM 2205 | extension "default-deny-all" set, thus preventing unrestricted 2206 | read-access to the cleartext key values. 2208 All of the writable data nodes defined by this module may be 2209 considered sensitive or vulnerable in some network environments. For 2210 instance, any modification to a key or reference to a key may 2211 dramatically alter the implemented security policy. For this reason, 2212 the NACM extension "default-deny-write" has been set for all data 2213 nodes defined in this module. 2215 This module does not define any RPCs, actions, or notifications, and 2216 thus the security consideration for such is not provided here. 2218 6. IANA Considerations 2220 6.1. The "IETF XML" Registry 2222 This document registers three URIs in the "ns" subregistry of the 2223 IETF XML Registry [RFC3688]. Following the format in [RFC3688], the 2224 following registrations are requested: 2226 URI: urn:ietf:params:xml:ns:yang:ietf-tls-common 2227 Registrant Contact: The IESG 2228 XML: N/A, the requested URI is an XML namespace. 2230 URI: urn:ietf:params:xml:ns:yang:ietf-tls-client 2231 Registrant Contact: The IESG 2232 XML: N/A, the requested URI is an XML namespace. 2234 URI: urn:ietf:params:xml:ns:yang:ietf-tls-server 2235 Registrant Contact: The IESG 2236 XML: N/A, the requested URI is an XML namespace. 2238 6.2. The "YANG Module Names" Registry 2240 This document registers three YANG modules in the YANG Module Names 2241 registry [RFC6020]. Following the format in [RFC6020], the following 2242 registrations are requested: 2244 name: ietf-tls-common 2245 namespace: urn:ietf:params:xml:ns:yang:ietf-tls-common 2246 prefix: tlscmn 2247 reference: RFC FFFF 2249 name: ietf-tls-client 2250 namespace: urn:ietf:params:xml:ns:yang:ietf-tls-client 2251 prefix: tlsc 2252 reference: RFC FFFF 2254 name: ietf-tls-server 2255 namespace: urn:ietf:params:xml:ns:yang:ietf-tls-server 2256 prefix: tlss 2257 reference: RFC FFFF 2259 7. References 2261 7.1. Normative References 2263 [I-D.ietf-netconf-crypto-types] 2264 Watsen, K., "YANG Data Types and Groupings for 2265 Cryptography", Work in Progress, Internet-Draft, draft- 2266 ietf-netconf-crypto-types-18, 20 August 2020, 2267 . 2270 [I-D.ietf-netconf-keystore] 2271 Watsen, K., "A YANG Data Model for a Keystore", Work in 2272 Progress, Internet-Draft, draft-ietf-netconf-keystore-20, 2273 20 August 2020, . 2276 [I-D.ietf-netconf-trust-anchors] 2277 Watsen, K., "A YANG Data Model for a Truststore", Work in 2278 Progress, Internet-Draft, draft-ietf-netconf-trust- 2279 anchors-13, 20 August 2020, . 2282 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2283 Requirement Levels", BCP 14, RFC 2119, 2284 DOI 10.17487/RFC2119, March 1997, 2285 . 2287 [RFC5288] Salowey, J., Choudhury, A., and D. McGrew, "AES Galois 2288 Counter Mode (GCM) Cipher Suites for TLS", RFC 5288, 2289 DOI 10.17487/RFC5288, August 2008, 2290 . 2292 [RFC5289] Rescorla, E., "TLS Elliptic Curve Cipher Suites with SHA- 2293 256/384 and AES Galois Counter Mode (GCM)", RFC 5289, 2294 DOI 10.17487/RFC5289, August 2008, 2295 . 2297 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 2298 the Network Configuration Protocol (NETCONF)", RFC 6020, 2299 DOI 10.17487/RFC6020, October 2010, 2300 . 2302 [RFC7589] Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the 2303 NETCONF Protocol over Transport Layer Security (TLS) with 2304 Mutual X.509 Authentication", RFC 7589, 2305 DOI 10.17487/RFC7589, June 2015, 2306 . 2308 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2309 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2310 . 2312 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2313 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2314 May 2017, . 2316 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 2317 Access Control Model", STD 91, RFC 8341, 2318 DOI 10.17487/RFC8341, March 2018, 2319 . 2321 [RFC8422] Nir, Y., Josefsson, S., and M. Pegourie-Gonnard, "Elliptic 2322 Curve Cryptography (ECC) Cipher Suites for Transport Layer 2323 Security (TLS) Versions 1.2 and Earlier", RFC 8422, 2324 DOI 10.17487/RFC8422, August 2018, 2325 . 2327 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 2328 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 2329 . 2331 7.2. Informative References 2333 [I-D.ietf-netconf-http-client-server] 2334 Watsen, K., "YANG Groupings for HTTP Clients and HTTP 2335 Servers", Work in Progress, Internet-Draft, draft-ietf- 2336 netconf-http-client-server-05, 20 August 2020, 2337 . 2340 [I-D.ietf-netconf-netconf-client-server] 2341 Watsen, K., "NETCONF Client and Server Models", Work in 2342 Progress, Internet-Draft, draft-ietf-netconf-netconf- 2343 client-server-21, 20 August 2020, 2344 . 2347 [I-D.ietf-netconf-restconf-client-server] 2348 Watsen, K., "RESTCONF Client and Server Models", Work in 2349 Progress, Internet-Draft, draft-ietf-netconf-restconf- 2350 client-server-21, 20 August 2020, 2351 . 2354 [I-D.ietf-netconf-ssh-client-server] 2355 Watsen, K., "YANG Groupings for SSH Clients and SSH 2356 Servers", Work in Progress, Internet-Draft, draft-ietf- 2357 netconf-ssh-client-server-22, 20 August 2020, 2358 . 2361 [I-D.ietf-netconf-tcp-client-server] 2362 Watsen, K. and M. Scharf, "YANG Groupings for TCP Clients 2363 and TCP Servers", Work in Progress, Internet-Draft, draft- 2364 ietf-netconf-tcp-client-server-08, 20 August 2020, 2365 . 2368 [I-D.ietf-netconf-tls-client-server] 2369 Watsen, K., "YANG Groupings for TLS Clients and TLS 2370 Servers", Work in Progress, Internet-Draft, draft-ietf- 2371 netconf-tls-client-server-22, 20 August 2020, 2372 . 2375 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 2376 RFC 2246, DOI 10.17487/RFC2246, January 1999, 2377 . 2379 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 2380 DOI 10.17487/RFC2818, May 2000, 2381 . 2383 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2384 DOI 10.17487/RFC3688, January 2004, 2385 . 2387 [RFC4346] Dierks, T. and E. Rescorla, "The Transport Layer Security 2388 (TLS) Protocol Version 1.1", RFC 4346, 2389 DOI 10.17487/RFC4346, April 2006, 2390 . 2392 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2393 (TLS) Protocol Version 1.2", RFC 5246, 2394 DOI 10.17487/RFC5246, August 2008, 2395 . 2397 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2398 and A. Bierman, Ed., "Network Configuration Protocol 2399 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2400 . 2402 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2403 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2404 . 2406 [RFC8071] Watsen, K., "NETCONF Call Home and RESTCONF Call Home", 2407 RFC 8071, DOI 10.17487/RFC8071, February 2017, 2408 . 2410 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 2411 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 2412 . 2414 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 2415 and R. Wilton, "Network Management Datastore Architecture 2416 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 2417 . 2419 Appendix A. Change Log 2421 This section is to be removed before publishing as an RFC. 2423 A.1. 00 to 01 2425 * Noted that '0.0.0.0' and '::' might have special meanings. 2427 * Renamed "keychain" to "keystore". 2429 A.2. 01 to 02 2431 * Removed the groupings containing transport-level configuration. 2432 Now modules contain only the transport-independent groupings. 2434 * Filled in previously incomplete 'ietf-tls-client' module. 2436 * Added cipher suites for various algorithms into new 'ietf-tls- 2437 common' module. 2439 A.3. 02 to 03 2441 * Added a 'must' statement to container 'server-auth' asserting that 2442 at least one of the various auth mechanisms must be specified. 2444 * Fixed description statement for leaf 'trusted-ca-certs'. 2446 A.4. 03 to 04 2448 * Updated title to "YANG Groupings for TLS Clients and TLS Servers" 2450 * Updated leafref paths to point to new keystore path 2452 * Changed the YANG prefix for ietf-tls-common from 'tlscom' to 2453 'tlscmn'. 2455 * Added TLS protocol verions 1.0 and 1.1. 2457 * Made author lists consistent 2458 * Now tree diagrams reference ietf-netmod-yang-tree-diagrams 2460 * Updated YANG to use typedefs around leafrefs to common keystore 2461 paths 2463 * Now inlines key and certificates (no longer a leafref to keystore) 2465 A.5. 04 to 05 2467 * Merged changes from co-author. 2469 A.6. 05 to 06 2471 * Updated to use trust anchors from trust-anchors draft (was 2472 keystore draft) 2474 * Now Uses new keystore grouping enabling asymmetric key to be 2475 either locally defined or a reference to the keystore. 2477 A.7. 06 to 07 2479 * factored the tls-[client|server]-groupings into more reusable 2480 groupings. 2482 * added if-feature statements for the new "x509-certificates" 2483 feature defined in draft-ietf-netconf-trust-anchors. 2485 A.8. 07 to 08 2487 * Added a number of compatibility matrices to Section 5 (thanks 2488 Frank!) 2490 * Clarified that any configured "cipher-suite" values need to be 2491 compatible with the configured private key. 2493 A.9. 08 to 09 2495 * Updated examples to reflect update to groupings defined in the 2496 keystore draft. 2498 * Add TLS keepalives features and groupings. 2500 * Prefixed top-level TLS grouping nodes with 'tls-' and support 2501 mashups. 2503 * Updated copyright date, boilerplate template, affiliation, and 2504 folding algorithm. 2506 A.10. 09 to 10 2508 * Reformatted the YANG modules. 2510 A.11. 10 to 11 2512 * Collapsed all the inner groupings into the top-level grouping. 2514 * Added a top-level "demux container" inside the top-level grouping. 2516 * Added NACM statements and updated the Security Considerations 2517 section. 2519 * Added "presence" statements on the "keepalive" containers, as was 2520 needed to address a validation error that appeared after adding 2521 the "must" statements into the NETCONF/RESTCONF client/server 2522 modules. 2524 * Updated the boilerplate text in module-level "description" 2525 statement to match copyeditor convention. 2527 A.12. 11 to 12 2529 * In server model, made 'client-authentication' a 'presence' node 2530 indicating that the server supports client authentication. 2532 * In the server model, added a 'required-or-optional' choice to 2533 'client-authentication' to better support protocols such as 2534 RESTCONF. 2536 * In the server model, added a 'local-or-external' choice to 2537 'client-authentication' to better support consuming data models 2538 that prefer to keep client auth with client definitions than in a 2539 model principally concerned with the "transport". 2541 * In both models, removed the "demux containers", floating the 2542 nacm:default-deny-write to each descendent node, and adding a note 2543 to model designers regarding the potential need to add their own 2544 demux containers. 2546 * Fixed a couple references (section 2 --> section 3) 2548 A.13. 12 to 13 2550 * Updated to reflect changes in trust-anchors drafts (e.g., s/trust- 2551 anchors/truststore/g + s/pinned.//) 2553 A.14. 12 to 13 2555 * Removed 'container' under 'client-identity' to match server model. 2557 * Updated examples to reflect change grouping in keystore module. 2559 A.15. 13 to 14 2561 * Removed the "certificate" container from "client-identity" in the 2562 ietf-tls-client module. 2564 * Updated examples to reflect ietf-crypto-types change (e.g., 2565 identities --> enumerations) 2567 A.16. 14 to 15 2569 * Updated "server-authentication" and "client-authentication" nodes 2570 from being a leaf of type "ts:certificates-ref" to a container 2571 that uses "ts:local-or-truststore-certs-grouping". 2573 A.17. 15 to 16 2575 * Removed unnecessary if-feature statements in the -client and 2576 -server modules. 2578 * Cleaned up some description statements in the -client and -server 2579 modules. 2581 * Fixed a canonical ordering issue in ietf-tls-common detected by 2582 new pyang. 2584 A.18. 16 to 17 2586 * Removed choice local-or-external by removing the 'external' case 2587 and flattening the 'local' case and adding a "client-auth-config- 2588 supported" feature. 2590 * Removed choice required-or-optional. 2592 * Updated examples to include the "*-key-format" nodes. 2594 * Augmented-in "must" expressions ensuring that locally-defined 2595 public-key-format are "ct:ssh-public-key-format" (must expr for 2596 ref'ed keys are TBD). 2598 A.19. 17 to 18 2600 * Removed the unused "external-client-auth-supported" feature. 2602 * Made client-indentity optional, as there may be over-the-top auth 2603 instead. 2605 * Added augment to uses of local-or-keystore-symmetric-key-grouping 2606 for a psk "id" node. 2608 * Added missing presence container "psks" to ietf-tls-server's 2609 "client-authentication" container. 2611 * Updated examples to reflect new "bag" addition to truststore. 2613 * Removed feature-limited caseless 'case' statements to improve tree 2614 diagram rendering. 2616 * Refined truststore/keystore groupings to ensure the key formats 2617 "must" be particular values. 2619 * Switched to using truststore's new "public-key" bag (instead of 2620 separate "ssh-public-key" and "raw-public-key" bags. 2622 * Updated client/server examples to cover ALL cases (local/ref x 2623 cert/raw-key/psk). 2625 A.20. 18 to 19 2627 * Updated the "keepalives" containers in part to address Michal 2628 Vasko's request to align with RFC 8071, and in part to better 2629 align to RFC 6520. 2631 * Removed algorithm-mapping tables from the "TLS Common Model" 2632 section 2634 * Removed the 'algorithm' node from the examples. 2636 * Renamed both "client-certs" and "server-certs" to "ee-certs" 2638 * Added a "Note to Reviewers" note to first page. 2640 A.21. 19 to 20 2642 * Modified the 'must' expression in the "ietf-tls-client:server- 2643 authention" node to cover the "raw-public-keys" and "psks" nodes 2644 also. 2646 * Added a "must 'ca-certs or ee-certs or raw-public-keys or psks'" 2647 statement to the ietf-tls-server:client-authentication" node. 2649 * Added "mandatory true" to "choice auth-type" and a "presence" 2650 statement to its ancestor. 2652 * Expanded "Data Model Overview section(s) [remove "wall" of tree 2653 diagrams]. 2655 * Moved the "ietf-ssh-common" module section to proceed the other 2656 two module sections. 2658 * Updated the Security Considerations section. 2660 A.22. 20 to 21 2662 * Updated examples to reflect new "cleartext-" prefix in the crypto- 2663 types draft. 2665 A.23. 21 to 22 2667 * In both the "client-authentication" and "server-authentication" 2668 subtrees, replaced the "psks" node from being a P-container to a 2669 leaf of type "empty". 2671 * Cleaned up examples (e.g., removed FIXMEs) 2673 * Fixed issues found by the SecDir review of the "keystore" draft. 2675 * Updated the "psk" sections in the "ietf-tls-client" and "ietf-tls- 2676 server" modules to more correctly reflect RFC 4279. 2678 A.24. 22 to 23 2680 * Addressed comments raised by YANG Doctor in the ct/ts/ks drafts. 2682 Acknowledgements 2684 The authors would like to thank for following for lively discussions 2685 on list and in the halls (ordered by first name): Alan Luchuk, Andy 2686 Bierman, Balazs Kovacs, Benoit Claise, Bert Wijnen, David Lamparter, 2687 Gary Wu, Henk Birkholz, Juergen Schoenwaelder, Ladislav Lhotka, Liang 2688 Xia, Martin Bjorklund, Mehmet Ersue, Michal Vasko, Phil Shafer, Radek 2689 Krejci, Sean Turner, and Tom Petch. 2691 Special acknowledgement goes to Gary Wu who contributed the "ietf- 2692 tls-common" module. 2694 Author's Address 2696 Kent Watsen 2697 Watsen Networks 2699 Email: kent+ietf@watsen.net