idnits 2.17.1 draft-ietf-netconf-ssh-client-server-20.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 1383 has weird spacing: '...ificate has a...' -- The document date (8 July 2020) is 1387 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 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 G. Wu 5 Expires: 9 January 2021 Cisco Systems 6 8 July 2020 8 YANG Groupings for SSH Clients and SSH Servers 9 draft-ietf-netconf-ssh-client-server-20 11 Abstract 13 This document defines three YANG modules: the first defines groupings 14 for a generic SSH client, the second defines groupings for a generic 15 SSH 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 SSH 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 * "EEEE" --> 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-08" --> 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 9 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 . . . . . . . . . . . . . . . . . . . . . . . . 3 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-ssh-common" Module . . . . . . . . . . . . . . . . 6 89 2.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 6 90 2.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 9 91 2.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 9 92 3. The "ietf-ssh-client" Module . . . . . . . . . . . . . . . . 19 93 3.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 19 94 3.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 21 95 3.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 25 96 4. The "ietf-ssh-server" Module . . . . . . . . . . . . . . . . 32 97 4.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 32 98 4.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 34 99 4.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 38 100 5. Security Considerations . . . . . . . . . . . . . . . . . . . 47 101 5.1. The "ietf-ssh-common" YANG Module . . . . . . . . . . . . 47 102 5.2. The "ietf-ssh-client" YANG Module . . . . . . . . . . . . 48 103 5.3. The "ietf-ssh-server" YANG Module . . . . . . . . . . . . 49 104 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 50 105 6.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 50 106 6.2. The YANG Module Names Registry . . . . . . . . . . . . . 50 107 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 51 108 7.1. Normative References . . . . . . . . . . . . . . . . . . 51 109 7.2. Informative References . . . . . . . . . . . . . . . . . 52 110 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 54 111 A.1. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 54 112 A.2. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 54 113 A.3. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 54 114 A.4. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 55 115 A.5. 04 to 05 . . . . . . . . . . . . . . . . . . . . . . . . 55 116 A.6. 05 to 06 . . . . . . . . . . . . . . . . . . . . . . . . 55 117 A.7. 06 to 07 . . . . . . . . . . . . . . . . . . . . . . . . 55 118 A.8. 07 to 08 . . . . . . . . . . . . . . . . . . . . . . . . 56 119 A.9. 08 to 09 . . . . . . . . . . . . . . . . . . . . . . . . 56 120 A.10. 09 to 10 . . . . . . . . . . . . . . . . . . . . . . . . 56 121 A.11. 10 to 11 . . . . . . . . . . . . . . . . . . . . . . . . 56 122 A.12. 11 to 12 . . . . . . . . . . . . . . . . . . . . . . . . 56 123 A.13. 12 to 13 . . . . . . . . . . . . . . . . . . . . . . . . 57 124 A.14. 13 to 14 . . . . . . . . . . . . . . . . . . . . . . . . 57 125 A.15. 14 to 15 . . . . . . . . . . . . . . . . . . . . . . . . 57 126 A.16. 15 to 16 . . . . . . . . . . . . . . . . . . . . . . . . 57 127 A.17. 16 to 17 . . . . . . . . . . . . . . . . . . . . . . . . 57 128 A.18. 17 to 18 . . . . . . . . . . . . . . . . . . . . . . . . 58 129 A.19. 18 to 19 . . . . . . . . . . . . . . . . . . . . . . . . 58 130 A.20. 19 to 20 . . . . . . . . . . . . . . . . . . . . . . . . 59 131 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 59 132 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 59 134 1. Introduction 136 This document defines three YANG 1.1 [RFC7950] modules: the first 137 defines a grouping for a generic SSH client, the second defines a 138 grouping for a generic SSH server, and the third defines identities 139 and groupings common to both the client and the server. It is 140 intended that these groupings will be used by applications using the 141 SSH protocol [RFC4252], [RFC4253], and [RFC4254]. For instance, 142 these groupings could be used to help define the data model for an 143 OpenSSH [OPENSSH] server or a NETCONF over SSH [RFC6242] based 144 server. 146 The client and server YANG modules in this document each define one 147 grouping, which is focused on just SSH-specific configuration, and 148 specifically avoids any transport-level configuration, such as what 149 ports to listen on or connect to. This affords applications the 150 opportunity to define their own strategy for how the underlying TCP 151 connection is established. For instance, applications supporting 152 NETCONF Call Home [RFC8071] could use the "ssh-server-grouping" 153 grouping for the SSH parts it provides, while adding data nodes for 154 the TCP-level call-home configuration. 156 The modules defined in this document use groupings defined in 157 [I-D.ietf-netconf-keystore] enabling keys to be either locally 158 defined or a reference to globally configured values. 160 The modules defined in this document optionally support [RFC6187] 161 enabling X.509v3 certificate based host keys and public keys. 163 1.1. Relation to other RFCs 165 This document presents one or more YANG modules [RFC7950] that are 166 part of a collection of RFCs that work together to define 167 configuration modules for clients and servers of both the NETCONF 168 [RFC6241] and RESTCONF [RFC8040] protocols. 170 The modules have been defined in a modular fashion to enable their 171 use by other efforts, some of which are known to be in progress at 172 the time of this writing, with many more expected to be defined in 173 time. 175 The relationship between the various RFCs in the collection is 176 presented in the below diagram. The labels in the diagram represent 177 the primary purpose provided by each RFC. Links the each RFC are 178 provided below the diagram. 180 crypto-types 181 ^ ^ 182 / \ 183 / \ 184 truststore keystore 185 ^ ^ ^ ^ 186 | +---------+ | | 187 | | | | 188 | +------------+ | 189 tcp-client-server | / | | 190 ^ ^ ssh-client-server | | 191 | | ^ tls-client-server 192 | | | ^ ^ http-client-server 193 | | | | | ^ 194 | | | +-----+ +---------+ | 195 | | | | | | 196 | +-----------|--------|--------------+ | | 197 | | | | | | 198 +-----------+ | | | | | 199 | | | | | | 200 | | | | | | 201 netconf-client-server restconf-client-server 203 +=======================+===========================================+ 204 | Label in Diagram | Originating RFC | 205 +=======================+===========================================+ 206 | crypto-types | [I-D.ietf-netconf-crypto-types] | 207 +-----------------------+-------------------------------------------+ 208 | truststore | [I-D.ietf-netconf-trust-anchors] | 209 +-----------------------+-------------------------------------------+ 210 | keystore | [I-D.ietf-netconf-keystore] | 211 +-----------------------+-------------------------------------------+ 212 | tcp-client-server | [I-D.ietf-netconf-tcp-client-server] | 213 +-----------------------+-------------------------------------------+ 214 | ssh-client-server | [I-D.ietf-netconf-ssh-client-server] | 215 +-----------------------+-------------------------------------------+ 216 | tls-client-server | [I-D.ietf-netconf-tls-client-server] | 217 +-----------------------+-------------------------------------------+ 218 | http-client-server | [I-D.ietf-netconf-http-client-server] | 219 +-----------------------+-------------------------------------------+ 220 | netconf-client-server | [I-D.ietf-netconf-netconf-client-server] | 221 +-----------------------+-------------------------------------------+ 222 |restconf-client-server | [I-D.ietf-netconf-restconf-client-server] | 223 +-----------------------+-------------------------------------------+ 225 Table 1: Label to RFC Mapping 227 1.2. Specification Language 229 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 230 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 231 "OPTIONAL" in this document are to be interpreted as described in BCP 232 14 [RFC2119] [RFC8174] when, and only when, they appear in all 233 capitals, as shown here. 235 1.3. Adherence to the NMDA 237 This document in compliant with the Network Management Datastore 238 Architecture (NMDA) [RFC8342]. For instance, as described in 239 [I-D.ietf-netconf-trust-anchors] and [I-D.ietf-netconf-keystore], 240 trust anchors and keys installed during manufacturing are expected to 241 appear in . 243 2. The "ietf-ssh-common" Module 245 The SSH common model presented in this section contains identities 246 and groupings common to both SSH clients and SSH servers. The 247 "transport-params-grouping" grouping can be used to configure the 248 list of SSH transport algorithms permitted by the SSH client or SSH 249 server. The lists of algorithms are ordered such that, if multiple 250 algorithms are permitted by the client, the algorithm that appears 251 first in its list that is also permitted by the server is used for 252 the SSH transport layer connection. The ability to restrict the 253 algorithms allowed is provided in this grouping for SSH clients and 254 SSH servers that are capable of doing so and may serve to make SSH 255 clients and SSH servers compliant with security policies. 257 Features are defined for algorithms that are OPTIONAL or are not 258 widely supported by popular implementations. Note that the list of 259 algorithms is not exhaustive. As well, some algorithms that are 260 REQUIRED by [RFC4253] are missing, notably "ssh-dss" and "diffie- 261 hellman-group1-sha1" due to their weak security and there being 262 alternatives that are widely supported. 264 2.1. Data Model Overview 266 2.1.1. Features 268 The following diagram lists all the "feature" statements defined in 269 the "ietf-ssh-common" module: 271 Features: 272 +-- ssh-ecc 273 +-- ssh-x509-certs 274 +-- ssh-dh-group-exchange 275 +-- ssh-ctr 276 +-- ssh-sha2 278 2.1.2. Identities 280 The following diagram illustrates the relationship amongst the 281 "identity" statements defined in the "ietf-ssh-common" module: 283 Identities: 284 +-- public-key-alg-base 285 | +-- ssh-dss 286 | +-- ssh-rsa 287 | +-- ecdsa-sha2-nistp256 288 | +-- ecdsa-sha2-nistp384 289 | +-- ecdsa-sha2-nistp521 290 | +-- x509v3-ssh-rsa 291 | +-- x509v3-rsa2048-sha256 292 | +-- x509v3-ecdsa-sha2-nistp256 293 | +-- x509v3-ecdsa-sha2-nistp384 294 | +-- x509v3-ecdsa-sha2-nistp521 295 +-- key-exchange-alg-base 296 | +-- diffie-hellman-group14-sha1 297 | +-- diffie-hellman-group-exchange-sha1 298 | +-- diffie-hellman-group-exchange-sha256 299 | +-- ecdh-sha2-nistp256 300 | +-- ecdh-sha2-nistp384 301 | +-- ecdh-sha2-nistp521 302 +-- encryption-alg-base 303 | +-- triple-des-cbc 304 | +-- aes128-cbc 305 | +-- aes192-cbc 306 | +-- aes256-cbc 307 | +-- aes128-ctr 308 | +-- aes192-ctr 309 | +-- aes256-ctr 310 +-- mac-alg-base 311 +-- hmac-sha1 312 +-- hmac-sha2-256 313 +-- hmac-sha2-512 315 Comments: 317 * The diagram shows that there are four base identities. 319 * These identities are used by this module to define algorithms for 320 public-key, key-exchange, encryption, and MACs. 321 * These base identities are "abstract", in the object orientied 322 programming sense, in that they only define a "class" of 323 algorithms, rather than a specific algorithm. 325 2.1.3. Groupings 327 The following diagram lists all the "grouping" statements defined in 328 the "ietf-ssh-common" module: 330 Groupings: 331 +-- transport-params-grouping 333 Each of these groupings are presented in the following subsections. 335 2.1.3.1. The "transport-params-grouping" Grouping 337 The following tree diagram [RFC8340] illustrates the "transport- 338 params-grouping" grouping: 340 grouping transport-params-grouping 341 +-- host-key 342 | +-- host-key-alg* identityref 343 +-- key-exchange 344 | +-- key-exchange-alg* identityref 345 +-- encryption 346 | +-- encryption-alg* identityref 347 +-- mac 348 +-- mac-alg* identityref 350 Comments: 352 * This grouping is used by both the "ssh-client-grouping" and the 353 "ssh-server-grouping" groupings defined in Section 3.1.2.1 and 354 Section 4.1.2.1, respectively. 356 * This grouping enables client and server configurations to specify 357 the algorithms that are to be used when establishing SSH sessions. 359 * Each list is "ordered-by user". 361 2.1.4. Protocol-accessible Nodes 363 The "ietf-ssh-common" module does not contain any protocol-accessible 364 nodes, but the module needs to be "implemented", as described in 365 Section 5.6.5 of [RFC7950], in order for the identities in 366 Section 2.1.2 to be defined. 368 2.2. Example Usage 370 This following example illustrates how the "transport-params- 371 grouping' grouping appears when populated with some data. 373 376 377 algs:x509v3-rsa2048-sha256 378 algs:ssh-rsa 379 380 381 382 algs:diffie-hellman-group-exchange-sha256 383 384 385 386 algs:aes256-ctr 387 algs:aes192-ctr 388 algs:aes128-ctr 389 algs:aes256-cbc 390 algs:aes192-cbc 391 algs:aes128-cbc 392 393 394 algs:hmac-sha2-256 395 algs:hmac-sha2-512 396 397 399 2.3. YANG Module 401 This YANG module has normative references to [RFC4253], [RFC4344], 402 [RFC4419], [RFC5656], [RFC6187], and [RFC6668]. 404 file "ietf-ssh-common@2020-07-08.yang" 406 module ietf-ssh-common { 407 yang-version 1.1; 408 namespace "urn:ietf:params:xml:ns:yang:ietf-ssh-common"; 409 prefix sshcmn; 411 organization 412 "IETF NETCONF (Network Configuration) Working Group"; 414 contact 415 "WG Web: 416 WG List: 417 Author: Kent Watsen 418 Author: Gary Wu "; 420 description 421 "This module defines a common features, identities, and 422 groupings for Secure Shell (SSH). 424 Copyright (c) 2020 IETF Trust and the persons identified 425 as authors of the code. All rights reserved. 427 Redistribution and use in source and binary forms, with 428 or without modification, is permitted pursuant to, and 429 subject to the license terms contained in, the Simplified 430 BSD License set forth in Section 4.c of the IETF Trust's 431 Legal Provisions Relating to IETF Documents 432 (https://trustee.ietf.org/license-info). 434 This version of this YANG module is part of RFC EEEE 435 (https://www.rfc-editor.org/info/rfcEEEE); see the RFC 436 itself for full legal notices.; 438 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 439 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 440 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 441 are to be interpreted as described in BCP 14 (RFC 2119) 442 (RFC 8174) when, and only when, they appear in all 443 capitals, as shown here."; 445 revision 2020-07-08 { 446 description 447 "Initial version"; 448 reference 449 "RFC EEEE: YANG Groupings for SSH Clients and SSH Servers"; 450 } 452 // Features 454 feature ssh-ecc { 455 description 456 "Elliptic Curve Cryptography is supported for SSH."; 457 reference 458 "RFC 5656: Elliptic Curve Algorithm Integration in the 459 Secure Shell Transport Layer"; 460 } 462 feature ssh-x509-certs { 463 description 464 "X.509v3 certificates are supported for SSH per RFC 6187."; 465 reference 466 "RFC 6187: X.509v3 Certificates for Secure Shell 467 Authentication"; 468 } 470 feature ssh-dh-group-exchange { 471 description 472 "Diffie-Hellman Group Exchange is supported for SSH."; 473 reference 474 "RFC 4419: Diffie-Hellman Group Exchange for the 475 Secure Shell (SSH) Transport Layer Protocol"; 476 } 478 feature ssh-ctr { 479 description 480 "SDCTR encryption mode is supported for SSH."; 481 reference 482 "RFC 4344: The Secure Shell (SSH) Transport Layer 483 Encryption Modes"; 484 } 486 feature ssh-sha2 { 487 description 488 "The SHA2 family of cryptographic hash functions is 489 supported for SSH."; 490 reference 491 "FIPS PUB 180-4: Secure Hash Standard (SHS)"; 492 } 494 // Identities 496 identity public-key-alg-base { 497 description 498 "Base identity used to identify public key algorithms."; 499 } 501 identity ssh-dss { 502 base public-key-alg-base; 503 description 504 "Digital Signature Algorithm using SHA-1 as the 505 hashing algorithm."; 506 reference 507 "RFC 4253: 508 The Secure Shell (SSH) Transport Layer Protocol"; 509 } 511 identity ssh-rsa { 512 base public-key-alg-base; 513 description 514 "RSASSA-PKCS1-v1_5 signature scheme using SHA-1 as the 515 hashing algorithm."; 516 reference 517 "RFC 4253: 518 The Secure Shell (SSH) Transport Layer Protocol"; 519 } 521 identity ecdsa-sha2-nistp256 { 522 if-feature "ssh-ecc and ssh-sha2"; 523 base public-key-alg-base; 524 description 525 "Elliptic Curve Digital Signature Algorithm (ECDSA) using the 526 nistp256 curve and the SHA2 family of hashing algorithms."; 527 reference 528 "RFC 5656: Elliptic Curve Algorithm Integration in the 529 Secure Shell Transport Layer"; 530 } 532 identity ecdsa-sha2-nistp384 { 533 if-feature "ssh-ecc and ssh-sha2"; 534 base public-key-alg-base; 535 description 536 "Elliptic Curve Digital Signature Algorithm (ECDSA) using the 537 nistp384 curve and the SHA2 family of hashing algorithms."; 538 reference 539 "RFC 5656: Elliptic Curve Algorithm Integration in the 540 Secure Shell Transport Layer"; 541 } 543 identity ecdsa-sha2-nistp521 { 544 if-feature "ssh-ecc and ssh-sha2"; 545 base public-key-alg-base; 546 description 547 "Elliptic Curve Digital Signature Algorithm (ECDSA) using the 548 nistp521 curve and the SHA2 family of hashing algorithms."; 549 reference 550 "RFC 5656: Elliptic Curve Algorithm Integration in the 551 Secure Shell Transport Layer"; 552 } 554 identity x509v3-ssh-rsa { 555 if-feature "ssh-x509-certs"; 556 base public-key-alg-base; 557 description 558 "RSASSA-PKCS1-v1_5 signature scheme using a public key stored 559 in an X.509v3 certificate and using SHA-1 as the hashing 560 algorithm."; 561 reference 562 "RFC 6187: X.509v3 Certificates for Secure Shell 563 Authentication"; 564 } 566 identity x509v3-rsa2048-sha256 { 567 if-feature "ssh-x509-certs and ssh-sha2"; 568 base public-key-alg-base; 569 description 570 "RSASSA-PKCS1-v1_5 signature scheme using a public key stored 571 in an X.509v3 certificate and using SHA-256 as the hashing 572 algorithm. RSA keys conveyed using this format MUST have a 573 modulus of at least 2048 bits."; 574 reference 575 "RFC 6187: X.509v3 Certificates for Secure Shell 576 Authentication"; 577 } 579 identity x509v3-ecdsa-sha2-nistp256 { 580 if-feature "ssh-ecc and ssh-x509-certs and ssh-sha2"; 581 base public-key-alg-base; 582 description 583 "Elliptic Curve Digital Signature Algorithm (ECDSA) 584 using the nistp256 curve with a public key stored in 585 an X.509v3 certificate and using the SHA2 family of 586 hashing algorithms."; 587 reference 588 "RFC 6187: X.509v3 Certificates for Secure Shell 589 Authentication"; 590 } 592 identity x509v3-ecdsa-sha2-nistp384 { 593 if-feature "ssh-ecc and ssh-x509-certs and ssh-sha2"; 594 base public-key-alg-base; 595 description 596 "Elliptic Curve Digital Signature Algorithm (ECDSA) 597 using the nistp384 curve with a public key stored in 598 an X.509v3 certificate and using the SHA2 family of 599 hashing algorithms."; 600 reference 601 "RFC 6187: X.509v3 Certificates for Secure Shell 602 Authentication"; 603 } 605 identity x509v3-ecdsa-sha2-nistp521 { 606 if-feature "ssh-ecc and ssh-x509-certs and ssh-sha2"; 607 base public-key-alg-base; 608 description 609 "Elliptic Curve Digital Signature Algorithm (ECDSA) 610 using the nistp521 curve with a public key stored in 611 an X.509v3 certificate and using the SHA2 family of 612 hashing algorithms."; 613 reference 614 "RFC 6187: X.509v3 Certificates for Secure Shell 615 Authentication"; 616 } 618 identity key-exchange-alg-base { 619 description 620 "Base identity used to identify key exchange algorithms."; 621 } 623 identity diffie-hellman-group14-sha1 { 624 base key-exchange-alg-base; 625 description 626 "Diffie-Hellman key exchange with SHA-1 as HASH and 627 Oakley Group 14 (2048-bit MODP Group)."; 628 reference 629 "RFC 4253: The Secure Shell (SSH) Transport Layer Protocol"; 630 } 632 identity diffie-hellman-group-exchange-sha1 { 633 if-feature "ssh-dh-group-exchange"; 634 base key-exchange-alg-base; 635 description 636 "Diffie-Hellman Group and Key Exchange with SHA-1 as HASH."; 637 reference 638 "RFC 4419: Diffie-Hellman Group Exchange for the 639 Secure Shell (SSH) Transport Layer Protocol"; 640 } 642 identity diffie-hellman-group-exchange-sha256 { 643 if-feature "ssh-dh-group-exchange and ssh-sha2"; 644 base key-exchange-alg-base; 645 description 646 "Diffie-Hellman Group and Key Exchange with SHA-256 as HASH."; 647 reference 648 "RFC 4419: Diffie-Hellman Group Exchange for the 649 Secure Shell (SSH) Transport Layer Protocol"; 650 } 652 identity ecdh-sha2-nistp256 { 653 if-feature "ssh-ecc and ssh-sha2"; 654 base key-exchange-alg-base; 655 description 656 "Elliptic Curve Diffie-Hellman (ECDH) key exchange using the 657 nistp256 curve and the SHA2 family of hashing algorithms."; 658 reference 659 "RFC 5656: Elliptic Curve Algorithm Integration in the 660 Secure Shell Transport Layer"; 661 } 663 identity ecdh-sha2-nistp384 { 664 if-feature "ssh-ecc and ssh-sha2"; 665 base key-exchange-alg-base; 666 description 667 "Elliptic Curve Diffie-Hellman (ECDH) key exchange using the 668 nistp384 curve and the SHA2 family of hashing algorithms."; 669 reference 670 "RFC 5656: Elliptic Curve Algorithm Integration in the 671 Secure Shell Transport Layer"; 672 } 674 identity ecdh-sha2-nistp521 { 675 if-feature "ssh-ecc and ssh-sha2"; 676 base key-exchange-alg-base; 677 description 678 "Elliptic Curve Diffie-Hellman (ECDH) key exchange using the 679 nistp521 curve and the SHA2 family of hashing algorithms."; 680 reference 681 "RFC 5656: Elliptic Curve Algorithm Integration in the 682 Secure Shell Transport Layer"; 683 } 685 identity encryption-alg-base { 686 description 687 "Base identity used to identify encryption algorithms."; 688 } 690 identity triple-des-cbc { 691 base encryption-alg-base; 692 description 693 "Three-key 3DES in CBC mode."; 694 reference 695 "RFC 4253: The Secure Shell (SSH) Transport Layer Protocol"; 696 } 698 identity aes128-cbc { 699 base encryption-alg-base; 700 description 701 "AES in CBC mode, with a 128-bit key."; 702 reference 703 "RFC 4253: The Secure Shell (SSH) Transport Layer Protocol"; 705 } 707 identity aes192-cbc { 708 base encryption-alg-base; 709 description 710 "AES in CBC mode, with a 192-bit key."; 711 reference 712 "RFC 4253: The Secure Shell (SSH) Transport Layer Protocol"; 713 } 715 identity aes256-cbc { 716 base encryption-alg-base; 717 description 718 "AES in CBC mode, with a 256-bit key."; 719 reference 720 "RFC 4253: The Secure Shell (SSH) Transport Layer Protocol"; 721 } 723 identity aes128-ctr { 724 if-feature "ssh-ctr"; 725 base encryption-alg-base; 726 description 727 "AES in SDCTR mode, with 128-bit key."; 728 reference 729 "RFC 4344: The Secure Shell (SSH) Transport Layer Encryption 730 Modes"; 731 } 733 identity aes192-ctr { 734 if-feature "ssh-ctr"; 735 base encryption-alg-base; 736 description 737 "AES in SDCTR mode, with 192-bit key."; 738 reference 739 "RFC 4344: The Secure Shell (SSH) Transport Layer Encryption 740 Modes"; 741 } 743 identity aes256-ctr { 744 if-feature "ssh-ctr"; 745 base encryption-alg-base; 746 description 747 "AES in SDCTR mode, with 256-bit key."; 748 reference 749 "RFC 4344: The Secure Shell (SSH) Transport Layer Encryption 750 Modes"; 751 } 752 identity mac-alg-base { 753 description 754 "Base identity used to identify message authentication 755 code (MAC) algorithms."; 756 } 758 identity hmac-sha1 { 759 base mac-alg-base; 760 description 761 "HMAC-SHA1"; 762 reference 763 "RFC 4253: The Secure Shell (SSH) Transport Layer Protocol"; 764 } 766 identity hmac-sha2-256 { 767 if-feature "ssh-sha2"; 768 base mac-alg-base; 769 description 770 "HMAC-SHA2-256"; 771 reference 772 "RFC 6668: SHA-2 Data Integrity Verification for the 773 Secure Shell (SSH) Transport Layer Protocol"; 774 } 776 identity hmac-sha2-512 { 777 if-feature "ssh-sha2"; 778 base mac-alg-base; 779 description 780 "HMAC-SHA2-512"; 781 reference 782 "RFC 6668: SHA-2 Data Integrity Verification for the 783 Secure Shell (SSH) Transport Layer Protocol"; 784 } 786 // Groupings 788 grouping transport-params-grouping { 789 description 790 "A reusable grouping for SSH transport parameters."; 791 reference 792 "RFC 4253: The Secure Shell (SSH) Transport Layer Protocol"; 793 container host-key { 794 description 795 "Parameters regarding host key."; 796 leaf-list host-key-alg { 797 type identityref { 798 base public-key-alg-base; 799 } 800 ordered-by user; 801 description 802 "Acceptable host key algorithms in order of descending 803 preference. The configured host key algorithms should 804 be compatible with the algorithm used by the configured 805 private key. Please see Section 5 of RFC EEEE for 806 valid combinations. 808 If this leaf-list is not configured (has zero elements) 809 the acceptable host key algorithms are implementation- 810 defined."; 811 reference 812 "RFC EEEE: YANG Groupings for SSH Clients and SSH Servers"; 813 } 814 } 815 container key-exchange { 816 description 817 "Parameters regarding key exchange."; 818 leaf-list key-exchange-alg { 819 type identityref { 820 base key-exchange-alg-base; 821 } 822 ordered-by user; 823 description 824 "Acceptable key exchange algorithms in order of descending 825 preference. 827 If this leaf-list is not configured (has zero elements) 828 the acceptable key exchange algorithms are implementation 829 defined."; 830 } 831 } 832 container encryption { 833 description 834 "Parameters regarding encryption."; 835 leaf-list encryption-alg { 836 type identityref { 837 base encryption-alg-base; 838 } 839 ordered-by user; 840 description 841 "Acceptable encryption algorithms in order of descending 842 preference. 844 If this leaf-list is not configured (has zero elements) 845 the acceptable encryption algorithms are implementation 846 defined."; 847 } 849 } 850 container mac { 851 description 852 "Parameters regarding message authentication code (MAC)."; 853 leaf-list mac-alg { 854 type identityref { 855 base mac-alg-base; 856 } 857 ordered-by user; 858 description 859 "Acceptable MAC algorithms in order of descending 860 preference. 862 If this leaf-list is not configured (has zero elements) 863 the acceptable MAC algorithms are implementation- 864 defined."; 865 } 866 } 867 } 868 } 870 872 3. The "ietf-ssh-client" Module 874 3.1. Data Model Overview 876 3.1.1. Features 878 The following diagram lists all the "feature" statements defined in 879 the "ietf-ssh-client" module: 881 Features: 882 +-- ssh-client-transport-params-config 883 +-- ssh-client-keepalives 884 +-- client-identity-password 885 +-- client-identity-publickey 886 +-- client-identity-hostbased 887 +-- client-identity-none 889 3.1.2. Groupings 891 The following diagram lists all the "grouping" statements defined in 892 the "ietf-ssh-client" module: 894 Groupings: 895 +-- ssh-client-grouping 897 Each of these groupings are presented in the following subsections. 899 3.1.2.1. The "ssh-client-grouping" Grouping 901 The following tree diagram [RFC8340] illustrates the "ssh-client- 902 grouping" grouping: 904 =============== NOTE: '\' line wrapping per RFC 8792 ================ 906 grouping ssh-client-grouping 907 +-- client-identity 908 | +-- username? string 909 | +-- public-key! {client-identity-publickey}? 910 | | +---u ks:local-or-keystore-asymmetric-key-grouping 911 | +-- password? string {client-identity-password}? 912 | +-- hostbased! {client-identity-hostbased}? 913 | | +---u ks:local-or-keystore-asymmetric-key-grouping 914 | +-- none? empty {client-identity-none}? 915 | +-- certificate! {sshcmn:ssh-x509-certs}? 916 | +---u ks:local-or-keystore-end-entity-cert-with-key-groupi\ 917 ng 918 +-- server-authentication 919 | +-- ssh-host-keys! 920 | | +---u ts:local-or-truststore-public-keys-grouping 921 | +-- ca-certs! {sshcmn:ssh-x509-certs}? 922 | | +---u ts:local-or-truststore-certs-grouping 923 | +-- ee-certs! {sshcmn:ssh-x509-certs}? 924 | +---u ts:local-or-truststore-certs-grouping 925 +-- transport-params {ssh-client-transport-params-config}? 926 | +---u sshcmn:transport-params-grouping 927 +-- keepalives! {ssh-client-keepalives}? 928 +-- max-wait? uint16 929 +-- max-attempts? uint8 931 Comments: 933 * The "client-identity" node configures a "username" and 934 credentials, each enabled by a "feature" statement defined in 935 Section 3.1.1. 937 * The "server-authentication" node configures trust anchors for 938 authenticating the SSH server, with each option enabled by a 939 "feature" statement. 941 * The "transport-params" node, which must be enabled by a feature, 942 configures parameters for the SSH sessions established by this 943 configuration. 945 * The "keepalives" node, which must be enabled by a feature, 946 configures a "presence" container for testing the aliveness of the 947 SSH server. The aliveness-test occurs at the SSH protocol layer. 949 * For the referenced grouping statement(s): 951 - The "local-or-keystore-asymmetric-key-grouping" grouping is 952 discussed in Section 2.1.3.4 of [I-D.ietf-netconf-keystore]. 953 - The "local-or-keystore-end-entity-cert-with-key-grouping" 954 grouping is discussed in Section 2.1.3.6 of 955 [I-D.ietf-netconf-keystore]. 956 - The "local-or-truststore-public-keys-grouping" grouping is 957 discussed in Section 2.1.3.2 of 958 [I-D.ietf-netconf-trust-anchors]. 959 - The "local-or-truststore-certs-grouping" grouping is discussed 960 in Section 2.1.3.1 of [I-D.ietf-netconf-trust-anchors]. 961 - The "transport-params-grouping" grouping is discussed in 962 Section 2.1.3.1 in this document. 964 3.2. Example Usage 966 This section presents two examples showing the "ssh-client-grouping" 967 grouping populated with some data. These examples are effectively 968 the same except the first configures the client identity using a 969 local key while the second uses a key configured in a keystore. Both 970 examples are consistent with the examples presented in Section 2 of 971 [I-D.ietf-netconf-trust-anchors] and Section 3.2 of 972 [I-D.ietf-netconf-keystore]. 974 The following configuration example uses local-definitions for the 975 client identity and server authentication: 977 =============== NOTE: '\\' line wrapping per RFC 8792 =============== 979 984 985 986 foobar 987 988 989 ct:ssh-public-key-format 991 base64encodedvalue== 992 ct:rsa-private-key-format 995 base64encodedvalue== 996 997 998 1000 1001 1002 1003 1005 1006 1007 corp-fw1 1008 ct:ssh-public-key-format 1010 base64encodedvalue== 1011 1015 1016 1017 corp-fw2 1018 ct:ssh-public-key-format 1020 base64encodedvalue== 1021 1022 1023 1024 1025 1026 1027 1028 Server Cert Issuer #1 1029 base64encodedvalue== 1030 1031 1032 Server Cert Issuer #2 1033 base64encodedvalue== 1034 1035 1036 1037 1038 1039 1040 My Application #1 1041 base64encodedvalue== 1043 1044 1045 My Application #2 1046 base64encodedvalue== 1047 1048 1049 1050 1052 1053 30 1054 3 1055 1057 1059 The following configuration example uses keystore-references for the 1060 client identity and truststore-references for server authentication: 1061 from the keystore: 1063 =============== NOTE: '\' line wrapping per RFC 8792 ================ 1065 1069 1070 1071 foobar 1072 1077 1078 1079 ssh-rsa-key-with-cert 1080 ex-rsa-cert2 1081 1082 1083 1085 1086 1087 1089 trusted-ssh-public-keys 1091 1092 1093 trusted-server-ca-certs 1095 1096 1097 trusted-server-ee-certs 1099 1100 1102 1103 30 1104 3 1105 1107 1109 3.3. YANG Module 1111 This YANG module has normative references to 1112 [I-D.ietf-netconf-trust-anchors], and [I-D.ietf-netconf-keystore]. 1114 file "ietf-ssh-client@2020-07-08.yang" 1116 module ietf-ssh-client { 1117 yang-version 1.1; 1118 namespace "urn:ietf:params:xml:ns:yang:ietf-ssh-client"; 1119 prefix sshc; 1121 import ietf-netconf-acm { 1122 prefix nacm; 1123 reference 1124 "RFC 8341: Network Configuration Access Control Model"; 1125 } 1127 import ietf-crypto-types { 1128 prefix ct; 1129 reference 1130 "RFC AAAA: YANG Data Types and Groupings for Cryptography"; 1131 } 1133 import ietf-truststore { 1134 prefix ts; 1135 reference 1136 "RFC BBBB: A YANG Data Model for a Truststore"; 1137 } 1139 import ietf-keystore { 1140 prefix ks; 1141 reference 1142 "RFC CCCC: A YANG Data Model for a Keystore"; 1143 } 1145 import ietf-ssh-common { 1146 prefix sshcmn; 1147 revision-date 2020-07-08; // stable grouping definitions 1148 reference 1149 "RFC EEEE: YANG Groupings for SSH Clients and SSH Servers"; 1150 } 1152 organization 1153 "IETF NETCONF (Network Configuration) Working Group"; 1155 contact 1156 "WG Web: 1157 WG List: 1158 Author: Kent Watsen 1159 Author: Gary Wu "; 1161 description 1162 "This module defines reusable groupings for SSH clients that 1163 can be used as a basis for specific SSH client instances. 1165 Copyright (c) 2020 IETF Trust and the persons identified 1166 as authors of the code. All rights reserved. 1168 Redistribution and use in source and binary forms, with 1169 or without modification, is permitted pursuant to, and 1170 subject to the license terms contained in, the Simplified 1171 BSD License set forth in Section 4.c of the IETF Trust's 1172 Legal Provisions Relating to IETF Documents 1173 (https://trustee.ietf.org/license-info). 1175 This version of this YANG module is part of RFC EEEE 1176 (https://www.rfc-editor.org/info/rfcEEEE); see the RFC 1177 itself for full legal notices.; 1179 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1180 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 1181 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 1182 are to be interpreted as described in BCP 14 (RFC 2119) 1183 (RFC 8174) when, and only when, they appear in all 1184 capitals, as shown here."; 1186 revision 2020-07-08 { 1187 description 1188 "Initial version"; 1189 reference 1190 "RFC EEEE: YANG Groupings for SSH Clients and SSH Servers"; 1191 } 1193 // Features 1195 feature ssh-client-transport-params-config { 1196 description 1197 "SSH transport layer parameters are configurable on an SSH 1198 client."; 1199 } 1201 feature ssh-client-keepalives { 1202 description 1203 "Per socket SSH keepalive parameters are configurable for 1204 SSH clients on the server implementing this feature."; 1206 } 1208 feature client-identity-password { 1209 description 1210 "Indicates that the 'password' authentication type 1211 is supported for client identification."; 1212 } 1214 feature client-identity-publickey { 1215 description 1216 "Indicates that the 'publickey' authentication type 1217 is supported for client identification. 1219 The 'publickey' authentication type is required by 1220 RFC 4252, but common implementations enable it to 1221 be disabled."; 1222 } 1224 feature client-identity-hostbased { 1225 description 1226 "Indicates that the 'hostbased' authentication type 1227 is supported for client identification."; 1228 } 1230 feature client-identity-none { 1231 description 1232 "Indicates that the 'none' authentication type is 1233 supported for client identification."; 1234 } 1236 // Groupings 1238 grouping ssh-client-grouping { 1239 description 1240 "A reusable grouping for configuring a SSH client without 1241 any consideration for how an underlying TCP session is 1242 established. 1244 Note that this grouping uses fairly typical descendent 1245 node names such that a stack of 'uses' statements will 1246 have name conflicts. It is intended that the consuming 1247 data model will resolve the issue (e.g., by wrapping 1248 the 'uses' statement in a container called 1249 'ssh-client-parameters'). This model purposely does 1250 not do this itself so as to provide maximum flexibility 1251 to consuming models."; 1253 container client-identity { 1254 nacm:default-deny-write; 1255 must 1256 'public-key or password or hostbased or none or certificate'; 1257 description 1258 "The credentials that the client may use, pending 1259 the SSH server's requirements, by the SSH client 1260 to authenticate to the SSH server."; 1261 leaf username { 1262 type string; 1263 description 1264 "The username of this user. This will be the username 1265 used, for instance, to log into an SSH server."; 1266 } 1267 container public-key { 1268 if-feature client-identity-publickey; 1269 presence 1270 "Indicates that publickey-based authentication 1271 is configured"; 1272 description 1273 "A locally-defined or referenced asymmetric key 1274 pair to be used for client identification."; 1275 reference 1276 "RFC CCCC: A YANG Data Model for a Keystore"; 1277 uses ks:local-or-keystore-asymmetric-key-grouping { 1278 refine "local-or-keystore/local/local-definition" { 1279 must 'public-key-format = "ct:ssh-public-key-format"'; 1280 } 1281 refine "local-or-keystore/keystore/keystore-reference" { 1282 must 'deref(.)/../ks:public-key-format' 1283 + ' = "ct:ssh-public-key-format"'; 1284 } 1285 } 1286 } 1287 leaf password { 1288 if-feature client-identity-password; 1289 nacm:default-deny-all; 1290 type string; 1291 description 1292 "A password to be used for client identification."; 1293 } 1294 container hostbased { 1295 if-feature client-identity-hostbased; 1296 presence 1297 "Indicates that hostbased authentication is configured"; 1298 description 1299 "A locally-defined or referenced asymmetric key 1300 pair to be used for host identification."; 1301 reference 1302 "RFC CCCC: A YANG Data Model for a Keystore"; 1303 uses ks:local-or-keystore-asymmetric-key-grouping { 1304 refine "local-or-keystore/local/local-definition" { 1305 must 'public-key-format = "ct:ssh-public-key-format"'; 1306 } 1307 refine "local-or-keystore/keystore/keystore-reference" { 1308 must 'deref(.)/../ks:public-key-format' 1309 + ' = "ct:ssh-public-key-format"'; 1310 } 1311 } 1312 } 1313 leaf none { 1314 if-feature client-identity-none; 1315 type empty; 1316 description 1317 "Indicates that 'none' algorithm is used for client 1318 identification."; 1319 } 1320 container certificate { 1321 if-feature "sshcmn:ssh-x509-certs"; 1322 presence 1323 "Indicates that certificate-based authentication 1324 is configured"; 1325 description 1326 "A locally-defined or referenced certificate 1327 to be used for client identification."; 1328 reference 1329 "RFC CCCC: A YANG Data Model for a Keystore"; 1330 uses 1331 ks:local-or-keystore-end-entity-cert-with-key-grouping { 1332 refine "local-or-keystore/local/local-definition" { 1333 must 1334 'public-key-format' 1335 + ' = "ct:subject-public-key-info-format"'; 1336 } 1337 refine "local-or-keystore/keystore/keystore-reference" 1338 + "/asymmetric-key" { 1339 must 'deref(.)/../ks:public-key-format' 1340 + ' = "ct:subject-public-key-info-format"'; 1341 } 1342 } 1343 } 1344 } // container client-identity 1346 container server-authentication { 1347 nacm:default-deny-write; 1348 must 'ssh-host-keys or ca-certs or ee-certs'; 1349 description 1350 "Specifies how the SSH client can authenticate SSH servers. 1351 Any combination of credentials is additive and unordered."; 1352 container ssh-host-keys { 1353 presence 1354 "Indicates that the client can authenticate servers 1355 using the configured SSH host keys."; 1356 description 1357 "A list of SSH host keys used by the SSH client to 1358 authenticate SSH server host keys. A server host key 1359 is authenticated if it is an exact match to a 1360 configured SSH host key."; 1361 reference 1362 "RFC BBBB: A YANG Data Model for a Truststore"; 1363 uses ts:local-or-truststore-public-keys-grouping { 1364 refine 1365 "local-or-truststore/local/local-definition/public-key" { 1366 must 'public-key-format = "ct:ssh-public-key-format"'; 1367 } 1368 refine 1369 "local-or-truststore/truststore/truststore-reference" { 1370 must 'deref(.)/../*/ts:public-key-format' 1371 + ' = "ct:ssh-public-key-format"'; 1372 } 1373 } 1374 } 1375 container ca-certs { 1376 if-feature "sshcmn:ssh-x509-certs"; 1377 presence 1378 "Indicates that the client can authenticate servers 1379 using the configured trust anchor certificates."; 1380 description 1381 "A set of certificate authority (CA) certificates used by 1382 the SSH client to authenticate SSH servers. A server 1383 is authenticated if its certificate has a valid chain 1384 of trust to a configured CA certificate."; 1385 reference 1386 "RFC BBBB: A YANG Data Model for a Truststore"; 1387 uses ts:local-or-truststore-certs-grouping; 1388 } 1389 container ee-certs { 1390 if-feature "sshcmn:ssh-x509-certs"; 1391 presence 1392 "Indicates that the client can authenticate servers 1393 using the configured end-entity certificates."; 1394 description 1395 "A set of end-entity certificates used by the SSH client 1396 to authenticate SSH servers. A server is authenticated 1397 if its certificate is an exact match to a configured 1398 end-entity certificate."; 1399 reference 1400 "RFC BBBB: A YANG Data Model for a Truststore"; 1401 uses ts:local-or-truststore-certs-grouping; 1402 } 1403 } // container server-authentication 1405 container transport-params { 1406 nacm:default-deny-write; 1407 if-feature "ssh-client-transport-params-config"; 1408 description 1409 "Configurable parameters of the SSH transport layer."; 1410 uses sshcmn:transport-params-grouping; 1411 } // container transport-parameters 1413 container keepalives { 1414 nacm:default-deny-write; 1415 if-feature "ssh-client-keepalives"; 1416 presence 1417 "Indicates that the SSH client proactively tests the 1418 aliveness of the remote SSH server."; 1419 description 1420 "Configures the keep-alive policy, to proactively test 1421 the aliveness of the SSH server. An unresponsive TLS 1422 server is dropped after approximately max-wait * 1423 max-attempts seconds. Per Section 4 of RFC 4254, 1424 the SSH client SHOULD send an SSH_MSG_GLOBAL_REQUEST 1425 message with a purposely nonexistent 'request name' 1426 value (e.g., keepalive@ietf.org) and the 'want reply' 1427 value set to '1'."; 1428 reference 1429 "RFC 4254: The Secure Shell (SSH) Connection Protocol"; 1430 leaf max-wait { 1431 type uint16 { 1432 range "1..max"; 1433 } 1434 units "seconds"; 1435 default "30"; 1436 description 1437 "Sets the amount of time in seconds after which if 1438 no data has been received from the SSH server, a 1439 TLS-level message will be sent to test the 1440 aliveness of the SSH server."; 1441 } 1442 leaf max-attempts { 1443 type uint8; 1444 default "3"; 1445 description 1446 "Sets the maximum number of sequential keep-alive 1447 messages that can fail to obtain a response from 1448 the SSH server before assuming the SSH server is 1449 no longer alive."; 1450 } 1451 } // container keepalives 1452 } // grouping ssh-client-grouping 1453 } // module ietf-ssh-client 1455 1457 4. The "ietf-ssh-server" Module 1459 4.1. Data Model Overview 1461 4.1.1. Features 1463 The following diagram lists all the "feature" statements defined in 1464 the "ietf-ssh-server" module: 1466 Features: 1467 +-- ssh-server-transport-params-config 1468 +-- ssh-server-keepalives 1469 +-- client-auth-config-supported 1470 +-- client-auth-publickey 1471 +-- client-auth-password 1472 +-- client-auth-hostbased 1473 +-- client-auth-none 1475 4.1.2. Groupings 1477 The following diagram lists all the "grouping" statements defined in 1478 the "ietf-ssh-server" module: 1480 Groupings: 1481 +-- ssh-server-grouping 1483 Each of these groupings are presented in the following subsections. 1485 4.1.2.1. The "ssh-server-grouping" Grouping 1487 The following tree diagram [RFC8340] illustrates the "ssh-server- 1488 grouping" grouping: 1490 =============== NOTE: '\' line wrapping per RFC 8792 ================ 1492 grouping ssh-server-grouping 1493 +-- server-identity 1494 | +-- host-key* [name] 1495 | +-- name? string 1496 | +-- (host-key-type) 1497 | +--:(public-key) 1498 | | +-- public-key 1499 | | +---u ks:local-or-keystore-asymmetric-key-grouping 1500 | +--:(certificate) 1501 | +-- certificate {sshcmn:ssh-x509-certs}? 1502 | +---u ks:local-or-keystore-end-entity-cert-with-k\ 1503 ey-grouping 1504 +-- client-authentication 1505 | +-- supported-authentication-methods 1506 | | +-- publickey? empty 1507 | | +-- password? empty {client-auth-password}? 1508 | | +-- hostbased? empty {client-auth-hostbased}? 1509 | | +-- none? empty {client-auth-none}? 1510 | +-- users {client-auth-config-supported}? 1511 | | +-- user* [name] 1512 | | +-- name? string 1513 | | +-- public-keys! {client-auth-publickey}? 1514 | | | +---u ts:local-or-truststore-public-keys-grouping 1515 | | +-- password? ianach:crypt-hash 1516 | | | {client-auth-password}? 1517 | | +-- hostbased! {client-auth-hostbased}? 1518 | | | +---u ts:local-or-truststore-public-keys-grouping 1519 | | +-- none? empty {client-auth-none}? 1520 | +-- ca-certs! 1521 | | {client-auth-config-supported,sshcmn:ssh-x509-certs}? 1522 | | +---u ts:local-or-truststore-certs-grouping 1523 | +-- ee-certs! 1524 | {client-auth-config-supported,sshcmn:ssh-x509-certs}? 1525 | +---u ts:local-or-truststore-certs-grouping 1526 +-- transport-params {ssh-server-transport-params-config}? 1527 | +---u sshcmn:transport-params-grouping 1528 +-- keepalives! {ssh-server-keepalives}? 1529 +-- max-wait? uint16 1530 +-- max-attempts? uint8 1532 Comments: 1534 * The "server-identity" node configures identity credentials. The 1535 ability to use a certificate is enabled by a "feature". 1537 * The "client-authentication" node configures trust anchors for 1538 authenticating the SSH client, with each option enabled by a 1539 "feature" statement. 1541 * The "transport-params" node, which must be enabled by a feature, 1542 configures parameters for the SSH sessions established by this 1543 configuration. 1545 * The "keepalives" node, which must be enabled by a feature, 1546 configures a "presence" container for testing the aliveness of the 1547 SSH client. The aliveness-test occurs at the SSH protocol layer. 1549 * For the referenced grouping statement(s): 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-end-entity-cert-with-key-grouping" 1554 grouping is discussed in Section 2.1.3.6 of 1555 [I-D.ietf-netconf-keystore]. 1556 - The "local-or-truststore-public-keys-grouping" grouping is 1557 discussed in Section 2.1.3.2 of 1558 [I-D.ietf-netconf-trust-anchors]. 1559 - The "local-or-truststore-certs-grouping" grouping is discussed 1560 in Section 2.1.3.1 of [I-D.ietf-netconf-trust-anchors]. 1561 - The "transport-params-grouping" grouping is discussed in 1562 Section 2.1.3.1 in this document. 1564 4.2. Example Usage 1566 This section presents two examples showing the "ssh-server-grouping" 1567 grouping populated with some data. These examples are effectively 1568 the same except the first configures the server identity using a 1569 local key while the second uses a key configured in a keystore. Both 1570 examples are consistent with the examples presented in Section 2 of 1571 [I-D.ietf-netconf-trust-anchors] and Section 3.2 of 1572 [I-D.ietf-netconf-keystore]. 1574 The following configuration example uses local-definitions for the 1575 server identity and client authentication: 1577 =============== NOTE: '\' line wrapping per RFC 8792 ================ 1579 1584 1585 1586 1587 my-pubkey-based-host-key 1588 1589 1590 ct:ssh-public-key-format 1592 base64encodedvalue== 1593 ct:rsa-private-key-format 1595 base64encodedvalue== 1596 1597 1598 1599 1600 my-cert-based-host-key 1601 1602 1603 ct:subject-public-key-info-format 1605 base64encodedvalue== 1606 ct:rsa-private-key-format 1608 base64encodedvalue== 1609 base64encodedvalue== 1610 1611 1612 1613 1615 1616 1617 1618 1619 1620 1621 1622 mary 1623 $0$secret 1624 1625 1626 1627 1628 User A 1629 ct:ssh-public-key-format 1631 base64encodedvalue== 1632 1635 1636 1637 User B 1638 ct:ssh-public-key-format 1640 base64encodedvalue== 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 Identity Cert Issuer #1 1651 base64encodedvalue== 1652 1653 1654 Identity Cert Issuer #2 1655 base64encodedvalue== 1656 1657 1658 1659 1660 1661 1662 Application #1 1663 base64encodedvalue== 1664 1665 1666 Application #2 1667 base64encodedvalue== 1668 1669 1670 1671 1673 1674 30 1675 3 1676 1678 1679 The following configuration example uses keystore-references for the 1680 server identity and truststore-references for client authentication: 1681 from the keystore: 1683 =============== NOTE: '\' line wrapping per RFC 8792 ================ 1685 1689 1690 1691 1692 my-pubkey-based-host-key 1693 1694 ssh-rsa-key 1695 1696 1697 1698 my-cert-based-host-key 1699 1700 1701 ssh-rsa-key-with-cert 1702 ex-rsa-cert2 1703 1704 1705 1706 1708 1709 1710 1711 1712 1713 1714 1715 mary 1716 $0$secret 1717 1718 SSH Public Keys for Application A 1720 1721 1722 1723 1724 trusted-client-ca-certs 1726 1727 1728 trusted-client-ee-certs 1730 1731 1733 1734 30 1735 3 1736 1738 1740 4.3. YANG Module 1742 This YANG module has normative references to 1743 [I-D.ietf-netconf-trust-anchors] and [I-D.ietf-netconf-keystore] and 1744 informative references to [RFC4253] and [RFC7317]. 1746 file "ietf-ssh-server@2020-07-08.yang" 1748 module ietf-ssh-server { 1749 yang-version 1.1; 1750 namespace "urn:ietf:params:xml:ns:yang:ietf-ssh-server"; 1751 prefix sshs; 1753 import iana-crypt-hash { 1754 prefix ianach; 1755 reference 1756 "RFC 7317: A YANG Data Model for System Management"; 1757 } 1759 import ietf-netconf-acm { 1760 prefix nacm; 1761 reference 1762 "RFC 8341: Network Configuration Access Control Model"; 1763 } 1765 import ietf-crypto-types { 1766 prefix ct; 1767 reference 1768 "RFC AAAA: YANG Data Types and Groupings for Cryptography"; 1769 } 1771 import ietf-truststore { 1772 prefix ts; 1773 reference 1774 "RFC BBBB: A YANG Data Model for a Truststore"; 1776 } 1778 import ietf-keystore { 1779 prefix ks; 1780 reference 1781 "RFC CCCC: A YANG Data Model for a Keystore"; 1782 } 1784 import ietf-ssh-common { 1785 prefix sshcmn; 1786 revision-date 2020-07-08; // stable grouping definitions 1787 reference 1788 "RFC EEEE: YANG Groupings for SSH Clients and SSH Servers"; 1789 } 1791 organization 1792 "IETF NETCONF (Network Configuration) Working Group"; 1794 contact 1795 "WG Web: 1796 WG List: 1797 Author: Kent Watsen 1798 Author: Gary Wu "; 1800 description 1801 "This module defines reusable groupings for SSH servers that 1802 can be used as a basis for specific SSH server instances. 1804 Copyright (c) 2020 IETF Trust and the persons identified 1805 as authors of the code. All rights reserved. 1807 Redistribution and use in source and binary forms, with 1808 or without modification, is permitted pursuant to, and 1809 subject to the license terms contained in, the Simplified 1810 BSD License set forth in Section 4.c of the IETF Trust's 1811 Legal Provisions Relating to IETF Documents 1812 (https://trustee.ietf.org/license-info). 1814 This version of this YANG module is part of RFC EEEE 1815 (https://www.rfc-editor.org/info/rfcEEEE); see the RFC 1816 itself for full legal notices.; 1818 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1819 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 1820 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 1821 are to be interpreted as described in BCP 14 (RFC 2119) 1822 (RFC 8174) when, and only when, they appear in all 1823 capitals, as shown here."; 1825 revision 2020-07-08 { 1826 description 1827 "Initial version"; 1828 reference 1829 "RFC EEEE: YANG Groupings for SSH Clients and SSH Servers"; 1830 } 1832 // Features 1834 feature ssh-server-transport-params-config { 1835 description 1836 "SSH transport layer parameters are configurable on an SSH 1837 server."; 1838 } 1840 feature ssh-server-keepalives { 1841 description 1842 "Per socket SSH keepalive parameters are configurable for 1843 SSH servers on the server implementing this feature."; 1844 } 1846 feature client-auth-config-supported { 1847 description 1848 "Indicates that the configuration for how to authenticate 1849 clients can be configured herein, as opposed to in an 1850 application specific location. That is, to support the 1851 consuming data models that prefer to place client 1852 authentication with client definitions, rather then 1853 in a data model principally concerned with configuring 1854 the transport."; 1855 } 1857 feature client-auth-publickey { 1858 description 1859 "Indicates that the 'publickey' authentication type 1860 is supported. 1862 The 'publickey' authentication type is required by 1863 RFC 4252, but common implementations enable it to 1864 be disabled."; 1865 reference 1866 "RFC 4252: 1867 The Secure Shell (SSH) Authentication Protocol"; 1868 } 1870 feature client-auth-password { 1871 description 1872 "Indicates that the 'password' authentication type 1873 is supported."; 1874 } 1876 feature client-auth-hostbased { 1877 description 1878 "Indicates that the 'hostbased' authentication type 1879 is supported."; 1880 } 1882 feature client-auth-none { 1883 description 1884 "Indicates that the 'none' authentication type is 1885 supported."; 1886 } 1888 // Groupings 1890 grouping ssh-server-grouping { 1891 description 1892 "A reusable grouping for configuring a SSH server without 1893 any consideration for how underlying TCP sessions are 1894 established. 1896 Note that this grouping uses fairly typical descendent 1897 node names such that a stack of 'uses' statements will 1898 have name conflicts. It is intended that the consuming 1899 data model will resolve the issue (e.g., by wrapping 1900 the 'uses' statement in a container called 1901 'ssh-server-parameters'). This model purposely does 1902 not do this itself so as to provide maximum flexibility 1903 to consuming models."; 1905 container server-identity { 1906 nacm:default-deny-write; 1907 description 1908 "The list of host keys the SSH server will present when 1909 establishing a SSH connection."; 1910 list host-key { 1911 key "name"; 1912 min-elements 1; 1913 ordered-by user; 1914 description 1915 "An ordered list of host keys the SSH server will use to 1916 construct its ordered list of algorithms, when sending 1917 its SSH_MSG_KEXINIT message, as defined in Section 7.1 1918 of RFC 4253."; 1919 reference 1920 "RFC 4253: The Secure Shell (SSH) Transport Layer 1921 Protocol"; 1922 leaf name { 1923 type string; 1924 description 1925 "An arbitrary name for this host key"; 1926 } 1927 choice host-key-type { 1928 mandatory true; 1929 description 1930 "The type of host key being specified"; 1931 container public-key { 1932 description 1933 "A locally-defined or referenced asymmetric key pair 1934 to be used for the SSH server's host key."; 1935 reference 1936 "RFC CCCC: A YANG Data Model for a Keystore"; 1937 uses ks:local-or-keystore-asymmetric-key-grouping { 1938 refine "local-or-keystore/local/local-definition" { 1939 must 1940 'public-key-format = "ct:ssh-public-key-format"'; 1941 } 1942 refine "local-or-keystore/keystore/" 1943 + "keystore-reference" { 1944 must 'deref(.)/../ks:public-key-format' 1945 + ' = "ct:ssh-public-key-format"'; 1946 } 1947 } 1948 } 1949 container certificate { 1950 if-feature "sshcmn:ssh-x509-certs"; 1951 description 1952 "A locally-defined or referenced end-entity 1953 certificate to be used for the SSH server's 1954 host key."; 1955 reference 1956 "RFC CCCC: A YANG Data Model for a Keystore"; 1957 uses 1958 ks:local-or-keystore-end-entity-cert-with-key-grouping { 1959 refine "local-or-keystore/local/local-definition" { 1960 must 1961 'public-key-format' 1962 + ' = "ct:subject-public-key-info-format"'; 1963 } 1964 refine "local-or-keystore/keystore/keystore-reference" 1965 + "/asymmetric-key" { 1966 must 'deref(.)/../ks:public-key-format' 1967 + ' = "ct:subject-public-key-info-format"'; 1968 } 1970 } 1971 } 1972 } 1973 } 1974 } // container server-identity 1976 container client-authentication { 1977 nacm:default-deny-write; 1978 description 1979 "Specifies how the SSH server can authenticate SSH clients."; 1980 container supported-authentication-methods { 1981 description 1982 "Indicates which authentication methods the server 1983 supports."; 1984 leaf publickey { 1985 type empty; 1986 description 1987 "Indicates that the 'publickey' method is supported. 1988 Note that RFC 6187 X.509v3 Certificates for SSH uses 1989 the 'publickey' method name."; 1990 reference 1991 "RFC 4252: The Secure Shell (SSH) Authentication 1992 Protocol. 1993 RFC 6187: X.509v3 Certificates for Secure Shell 1994 Authentication."; 1995 } 1996 leaf password { 1997 if-feature client-auth-password; 1998 type empty; 1999 description 2000 "Indicates that the 'password' method is supported."; 2001 reference 2002 "RFC 4252: The Secure Shell (SSH) Authentication 2003 Protocol."; 2004 } 2005 leaf hostbased { 2006 if-feature client-auth-hostbased; 2007 type empty; 2008 description 2009 "Indicates that the 'hostbased' method is supported."; 2010 reference 2011 "RFC 4252: The Secure Shell (SSH) Authentication 2012 Protocol."; 2013 } 2014 leaf none { 2015 if-feature client-auth-none; 2016 type empty; 2017 description 2018 "Indicates that the 'none' method is supported."; 2019 reference 2020 "RFC 4252: The Secure Shell (SSH) Authentication 2021 Protocol."; 2022 } 2023 } 2025 container users { 2026 if-feature "client-auth-config-supported"; 2027 description 2028 "A list of locally configured users."; 2029 list user { 2030 key name; 2031 description 2032 "The list of local users configured on this device."; 2033 leaf name { 2034 type string; 2035 description 2036 "The user name string identifying this entry."; 2037 } 2038 container public-keys { 2039 if-feature client-auth-publickey; 2040 presence 2041 "Indicates that the server can authenticate this 2042 user using any of the configured SSH public keys."; 2043 description 2044 "A set of SSH public keys may be used by the SSH 2045 server to authenticate this user. A user is 2046 authenticated if its public key is an exact 2047 match to a configured public key."; 2048 reference 2049 "RFC BBBB: A YANG Data Model for a Truststore"; 2050 uses ts:local-or-truststore-public-keys-grouping { 2051 refine "local-or-truststore/local/local-definition" 2052 + "/public-key" { 2053 must 'public-key-format' 2054 + ' = "ct:ssh-public-key-format"'; 2055 } 2056 refine "local-or-truststore/truststore/" 2057 + "truststore-reference" { 2058 must 'deref(.)/../*/ts:public-key-format' 2059 + ' = "ct:ssh-public-key-format"'; 2060 } 2061 } 2062 } 2063 leaf password { 2064 if-feature client-auth-password; 2065 type ianach:crypt-hash; 2066 description 2067 "The password for this user."; 2068 } 2070 container hostbased { 2071 if-feature client-auth-hostbased; 2072 presence 2073 "Indicates that the server can authenticate this 2074 user's 'host' using any of the configured SSH 2075 host keys."; 2076 description 2077 "A set of SSH host keys may be used by the SSH 2078 server to authenticate this user's host. A 2079 user's host is authenticated if its host key 2080 is an exact match to a configured host key."; 2081 reference 2082 "RFC 4253: The Secure Shell (SSH) Transport Layer 2083 RFC BBBB: A YANG Data Model for a Truststore"; 2084 uses ts:local-or-truststore-public-keys-grouping { 2085 refine "local-or-truststore/local/local-definition" 2086 + "/public-key" { 2087 must 'public-key-format' 2088 + ' = "ct:ssh-public-key-format"'; 2089 } 2090 refine "local-or-truststore/truststore" 2091 + "/truststore-reference" { 2092 must 'deref(.)/../*/ts:public-key-format' 2093 + ' = "ct:ssh-public-key-format"'; 2094 } 2095 } 2096 } 2097 leaf none { 2098 if-feature client-auth-none; 2099 type empty; 2100 description 2101 "Indicates that the 'none' method is supported."; 2102 reference 2103 "RFC 4252: The Secure Shell (SSH) Authentication 2104 Protocol."; 2105 } 2106 } 2107 } 2108 container ca-certs { 2109 if-feature "client-auth-config-supported"; 2110 if-feature "sshcmn:ssh-x509-certs"; 2111 presence 2112 "Indicates that the SSH server can authenticate SSH 2113 clients using configured certificate authority (CA) 2114 certificates."; 2115 description 2116 "A set of certificate authority (CA) certificates used by 2117 the SSH server to authenticate SSH client certificates. 2118 A client certificate is authenticated if it has a valid 2119 chain of trust to a configured CA certificate."; 2120 reference 2121 "RFC BBBB: A YANG Data Model for a Truststore"; 2122 uses ts:local-or-truststore-certs-grouping; 2123 } 2124 container ee-certs { 2125 if-feature "client-auth-config-supported"; 2126 if-feature "sshcmn:ssh-x509-certs"; 2127 presence 2128 "Indicates that the SSH server can authenticate SSH 2129 clients using configured end-entity certificates."; 2130 description 2131 "A set of client certificates (i.e., end entity 2132 certificates) used by the SSH server to authenticate 2133 the certificates presented by SSH clients. A client 2134 certificate is authenticated if it is an exact match 2135 to a configured end-entity certificate."; 2136 reference 2137 "RFC BBBB: A YANG Data Model for a Truststore"; 2138 uses ts:local-or-truststore-certs-grouping; 2139 } 2140 } // container client-authentication 2142 container transport-params { 2143 nacm:default-deny-write; 2144 if-feature "ssh-server-transport-params-config"; 2145 description 2146 "Configurable parameters of the SSH transport layer."; 2147 uses sshcmn:transport-params-grouping; 2148 } // container transport-params 2150 container keepalives { 2151 nacm:default-deny-write; 2152 if-feature "ssh-server-keepalives"; 2153 presence 2154 "Indicates that the SSH server proactively tests the 2155 aliveness of the remote SSH client."; 2156 description 2157 "Configures the keep-alive policy, to proactively test 2158 the aliveness of the SSL client. An unresponsive SSL 2159 client is dropped after approximately max-wait * 2160 max-attempts seconds. Per Section 4 of RFC 4254, 2161 the SSH server SHOULD send an SSH_MSG_GLOBAL_REQUEST 2162 message with a purposely nonexistent 'request name' 2163 value (e.g., keepalive@ietf.org) and the 'want reply' 2164 value set to '1'."; 2165 reference 2166 "RFC 4254: The Secure Shell (SSH) Connection Protocol"; 2167 leaf max-wait { 2168 type uint16 { 2169 range "1..max"; 2170 } 2171 units "seconds"; 2172 default "30"; 2173 description 2174 "Sets the amount of time in seconds after which 2175 if no data has been received from the SSL client, 2176 a SSL-level message will be sent to test the 2177 aliveness of the SSL client."; 2178 } 2179 leaf max-attempts { 2180 type uint8; 2181 default "3"; 2182 description 2183 "Sets the maximum number of sequential keep-alive 2184 messages that can fail to obtain a response from 2185 the SSL client before assuming the SSL client is 2186 no longer alive."; 2187 } 2188 } 2189 } // grouping ssh-server-grouping 2190 } // module ietf-ssh-server 2192 2194 5. Security Considerations 2196 5.1. The "ietf-ssh-common" YANG Module 2198 The "ietf-ssh-common" YANG module defines "grouping" statements that 2199 are designed to be accessed via YANG based management protocols, such 2200 as NETCONF [RFC6241] and RESTCONF [RFC8040]. Both of these protocols 2201 have mandatory-to-implement secure transport layers (e.g., SSH, TLS) 2202 with mutual authentication. 2204 The NETCONF access control model (NACM) [RFC8341] provides the means 2205 to restrict access for particular users to a pre-configured subset of 2206 all available protocol operations and content. 2208 Since the module in this document only define groupings, these 2209 considerations are primarily for the designers of other modules that 2210 use these groupings. 2212 None of the readable data nodes defined in this YANG module are 2213 considered sensitive or vulnerable in network environments. The NACM 2214 "default-deny-all" extension has not been set for any data nodes 2215 defined in this module. 2217 None of the writable data nodes defined in this YANG module are 2218 considered sensitive or vulnerable in network environments. The NACM 2219 "default-deny-write" extension has not been set for any data nodes 2220 defined in this module. 2222 This module does not define any RPCs, actions, or notifications, and 2223 thus the security consideration for such is not provided here. 2225 5.2. The "ietf-ssh-client" YANG Module 2227 The "ietf-ssh-client" YANG module defines "grouping" statements that 2228 are designed to be accessed via YANG based management protocols, such 2229 as NETCONF [RFC6241] and RESTCONF [RFC8040]. Both of these protocols 2230 have mandatory-to-implement secure transport layers (e.g., SSH, TLS) 2231 with mutual authentication. 2233 The NETCONF access control model (NACM) [RFC8341] provides the means 2234 to restrict access for particular users to a pre-configured subset of 2235 all available protocol operations and content. 2237 Since the module in this document only define groupings, these 2238 considerations are primarily for the designers of other modules that 2239 use these groupings. 2241 One readable data node defined in this YANG module may be considered 2242 sensitive or vulnerable in some network environments. This node is 2243 as follows: 2245 * The "client-identity/password" node: 2247 The cleartext "password" node defined in the "ssh-client- 2248 grouping" grouping is additionally sensitive to read operations 2249 such that, in normal use cases, it should never be returned to 2250 a client. For this reason, the NACM extension "default-deny- 2251 all" has been applied to it. 2253 | Please be aware that this module uses the "key" and "private- 2254 | key" nodes from the "ietf-crypto-types" module 2255 | [I-D.ietf-netconf-crypto-types], where said nodes have the NACM 2256 | extension "default-deny-all" set, thus preventing unrestricted 2257 | read-access to the cleartext key values. 2259 All of the writable data nodes defined by this module may be 2260 considered sensitive or vulnerable in some network environments. For 2261 instance, any modification to a key or reference to a key may 2262 dramatically alter the implemented security policy. For this reason, 2263 the NACM extension "default-deny-write" has been set for all data 2264 nodes defined in this module. 2266 This module does not define any RPCs, actions, or notifications, and 2267 thus the security consideration for such is not provided here. 2269 5.3. The "ietf-ssh-server" YANG Module 2271 The "ietf-ssh-server" YANG module defines "grouping" statements that 2272 are designed to be accessed via YANG based management protocols, such 2273 as NETCONF [RFC6241] and RESTCONF [RFC8040]. Both of these protocols 2274 have mandatory-to-implement secure transport layers (e.g., SSH, TLS) 2275 with mutual authentication. 2277 The NETCONF access control model (NACM) [RFC8341] provides the means 2278 to restrict access for particular users to a pre-configured subset of 2279 all available protocol operations and content. 2281 Since the module in this document only define groupings, these 2282 considerations are primarily for the designers of other modules that 2283 use these groupings. 2285 None of the readable data nodes defined in this YANG module are 2286 considered sensitive or vulnerable in network environments. The NACM 2287 "default-deny-all" extension has not been set for any data nodes 2288 defined in this module. 2290 | Please be aware that this module uses the "key" and "private- 2291 | key" nodes from the "ietf-crypto-types" module 2292 | [I-D.ietf-netconf-crypto-types], where said nodes have the NACM 2293 | extension "default-deny-all" set, thus preventing unrestricted 2294 | read-access to the cleartext key values. 2296 All of the writable data nodes defined by this module may be 2297 considered sensitive or vulnerable in some network environments. For 2298 instance, the addition or removal of references to keys, 2299 certificates, trusted anchors, etc., or even the modification of 2300 transport or keepalive parameters can dramatically alter the 2301 implemented security policy. For this reason, the NACM extension 2302 "default-deny-write" has been set for all data nodes defined in this 2303 module. 2305 This module does not define any RPCs, actions, or notifications, and 2306 thus the security consideration for such is not provided here. 2308 6. IANA Considerations 2310 6.1. The IETF XML Registry 2312 This document registers three URIs in the "ns" subregistry of the 2313 IETF XML Registry [RFC3688]. Following the format in [RFC3688], the 2314 following registrations are requested: 2316 URI: urn:ietf:params:xml:ns:yang:ietf-ssh-common 2317 Registrant Contact: The NETCONF WG of the IETF. 2318 XML: N/A, the requested URI is an XML namespace. 2320 URI: urn:ietf:params:xml:ns:yang:ietf-ssh-client 2321 Registrant Contact: The NETCONF WG of the IETF. 2322 XML: N/A, the requested URI is an XML namespace. 2324 URI: urn:ietf:params:xml:ns:yang:ietf-ssh-server 2325 Registrant Contact: The NETCONF WG of the IETF. 2326 XML: N/A, the requested URI is an XML namespace. 2328 6.2. The YANG Module Names Registry 2330 This document registers three YANG modules in the YANG Module Names 2331 registry [RFC6020]. Following the format in [RFC6020], the following 2332 registrations are requested: 2334 name: ietf-ssh-common 2335 namespace: urn:ietf:params:xml:ns:yang:ietf-ssh-common 2336 prefix: sshcmn 2337 reference: RFC EEEE 2339 name: ietf-ssh-client 2340 namespace: urn:ietf:params:xml:ns:yang:ietf-ssh-client 2341 prefix: sshc 2342 reference: RFC EEEE 2344 name: ietf-ssh-server 2345 namespace: urn:ietf:params:xml:ns:yang:ietf-ssh-server 2346 prefix: sshs 2347 reference: RFC EEEE 2349 7. References 2351 7.1. Normative References 2353 [I-D.ietf-netconf-crypto-types] 2354 Watsen, K., "Common YANG Data Types for Cryptography", 2355 Work in Progress, Internet-Draft, draft-ietf-netconf- 2356 crypto-types-15, 20 May 2020, 2357 . 2360 [I-D.ietf-netconf-keystore] 2361 Watsen, K., "A YANG Data Model for a Keystore", Work in 2362 Progress, Internet-Draft, draft-ietf-netconf-keystore-17, 2363 20 May 2020, . 2366 [I-D.ietf-netconf-trust-anchors] 2367 Watsen, K., "A YANG Data Model for a Truststore", Work in 2368 Progress, Internet-Draft, draft-ietf-netconf-trust- 2369 anchors-10, 20 May 2020, . 2372 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2373 Requirement Levels", BCP 14, RFC 2119, 2374 DOI 10.17487/RFC2119, March 1997, 2375 . 2377 [RFC4344] Bellare, M., Kohno, T., and C. Namprempre, "The Secure 2378 Shell (SSH) Transport Layer Encryption Modes", RFC 4344, 2379 DOI 10.17487/RFC4344, January 2006, 2380 . 2382 [RFC4419] Friedl, M., Provos, N., and W. Simpson, "Diffie-Hellman 2383 Group Exchange for the Secure Shell (SSH) Transport Layer 2384 Protocol", RFC 4419, DOI 10.17487/RFC4419, March 2006, 2385 . 2387 [RFC5656] Stebila, D. and J. Green, "Elliptic Curve Algorithm 2388 Integration in the Secure Shell Transport Layer", 2389 RFC 5656, DOI 10.17487/RFC5656, December 2009, 2390 . 2392 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 2393 the Network Configuration Protocol (NETCONF)", RFC 6020, 2394 DOI 10.17487/RFC6020, October 2010, 2395 . 2397 [RFC6187] Igoe, K. and D. Stebila, "X.509v3 Certificates for Secure 2398 Shell Authentication", RFC 6187, DOI 10.17487/RFC6187, 2399 March 2011, . 2401 [RFC6668] Bider, D. and M. Baushke, "SHA-2 Data Integrity 2402 Verification for the Secure Shell (SSH) Transport Layer 2403 Protocol", RFC 6668, DOI 10.17487/RFC6668, July 2012, 2404 . 2406 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2407 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2408 . 2410 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2411 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2412 May 2017, . 2414 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 2415 Access Control Model", STD 91, RFC 8341, 2416 DOI 10.17487/RFC8341, March 2018, 2417 . 2419 7.2. Informative References 2421 [I-D.ietf-netconf-http-client-server] 2422 Watsen, K., "YANG Groupings for HTTP Clients and HTTP 2423 Servers", Work in Progress, Internet-Draft, draft-ietf- 2424 netconf-http-client-server-03, 20 May 2020, 2425 . 2428 [I-D.ietf-netconf-netconf-client-server] 2429 Watsen, K., "NETCONF Client and Server Models", Work in 2430 Progress, Internet-Draft, draft-ietf-netconf-netconf- 2431 client-server-19, 20 May 2020, 2432 . 2435 [I-D.ietf-netconf-restconf-client-server] 2436 Watsen, K., "RESTCONF Client and Server Models", Work in 2437 Progress, Internet-Draft, draft-ietf-netconf-restconf- 2438 client-server-19, 20 May 2020, 2439 . 2442 [I-D.ietf-netconf-ssh-client-server] 2443 Watsen, K. and G. Wu, "YANG Groupings for SSH Clients and 2444 SSH Servers", Work in Progress, Internet-Draft, draft- 2445 ietf-netconf-ssh-client-server-19, 20 May 2020, 2446 . 2449 [I-D.ietf-netconf-tcp-client-server] 2450 Watsen, K. and M. Scharf, "YANG Groupings for TCP Clients 2451 and TCP Servers", Work in Progress, Internet-Draft, draft- 2452 ietf-netconf-tcp-client-server-06, 16 June 2020, 2453 . 2456 [I-D.ietf-netconf-tls-client-server] 2457 Watsen, K. and G. Wu, "YANG Groupings for TLS Clients and 2458 TLS Servers", Work in Progress, Internet-Draft, draft- 2459 ietf-netconf-tls-client-server-19, 20 May 2020, 2460 . 2463 [OPENSSH] Project, T. O., "OpenSSH", 2016, . 2465 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2466 DOI 10.17487/RFC3688, January 2004, 2467 . 2469 [RFC4252] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) 2470 Authentication Protocol", RFC 4252, DOI 10.17487/RFC4252, 2471 January 2006, . 2473 [RFC4253] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) 2474 Transport Layer Protocol", RFC 4253, DOI 10.17487/RFC4253, 2475 January 2006, . 2477 [RFC4254] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) 2478 Connection Protocol", RFC 4254, DOI 10.17487/RFC4254, 2479 January 2006, . 2481 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2482 and A. Bierman, Ed., "Network Configuration Protocol 2483 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2484 . 2486 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 2487 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 2488 . 2490 [RFC7317] Bierman, A. and M. Bjorklund, "A YANG Data Model for 2491 System Management", RFC 7317, DOI 10.17487/RFC7317, August 2492 2014, . 2494 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2495 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2496 . 2498 [RFC8071] Watsen, K., "NETCONF Call Home and RESTCONF Call Home", 2499 RFC 8071, DOI 10.17487/RFC8071, February 2017, 2500 . 2502 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 2503 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 2504 . 2506 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 2507 and R. Wilton, "Network Management Datastore Architecture 2508 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 2509 . 2511 Appendix A. Change Log 2513 This section is to be removed before publishing as an RFC. 2515 A.1. 00 to 01 2517 * Noted that '0.0.0.0' and '::' might have special meanings. 2519 * Renamed "keychain" to "keystore". 2521 A.2. 01 to 02 2523 * Removed the groupings 'listening-ssh-client-grouping' and 2524 'listening-ssh-server-grouping'. Now modules only contain the 2525 transport-independent groupings. 2527 * Simplified the "client-auth" part in the ietf-ssh-client module. 2528 It now inlines what it used to point to keystore for. 2530 * Added cipher suites for various algorithms into new 'ietf-ssh- 2531 common' module. 2533 A.3. 02 to 03 2535 * Removed 'RESTRICTED' enum from 'password' leaf type. 2537 * Added a 'must' statement to container 'server-auth' asserting that 2538 at least one of the various auth mechanisms must be specified. 2540 * Fixed description statement for leaf 'trusted-ca-certs'. 2542 A.4. 03 to 04 2544 * Change title to "YANG Groupings for SSH Clients and SSH Servers" 2546 * Added reference to RFC 6668 2548 * Added RFC 8174 to Requirements Language Section. 2550 * Enhanced description statement for ietf-ssh-server's "trusted-ca- 2551 certs" leaf. 2553 * Added mandatory true to ietf-ssh-client's "client-auth" 'choice' 2554 statement. 2556 * Changed the YANG prefix for module ietf-ssh-common from 'sshcom' 2557 to 'sshcmn'. 2559 * Removed the compression algorithms as they are not commonly 2560 configurable in vendors' implementations. 2562 * Updating descriptions in transport-params-grouping and the 2563 servers's usage of it. 2565 * Now tree diagrams reference ietf-netmod-yang-tree-diagrams 2567 * Updated YANG to use typedefs around leafrefs to common keystore 2568 paths 2570 * Now inlines key and certificates (no longer a leafref to keystore) 2572 A.5. 04 to 05 2574 * Merged changes from co-author. 2576 A.6. 05 to 06 2578 * Updated to use trust anchors from trust-anchors draft (was 2579 keystore draft) 2581 * Now uses new keystore grouping enabling asymmetric key to be 2582 either locally defined or a reference to the keystore. 2584 A.7. 06 to 07 2586 * factored the ssh-[client|server]-groupings into more reusable 2587 groupings. 2589 * added if-feature statements for the new "ssh-host-keys" and 2590 "x509-certificates" features defined in draft-ietf-netconf-trust- 2591 anchors. 2593 A.8. 07 to 08 2595 * Added a number of compatibility matrices to Section 5 (thanks 2596 Frank!) 2598 * Clarified that any configured "host-key-alg" values need to be 2599 compatible with the configured private key. 2601 A.9. 08 to 09 2603 * Updated examples to reflect update to groupings defined in the 2604 keystore -09 draft. 2606 * Add SSH keepalives features and groupings. 2608 * Prefixed top-level SSH grouping nodes with 'ssh-' and support 2609 mashups. 2611 * Updated copyright date, boilerplate template, affiliation, and 2612 folding algorithm. 2614 A.10. 09 to 10 2616 * Reformatted the YANG modules. 2618 A.11. 10 to 11 2620 * Reformatted lines causing folding to occur. 2622 A.12. 11 to 12 2624 * Collapsed all the inner groupings into the top-level grouping. 2626 * Added a top-level "demux container" inside the top-level grouping. 2628 * Added NACM statements and updated the Security Considerations 2629 section. 2631 * Added "presence" statements on the "keepalive" containers, as was 2632 needed to address a validation error that appeared after adding 2633 the "must" statements into the NETCONF/RESTCONF client/server 2634 modules. 2636 * Updated the boilerplate text in module-level "description" 2637 statement to match copyeditor convention. 2639 A.13. 12 to 13 2641 * Removed the "demux containers", floating the nacm:default-deny- 2642 write to each descendent node, and adding a note to model 2643 designers regarding the potential need to add their own demux 2644 containers. 2646 * Fixed a couple references (section 2 --> section 3) 2648 * In the server model, replaced with and introduced 'local-or-external' choice. 2651 A.14. 13 to 14 2653 * Updated to reflect changes in trust-anchors drafts (e.g., s/trust- 2654 anchors/truststore/g + s/pinned.//) 2656 A.15. 14 to 15 2658 * Updated examples to reflect ietf-crypto-types change (e.g., 2659 identities --> enumerations) 2661 * Updated "server-authentication" and "client-authentication" nodes 2662 from being a leaf of type "ts:host-keys-ref" or "ts:certificates- 2663 ref" to a container that uses "ts:local-or-truststore-host-keys- 2664 grouping" or "ts:local-or-truststore-certs-grouping". 2666 A.16. 15 to 16 2668 * Removed unnecessary if-feature statements in the -client and 2669 -server modules. 2671 * Cleaned up some description statements in the -client and -server 2672 modules. 2674 * Fixed a canonical ordering issue in ietf-ssh-common detected by 2675 new pyang. 2677 A.17. 16 to 17 2679 * Removed choice local-or-external by removing the 'external' case 2680 and flattening the 'local' case and adding a "client-auth-config- 2681 supported" feature. 2683 * Updated examples to include the "*-key-format" nodes. 2685 * Augmented-in "must" expressions ensuring that locally-defined 2686 public-key-format are "ct:ssh-public-key-format" (must expr for 2687 ref'ed keys are TBD). 2689 A.18. 17 to 18 2691 * Removed leaf-list 'other' from ietf-ssh-server. 2693 * Removed unused 'external-client-auth-supported' feature. 2695 * Added features client-auth-password, client-auth-hostbased, and 2696 client-auth-none. 2698 * Renamed 'host-key' to 'public-key' for when refering to 2699 'publickey' based auth. 2701 * Added new feature-protected 'hostbased' and 'none' to the 'user' 2702 node's config. 2704 * Added new feature-protected 'hostbased' and 'none' to the 'client- 2705 identity' node's config. 2707 * Updated examples to reflect new "bag" addition to truststore. 2709 * Refined truststore/keystore groupings to ensure the key formats 2710 "must" be particular values. 2712 * Switched to using truststore's new "public-key" bag (instead of 2713 separate "ssh-public-key" and "raw-public-key" bags. 2715 * Updated client/server examples to cover ALL cases (local/ref x 2716 cert/raw-key/psk). 2718 A.19. 18 to 19 2720 * Updated the "keepalives" containers to address Michal Vasko's 2721 request to align with RFC 8071. 2723 * Removed algorithm-mapping tables from the "SSH Common Model" 2724 section 2726 * Removed 'algorithm' node from examples. 2728 * Added feature "client-identity-publickey" 2730 * Removed "choice auth-type", as auth-types aren't exclusive. 2732 * Renamed both "client-certs" and "server-certs" to "ee-certs" 2733 * Switch "must" to assert the public-key-format is "subject-public- 2734 key-info-format" when certificates are used. 2736 * Added a "Note to Reviewers" note to first page. 2738 A.20. 19 to 20 2740 * Added a "must 'public-key or password or hostbased or none or 2741 certificate'" statement to the "user" node in ietf-ssh-client 2743 * Expanded "Data Model Overview section(s) [remove "wall" of tree 2744 diagrams]. 2746 * Moved the "ietf-ssh-common" module section to proceed the other 2747 two module sections. 2749 * Updated the Security Considerations section. 2751 Acknowledgements 2753 The authors would like to thank for following for lively discussions 2754 on list and in the halls (ordered by last name): Andy Bierman, Martin 2755 Bjorklund, Benoit Claise, Mehmet Ersue, Balazs Kovacs, Radek Krejci, 2756 David Lamparter, Ladislav Lhotka, Alan Luchuk, Tom Petch, Juergen 2757 Schoenwaelder, Phil Shafer, Sean Turner, Michal Vasko, Bert Wijnen, 2758 and Liang Xia. 2760 Authors' Addresses 2762 Kent Watsen 2763 Watsen Networks 2765 Email: kent+ietf@watsen.net 2767 Gary Wu 2768 Cisco Systems 2770 Email: garywu@cisco.com