idnits 2.17.1 draft-ietf-netconf-ssh-client-server-22.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 == Line 1402 has weird spacing: '...ificate has a...' -- The document date (20 August 2020) is 1335 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-17 == Outdated reference: A later version (-35) exists of draft-ietf-netconf-keystore-19 == Outdated reference: A later version (-28) exists of draft-ietf-netconf-trust-anchors-12 == Outdated reference: A later version (-20) exists of draft-ietf-netconf-http-client-server-04 == Outdated reference: A later version (-36) exists of draft-ietf-netconf-netconf-client-server-20 == Outdated reference: A later version (-36) exists of draft-ietf-netconf-restconf-client-server-20 == Outdated reference: A later version (-40) exists of draft-ietf-netconf-ssh-client-server-21 == Outdated reference: A later version (-26) exists of draft-ietf-netconf-tcp-client-server-07 == Outdated reference: A later version (-41) exists of draft-ietf-netconf-tls-client-server-21 Summary: 0 errors (**), 0 flaws (~~), 11 warnings (==), 1 comment (--). 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 20 August 2020 5 Expires: 21 February 2021 7 YANG Groupings for SSH Clients and SSH Servers 8 draft-ietf-netconf-ssh-client-server-22 10 Abstract 12 This document defines three YANG modules: the first defines groupings 13 for a generic SSH client, the second defines groupings for a generic 14 SSH server, and the third defines common identities and groupings 15 used by both the client and the server. It is intended that these 16 groupings will be used by applications using the SSH protocol. 18 Editorial Note (To be removed by RFC Editor) 20 This draft contains placeholder values that need to be replaced with 21 finalized values at the time of publication. This note summarizes 22 all of the substitutions that are needed. No other RFC Editor 23 instructions are specified elsewhere in this document. 25 Artwork in this document contains shorthand references to drafts in 26 progress. Please apply the following replacements: 28 * "AAAA" --> the assigned RFC value for draft-ietf-netconf-crypto- 29 types 31 * "BBBB" --> the assigned RFC value for draft-ietf-netconf-trust- 32 anchors 34 * "CCCC" --> the assigned RFC value for draft-ietf-netconf-keystore 36 * "DDDD" --> the assigned RFC value for draft-ietf-netconf-tcp- 37 client-server 39 * "EEEE" --> the assigned RFC value for this draft 41 Artwork in this document contains placeholder values for the date of 42 publication of this draft. Please apply the following replacement: 44 * "2020-08-20" --> the publication date of this draft 46 The following Appendix section is to be removed prior to publication: 48 * Appendix A. Change Log 50 Status of This Memo 52 This Internet-Draft is submitted in full conformance with the 53 provisions of BCP 78 and BCP 79. 55 Internet-Drafts are working documents of the Internet Engineering 56 Task Force (IETF). Note that other groups may also distribute 57 working documents as Internet-Drafts. The list of current Internet- 58 Drafts is at https://datatracker.ietf.org/drafts/current/. 60 Internet-Drafts are draft documents valid for a maximum of six months 61 and may be updated, replaced, or obsoleted by other documents at any 62 time. It is inappropriate to use Internet-Drafts as reference 63 material or to cite them other than as "work in progress." 65 This Internet-Draft will expire on 21 February 2021. 67 Copyright Notice 69 Copyright (c) 2020 IETF Trust and the persons identified as the 70 document authors. All rights reserved. 72 This document is subject to BCP 78 and the IETF Trust's Legal 73 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 74 license-info) in effect on the date of publication of this document. 75 Please review these documents carefully, as they describe your rights 76 and restrictions with respect to this document. Code Components 77 extracted from this document must include Simplified BSD License text 78 as described in Section 4.e of the Trust Legal Provisions and are 79 provided without warranty as described in the Simplified BSD License. 81 Table of Contents 83 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 84 1.1. Relation to other RFCs . . . . . . . . . . . . . . . . . 4 85 1.2. Specification Language . . . . . . . . . . . . . . . . . 6 86 1.3. Adherence to the NMDA . . . . . . . . . . . . . . . . . . 6 87 2. The "ietf-ssh-common" Module . . . . . . . . . . . . . . . . 6 88 2.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 6 89 2.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 9 90 2.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 9 91 3. The "ietf-ssh-client" Module . . . . . . . . . . . . . . . . 19 92 3.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 19 93 3.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 22 94 3.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 26 95 4. The "ietf-ssh-server" Module . . . . . . . . . . . . . . . . 33 96 4.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 33 97 4.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 36 98 4.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 40 99 5. Security Considerations . . . . . . . . . . . . . . . . . . . 49 100 5.1. The "ietf-ssh-common" YANG Module . . . . . . . . . . . . 49 101 5.2. The "ietf-ssh-client" YANG Module . . . . . . . . . . . . 50 102 5.3. The "ietf-ssh-server" YANG Module . . . . . . . . . . . . 51 103 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 52 104 6.1. The "IETF XML" Registry . . . . . . . . . . . . . . . . . 52 105 6.2. The "YANG Module Names" Registry . . . . . . . . . . . . 52 106 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 53 107 7.1. Normative References . . . . . . . . . . . . . . . . . . 53 108 7.2. Informative References . . . . . . . . . . . . . . . . . 54 109 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 56 110 A.1. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 56 111 A.2. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 56 112 A.3. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 56 113 A.4. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 57 114 A.5. 04 to 05 . . . . . . . . . . . . . . . . . . . . . . . . 57 115 A.6. 05 to 06 . . . . . . . . . . . . . . . . . . . . . . . . 57 116 A.7. 06 to 07 . . . . . . . . . . . . . . . . . . . . . . . . 57 117 A.8. 07 to 08 . . . . . . . . . . . . . . . . . . . . . . . . 58 118 A.9. 08 to 09 . . . . . . . . . . . . . . . . . . . . . . . . 58 119 A.10. 09 to 10 . . . . . . . . . . . . . . . . . . . . . . . . 58 120 A.11. 10 to 11 . . . . . . . . . . . . . . . . . . . . . . . . 58 121 A.12. 11 to 12 . . . . . . . . . . . . . . . . . . . . . . . . 58 122 A.13. 12 to 13 . . . . . . . . . . . . . . . . . . . . . . . . 59 123 A.14. 13 to 14 . . . . . . . . . . . . . . . . . . . . . . . . 59 124 A.15. 14 to 15 . . . . . . . . . . . . . . . . . . . . . . . . 59 125 A.16. 15 to 16 . . . . . . . . . . . . . . . . . . . . . . . . 59 126 A.17. 16 to 17 . . . . . . . . . . . . . . . . . . . . . . . . 59 127 A.18. 17 to 18 . . . . . . . . . . . . . . . . . . . . . . . . 60 128 A.19. 18 to 19 . . . . . . . . . . . . . . . . . . . . . . . . 60 129 A.20. 19 to 20 . . . . . . . . . . . . . . . . . . . . . . . . 61 130 A.21. 20 to 21 . . . . . . . . . . . . . . . . . . . . . . . . 61 131 A.22. 21 to 22 . . . . . . . . . . . . . . . . . . . . . . . . 61 132 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 61 133 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 61 135 1. Introduction 137 This document defines three YANG 1.1 [RFC7950] modules: the first 138 defines a grouping for a generic SSH client, the second defines a 139 grouping for a generic SSH server, and the third defines identities 140 and groupings common to both the client and the server. It is 141 intended that these groupings will be used by applications using the 142 SSH protocol [RFC4252], [RFC4253], and [RFC4254]. For instance, 143 these groupings could be used to help define the data model for an 144 OpenSSH [OPENSSH] server or a NETCONF over SSH [RFC6242] based 145 server. 147 The client and server YANG modules in this document each define one 148 grouping, which is focused on just SSH-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 SSH parts it provides, while adding data nodes for 155 the TCP-level call-home configuration. 157 The modules defined in this document use groupings defined in 158 [I-D.ietf-netconf-keystore] enabling keys to be either locally 159 defined or a reference to globally configured values. 161 The modules defined in this document optionally support [RFC6187] 162 enabling X.509v3 certificate based host keys and public keys. 164 1.1. Relation to other RFCs 166 This document presents one or more YANG modules [RFC7950] that are 167 part of a collection of RFCs that work together to define 168 configuration modules for clients and servers of both the NETCONF 169 [RFC6241] and RESTCONF [RFC8040] protocols. 171 The modules have been defined in a modular fashion to enable their 172 use by other efforts, some of which are known to be in progress at 173 the time of this writing, with many more expected to be defined in 174 time. 176 The normative dependency relationship between the various RFCs in the 177 collection is presented in the below diagram. The labels in the 178 diagram represent the primary purpose provided by each RFC. 179 Hyperlinks to each RFC are provided below the diagram. 181 crypto-types 182 ^ ^ 183 / \ 184 / \ 185 truststore keystore 186 ^ ^ ^ ^ 187 | +---------+ | | 188 | | | | 189 | +------------+ | 190 tcp-client-server | / | | 191 ^ ^ ssh-client-server | | 192 | | ^ tls-client-server 193 | | | ^ ^ http-client-server 194 | | | | | ^ 195 | | | +-----+ +---------+ | 196 | | | | | | 197 | +-----------|--------|--------------+ | | 198 | | | | | | 199 +-----------+ | | | | | 200 | | | | | | 201 | | | | | | 202 netconf-client-server restconf-client-server 204 +=======================+===========================================+ 205 | Label in Diagram | Originating RFC | 206 +=======================+===========================================+ 207 | crypto-types | [I-D.ietf-netconf-crypto-types] | 208 +-----------------------+-------------------------------------------+ 209 | truststore | [I-D.ietf-netconf-trust-anchors] | 210 +-----------------------+-------------------------------------------+ 211 | keystore | [I-D.ietf-netconf-keystore] | 212 +-----------------------+-------------------------------------------+ 213 | tcp-client-server | [I-D.ietf-netconf-tcp-client-server] | 214 +-----------------------+-------------------------------------------+ 215 | ssh-client-server | [I-D.ietf-netconf-ssh-client-server] | 216 +-----------------------+-------------------------------------------+ 217 | tls-client-server | [I-D.ietf-netconf-tls-client-server] | 218 +-----------------------+-------------------------------------------+ 219 | http-client-server | [I-D.ietf-netconf-http-client-server] | 220 +-----------------------+-------------------------------------------+ 221 | netconf-client-server | [I-D.ietf-netconf-netconf-client-server] | 222 +-----------------------+-------------------------------------------+ 223 |restconf-client-server | [I-D.ietf-netconf-restconf-client-server] | 224 +-----------------------+-------------------------------------------+ 226 Table 1: Label to RFC Mapping 228 1.2. Specification Language 230 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 231 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 232 "OPTIONAL" in this document are to be interpreted as described in BCP 233 14 [RFC2119] [RFC8174] when, and only when, they appear in all 234 capitals, as shown here. 236 1.3. Adherence to the NMDA 238 This document in compliant with the Network Management Datastore 239 Architecture (NMDA) [RFC8342]. For instance, as described in 240 [I-D.ietf-netconf-trust-anchors] and [I-D.ietf-netconf-keystore], 241 trust anchors and keys installed during manufacturing are expected to 242 appear in . 244 2. The "ietf-ssh-common" Module 246 The SSH common model presented in this section contains identities 247 and groupings common to both SSH clients and SSH servers. The 248 "transport-params-grouping" grouping can be used to configure the 249 list of SSH transport algorithms permitted by the SSH client or SSH 250 server. The lists of algorithms are ordered such that, if multiple 251 algorithms are permitted by the client, the algorithm that appears 252 first in its list that is also permitted by the server is used for 253 the SSH transport layer connection. The ability to restrict the 254 algorithms allowed is provided in this grouping for SSH clients and 255 SSH servers that are capable of doing so and may serve to make SSH 256 clients and SSH servers compliant with security policies. 258 Features are defined for algorithms that are OPTIONAL or are not 259 widely supported by popular implementations. Note that the list of 260 algorithms is not exhaustive. As well, some algorithms that are 261 REQUIRED by [RFC4253] are missing, notably "ssh-dss" and "diffie- 262 hellman-group1-sha1" due to their weak security and there being 263 alternatives that are widely supported. 265 2.1. Data Model Overview 267 This section provides an overview of the "ietf-ssh-common" module in 268 terms of its features, identities, and groupings. 270 2.1.1. Features 272 The following diagram lists all the "feature" statements defined in 273 the "ietf-ssh-common" module: 275 Features: 276 +-- ssh-ecc 277 +-- ssh-x509-certs 278 +-- ssh-dh-group-exchange 279 +-- ssh-ctr 280 +-- ssh-sha2 282 | The diagram above uses syntax that is similar to but not 283 | defined in [RFC8340]. 285 2.1.2. Identities 287 The following diagram illustrates the relationship amongst the 288 "identity" statements defined in the "ietf-ssh-common" module: 290 Identities: 291 +-- public-key-alg-base 292 | +-- ssh-dss 293 | +-- ssh-rsa 294 | +-- ecdsa-sha2-nistp256 295 | +-- ecdsa-sha2-nistp384 296 | +-- ecdsa-sha2-nistp521 297 | +-- x509v3-ssh-rsa 298 | +-- x509v3-rsa2048-sha256 299 | +-- x509v3-ecdsa-sha2-nistp256 300 | +-- x509v3-ecdsa-sha2-nistp384 301 | +-- x509v3-ecdsa-sha2-nistp521 302 +-- key-exchange-alg-base 303 | +-- diffie-hellman-group14-sha1 304 | +-- diffie-hellman-group-exchange-sha1 305 | +-- diffie-hellman-group-exchange-sha256 306 | +-- ecdh-sha2-nistp256 307 | +-- ecdh-sha2-nistp384 308 | +-- ecdh-sha2-nistp521 309 +-- encryption-alg-base 310 | +-- triple-des-cbc 311 | +-- aes128-cbc 312 | +-- aes192-cbc 313 | +-- aes256-cbc 314 | +-- aes128-ctr 315 | +-- aes192-ctr 316 | +-- aes256-ctr 317 +-- mac-alg-base 318 +-- hmac-sha1 319 +-- hmac-sha2-256 320 +-- hmac-sha2-512 322 | The diagram above uses syntax that is similar to but not 323 | defined in [RFC8340]. 325 Comments: 327 * The diagram shows that there are four base identities. 328 * These identities are used by this module to define algorithms for 329 public-key, key-exchange, encryption, and MACs. 330 * These base identities are "abstract", in the object orientied 331 programming sense, in that they only define a "class" of 332 algorithms, rather than a specific algorithm. 334 2.1.3. Groupings 336 The following diagram lists all the "grouping" statements defined in 337 the "ietf-ssh-common" module: 339 Groupings: 340 +-- transport-params-grouping 342 | The diagram above uses syntax that is similar to but not 343 | defined in [RFC8340]. 345 Each of these groupings are presented in the following subsections. 347 2.1.3.1. The "transport-params-grouping" Grouping 349 The following tree diagram [RFC8340] illustrates the "transport- 350 params-grouping" grouping: 352 grouping transport-params-grouping 353 +-- host-key 354 | +-- host-key-alg* identityref 355 +-- key-exchange 356 | +-- key-exchange-alg* identityref 357 +-- encryption 358 | +-- encryption-alg* identityref 359 +-- mac 360 +-- mac-alg* identityref 362 Comments: 364 * This grouping is used by both the "ssh-client-grouping" and the 365 "ssh-server-grouping" groupings defined in Section 3.1.2.1 and 366 Section 4.1.2.1, respectively. 368 * This grouping enables client and server configurations to specify 369 the algorithms that are to be used when establishing SSH sessions. 371 * Each list is "ordered-by user". 373 2.1.4. Protocol-accessible Nodes 375 The "ietf-ssh-common" module does not contain any protocol-accessible 376 nodes, but the module needs to be "implemented", as described in 377 Section 5.6.5 of [RFC7950], in order for the identities in 378 Section 2.1.2 to be defined. 380 2.2. Example Usage 382 This following example illustrates how the "transport-params- 383 grouping' grouping appears when populated with some data. 385 388 389 algs:x509v3-rsa2048-sha256 390 algs:ssh-rsa 391 392 393 394 algs:diffie-hellman-group-exchange-sha256 395 396 397 398 algs:aes256-ctr 399 algs:aes192-ctr 400 algs:aes128-ctr 401 algs:aes256-cbc 402 algs:aes192-cbc 403 algs:aes128-cbc 404 405 406 algs:hmac-sha2-256 407 algs:hmac-sha2-512 408 409 411 2.3. YANG Module 413 This YANG module has normative references to [RFC4253], [RFC4344], 414 [RFC4419], [RFC5656], [RFC6187], and [RFC6668]. 416 file "ietf-ssh-common@2020-08-20.yang" 417 module ietf-ssh-common { 418 yang-version 1.1; 419 namespace "urn:ietf:params:xml:ns:yang:ietf-ssh-common"; 420 prefix sshcmn; 422 organization 423 "IETF NETCONF (Network Configuration) Working Group"; 425 contact 426 "WG Web: 427 WG List: 428 Author: Kent Watsen 429 Author: Gary Wu "; 431 description 432 "This module defines a common features, identities, and 433 groupings for Secure Shell (SSH). 435 Copyright (c) 2020 IETF Trust and the persons identified 436 as authors of the code. All rights reserved. 438 Redistribution and use in source and binary forms, with 439 or without modification, is permitted pursuant to, and 440 subject to the license terms contained in, the Simplified 441 BSD License set forth in Section 4.c of the IETF Trust's 442 Legal Provisions Relating to IETF Documents 443 (https://trustee.ietf.org/license-info). 445 This version of this YANG module is part of RFC EEEE 446 (https://www.rfc-editor.org/info/rfcEEEE); see the RFC 447 itself for full legal notices.; 449 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 450 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 451 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 452 are to be interpreted as described in BCP 14 (RFC 2119) 453 (RFC 8174) when, and only when, they appear in all 454 capitals, as shown here."; 456 revision 2020-08-20 { 457 description 458 "Initial version"; 459 reference 460 "RFC EEEE: YANG Groupings for SSH Clients and SSH Servers"; 461 } 463 // Features 464 feature ssh-ecc { 465 description 466 "Elliptic Curve Cryptography is supported for SSH."; 467 reference 468 "RFC 5656: Elliptic Curve Algorithm Integration in the 469 Secure Shell Transport Layer"; 470 } 472 feature ssh-x509-certs { 473 description 474 "X.509v3 certificates are supported for SSH per RFC 6187."; 475 reference 476 "RFC 6187: X.509v3 Certificates for Secure Shell 477 Authentication"; 478 } 480 feature ssh-dh-group-exchange { 481 description 482 "Diffie-Hellman Group Exchange is supported for SSH."; 483 reference 484 "RFC 4419: Diffie-Hellman Group Exchange for the 485 Secure Shell (SSH) Transport Layer Protocol"; 486 } 488 feature ssh-ctr { 489 description 490 "SDCTR encryption mode is supported for SSH."; 491 reference 492 "RFC 4344: The Secure Shell (SSH) Transport Layer 493 Encryption Modes"; 494 } 496 feature ssh-sha2 { 497 description 498 "The SHA2 family of cryptographic hash functions is 499 supported for SSH."; 500 reference 501 "FIPS PUB 180-4: Secure Hash Standard (SHS)"; 502 } 504 // Identities 506 identity public-key-alg-base { 507 description 508 "Base identity used to identify public key algorithms."; 509 } 511 identity ssh-dss { 512 base public-key-alg-base; 513 description 514 "Digital Signature Algorithm using SHA-1 as the 515 hashing algorithm."; 516 reference 517 "RFC 4253: 518 The Secure Shell (SSH) Transport Layer Protocol"; 519 } 521 identity ssh-rsa { 522 base public-key-alg-base; 523 description 524 "RSASSA-PKCS1-v1_5 signature scheme using SHA-1 as the 525 hashing algorithm."; 526 reference 527 "RFC 4253: 528 The Secure Shell (SSH) Transport Layer Protocol"; 529 } 531 identity ecdsa-sha2-nistp256 { 532 if-feature "ssh-ecc and ssh-sha2"; 533 base public-key-alg-base; 534 description 535 "Elliptic Curve Digital Signature Algorithm (ECDSA) using the 536 nistp256 curve and the SHA2 family of hashing algorithms."; 537 reference 538 "RFC 5656: Elliptic Curve Algorithm Integration in the 539 Secure Shell Transport Layer"; 540 } 542 identity ecdsa-sha2-nistp384 { 543 if-feature "ssh-ecc and ssh-sha2"; 544 base public-key-alg-base; 545 description 546 "Elliptic Curve Digital Signature Algorithm (ECDSA) using the 547 nistp384 curve and the SHA2 family of hashing algorithms."; 548 reference 549 "RFC 5656: Elliptic Curve Algorithm Integration in the 550 Secure Shell Transport Layer"; 551 } 553 identity ecdsa-sha2-nistp521 { 554 if-feature "ssh-ecc and ssh-sha2"; 555 base public-key-alg-base; 556 description 557 "Elliptic Curve Digital Signature Algorithm (ECDSA) using the 558 nistp521 curve and the SHA2 family of hashing algorithms."; 559 reference 560 "RFC 5656: Elliptic Curve Algorithm Integration in the 561 Secure Shell Transport Layer"; 562 } 564 identity x509v3-ssh-rsa { 565 if-feature "ssh-x509-certs"; 566 base public-key-alg-base; 567 description 568 "RSASSA-PKCS1-v1_5 signature scheme using a public key stored 569 in an X.509v3 certificate and using SHA-1 as the hashing 570 algorithm."; 571 reference 572 "RFC 6187: X.509v3 Certificates for Secure Shell 573 Authentication"; 574 } 576 identity x509v3-rsa2048-sha256 { 577 if-feature "ssh-x509-certs and ssh-sha2"; 578 base public-key-alg-base; 579 description 580 "RSASSA-PKCS1-v1_5 signature scheme using a public key stored 581 in an X.509v3 certificate and using SHA-256 as the hashing 582 algorithm. RSA keys conveyed using this format MUST have a 583 modulus of at least 2048 bits."; 584 reference 585 "RFC 6187: X.509v3 Certificates for Secure Shell 586 Authentication"; 587 } 589 identity x509v3-ecdsa-sha2-nistp256 { 590 if-feature "ssh-ecc and ssh-x509-certs and ssh-sha2"; 591 base public-key-alg-base; 592 description 593 "Elliptic Curve Digital Signature Algorithm (ECDSA) 594 using the nistp256 curve with a public key stored in 595 an X.509v3 certificate and using the SHA2 family of 596 hashing algorithms."; 597 reference 598 "RFC 6187: X.509v3 Certificates for Secure Shell 599 Authentication"; 600 } 602 identity x509v3-ecdsa-sha2-nistp384 { 603 if-feature "ssh-ecc and ssh-x509-certs and ssh-sha2"; 604 base public-key-alg-base; 605 description 606 "Elliptic Curve Digital Signature Algorithm (ECDSA) 607 using the nistp384 curve with a public key stored in 608 an X.509v3 certificate and using the SHA2 family of 609 hashing algorithms."; 610 reference 611 "RFC 6187: X.509v3 Certificates for Secure Shell 612 Authentication"; 613 } 615 identity x509v3-ecdsa-sha2-nistp521 { 616 if-feature "ssh-ecc and ssh-x509-certs and ssh-sha2"; 617 base public-key-alg-base; 618 description 619 "Elliptic Curve Digital Signature Algorithm (ECDSA) 620 using the nistp521 curve with a public key stored in 621 an X.509v3 certificate and using the SHA2 family of 622 hashing algorithms."; 623 reference 624 "RFC 6187: X.509v3 Certificates for Secure Shell 625 Authentication"; 626 } 628 identity key-exchange-alg-base { 629 description 630 "Base identity used to identify key exchange algorithms."; 631 } 633 identity diffie-hellman-group14-sha1 { 634 base key-exchange-alg-base; 635 description 636 "Diffie-Hellman key exchange with SHA-1 as HASH and 637 Oakley Group 14 (2048-bit MODP Group)."; 638 reference 639 "RFC 4253: The Secure Shell (SSH) Transport Layer Protocol"; 640 } 642 identity diffie-hellman-group-exchange-sha1 { 643 if-feature "ssh-dh-group-exchange"; 644 base key-exchange-alg-base; 645 description 646 "Diffie-Hellman Group and Key Exchange with SHA-1 as HASH."; 647 reference 648 "RFC 4419: Diffie-Hellman Group Exchange for the 649 Secure Shell (SSH) Transport Layer Protocol"; 650 } 652 identity diffie-hellman-group-exchange-sha256 { 653 if-feature "ssh-dh-group-exchange and ssh-sha2"; 654 base key-exchange-alg-base; 655 description 656 "Diffie-Hellman Group and Key Exchange with SHA-256 as HASH."; 657 reference 658 "RFC 4419: Diffie-Hellman Group Exchange for the 659 Secure Shell (SSH) Transport Layer Protocol"; 660 } 662 identity ecdh-sha2-nistp256 { 663 if-feature "ssh-ecc and ssh-sha2"; 664 base key-exchange-alg-base; 665 description 666 "Elliptic Curve Diffie-Hellman (ECDH) key exchange using the 667 nistp256 curve and the SHA2 family of hashing algorithms."; 668 reference 669 "RFC 5656: Elliptic Curve Algorithm Integration in the 670 Secure Shell Transport Layer"; 671 } 673 identity ecdh-sha2-nistp384 { 674 if-feature "ssh-ecc and ssh-sha2"; 675 base key-exchange-alg-base; 676 description 677 "Elliptic Curve Diffie-Hellman (ECDH) key exchange using the 678 nistp384 curve and the SHA2 family of hashing algorithms."; 679 reference 680 "RFC 5656: Elliptic Curve Algorithm Integration in the 681 Secure Shell Transport Layer"; 682 } 684 identity ecdh-sha2-nistp521 { 685 if-feature "ssh-ecc and ssh-sha2"; 686 base key-exchange-alg-base; 687 description 688 "Elliptic Curve Diffie-Hellman (ECDH) key exchange using the 689 nistp521 curve and the SHA2 family of hashing algorithms."; 690 reference 691 "RFC 5656: Elliptic Curve Algorithm Integration in the 692 Secure Shell Transport Layer"; 693 } 695 identity encryption-alg-base { 696 description 697 "Base identity used to identify encryption algorithms."; 698 } 700 identity triple-des-cbc { 701 base encryption-alg-base; 702 description 703 "Three-key 3DES in CBC mode."; 705 reference 706 "RFC 4253: The Secure Shell (SSH) Transport Layer Protocol"; 707 } 709 identity aes128-cbc { 710 base encryption-alg-base; 711 description 712 "AES in CBC mode, with a 128-bit key."; 713 reference 714 "RFC 4253: The Secure Shell (SSH) Transport Layer Protocol"; 715 } 717 identity aes192-cbc { 718 base encryption-alg-base; 719 description 720 "AES in CBC mode, with a 192-bit key."; 721 reference 722 "RFC 4253: The Secure Shell (SSH) Transport Layer Protocol"; 723 } 725 identity aes256-cbc { 726 base encryption-alg-base; 727 description 728 "AES in CBC mode, with a 256-bit key."; 729 reference 730 "RFC 4253: The Secure Shell (SSH) Transport Layer Protocol"; 731 } 733 identity aes128-ctr { 734 if-feature "ssh-ctr"; 735 base encryption-alg-base; 736 description 737 "AES in SDCTR mode, with 128-bit key."; 738 reference 739 "RFC 4344: The Secure Shell (SSH) Transport Layer Encryption 740 Modes"; 741 } 743 identity aes192-ctr { 744 if-feature "ssh-ctr"; 745 base encryption-alg-base; 746 description 747 "AES in SDCTR mode, with 192-bit key."; 748 reference 749 "RFC 4344: The Secure Shell (SSH) Transport Layer Encryption 750 Modes"; 751 } 752 identity aes256-ctr { 753 if-feature "ssh-ctr"; 754 base encryption-alg-base; 755 description 756 "AES in SDCTR mode, with 256-bit key."; 757 reference 758 "RFC 4344: The Secure Shell (SSH) Transport Layer Encryption 759 Modes"; 760 } 762 identity mac-alg-base { 763 description 764 "Base identity used to identify message authentication 765 code (MAC) algorithms."; 766 } 768 identity hmac-sha1 { 769 base mac-alg-base; 770 description 771 "HMAC-SHA1"; 772 reference 773 "RFC 4253: The Secure Shell (SSH) Transport Layer Protocol"; 774 } 776 identity hmac-sha2-256 { 777 if-feature "ssh-sha2"; 778 base mac-alg-base; 779 description 780 "HMAC-SHA2-256"; 781 reference 782 "RFC 6668: SHA-2 Data Integrity Verification for the 783 Secure Shell (SSH) Transport Layer Protocol"; 784 } 786 identity hmac-sha2-512 { 787 if-feature "ssh-sha2"; 788 base mac-alg-base; 789 description 790 "HMAC-SHA2-512"; 791 reference 792 "RFC 6668: SHA-2 Data Integrity Verification for the 793 Secure Shell (SSH) Transport Layer Protocol"; 794 } 796 // Groupings 798 grouping transport-params-grouping { 799 description 800 "A reusable grouping for SSH transport parameters."; 801 reference 802 "RFC 4253: The Secure Shell (SSH) Transport Layer Protocol"; 803 container host-key { 804 description 805 "Parameters regarding host key."; 806 leaf-list host-key-alg { 807 type identityref { 808 base public-key-alg-base; 809 } 810 ordered-by user; 811 description 812 "Acceptable host key algorithms 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 EEEE for 816 valid combinations. 818 If this leaf-list is not configured (has zero elements) 819 the acceptable host key algorithms are implementation- 820 defined."; 821 reference 822 "RFC EEEE: YANG Groupings for SSH Clients and SSH Servers"; 823 } 824 } 825 container key-exchange { 826 description 827 "Parameters regarding key exchange."; 828 leaf-list key-exchange-alg { 829 type identityref { 830 base key-exchange-alg-base; 831 } 832 ordered-by user; 833 description 834 "Acceptable key exchange algorithms in order of descending 835 preference. 837 If this leaf-list is not configured (has zero elements) 838 the acceptable key exchange algorithms are implementation 839 defined."; 840 } 841 } 842 container encryption { 843 description 844 "Parameters regarding encryption."; 845 leaf-list encryption-alg { 846 type identityref { 847 base encryption-alg-base; 849 } 850 ordered-by user; 851 description 852 "Acceptable encryption algorithms in order of descending 853 preference. 855 If this leaf-list is not configured (has zero elements) 856 the acceptable encryption algorithms are implementation 857 defined."; 858 } 859 } 860 container mac { 861 description 862 "Parameters regarding message authentication code (MAC)."; 863 leaf-list mac-alg { 864 type identityref { 865 base mac-alg-base; 866 } 867 ordered-by user; 868 description 869 "Acceptable MAC algorithms in order of descending 870 preference. 872 If this leaf-list is not configured (has zero elements) 873 the acceptable MAC algorithms are implementation- 874 defined."; 875 } 876 } 877 } 878 } 880 882 3. The "ietf-ssh-client" Module 884 This section defines a YANG 1.1 [RFC7950] module called "ietf-ssh- 885 client". A high-level overview of the module is provided in 886 Section 3.1. Examples illustatrating the module's use are provided 887 in Examples (Section 3.2). The YANG module itself is defined in 888 Section 3.3. 890 3.1. Data Model Overview 892 This section provides an overview of the "ietf-ssh-client" module in 893 terms of its features and groupings. 895 3.1.1. Features 897 The following diagram lists all the "feature" statements defined in 898 the "ietf-ssh-client" module: 900 Features: 901 +-- ssh-client-transport-params-config 902 +-- ssh-client-keepalives 903 +-- client-identity-password 904 +-- client-identity-publickey 905 +-- client-identity-hostbased 906 +-- client-identity-none 908 | The diagram above uses syntax that is similar to but not 909 | defined in [RFC8340]. 911 3.1.2. Groupings 913 The following diagram lists all the "grouping" statements defined in 914 the "ietf-ssh-client" module: 916 Groupings: 917 +-- ssh-client-grouping 919 | The diagram above uses syntax that is similar to but not 920 | defined in [RFC8340]. 922 Each of these groupings are presented in the following subsections. 924 3.1.2.1. The "ssh-client-grouping" Grouping 926 The following tree diagram [RFC8340] illustrates the "ssh-client- 927 grouping" grouping: 929 =============== NOTE: '\' line wrapping per RFC 8792 ================ 931 grouping ssh-client-grouping 932 +-- client-identity 933 | +-- username? string 934 | +-- public-key! {client-identity-publickey}? 935 | | +---u ks:local-or-keystore-asymmetric-key-grouping 936 | +-- password! {client-identity-password}? 937 | | +---u ct:password-grouping 938 | +-- hostbased! {client-identity-hostbased}? 939 | | +---u ks:local-or-keystore-asymmetric-key-grouping 940 | +-- none? empty {client-identity-none}? 941 | +-- certificate! {sshcmn:ssh-x509-certs}? 942 | +---u ks:local-or-keystore-end-entity-cert-with-key-groupi\ 943 ng 944 +-- server-authentication 945 | +-- ssh-host-keys! 946 | | +---u ts:local-or-truststore-public-keys-grouping 947 | +-- ca-certs! {sshcmn:ssh-x509-certs}? 948 | | +---u ts:local-or-truststore-certs-grouping 949 | +-- ee-certs! {sshcmn:ssh-x509-certs}? 950 | +---u ts:local-or-truststore-certs-grouping 951 +-- transport-params {ssh-client-transport-params-config}? 952 | +---u sshcmn:transport-params-grouping 953 +-- keepalives! {ssh-client-keepalives}? 954 +-- max-wait? uint16 955 +-- max-attempts? uint8 957 Comments: 959 * The "client-identity" node configures a "username" and 960 credentials, each enabled by a "feature" statement defined in 961 Section 3.1.1. 963 * The "server-authentication" node configures trust anchors for 964 authenticating the SSH server, with each option enabled by a 965 "feature" statement. 967 * The "transport-params" node, which must be enabled by a feature, 968 configures parameters for the SSH sessions established by this 969 configuration. 971 * The "keepalives" node, which must be enabled by a feature, 972 configures a "presence" container for testing the aliveness of the 973 SSH server. The aliveness-test occurs at the SSH protocol layer. 975 * For the referenced grouping statement(s): 977 - The "local-or-keystore-asymmetric-key-grouping" grouping is 978 discussed in Section 2.1.3.4 of [I-D.ietf-netconf-keystore]. 979 - The "local-or-keystore-end-entity-cert-with-key-grouping" 980 grouping is discussed in Section 2.1.3.6 of 981 [I-D.ietf-netconf-keystore]. 982 - The "local-or-truststore-public-keys-grouping" grouping is 983 discussed in Section 2.1.3.2 of 984 [I-D.ietf-netconf-trust-anchors]. 985 - The "local-or-truststore-certs-grouping" grouping is discussed 986 in Section 2.1.3.1 of [I-D.ietf-netconf-trust-anchors]. 987 - The "transport-params-grouping" grouping is discussed in 988 Section 2.1.3.1 in this document. 990 3.2. Example Usage 992 This section presents two examples showing the "ssh-client-grouping" 993 grouping populated with some data. These examples are effectively 994 the same except the first configures the client identity using a 995 local key while the second uses a key configured in a keystore. Both 996 examples are consistent with the examples presented in Section 2 of 997 [I-D.ietf-netconf-trust-anchors] and Section 3.2 of 998 [I-D.ietf-netconf-keystore]. 1000 The following configuration example uses local-definitions for the 1001 client identity and server authentication: 1003 =============== NOTE: '\' line wrapping per RFC 8792 ================ 1005 1010 1011 1012 foobar 1013 1014 1015 ct:ssh-public-key-format 1017 base64encodedvalue== 1018 ct:rsa-private-key-format 1020 base64encodedvalue== 1022 1023 1024 1025 1026 1027 1028 1029 1030 corp-fw1 1031 ct:ssh-public-key-format 1033 base64encodedvalue== 1034 1035 1036 corp-fw2 1037 ct:ssh-public-key-format 1039 base64encodedvalue== 1040 1041 1042 1043 1044 1045 1046 Server Cert Issuer #1 1047 base64encodedvalue== 1048 1049 1050 Server Cert Issuer #2 1051 base64encodedvalue== 1052 1053 1054 1055 1056 1057 1058 My Application #1 1059 base64encodedvalue== 1060 1061 1062 My Application #2 1063 base64encodedvalue== 1064 1065 1066 1067 1069 1070 30 1071 3 1072 1074 1076 The following configuration example uses keystore-references for the 1077 client identity and truststore-references for server authentication: 1078 from the keystore: 1080 =============== NOTE: '\' line wrapping per RFC 8792 ================ 1082 1086 1087 1088 foobar 1089 1094 1095 1096 ssh-rsa-key-with-cert 1097 ex-rsa-cert2 1098 1099 1100 1102 1103 1104 1105 trusted-ssh-public-keys 1107 1108 1109 trusted-server-ca-certs 1111 1112 1113 trusted-server-ee-certs 1115 1116 1118 1119 30 1120 3 1121 1123 1125 3.3. YANG Module 1127 This YANG module has normative references to 1128 [I-D.ietf-netconf-trust-anchors], and [I-D.ietf-netconf-keystore]. 1130 file "ietf-ssh-client@2020-08-20.yang" 1132 module ietf-ssh-client { 1133 yang-version 1.1; 1134 namespace "urn:ietf:params:xml:ns:yang:ietf-ssh-client"; 1135 prefix sshc; 1137 import ietf-netconf-acm { 1138 prefix nacm; 1139 reference 1140 "RFC 8341: Network Configuration Access Control Model"; 1141 } 1143 import ietf-crypto-types { 1144 prefix ct; 1145 reference 1146 "RFC AAAA: YANG Data Types and Groupings for Cryptography"; 1147 } 1149 import ietf-truststore { 1150 prefix ts; 1151 reference 1152 "RFC BBBB: A YANG Data Model for a Truststore"; 1153 } 1155 import ietf-keystore { 1156 prefix ks; 1157 reference 1158 "RFC CCCC: A YANG Data Model for a Keystore"; 1159 } 1161 import ietf-ssh-common { 1162 prefix sshcmn; 1163 revision-date 2020-08-20; // stable grouping definitions 1164 reference 1165 "RFC EEEE: YANG Groupings for SSH Clients and SSH Servers"; 1166 } 1168 organization 1169 "IETF NETCONF (Network Configuration) Working Group"; 1171 contact 1172 "WG Web: 1173 WG List: 1174 Author: Kent Watsen 1175 Author: Gary Wu "; 1177 description 1178 "This module defines reusable groupings for SSH clients that 1179 can be used as a basis for specific SSH client instances. 1181 Copyright (c) 2020 IETF Trust and the persons identified 1182 as authors of the code. All rights reserved. 1184 Redistribution and use in source and binary forms, with 1185 or without modification, is permitted pursuant to, and 1186 subject to the license terms contained in, the Simplified 1187 BSD License set forth in Section 4.c of the IETF Trust's 1188 Legal Provisions Relating to IETF Documents 1189 (https://trustee.ietf.org/license-info). 1191 This version of this YANG module is part of RFC EEEE 1192 (https://www.rfc-editor.org/info/rfcEEEE); see the RFC 1193 itself for full legal notices.; 1195 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1196 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 1197 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 1198 are to be interpreted as described in BCP 14 (RFC 2119) 1199 (RFC 8174) when, and only when, they appear in all 1200 capitals, as shown here."; 1202 revision 2020-08-20 { 1203 description 1204 "Initial version"; 1205 reference 1206 "RFC EEEE: YANG Groupings for SSH Clients and SSH Servers"; 1207 } 1209 // Features 1211 feature ssh-client-transport-params-config { 1212 description 1213 "SSH transport layer parameters are configurable on an SSH 1214 client."; 1215 } 1217 feature ssh-client-keepalives { 1218 description 1219 "Per socket SSH keepalive parameters are configurable for 1220 SSH clients on the server implementing this feature."; 1222 } 1224 feature client-identity-password { 1225 description 1226 "Indicates that the 'password' authentication type 1227 is supported for client identification."; 1228 } 1230 feature client-identity-publickey { 1231 description 1232 "Indicates that the 'publickey' authentication type 1233 is supported for client identification. 1235 The 'publickey' authentication type is required by 1236 RFC 4252, but common implementations enable it to 1237 be disabled."; 1238 } 1240 feature client-identity-hostbased { 1241 description 1242 "Indicates that the 'hostbased' authentication type 1243 is supported for client identification."; 1244 } 1246 feature client-identity-none { 1247 description 1248 "Indicates that the 'none' authentication type is 1249 supported for client identification."; 1250 } 1252 // Groupings 1254 grouping ssh-client-grouping { 1255 description 1256 "A reusable grouping for configuring a SSH client without 1257 any consideration for how an underlying TCP session is 1258 established. 1260 Note that this grouping uses fairly typical descendent 1261 node names such that a stack of 'uses' statements will 1262 have name conflicts. It is intended that the consuming 1263 data model will resolve the issue (e.g., by wrapping 1264 the 'uses' statement in a container called 1265 'ssh-client-parameters'). This model purposely does 1266 not do this itself so as to provide maximum flexibility 1267 to consuming models."; 1269 container client-identity { 1270 nacm:default-deny-write; 1271 must 1272 'public-key or password or hostbased or none or certificate'; 1273 description 1274 "The credentials that the client may use, pending 1275 the SSH server's requirements, by the SSH client 1276 to authenticate to the SSH server."; 1277 leaf username { 1278 type string; 1279 description 1280 "The username of this user. This will be the username 1281 used, for instance, to log into an SSH server."; 1282 } 1283 container public-key { 1284 if-feature client-identity-publickey; 1285 presence 1286 "Indicates that publickey-based authentication 1287 is configured"; 1288 description 1289 "A locally-defined or referenced asymmetric key 1290 pair to be used for client identification."; 1291 reference 1292 "RFC CCCC: A YANG Data Model for a Keystore"; 1293 uses ks:local-or-keystore-asymmetric-key-grouping { 1294 refine "local-or-keystore/local/local-definition" { 1295 must 'public-key-format = "ct:ssh-public-key-format"'; 1296 } 1297 refine "local-or-keystore/keystore/keystore-reference" { 1298 must 'deref(.)/../ks:public-key-format' 1299 + ' = "ct:ssh-public-key-format"'; 1300 } 1301 } 1302 } 1303 container password { 1304 if-feature client-identity-password; 1305 presence 1306 "Indicates that password-based authenitcation is 1307 configured."; 1308 description 1309 "A password to be used to authenicate the client's 1310 identity."; 1311 uses ct:password-grouping; 1312 } 1313 container hostbased { 1314 if-feature client-identity-hostbased; 1315 presence 1316 "Indicates that hostbased authentication is configured"; 1317 description 1318 "A locally-defined or referenced asymmetric key 1319 pair to be used for host identification."; 1320 reference 1321 "RFC CCCC: A YANG Data Model for a Keystore"; 1322 uses ks:local-or-keystore-asymmetric-key-grouping { 1323 refine "local-or-keystore/local/local-definition" { 1324 must 'public-key-format = "ct:ssh-public-key-format"'; 1325 } 1326 refine "local-or-keystore/keystore/keystore-reference" { 1327 must 'deref(.)/../ks:public-key-format' 1328 + ' = "ct:ssh-public-key-format"'; 1329 } 1330 } 1331 } 1332 leaf none { 1333 if-feature client-identity-none; 1334 type empty; 1335 description 1336 "Indicates that 'none' algorithm is used for client 1337 identification."; 1338 } 1339 container certificate { 1340 if-feature "sshcmn:ssh-x509-certs"; 1341 presence 1342 "Indicates that certificate-based authentication 1343 is configured"; 1344 description 1345 "A locally-defined or referenced certificate 1346 to be used for client identification."; 1347 reference 1348 "RFC CCCC: A YANG Data Model for a Keystore"; 1349 uses 1350 ks:local-or-keystore-end-entity-cert-with-key-grouping { 1351 refine "local-or-keystore/local/local-definition" { 1352 must 1353 'public-key-format' 1354 + ' = "ct:subject-public-key-info-format"'; 1355 } 1356 refine "local-or-keystore/keystore/keystore-reference" 1357 + "/asymmetric-key" { 1358 must 'deref(.)/../ks:public-key-format' 1359 + ' = "ct:subject-public-key-info-format"'; 1360 } 1361 } 1362 } 1363 } // container client-identity 1365 container server-authentication { 1366 nacm:default-deny-write; 1367 must 'ssh-host-keys or ca-certs or ee-certs'; 1368 description 1369 "Specifies how the SSH client can authenticate SSH servers. 1370 Any combination of credentials is additive and unordered."; 1371 container ssh-host-keys { 1372 presence 1373 "Indicates that the client can authenticate servers 1374 using the configured SSH host keys."; 1375 description 1376 "A list of SSH host keys used by the SSH client to 1377 authenticate SSH server host keys. A server host key 1378 is authenticated if it is an exact match to a 1379 configured SSH host key."; 1380 reference 1381 "RFC BBBB: A YANG Data Model for a Truststore"; 1382 uses ts:local-or-truststore-public-keys-grouping { 1383 refine 1384 "local-or-truststore/local/local-definition/public-key" { 1385 must 'public-key-format = "ct:ssh-public-key-format"'; 1386 } 1387 refine 1388 "local-or-truststore/truststore/truststore-reference" { 1389 must 'deref(.)/../*/ts:public-key-format' 1390 + ' = "ct:ssh-public-key-format"'; 1391 } 1392 } 1393 } 1394 container ca-certs { 1395 if-feature "sshcmn:ssh-x509-certs"; 1396 presence 1397 "Indicates that the client can authenticate servers 1398 using the configured trust anchor certificates."; 1399 description 1400 "A set of certificate authority (CA) certificates used by 1401 the SSH client to authenticate SSH servers. A server 1402 is authenticated if its certificate has a valid chain 1403 of trust to a configured CA certificate."; 1404 reference 1405 "RFC BBBB: A YANG Data Model for a Truststore"; 1406 uses ts:local-or-truststore-certs-grouping; 1407 } 1408 container ee-certs { 1409 if-feature "sshcmn:ssh-x509-certs"; 1410 presence 1411 "Indicates that the client can authenticate servers 1412 using the configured end-entity certificates."; 1413 description 1414 "A set of end-entity certificates used by the SSH client 1415 to authenticate SSH servers. A server is authenticated 1416 if its certificate is an exact match to a configured 1417 end-entity certificate."; 1418 reference 1419 "RFC BBBB: A YANG Data Model for a Truststore"; 1420 uses ts:local-or-truststore-certs-grouping; 1421 } 1422 } // container server-authentication 1424 container transport-params { 1425 nacm:default-deny-write; 1426 if-feature "ssh-client-transport-params-config"; 1427 description 1428 "Configurable parameters of the SSH transport layer."; 1429 uses sshcmn:transport-params-grouping; 1430 } // container transport-parameters 1432 container keepalives { 1433 nacm:default-deny-write; 1434 if-feature "ssh-client-keepalives"; 1435 presence 1436 "Indicates that the SSH client proactively tests the 1437 aliveness of the remote SSH server."; 1438 description 1439 "Configures the keep-alive policy, to proactively test 1440 the aliveness of the SSH server. An unresponsive TLS 1441 server is dropped after approximately max-wait * 1442 max-attempts seconds. Per Section 4 of RFC 4254, 1443 the SSH client SHOULD send an SSH_MSG_GLOBAL_REQUEST 1444 message with a purposely nonexistent 'request name' 1445 value (e.g., keepalive@ietf.org) and the 'want reply' 1446 value set to '1'."; 1447 reference 1448 "RFC 4254: The Secure Shell (SSH) Connection Protocol"; 1449 leaf max-wait { 1450 type uint16 { 1451 range "1..max"; 1452 } 1453 units "seconds"; 1454 default "30"; 1455 description 1456 "Sets the amount of time in seconds after which if 1457 no data has been received from the SSH server, a 1458 TLS-level message will be sent to test the 1459 aliveness of the SSH server."; 1460 } 1461 leaf max-attempts { 1462 type uint8; 1463 default "3"; 1464 description 1465 "Sets the maximum number of sequential keep-alive 1466 messages that can fail to obtain a response from 1467 the SSH server before assuming the SSH server is 1468 no longer alive."; 1469 } 1470 } // container keepalives 1471 } // grouping ssh-client-grouping 1472 } // module ietf-ssh-client 1474 1476 4. The "ietf-ssh-server" Module 1478 This section defines a YANG 1.1 [RFC7950] module called "ietf-ssh- 1479 server". A high-level overview of the module is provided in 1480 Section 4.1. Examples illustatrating the module's use are provided 1481 in Examples (Section 4.2). The YANG module itself is defined in 1482 Section 4.3. 1484 4.1. Data Model Overview 1486 This section provides an overview of the "ietf-ssh-server" module in 1487 terms of its features and groupings. 1489 4.1.1. Features 1491 The following diagram lists all the "feature" statements defined in 1492 the "ietf-ssh-server" module: 1494 Features: 1495 +-- ssh-server-transport-params-config 1496 +-- ssh-server-keepalives 1497 +-- client-auth-config-supported 1498 +-- client-auth-publickey 1499 +-- client-auth-password 1500 +-- client-auth-hostbased 1501 +-- client-auth-none 1503 | The diagram above uses syntax that is similar to but not 1504 | defined in [RFC8340]. 1506 4.1.2. Groupings 1508 The following diagram lists all the "grouping" statements defined in 1509 the "ietf-ssh-server" module: 1511 Groupings: 1512 +-- ssh-server-grouping 1514 | The diagram above uses syntax that is similar to but not 1515 | defined in [RFC8340]. 1517 Each of these groupings are presented in the following subsections. 1519 4.1.2.1. The "ssh-server-grouping" Grouping 1521 The following tree diagram [RFC8340] illustrates the "ssh-server- 1522 grouping" grouping: 1524 =============== NOTE: '\' line wrapping per RFC 8792 ================ 1526 grouping ssh-server-grouping 1527 +-- server-identity 1528 | +-- host-key* [name] 1529 | +-- name? string 1530 | +-- (host-key-type) 1531 | +--:(public-key) 1532 | | +-- public-key 1533 | | +---u ks:local-or-keystore-asymmetric-key-grouping 1534 | +--:(certificate) 1535 | +-- certificate {sshcmn:ssh-x509-certs}? 1536 | +---u ks:local-or-keystore-end-entity-cert-with-k\ 1537 ey-grouping 1538 +-- client-authentication 1539 | +-- supported-authentication-methods 1540 | | +-- publickey? empty 1541 | | +-- password? empty {client-auth-password}? 1542 | | +-- hostbased? empty {client-auth-hostbased}? 1543 | | +-- none? empty {client-auth-none}? 1544 | +-- users {client-auth-config-supported}? 1545 | | +-- user* [name] 1546 | | +-- name? string 1547 | | +-- public-keys! {client-auth-publickey}? 1548 | | | +---u ts:local-or-truststore-public-keys-grouping 1549 | | +-- password? ianach:crypt-hash 1550 | | | {client-auth-password}? 1551 | | +-- hostbased! {client-auth-hostbased}? 1552 | | | +---u ts:local-or-truststore-public-keys-grouping 1553 | | +-- none? empty {client-auth-none}? 1554 | +-- ca-certs! 1555 | | {client-auth-config-supported,sshcmn:ssh-x509-certs}? 1556 | | +---u ts:local-or-truststore-certs-grouping 1557 | +-- ee-certs! 1558 | {client-auth-config-supported,sshcmn:ssh-x509-certs}? 1559 | +---u ts:local-or-truststore-certs-grouping 1560 +-- transport-params {ssh-server-transport-params-config}? 1561 | +---u sshcmn:transport-params-grouping 1562 +-- keepalives! {ssh-server-keepalives}? 1563 +-- max-wait? uint16 1564 +-- max-attempts? uint8 1566 Comments: 1568 * The "server-identity" node configures identity credentials. The 1569 ability to use a certificate is enabled by a "feature". 1571 * The "client-authentication" node configures trust anchors for 1572 authenticating the SSH client, with each option enabled by a 1573 "feature" statement. 1575 * The "transport-params" node, which must be enabled by a feature, 1576 configures parameters for the SSH sessions established by this 1577 configuration. 1579 * The "keepalives" node, which must be enabled by a feature, 1580 configures a "presence" container for testing the aliveness of the 1581 SSH client. The aliveness-test occurs at the SSH protocol layer. 1583 * For the referenced grouping statement(s): 1585 - The "local-or-keystore-asymmetric-key-grouping" grouping is 1586 discussed in Section 2.1.3.4 of [I-D.ietf-netconf-keystore]. 1587 - The "local-or-keystore-end-entity-cert-with-key-grouping" 1588 grouping is discussed in Section 2.1.3.6 of 1589 [I-D.ietf-netconf-keystore]. 1590 - The "local-or-truststore-public-keys-grouping" grouping is 1591 discussed in Section 2.1.3.2 of 1592 [I-D.ietf-netconf-trust-anchors]. 1593 - The "local-or-truststore-certs-grouping" grouping is discussed 1594 in Section 2.1.3.1 of [I-D.ietf-netconf-trust-anchors]. 1595 - The "transport-params-grouping" grouping is discussed in 1596 Section 2.1.3.1 in this document. 1598 4.2. Example Usage 1600 This section presents two examples showing the "ssh-server-grouping" 1601 grouping populated with some data. These examples are effectively 1602 the same except the first configures the server identity using a 1603 local key while the second uses a key configured in a keystore. Both 1604 examples are consistent with the examples presented in Section 2 of 1605 [I-D.ietf-netconf-trust-anchors] and Section 3.2 of 1606 [I-D.ietf-netconf-keystore]. 1608 The following configuration example uses local-definitions for the 1609 server identity and client authentication: 1611 =============== NOTE: '\' line wrapping per RFC 8792 ================ 1613 1618 1619 1620 1621 my-pubkey-based-host-key 1622 1623 1624 ct:ssh-public-key-format 1626 base64encodedvalue== 1627 ct:rsa-private-key-format 1629 base64encodedvalue== 1631 1632 1633 1634 1635 my-cert-based-host-key 1636 1637 1638 ct:subject-public-key-info-format 1640 base64encodedvalue== 1641 ct:rsa-private-key-format 1643 base64encodedvalue== 1645 base64encodedvalue== 1646 1647 1648 1649 1651 1652 1653 1654 1655 1656 1657 1658 mary 1659 $0$secret 1660 1661 1662 1663 1664 User A 1665 ct:ssh-public-key-format 1667 base64encodedvalue== 1668 1670 1671 1672 User B 1673 ct:ssh-public-key-format 1675 base64encodedvalue== 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 Identity Cert Issuer #1 1686 base64encodedvalue== 1687 1688 1689 Identity Cert Issuer #2 1690 base64encodedvalue== 1691 1692 1693 1694 1695 1696 1697 Application #1 1698 base64encodedvalue== 1699 1700 1701 Application #2 1702 base64encodedvalue== 1703 1704 1705 1706 1708 1709 30 1710 3 1711 1713 1714 The following configuration example uses keystore-references for the 1715 server identity and truststore-references for client authentication: 1716 from the keystore: 1718 =============== NOTE: '\' line wrapping per RFC 8792 ================ 1720 1724 1725 1726 1727 my-pubkey-based-host-key 1728 1729 ssh-rsa-key 1730 1731 1732 1733 my-cert-based-host-key 1734 1735 1736 ssh-rsa-key-with-cert 1737 ex-rsa-cert2 1738 1739 1740 1741 1743 1744 1745 1746 1747 1748 1749 1750 mary 1751 $0$secret 1752 1753 SSH Public Keys for Application A 1755 1756 1757 1758 1759 trusted-client-ca-certs 1761 1762 1763 trusted-client-ee-certs 1765 1766 1768 1769 30 1770 3 1771 1773 1775 4.3. YANG Module 1777 This YANG module has normative references to 1778 [I-D.ietf-netconf-trust-anchors] and [I-D.ietf-netconf-keystore] and 1779 informative references to [RFC4253] and [RFC7317]. 1781 file "ietf-ssh-server@2020-08-20.yang" 1783 module ietf-ssh-server { 1784 yang-version 1.1; 1785 namespace "urn:ietf:params:xml:ns:yang:ietf-ssh-server"; 1786 prefix sshs; 1788 import iana-crypt-hash { 1789 prefix ianach; 1790 reference 1791 "RFC 7317: A YANG Data Model for System Management"; 1792 } 1794 import ietf-netconf-acm { 1795 prefix nacm; 1796 reference 1797 "RFC 8341: Network Configuration Access Control Model"; 1798 } 1800 import ietf-crypto-types { 1801 prefix ct; 1802 reference 1803 "RFC AAAA: YANG Data Types and Groupings for Cryptography"; 1804 } 1806 import ietf-truststore { 1807 prefix ts; 1808 reference 1809 "RFC BBBB: A YANG Data Model for a Truststore"; 1811 } 1813 import ietf-keystore { 1814 prefix ks; 1815 reference 1816 "RFC CCCC: A YANG Data Model for a Keystore"; 1817 } 1819 import ietf-ssh-common { 1820 prefix sshcmn; 1821 revision-date 2020-08-20; // stable grouping definitions 1822 reference 1823 "RFC EEEE: YANG Groupings for SSH Clients and SSH Servers"; 1824 } 1826 organization 1827 "IETF NETCONF (Network Configuration) Working Group"; 1829 contact 1830 "WG Web: 1831 WG List: 1832 Author: Kent Watsen 1833 Author: Gary Wu "; 1835 description 1836 "This module defines reusable groupings for SSH servers that 1837 can be used as a basis for specific SSH server instances. 1839 Copyright (c) 2020 IETF Trust and the persons identified 1840 as authors of the code. All rights reserved. 1842 Redistribution and use in source and binary forms, with 1843 or without modification, is permitted pursuant to, and 1844 subject to the license terms contained in, the Simplified 1845 BSD License set forth in Section 4.c of the IETF Trust's 1846 Legal Provisions Relating to IETF Documents 1847 (https://trustee.ietf.org/license-info). 1849 This version of this YANG module is part of RFC EEEE 1850 (https://www.rfc-editor.org/info/rfcEEEE); see the RFC 1851 itself for full legal notices.; 1853 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1854 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 1855 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 1856 are to be interpreted as described in BCP 14 (RFC 2119) 1857 (RFC 8174) when, and only when, they appear in all 1858 capitals, as shown here."; 1860 revision 2020-08-20 { 1861 description 1862 "Initial version"; 1863 reference 1864 "RFC EEEE: YANG Groupings for SSH Clients and SSH Servers"; 1865 } 1867 // Features 1869 feature ssh-server-transport-params-config { 1870 description 1871 "SSH transport layer parameters are configurable on an SSH 1872 server."; 1873 } 1875 feature ssh-server-keepalives { 1876 description 1877 "Per socket SSH keepalive parameters are configurable for 1878 SSH servers on the server implementing this feature."; 1879 } 1881 feature client-auth-config-supported { 1882 description 1883 "Indicates that the configuration for how to authenticate 1884 clients can be configured herein, as opposed to in an 1885 application specific location. That is, to support the 1886 consuming data models that prefer to place client 1887 authentication with client definitions, rather then 1888 in a data model principally concerned with configuring 1889 the transport."; 1890 } 1892 feature client-auth-publickey { 1893 description 1894 "Indicates that the 'publickey' authentication type 1895 is supported. 1897 The 'publickey' authentication type is required by 1898 RFC 4252, but common implementations enable it to 1899 be disabled."; 1900 reference 1901 "RFC 4252: 1902 The Secure Shell (SSH) Authentication Protocol"; 1903 } 1905 feature client-auth-password { 1906 description 1907 "Indicates that the 'password' authentication type 1908 is supported."; 1909 } 1911 feature client-auth-hostbased { 1912 description 1913 "Indicates that the 'hostbased' authentication type 1914 is supported."; 1915 } 1917 feature client-auth-none { 1918 description 1919 "Indicates that the 'none' authentication type is 1920 supported."; 1921 } 1923 // Groupings 1925 grouping ssh-server-grouping { 1926 description 1927 "A reusable grouping for configuring a SSH server without 1928 any consideration for how underlying TCP sessions are 1929 established. 1931 Note that this grouping uses fairly typical descendent 1932 node names such that a stack of 'uses' statements will 1933 have name conflicts. It is intended that the consuming 1934 data model will resolve the issue (e.g., by wrapping 1935 the 'uses' statement in a container called 1936 'ssh-server-parameters'). This model purposely does 1937 not do this itself so as to provide maximum flexibility 1938 to consuming models."; 1940 container server-identity { 1941 nacm:default-deny-write; 1942 description 1943 "The list of host keys the SSH server will present when 1944 establishing a SSH connection."; 1945 list host-key { 1946 key "name"; 1947 min-elements 1; 1948 ordered-by user; 1949 description 1950 "An ordered list of host keys the SSH server will use to 1951 construct its ordered list of algorithms, when sending 1952 its SSH_MSG_KEXINIT message, as defined in Section 7.1 1953 of RFC 4253."; 1954 reference 1955 "RFC 4253: The Secure Shell (SSH) Transport Layer 1956 Protocol"; 1957 leaf name { 1958 type string; 1959 description 1960 "An arbitrary name for this host key"; 1961 } 1962 choice host-key-type { 1963 mandatory true; 1964 description 1965 "The type of host key being specified"; 1966 container public-key { 1967 description 1968 "A locally-defined or referenced asymmetric key pair 1969 to be used for the SSH server's host key."; 1970 reference 1971 "RFC CCCC: A YANG Data Model for a Keystore"; 1972 uses ks:local-or-keystore-asymmetric-key-grouping { 1973 refine "local-or-keystore/local/local-definition" { 1974 must 1975 'public-key-format = "ct:ssh-public-key-format"'; 1976 } 1977 refine "local-or-keystore/keystore/" 1978 + "keystore-reference" { 1979 must 'deref(.)/../ks:public-key-format' 1980 + ' = "ct:ssh-public-key-format"'; 1981 } 1982 } 1983 } 1984 container certificate { 1985 if-feature "sshcmn:ssh-x509-certs"; 1986 description 1987 "A locally-defined or referenced end-entity 1988 certificate to be used for the SSH server's 1989 host key."; 1990 reference 1991 "RFC CCCC: A YANG Data Model for a Keystore"; 1992 uses 1993 ks:local-or-keystore-end-entity-cert-with-key-grouping { 1994 refine "local-or-keystore/local/local-definition" { 1995 must 1996 'public-key-format' 1997 + ' = "ct:subject-public-key-info-format"'; 1998 } 1999 refine "local-or-keystore/keystore/keystore-reference" 2000 + "/asymmetric-key" { 2001 must 'deref(.)/../ks:public-key-format' 2002 + ' = "ct:subject-public-key-info-format"'; 2003 } 2005 } 2006 } 2007 } 2008 } 2009 } // container server-identity 2011 container client-authentication { 2012 nacm:default-deny-write; 2013 description 2014 "Specifies how the SSH server can authenticate SSH clients."; 2015 container supported-authentication-methods { 2016 description 2017 "Indicates which authentication methods the server 2018 supports."; 2019 leaf publickey { 2020 type empty; 2021 description 2022 "Indicates that the 'publickey' method is supported. 2023 Note that RFC 6187 X.509v3 Certificates for SSH uses 2024 the 'publickey' method name."; 2025 reference 2026 "RFC 4252: The Secure Shell (SSH) Authentication 2027 Protocol. 2028 RFC 6187: X.509v3 Certificates for Secure Shell 2029 Authentication."; 2030 } 2031 leaf password { 2032 if-feature client-auth-password; 2033 type empty; 2034 description 2035 "Indicates that the 'password' method is supported."; 2036 reference 2037 "RFC 4252: The Secure Shell (SSH) Authentication 2038 Protocol."; 2039 } 2040 leaf hostbased { 2041 if-feature client-auth-hostbased; 2042 type empty; 2043 description 2044 "Indicates that the 'hostbased' method is supported."; 2045 reference 2046 "RFC 4252: The Secure Shell (SSH) Authentication 2047 Protocol."; 2048 } 2049 leaf none { 2050 if-feature client-auth-none; 2051 type empty; 2052 description 2053 "Indicates that the 'none' method is supported."; 2054 reference 2055 "RFC 4252: The Secure Shell (SSH) Authentication 2056 Protocol."; 2057 } 2058 } 2060 container users { 2061 if-feature "client-auth-config-supported"; 2062 description 2063 "A list of locally configured users."; 2064 list user { 2065 key name; 2066 description 2067 "The list of local users configured on this device."; 2068 leaf name { 2069 type string; 2070 description 2071 "The user name string identifying this entry."; 2072 } 2073 container public-keys { 2074 if-feature client-auth-publickey; 2075 presence 2076 "Indicates that the server can authenticate this 2077 user using any of the configured SSH public keys."; 2078 description 2079 "A set of SSH public keys may be used by the SSH 2080 server to authenticate this user. A user is 2081 authenticated if its public key is an exact 2082 match to a configured public key."; 2083 reference 2084 "RFC BBBB: A YANG Data Model for a Truststore"; 2085 uses ts:local-or-truststore-public-keys-grouping { 2086 refine "local-or-truststore/local/local-definition" 2087 + "/public-key" { 2088 must 'public-key-format' 2089 + ' = "ct:ssh-public-key-format"'; 2090 } 2091 refine "local-or-truststore/truststore/" 2092 + "truststore-reference" { 2093 must 'deref(.)/../*/ts:public-key-format' 2094 + ' = "ct:ssh-public-key-format"'; 2095 } 2096 } 2097 } 2098 leaf password { 2099 if-feature client-auth-password; 2100 type ianach:crypt-hash; 2101 description 2102 "The password for this user."; 2103 } 2105 container hostbased { 2106 if-feature client-auth-hostbased; 2107 presence 2108 "Indicates that the server can authenticate this 2109 user's 'host' using any of the configured SSH 2110 host keys."; 2111 description 2112 "A set of SSH host keys may be used by the SSH 2113 server to authenticate this user's host. A 2114 user's host is authenticated if its host key 2115 is an exact match to a configured host key."; 2116 reference 2117 "RFC 4253: The Secure Shell (SSH) Transport Layer 2118 RFC BBBB: A YANG Data Model for a Truststore"; 2119 uses ts:local-or-truststore-public-keys-grouping { 2120 refine "local-or-truststore/local/local-definition" 2121 + "/public-key" { 2122 must 'public-key-format' 2123 + ' = "ct:ssh-public-key-format"'; 2124 } 2125 refine "local-or-truststore/truststore" 2126 + "/truststore-reference" { 2127 must 'deref(.)/../*/ts:public-key-format' 2128 + ' = "ct:ssh-public-key-format"'; 2129 } 2130 } 2131 } 2132 leaf none { 2133 if-feature client-auth-none; 2134 type empty; 2135 description 2136 "Indicates that the 'none' method is supported."; 2137 reference 2138 "RFC 4252: The Secure Shell (SSH) Authentication 2139 Protocol."; 2140 } 2141 } 2142 } 2143 container ca-certs { 2144 if-feature "client-auth-config-supported"; 2145 if-feature "sshcmn:ssh-x509-certs"; 2146 presence 2147 "Indicates that the SSH server can authenticate SSH 2148 clients using configured certificate authority (CA) 2149 certificates."; 2150 description 2151 "A set of certificate authority (CA) certificates used by 2152 the SSH server to authenticate SSH client certificates. 2153 A client certificate is authenticated if it has a valid 2154 chain of trust to a configured CA certificate."; 2155 reference 2156 "RFC BBBB: A YANG Data Model for a Truststore"; 2157 uses ts:local-or-truststore-certs-grouping; 2158 } 2159 container ee-certs { 2160 if-feature "client-auth-config-supported"; 2161 if-feature "sshcmn:ssh-x509-certs"; 2162 presence 2163 "Indicates that the SSH server can authenticate SSH 2164 clients using configured end-entity certificates."; 2165 description 2166 "A set of client certificates (i.e., end entity 2167 certificates) used by the SSH server to authenticate 2168 the certificates presented by SSH clients. A client 2169 certificate is authenticated if it is an exact match 2170 to a configured end-entity certificate."; 2171 reference 2172 "RFC BBBB: A YANG Data Model for a Truststore"; 2173 uses ts:local-or-truststore-certs-grouping; 2174 } 2175 } // container client-authentication 2177 container transport-params { 2178 nacm:default-deny-write; 2179 if-feature "ssh-server-transport-params-config"; 2180 description 2181 "Configurable parameters of the SSH transport layer."; 2182 uses sshcmn:transport-params-grouping; 2183 } // container transport-params 2185 container keepalives { 2186 nacm:default-deny-write; 2187 if-feature "ssh-server-keepalives"; 2188 presence 2189 "Indicates that the SSH server proactively tests the 2190 aliveness of the remote SSH client."; 2191 description 2192 "Configures the keep-alive policy, to proactively test 2193 the aliveness of the SSL client. An unresponsive SSL 2194 client is dropped after approximately max-wait * 2195 max-attempts seconds. Per Section 4 of RFC 4254, 2196 the SSH server SHOULD send an SSH_MSG_GLOBAL_REQUEST 2197 message with a purposely nonexistent 'request name' 2198 value (e.g., keepalive@ietf.org) and the 'want reply' 2199 value set to '1'."; 2200 reference 2201 "RFC 4254: The Secure Shell (SSH) Connection Protocol"; 2202 leaf max-wait { 2203 type uint16 { 2204 range "1..max"; 2205 } 2206 units "seconds"; 2207 default "30"; 2208 description 2209 "Sets the amount of time in seconds after which 2210 if no data has been received from the SSL client, 2211 a SSL-level message will be sent to test the 2212 aliveness of the SSL client."; 2213 } 2214 leaf max-attempts { 2215 type uint8; 2216 default "3"; 2217 description 2218 "Sets the maximum number of sequential keep-alive 2219 messages that can fail to obtain a response from 2220 the SSL client before assuming the SSL client is 2221 no longer alive."; 2222 } 2223 } 2224 } // grouping ssh-server-grouping 2225 } // module ietf-ssh-server 2227 2229 5. Security Considerations 2231 5.1. The "ietf-ssh-common" YANG Module 2233 The "ietf-ssh-common" YANG module defines "grouping" statements that 2234 are designed to be accessed via YANG based management protocols, such 2235 as NETCONF [RFC6241] and RESTCONF [RFC8040]. Both of these protocols 2236 have mandatory-to-implement secure transport layers (e.g., SSH, TLS) 2237 with mutual authentication. 2239 The NETCONF access control model (NACM) [RFC8341] provides the means 2240 to restrict access for particular users to a pre-configured subset of 2241 all available protocol operations and content. 2243 Since the module in this document only define groupings, these 2244 considerations are primarily for the designers of other modules that 2245 use these groupings. 2247 None of the readable data nodes defined in this YANG module are 2248 considered sensitive or vulnerable in network environments. The NACM 2249 "default-deny-all" extension has not been set for any data nodes 2250 defined in this module. 2252 None of the writable data nodes defined in this YANG module are 2253 considered sensitive or vulnerable in network environments. The NACM 2254 "default-deny-write" extension has not been set for any data nodes 2255 defined in this module. 2257 This module does not define any RPCs, actions, or notifications, and 2258 thus the security consideration for such is not provided here. 2260 5.2. The "ietf-ssh-client" YANG Module 2262 The "ietf-ssh-client" YANG module defines "grouping" statements that 2263 are designed to be accessed via YANG based management protocols, such 2264 as NETCONF [RFC6241] and RESTCONF [RFC8040]. Both of these protocols 2265 have mandatory-to-implement secure transport layers (e.g., SSH, TLS) 2266 with mutual authentication. 2268 The NETCONF access control model (NACM) [RFC8341] provides the means 2269 to restrict access for particular users to a pre-configured subset of 2270 all available protocol operations and content. 2272 Since the module in this document only define groupings, these 2273 considerations are primarily for the designers of other modules that 2274 use these groupings. 2276 One readable data node defined in this YANG module may be considered 2277 sensitive or vulnerable in some network environments. This node is 2278 as follows: 2280 * The "client-identity/password" node: 2282 The cleartext "password" node defined in the "ssh-client- 2283 grouping" grouping is additionally sensitive to read operations 2284 such that, in normal use cases, it should never be returned to 2285 a client. For this reason, the NACM extension "default-deny- 2286 all" has been applied to it. 2288 | Please be aware that this module uses the "key" and "private- 2289 | key" nodes from the "ietf-crypto-types" module 2290 | [I-D.ietf-netconf-crypto-types], where said nodes have the NACM 2291 | extension "default-deny-all" set, thus preventing unrestricted 2292 | read-access to the cleartext key values. 2294 All of the writable data nodes defined by this module may be 2295 considered sensitive or vulnerable in some network environments. For 2296 instance, any modification to a key or reference to a key may 2297 dramatically alter the implemented security policy. For this reason, 2298 the NACM extension "default-deny-write" has been set for all data 2299 nodes defined in this module. 2301 This module does not define any RPCs, actions, or notifications, and 2302 thus the security consideration for such is not provided here. 2304 5.3. The "ietf-ssh-server" YANG Module 2306 The "ietf-ssh-server" YANG module defines "grouping" statements that 2307 are designed to be accessed via YANG based management protocols, such 2308 as NETCONF [RFC6241] and RESTCONF [RFC8040]. Both of these protocols 2309 have mandatory-to-implement secure transport layers (e.g., SSH, TLS) 2310 with mutual authentication. 2312 The NETCONF access control model (NACM) [RFC8341] provides the means 2313 to restrict access for particular users to a pre-configured subset of 2314 all available protocol operations and content. 2316 Since the module in this document only define groupings, these 2317 considerations are primarily for the designers of other modules that 2318 use these groupings. 2320 None of the readable data nodes defined in this YANG module are 2321 considered sensitive or vulnerable in network environments. The NACM 2322 "default-deny-all" extension has not been set for any data nodes 2323 defined in this module. 2325 | Please be aware that this module uses the "key" and "private- 2326 | key" nodes from the "ietf-crypto-types" module 2327 | [I-D.ietf-netconf-crypto-types], where said nodes have the NACM 2328 | extension "default-deny-all" set, thus preventing unrestricted 2329 | read-access to the cleartext key values. 2331 All of the writable data nodes defined by this module may be 2332 considered sensitive or vulnerable in some network environments. For 2333 instance, the addition or removal of references to keys, 2334 certificates, trusted anchors, etc., or even the modification of 2335 transport or keepalive parameters can dramatically alter the 2336 implemented security policy. For this reason, the NACM extension 2337 "default-deny-write" has been set for all data nodes defined in this 2338 module. 2340 This module does not define any RPCs, actions, or notifications, and 2341 thus the security consideration for such is not provided here. 2343 6. IANA Considerations 2345 6.1. The "IETF XML" Registry 2347 This document registers three URIs in the "ns" subregistry of the 2348 IETF XML Registry [RFC3688]. Following the format in [RFC3688], the 2349 following registrations are requested: 2351 URI: urn:ietf:params:xml:ns:yang:ietf-ssh-common 2352 Registrant Contact: The NETCONF WG of the IETF. 2353 XML: N/A, the requested URI is an XML namespace. 2355 URI: urn:ietf:params:xml:ns:yang:ietf-ssh-client 2356 Registrant Contact: The NETCONF WG of the IETF. 2357 XML: N/A, the requested URI is an XML namespace. 2359 URI: urn:ietf:params:xml:ns:yang:ietf-ssh-server 2360 Registrant Contact: The NETCONF WG of the IETF. 2361 XML: N/A, the requested URI is an XML namespace. 2363 6.2. The "YANG Module Names" Registry 2365 This document registers three YANG modules in the YANG Module Names 2366 registry [RFC6020]. Following the format in [RFC6020], the following 2367 registrations are requested: 2369 name: ietf-ssh-common 2370 namespace: urn:ietf:params:xml:ns:yang:ietf-ssh-common 2371 prefix: sshcmn 2372 reference: RFC EEEE 2374 name: ietf-ssh-client 2375 namespace: urn:ietf:params:xml:ns:yang:ietf-ssh-client 2376 prefix: sshc 2377 reference: RFC EEEE 2379 name: ietf-ssh-server 2380 namespace: urn:ietf:params:xml:ns:yang:ietf-ssh-server 2381 prefix: sshs 2382 reference: RFC EEEE 2384 7. References 2386 7.1. Normative References 2388 [I-D.ietf-netconf-crypto-types] 2389 Watsen, K., "YANG Data Types and Groupings for 2390 Cryptography", Work in Progress, Internet-Draft, draft- 2391 ietf-netconf-crypto-types-17, 10 July 2020, 2392 . 2395 [I-D.ietf-netconf-keystore] 2396 Watsen, K., "A YANG Data Model for a Keystore", Work in 2397 Progress, Internet-Draft, draft-ietf-netconf-keystore-19, 2398 10 July 2020, . 2401 [I-D.ietf-netconf-trust-anchors] 2402 Watsen, K., "A YANG Data Model for a Truststore", Work in 2403 Progress, Internet-Draft, draft-ietf-netconf-trust- 2404 anchors-12, 10 July 2020, . 2407 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2408 Requirement Levels", BCP 14, RFC 2119, 2409 DOI 10.17487/RFC2119, March 1997, 2410 . 2412 [RFC4344] Bellare, M., Kohno, T., and C. Namprempre, "The Secure 2413 Shell (SSH) Transport Layer Encryption Modes", RFC 4344, 2414 DOI 10.17487/RFC4344, January 2006, 2415 . 2417 [RFC4419] Friedl, M., Provos, N., and W. Simpson, "Diffie-Hellman 2418 Group Exchange for the Secure Shell (SSH) Transport Layer 2419 Protocol", RFC 4419, DOI 10.17487/RFC4419, March 2006, 2420 . 2422 [RFC5656] Stebila, D. and J. Green, "Elliptic Curve Algorithm 2423 Integration in the Secure Shell Transport Layer", 2424 RFC 5656, DOI 10.17487/RFC5656, December 2009, 2425 . 2427 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 2428 the Network Configuration Protocol (NETCONF)", RFC 6020, 2429 DOI 10.17487/RFC6020, October 2010, 2430 . 2432 [RFC6187] Igoe, K. and D. Stebila, "X.509v3 Certificates for Secure 2433 Shell Authentication", RFC 6187, DOI 10.17487/RFC6187, 2434 March 2011, . 2436 [RFC6668] Bider, D. and M. Baushke, "SHA-2 Data Integrity 2437 Verification for the Secure Shell (SSH) Transport Layer 2438 Protocol", RFC 6668, DOI 10.17487/RFC6668, July 2012, 2439 . 2441 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2442 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2443 . 2445 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2446 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2447 May 2017, . 2449 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 2450 Access Control Model", STD 91, RFC 8341, 2451 DOI 10.17487/RFC8341, March 2018, 2452 . 2454 7.2. Informative References 2456 [I-D.ietf-netconf-http-client-server] 2457 Watsen, K., "YANG Groupings for HTTP Clients and HTTP 2458 Servers", Work in Progress, Internet-Draft, draft-ietf- 2459 netconf-http-client-server-04, 8 July 2020, 2460 . 2463 [I-D.ietf-netconf-netconf-client-server] 2464 Watsen, K., "NETCONF Client and Server Models", Work in 2465 Progress, Internet-Draft, draft-ietf-netconf-netconf- 2466 client-server-20, 8 July 2020, 2467 . 2470 [I-D.ietf-netconf-restconf-client-server] 2471 Watsen, K., "RESTCONF Client and Server Models", Work in 2472 Progress, Internet-Draft, draft-ietf-netconf-restconf- 2473 client-server-20, 8 July 2020, 2474 . 2477 [I-D.ietf-netconf-ssh-client-server] 2478 Watsen, K. and G. Wu, "YANG Groupings for SSH Clients and 2479 SSH Servers", Work in Progress, Internet-Draft, draft- 2480 ietf-netconf-ssh-client-server-21, 10 July 2020, 2481 . 2484 [I-D.ietf-netconf-tcp-client-server] 2485 Watsen, K. and M. Scharf, "YANG Groupings for TCP Clients 2486 and TCP Servers", Work in Progress, Internet-Draft, draft- 2487 ietf-netconf-tcp-client-server-07, 8 July 2020, 2488 . 2491 [I-D.ietf-netconf-tls-client-server] 2492 Watsen, K. and G. Wu, "YANG Groupings for TLS Clients and 2493 TLS Servers", Work in Progress, Internet-Draft, draft- 2494 ietf-netconf-tls-client-server-21, 10 July 2020, 2495 . 2498 [OPENSSH] Project, T. O., "OpenSSH", 2016, . 2500 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2501 DOI 10.17487/RFC3688, January 2004, 2502 . 2504 [RFC4252] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) 2505 Authentication Protocol", RFC 4252, DOI 10.17487/RFC4252, 2506 January 2006, . 2508 [RFC4253] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) 2509 Transport Layer Protocol", RFC 4253, DOI 10.17487/RFC4253, 2510 January 2006, . 2512 [RFC4254] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) 2513 Connection Protocol", RFC 4254, DOI 10.17487/RFC4254, 2514 January 2006, . 2516 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2517 and A. Bierman, Ed., "Network Configuration Protocol 2518 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2519 . 2521 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 2522 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 2523 . 2525 [RFC7317] Bierman, A. and M. Bjorklund, "A YANG Data Model for 2526 System Management", RFC 7317, DOI 10.17487/RFC7317, August 2527 2014, . 2529 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2530 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2531 . 2533 [RFC8071] Watsen, K., "NETCONF Call Home and RESTCONF Call Home", 2534 RFC 8071, DOI 10.17487/RFC8071, February 2017, 2535 . 2537 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 2538 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 2539 . 2541 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 2542 and R. Wilton, "Network Management Datastore Architecture 2543 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 2544 . 2546 Appendix A. Change Log 2548 This section is to be removed before publishing as an RFC. 2550 A.1. 00 to 01 2552 * Noted that '0.0.0.0' and '::' might have special meanings. 2554 * Renamed "keychain" to "keystore". 2556 A.2. 01 to 02 2558 * Removed the groupings 'listening-ssh-client-grouping' and 2559 'listening-ssh-server-grouping'. Now modules only contain the 2560 transport-independent groupings. 2562 * Simplified the "client-auth" part in the ietf-ssh-client module. 2563 It now inlines what it used to point to keystore for. 2565 * Added cipher suites for various algorithms into new 'ietf-ssh- 2566 common' module. 2568 A.3. 02 to 03 2570 * Removed 'RESTRICTED' enum from 'password' leaf type. 2572 * Added a 'must' statement to container 'server-auth' asserting that 2573 at least one of the various auth mechanisms must be specified. 2575 * Fixed description statement for leaf 'trusted-ca-certs'. 2577 A.4. 03 to 04 2579 * Change title to "YANG Groupings for SSH Clients and SSH Servers" 2581 * Added reference to RFC 6668 2583 * Added RFC 8174 to Requirements Language Section. 2585 * Enhanced description statement for ietf-ssh-server's "trusted-ca- 2586 certs" leaf. 2588 * Added mandatory true to ietf-ssh-client's "client-auth" 'choice' 2589 statement. 2591 * Changed the YANG prefix for module ietf-ssh-common from 'sshcom' 2592 to 'sshcmn'. 2594 * Removed the compression algorithms as they are not commonly 2595 configurable in vendors' implementations. 2597 * Updating descriptions in transport-params-grouping and the 2598 servers's usage of it. 2600 * Now tree diagrams reference ietf-netmod-yang-tree-diagrams 2602 * Updated YANG to use typedefs around leafrefs to common keystore 2603 paths 2605 * Now inlines key and certificates (no longer a leafref to keystore) 2607 A.5. 04 to 05 2609 * Merged changes from co-author. 2611 A.6. 05 to 06 2613 * Updated to use trust anchors from trust-anchors draft (was 2614 keystore draft) 2616 * Now uses new keystore grouping enabling asymmetric key to be 2617 either locally defined or a reference to the keystore. 2619 A.7. 06 to 07 2621 * factored the ssh-[client|server]-groupings into more reusable 2622 groupings. 2624 * added if-feature statements for the new "ssh-host-keys" and 2625 "x509-certificates" features defined in draft-ietf-netconf-trust- 2626 anchors. 2628 A.8. 07 to 08 2630 * Added a number of compatibility matrices to Section 5 (thanks 2631 Frank!) 2633 * Clarified that any configured "host-key-alg" values need to be 2634 compatible with the configured private key. 2636 A.9. 08 to 09 2638 * Updated examples to reflect update to groupings defined in the 2639 keystore -09 draft. 2641 * Add SSH keepalives features and groupings. 2643 * Prefixed top-level SSH grouping nodes with 'ssh-' and support 2644 mashups. 2646 * Updated copyright date, boilerplate template, affiliation, and 2647 folding algorithm. 2649 A.10. 09 to 10 2651 * Reformatted the YANG modules. 2653 A.11. 10 to 11 2655 * Reformatted lines causing folding to occur. 2657 A.12. 11 to 12 2659 * Collapsed all the inner groupings into the top-level grouping. 2661 * Added a top-level "demux container" inside the top-level grouping. 2663 * Added NACM statements and updated the Security Considerations 2664 section. 2666 * Added "presence" statements on the "keepalive" containers, as was 2667 needed to address a validation error that appeared after adding 2668 the "must" statements into the NETCONF/RESTCONF client/server 2669 modules. 2671 * Updated the boilerplate text in module-level "description" 2672 statement to match copyeditor convention. 2674 A.13. 12 to 13 2676 * Removed the "demux containers", floating the nacm:default-deny- 2677 write to each descendent node, and adding a note to model 2678 designers regarding the potential need to add their own demux 2679 containers. 2681 * Fixed a couple references (section 2 --> section 3) 2683 * In the server model, replaced with and introduced 'local-or-external' choice. 2686 A.14. 13 to 14 2688 * Updated to reflect changes in trust-anchors drafts (e.g., s/trust- 2689 anchors/truststore/g + s/pinned.//) 2691 A.15. 14 to 15 2693 * Updated examples to reflect ietf-crypto-types change (e.g., 2694 identities --> enumerations) 2696 * Updated "server-authentication" and "client-authentication" nodes 2697 from being a leaf of type "ts:host-keys-ref" or "ts:certificates- 2698 ref" to a container that uses "ts:local-or-truststore-host-keys- 2699 grouping" or "ts:local-or-truststore-certs-grouping". 2701 A.16. 15 to 16 2703 * Removed unnecessary if-feature statements in the -client and 2704 -server modules. 2706 * Cleaned up some description statements in the -client and -server 2707 modules. 2709 * Fixed a canonical ordering issue in ietf-ssh-common detected by 2710 new pyang. 2712 A.17. 16 to 17 2714 * Removed choice local-or-external by removing the 'external' case 2715 and flattening the 'local' case and adding a "client-auth-config- 2716 supported" feature. 2718 * Updated examples to include the "*-key-format" nodes. 2720 * Augmented-in "must" expressions ensuring that locally-defined 2721 public-key-format are "ct:ssh-public-key-format" (must expr for 2722 ref'ed keys are TBD). 2724 A.18. 17 to 18 2726 * Removed leaf-list 'other' from ietf-ssh-server. 2728 * Removed unused 'external-client-auth-supported' feature. 2730 * Added features client-auth-password, client-auth-hostbased, and 2731 client-auth-none. 2733 * Renamed 'host-key' to 'public-key' for when refering to 2734 'publickey' based auth. 2736 * Added new feature-protected 'hostbased' and 'none' to the 'user' 2737 node's config. 2739 * Added new feature-protected 'hostbased' and 'none' to the 'client- 2740 identity' node's config. 2742 * Updated examples to reflect new "bag" addition to truststore. 2744 * Refined truststore/keystore groupings to ensure the key formats 2745 "must" be particular values. 2747 * Switched to using truststore's new "public-key" bag (instead of 2748 separate "ssh-public-key" and "raw-public-key" bags. 2750 * Updated client/server examples to cover ALL cases (local/ref x 2751 cert/raw-key/psk). 2753 A.19. 18 to 19 2755 * Updated the "keepalives" containers to address Michal Vasko's 2756 request to align with RFC 8071. 2758 * Removed algorithm-mapping tables from the "SSH Common Model" 2759 section 2761 * Removed 'algorithm' node from examples. 2763 * Added feature "client-identity-publickey" 2765 * Removed "choice auth-type", as auth-types aren't exclusive. 2767 * Renamed both "client-certs" and "server-certs" to "ee-certs" 2768 * Switch "must" to assert the public-key-format is "subject-public- 2769 key-info-format" when certificates are used. 2771 * Added a "Note to Reviewers" note to first page. 2773 A.20. 19 to 20 2775 * Added a "must 'public-key or password or hostbased or none or 2776 certificate'" statement to the "user" node in ietf-ssh-client 2778 * Expanded "Data Model Overview section(s) [remove "wall" of tree 2779 diagrams]. 2781 * Moved the "ietf-ssh-common" module section to proceed the other 2782 two module sections. 2784 * Updated the Security Considerations section. 2786 A.21. 20 to 21 2788 * Updated examples to reflect new "cleartext-" prefix in the crypto- 2789 types draft. 2791 A.22. 21 to 22 2793 * Cleaned up the SSH-client examples (i.e., removing FIXMEs) 2795 * Fixed issues found by the SecDir review of the "keystore" draft. 2797 * Updated the "ietf-ssh-client" module to use the new "password- 2798 grouping" grouping from the "crypto-types" module. 2800 Acknowledgements 2802 The authors would like to thank for following for lively discussions 2803 on list and in the halls (ordered by first name): Alan Luchuk, Andy 2804 Bierman, Balazs Kovacs, Benoit Claise, Bert Wijnen, David Lamparter, 2805 Gary Wu, Juergen Schoenwaelder, Ladislav Lhotka, Liang Xia, Martin 2806 Bjorklund, Mehmet Ersue, Michal Vasko, Phil Shafer, Radek Krejci, 2807 Sean Turner, Tom Petch. 2809 Special acknowledgement goes to Gary Wu who contributed the "ietf- 2810 ssh-common" module. 2812 Author's Address 2813 Kent Watsen 2814 Watsen Networks 2816 Email: kent+ietf@watsen.net