idnits 2.17.1 draft-ietf-netconf-tls-client-server-21.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 July 2020) is 1379 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-15 == Outdated reference: A later version (-35) exists of draft-ietf-netconf-keystore-17 == Outdated reference: A later version (-28) exists of draft-ietf-netconf-trust-anchors-10 == Outdated reference: A later version (-20) exists of draft-ietf-netconf-http-client-server-03 == Outdated reference: A later version (-36) exists of draft-ietf-netconf-netconf-client-server-19 == Outdated reference: A later version (-36) exists of draft-ietf-netconf-restconf-client-server-19 == Outdated reference: A later version (-40) exists of draft-ietf-netconf-ssh-client-server-19 == Outdated reference: A later version (-26) exists of draft-ietf-netconf-tcp-client-server-06 == Outdated reference: A later version (-41) exists of draft-ietf-netconf-tls-client-server-19 -- 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 G. Wu 5 Expires: 11 January 2021 Cisco Systems 6 10 July 2020 8 YANG Groupings for TLS Clients and TLS Servers 9 draft-ietf-netconf-tls-client-server-21 11 Abstract 13 This document defines three YANG modules: the first defines groupings 14 for a generic TLS client, the second defines groupings for a generic 15 TLS server, and the third defines common identities and groupings 16 used by both the client and the server. It is intended that these 17 groupings will be used by applications using the TLS protocol. 19 Editorial Note (To be removed by RFC Editor) 21 This draft contains placeholder values that need to be replaced with 22 finalized values at the time of publication. This note summarizes 23 all of the substitutions that are needed. No other RFC Editor 24 instructions are specified elsewhere in this document. 26 Artwork in this document contains shorthand references to drafts in 27 progress. Please apply the following replacements: 29 * "AAAA" --> the assigned RFC value for draft-ietf-netconf-crypto- 30 types 32 * "BBBB" --> the assigned RFC value for draft-ietf-netconf-trust- 33 anchors 35 * "CCCC" --> the assigned RFC value for draft-ietf-netconf-keystore 37 * "DDDD" --> the assigned RFC value for draft-ietf-netconf-tcp- 38 client-server 40 * "FFFF" --> the assigned RFC value for this draft 42 Artwork in this document contains placeholder values for the date of 43 publication of this draft. Please apply the following replacement: 45 * "2020-07-10" --> the publication date of this draft 47 The following Appendix section is to be removed prior to publication: 49 * Appendix A. Change Log 51 Status of This Memo 53 This Internet-Draft is submitted in full conformance with the 54 provisions of BCP 78 and BCP 79. 56 Internet-Drafts are working documents of the Internet Engineering 57 Task Force (IETF). Note that other groups may also distribute 58 working documents as Internet-Drafts. The list of current Internet- 59 Drafts is at https://datatracker.ietf.org/drafts/current/. 61 Internet-Drafts are draft documents valid for a maximum of six months 62 and may be updated, replaced, or obsoleted by other documents at any 63 time. It is inappropriate to use Internet-Drafts as reference 64 material or to cite them other than as "work in progress." 66 This Internet-Draft will expire on 11 January 2021. 68 Copyright Notice 70 Copyright (c) 2020 IETF Trust and the persons identified as the 71 document authors. All rights reserved. 73 This document is subject to BCP 78 and the IETF Trust's Legal 74 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 75 license-info) in effect on the date of publication of this document. 76 Please review these documents carefully, as they describe your rights 77 and restrictions with respect to this document. Code Components 78 extracted from this document must include Simplified BSD License text 79 as described in Section 4.e of the Trust Legal Provisions and are 80 provided without warranty as described in the Simplified BSD License. 82 Table of Contents 84 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 85 1.1. Relation to other RFCs . . . . . . . . . . . . . . . . . 4 86 1.2. Specification Language . . . . . . . . . . . . . . . . . 6 87 1.3. Adherence to the NMDA . . . . . . . . . . . . . . . . . . 6 88 2. The "ietf-tls-common" Module . . . . . . . . . . . . . . . . 6 89 2.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 7 90 2.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 9 91 2.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 10 92 3. The "ietf-tls-client" Module . . . . . . . . . . . . . . . . 19 93 3.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 19 94 3.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 21 95 3.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 24 96 4. The "ietf-tls-server" Module . . . . . . . . . . . . . . . . 32 97 4.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 32 98 4.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 35 99 4.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 39 100 5. Security Considerations . . . . . . . . . . . . . . . . . . . 46 101 5.1. The "ietf-tls-common" YANG Module . . . . . . . . . . . . 46 102 5.2. The "ietf-tls-client" YANG Module . . . . . . . . . . . . 47 103 5.3. The "ietf-tls-server" YANG Module . . . . . . . . . . . . 48 104 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 49 105 6.1. The "IETF XML" Registry . . . . . . . . . . . . . . . . . 49 106 6.2. The "YANG Module Names" Registry . . . . . . . . . . . . 49 107 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 49 108 7.1. Normative References . . . . . . . . . . . . . . . . . . 49 109 7.2. Informative References . . . . . . . . . . . . . . . . . 51 110 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 53 111 A.1. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 53 112 A.2. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 53 113 A.3. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 53 114 A.4. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 53 115 A.5. 04 to 05 . . . . . . . . . . . . . . . . . . . . . . . . 54 116 A.6. 05 to 06 . . . . . . . . . . . . . . . . . . . . . . . . 54 117 A.7. 06 to 07 . . . . . . . . . . . . . . . . . . . . . . . . 54 118 A.8. 07 to 08 . . . . . . . . . . . . . . . . . . . . . . . . 54 119 A.9. 08 to 09 . . . . . . . . . . . . . . . . . . . . . . . . 54 120 A.10. 09 to 10 . . . . . . . . . . . . . . . . . . . . . . . . 55 121 A.11. 10 to 11 . . . . . . . . . . . . . . . . . . . . . . . . 55 122 A.12. 11 to 12 . . . . . . . . . . . . . . . . . . . . . . . . 55 123 A.13. 12 to 13 . . . . . . . . . . . . . . . . . . . . . . . . 55 124 A.14. 12 to 13 . . . . . . . . . . . . . . . . . . . . . . . . 56 125 A.15. 13 to 14 . . . . . . . . . . . . . . . . . . . . . . . . 56 126 A.16. 14 to 15 . . . . . . . . . . . . . . . . . . . . . . . . 56 127 A.17. 15 to 16 . . . . . . . . . . . . . . . . . . . . . . . . 56 128 A.18. 16 to 17 . . . . . . . . . . . . . . . . . . . . . . . . 56 129 A.19. 17 to 18 . . . . . . . . . . . . . . . . . . . . . . . . 57 130 A.20. 18 to 19 . . . . . . . . . . . . . . . . . . . . . . . . 57 131 A.21. 19 to 20 . . . . . . . . . . . . . . . . . . . . . . . . 57 132 A.22. 20 to 21 . . . . . . . . . . . . . . . . . . . . . . . . 58 133 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 58 134 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 58 136 1. Introduction 138 This document defines three YANG 1.1 [RFC7950] modules: the first 139 defines a grouping for a generic TLS client, the second defines a 140 grouping for a generic TLS server, and the third defines identities 141 and groupings common to both the client and the server (TLS is 142 defined in [RFC5246]). It is intended that these groupings will be 143 used by applications using the TLS protocol. For instance, these 144 groupings could be used to help define the data model for an HTTPS 145 [RFC2818] server or a NETCONF over TLS [RFC7589] based server. 147 The client and server YANG modules in this document each define one 148 grouping, which is focused on just TLS-specific configuration, and 149 specifically avoids any transport-level configuration, such as what 150 ports to listen-on or connect-to. This affords applications the 151 opportunity to define their own strategy for how the underlying TCP 152 connection is established. For instance, applications supporting 153 NETCONF Call Home [RFC8071] could use the "ssh-server-grouping" 154 grouping for the TLS parts it provides, while adding data nodes for 155 the TCP-level call-home configuration. 157 1.1. Relation to other RFCs 159 This document presents one or more YANG modules [RFC7950] that are 160 part of a collection of RFCs that work together to define 161 configuration modules for clients and servers of both the NETCONF 162 [RFC6241] and RESTCONF [RFC8040] protocols. 164 The modules have been defined in a modular fashion to enable their 165 use by other efforts, some of which are known to be in progress at 166 the time of this writing, with many more expected to be defined in 167 time. 169 The relationship between the various RFCs in the collection is 170 presented in the below diagram. The labels in the diagram represent 171 the primary purpose provided by each RFC. Links the each RFC are 172 provided below the diagram. 174 crypto-types 175 ^ ^ 176 / \ 177 / \ 178 truststore keystore 179 ^ ^ ^ ^ 180 | +---------+ | | 181 | | | | 182 | +------------+ | 183 tcp-client-server | / | | 184 ^ ^ ssh-client-server | | 185 | | ^ tls-client-server 186 | | | ^ ^ http-client-server 187 | | | | | ^ 188 | | | +-----+ +---------+ | 189 | | | | | | 190 | +-----------|--------|--------------+ | | 191 | | | | | | 192 +-----------+ | | | | | 193 | | | | | | 194 | | | | | | 195 netconf-client-server restconf-client-server 197 +=======================+===========================================+ 198 | Label in Diagram | Originating RFC | 199 +=======================+===========================================+ 200 | crypto-types | [I-D.ietf-netconf-crypto-types] | 201 +-----------------------+-------------------------------------------+ 202 | truststore | [I-D.ietf-netconf-trust-anchors] | 203 +-----------------------+-------------------------------------------+ 204 | keystore | [I-D.ietf-netconf-keystore] | 205 +-----------------------+-------------------------------------------+ 206 | tcp-client-server | [I-D.ietf-netconf-tcp-client-server] | 207 +-----------------------+-------------------------------------------+ 208 | ssh-client-server | [I-D.ietf-netconf-ssh-client-server] | 209 +-----------------------+-------------------------------------------+ 210 | tls-client-server | [I-D.ietf-netconf-tls-client-server] | 211 +-----------------------+-------------------------------------------+ 212 | http-client-server | [I-D.ietf-netconf-http-client-server] | 213 +-----------------------+-------------------------------------------+ 214 | netconf-client-server | [I-D.ietf-netconf-netconf-client-server] | 215 +-----------------------+-------------------------------------------+ 216 |restconf-client-server | [I-D.ietf-netconf-restconf-client-server] | 217 +-----------------------+-------------------------------------------+ 219 Table 1: Label to RFC Mapping 221 1.2. Specification Language 223 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 224 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 225 "OPTIONAL" in this document are to be interpreted as described in BCP 226 14 [RFC2119] [RFC8174] when, and only when, they appear in all 227 capitals, as shown here. 229 1.3. Adherence to the NMDA 231 This document in compliant with the Network Management Datastore 232 Architecture (NMDA) [RFC8342]. For instance, as described in 233 [I-D.ietf-netconf-trust-anchors] and [I-D.ietf-netconf-keystore], 234 trust anchors and keys installed during manufacturing are expected to 235 appear in . 237 2. The "ietf-tls-common" Module 239 The TLS common model presented in this section contains identities 240 and groupings common to both TLS clients and TLS servers. The 241 "hello-params-grouping" grouping can be used to configure the list of 242 TLS algorithms permitted by the TLS client or TLS server. The lists 243 of algorithms are ordered such that, if multiple algorithms are 244 permitted by the client, the algorithm that appears first in its list 245 that is also permitted by the server is used for the TLS transport 246 layer connection. The ability to restrict the algorithms allowed is 247 provided in this grouping for TLS clients and TLS servers that are 248 capable of doing so and may serve to make TLS clients and TLS servers 249 compliant with local security policies. This model supports both 250 TLS1.2 [RFC5246] and TLS 1.3 [RFC8446]. 252 TLS 1.2 and TLS 1.3 have different ways defining their own supported 253 cryptographic algorithms, see TLS and DTLS IANA registries page 254 (https://www.iana.org/assignments/tls-parameters/tls- 255 parameters.xhtml): 257 * TLS 1.2 defines four categories of registries for cryptographic 258 algorithms: TLS Cipher Suites, TLS SignatureAlgorithm, TLS 259 HashAlgorithm, TLS Supported Groups. TLS Cipher Suites plays the 260 role of combining all of them into one set, as each value of the 261 set represents a unique and feasible combination of all the 262 cryptographic algorithms, and thus the other three registry 263 categories do not need to be considered here. In this document, 264 the TLS common model only chooses those TLS1.2 algorithms in TLS 265 Cipher Suites which are marked as recommended: 266 TLS_DHE_RSA_WITH_AES_128_GCM_SHA256, 267 TLS_DHE_RSA_WITH_AES_256_GCM_SHA384, 268 TLS_DHE_PSK_WITH_AES_128_GCM_SHA256, 269 TLS_DHE_PSK_WITH_AES_256_GCM_SHA384, and so on. All chosen 270 algorithms are enumerated in Table 1-1 below; 272 * TLS 1.3 defines its supported algorithms differently. Firstly, it 273 defines three categories of registries for cryptographic 274 algorithms: TLS Cipher Suites, TLS SignatureScheme, TLS Supported 275 Groups. Secondly, all three of these categories are useful, since 276 they represent different parts of all the supported algorithms 277 respectively. Thus, all of these registries categories are 278 considered here. In this draft, the TLS common model chooses only 279 those TLS1.3 algorithms specified in B.4, 4.2.3, 4.2.7 of 280 [RFC8446]. 282 Thus, in order to support both TLS1.2 and TLS1.3, the cipher-suites 283 part of the "hello-params-grouping" grouping should include three 284 parameters for configuring its permitted TLS algorithms, which are: 285 TLS Cipher Suites, TLS SignatureScheme, TLS Supported Groups. Note 286 that TLS1.2 only uses TLS Cipher Suites. 288 Features are defined for algorithms that are OPTIONAL or are not 289 widely supported by popular implementations. Note that the list of 290 algorithms is not exhaustive. 292 2.1. Data Model Overview 294 2.1.1. Features 296 The following diagram lists all the "feature" statements defined in 297 the "ietf-tls-common" module: 299 Features: 300 +-- tls-1_0 301 +-- tls-1_1 302 +-- tls-1_2 303 +-- tls-1_3 304 +-- tls-ecc 305 +-- tls-dhe 306 +-- tls-3des 307 +-- tls-gcm 308 +-- tls-sha2 310 2.1.2. Identities 312 The following diagram illustrates the relationship amongst the 313 "identity" statements defined in the "ietf-tls-common" module: 315 Identities: 316 +-- tls-version-base 317 | +-- tls-1.0 318 | +-- tls-1.1 319 | +-- tls-1.2 320 +-- cipher-suite-base 321 +-- rsa-with-aes-128-cbc-sha 322 +-- rsa-with-aes-256-cbc-sha 323 +-- rsa-with-aes-128-cbc-sha256 324 +-- rsa-with-aes-256-cbc-sha256 325 +-- dhe-rsa-with-aes-128-cbc-sha 326 +-- dhe-rsa-with-aes-256-cbc-sha 327 +-- dhe-rsa-with-aes-128-cbc-sha256 328 +-- dhe-rsa-with-aes-256-cbc-sha256 329 +-- ecdhe-ecdsa-with-aes-128-cbc-sha256 330 +-- ecdhe-ecdsa-with-aes-256-cbc-sha384 331 +-- ecdhe-rsa-with-aes-128-cbc-sha256 332 +-- ecdhe-rsa-with-aes-256-cbc-sha384 333 +-- ecdhe-ecdsa-with-aes-128-gcm-sha256 334 +-- ecdhe-ecdsa-with-aes-256-gcm-sha384 335 +-- ecdhe-rsa-with-aes-128-gcm-sha256 336 +-- ecdhe-rsa-with-aes-256-gcm-sha384 337 +-- rsa-with-3des-ede-cbc-sha 338 +-- ecdhe-rsa-with-3des-ede-cbc-sha 339 +-- ecdhe-rsa-with-aes-128-cbc-sha 340 +-- ecdhe-rsa-with-aes-256-cbc-sha 342 Comments: 344 * The diagram shows that there are two base identities. 345 * One base identity is used to specific TLS versions, while the 346 other is used to specify cipher-suites. 348 * These base identities are "abstract", in the object orientied 349 programming sense, in that they only define a "class" of things, 350 rather than a specific thing. 352 2.1.3. Groupings 354 The following diagram lists all the "grouping" statements defined in 355 the "ietf-tls-common" module: 357 Groupings: 358 +-- hello-params-grouping 360 Each of these groupings are presented in the following subsections. 362 2.1.3.1. The "hello-params-grouping" Grouping 364 The following tree diagram [RFC8340] illustrates the "hello-params- 365 grouping" grouping: 367 grouping hello-params-grouping 368 +-- tls-versions 369 | +-- tls-version* identityref 370 +-- cipher-suites 371 +-- cipher-suite* identityref 373 Comments: 375 * This grouping is used by both the "tls-client-grouping" and the 376 "tls-server-grouping" groupings defined in Section 3.1.2.1 and 377 Section 4.1.2.1, respectively. 379 * This grouping enables client and server configurations to specify 380 the TLS versions and cipher suites that are to be used when 381 establishing TLS sessions. 383 * The "cipher-suites" list is "ordered-by user". 385 2.1.4. Protocol-accessible Nodes 387 The "ietf-tls-common" module does not contain any protocol-accessible 388 nodes, but the module needs to be "implemented", as described in 389 Section 5.6.5 of [RFC7950], in order for the identities in 390 Section 2.1.2 to be defined. 392 2.2. Example Usage 394 This section shows how it would appear if the "hello-params-grouping" 395 grouping were populated with some data. 397 400 401 tlscmn:tls-1.1 402 tlscmn:tls-1.2 403 404 405 tlscmn:dhe-rsa-with-aes-128-cbc-sha 406 tlscmn:rsa-with-aes-128-cbc-sha 407 tlscmn:rsa-with-3des-ede-cbc-sha 408 409 411 2.3. YANG Module 413 This YANG module has a normative references to [RFC4346], [RFC5246], 414 [RFC5288], [RFC5289], and [RFC8422]. 416 This YANG module has a informative references to [RFC2246], 417 [RFC4346], [RFC5246], and [RFC8446]. 419 file "ietf-tls-common@2020-07-10.yang" 421 module ietf-tls-common { 422 yang-version 1.1; 423 namespace "urn:ietf:params:xml:ns:yang:ietf-tls-common"; 424 prefix tlscmn; 426 organization 427 "IETF NETCONF (Network Configuration) Working Group"; 429 contact 430 "WG Web: 431 WG List: 432 Author: Kent Watsen 433 Author: Gary Wu "; 435 description 436 "This module defines a common features, identities, and 437 groupings for Transport Layer Security (TLS). 439 Copyright (c) 2020 IETF Trust and the persons identified 440 as authors of the code. All rights reserved. 442 Redistribution and use in source and binary forms, with 443 or without modification, is permitted pursuant to, and 444 subject to the license terms contained in, the Simplified 445 BSD License set forth in Section 4.c of the IETF Trust's 446 Legal Provisions Relating to IETF Documents 447 (https://trustee.ietf.org/license-info). 449 This version of this YANG module is part of RFC FFFF 450 (https://www.rfc-editor.org/info/rfcFFFF); see the RFC 451 itself for full legal notices. 453 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 454 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 455 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 456 are to be interpreted as described in BCP 14 (RFC 2119) 457 (RFC 8174) when, and only when, they appear in all 458 capitals, as shown here."; 460 revision 2020-07-10 { 461 description 462 "Initial version"; 463 reference 464 "RFC FFFF: YANG Groupings for TLS Clients and TLS Servers"; 465 } 467 // Features 469 feature tls-1_0 { 470 description 471 "TLS Protocol Version 1.0 is supported."; 472 reference 473 "RFC 2246: The TLS Protocol Version 1.0"; 474 } 476 feature tls-1_1 { 477 description 478 "TLS Protocol Version 1.1 is supported."; 479 reference 480 "RFC 4346: The Transport Layer Security (TLS) Protocol 481 Version 1.1"; 482 } 484 feature tls-1_2 { 485 description 486 "TLS Protocol Version 1.2 is supported."; 487 reference 488 "RFC 5246: The Transport Layer Security (TLS) Protocol 489 Version 1.2"; 490 } 492 feature tls-1_3 { 493 description 494 "TLS Protocol Version 1.2 is supported."; 495 reference 496 "RFC 8446: The Transport Layer Security (TLS) Protocol 497 Version 1.3"; 498 } 500 feature tls-ecc { 501 description 502 "Elliptic Curve Cryptography (ECC) is supported for TLS."; 503 reference 504 "RFC 8422: Elliptic Curve Cryptography (ECC) Cipher Suites 505 for Transport Layer Security (TLS)"; 506 } 508 feature tls-dhe { 509 description 510 "Ephemeral Diffie-Hellman key exchange is supported for TLS."; 511 reference 512 "RFC 5246: The Transport Layer Security (TLS) Protocol 513 Version 1.2"; 514 } 516 feature tls-3des { 517 description 518 "The Triple-DES block cipher is supported for TLS."; 519 reference 520 "RFC 5246: The Transport Layer Security (TLS) Protocol 521 Version 1.2"; 522 } 524 feature tls-gcm { 525 description 526 "The Galois/Counter Mode authenticated encryption mode is 527 supported for TLS."; 528 reference 529 "RFC 5288: AES Galois Counter Mode (GCM) Cipher Suites for 530 TLS"; 531 } 533 feature tls-sha2 { 534 description 535 "The SHA2 family of cryptographic hash functions is supported 536 for TLS."; 537 reference 538 "FIPS PUB 180-4: Secure Hash Standard (SHS)"; 539 } 540 // Identities 542 identity tls-version-base { 543 description 544 "Base identity used to identify TLS protocol versions."; 545 } 547 identity tls-1.0 { 548 if-feature "tls-1_0"; 549 base tls-version-base; 550 description 551 "TLS Protocol Version 1.0."; 552 reference 553 "RFC 2246: The TLS Protocol Version 1.0"; 554 } 556 identity tls-1.1 { 557 if-feature "tls-1_1"; 558 base tls-version-base; 559 description 560 "TLS Protocol Version 1.1."; 561 reference 562 "RFC 4346: The Transport Layer Security (TLS) Protocol 563 Version 1.1"; 564 } 566 identity tls-1.2 { 567 if-feature "tls-1_2"; 568 base tls-version-base; 569 description 570 "TLS Protocol Version 1.2."; 571 reference 572 "RFC 5246: The Transport Layer Security (TLS) Protocol 573 Version 1.2"; 574 } 576 identity cipher-suite-base { 577 description 578 "Base identity used to identify TLS cipher suites."; 579 } 581 identity rsa-with-aes-128-cbc-sha { 582 base cipher-suite-base; 583 description 584 "Cipher suite TLS_RSA_WITH_AES_128_CBC_SHA."; 585 reference 586 "RFC 5246: The Transport Layer Security (TLS) Protocol 587 Version 1.2"; 589 } 591 identity rsa-with-aes-256-cbc-sha { 592 base cipher-suite-base; 593 description 594 "Cipher suite TLS_RSA_WITH_AES_256_CBC_SHA."; 595 reference 596 "RFC 5246: The Transport Layer Security (TLS) Protocol 597 Version 1.2"; 598 } 600 identity rsa-with-aes-128-cbc-sha256 { 601 if-feature "tls-sha2"; 602 base cipher-suite-base; 603 description 604 "Cipher suite TLS_RSA_WITH_AES_128_CBC_SHA256."; 605 reference 606 "RFC 5246: The Transport Layer Security (TLS) Protocol 607 Version 1.2"; 608 } 610 identity rsa-with-aes-256-cbc-sha256 { 611 if-feature "tls-sha2"; 612 base cipher-suite-base; 613 description 614 "Cipher suite TLS_RSA_WITH_AES_256_CBC_SHA256."; 615 reference 616 "RFC 5246: The Transport Layer Security (TLS) Protocol 617 Version 1.2"; 618 } 620 identity dhe-rsa-with-aes-128-cbc-sha { 621 if-feature "tls-dhe"; 622 base cipher-suite-base; 623 description 624 "Cipher suite TLS_DHE_RSA_WITH_AES_128_CBC_SHA."; 625 reference 626 "RFC 5246: The Transport Layer Security (TLS) Protocol 627 Version 1.2"; 628 } 630 identity dhe-rsa-with-aes-256-cbc-sha { 631 if-feature "tls-dhe"; 632 base cipher-suite-base; 633 description 634 "Cipher suite TLS_DHE_RSA_WITH_AES_256_CBC_SHA."; 635 reference 636 "RFC 5246: The Transport Layer Security (TLS) Protocol 637 Version 1.2"; 638 } 640 identity dhe-rsa-with-aes-128-cbc-sha256 { 641 if-feature "tls-dhe and tls-sha2"; 642 base cipher-suite-base; 643 description 644 "Cipher suite TLS_DHE_RSA_WITH_AES_128_CBC_SHA256."; 645 reference 646 "RFC 5246: The Transport Layer Security (TLS) Protocol 647 Version 1.2"; 648 } 650 identity dhe-rsa-with-aes-256-cbc-sha256 { 651 if-feature "tls-dhe and tls-sha2"; 652 base cipher-suite-base; 653 description 654 "Cipher suite TLS_DHE_RSA_WITH_AES_256_CBC_SHA256."; 655 reference 656 "RFC 5246: The Transport Layer Security (TLS) Protocol 657 Version 1.2"; 658 } 660 identity ecdhe-ecdsa-with-aes-128-cbc-sha256 { 661 if-feature "tls-ecc and tls-sha2"; 662 base cipher-suite-base; 663 description 664 "Cipher suite TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256."; 665 reference 666 "RFC 5289: TLS Elliptic Curve Cipher Suites with 667 SHA-256/384 and AES Galois Counter Mode (GCM)"; 668 } 670 identity ecdhe-ecdsa-with-aes-256-cbc-sha384 { 671 if-feature "tls-ecc and tls-sha2"; 672 base cipher-suite-base; 673 description 674 "Cipher suite TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384."; 675 reference 676 "RFC 5289: TLS Elliptic Curve Cipher Suites with 677 SHA-256/384 and AES Galois Counter Mode (GCM)"; 678 } 680 identity ecdhe-rsa-with-aes-128-cbc-sha256 { 681 if-feature "tls-ecc and tls-sha2"; 682 base cipher-suite-base; 683 description 684 "Cipher suite TLS_ECDHE_RSA_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)"; 689 } 691 identity ecdhe-rsa-with-aes-256-cbc-sha384 { 692 if-feature "tls-ecc and tls-sha2"; 693 base cipher-suite-base; 694 description 695 "Cipher suite TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384."; 696 reference 697 "RFC 5289: TLS Elliptic Curve Cipher Suites with 698 SHA-256/384 and AES Galois Counter Mode (GCM)"; 699 } 701 identity ecdhe-ecdsa-with-aes-128-gcm-sha256 { 702 if-feature "tls-ecc and tls-gcm and tls-sha2"; 703 base cipher-suite-base; 704 description 705 "Cipher suite TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256."; 706 reference 707 "RFC 5289: TLS Elliptic Curve Cipher Suites with 708 SHA-256/384 and AES Galois Counter Mode (GCM)"; 709 } 711 identity ecdhe-ecdsa-with-aes-256-gcm-sha384 { 712 if-feature "tls-ecc and tls-gcm and tls-sha2"; 713 base cipher-suite-base; 714 description 715 "Cipher suite TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384."; 716 reference 717 "RFC 5289: TLS Elliptic Curve Cipher Suites with 718 SHA-256/384 and AES Galois Counter Mode (GCM)"; 719 } 721 identity ecdhe-rsa-with-aes-128-gcm-sha256 { 722 if-feature "tls-ecc and tls-gcm and tls-sha2"; 723 base cipher-suite-base; 724 description 725 "Cipher suite TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256."; 726 reference 727 "RFC 5289: TLS Elliptic Curve Cipher Suites with 728 SHA-256/384 and AES Galois Counter Mode (GCM)"; 729 } 731 identity ecdhe-rsa-with-aes-256-gcm-sha384 { 732 if-feature "tls-ecc and tls-gcm and tls-sha2"; 733 base cipher-suite-base; 734 description 735 "Cipher suite TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384."; 736 reference 737 "RFC 5289: TLS Elliptic Curve Cipher Suites with 738 SHA-256/384 and AES Galois Counter Mode (GCM)"; 739 } 741 identity rsa-with-3des-ede-cbc-sha { 742 if-feature "tls-3des"; 743 base cipher-suite-base; 744 description 745 "Cipher suite TLS_RSA_WITH_3DES_EDE_CBC_SHA."; 746 reference 747 "RFC 5246: The Transport Layer Security (TLS) Protocol 748 Version 1.2"; 749 } 751 identity ecdhe-rsa-with-3des-ede-cbc-sha { 752 if-feature "tls-ecc and tls-3des"; 753 base cipher-suite-base; 754 description 755 "Cipher suite TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA."; 756 reference 757 "RFC 8422: Elliptic Curve Cryptography (ECC) Cipher Suites 758 for Transport Layer Security (TLS)"; 759 } 761 identity ecdhe-rsa-with-aes-128-cbc-sha { 762 if-feature "tls-ecc"; 763 base cipher-suite-base; 764 description 765 "Cipher suite TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA."; 766 reference 767 "RFC 8422: Elliptic Curve Cryptography (ECC) Cipher Suites 768 for Transport Layer Security (TLS)"; 769 } 771 identity ecdhe-rsa-with-aes-256-cbc-sha { 772 if-feature "tls-ecc"; 773 base cipher-suite-base; 774 description 775 "Cipher suite TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA."; 776 reference 777 "RFC 8422: Elliptic Curve Cryptography (ECC) Cipher Suites 778 for Transport Layer Security (TLS)"; 779 } 781 // Groupings 782 grouping hello-params-grouping { 783 description 784 "A reusable grouping for TLS hello message parameters."; 785 reference 786 "RFC 5246: The Transport Layer Security (TLS) Protocol 787 Version 1.2"; 788 container tls-versions { 789 description 790 "Parameters regarding TLS versions."; 791 leaf-list tls-version { 792 type identityref { 793 base tls-version-base; 794 } 795 description 796 "Acceptable TLS protocol versions. 798 If this leaf-list is not configured (has zero elements) 799 the acceptable TLS protocol versions are implementation- 800 defined."; 801 } 802 } 803 container cipher-suites { 804 description 805 "Parameters regarding cipher suites."; 806 leaf-list cipher-suite { 807 type identityref { 808 base cipher-suite-base; 809 } 810 ordered-by user; 811 description 812 "Acceptable cipher suites in order of descending 813 preference. The configured host key algorithms should 814 be compatible with the algorithm used by the configured 815 private key. Please see Section 5 of RFC FFFF for 816 valid combinations. 818 If this leaf-list is not configured (has zero elements) 819 the acceptable cipher suites are implementation- 820 defined."; 821 reference 822 "RFC FFFF: YANG Groupings for TLS Clients and TLS Servers"; 823 } 824 } 825 } 826 } 828 830 3. The "ietf-tls-client" Module 832 3.1. Data Model Overview 834 3.1.1. Features 836 The following diagram lists all the "feature" statements defined in 837 the "ietf-tls-client" module: 839 Features: 840 +-- tls-client-hello-params-config 841 +-- tls-client-keepalives 842 +-- x509-certificate-auth 843 +-- raw-public-key-auth 844 +-- psk-auth 846 3.1.2. Groupings 848 The following diagram lists all the "grouping" statements defined in 849 the "ietf-tls-client" module: 851 Groupings: 852 +-- tls-client-grouping 854 Each of these groupings are presented in the following subsections. 856 3.1.2.1. The "tls-client-grouping" Grouping 858 The following tree diagram [RFC8340] illustrates the "tls-client- 859 grouping" grouping: 861 =============== NOTE: '\' line wrapping per RFC 8792 ================ 863 grouping tls-client-grouping 864 +-- client-identity! 865 | +-- (auth-type) 866 | +--:(certificate) {x509-certificate-auth}? 867 | | +-- certificate 868 | | +---u ks:local-or-keystore-end-entity-cert-with-key-\ 869 grouping 870 | +--:(raw-public-key) {raw-public-key-auth}? 871 | | +-- raw-private-key 872 | | +---u ks:local-or-keystore-asymmetric-key-grouping 873 | +--:(psk) {psk-auth}? 874 | +-- psk 875 | +---u ks:local-or-keystore-symmetric-key-grouping 876 +-- server-authentication 877 | +-- ca-certs! {x509-certificate-auth}? 878 | | +---u ts:local-or-truststore-certs-grouping 879 | +-- ee-certs! {x509-certificate-auth}? 880 | | +---u ts:local-or-truststore-certs-grouping 881 | +-- raw-public-keys! {raw-public-key-auth}? 882 | | +---u ts:local-or-truststore-public-keys-grouping 883 | +-- psks! {psk-auth}? 884 +-- hello-params {tls-client-hello-params-config}? 885 | +---u tlscmn:hello-params-grouping 886 +-- keepalives {tls-client-keepalives}? 887 +-- peer-allowed-to-send? empty 888 +-- test-peer-aliveness! 889 +-- max-wait? uint16 890 +-- max-attempts? uint8 892 Comments: 894 * The "client-identity" node, which is optionally configured (as 895 client authentication MAY occur at a higher protocol layer), 896 configures identity credentials, each enabled by a "feature" 897 statement defined in Section 3.1.1. 899 * The "server-authentication" node configures trust anchors for 900 authenticating the TLS server, with each option enabled by a 901 "feature" statement. 903 * The "hello-params" node , which must be enabled by a feature, 904 configures parameters for the TLS sessions established by this 905 configuration. 907 * The "keepalives" node, which must be enabled by a feature, 908 configures a "presence" container for testing the aliveness of the 909 TLS server. The aliveness-test occurs at the TLS protocol layer. 911 * For the referenced grouping statement(s): 913 - The "local-or-keystore-end-entity-cert-with-key-grouping" 914 grouping is discussed in Section 2.1.3.6 of 915 [I-D.ietf-netconf-keystore]. 916 - The "local-or-keystore-asymmetric-key-grouping" grouping is 917 discussed in Section 2.1.3.4 of [I-D.ietf-netconf-keystore]. 918 - The "local-or-keystore-symmetric-key-grouping" grouping is 919 discussed in Section 2.1.3.3 of [I-D.ietf-netconf-keystore]. 920 - The "local-or-truststore-certs-grouping" grouping is discussed 921 in Section 2.1.3.1 of [I-D.ietf-netconf-trust-anchors]. 922 - The "local-or-truststore-public-keys-grouping" grouping is 923 discussed in Section 2.1.3.2 of 924 [I-D.ietf-netconf-trust-anchors]. 925 - The "hello-params-grouping" grouping is discussed in 926 Section 2.1.3.1 in this document. 928 3.1.3. Protocol-accessible Nodes 930 The "ietf-tls-client" module does not contain any protocol-accessible 931 nodes. 933 3.2. Example Usage 935 This section presents two examples showing the "tls-client-grouping" 936 grouping populated with some data. These examples are effectively 937 the same except the first configures the client identity using a 938 local key while the second uses a key configured in a keystore. Both 939 examples are consistent with the examples presented in Section 2 of 940 [I-D.ietf-netconf-trust-anchors] and Section 3.2 of 941 [I-D.ietf-netconf-keystore]. 943 The following configuration example uses local-definitions for the 944 client identity and server authentication: 946 =============== NOTE: '\' line wrapping per RFC 8792 ================ 948 952 953 954 955 956 ct:subject-public-key-info-format 958 base64encodedvalue== 959 ct:rsa-private-key-format 961 base64encodedvalue== 963 base64encodedvalue== 964 965 966 985 987 988 989 990 991 992 Server Cert Issuer #1 993 base64encodedvalue== 994 995 996 Server Cert Issuer #2 997 base64encodedvalue== 998 999 1000 1001 1002 1003 1004 My Application #1 1005 base64encodedvalue== 1006 1007 1008 My Application #2 1009 base64encodedvalue== 1010 1011 1012 1013 1014 1015 1016 corp-fw1 1017 ct:subject-public-key-info-format 1019 base64encodedvalue== 1020 1021 1022 corp-fw1 1023 ct:subject-public-key-info-format 1025 base64encodedvalue== 1026 1027 1028 1029 1030 1032 1033 1034 30 1035 3 1036 1037 1039 1041 The following configuration example uses keystore-references for the 1042 client identity and truststore-references for server authentication: 1043 from the keystore: 1045 =============== NOTE: '\' line wrapping per RFC 8792 ================ 1047 1049 1050 1051 1052 1053 rsa-asymmetric-key 1054 ex-rsa-cert 1055 1056 1057 1066 1068 1069 1070 1071 trusted-server-ca-certs 1073 1074 1075 trusted-server-ee-certs 1077 1078 1079 Raw Public Keys for TLS Servers 1081 1082 1083 1085 1086 1087 30 1088 3 1089 1090 1092 1094 3.3. YANG Module 1096 This YANG module has normative references to 1097 [I-D.ietf-netconf-trust-anchors] and [I-D.ietf-netconf-keystore]. 1099 file "ietf-tls-client@2020-07-10.yang" 1101 module ietf-tls-client { 1102 yang-version 1.1; 1103 namespace "urn:ietf:params:xml:ns:yang:ietf-tls-client"; 1104 prefix tlsc; 1106 import ietf-netconf-acm { 1107 prefix nacm; 1108 reference 1109 "RFC 8341: Network Configuration Access Control Model"; 1110 } 1112 import ietf-crypto-types { 1113 prefix ct; 1114 reference 1115 "RFC AAAA: YANG Data Types and Groupings for Cryptography"; 1116 } 1118 import ietf-truststore { 1119 prefix ts; 1120 reference 1121 "RFC BBBB: A YANG Data Model for a Truststore"; 1122 } 1124 import ietf-keystore { 1125 prefix ks; 1126 reference 1127 "RFC CCCC: A YANG Data Model for a Keystore"; 1128 } 1130 import ietf-tls-common { 1131 prefix tlscmn; 1132 revision-date 2020-07-10; // stable grouping definitions 1133 reference 1134 "RFC FFFF: YANG Groupings for TLS Clients and TLS Servers"; 1135 } 1137 organization 1138 "IETF NETCONF (Network Configuration) Working Group"; 1140 contact 1141 "WG Web: 1142 WG List: 1143 Author: Kent Watsen 1144 Author: Gary Wu "; 1146 description 1147 "This module defines reusable groupings for TLS clients that 1148 can be used as a basis for specific TLS client instances. 1150 Copyright (c) 2020 IETF Trust and the persons identified 1151 as authors of the code. All rights reserved. 1153 Redistribution and use in source and binary forms, with 1154 or without modification, is permitted pursuant to, and 1155 subject to the license terms contained in, the Simplified 1156 BSD License set forth in Section 4.c of the IETF Trust's 1157 Legal Provisions Relating to IETF Documents 1158 (https://trustee.ietf.org/license-info). 1160 This version of this YANG module is part of RFC FFFF 1161 (https://www.rfc-editor.org/info/rfcFFFF); see the RFC 1162 itself for full legal notices. 1164 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1165 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 1166 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 1167 are to be interpreted as described in BCP 14 (RFC 2119) 1168 (RFC 8174) when, and only when, they appear in all 1169 capitals, as shown here."; 1171 revision 2020-07-10 { 1172 description 1173 "Initial version"; 1174 reference 1175 "RFC FFFF: YANG Groupings for TLS Clients and TLS Servers"; 1176 } 1178 // Features 1180 feature tls-client-hello-params-config { 1181 description 1182 "TLS hello message parameters are configurable on a TLS 1183 client."; 1184 } 1186 feature tls-client-keepalives { 1187 description 1188 "Per socket TLS keepalive parameters are configurable for 1189 TLS clients on the server implementing this feature."; 1190 } 1192 feature x509-certificate-auth { 1193 description 1194 "Indicates that the client supports authenticating servers 1195 using X.509 certificates."; 1196 } 1198 feature raw-public-key-auth { 1199 description 1200 "Indicates that the client supports authenticating servers 1201 using ray public keys."; 1202 } 1204 feature psk-auth { 1205 description 1206 "Indicates that the client supports authenticating servers 1207 using PSKs (pre-shared or pairwise-symmetric keys)."; 1208 } 1210 // Groupings 1212 grouping tls-client-grouping { 1213 description 1214 "A reusable grouping for configuring a TLS client without 1215 any consideration for how an underlying TCP session is 1216 established. 1218 Note that this grouping uses fairly typical descendent 1219 node names such that a stack of 'uses' statements will 1220 have name conflicts. It is intended that the consuming 1221 data model will resolve the issue (e.g., by wrapping 1222 the 'uses' statement in a container called 1223 'tls-client-parameters'). This model purposely does 1224 not do this itself so as to provide maximum flexibility 1225 to consuming models."; 1227 container client-identity { 1228 nacm:default-deny-write; 1229 presence 1230 "Indicates that TLS-level client authentication 1231 is sent. Present so that the 'choice' node's 1232 mandatory true doesn't imply that a client 1233 identity must be configured."; 1234 description 1235 "Identity credentials the TLS client MAY present when 1236 establishing a connection to a TLS server. If not 1237 configured, then client authentication is presumed to 1238 occur a protocol layer above TLS. When configured, 1239 and requested by the TLS server when establishing a 1240 TLS session, these credentials are passed in the 1241 Certificate message defined in Section 7.4.2 of 1242 RFC 5246."; 1243 reference 1244 "RFC 5246: The Transport Layer Security (TLS) Protocol 1245 Version 1.2 1246 RFC CCCC: A YANG Data Model for a Keystore"; 1247 choice auth-type { 1248 mandatory true; 1249 description 1250 "A choice amongst available authentication types."; 1251 /* FIXME: delete now? 1252 Not mandatory as client identity MAY be provided 1253 by another layer in the protocol stack (e.g., an 1254 HTTP authentication mechanism).";*/ 1255 case certificate { 1256 if-feature x509-certificate-auth; 1257 container certificate { 1258 description 1259 "Specifies the client identity using a certificate."; 1260 uses 1261 ks:local-or-keystore-end-entity-cert-with-key-grouping{ 1262 refine "local-or-keystore/local/local-definition" { 1263 must 'public-key-format' 1264 + ' = "ct:subject-public-key-info-format"'; 1265 } 1266 refine "local-or-keystore/keystore/keystore-reference" 1267 + "/asymmetric-key" { 1268 must 'deref(.)/../ks:public-key-format' 1269 + ' = "ct:subject-public-key-info-format"'; 1270 } 1271 } 1272 } 1273 } 1274 case raw-public-key { 1275 if-feature raw-public-key-auth; 1276 container raw-private-key { 1277 description 1278 "Specifies the client identity using a raw 1279 private key."; 1280 uses ks:local-or-keystore-asymmetric-key-grouping { 1281 refine "local-or-keystore/local/local-definition" { 1282 must 'public-key-format' 1283 + ' = "ct:subject-public-key-info-format"'; 1284 } 1285 refine "local-or-keystore/keystore" 1286 + "/keystore-reference" { 1287 must 'deref(.)/../ks:public-key-format' 1288 + ' = "ct:subject-public-key-info-format"'; 1290 } 1291 } 1292 } 1293 } 1294 case psk { 1295 if-feature psk-auth; 1296 container psk { 1297 description 1298 "Specifies the client identity using a PSK (pre-shared 1299 or pairwise-symmetric key). Note that, when the PSK is 1300 configured as a Keystore reference, the key's 'name' 1301 node MAY be used as the PSK's ID when used by the TLS 1302 protocol."; 1303 uses ks:local-or-keystore-symmetric-key-grouping { 1304 augment "local-or-keystore/local/local-definition" { 1305 if-feature "ks:local-definitions-supported"; 1306 description 1307 "Adds an 'id' value when the PSK is used by TLS."; 1308 leaf id { 1309 type string; // FIXME: is this the right type? 1310 description 1311 "The key id used in the TLS protocol for PSKs."; 1312 } 1313 } 1314 } 1315 } 1316 } 1317 } 1318 } // container client-identity 1320 container server-authentication { 1321 nacm:default-deny-write; 1322 must 'ca-certs or ee-certs or raw-public-keys or psks'; 1323 description 1324 "Specifies how the TLS client can authenticate TLS servers. 1325 Any combination of credentials is additive and unordered. 1327 Note that no configuration is required for PSK (pre-shared 1328 or pairwise-symmetric key) based authentication as the key 1329 is necessarily the same as configured in the '../client- 1330 identity' node."; 1331 container ca-certs { 1332 if-feature "x509-certificate-auth"; 1333 presence 1334 "Indicates that the TLS client can authenticate TLS servers 1335 using configured certificate authority certificates."; 1336 description 1337 "A set of certificate authority (CA) certificates used by 1338 the TLS client to authenticate TLS server certificates. 1339 A server certificate is authenticated if it has a valid 1340 chain of trust to a configured CA certificate."; 1341 reference 1342 "RFC BBBB: A YANG Data Model for a Truststore"; 1343 uses ts:local-or-truststore-certs-grouping; 1344 } 1345 container ee-certs { // FIXME: plural too much? 1346 if-feature "x509-certificate-auth"; 1347 presence 1348 "Indicates that the TLS client can authenticate TLS 1349 servers using configured server certificates."; 1350 description 1351 "A set of server certificates (i.e., end entity 1352 certificates) used by the TLS client to authenticate 1353 certificates presented by TLS servers. A server 1354 certificate is authenticated if it is an exact 1355 match to a configured server certificate."; 1356 reference 1357 "RFC BBBB: A YANG Data Model for a Truststore"; 1358 uses ts:local-or-truststore-certs-grouping; 1359 } 1360 container raw-public-keys { 1361 if-feature "raw-public-key-auth"; 1362 presence 1363 "Indicates that the TLS client can authenticate TLS 1364 servers using configured server certificates."; 1365 description 1366 "A set of raw public keys used by the TLS client to 1367 authenticate raw public keys presented by the TLS 1368 server. A raw public key is authenticated if it 1369 is an exact match to a configured raw public key."; 1370 reference 1371 "RFC BBBB: A YANG Data Model for a Truststore"; 1372 uses ts:local-or-truststore-public-keys-grouping { 1373 refine "local-or-truststore/local/local-definition" 1374 + "/public-key" { 1375 must 'public-key-format' 1376 + ' = "ct:subject-public-key-info-format"'; 1377 } 1378 refine "local-or-truststore/truststore" 1379 + "/truststore-reference" { 1380 must 'deref(.)/../*/ts:public-key-format' 1381 + ' = "ct:subject-public-key-info-format"'; 1382 } 1383 } 1384 } 1385 container psks { 1386 if-feature "psk-auth"; 1387 presence 1388 "Indicates that the TLS client can authenticate TLS servers 1389 using a configure PSK (pre-shared or pairwise-symmetric 1390 key)."; 1391 description 1392 "No configuration is required since the PSK value is the 1393 same as PSK value configured in the 'client-identity' 1394 node."; 1395 } 1396 } // container server-authentication 1398 container hello-params { 1399 nacm:default-deny-write; 1400 if-feature "tls-client-hello-params-config"; 1401 uses tlscmn:hello-params-grouping; 1402 description 1403 "Configurable parameters for the TLS hello message."; 1404 } // container hello-params 1406 container keepalives { 1407 nacm:default-deny-write; 1408 if-feature "tls-client-keepalives"; 1409 description 1410 "Configures the keepalive policy for the TLS client."; 1411 leaf peer-allowed-to-send { 1412 type empty; 1413 description 1414 "Indicates that the remote TLS server is allowed to send 1415 HeartbeatRequest messages, as defined by RFC 6520 1416 to this TLS client."; 1417 reference 1418 "RFC 6520: Transport Layer Security (TLS) and Datagram 1419 Transport Layer Security (DTLS) Heartbeat Extension"; 1420 } 1421 container test-peer-aliveness { 1422 presence 1423 "Indicates that the TLS client proactively tests the 1424 aliveness of the remote TLS server."; 1425 description 1426 "Configures the keep-alive policy to proactively test 1427 the aliveness of the TLS server. An unresponsive 1428 TLS server is dropped after approximately max-wait 1429 * max-attempts seconds. The TLS client MUST send 1430 HeartbeatRequest messages, as defined by RFC 6520."; 1431 reference 1432 "RFC 6520: Transport Layer Security (TLS) and Datagram 1433 Transport Layer Security (DTLS) Heartbeat Extension"; 1435 leaf max-wait { 1436 type uint16 { 1437 range "1..max"; 1438 } 1439 units "seconds"; 1440 default "30"; 1441 description 1442 "Sets the amount of time in seconds after which if 1443 no data has been received from the TLS server, a 1444 TLS-level message will be sent to test the 1445 aliveness of the TLS server."; 1446 } 1447 leaf max-attempts { 1448 type uint8; 1449 default "3"; 1450 description 1451 "Sets the maximum number of sequential keep-alive 1452 messages that can fail to obtain a response from 1453 the TLS server before assuming the TLS server is 1454 no longer alive."; 1455 } 1456 } 1457 } 1458 } // grouping tls-client-grouping 1459 } // module ietf-tls-client 1461 1463 4. The "ietf-tls-server" Module 1465 4.1. Data Model Overview 1467 4.1.1. Features 1469 The following diagram lists all the "feature" statements defined in 1470 the "ietf-tls-server" module: 1472 Features: 1473 +-- tls-server-hello-params-config 1474 +-- tls-server-keepalives 1475 +-- client-auth-config-supported 1476 +-- x509-certificate-auth 1477 +-- raw-public-key-auth 1478 +-- psk-auth 1480 4.1.2. Groupings 1482 The following diagram lists all the "grouping" statements defined in 1483 the "ietf-tls-server" module: 1485 Groupings: 1486 +-- tls-server-grouping 1488 Each of these groupings are presented in the following subsections. 1490 4.1.2.1. The "tls-server-grouping" Grouping 1492 The following tree diagram [RFC8340] illustrates the "tls-server- 1493 grouping" grouping: 1495 =============== NOTE: '\' line wrapping per RFC 8792 ================ 1497 grouping tls-server-grouping 1498 +-- server-identity 1499 | +-- (auth-type) 1500 | +--:(certificate) {x509-certificate-auth}? 1501 | | +-- certificate 1502 | | +---u ks:local-or-keystore-end-entity-cert-with-key-\ 1503 grouping 1504 | +--:(raw-private-key) {raw-public-key-auth}? 1505 | | +-- raw-private-key 1506 | | +---u ks:local-or-keystore-asymmetric-key-grouping 1507 | +--:(psk) {psk-auth}? 1508 | +-- psk 1509 | +---u ks:local-or-keystore-symmetric-key-grouping 1510 +-- client-authentication! {client-auth-config-supported}? 1511 | +-- ca-certs! {x509-certificate-auth}? 1512 | | +---u ts:local-or-truststore-certs-grouping 1513 | +-- ee-certs! {x509-certificate-auth}? 1514 | | +---u ts:local-or-truststore-certs-grouping 1515 | +-- raw-public-keys! {raw-public-key-auth}? 1516 | | +---u ts:local-or-truststore-public-keys-grouping 1517 | +-- psks! {psk-auth}? 1518 +-- hello-params {tls-server-hello-params-config}? 1519 | +---u tlscmn:hello-params-grouping 1520 +-- keepalives {tls-server-keepalives}? 1521 +-- peer-allowed-to-send? empty 1522 +-- test-peer-aliveness! 1523 +-- max-wait? uint16 1524 +-- max-attempts? uint8 1526 Comments: 1528 * The "server-identity" node configures identity credentials, each 1529 of which is enabled by a "feature". 1531 * The "client-authentication" node, which is optionally configured 1532 (as client authentication MAY occur at a higher protocol layer), 1533 configures trust anchors for authenticating the TLS client, with 1534 each option enabled by a "feature" statement. 1536 * The "hello-params" node, which must be enabled by a feature, 1537 configures parameters for the TLS sessions established by this 1538 configuration. 1540 * The "keepalives" node, which must be enabled by a feature, 1541 configures a flag enabling the TLS client to test the aliveness of 1542 the TLS server, as well as a "presence" container for testing the 1543 aliveness of the TLSi client. The aliveness-tests occurs at the 1544 TLS protocol layer. 1546 * For the referenced grouping statement(s): 1548 - The "local-or-keystore-end-entity-cert-with-key-grouping" 1549 grouping is discussed in Section 2.1.3.6 of 1550 [I-D.ietf-netconf-keystore]. 1551 - The "local-or-keystore-asymmetric-key-grouping" grouping is 1552 discussed in Section 2.1.3.4 of [I-D.ietf-netconf-keystore]. 1553 - The "local-or-keystore-symmetric-key-grouping" grouping is 1554 discussed in Section 2.1.3.3 of [I-D.ietf-netconf-keystore]. 1555 - The "local-or-truststore-public-keys-grouping" grouping is 1556 discussed in Section 2.1.3.2 of 1557 [I-D.ietf-netconf-trust-anchors]. 1558 - The "local-or-truststore-certs-grouping" grouping is discussed 1559 in Section 2.1.3.1 of [I-D.ietf-netconf-trust-anchors]. 1560 - The "hello-params-grouping" grouping is discussed in 1561 Section 2.1.3.1 in this document. 1563 4.1.3. Protocol-accessible Nodes 1565 The "ietf-tls-server" module does not contain any protocol-accessible 1566 nodes. 1568 4.2. Example Usage 1570 This section presents two examples showing the "tls-server-grouping" 1571 grouping populated with some data. These examples are effectively 1572 the same except the first configures the server identity using a 1573 local key while the second uses a key configured in a keystore. Both 1574 examples are consistent with the examples presented in Section 2 of 1575 [I-D.ietf-netconf-trust-anchors] and Section 3.2 of 1576 [I-D.ietf-netconf-keystore]. 1578 The following configuration example uses local-definitions for the 1579 server identity and client authentication: 1581 =============== NOTE: '\' line wrapping per RFC 8792 ================ 1583 1587 1588 1589 1590 1591 ct:subject-public-key-info-format 1593 base64encodedvalue== 1594 ct:rsa-private-key-format 1596 base64encodedvalue== 1598 base64encodedvalue== 1599 1600 1601 1620 1622 1623 1624 1625 1626 1627 Identity Cert Issuer #1 1628 base64encodedvalue== 1629 1630 1631 Identity Cert Issuer #2 1632 base64encodedvalue== 1633 1634 1635 1636 1637 1638 1639 Application #1 1640 base64encodedvalue== 1641 1642 1643 Application #2 1644 base64encodedvalue== 1645 1646 1647 1648 1649 1650 1651 User A 1652 ct:subject-public-key-info-format 1654 base64encodedvalue== 1655 1656 1657 User B 1658 ct:subject-public-key-info-format 1660 base64encodedvalue== 1661 1662 1663 1664 1665 1667 1668 1669 1671 1673 The following configuration example uses keystore-references for the 1674 server identity and truststore-references for client authentication: 1675 from the keystore: 1677 =============== NOTE: '\' line wrapping per RFC 8792 ================ 1679 1681 1682 1683 1684 1685 rsa-asymmetric-key 1686 ex-rsa-cert 1687 1688 1689 1698 1700 1701 1702 1703 trusted-client-ca-certs 1705 1706 1707 trusted-client-ee-certs 1709 1710 1711 Raw Public Keys for TLS Clients 1713 1714 1715 1717 1718 1719 1721 1723 4.3. YANG Module 1725 This YANG module has a normative references to [RFC5246], 1726 [I-D.ietf-netconf-trust-anchors] and [I-D.ietf-netconf-keystore]. 1728 file "ietf-tls-server@2020-07-10.yang" 1730 module ietf-tls-server { 1731 yang-version 1.1; 1732 namespace "urn:ietf:params:xml:ns:yang:ietf-tls-server"; 1733 prefix tlss; 1735 import ietf-netconf-acm { 1736 prefix nacm; 1737 reference 1738 "RFC 8341: Network Configuration Access Control Model"; 1739 } 1741 import ietf-crypto-types { 1742 prefix ct; 1743 reference 1744 "RFC AAAA: YANG Data Types and Groupings for Cryptography"; 1745 } 1747 import ietf-truststore { 1748 prefix ts; 1749 reference 1750 "RFC BBBB: A YANG Data Model for a Truststore"; 1751 } 1753 import ietf-keystore { 1754 prefix ks; 1755 reference 1756 "RFC CCCC: A YANG Data Model for a Keystore"; 1757 } 1759 import ietf-tls-common { 1760 prefix tlscmn; 1761 revision-date 2020-07-10; // stable grouping definitions 1762 reference 1763 "RFC FFFF: YANG Groupings for TLS Clients and TLS Servers"; 1764 } 1766 organization 1767 "IETF NETCONF (Network Configuration) Working Group"; 1769 contact 1770 "WG Web: 1771 WG List: 1772 Author: Kent Watsen 1773 Author: Gary Wu "; 1775 description 1776 "This module defines reusable groupings for TLS servers that 1777 can be used as a basis for specific TLS server instances. 1779 Copyright (c) 2020 IETF Trust and the persons identified 1780 as authors of the code. All rights reserved. 1782 Redistribution and use in source and binary forms, with 1783 or without modification, is permitted pursuant to, and 1784 subject to the license terms contained in, the Simplified 1785 BSD License set forth in Section 4.c of the IETF Trust's 1786 Legal Provisions Relating to IETF Documents 1787 (https://trustee.ietf.org/license-info). 1789 This version of this YANG module is part of RFC FFFF 1790 (https://www.rfc-editor.org/info/rfcFFFF); see the RFC 1791 itself for full legal notices. 1793 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1794 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 1795 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 1796 are to be interpreted as described in BCP 14 (RFC 2119) 1797 (RFC 8174) when, and only when, they appear in all 1798 capitals, as shown here."; 1800 revision 2020-07-10 { 1801 description 1802 "Initial version"; 1803 reference 1804 "RFC FFFF: YANG Groupings for TLS Clients and TLS Servers"; 1805 } 1807 // Features 1809 feature tls-server-hello-params-config { 1810 description 1811 "TLS hello message parameters are configurable on a TLS 1812 server."; 1813 } 1815 feature tls-server-keepalives { 1816 description 1817 "Per socket TLS keepalive parameters are configurable for 1818 TLS servers on the server implementing this feature."; 1820 } 1822 feature client-auth-config-supported { 1823 description 1824 "Indicates that the configuration for how to authenticate 1825 clients can be configured herein, as opposed to in an 1826 application specific location. That is, to support the 1827 consuming data models that prefer to place client 1828 authentication with client definitions, rather then 1829 in a data model principally concerned with configuring 1830 the transport."; 1831 } 1833 feature x509-certificate-auth { 1834 description 1835 "Indicates that the server supports authenticating clients 1836 using X.509 certificates."; 1837 } 1839 feature raw-public-key-auth { 1840 description 1841 "Indicates that the server supports authenticating clients 1842 using ray public keys."; 1843 } 1845 feature psk-auth { 1846 description 1847 "Indicates that the server supports authenticating clients 1848 using PSKs (pre-shared or pairwise-symmetric keys)."; 1849 } 1851 // Groupings 1853 grouping tls-server-grouping { 1854 description 1855 "A reusable grouping for configuring a TLS server without 1856 any consideration for how underlying TCP sessions are 1857 established. 1859 Note that this grouping uses fairly typical descendent 1860 node names such that a stack of 'uses' statements will 1861 have name conflicts. It is intended that the consuming 1862 data model will resolve the issue (e.g., by wrapping 1863 the 'uses' statement in a container called 1864 'tls-server-parameters'). This model purposely does 1865 not do this itself so as to provide maximum flexibility 1866 to consuming models."; 1868 container server-identity { 1869 nacm:default-deny-write; 1870 description 1871 "A locally-defined or referenced end-entity certificate, 1872 including any configured intermediate certificates, the 1873 TLS server will present when establishing a TLS connection 1874 in its Certificate message, as defined in Section 7.4.2 1875 in RFC 5246."; 1876 reference 1877 "RFC 5246: The Transport Layer Security (TLS) Protocol 1878 Version 1.2 1879 RFC CCCC: A YANG Data Model for a Keystore"; 1880 choice auth-type { 1881 mandatory true; 1882 description 1883 "A choice amongst authentication types."; 1884 case certificate { 1885 if-feature x509-certificate-auth; 1886 container certificate { 1887 description 1888 "Specifies the server identity using a certificate."; 1889 uses 1890 ks:local-or-keystore-end-entity-cert-with-key-grouping{ 1891 refine "local-or-keystore/local/local-definition" { 1892 must 'public-key-format' 1893 + ' = "ct:subject-public-key-info-format"'; 1894 } 1895 refine "local-or-keystore/keystore/keystore-reference" 1896 + "/asymmetric-key" { 1897 must 'deref(.)/../ks:public-key-format' 1898 + ' = "ct:subject-public-key-info-format"'; 1899 } 1900 } 1901 } 1902 } 1903 case raw-private-key { 1904 if-feature raw-public-key-auth; 1905 container raw-private-key { 1906 description 1907 "Specifies the server identity using a raw 1908 private key."; 1909 uses ks:local-or-keystore-asymmetric-key-grouping { 1910 refine "local-or-keystore/local/local-definition" { 1911 must 'public-key-format' 1912 + ' = "ct:subject-public-key-info-format"'; 1914 } 1915 refine "local-or-keystore/keystore/keystore-reference"{ 1916 must 'deref(.)/../ks:public-key-format' 1917 + ' = "ct:subject-public-key-info-format"'; 1918 } 1919 } 1920 } 1921 } 1922 case psk { 1923 if-feature psk-auth; 1924 container psk { 1925 description 1926 "Specifies the server identity using a PSK (pre-shared 1927 or pairwise-symmetric key). Note that, when the PSK is 1928 configured as a Keystore reference, the key's 'name' 1929 node MAY be used as the PSK's ID when used by the TLS 1930 protocol."; 1931 uses ks:local-or-keystore-symmetric-key-grouping { 1932 augment "local-or-keystore/local/local-definition" { 1933 if-feature "ks:local-definitions-supported"; 1934 description 1935 "An 'id' value for when the PSK is used by TLS."; 1936 leaf id { 1937 type string; // FIXME: is this the right type? 1938 description 1939 "The key id used in the TLS protocol for PSKs."; 1940 } 1941 } 1942 } 1943 } 1944 } 1945 } 1946 } // container server-identity 1948 container client-authentication { 1949 if-feature "client-auth-config-supported"; 1950 nacm:default-deny-write; 1951 must 'ca-certs or ee-certs or raw-public-keys or psks'; 1952 presence 1953 "Indicates that client authentication is supported (i.e., 1954 that the server will request clients send certificates). 1955 If not configured, the TLS server SHOULD NOT request the 1956 TLS clients provide authentication credentials."; 1957 description 1958 "Specifies how the TLS server can authenticate TLS clients. 1959 Any combination of credentials is additive and unordered. 1961 Note that no configuration is required for PSK (pre-shared 1962 or pairwise-symmetric key) based authentication as the key 1963 is necessarily the same as configured in the '../server- 1964 identity' node."; 1965 container ca-certs { 1966 if-feature "x509-certificate-auth"; 1967 presence 1968 "Indicates that the TLS server can authenticate TLS clients 1969 using configured certificate authority certificates."; 1970 description 1971 "A set of certificate authority (CA) certificates used by 1972 the TLS server to authenticate TLS client certificates. A 1973 client certificate is authenticated if it has a valid 1974 chain of trust to a configured CA certificate."; 1975 reference 1976 "RFC BBBB: A YANG Data Model for a Truststore"; 1977 uses ts:local-or-truststore-certs-grouping; 1978 } 1979 container ee-certs { // FIXME: plural too much? 1980 if-feature "x509-certificate-auth"; 1981 presence 1982 "Indicates that the TLS server can authenticate TLS 1983 clients using configured client certificates."; 1984 description 1985 "A set of client certificates (i.e., end entity 1986 certificates) used by the TLS server to authenticate 1987 certificates presented by TLS clients. A client 1988 certificate is authenticated if it is an exact 1989 match to a configured client certificate."; 1990 reference 1991 "RFC BBBB: A YANG Data Model for a Truststore"; 1992 uses ts:local-or-truststore-certs-grouping; 1993 } 1994 container raw-public-keys { 1995 if-feature "raw-public-key-auth"; 1996 presence 1997 "Indicates that the TLS server can authenticate TLS 1998 clients using raw public keys."; 1999 description 2000 "A set of raw public keys used by the TLS server to 2001 authenticate raw public keys presented by the TLS 2002 client. A raw public key is authenticated if it 2003 is an exact match to a configured raw public key."; 2004 reference 2005 "RFC BBBB: A YANG Data Model for a Truststore"; 2006 uses ts:local-or-truststore-public-keys-grouping { 2007 refine "local-or-truststore/local/local-definition" 2008 + "/public-key" { 2009 must 'public-key-format' 2010 + ' = "ct:subject-public-key-info-format"'; 2011 } 2012 refine "local-or-truststore/truststore" 2013 + "/truststore-reference" { 2014 must 'deref(.)/../*/ts:public-key-format' 2015 + ' = "ct:subject-public-key-info-format"'; 2016 } 2017 } 2018 } 2019 container psks { 2020 if-feature "psk-auth"; 2021 presence 2022 "Indicates that the TLS server can authenticate the TLS 2023 client using its PSK (pre-shared or pairwise-symmetric 2024 key)."; 2025 description 2026 "No configuration is required since the PSK value is the 2027 same as PSK value configured in the 'client-identity' 2028 node."; 2029 } 2030 } // container client-authentication 2032 container hello-params { 2033 nacm:default-deny-write; 2034 if-feature "tls-server-hello-params-config"; 2035 uses tlscmn:hello-params-grouping; 2036 description 2037 "Configurable parameters for the TLS hello message."; 2038 } // container hello-params 2040 container keepalives { 2041 nacm:default-deny-write; 2042 if-feature "tls-server-keepalives"; 2043 description 2044 "Configures the keepalive policy for the TLS server."; 2045 leaf peer-allowed-to-send { 2046 type empty; 2047 description 2048 "Indicates that the remote TLS client is allowed to send 2049 HeartbeatRequest messages, as defined by RFC 6520 2050 to this TLS server."; 2051 reference 2052 "RFC 6520: Transport Layer Security (TLS) and Datagram 2053 Transport Layer Security (DTLS) Heartbeat Extension"; 2054 } 2055 container test-peer-aliveness { 2056 presence 2057 "Indicates that the TLS server proactively tests the 2058 aliveness of the remote TLS client."; 2059 description 2060 "Configures the keep-alive policy to proactively test 2061 the aliveness of the TLS client. An unresponsive 2062 TLS client is dropped after approximately max-wait 2063 * max-attempts seconds."; 2064 leaf max-wait { 2065 type uint16 { 2066 range "1..max"; 2067 } 2068 units "seconds"; 2069 default "30"; 2070 description 2071 "Sets the amount of time in seconds after which if 2072 no data has been received from the TLS client, a 2073 TLS-level message will be sent to test the 2074 aliveness of the TLS client."; 2075 } 2076 leaf max-attempts { 2077 type uint8; 2078 default "3"; 2079 description 2080 "Sets the maximum number of sequential keep-alive 2081 messages that can fail to obtain a response from 2082 the TLS client before assuming the TLS client is 2083 no longer alive."; 2084 } 2085 } 2086 } // container keepalives 2087 } // grouping tls-server-grouping 2088 } // module ietf-tls-server 2090 2092 5. Security Considerations 2094 5.1. The "ietf-tls-common" YANG Module 2096 The "ietf-tls-common" YANG module defines "grouping" statements that 2097 are designed to be accessed via YANG based management protocols, such 2098 as NETCONF [RFC6241] and RESTCONF [RFC8040]. Both of these protocols 2099 have mandatory-to-implement secure transport layers (e.g., SSH, TLS) 2100 with mutual authentication. 2102 The NETCONF access control model (NACM) [RFC8341] provides the means 2103 to restrict access for particular users to a pre-configured subset of 2104 all available protocol operations and content. 2106 Since the module in this document only define groupings, these 2107 considerations are primarily for the designers of other modules that 2108 use these groupings. 2110 None of the readable data nodes defined in this YANG module are 2111 considered sensitive or vulnerable in network environments. The NACM 2112 "default-deny-all" extension has not been set for any data nodes 2113 defined in this module. 2115 None of the writable data nodes defined in this YANG module are 2116 considered sensitive or vulnerable in network environments. The NACM 2117 "default-deny-write" extension has not been set for any data nodes 2118 defined in this module. 2120 This module does not define any RPCs, actions, or notifications, and 2121 thus the security consideration for such is not provided here. 2123 5.2. The "ietf-tls-client" YANG Module 2125 The "ietf-tls-client" YANG module defines "grouping" statements that 2126 are designed to be accessed via YANG based management protocols, such 2127 as NETCONF [RFC6241] and RESTCONF [RFC8040]. Both of these protocols 2128 have mandatory-to-implement secure transport layers (e.g., SSH, TLS) 2129 with mutual authentication. 2131 The NETCONF access control model (NACM) [RFC8341] provides the means 2132 to restrict access for particular users to a pre-configured subset of 2133 all available protocol operations and content. 2135 Since the module in this document only define groupings, these 2136 considerations are primarily for the designers of other modules that 2137 use these groupings. 2139 None of the readable data nodes defined in this YANG module are 2140 considered sensitive or vulnerable in network environments. The NACM 2141 "default-deny-all" extension has not been set for any data nodes 2142 defined in this module. 2144 | Please be aware that this module uses the "key" and "private- 2145 | key" nodes from the "ietf-crypto-types" module 2146 | [I-D.ietf-netconf-crypto-types], where said nodes have the NACM 2147 | extension "default-deny-all" set, thus preventing unrestricted 2148 | read-access to the cleartext key values. 2150 All of the writable data nodes defined by this module may be 2151 considered sensitive or vulnerable in some network environments. For 2152 instance, any modification to a key or reference to a key may 2153 dramatically alter the implemented security policy. For this reason, 2154 the NACM extension "default-deny-write" has been set for all data 2155 nodes defined in this module. 2157 This module does not define any RPCs, actions, or notifications, and 2158 thus the security consideration for such is not provided here. 2160 5.3. The "ietf-tls-server" YANG Module 2162 The "ietf-tls-server" YANG module defines "grouping" statements that 2163 are designed to be accessed via YANG based management protocols, such 2164 as NETCONF [RFC6241] and RESTCONF [RFC8040]. Both of these protocols 2165 have mandatory-to-implement secure transport layers (e.g., SSH, TLS) 2166 with mutual authentication. 2168 The NETCONF access control model (NACM) [RFC8341] provides the means 2169 to restrict access for particular users to a pre-configured subset of 2170 all available protocol operations and content. 2172 Since the module in this document only define groupings, these 2173 considerations are primarily for the designers of other modules that 2174 use these groupings. 2176 None of the readable data nodes defined in this YANG module are 2177 considered sensitive or vulnerable in network environments. The NACM 2178 "default-deny-all" extension has not been set for any data nodes 2179 defined in this module. 2181 | Please be aware that this module uses the "key" and "private- 2182 | key" nodes from the "ietf-crypto-types" module 2183 | [I-D.ietf-netconf-crypto-types], where said nodes have the NACM 2184 | extension "default-deny-all" set, thus preventing unrestricted 2185 | read-access to the cleartext key values. 2187 All of the writable data nodes defined by this module may be 2188 considered sensitive or vulnerable in some network environments. For 2189 instance, any modification to a key or reference to a key may 2190 dramatically alter the implemented security policy. For this reason, 2191 the NACM extension "default-deny-write" has been set for all data 2192 nodes defined in this module. 2194 This module does not define any RPCs, actions, or notifications, and 2195 thus the security consideration for such is not provided here. 2197 6. IANA Considerations 2199 6.1. The "IETF XML" Registry 2201 This document registers three URIs in the "ns" subregistry of the 2202 IETF XML Registry [RFC3688]. Following the format in [RFC3688], the 2203 following registrations are requested: 2205 URI: urn:ietf:params:xml:ns:yang:ietf-tls-common 2206 Registrant Contact: The NETCONF WG of the IETF. 2207 XML: N/A, the requested URI is an XML namespace. 2209 URI: urn:ietf:params:xml:ns:yang:ietf-tls-client 2210 Registrant Contact: The NETCONF WG of the IETF. 2211 XML: N/A, the requested URI is an XML namespace. 2213 URI: urn:ietf:params:xml:ns:yang:ietf-tls-server 2214 Registrant Contact: The NETCONF WG of the IETF. 2215 XML: N/A, the requested URI is an XML namespace. 2217 6.2. The "YANG Module Names" Registry 2219 This document registers three YANG modules in the YANG Module Names 2220 registry [RFC6020]. Following the format in [RFC6020], the following 2221 registrations are requested: 2223 name: ietf-tls-common 2224 namespace: urn:ietf:params:xml:ns:yang:ietf-tls-common 2225 prefix: tlscmn 2226 reference: RFC FFFF 2228 name: ietf-tls-client 2229 namespace: urn:ietf:params:xml:ns:yang:ietf-tls-client 2230 prefix: tlsc 2231 reference: RFC FFFF 2233 name: ietf-tls-server 2234 namespace: urn:ietf:params:xml:ns:yang:ietf-tls-server 2235 prefix: tlss 2236 reference: RFC FFFF 2238 7. References 2240 7.1. Normative References 2242 [I-D.ietf-netconf-crypto-types] 2243 Watsen, K., "Common YANG Data Types for Cryptography", 2244 Work in Progress, Internet-Draft, draft-ietf-netconf- 2245 crypto-types-15, 20 May 2020, 2246 . 2249 [I-D.ietf-netconf-keystore] 2250 Watsen, K., "A YANG Data Model for a Keystore", Work in 2251 Progress, Internet-Draft, draft-ietf-netconf-keystore-17, 2252 20 May 2020, . 2255 [I-D.ietf-netconf-trust-anchors] 2256 Watsen, K., "A YANG Data Model for a Truststore", Work in 2257 Progress, Internet-Draft, draft-ietf-netconf-trust- 2258 anchors-10, 20 May 2020, . 2261 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2262 Requirement Levels", BCP 14, RFC 2119, 2263 DOI 10.17487/RFC2119, March 1997, 2264 . 2266 [RFC5288] Salowey, J., Choudhury, A., and D. McGrew, "AES Galois 2267 Counter Mode (GCM) Cipher Suites for TLS", RFC 5288, 2268 DOI 10.17487/RFC5288, August 2008, 2269 . 2271 [RFC5289] Rescorla, E., "TLS Elliptic Curve Cipher Suites with SHA- 2272 256/384 and AES Galois Counter Mode (GCM)", RFC 5289, 2273 DOI 10.17487/RFC5289, August 2008, 2274 . 2276 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 2277 the Network Configuration Protocol (NETCONF)", RFC 6020, 2278 DOI 10.17487/RFC6020, October 2010, 2279 . 2281 [RFC7589] Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the 2282 NETCONF Protocol over Transport Layer Security (TLS) with 2283 Mutual X.509 Authentication", RFC 7589, 2284 DOI 10.17487/RFC7589, June 2015, 2285 . 2287 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2288 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2289 . 2291 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2292 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2293 May 2017, . 2295 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 2296 Access Control Model", STD 91, RFC 8341, 2297 DOI 10.17487/RFC8341, March 2018, 2298 . 2300 [RFC8422] Nir, Y., Josefsson, S., and M. Pegourie-Gonnard, "Elliptic 2301 Curve Cryptography (ECC) Cipher Suites for Transport Layer 2302 Security (TLS) Versions 1.2 and Earlier", RFC 8422, 2303 DOI 10.17487/RFC8422, August 2018, 2304 . 2306 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 2307 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 2308 . 2310 7.2. Informative References 2312 [I-D.ietf-netconf-http-client-server] 2313 Watsen, K., "YANG Groupings for HTTP Clients and HTTP 2314 Servers", Work in Progress, Internet-Draft, draft-ietf- 2315 netconf-http-client-server-03, 20 May 2020, 2316 . 2319 [I-D.ietf-netconf-netconf-client-server] 2320 Watsen, K., "NETCONF Client and Server Models", Work in 2321 Progress, Internet-Draft, draft-ietf-netconf-netconf- 2322 client-server-19, 20 May 2020, 2323 . 2326 [I-D.ietf-netconf-restconf-client-server] 2327 Watsen, K., "RESTCONF Client and Server Models", Work in 2328 Progress, Internet-Draft, draft-ietf-netconf-restconf- 2329 client-server-19, 20 May 2020, 2330 . 2333 [I-D.ietf-netconf-ssh-client-server] 2334 Watsen, K. and G. Wu, "YANG Groupings for SSH Clients and 2335 SSH Servers", Work in Progress, Internet-Draft, draft- 2336 ietf-netconf-ssh-client-server-19, 20 May 2020, 2337 . 2340 [I-D.ietf-netconf-tcp-client-server] 2341 Watsen, K. and M. Scharf, "YANG Groupings for TCP Clients 2342 and TCP Servers", Work in Progress, Internet-Draft, draft- 2343 ietf-netconf-tcp-client-server-06, 16 June 2020, 2344 . 2347 [I-D.ietf-netconf-tls-client-server] 2348 Watsen, K. and G. Wu, "YANG Groupings for TLS Clients and 2349 TLS Servers", Work in Progress, Internet-Draft, draft- 2350 ietf-netconf-tls-client-server-19, 20 May 2020, 2351 . 2354 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 2355 RFC 2246, DOI 10.17487/RFC2246, January 1999, 2356 . 2358 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 2359 DOI 10.17487/RFC2818, May 2000, 2360 . 2362 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2363 DOI 10.17487/RFC3688, January 2004, 2364 . 2366 [RFC4346] Dierks, T. and E. Rescorla, "The Transport Layer Security 2367 (TLS) Protocol Version 1.1", RFC 4346, 2368 DOI 10.17487/RFC4346, April 2006, 2369 . 2371 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2372 (TLS) Protocol Version 1.2", RFC 5246, 2373 DOI 10.17487/RFC5246, August 2008, 2374 . 2376 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2377 and A. Bierman, Ed., "Network Configuration Protocol 2378 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2379 . 2381 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2382 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2383 . 2385 [RFC8071] Watsen, K., "NETCONF Call Home and RESTCONF Call Home", 2386 RFC 8071, DOI 10.17487/RFC8071, February 2017, 2387 . 2389 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 2390 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 2391 . 2393 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 2394 and R. Wilton, "Network Management Datastore Architecture 2395 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 2396 . 2398 Appendix A. Change Log 2400 This section is to be removed before publishing as an RFC. 2402 A.1. 00 to 01 2404 * Noted that '0.0.0.0' and '::' might have special meanings. 2406 * Renamed "keychain" to "keystore". 2408 A.2. 01 to 02 2410 * Removed the groupings containing transport-level configuration. 2411 Now modules contain only the transport-independent groupings. 2413 * Filled in previously incomplete 'ietf-tls-client' module. 2415 * Added cipher suites for various algorithms into new 'ietf-tls- 2416 common' module. 2418 A.3. 02 to 03 2420 * Added a 'must' statement to container 'server-auth' asserting that 2421 at least one of the various auth mechanisms must be specified. 2423 * Fixed description statement for leaf 'trusted-ca-certs'. 2425 A.4. 03 to 04 2427 * Updated title to "YANG Groupings for TLS Clients and TLS Servers" 2429 * Updated leafref paths to point to new keystore path 2431 * Changed the YANG prefix for ietf-tls-common from 'tlscom' to 2432 'tlscmn'. 2434 * Added TLS protocol verions 1.0 and 1.1. 2436 * Made author lists consistent 2437 * Now tree diagrams reference ietf-netmod-yang-tree-diagrams 2439 * Updated YANG to use typedefs around leafrefs to common keystore 2440 paths 2442 * Now inlines key and certificates (no longer a leafref to keystore) 2444 A.5. 04 to 05 2446 * Merged changes from co-author. 2448 A.6. 05 to 06 2450 * Updated to use trust anchors from trust-anchors draft (was 2451 keystore draft) 2453 * Now Uses new keystore grouping enabling asymmetric key to be 2454 either locally defined or a reference to the keystore. 2456 A.7. 06 to 07 2458 * factored the tls-[client|server]-groupings into more reusable 2459 groupings. 2461 * added if-feature statements for the new "x509-certificates" 2462 feature defined in draft-ietf-netconf-trust-anchors. 2464 A.8. 07 to 08 2466 * Added a number of compatibility matrices to Section 5 (thanks 2467 Frank!) 2469 * Clarified that any configured "cipher-suite" values need to be 2470 compatible with the configured private key. 2472 A.9. 08 to 09 2474 * Updated examples to reflect update to groupings defined in the 2475 keystore draft. 2477 * Add TLS keepalives features and groupings. 2479 * Prefixed top-level TLS grouping nodes with 'tls-' and support 2480 mashups. 2482 * Updated copyright date, boilerplate template, affiliation, and 2483 folding algorithm. 2485 A.10. 09 to 10 2487 * Reformatted the YANG modules. 2489 A.11. 10 to 11 2491 * Collapsed all the inner groupings into the top-level grouping. 2493 * Added a top-level "demux container" inside the top-level grouping. 2495 * Added NACM statements and updated the Security Considerations 2496 section. 2498 * Added "presence" statements on the "keepalive" containers, as was 2499 needed to address a validation error that appeared after adding 2500 the "must" statements into the NETCONF/RESTCONF client/server 2501 modules. 2503 * Updated the boilerplate text in module-level "description" 2504 statement to match copyeditor convention. 2506 A.12. 11 to 12 2508 * In server model, made 'client-authentication' a 'presence' node 2509 indicating that the server supports client authentication. 2511 * In the server model, added a 'required-or-optional' choice to 2512 'client-authentication' to better support protocols such as 2513 RESTCONF. 2515 * In the server model, added a 'local-or-external' choice to 2516 'client-authentication' to better support consuming data models 2517 that prefer to keep client auth with client definitions than in a 2518 model principally concerned with the "transport". 2520 * In both models, removed the "demux containers", floating the 2521 nacm:default-deny-write to each descendent node, and adding a note 2522 to model designers regarding the potential need to add their own 2523 demux containers. 2525 * Fixed a couple references (section 2 --> section 3) 2527 A.13. 12 to 13 2529 * Updated to reflect changes in trust-anchors drafts (e.g., s/trust- 2530 anchors/truststore/g + s/pinned.//) 2532 A.14. 12 to 13 2534 * Removed 'container' under 'client-identity' to match server model. 2536 * Updated examples to reflect change grouping in keystore module. 2538 A.15. 13 to 14 2540 * Removed the "certificate" container from "client-identity" in the 2541 ietf-tls-client module. 2543 * Updated examples to reflect ietf-crypto-types change (e.g., 2544 identities --> enumerations) 2546 A.16. 14 to 15 2548 * Updated "server-authentication" and "client-authentication" nodes 2549 from being a leaf of type "ts:certificates-ref" to a container 2550 that uses "ts:local-or-truststore-certs-grouping". 2552 A.17. 15 to 16 2554 * Removed unnecessary if-feature statements in the -client and 2555 -server modules. 2557 * Cleaned up some description statements in the -client and -server 2558 modules. 2560 * Fixed a canonical ordering issue in ietf-tls-common detected by 2561 new pyang. 2563 A.18. 16 to 17 2565 * Removed choice local-or-external by removing the 'external' case 2566 and flattening the 'local' case and adding a "client-auth-config- 2567 supported" feature. 2569 * Removed choice required-or-optional. 2571 * Updated examples to include the "*-key-format" nodes. 2573 * Augmented-in "must" expressions ensuring that locally-defined 2574 public-key-format are "ct:ssh-public-key-format" (must expr for 2575 ref'ed keys are TBD). 2577 A.19. 17 to 18 2579 * Removed the unused "external-client-auth-supported" feature. 2581 * Made client-indentity optional, as there may be over-the-top auth 2582 instead. 2584 * Added augment to uses of local-or-keystore-symmetric-key-grouping 2585 for a psk "id" node. 2587 * Added missing presence container "psks" to ietf-tls-server's 2588 "client-authentication" container. 2590 * Updated examples to reflect new "bag" addition to truststore. 2592 * Removed feature-limited caseless 'case' statements to improve tree 2593 diagram rendering. 2595 * Refined truststore/keystore groupings to ensure the key formats 2596 "must" be particular values. 2598 * Switched to using truststore's new "public-key" bag (instead of 2599 separate "ssh-public-key" and "raw-public-key" bags. 2601 * Updated client/server examples to cover ALL cases (local/ref x 2602 cert/raw-key/psk). 2604 A.20. 18 to 19 2606 * Updated the "keepalives" containers in part to address Michal 2607 Vasko's request to align with RFC 8071, and in part to better 2608 align to RFC 6520. 2610 * Removed algorithm-mapping tables from the "TLS Common Model" 2611 section 2613 * Removed the 'algorithm' node from the examples. 2615 * Renamed both "client-certs" and "server-certs" to "ee-certs" 2617 * Added a "Note to Reviewers" note to first page. 2619 A.21. 19 to 20 2621 * Modified the 'must' expression in the "ietf-tls-client:server- 2622 authention" node to cover the "raw-public-keys" and "psks" nodes 2623 also. 2625 * Added a "must 'ca-certs or ee-certs or raw-public-keys or psks'" 2626 statement to the ietf-tls-server:client-authentication" node. 2628 * Added "mandatory true" to "choice auth-type" and a "presence" 2629 statement to its ancestor. 2631 * Expanded "Data Model Overview section(s) [remove "wall" of tree 2632 diagrams]. 2634 * Moved the "ietf-ssh-common" module section to proceed the other 2635 two module sections. 2637 * Updated the Security Considerations section. 2639 A.22. 20 to 21 2641 * Updated examples to reflect new "cleartext-" prefix in the crypto- 2642 types draft. 2644 Acknowledgements 2646 The authors would like to thank for following for lively discussions 2647 on list and in the halls (ordered by last name): Andy Bierman, Martin 2648 Bjorklund, Benoit Claise, Mehmet Ersue, Balazs Kovacs, Radek Krejci, 2649 David Lamparter, Ladislav Lhotka, Alan Luchuk, Tom Petch, Juergen 2650 Schoenwaelder, Phil Shafer, Sean Turner, Michal Vasko, Bert Wijnen, 2651 and Liang Xia. 2653 Authors' Addresses 2655 Kent Watsen 2656 Watsen Networks 2658 Email: kent+ietf@watsen.net 2660 Gary Wu 2661 Cisco Systems 2663 Email: garywu@cisco.com