idnits 2.17.1 draft-ietf-netconf-tls-client-server-24.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 (18 May 2021) is 1075 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-19 == Outdated reference: A later version (-35) exists of draft-ietf-netconf-keystore-21 == Outdated reference: A later version (-28) exists of draft-ietf-netconf-trust-anchors-14 == Outdated reference: A later version (-20) exists of draft-ietf-netconf-http-client-server-06 == Outdated reference: A later version (-36) exists of draft-ietf-netconf-netconf-client-server-22 == Outdated reference: A later version (-36) exists of draft-ietf-netconf-restconf-client-server-22 == Outdated reference: A later version (-40) exists of draft-ietf-netconf-ssh-client-server-23 == Outdated reference: A later version (-26) exists of draft-ietf-netconf-tcp-client-server-09 == Outdated reference: A later version (-41) exists of draft-ietf-netconf-tls-client-server-23 -- 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 18 May 2021 5 Expires: 19 November 2021 7 YANG Groupings for TLS Clients and TLS Servers 8 draft-ietf-netconf-tls-client-server-24 10 Abstract 12 This document defines three YANG 1.1 modules: the first defines 13 identities and groupings common to both TLS clients and TLS servers, 14 the second defines a grouping for a generic TLS client, and the third 15 defines a grouping for a generic TLS server. 17 Editorial Note (To be removed by RFC Editor) 19 This draft contains placeholder values that need to be replaced with 20 finalized values at the time of publication. This note summarizes 21 all of the substitutions that are needed. No other RFC Editor 22 instructions are specified elsewhere in this document. 24 Artwork in this document contains shorthand references to drafts in 25 progress. Please apply the following replacements: 27 * "AAAA" --> the assigned RFC value for draft-ietf-netconf-crypto- 28 types 30 * "BBBB" --> the assigned RFC value for draft-ietf-netconf-trust- 31 anchors 33 * "CCCC" --> the assigned RFC value for draft-ietf-netconf-keystore 35 * "DDDD" --> the assigned RFC value for draft-ietf-netconf-tcp- 36 client-server 38 * "FFFF" --> the assigned RFC value for this draft 40 Artwork in this document contains placeholder values for the date of 41 publication of this draft. Please apply the following replacement: 43 * "2021-05-18" --> the publication date of this draft 45 The following Appendix section is to be removed prior to publication: 47 * Appendix A. Change Log 49 Status of This Memo 51 This Internet-Draft is submitted in full conformance with the 52 provisions of BCP 78 and BCP 79. 54 Internet-Drafts are working documents of the Internet Engineering 55 Task Force (IETF). Note that other groups may also distribute 56 working documents as Internet-Drafts. The list of current Internet- 57 Drafts is at https://datatracker.ietf.org/drafts/current/. 59 Internet-Drafts are draft documents valid for a maximum of six months 60 and may be updated, replaced, or obsoleted by other documents at any 61 time. It is inappropriate to use Internet-Drafts as reference 62 material or to cite them other than as "work in progress." 64 This Internet-Draft will expire on 19 November 2021. 66 Copyright Notice 68 Copyright (c) 2021 IETF Trust and the persons identified as the 69 document authors. All rights reserved. 71 This document is subject to BCP 78 and the IETF Trust's Legal 72 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 73 license-info) in effect on the date of publication of this document. 74 Please review these documents carefully, as they describe your rights 75 and restrictions with respect to this document. Code Components 76 extracted from this document must include Simplified BSD License text 77 as described in Section 4.e of the Trust Legal Provisions and are 78 provided without warranty as described in the Simplified BSD License. 80 Table of Contents 82 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 83 1.1. Relation to other RFCs . . . . . . . . . . . . . . . . . 4 84 1.2. Specification Language . . . . . . . . . . . . . . . . . 6 85 1.3. Adherence to the NMDA . . . . . . . . . . . . . . . . . . 6 86 2. The "ietf-tls-common" Module . . . . . . . . . . . . . . . . 6 87 2.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 7 88 2.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 10 89 2.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 10 90 3. The "ietf-tls-client" Module . . . . . . . . . . . . . . . . 19 91 3.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 19 92 3.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 22 93 3.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 26 94 4. The "ietf-tls-server" Module . . . . . . . . . . . . . . . . 34 95 4.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 34 96 4.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 36 97 4.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 40 98 5. Security Considerations . . . . . . . . . . . . . . . . . . . 47 99 5.1. The "ietf-tls-common" YANG Module . . . . . . . . . . . . 48 100 5.2. The "ietf-tls-client" YANG Module . . . . . . . . . . . . 48 101 5.3. The "ietf-tls-server" YANG Module . . . . . . . . . . . . 49 102 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 50 103 6.1. The "IETF XML" Registry . . . . . . . . . . . . . . . . . 50 104 6.2. The "YANG Module Names" Registry . . . . . . . . . . . . 50 105 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 51 106 7.1. Normative References . . . . . . . . . . . . . . . . . . 51 107 7.2. Informative References . . . . . . . . . . . . . . . . . 52 108 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 54 109 A.1. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 54 110 A.2. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 54 111 A.3. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 55 112 A.4. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 55 113 A.5. 04 to 05 . . . . . . . . . . . . . . . . . . . . . . . . 55 114 A.6. 05 to 06 . . . . . . . . . . . . . . . . . . . . . . . . 55 115 A.7. 06 to 07 . . . . . . . . . . . . . . . . . . . . . . . . 55 116 A.8. 07 to 08 . . . . . . . . . . . . . . . . . . . . . . . . 56 117 A.9. 08 to 09 . . . . . . . . . . . . . . . . . . . . . . . . 56 118 A.10. 09 to 10 . . . . . . . . . . . . . . . . . . . . . . . . 56 119 A.11. 10 to 11 . . . . . . . . . . . . . . . . . . . . . . . . 56 120 A.12. 11 to 12 . . . . . . . . . . . . . . . . . . . . . . . . 56 121 A.13. 12 to 13 . . . . . . . . . . . . . . . . . . . . . . . . 57 122 A.14. 12 to 13 . . . . . . . . . . . . . . . . . . . . . . . . 57 123 A.15. 13 to 14 . . . . . . . . . . . . . . . . . . . . . . . . 57 124 A.16. 14 to 15 . . . . . . . . . . . . . . . . . . . . . . . . 57 125 A.17. 15 to 16 . . . . . . . . . . . . . . . . . . . . . . . . 57 126 A.18. 16 to 17 . . . . . . . . . . . . . . . . . . . . . . . . 58 127 A.19. 17 to 18 . . . . . . . . . . . . . . . . . . . . . . . . 58 128 A.20. 18 to 19 . . . . . . . . . . . . . . . . . . . . . . . . 59 129 A.21. 19 to 20 . . . . . . . . . . . . . . . . . . . . . . . . 59 130 A.22. 20 to 21 . . . . . . . . . . . . . . . . . . . . . . . . 59 131 A.23. 21 to 22 . . . . . . . . . . . . . . . . . . . . . . . . 59 132 A.24. 22 to 23 . . . . . . . . . . . . . . . . . . . . . . . . 60 133 A.25. 23 to 24 . . . . . . . . . . . . . . . . . . . . . . . . 60 134 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 60 135 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 60 136 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 60 138 1. Introduction 140 This document defines three YANG 1.1 [RFC7950] modules: the first 141 defines identities and groupings common to both TLS clients and TLS 142 servers, the second defines a grouping for a generic TLS client, and 143 the third defines a grouping for a generic TLS server. It is 144 intended that these groupings will be used by applications using the 145 TLS protocol [RFC5246]. For instance, these groupings could be used 146 to help define the data model for an HTTPS [RFC2818] server or a 147 NETCONF over TLS [RFC7589] based server. 149 The client and server YANG modules in this document each define one 150 grouping, which is focused on just TLS-specific configuration, and 151 specifically avoids any transport-level configuration, such as what 152 ports to listen-on or connect-to. This affords applications the 153 opportunity to define their own strategy for how the underlying TCP 154 connection is established. For instance, applications supporting 155 NETCONF Call Home [RFC8071] could use the "ssh-server-grouping" 156 grouping for the TLS parts it provides, while adding data nodes for 157 the TCP-level call-home configuration. 159 1.1. Relation to other RFCs 161 This document presents one or more YANG modules [RFC7950] that are 162 part of a collection of RFCs that work together to, ultimately, 163 enable the configuration of the clients and servers of both the 164 NETCONF [RFC6241] and RESTCONF [RFC8040] protocols. 166 The modules have been defined in a modular fashion to enable their 167 use by other efforts, some of which are known to be in progress at 168 the time of this writing, with many more expected to be defined in 169 time. 171 The normative dependency relationship between the various RFCs in the 172 collection is presented in the below diagram. The labels in the 173 diagram represent the primary purpose provided by each RFC. 174 Hyperlinks to each RFC are provided below the diagram. 176 crypto-types 177 ^ ^ 178 / \ 179 / \ 180 truststore keystore 181 ^ ^ ^ ^ 182 | +---------+ | | 183 | | | | 184 | +------------+ | 185 tcp-client-server | / | | 186 ^ ^ ssh-client-server | | 187 | | ^ tls-client-server 188 | | | ^ ^ http-client-server 189 | | | | | ^ 190 | | | +-----+ +---------+ | 191 | | | | | | 192 | +-----------|--------|--------------+ | | 193 | | | | | | 194 +-----------+ | | | | | 195 | | | | | | 196 | | | | | | 197 netconf-client-server restconf-client-server 199 +=======================+===========================================+ 200 |Label in Diagram | Originating RFC | 201 +=======================+===========================================+ 202 |crypto-types | [I-D.ietf-netconf-crypto-types] | 203 +-----------------------+-------------------------------------------+ 204 |truststore | [I-D.ietf-netconf-trust-anchors] | 205 +-----------------------+-------------------------------------------+ 206 |keystore | [I-D.ietf-netconf-keystore] | 207 +-----------------------+-------------------------------------------+ 208 |tcp-client-server | [I-D.ietf-netconf-tcp-client-server] | 209 +-----------------------+-------------------------------------------+ 210 |ssh-client-server | [I-D.ietf-netconf-ssh-client-server] | 211 +-----------------------+-------------------------------------------+ 212 |tls-client-server | [I-D.ietf-netconf-tls-client-server] | 213 +-----------------------+-------------------------------------------+ 214 |http-client-server | [I-D.ietf-netconf-http-client-server] | 215 +-----------------------+-------------------------------------------+ 216 |netconf-client-server | [I-D.ietf-netconf-netconf-client-server] | 217 +-----------------------+-------------------------------------------+ 218 |restconf-client-server | [I-D.ietf-netconf-restconf-client-server] | 219 +-----------------------+-------------------------------------------+ 221 Table 1: Label to RFC Mapping 223 1.2. Specification Language 225 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 226 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 227 "OPTIONAL" in this document are to be interpreted as described in BCP 228 14 [RFC2119] [RFC8174] when, and only when, they appear in all 229 capitals, as shown here. 231 1.3. Adherence to the NMDA 233 This document is compliant with the Network Management Datastore 234 Architecture (NMDA) [RFC8342]. For instance, as described in 235 [I-D.ietf-netconf-trust-anchors] and [I-D.ietf-netconf-keystore], 236 trust anchors and keys installed during manufacturing are expected to 237 appear in . 239 2. The "ietf-tls-common" Module 241 The TLS common model presented in this section contains identities 242 and groupings common to both TLS clients and TLS servers. The 243 "hello-params-grouping" grouping can be used to configure the list of 244 TLS algorithms permitted by the TLS client or TLS server. The lists 245 of algorithms are ordered such that, if multiple algorithms are 246 permitted by the client, the algorithm that appears first in its list 247 that is also permitted by the server is used for the TLS transport 248 layer connection. The ability to restrict the algorithms allowed is 249 provided in this grouping for TLS clients and TLS servers that are 250 capable of doing so and may serve to make TLS clients and TLS servers 251 compliant with local security policies. This model supports both 252 TLS1.2 [RFC5246] and TLS 1.3 [RFC8446]. 254 TLS 1.2 and TLS 1.3 have different ways defining their own supported 255 cryptographic algorithms, see TLS and DTLS IANA registries page 256 (https://www.iana.org/assignments/tls-parameters/tls- 257 parameters.xhtml): 259 * TLS 1.2 defines four categories of registries for cryptographic 260 algorithms: TLS Cipher Suites, TLS SignatureAlgorithm, TLS 261 HashAlgorithm, TLS Supported Groups. TLS Cipher Suites plays the 262 role of combining all of them into one set, as each value of the 263 set represents a unique and feasible combination of all the 264 cryptographic algorithms, and thus the other three registry 265 categories do not need to be considered here. In this document, 266 the TLS common model only chooses those TLS1.2 algorithms in TLS 267 Cipher Suites which are marked as recommended: 268 TLS_DHE_RSA_WITH_AES_128_GCM_SHA256, 269 TLS_DHE_RSA_WITH_AES_256_GCM_SHA384, 270 TLS_DHE_PSK_WITH_AES_128_GCM_SHA256, 271 TLS_DHE_PSK_WITH_AES_256_GCM_SHA384, and so on. All chosen 272 algorithms are enumerated in Table 1-1 below; 274 * TLS 1.3 defines its supported algorithms differently. Firstly, it 275 defines three categories of registries for cryptographic 276 algorithms: TLS Cipher Suites, TLS SignatureScheme, TLS Supported 277 Groups. Secondly, all three of these categories are useful, since 278 they represent different parts of all the supported algorithms 279 respectively. Thus, all of these registries categories are 280 considered here. In this draft, the TLS common model chooses only 281 those TLS1.3 algorithms specified in B.4, 4.2.3, 4.2.7 of 282 [RFC8446]. 284 Thus, in order to support both TLS1.2 and TLS1.3, the cipher-suites 285 part of the "hello-params-grouping" grouping should include three 286 parameters for configuring its permitted TLS algorithms, which are: 287 TLS Cipher Suites, TLS SignatureScheme, TLS Supported Groups. Note 288 that TLS1.2 only uses TLS Cipher Suites. 290 Features are defined for algorithms that are OPTIONAL or are not 291 widely supported by popular implementations. Note that the list of 292 algorithms is not exhaustive. 294 2.1. Data Model Overview 296 This section provides an overview of the "ietf-tls-common" module in 297 terms of its features, identitiesm and groupings. 299 2.1.1. Features 301 The following diagram lists all the "feature" statements defined in 302 the "ietf-tls-common" module: 304 Features: 305 +-- tls-1_0 306 +-- tls-1_1 307 +-- tls-1_2 308 +-- tls-1_3 309 +-- tls-ecc 310 +-- tls-dhe 311 +-- tls-3des 312 +-- tls-gcm 313 +-- tls-sha2 315 | The diagram above uses syntax that is similar to but not 316 | defined in [RFC8340]. 318 2.1.2. Identities 320 The following diagram illustrates the relationship amongst the 321 "identity" statements defined in the "ietf-tls-common" module: 323 Identities: 324 +-- tls-version-base 325 | +-- tls-1.0 326 | +-- tls-1.1 327 | +-- tls-1.2 328 | +-- tls-1.3 329 +-- cipher-suite-base 330 +-- rsa-with-aes-128-cbc-sha 331 +-- rsa-with-aes-256-cbc-sha 332 +-- rsa-with-aes-128-cbc-sha256 333 +-- rsa-with-aes-256-cbc-sha256 334 +-- dhe-rsa-with-aes-128-cbc-sha 335 +-- dhe-rsa-with-aes-256-cbc-sha 336 +-- dhe-rsa-with-aes-128-cbc-sha256 337 +-- dhe-rsa-with-aes-256-cbc-sha256 338 +-- ecdhe-ecdsa-with-aes-128-cbc-sha256 339 +-- ecdhe-ecdsa-with-aes-256-cbc-sha384 340 +-- ecdhe-rsa-with-aes-128-cbc-sha256 341 +-- ecdhe-rsa-with-aes-256-cbc-sha384 342 +-- ecdhe-ecdsa-with-aes-128-gcm-sha256 343 +-- ecdhe-ecdsa-with-aes-256-gcm-sha384 344 +-- ecdhe-rsa-with-aes-128-gcm-sha256 345 +-- ecdhe-rsa-with-aes-256-gcm-sha384 346 +-- rsa-with-3des-ede-cbc-sha 347 +-- ecdhe-rsa-with-3des-ede-cbc-sha 348 +-- ecdhe-rsa-with-aes-128-cbc-sha 349 +-- ecdhe-rsa-with-aes-256-cbc-sha 351 | The diagram above uses syntax that is similar to but not 352 | defined in [RFC8340]. 354 Comments: 356 * The diagram shows that there are two base identities. 357 * One base identity is used to specific TLS versions, while the 358 other is used to specify cipher-suites. 359 * These base identities are "abstract", in the object oriented 360 programming sense, in that they only define a "class" of things, 361 rather than a specific thing. 363 2.1.3. Groupings 365 The "ietf-tls-common" module defines the following "grouping" 366 statement: 368 * hello-params-grouping 370 This grouping is presented in the following subsection. 372 2.1.3.1. The "hello-params-grouping" Grouping 374 The following tree diagram [RFC8340] illustrates the "hello-params- 375 grouping" grouping: 377 grouping hello-params-grouping 378 +-- tls-versions 379 | +-- tls-version* identityref 380 +-- cipher-suites 381 +-- cipher-suite* identityref 383 Comments: 385 * This grouping is used by both the "tls-client-grouping" and the 386 "tls-server-grouping" groupings defined in Section 3.1.2.1 and 387 Section 4.1.2.1, respectively. 389 * This grouping enables client and server configurations to specify 390 the TLS versions and cipher suites that are to be used when 391 establishing TLS sessions. 393 * The "cipher-suites" list is "ordered-by user". 395 2.1.4. Protocol-accessible Nodes 397 The "ietf-tls-common" module defines only "grouping" statements that 398 are used by other modules to instantiate protocol-accessible nodes. 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 406 407 410 411 tlscmn:tls-1.1 412 tlscmn:tls-1.2 413 414 415 tlscmn:dhe-rsa-with-aes-128-cbc-sha 416 tlscmn:rsa-with-aes-128-cbc-sha 417 tlscmn:rsa-with-3des-ede-cbc-sha 418 419 421 2.3. YANG Module 423 This YANG module has a normative references to [RFC4346], [RFC5246], 424 [RFC5288], [RFC5289], [RFC8422], and FIPS PUB 180-4. 426 This YANG module has a informative references to [RFC2246], 427 [RFC4346], [RFC5246], and [RFC8446]. 429 file "ietf-tls-common@2021-05-18.yang" 431 module ietf-tls-common { 432 yang-version 1.1; 433 namespace "urn:ietf:params:xml:ns:yang:ietf-tls-common"; 434 prefix tlscmn; 436 organization 437 "IETF NETCONF (Network Configuration) Working Group"; 439 contact 440 "WG Web: 441 WG List: 442 Author: Kent Watsen 443 Author: Gary Wu "; 445 description 446 "This module defines a common features, identities, and 447 groupings for Transport Layer Security (TLS). 449 Copyright (c) 2021 IETF Trust and the persons identified 450 as authors of the code. All rights reserved. 452 Redistribution and use in source and binary forms, with 453 or without modification, is permitted pursuant to, and 454 subject to the license terms contained in, the Simplified 455 BSD License set forth in Section 4.c of the IETF Trust's 456 Legal Provisions Relating to IETF Documents 457 (https://trustee.ietf.org/license-info). 459 This version of this YANG module is part of RFC FFFF 460 (https://www.rfc-editor.org/info/rfcFFFF); see the RFC 461 itself for full legal notices. 463 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 464 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 465 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 466 are to be interpreted as described in BCP 14 (RFC 2119) 467 (RFC 8174) when, and only when, they appear in all 468 capitals, as shown here."; 470 revision 2021-05-18 { 471 description 472 "Initial version"; 473 reference 474 "RFC FFFF: YANG Groupings for TLS Clients and TLS Servers"; 475 } 477 // Features 479 feature tls-1_0 { 480 description 481 "TLS Protocol Version 1.0 is supported. TLS 1.0 is obsolete 482 and thus it is NOT RECOMMENDED to enable this feature."; 483 reference 484 "RFC 2246: The TLS Protocol Version 1.0"; 485 } 487 feature tls-1_1 { 488 description 489 "TLS Protocol Version 1.1 is supported. TLS 1.1 is obsolete 490 and thus it is NOT RECOMMENDED to enable this feature."; 491 reference 492 "RFC 4346: The Transport Layer Security (TLS) Protocol 493 Version 1.1"; 494 } 496 feature tls-1_2 { 497 description 498 "TLS Protocol Version 1.2 is supported TLS 1.2 is obsolete 499 and thus it is NOT RECOMMENDED to enable this feature."; 500 reference 501 "RFC 5246: The Transport Layer Security (TLS) Protocol 502 Version 1.2"; 503 } 505 feature tls-1_3 { 506 description 507 "TLS Protocol Version 1.3 is supported."; 508 reference 509 "RFC 8446: The Transport Layer Security (TLS) Protocol 510 Version 1.3"; 511 } 513 feature tls-ecc { 514 description 515 "Elliptic Curve Cryptography (ECC) is supported for TLS."; 516 reference 517 "RFC 8422: Elliptic Curve Cryptography (ECC) Cipher Suites 518 for Transport Layer Security (TLS)"; 519 } 521 feature tls-dhe { 522 description 523 "Ephemeral Diffie-Hellman key exchange is supported for TLS."; 524 reference 525 "RFC 5246: The Transport Layer Security (TLS) Protocol 526 Version 1.2"; 527 } 529 feature tls-3des { 530 description 531 "The Triple-DES block cipher is supported for TLS."; 532 reference 533 "RFC 5246: The Transport Layer Security (TLS) Protocol 534 Version 1.2"; 535 } 537 feature tls-gcm { 538 description 539 "The Galois/Counter Mode authenticated encryption mode is 540 supported for TLS."; 541 reference 542 "RFC 5288: AES Galois Counter Mode (GCM) Cipher Suites for 543 TLS"; 544 } 545 feature tls-sha2 { 546 description 547 "The SHA2 family of cryptographic hash functions is supported 548 for TLS."; 549 reference 550 "FIPS PUB 180-4: Secure Hash Standard (SHS)"; 551 } 553 // Identities 555 identity tls-version-base { 556 description 557 "Base identity used to identify TLS protocol versions."; 558 } 560 identity tls-1.0 { 561 if-feature "tls-1_0"; 562 base tls-version-base; 563 description 564 "TLS Protocol Version 1.0."; 565 reference 566 "RFC 2246: The TLS Protocol Version 1.0"; 567 } 569 identity tls-1.1 { 570 if-feature "tls-1_1"; 571 base tls-version-base; 572 description 573 "TLS Protocol Version 1.1."; 574 reference 575 "RFC 4346: The Transport Layer Security (TLS) Protocol 576 Version 1.1"; 577 } 579 identity tls-1.2 { 580 if-feature "tls-1_2"; 581 base tls-version-base; 582 description 583 "TLS Protocol Version 1.2."; 584 reference 585 "RFC 5246: The Transport Layer Security (TLS) Protocol 586 Version 1.2"; 587 } 589 identity tls-1.3 { 590 if-feature "tls-1_3"; 591 base tls-version-base; 592 description 593 "TLS Protocol Version 1.3."; 594 reference 595 "RFC 8446: The Transport Layer Security (TLS) Protocol 596 Version 1.3"; 597 } 599 identity cipher-suite-base { 600 description 601 "Base identity used to identify TLS cipher suites."; 602 } 604 identity rsa-with-aes-128-cbc-sha { 605 base cipher-suite-base; 606 description 607 "Cipher suite TLS_RSA_WITH_AES_128_CBC_SHA."; 608 reference 609 "RFC 5246: The Transport Layer Security (TLS) Protocol 610 Version 1.2"; 611 } 613 identity rsa-with-aes-256-cbc-sha { 614 base cipher-suite-base; 615 description 616 "Cipher suite TLS_RSA_WITH_AES_256_CBC_SHA."; 617 reference 618 "RFC 5246: The Transport Layer Security (TLS) Protocol 619 Version 1.2"; 620 } 622 identity rsa-with-aes-128-cbc-sha256 { 623 if-feature "tls-sha2"; 624 base cipher-suite-base; 625 description 626 "Cipher suite TLS_RSA_WITH_AES_128_CBC_SHA256."; 627 reference 628 "RFC 5246: The Transport Layer Security (TLS) Protocol 629 Version 1.2"; 630 } 632 identity rsa-with-aes-256-cbc-sha256 { 633 if-feature "tls-sha2"; 634 base cipher-suite-base; 635 description 636 "Cipher suite TLS_RSA_WITH_AES_256_CBC_SHA256."; 637 reference 638 "RFC 5246: The Transport Layer Security (TLS) Protocol 639 Version 1.2"; 640 } 641 identity dhe-rsa-with-aes-128-cbc-sha { 642 if-feature "tls-dhe"; 643 base cipher-suite-base; 644 description 645 "Cipher suite TLS_DHE_RSA_WITH_AES_128_CBC_SHA."; 646 reference 647 "RFC 5246: The Transport Layer Security (TLS) Protocol 648 Version 1.2"; 649 } 651 identity dhe-rsa-with-aes-256-cbc-sha { 652 if-feature "tls-dhe"; 653 base cipher-suite-base; 654 description 655 "Cipher suite TLS_DHE_RSA_WITH_AES_256_CBC_SHA."; 656 reference 657 "RFC 5246: The Transport Layer Security (TLS) Protocol 658 Version 1.2"; 659 } 661 identity dhe-rsa-with-aes-128-cbc-sha256 { 662 if-feature "tls-dhe and tls-sha2"; 663 base cipher-suite-base; 664 description 665 "Cipher suite TLS_DHE_RSA_WITH_AES_128_CBC_SHA256."; 666 reference 667 "RFC 5246: The Transport Layer Security (TLS) Protocol 668 Version 1.2"; 669 } 671 identity dhe-rsa-with-aes-256-cbc-sha256 { 672 if-feature "tls-dhe and tls-sha2"; 673 base cipher-suite-base; 674 description 675 "Cipher suite TLS_DHE_RSA_WITH_AES_256_CBC_SHA256."; 676 reference 677 "RFC 5246: The Transport Layer Security (TLS) Protocol 678 Version 1.2"; 679 } 681 identity ecdhe-ecdsa-with-aes-128-cbc-sha256 { 682 if-feature "tls-ecc and tls-sha2"; 683 base cipher-suite-base; 684 description 685 "Cipher suite TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256."; 686 reference 687 "RFC 5289: TLS Elliptic Curve Cipher Suites with 688 SHA-256/384 and AES Galois Counter Mode (GCM)"; 690 } 692 identity ecdhe-ecdsa-with-aes-256-cbc-sha384 { 693 if-feature "tls-ecc and tls-sha2"; 694 base cipher-suite-base; 695 description 696 "Cipher suite TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384."; 697 reference 698 "RFC 5289: TLS Elliptic Curve Cipher Suites with 699 SHA-256/384 and AES Galois Counter Mode (GCM)"; 700 } 702 identity ecdhe-rsa-with-aes-128-cbc-sha256 { 703 if-feature "tls-ecc and tls-sha2"; 704 base cipher-suite-base; 705 description 706 "Cipher suite TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256."; 707 reference 708 "RFC 5289: TLS Elliptic Curve Cipher Suites with 709 SHA-256/384 and AES Galois Counter Mode (GCM)"; 710 } 712 identity ecdhe-rsa-with-aes-256-cbc-sha384 { 713 if-feature "tls-ecc and tls-sha2"; 714 base cipher-suite-base; 715 description 716 "Cipher suite TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384."; 717 reference 718 "RFC 5289: TLS Elliptic Curve Cipher Suites with 719 SHA-256/384 and AES Galois Counter Mode (GCM)"; 720 } 722 identity ecdhe-ecdsa-with-aes-128-gcm-sha256 { 723 if-feature "tls-ecc and tls-gcm and tls-sha2"; 724 base cipher-suite-base; 725 description 726 "Cipher suite TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256."; 727 reference 728 "RFC 5289: TLS Elliptic Curve Cipher Suites with 729 SHA-256/384 and AES Galois Counter Mode (GCM)"; 730 } 732 identity ecdhe-ecdsa-with-aes-256-gcm-sha384 { 733 if-feature "tls-ecc and tls-gcm and tls-sha2"; 734 base cipher-suite-base; 735 description 736 "Cipher suite TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384."; 737 reference 738 "RFC 5289: TLS Elliptic Curve Cipher Suites with 739 SHA-256/384 and AES Galois Counter Mode (GCM)"; 740 } 742 identity ecdhe-rsa-with-aes-128-gcm-sha256 { 743 if-feature "tls-ecc and tls-gcm and tls-sha2"; 744 base cipher-suite-base; 745 description 746 "Cipher suite TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256."; 747 reference 748 "RFC 5289: TLS Elliptic Curve Cipher Suites with 749 SHA-256/384 and AES Galois Counter Mode (GCM)"; 750 } 752 identity ecdhe-rsa-with-aes-256-gcm-sha384 { 753 if-feature "tls-ecc and tls-gcm and tls-sha2"; 754 base cipher-suite-base; 755 description 756 "Cipher suite TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384."; 757 reference 758 "RFC 5289: TLS Elliptic Curve Cipher Suites with 759 SHA-256/384 and AES Galois Counter Mode (GCM)"; 760 } 762 identity rsa-with-3des-ede-cbc-sha { 763 if-feature "tls-3des"; 764 base cipher-suite-base; 765 description 766 "Cipher suite TLS_RSA_WITH_3DES_EDE_CBC_SHA."; 767 reference 768 "RFC 5246: The Transport Layer Security (TLS) Protocol 769 Version 1.2"; 770 } 772 identity ecdhe-rsa-with-3des-ede-cbc-sha { 773 if-feature "tls-ecc and tls-3des"; 774 base cipher-suite-base; 775 description 776 "Cipher suite TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA."; 777 reference 778 "RFC 8422: Elliptic Curve Cryptography (ECC) Cipher Suites 779 for Transport Layer Security (TLS)"; 780 } 782 identity ecdhe-rsa-with-aes-128-cbc-sha { 783 if-feature "tls-ecc"; 784 base cipher-suite-base; 785 description 786 "Cipher suite TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA."; 787 reference 788 "RFC 8422: Elliptic Curve Cryptography (ECC) Cipher Suites 789 for Transport Layer Security (TLS)"; 790 } 792 identity ecdhe-rsa-with-aes-256-cbc-sha { 793 if-feature "tls-ecc"; 794 base cipher-suite-base; 795 description 796 "Cipher suite TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA."; 797 reference 798 "RFC 8422: Elliptic Curve Cryptography (ECC) Cipher Suites 799 for Transport Layer Security (TLS)"; 800 } 802 // Groupings 804 grouping hello-params-grouping { 805 description 806 "A reusable grouping for TLS hello message parameters."; 807 reference 808 "RFC 5246: The Transport Layer Security (TLS) Protocol 809 Version 1.2"; 810 container tls-versions { 811 description 812 "Parameters regarding TLS versions."; 813 leaf-list tls-version { 814 type identityref { 815 base tls-version-base; 816 } 817 description 818 "Acceptable TLS protocol versions. 820 If this leaf-list is not configured (has zero elements) 821 the acceptable TLS protocol versions are implementation- 822 defined."; 823 } 824 } 825 container cipher-suites { 826 description 827 "Parameters regarding cipher suites."; 828 leaf-list cipher-suite { 829 type identityref { 830 base cipher-suite-base; 831 } 832 ordered-by user; 833 description 834 "Acceptable cipher suites in order of descending 835 preference. The configured host key algorithms should 836 be compatible with the algorithm used by the configured 837 private key. Please see Section 5 of RFC FFFF for 838 valid combinations. 840 If this leaf-list is not configured (has zero elements) 841 the acceptable cipher suites are implementation- 842 defined."; 843 reference 844 "RFC FFFF: YANG Groupings for TLS Clients and TLS Servers"; 845 } 846 } 847 } // hello-params-grouping 849 } 851 853 3. The "ietf-tls-client" Module 855 This section defines a YANG 1.1 [RFC7950] module called "ietf-tls- 856 client". A high-level overview of the module is provided in 857 Section 3.1. Examples illustrating the module's use are provided in 858 Examples (Section 3.2). The YANG module itself is defined in 859 Section 3.3. 861 3.1. Data Model Overview 863 This section provides an overview of the "ietf-tls-client" module in 864 terms of its features and groupings. 866 3.1.1. Features 868 The following diagram lists all the "feature" statements defined in 869 the "ietf-tls-client" module: 871 Features: 872 +-- tls-client-hello-params-config 873 +-- tls-client-keepalives 874 +-- client-ident-x509-cert 875 +-- client-ident-raw-public-key 876 +-- client-ident-psk 877 +-- server-auth-x509-cert 878 +-- server-auth-raw-public-key 879 +-- server-auth-psk 880 | The diagram above uses syntax that is similar to but not 881 | defined in [RFC8340]. 883 3.1.2. Groupings 885 The "ietf-tls-client" module defines the following "grouping" 886 statement: 888 * tls-client-grouping 890 This grouping is presented in the following subsection. 892 3.1.2.1. The "tls-client-grouping" Grouping 894 The following tree diagram [RFC8340] illustrates the "tls-client- 895 grouping" grouping: 897 =============== NOTE: '\' line wrapping per RFC 8792 ================ 899 grouping tls-client-grouping 900 +-- client-identity! 901 | +-- (auth-type) 902 | +--:(certificate) {client-ident-x509-cert}? 903 | | +-- certificate 904 | | +---u ks:local-or-keystore-end-entity-cert-with-key-\ 905 grouping 906 | +--:(raw-public-key) {client-ident-raw-public-key}? 907 | | +-- raw-private-key 908 | | +---u ks:local-or-keystore-asymmetric-key-grouping 909 | +--:(psk) {client-ident-psk}? 910 | +-- psk 911 | +---u ks:local-or-keystore-symmetric-key-grouping 912 | +-- id? 913 | string 914 +-- server-authentication 915 | +-- ca-certs! {client-ident-x509-cert}? 916 | | +---u ts:local-or-truststore-certs-grouping 917 | +-- ee-certs! {client-ident-x509-cert}? 918 | | +---u ts:local-or-truststore-certs-grouping 919 | +-- raw-public-keys! {client-ident-raw-public-key}? 920 | | +---u ts:local-or-truststore-public-keys-grouping 921 | +-- psks? empty {client-ident-psk}? 922 +-- hello-params {tls-client-hello-params-config}? 923 | +---u tlscmn:hello-params-grouping 924 +-- keepalives {tls-client-keepalives}? 925 +-- peer-allowed-to-send? empty 926 +-- test-peer-aliveness! 927 +-- max-wait? uint16 928 +-- max-attempts? uint8 930 Comments: 932 * The "client-identity" node, which is optionally configured (as 933 client authentication MAY occur at a higher protocol layer), 934 configures identity credentials, each enabled by a "feature" 935 statement defined in Section 3.1.1. 937 * The "server-authentication" node configures trust anchors for 938 authenticating the TLS server, with each option enabled by a 939 "feature" statement. 941 * The "hello-params" node , which must be enabled by a feature, 942 configures parameters for the TLS sessions established by this 943 configuration. 945 * The "keepalives" node, which must be enabled by a feature, 946 configures a "presence" container for testing the aliveness of the 947 TLS server. The aliveness-test occurs at the TLS protocol layer. 949 * For the referenced grouping statement(s): 951 - The "local-or-keystore-end-entity-cert-with-key-grouping" 952 grouping is discussed in Section 2.1.3.6 of 953 [I-D.ietf-netconf-keystore]. 954 - The "local-or-keystore-asymmetric-key-grouping" grouping is 955 discussed in Section 2.1.3.4 of [I-D.ietf-netconf-keystore]. 956 - The "local-or-keystore-symmetric-key-grouping" grouping is 957 discussed in Section 2.1.3.3 of [I-D.ietf-netconf-keystore]. 958 - The "local-or-truststore-certs-grouping" grouping is discussed 959 in Section 2.1.3.1 of [I-D.ietf-netconf-trust-anchors]. 960 - The "local-or-truststore-public-keys-grouping" grouping is 961 discussed in Section 2.1.3.2 of 962 [I-D.ietf-netconf-trust-anchors]. 963 - The "hello-params-grouping" grouping is discussed in 964 Section 2.1.3.1 in this document. 966 3.1.3. Protocol-accessible Nodes 968 The "ietf-tls-client" module defines only "grouping" statements that 969 are used by other modules to instantiate protocol-accessible nodes. 971 3.2. Example Usage 973 This section presents two examples showing the "tls-client-grouping" 974 grouping populated with some data. These examples are effectively 975 the same except the first configures the client identity using a 976 local key while the second uses a key configured in a keystore. Both 977 examples are consistent with the examples presented in Section 2 of 978 [I-D.ietf-netconf-trust-anchors] and Section 3.2 of 979 [I-D.ietf-netconf-keystore]. 981 The following configuration example uses local-definitions for the 982 client identity and server authentication: 984 =============== NOTE: '\' line wrapping per RFC 8792 ================ 986 987 988 992 993 994 995 996 ct:subject-public-key-info-format 998 base64encodedvalue== 999 ct:rsa-private-key-format 1001 base64encodedvalue== 1003 base64encodedvalue== 1004 1005 1006 1025 1027 1028 1029 1030 1031 1032 Server Cert Issuer #1 1033 base64encodedvalue== 1034 1035 1036 Server Cert Issuer #2 1037 base64encodedvalue== 1038 1039 1040 1041 1042 1043 1044 My Application #1 1045 base64encodedvalue== 1046 1047 1048 My Application #2 1049 base64encodedvalue== 1050 1051 1052 1053 1054 1055 1056 corp-fw1 1057 ct:subject-public-key-info-format 1059 base64encodedvalue== 1060 1061 1062 corp-fw1 1063 ct:subject-public-key-info-format 1065 base64encodedvalue== 1066 1067 1068 1069 1070 1072 1073 1074 30 1075 3 1076 1077 1079 1081 The following configuration example uses keystore-references for the 1082 client identity and truststore-references for server authentication: 1083 from the keystore: 1085 =============== NOTE: '\' line wrapping per RFC 8792 ================ 1087 1088 1089 1091 1092 1093 1094 1095 rsa-asymmetric-key 1096 ex-rsa-cert 1097 1098 1099 1108 1110 1111 1112 1113 trusted-server-ca-certs 1115 1116 1117 trusted-server-ee-certs 1119 1120 1121 Raw Public Keys for TLS Servers 1123 1124 1125 1127 1128 1129 30 1130 3 1131 1132 1134 1136 3.3. YANG Module 1138 This YANG module has normative references to 1139 [I-D.ietf-netconf-trust-anchors] and [I-D.ietf-netconf-keystore]. 1141 file "ietf-tls-client@2021-05-18.yang" 1143 module ietf-tls-client { 1144 yang-version 1.1; 1145 namespace "urn:ietf:params:xml:ns:yang:ietf-tls-client"; 1146 prefix tlsc; 1148 import ietf-netconf-acm { 1149 prefix nacm; 1150 reference 1151 "RFC 8341: Network Configuration Access Control Model"; 1152 } 1154 import ietf-crypto-types { 1155 prefix ct; 1156 reference 1157 "RFC AAAA: YANG Data Types and Groupings for Cryptography"; 1158 } 1160 import ietf-truststore { 1161 prefix ts; 1162 reference 1163 "RFC BBBB: A YANG Data Model for a Truststore"; 1164 } 1166 import ietf-keystore { 1167 prefix ks; 1168 reference 1169 "RFC CCCC: A YANG Data Model for a Keystore"; 1170 } 1172 import ietf-tls-common { 1173 prefix tlscmn; 1174 revision-date 2021-05-18; // stable grouping definitions 1175 reference 1176 "RFC FFFF: YANG Groupings for TLS Clients and TLS Servers"; 1177 } 1179 organization 1180 "IETF NETCONF (Network Configuration) Working Group"; 1182 contact 1183 "WG Web: 1184 WG List: 1185 Author: Kent Watsen 1186 Author: Gary Wu "; 1188 description 1189 "This module defines reusable groupings for TLS clients that 1190 can be used as a basis for specific TLS client instances. 1192 Copyright (c) 2021 IETF Trust and the persons identified 1193 as authors of the code. All rights reserved. 1195 Redistribution and use in source and binary forms, with 1196 or without modification, is permitted pursuant to, and 1197 subject to the license terms contained in, the Simplified 1198 BSD License set forth in Section 4.c of the IETF Trust's 1199 Legal Provisions Relating to IETF Documents 1200 (https://trustee.ietf.org/license-info). 1202 This version of this YANG module is part of RFC FFFF 1203 (https://www.rfc-editor.org/info/rfcFFFF); see the RFC 1204 itself for full legal notices. 1206 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1207 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 1208 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 1209 are to be interpreted as described in BCP 14 (RFC 2119) 1210 (RFC 8174) when, and only when, they appear in all 1211 capitals, as shown here."; 1213 revision 2021-05-18 { 1214 description 1215 "Initial version"; 1216 reference 1217 "RFC FFFF: YANG Groupings for TLS Clients and TLS Servers"; 1218 } 1220 // Features 1222 feature tls-client-hello-params-config { 1223 description 1224 "TLS hello message parameters are configurable on a TLS 1225 client."; 1226 } 1228 feature tls-client-keepalives { 1229 description 1230 "Per socket TLS keepalive parameters are configurable for 1231 TLS clients on the server implementing this feature."; 1232 } 1234 feature client-ident-x509-cert { 1235 description 1236 "Indicates that the client supports identifying itself 1237 using X.509 certificates."; 1238 } 1240 feature client-ident-raw-public-key { 1241 description 1242 "Indicates that the client supports identifying itself 1243 using raw public keys."; 1244 } 1246 feature client-ident-psk { 1247 description 1248 "Indicates that the client supports identifying itself 1249 using PSKs (pre-shared or pairwise-symmetric keys)."; 1250 } 1252 feature server-auth-x509-cert { 1253 description 1254 "Indicates that the client supports authenticating servers 1255 using X.509 certificates."; 1256 } 1258 feature server-auth-raw-public-key { 1259 description 1260 "Indicates that the client supports authenticating servers 1261 using raw public keys."; 1262 } 1264 feature server-auth-psk { 1265 description 1266 "Indicates that the client supports authenticating servers 1267 using PSKs (pre-shared or pairwise-symmetric keys)."; 1268 } 1270 // Groupings 1272 grouping tls-client-grouping { 1273 description 1274 "A reusable grouping for configuring a TLS client without 1275 any consideration for how an underlying TCP session is 1276 established. 1278 Note that this grouping uses fairly typical descendant 1279 node names such that a stack of 'uses' statements will 1280 have name conflicts. It is intended that the consuming 1281 data model will resolve the issue (e.g., by wrapping 1282 the 'uses' statement in a container called 1283 'tls-client-parameters'). This model purposely does 1284 not do this itself so as to provide maximum flexibility 1285 to consuming models."; 1287 container client-identity { 1288 nacm:default-deny-write; 1289 presence 1290 "Indicates that a TLS-level client identity has been 1291 configured. This statement is present so the mandatory 1292 descendant do not imply that this node must be configured."; 1293 description 1294 "Identity credentials the TLS client MAY present when 1295 establishing a connection to a TLS server. If not 1296 configured, then client authentication is presumed to 1297 occur a protocol layer above TLS. When configured, 1298 and requested by the TLS server when establishing a 1299 TLS session, these credentials are passed in the 1300 Certificate message defined in Section 7.4.2 of 1301 RFC 5246."; 1302 reference 1303 "RFC 5246: The Transport Layer Security (TLS) Protocol 1304 Version 1.2 1305 RFC CCCC: A YANG Data Model for a Keystore"; 1306 choice auth-type { 1307 mandatory true; 1308 description 1309 "A choice amongst available authentication types."; 1310 case certificate { 1311 if-feature "client-ident-x509-cert"; 1312 container certificate { 1313 description 1314 "Specifies the client identity using a certificate."; 1315 uses 1316 ks:local-or-keystore-end-entity-cert-with-key-grouping{ 1317 refine "local-or-keystore/local/local-definition" { 1318 must 'public-key-format' 1319 + ' = "ct:subject-public-key-info-format"'; 1320 } 1321 refine "local-or-keystore/keystore/keystore-reference" 1322 + "/asymmetric-key" { 1323 must 'deref(.)/../ks:public-key-format' 1324 + ' = "ct:subject-public-key-info-format"'; 1325 } 1327 } 1328 } 1329 } 1330 case raw-public-key { 1331 if-feature "client-ident-raw-public-key"; 1332 container raw-private-key { 1333 description 1334 "Specifies the client identity using a raw 1335 private key."; 1336 uses ks:local-or-keystore-asymmetric-key-grouping { 1337 refine "local-or-keystore/local/local-definition" { 1338 must 'public-key-format' 1339 + ' = "ct:subject-public-key-info-format"'; 1340 } 1341 refine "local-or-keystore/keystore" 1342 + "/keystore-reference" { 1343 must 'deref(.)/../ks:public-key-format' 1344 + ' = "ct:subject-public-key-info-format"'; 1345 } 1346 } 1347 } 1348 } 1349 case psk { 1350 if-feature "client-ident-psk"; 1351 container psk { 1352 description 1353 "Specifies the client identity using a PSK (pre-shared 1354 or pairwise-symmetric key)."; 1355 uses ks:local-or-keystore-symmetric-key-grouping; 1356 leaf id { 1357 type string; 1358 description 1359 "The key 'psk_identity' value used in the TLS 1360 'ClientKeyExchange' message."; 1361 reference 1362 "RFC 4279: Pre-Shared Key Ciphersuites for 1363 Transport Layer Security (TLS)"; 1364 } 1365 } 1366 } 1367 } 1368 } // container client-identity 1370 container server-authentication { 1371 nacm:default-deny-write; 1372 must 'ca-certs or ee-certs or raw-public-keys or psks'; 1373 description 1374 "Specifies how the TLS client can authenticate TLS servers. 1376 Any combination of credentials is additive and unordered. 1378 Note that no configuration is required for PSK (pre-shared 1379 or pairwise-symmetric key) based authentication as the key 1380 is necessarily the same as configured in the '../client- 1381 identity' node."; 1382 container ca-certs { 1383 if-feature "client-ident-x509-cert"; 1384 presence 1385 "Indicates that CA certificates have been configured. 1386 This statement is present so the mandatory descendant 1387 nodes do not imply that this node must be configured."; 1388 description 1389 "A set of certificate authority (CA) certificates used by 1390 the TLS client to authenticate TLS server certificates. 1391 A server certificate is authenticated if it has a valid 1392 chain of trust to a configured CA certificate."; 1393 reference 1394 "RFC BBBB: A YANG Data Model for a Truststore"; 1395 uses ts:local-or-truststore-certs-grouping; 1396 } 1397 container ee-certs { 1398 if-feature "client-ident-x509-cert"; 1399 presence 1400 "Indicates that EE certificates have been configured. 1401 This statement is present so the mandatory descendant 1402 nodes do not imply that this node must be configured."; 1403 description 1404 "A set of server certificates (i.e., end entity 1405 certificates) used by the TLS client to authenticate 1406 certificates presented by TLS servers. A server 1407 certificate is authenticated if it is an exact 1408 match to a configured server certificate."; 1409 reference 1410 "RFC BBBB: A YANG Data Model for a Truststore"; 1411 uses ts:local-or-truststore-certs-grouping; 1412 } 1413 container raw-public-keys { 1414 if-feature "client-ident-raw-public-key"; 1415 presence 1416 "Indicates that raw public keys have been configured. 1417 This statement is present so the mandatory descendant 1418 nodes do not imply that this node must be configured."; 1419 description 1420 "A set of raw public keys used by the TLS client to 1421 authenticate raw public keys presented by the TLS 1422 server. A raw public key is authenticated if it 1423 is an exact match to a configured raw public key."; 1425 reference 1426 "RFC BBBB: A YANG Data Model for a Truststore"; 1427 uses ts:local-or-truststore-public-keys-grouping { 1428 refine "local-or-truststore/local/local-definition" 1429 + "/public-key" { 1430 must 'public-key-format' 1431 + ' = "ct:subject-public-key-info-format"'; 1432 } 1433 refine "local-or-truststore/truststore" 1434 + "/truststore-reference" { 1435 must 'deref(.)/../*/ts:public-key-format' 1436 + ' = "ct:subject-public-key-info-format"'; 1437 } 1438 } 1439 } 1440 leaf psks { 1441 if-feature "client-ident-psk"; 1442 type empty; 1443 description 1444 "Indicates that the TLS client can authenticate TLS servers 1445 using configure PSKs (pre-shared or pairwise-symmetric 1446 keys). 1448 No configuration is required since the PSK value is the 1449 same as PSK value configured in the 'client-identity' 1450 node."; 1451 } 1452 } // container server-authentication 1454 container hello-params { 1455 nacm:default-deny-write; 1456 if-feature "tls-client-hello-params-config"; 1457 uses tlscmn:hello-params-grouping; 1458 description 1459 "Configurable parameters for the TLS hello message."; 1460 } // container hello-params 1462 container keepalives { 1463 nacm:default-deny-write; 1464 if-feature "tls-client-keepalives"; 1465 description 1466 "Configures the keepalive policy for the TLS client."; 1467 leaf peer-allowed-to-send { 1468 type empty; 1469 description 1470 "Indicates that the remote TLS server is allowed to send 1471 HeartbeatRequest messages, as defined by RFC 6520 1472 to this TLS client."; 1474 reference 1475 "RFC 6520: Transport Layer Security (TLS) and Datagram 1476 Transport Layer Security (DTLS) Heartbeat Extension"; 1477 } 1478 container test-peer-aliveness { 1479 presence 1480 "Indicates that the TLS client proactively tests the 1481 aliveness of the remote TLS server."; 1482 description 1483 "Configures the keep-alive policy to proactively test 1484 the aliveness of the TLS server. An unresponsive 1485 TLS server is dropped after approximately max-wait 1486 * max-attempts seconds. The TLS client MUST send 1487 HeartbeatRequest messages, as defined by RFC 6520."; 1488 reference 1489 "RFC 6520: Transport Layer Security (TLS) and Datagram 1490 Transport Layer Security (DTLS) Heartbeat Extension"; 1491 leaf max-wait { 1492 type uint16 { 1493 range "1..max"; 1494 } 1495 units "seconds"; 1496 default "30"; 1497 description 1498 "Sets the amount of time in seconds after which if 1499 no data has been received from the TLS server, a 1500 TLS-level message will be sent to test the 1501 aliveness of the TLS server."; 1502 } 1503 leaf max-attempts { 1504 type uint8; 1505 default "3"; 1506 description 1507 "Sets the maximum number of sequential keep-alive 1508 messages that can fail to obtain a response from 1509 the TLS server before assuming the TLS server is 1510 no longer alive."; 1511 } 1512 } 1513 } 1514 } // grouping tls-client-grouping 1516 } 1518 1520 4. The "ietf-tls-server" Module 1522 This section defines a YANG 1.1 module called "ietf-tls-server". A 1523 high-level overview of the module is provided in Section 4.1. 1524 Examples illustrating the module's use are provided in Examples 1525 (Section 4.2). The YANG module itself is defined in Section 4.3. 1527 4.1. Data Model Overview 1529 This section provides an overview of the "ietf-tls-server" module in 1530 terms of its features and groupings. 1532 4.1.1. Features 1534 The following diagram lists all the "feature" statements defined in 1535 the "ietf-tls-server" module: 1537 Features: 1538 +-- tls-server-hello-params-config 1539 +-- tls-server-keepalives 1540 +-- server-ident-x509-cert 1541 +-- server-ident-raw-public-key 1542 +-- server-ident-psk 1543 +-- client-auth-supported 1544 +-- client-auth-x509-cert 1545 +-- client-auth-raw-public-key 1546 +-- client-auth-psk 1548 | The diagram above uses syntax that is similar to but not 1549 | defined in [RFC8340]. 1551 4.1.2. Groupings 1553 The "ietf-tls-server" module defines the following "grouping" 1554 statement: 1556 * tls-server-grouping 1558 This grouping is presented in the following subsection. 1560 4.1.2.1. The "tls-server-grouping" Grouping 1562 The following tree diagram [RFC8340] illustrates the "tls-server- 1563 grouping" grouping: 1565 =============== NOTE: '\' line wrapping per RFC 8792 ================ 1567 grouping tls-server-grouping 1568 +-- server-identity 1569 | +-- (auth-type) 1570 | +--:(certificate) {server-ident-x509-cert}? 1571 | | +-- certificate 1572 | | +---u ks:local-or-keystore-end-entity-cert-with-key-\ 1573 grouping 1574 | +--:(raw-private-key) {server-ident-raw-public-key}? 1575 | | +-- raw-private-key 1576 | | +---u ks:local-or-keystore-asymmetric-key-grouping 1577 | +--:(psk) {server-ident-psk}? 1578 | +-- psk 1579 | +---u ks:local-or-keystore-symmetric-key-grouping 1580 | +-- id_hint? 1581 | string 1582 +-- client-authentication! {client-auth-supported}? 1583 | +-- ca-certs! {client-auth-x509-cert}? 1584 | | +---u ts:local-or-truststore-certs-grouping 1585 | +-- ee-certs! {client-auth-x509-cert}? 1586 | | +---u ts:local-or-truststore-certs-grouping 1587 | +-- raw-public-keys! {client-auth-raw-public-key}? 1588 | | +---u ts:local-or-truststore-public-keys-grouping 1589 | +-- psks? empty {client-auth-psk}? 1590 +-- hello-params {tls-server-hello-params-config}? 1591 | +---u tlscmn:hello-params-grouping 1592 +-- keepalives {tls-server-keepalives}? 1593 +-- peer-allowed-to-send? empty 1594 +-- test-peer-aliveness! 1595 +-- max-wait? uint16 1596 +-- max-attempts? uint8 1598 Comments: 1600 * The "server-identity" node configures identity credentials, each 1601 of which is enabled by a "feature". 1603 * The "client-authentication" node, which is optionally configured 1604 (as client authentication MAY occur at a higher protocol layer), 1605 configures trust anchors for authenticating the TLS client, with 1606 each option enabled by a "feature" statement. 1608 * The "hello-params" node, which must be enabled by a feature, 1609 configures parameters for the TLS sessions established by this 1610 configuration. 1612 * The "keepalives" node, which must be enabled by a feature, 1613 configures a flag enabling the TLS client to test the aliveness of 1614 the TLS server, as well as a "presence" container for testing the 1615 aliveness of the TLSi client. The aliveness-tests occurs at the 1616 TLS protocol layer. 1618 * For the referenced grouping statement(s): 1620 - The "local-or-keystore-end-entity-cert-with-key-grouping" 1621 grouping is discussed in Section 2.1.3.6 of 1622 [I-D.ietf-netconf-keystore]. 1623 - The "local-or-keystore-asymmetric-key-grouping" grouping is 1624 discussed in Section 2.1.3.4 of [I-D.ietf-netconf-keystore]. 1625 - The "local-or-keystore-symmetric-key-grouping" grouping is 1626 discussed in Section 2.1.3.3 of [I-D.ietf-netconf-keystore]. 1627 - The "local-or-truststore-public-keys-grouping" grouping is 1628 discussed in Section 2.1.3.2 of 1629 [I-D.ietf-netconf-trust-anchors]. 1630 - The "local-or-truststore-certs-grouping" grouping is discussed 1631 in Section 2.1.3.1 of [I-D.ietf-netconf-trust-anchors]. 1632 - The "hello-params-grouping" grouping is discussed in 1633 Section 2.1.3.1 in this document. 1635 4.1.3. Protocol-accessible Nodes 1637 The "ietf-tls-server" module defines only "grouping" statements that 1638 are used by other modules to instantiate protocol-accessible nodes. 1640 4.2. Example Usage 1642 This section presents two examples showing the "tls-server-grouping" 1643 grouping populated with some data. These examples are effectively 1644 the same except the first configures the server identity using a 1645 local key while the second uses a key configured in a keystore. Both 1646 examples are consistent with the examples presented in Section 2 of 1647 [I-D.ietf-netconf-trust-anchors] and Section 3.2 of 1648 [I-D.ietf-netconf-keystore]. 1650 The following configuration example uses local-definitions for the 1651 server identity and client authentication: 1653 =============== NOTE: '\' line wrapping per RFC 8792 ================ 1655 1656 1657 1660 1661 1662 1663 1664 ct:subject-public-key-info-format 1666 base64encodedvalue== 1667 ct:rsa-private-key-format 1669 base64encodedvalue== 1671 base64encodedvalue== 1672 1673 1674 1693 1695 1696 1697 1698 1699 1700 Identity Cert Issuer #1 1701 base64encodedvalue== 1702 1703 1704 Identity Cert Issuer #2 1705 base64encodedvalue== 1706 1707 1709 1710 1711 1712 1713 Application #1 1714 base64encodedvalue== 1715 1716 1717 Application #2 1718 base64encodedvalue== 1719 1720 1721 1722 1723 1724 1725 User A 1726 ct:subject-public-key-info-format 1728 base64encodedvalue== 1729 1730 1731 User B 1732 ct:subject-public-key-info-format 1734 base64encodedvalue== 1735 1736 1737 1738 1739 1741 1742 1743 1745 1747 The following configuration example uses keystore-references for the 1748 server identity and truststore-references for client authentication: 1749 from the keystore: 1751 =============== NOTE: '\' line wrapping per RFC 8792 ================ 1753 1754 1755 1757 1758 1759 1760 1761 rsa-asymmetric-key 1762 ex-rsa-cert 1763 1764 1765 1774 1776 1777 1778 1779 trusted-client-ca-certs 1781 1782 1783 trusted-client-ee-certs 1785 1786 1787 Raw Public Keys for TLS Clients 1789 1790 1791 1793 1794 1795 1797 1799 4.3. YANG Module 1801 This YANG module has a normative references to [RFC5246], 1802 [I-D.ietf-netconf-trust-anchors] and [I-D.ietf-netconf-keystore]. 1804 file "ietf-tls-server@2021-05-18.yang" 1806 module ietf-tls-server { 1807 yang-version 1.1; 1808 namespace "urn:ietf:params:xml:ns:yang:ietf-tls-server"; 1809 prefix tlss; 1811 import ietf-netconf-acm { 1812 prefix nacm; 1813 reference 1814 "RFC 8341: Network Configuration Access Control Model"; 1815 } 1817 import ietf-crypto-types { 1818 prefix ct; 1819 reference 1820 "RFC AAAA: YANG Data Types and Groupings for Cryptography"; 1821 } 1823 import ietf-truststore { 1824 prefix ts; 1825 reference 1826 "RFC BBBB: A YANG Data Model for a Truststore"; 1827 } 1829 import ietf-keystore { 1830 prefix ks; 1831 reference 1832 "RFC CCCC: A YANG Data Model for a Keystore"; 1833 } 1835 import ietf-tls-common { 1836 prefix tlscmn; 1837 revision-date 2021-05-18; // stable grouping definitions 1838 reference 1839 "RFC FFFF: YANG Groupings for TLS Clients and TLS Servers"; 1840 } 1842 organization 1843 "IETF NETCONF (Network Configuration) Working Group"; 1845 contact 1846 "WG Web: 1847 WG List: 1848 Author: Kent Watsen 1849 Author: Gary Wu "; 1851 description 1852 "This module defines reusable groupings for TLS servers that 1853 can be used as a basis for specific TLS server instances. 1855 Copyright (c) 2021 IETF Trust and the persons identified 1856 as authors of the code. All rights reserved. 1858 Redistribution and use in source and binary forms, with 1859 or without modification, is permitted pursuant to, and 1860 subject to the license terms contained in, the Simplified 1861 BSD License set forth in Section 4.c of the IETF Trust's 1862 Legal Provisions Relating to IETF Documents 1863 (https://trustee.ietf.org/license-info). 1865 This version of this YANG module is part of RFC FFFF 1866 (https://www.rfc-editor.org/info/rfcFFFF); see the RFC 1867 itself for full legal notices. 1869 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1870 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 1871 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 1872 are to be interpreted as described in BCP 14 (RFC 2119) 1873 (RFC 8174) when, and only when, they appear in all 1874 capitals, as shown here."; 1876 revision 2021-05-18 { 1877 description 1878 "Initial version"; 1879 reference 1880 "RFC FFFF: YANG Groupings for TLS Clients and TLS Servers"; 1881 } 1883 // Features 1885 feature tls-server-hello-params-config { 1886 description 1887 "TLS hello message parameters are configurable on a TLS 1888 server."; 1889 } 1891 feature tls-server-keepalives { 1892 description 1893 "Per socket TLS keepalive parameters are configurable for 1894 TLS servers on the server implementing this feature."; 1896 } 1898 feature server-ident-x509-cert { 1899 description 1900 "Indicates that the server supports identifying itself 1901 using X.509 certificates."; 1902 } 1904 feature server-ident-raw-public-key { 1905 description 1906 "Indicates that the server supports identifying itself 1907 using raw public keys."; 1908 } 1910 feature server-ident-psk { 1911 description 1912 "Indicates that the server supports identifying itself 1913 using PSKs (pre-shared or pairwise-symmetric keys)."; 1914 } 1916 feature client-auth-supported { 1917 description 1918 "Indicates that the configuration for how to authenticate 1919 clients can be configured herein. TLS-level client 1920 authentication may not be needed when client authentication 1921 is expected to occur only at another protocol layer."; 1922 } 1924 feature client-auth-x509-cert { 1925 description 1926 "Indicates that the server supports authenticating clients 1927 using X.509 certificates."; 1928 } 1930 feature client-auth-raw-public-key { 1931 description 1932 "Indicates that the server supports authenticating clients 1933 using raw public keys."; 1934 } 1936 feature client-auth-psk { 1937 description 1938 "Indicates that the server supports authenticating clients 1939 using PSKs (pre-shared or pairwise-symmetric keys)."; 1940 } 1942 // Groupings 1943 grouping tls-server-grouping { 1944 description 1945 "A reusable grouping for configuring a TLS server without 1946 any consideration for how underlying TCP sessions are 1947 established. 1949 Note that this grouping uses fairly typical descendant 1950 node names such that a stack of 'uses' statements will 1951 have name conflicts. It is intended that the consuming 1952 data model will resolve the issue (e.g., by wrapping 1953 the 'uses' statement in a container called 1954 'tls-server-parameters'). This model purposely does 1955 not do this itself so as to provide maximum flexibility 1956 to consuming models."; 1958 container server-identity { 1959 nacm:default-deny-write; 1960 description 1961 "A locally-defined or referenced end-entity certificate, 1962 including any configured intermediate certificates, the 1963 TLS server will present when establishing a TLS connection 1964 in its Certificate message, as defined in Section 7.4.2 1965 in RFC 5246."; 1966 reference 1967 "RFC 5246: The Transport Layer Security (TLS) Protocol 1968 Version 1.2 1969 RFC CCCC: A YANG Data Model for a Keystore"; 1970 choice auth-type { 1971 mandatory true; 1972 description 1973 "A choice amongst authentication types."; 1974 case certificate { 1975 if-feature "server-ident-x509-cert"; 1976 container certificate { 1977 description 1978 "Specifies the server identity using a certificate."; 1979 uses 1980 ks:local-or-keystore-end-entity-cert-with-key-grouping{ 1981 refine "local-or-keystore/local/local-definition" { 1982 must 'public-key-format' 1983 + ' = "ct:subject-public-key-info-format"'; 1984 } 1985 refine "local-or-keystore/keystore/keystore-reference" 1986 + "/asymmetric-key" { 1987 must 'deref(.)/../ks:public-key-format' 1988 + ' = "ct:subject-public-key-info-format"'; 1989 } 1990 } 1992 } 1993 } 1994 case raw-private-key { 1995 if-feature "server-ident-raw-public-key"; 1996 container raw-private-key { 1997 description 1998 "Specifies the server identity using a raw 1999 private key."; 2000 uses ks:local-or-keystore-asymmetric-key-grouping { 2001 refine "local-or-keystore/local/local-definition" { 2002 must 'public-key-format' 2003 + ' = "ct:subject-public-key-info-format"'; 2004 } 2005 refine "local-or-keystore/keystore/keystore-reference"{ 2006 must 'deref(.)/../ks:public-key-format' 2007 + ' = "ct:subject-public-key-info-format"'; 2008 } 2009 } 2010 } 2011 } 2012 case psk { 2013 if-feature "server-ident-psk"; 2014 container psk { 2015 description 2016 "Specifies the server identity using a PSK (pre-shared 2017 or pairwise-symmetric key)."; 2018 uses ks:local-or-keystore-symmetric-key-grouping; 2019 leaf id_hint { 2020 type string; 2021 description 2022 "The key 'psk_identity_hint' value used in the TLS 2023 'ServerKeyExchange' message."; 2024 reference 2025 "RFC 4279: Pre-Shared Key Ciphersuites for 2026 Transport Layer Security (TLS)"; 2027 } 2028 } 2029 } 2030 } 2031 } // container server-identity 2033 container client-authentication { 2034 if-feature "client-auth-supported"; 2035 nacm:default-deny-write; 2036 must 'ca-certs or ee-certs or raw-public-keys or psks'; 2037 presence 2038 "Indicates that client authentication is supported (i.e., 2039 that the server will request clients send certificates). 2041 If not configured, the TLS server SHOULD NOT request the 2042 TLS clients provide authentication credentials."; 2043 description 2044 "Specifies how the TLS server can authenticate TLS clients. 2045 Any combination of credentials is additive and unordered. 2047 Note that no configuration is required for PSK (pre-shared 2048 or pairwise-symmetric key) based authentication as the key 2049 is necessarily the same as configured in the '../server- 2050 identity' node."; 2051 container ca-certs { 2052 if-feature "client-auth-x509-cert"; 2053 presence 2054 "Indicates that CA certificates have been configured. 2055 This statement is present so the mandatory descendant 2056 nodes do not imply that this node must be configured."; 2057 description 2058 "A set of certificate authority (CA) certificates used by 2059 the TLS server to authenticate TLS client certificates. 2060 A client certificate is authenticated if it has a valid 2061 chain of trust to a configured CA certificate."; 2062 reference 2063 "RFC BBBB: A YANG Data Model for a Truststore"; 2064 uses ts:local-or-truststore-certs-grouping; 2065 } 2066 container ee-certs { 2067 if-feature "client-auth-x509-cert"; 2068 presence 2069 "Indicates that EE certificates have been configured. 2070 This statement is present so the mandatory descendant 2071 nodes do not imply that this node must be configured."; 2072 description 2073 "A set of client certificates (i.e., end entity 2074 certificates) used by the TLS server to authenticate 2075 certificates presented by TLS clients. A client 2076 certificate is authenticated if it is an exact 2077 match to a configured client certificate."; 2078 reference 2079 "RFC BBBB: A YANG Data Model for a Truststore"; 2080 uses ts:local-or-truststore-certs-grouping; 2081 } 2082 container raw-public-keys { 2083 if-feature "client-auth-raw-public-key"; 2084 presence 2085 "Indicates that raw public keys have been configured. 2086 This statement is present so the mandatory descendant 2087 nodes do not imply that this node must be configured."; 2088 description 2089 "A set of raw public keys used by the TLS server to 2090 authenticate raw public keys presented by the TLS 2091 client. A raw public key is authenticated if it 2092 is an exact match to a configured raw public key."; 2093 reference 2094 "RFC BBBB: A YANG Data Model for a Truststore"; 2095 uses ts:local-or-truststore-public-keys-grouping { 2096 refine "local-or-truststore/local/local-definition" 2097 + "/public-key" { 2098 must 'public-key-format' 2099 + ' = "ct:subject-public-key-info-format"'; 2100 } 2101 refine "local-or-truststore/truststore" 2102 + "/truststore-reference" { 2103 must 'deref(.)/../*/ts:public-key-format' 2104 + ' = "ct:subject-public-key-info-format"'; 2105 } 2106 } 2107 } 2108 leaf psks { 2109 if-feature "client-auth-psk"; 2110 type empty; 2111 description 2112 "Indicates that the TLS server can authenticate TLS clients 2113 using configured PSKs (pre-shared or pairwise-symmetric 2114 keys). 2116 No configuration is required since the PSK value is the 2117 same as PSK value configured in the 'server-identity' 2118 node."; 2119 } 2120 } // container client-authentication 2122 container hello-params { 2123 nacm:default-deny-write; 2124 if-feature "tls-server-hello-params-config"; 2125 uses tlscmn:hello-params-grouping; 2126 description 2127 "Configurable parameters for the TLS hello message."; 2128 } // container hello-params 2130 container keepalives { 2131 nacm:default-deny-write; 2132 if-feature "tls-server-keepalives"; 2133 description 2134 "Configures the keepalive policy for the TLS server."; 2135 leaf peer-allowed-to-send { 2136 type empty; 2137 description 2138 "Indicates that the remote TLS client is allowed to send 2139 HeartbeatRequest messages, as defined by RFC 6520 2140 to this TLS server."; 2141 reference 2142 "RFC 6520: Transport Layer Security (TLS) and Datagram 2143 Transport Layer Security (DTLS) Heartbeat Extension"; 2144 } 2145 container test-peer-aliveness { 2146 presence 2147 "Indicates that the TLS server proactively tests the 2148 aliveness of the remote TLS client."; 2149 description 2150 "Configures the keep-alive policy to proactively test 2151 the aliveness of the TLS client. An unresponsive 2152 TLS client is dropped after approximately max-wait 2153 * max-attempts seconds."; 2154 leaf max-wait { 2155 type uint16 { 2156 range "1..max"; 2157 } 2158 units "seconds"; 2159 default "30"; 2160 description 2161 "Sets the amount of time in seconds after which if 2162 no data has been received from the TLS client, a 2163 TLS-level message will be sent to test the 2164 aliveness of the TLS client."; 2165 } 2166 leaf max-attempts { 2167 type uint8; 2168 default "3"; 2169 description 2170 "Sets the maximum number of sequential keep-alive 2171 messages that can fail to obtain a response from 2172 the TLS client before assuming the TLS client is 2173 no longer alive."; 2174 } 2175 } 2176 } // container keepalives 2177 } // grouping tls-server-grouping 2179 } 2181 2183 5. Security Considerations 2184 5.1. The "ietf-tls-common" YANG Module 2186 The "ietf-tls-common" YANG module defines "grouping" statements that 2187 are designed to be accessed via YANG based management protocols, such 2188 as NETCONF [RFC6241] and RESTCONF [RFC8040]. Both of these protocols 2189 have mandatory-to-implement secure transport layers (e.g., SSH, TLS) 2190 with mutual authentication. 2192 The NETCONF access control model (NACM) [RFC8341] provides the means 2193 to restrict access for particular users to a pre-configured subset of 2194 all available protocol operations and content. 2196 Since the module in this document only define groupings, these 2197 considerations are primarily for the designers of other modules that 2198 use these groupings. 2200 None of the readable data nodes defined in this YANG module are 2201 considered sensitive or vulnerable in network environments. The NACM 2202 "default-deny-all" extension has not been set for any data nodes 2203 defined in this module. 2205 None of the writable data nodes defined in this YANG module are 2206 considered sensitive or vulnerable in network environments. The NACM 2207 "default-deny-write" extension has not been set for any data nodes 2208 defined in this module. 2210 This module does not define any RPCs, actions, or notifications, and 2211 thus the security consideration for such is not provided here. 2213 5.2. The "ietf-tls-client" YANG Module 2215 The "ietf-tls-client" YANG module defines "grouping" statements that 2216 are designed to be accessed via YANG based management protocols, such 2217 as NETCONF [RFC6241] and RESTCONF [RFC8040]. Both of these protocols 2218 have mandatory-to-implement secure transport layers (e.g., SSH, TLS) 2219 with mutual authentication. 2221 The NETCONF access control model (NACM) [RFC8341] provides the means 2222 to restrict access for particular users to a pre-configured subset of 2223 all available protocol operations and content. 2225 Since the module in this document only define groupings, these 2226 considerations are primarily for the designers of other modules that 2227 use these groupings. 2229 None of the readable data nodes defined in this YANG module are 2230 considered sensitive or vulnerable in network environments. The NACM 2231 "default-deny-all" extension has not been set for any data nodes 2232 defined in this module. 2234 | Please be aware that this module uses the "key" and "private- 2235 | key" nodes from the "ietf-crypto-types" module 2236 | [I-D.ietf-netconf-crypto-types], where said nodes have the NACM 2237 | extension "default-deny-all" set, thus preventing unrestricted 2238 | read-access to the cleartext key values. 2240 All of the writable data nodes defined by this module may be 2241 considered sensitive or vulnerable in some network environments. For 2242 instance, any modification to a key or reference to a key may 2243 dramatically alter the implemented security policy. For this reason, 2244 the NACM extension "default-deny-write" has been set for all data 2245 nodes defined in this module. 2247 This module does not define any RPCs, actions, or notifications, and 2248 thus the security consideration for such is not provided here. 2250 5.3. The "ietf-tls-server" YANG Module 2252 The "ietf-tls-server" YANG module defines "grouping" statements that 2253 are designed to be accessed via YANG based management protocols, such 2254 as NETCONF [RFC6241] and RESTCONF [RFC8040]. Both of these protocols 2255 have mandatory-to-implement secure transport layers (e.g., SSH, TLS) 2256 with mutual authentication. 2258 The NETCONF access control model (NACM) [RFC8341] provides the means 2259 to restrict access for particular users to a pre-configured subset of 2260 all available protocol operations and content. 2262 Since the module in this document only define groupings, these 2263 considerations are primarily for the designers of other modules that 2264 use these groupings. 2266 None of the readable data nodes defined in this YANG module are 2267 considered sensitive or vulnerable in network environments. The NACM 2268 "default-deny-all" extension has not been set for any data nodes 2269 defined in this module. 2271 | Please be aware that this module uses the "key" and "private- 2272 | key" nodes from the "ietf-crypto-types" module 2273 | [I-D.ietf-netconf-crypto-types], where said nodes have the NACM 2274 | extension "default-deny-all" set, thus preventing unrestricted 2275 | read-access to the cleartext key values. 2277 All of the writable data nodes defined by this module may be 2278 considered sensitive or vulnerable in some network environments. For 2279 instance, any modification to a key or reference to a key may 2280 dramatically alter the implemented security policy. For this reason, 2281 the NACM extension "default-deny-write" has been set for all data 2282 nodes defined in this module. 2284 This module does not define any RPCs, actions, or notifications, and 2285 thus the security consideration for such is not provided here. 2287 6. IANA Considerations 2289 6.1. The "IETF XML" Registry 2291 This document registers three URIs in the "ns" subregistry of the 2292 IETF XML Registry [RFC3688]. Following the format in [RFC3688], the 2293 following registrations are requested: 2295 URI: urn:ietf:params:xml:ns:yang:ietf-tls-common 2296 Registrant Contact: The IESG 2297 XML: N/A, the requested URI is an XML namespace. 2299 URI: urn:ietf:params:xml:ns:yang:ietf-tls-client 2300 Registrant Contact: The IESG 2301 XML: N/A, the requested URI is an XML namespace. 2303 URI: urn:ietf:params:xml:ns:yang:ietf-tls-server 2304 Registrant Contact: The IESG 2305 XML: N/A, the requested URI is an XML namespace. 2307 6.2. The "YANG Module Names" Registry 2309 This document registers three YANG modules in the YANG Module Names 2310 registry [RFC6020]. Following the format in [RFC6020], the following 2311 registrations are requested: 2313 name: ietf-tls-common 2314 namespace: urn:ietf:params:xml:ns:yang:ietf-tls-common 2315 prefix: tlscmn 2316 reference: RFC FFFF 2318 name: ietf-tls-client 2319 namespace: urn:ietf:params:xml:ns:yang:ietf-tls-client 2320 prefix: tlsc 2321 reference: RFC FFFF 2323 name: ietf-tls-server 2324 namespace: urn:ietf:params:xml:ns:yang:ietf-tls-server 2325 prefix: tlss 2326 reference: RFC FFFF 2328 7. References 2330 7.1. Normative References 2332 [I-D.ietf-netconf-crypto-types] 2333 Watsen, K., "YANG Data Types and Groupings for 2334 Cryptography", Work in Progress, Internet-Draft, draft- 2335 ietf-netconf-crypto-types-19, 10 February 2021, 2336 . 2339 [I-D.ietf-netconf-keystore] 2340 Watsen, K., "A YANG Data Model for a Keystore", Work in 2341 Progress, Internet-Draft, draft-ietf-netconf-keystore-21, 2342 10 February 2021, . 2345 [I-D.ietf-netconf-trust-anchors] 2346 Watsen, K., "A YANG Data Model for a Truststore", Work in 2347 Progress, Internet-Draft, draft-ietf-netconf-trust- 2348 anchors-14, 10 February 2021, 2349 . 2352 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2353 Requirement Levels", BCP 14, RFC 2119, 2354 DOI 10.17487/RFC2119, March 1997, 2355 . 2357 [RFC5288] Salowey, J., Choudhury, A., and D. McGrew, "AES Galois 2358 Counter Mode (GCM) Cipher Suites for TLS", RFC 5288, 2359 DOI 10.17487/RFC5288, August 2008, 2360 . 2362 [RFC5289] Rescorla, E., "TLS Elliptic Curve Cipher Suites with SHA- 2363 256/384 and AES Galois Counter Mode (GCM)", RFC 5289, 2364 DOI 10.17487/RFC5289, August 2008, 2365 . 2367 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 2368 the Network Configuration Protocol (NETCONF)", RFC 6020, 2369 DOI 10.17487/RFC6020, October 2010, 2370 . 2372 [RFC7589] Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the 2373 NETCONF Protocol over Transport Layer Security (TLS) with 2374 Mutual X.509 Authentication", RFC 7589, 2375 DOI 10.17487/RFC7589, June 2015, 2376 . 2378 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2379 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2380 . 2382 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2383 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2384 May 2017, . 2386 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 2387 Access Control Model", STD 91, RFC 8341, 2388 DOI 10.17487/RFC8341, March 2018, 2389 . 2391 [RFC8422] Nir, Y., Josefsson, S., and M. Pegourie-Gonnard, "Elliptic 2392 Curve Cryptography (ECC) Cipher Suites for Transport Layer 2393 Security (TLS) Versions 1.2 and Earlier", RFC 8422, 2394 DOI 10.17487/RFC8422, August 2018, 2395 . 2397 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 2398 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 2399 . 2401 7.2. Informative References 2403 [I-D.ietf-netconf-http-client-server] 2404 Watsen, K., "YANG Groupings for HTTP Clients and HTTP 2405 Servers", Work in Progress, Internet-Draft, draft-ietf- 2406 netconf-http-client-server-06, 10 February 2021, 2407 . 2410 [I-D.ietf-netconf-netconf-client-server] 2411 Watsen, K., "NETCONF Client and Server Models", Work in 2412 Progress, Internet-Draft, draft-ietf-netconf-netconf- 2413 client-server-22, 10 February 2021, 2414 . 2417 [I-D.ietf-netconf-restconf-client-server] 2418 Watsen, K., "RESTCONF Client and Server Models", Work in 2419 Progress, Internet-Draft, draft-ietf-netconf-restconf- 2420 client-server-22, 10 February 2021, 2421 . 2424 [I-D.ietf-netconf-ssh-client-server] 2425 Watsen, K., "YANG Groupings for SSH Clients and SSH 2426 Servers", Work in Progress, Internet-Draft, draft-ietf- 2427 netconf-ssh-client-server-23, 10 February 2021, 2428 . 2431 [I-D.ietf-netconf-tcp-client-server] 2432 Watsen, K. and M. Scharf, "YANG Groupings for TCP Clients 2433 and TCP Servers", Work in Progress, Internet-Draft, draft- 2434 ietf-netconf-tcp-client-server-09, 10 February 2021, 2435 . 2438 [I-D.ietf-netconf-tls-client-server] 2439 Watsen, K., "YANG Groupings for TLS Clients and TLS 2440 Servers", Work in Progress, Internet-Draft, draft-ietf- 2441 netconf-tls-client-server-23, 10 February 2021, 2442 . 2445 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 2446 RFC 2246, DOI 10.17487/RFC2246, January 1999, 2447 . 2449 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 2450 DOI 10.17487/RFC2818, May 2000, 2451 . 2453 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2454 DOI 10.17487/RFC3688, January 2004, 2455 . 2457 [RFC4346] Dierks, T. and E. Rescorla, "The Transport Layer Security 2458 (TLS) Protocol Version 1.1", RFC 4346, 2459 DOI 10.17487/RFC4346, April 2006, 2460 . 2462 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2463 (TLS) Protocol Version 1.2", RFC 5246, 2464 DOI 10.17487/RFC5246, August 2008, 2465 . 2467 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2468 and A. Bierman, Ed., "Network Configuration Protocol 2469 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2470 . 2472 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2473 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2474 . 2476 [RFC8071] Watsen, K., "NETCONF Call Home and RESTCONF Call Home", 2477 RFC 8071, DOI 10.17487/RFC8071, February 2017, 2478 . 2480 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 2481 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 2482 . 2484 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 2485 and R. Wilton, "Network Management Datastore Architecture 2486 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 2487 . 2489 Appendix A. Change Log 2491 This section is to be removed before publishing as an RFC. 2493 A.1. 00 to 01 2495 * Noted that '0.0.0.0' and '::' might have special meanings. 2497 * Renamed "keychain" to "keystore". 2499 A.2. 01 to 02 2501 * Removed the groupings containing transport-level configuration. 2502 Now modules contain only the transport-independent groupings. 2504 * Filled in previously incomplete 'ietf-tls-client' module. 2506 * Added cipher suites for various algorithms into new 'ietf-tls- 2507 common' module. 2509 A.3. 02 to 03 2511 * Added a 'must' statement to container 'server-auth' asserting that 2512 at least one of the various auth mechanisms must be specified. 2514 * Fixed description statement for leaf 'trusted-ca-certs'. 2516 A.4. 03 to 04 2518 * Updated title to "YANG Groupings for TLS Clients and TLS Servers" 2520 * Updated leafref paths to point to new keystore path 2522 * Changed the YANG prefix for ietf-tls-common from 'tlscom' to 2523 'tlscmn'. 2525 * Added TLS protocol verions 1.0 and 1.1. 2527 * Made author lists consistent 2529 * Now tree diagrams reference ietf-netmod-yang-tree-diagrams 2531 * Updated YANG to use typedefs around leafrefs to common keystore 2532 paths 2534 * Now inlines key and certificates (no longer a leafref to keystore) 2536 A.5. 04 to 05 2538 * Merged changes from co-author. 2540 A.6. 05 to 06 2542 * Updated to use trust anchors from trust-anchors draft (was 2543 keystore draft) 2545 * Now Uses new keystore grouping enabling asymmetric key to be 2546 either locally defined or a reference to the keystore. 2548 A.7. 06 to 07 2550 * factored the tls-[client|server]-groupings into more reusable 2551 groupings. 2553 * added if-feature statements for the new "x509-certificates" 2554 feature defined in draft-ietf-netconf-trust-anchors. 2556 A.8. 07 to 08 2558 * Added a number of compatibility matrices to Section 5 (thanks 2559 Frank!) 2561 * Clarified that any configured "cipher-suite" values need to be 2562 compatible with the configured private key. 2564 A.9. 08 to 09 2566 * Updated examples to reflect update to groupings defined in the 2567 keystore draft. 2569 * Add TLS keepalives features and groupings. 2571 * Prefixed top-level TLS grouping nodes with 'tls-' and support 2572 mashups. 2574 * Updated copyright date, boilerplate template, affiliation, and 2575 folding algorithm. 2577 A.10. 09 to 10 2579 * Reformatted the YANG modules. 2581 A.11. 10 to 11 2583 * Collapsed all the inner groupings into the top-level grouping. 2585 * Added a top-level "demux container" inside the top-level grouping. 2587 * Added NACM statements and updated the Security Considerations 2588 section. 2590 * Added "presence" statements on the "keepalive" containers, as was 2591 needed to address a validation error that appeared after adding 2592 the "must" statements into the NETCONF/RESTCONF client/server 2593 modules. 2595 * Updated the boilerplate text in module-level "description" 2596 statement to match copyeditor convention. 2598 A.12. 11 to 12 2599 * In server model, made 'client-authentication' a 'presence' node 2600 indicating that the server supports client authentication. 2602 * In the server model, added a 'required-or-optional' choice to 2603 'client-authentication' to better support protocols such as 2604 RESTCONF. 2606 * In the server model, added a 'local-or-external' choice to 2607 'client-authentication' to better support consuming data models 2608 that prefer to keep client auth with client definitions than in a 2609 model principally concerned with the "transport". 2611 * In both models, removed the "demux containers", floating the 2612 nacm:default-deny-write to each descendent node, and adding a note 2613 to model designers regarding the potential need to add their own 2614 demux containers. 2616 * Fixed a couple references (section 2 --> section 3) 2618 A.13. 12 to 13 2620 * Updated to reflect changes in trust-anchors drafts (e.g., s/trust- 2621 anchors/truststore/g + s/pinned.//) 2623 A.14. 12 to 13 2625 * Removed 'container' under 'client-identity' to match server model. 2627 * Updated examples to reflect change grouping in keystore module. 2629 A.15. 13 to 14 2631 * Removed the "certificate" container from "client-identity" in the 2632 ietf-tls-client module. 2634 * Updated examples to reflect ietf-crypto-types change (e.g., 2635 identities --> enumerations) 2637 A.16. 14 to 15 2639 * Updated "server-authentication" and "client-authentication" nodes 2640 from being a leaf of type "ts:certificates-ref" to a container 2641 that uses "ts:local-or-truststore-certs-grouping". 2643 A.17. 15 to 16 2645 * Removed unnecessary if-feature statements in the -client and 2646 -server modules. 2648 * Cleaned up some description statements in the -client and -server 2649 modules. 2651 * Fixed a canonical ordering issue in ietf-tls-common detected by 2652 new pyang. 2654 A.18. 16 to 17 2656 * Removed choice local-or-external by removing the 'external' case 2657 and flattening the 'local' case and adding a "client-auth- 2658 supported" feature. 2660 * Removed choice required-or-optional. 2662 * Updated examples to include the "*-key-format" nodes. 2664 * Augmented-in "must" expressions ensuring that locally-defined 2665 public-key-format are "ct:ssh-public-key-format" (must expr for 2666 ref'ed keys are TBD). 2668 A.19. 17 to 18 2670 * Removed the unused "external-client-auth-supported" feature. 2672 * Made client-indentity optional, as there may be over-the-top auth 2673 instead. 2675 * Added augment to uses of local-or-keystore-symmetric-key-grouping 2676 for a psk "id" node. 2678 * Added missing presence container "psks" to ietf-tls-server's 2679 "client-authentication" container. 2681 * Updated examples to reflect new "bag" addition to truststore. 2683 * Removed feature-limited caseless 'case' statements to improve tree 2684 diagram rendering. 2686 * Refined truststore/keystore groupings to ensure the key formats 2687 "must" be particular values. 2689 * Switched to using truststore's new "public-key" bag (instead of 2690 separate "ssh-public-key" and "raw-public-key" bags. 2692 * Updated client/server examples to cover ALL cases (local/ref x 2693 cert/raw-key/psk). 2695 A.20. 18 to 19 2697 * Updated the "keepalives" containers in part to address Michal 2698 Vasko's request to align with RFC 8071, and in part to better 2699 align to RFC 6520. 2701 * Removed algorithm-mapping tables from the "TLS Common Model" 2702 section 2704 * Removed the 'algorithm' node from the examples. 2706 * Renamed both "client-certs" and "server-certs" to "ee-certs" 2708 * Added a "Note to Reviewers" note to first page. 2710 A.21. 19 to 20 2712 * Modified the 'must' expression in the "ietf-tls-client:server- 2713 authention" node to cover the "raw-public-keys" and "psks" nodes 2714 also. 2716 * Added a "must 'ca-certs or ee-certs or raw-public-keys or psks'" 2717 statement to the ietf-tls-server:client-authentication" node. 2719 * Added "mandatory true" to "choice auth-type" and a "presence" 2720 statement to its ancestor. 2722 * Expanded "Data Model Overview section(s) [remove "wall" of tree 2723 diagrams]. 2725 * Moved the "ietf-ssh-common" module section to proceed the other 2726 two module sections. 2728 * Updated the Security Considerations section. 2730 A.22. 20 to 21 2732 * Updated examples to reflect new "cleartext-" prefix in the crypto- 2733 types draft. 2735 A.23. 21 to 22 2737 * In both the "client-authentication" and "server-authentication" 2738 subtrees, replaced the "psks" node from being a P-container to a 2739 leaf of type "empty". 2741 * Cleaned up examples (e.g., removed FIXMEs) 2742 * Fixed issues found by the SecDir review of the "keystore" draft. 2744 * Updated the "psk" sections in the "ietf-tls-client" and "ietf-tls- 2745 server" modules to more correctly reflect RFC 4279. 2747 A.24. 22 to 23 2749 * Addressed comments raised by YANG Doctor in the ct/ts/ks drafts. 2751 A.25. 23 to 24 2753 * Added missing reference to "FIPS PUB 180-4". 2755 * Added identity "tls-1.3" and updated description statement in 2756 other identities indicating that the protocol version is obsolete 2757 and enabling the feature is NOT RECOMMENDED. 2759 * Added XML-comment above examples explaining the reason for the 2760 unexpected top-most element's presence. 2762 * Added missing "client-ident-raw-public-key" and "client-ident-psk" 2763 featutes. 2765 * Aligned modules with `pyang -f` formatting. 2767 * Fixed nits found by YANG Doctor reviews. 2769 * Added a 'Contributors' section. 2771 Acknowledgements 2773 The authors would like to thank for following for lively discussions 2774 on list and in the halls (ordered by first name): Alan Luchuk, Andy 2775 Bierman, Balazs Kovacs, Benoit Claise, Bert Wijnen, David Lamparter, 2776 Dhruv Dhody, Gary Wu, Henk Birkholz, Juergen Schoenwaelder, Ladislav 2777 Lhotka, Liang Xia, Martin Bjoerklund, Mehmet Ersue, Michal Vasko, 2778 Phil Shafer, Radek Krejci, Sean Turner, and Tom Petch. 2780 Contributors 2782 Special acknowledgement goes to Gary Wu who contributed the "ietf- 2783 tls-common" module. 2785 Author's Address 2787 Kent Watsen 2788 Watsen Networks 2789 Email: kent+ietf@watsen.net