idnits 2.17.1 draft-ietf-netconf-ssh-client-server-14.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 595 has weird spacing: '...gorithm str...' == Line 1036 has weird spacing: '... string cer...' -- The document date (June 7, 2019) is 1785 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-06 == Outdated reference: A later version (-35) exists of draft-ietf-netconf-keystore-09 == Outdated reference: A later version (-28) exists of draft-ietf-netconf-trust-anchors-04 Summary: 0 errors (**), 0 flaws (~~), 6 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: December 9, 2019 Cisco Systems 6 L. Xia 7 Huawei 8 June 7, 2019 10 YANG Groupings for SSH Clients and SSH Servers 11 draft-ietf-netconf-ssh-client-server-14 13 Abstract 15 This document defines three YANG modules: the first defines groupings 16 for a generic SSH client, the second defines groupings for a generic 17 SSH server, and the third defines common identities and groupings 18 used by both the client and the server. It is intended that these 19 groupings will be used by applications using the SSH protocol. 21 Editorial Note (To be removed by RFC Editor) 23 This draft contains many placeholder values that need to be replaced 24 with finalized values at the time of publication. This note 25 summarizes all of the substitutions that are needed. No other RFC 26 Editor instructions are specified elsewhere in this document. 28 This document contains references to other drafts in progress, both 29 in the Normative References section, as well as in body text 30 throughout. Please update the following references to reflect their 31 final RFC assignments: 33 o I-D.ietf-netconf-trust-anchors 35 o I-D.ietf-netconf-keystore 37 Artwork in this document contains shorthand references to drafts in 38 progress. Please apply the following replacements: 40 o "XXXX" --> the assigned RFC value for this draft 42 o "YYYY" --> the assigned RFC value for I-D.ietf-netconf-trust- 43 anchors 45 o "ZZZZ" --> the assigned RFC value for I-D.ietf-netconf-keystore 47 Artwork in this document contains placeholder values for the date of 48 publication of this draft. Please apply the following replacement: 50 o "2019-06-07" --> the publication date of this draft 52 The following Appendix section is to be removed prior to publication: 54 o Appendix A. Change Log 56 Status of This Memo 58 This Internet-Draft is submitted in full conformance with the 59 provisions of BCP 78 and BCP 79. 61 Internet-Drafts are working documents of the Internet Engineering 62 Task Force (IETF). Note that other groups may also distribute 63 working documents as Internet-Drafts. The list of current Internet- 64 Drafts is at https://datatracker.ietf.org/drafts/current/. 66 Internet-Drafts are draft documents valid for a maximum of six months 67 and may be updated, replaced, or obsoleted by other documents at any 68 time. It is inappropriate to use Internet-Drafts as reference 69 material or to cite them other than as "work in progress." 71 This Internet-Draft will expire on December 9, 2019. 73 Copyright Notice 75 Copyright (c) 2019 IETF Trust and the persons identified as the 76 document authors. All rights reserved. 78 This document is subject to BCP 78 and the IETF Trust's Legal 79 Provisions Relating to IETF Documents 80 (https://trustee.ietf.org/license-info) in effect on the date of 81 publication of this document. Please review these documents 82 carefully, as they describe your rights and restrictions with respect 83 to this document. Code Components extracted from this document must 84 include Simplified BSD License text as described in Section 4.e of 85 the Trust Legal Provisions and are provided without warranty as 86 described in the Simplified BSD License. 88 Table of Contents 90 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 91 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 92 3. The SSH Client Model . . . . . . . . . . . . . . . . . . . . 4 93 3.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 4 94 3.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 5 95 3.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 9 96 4. The SSH Server Model . . . . . . . . . . . . . . . . . . . . 14 97 4.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 14 98 4.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 15 99 4.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 17 100 5. The SSH Common Model . . . . . . . . . . . . . . . . . . . . 26 101 5.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 28 102 5.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 29 103 5.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 29 104 6. Security Considerations . . . . . . . . . . . . . . . . . . . 39 105 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 40 106 7.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 40 107 7.2. The YANG Module Names Registry . . . . . . . . . . . . . 41 108 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 41 109 8.1. Normative References . . . . . . . . . . . . . . . . . . 41 110 8.2. Informative References . . . . . . . . . . . . . . . . . 43 111 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 45 112 A.1. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 45 113 A.2. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 45 114 A.3. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 45 115 A.4. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 45 116 A.5. 04 to 05 . . . . . . . . . . . . . . . . . . . . . . . . 46 117 A.6. 05 to 06 . . . . . . . . . . . . . . . . . . . . . . . . 46 118 A.7. 06 to 07 . . . . . . . . . . . . . . . . . . . . . . . . 46 119 A.8. 07 to 08 . . . . . . . . . . . . . . . . . . . . . . . . 46 120 A.9. 08 to 09 . . . . . . . . . . . . . . . . . . . . . . . . 46 121 A.10. 09 to 10 . . . . . . . . . . . . . . . . . . . . . . . . 47 122 A.11. 10 to 11 . . . . . . . . . . . . . . . . . . . . . . . . 47 123 A.12. 11 to 12 . . . . . . . . . . . . . . . . . . . . . . . . 47 124 A.13. 12 to 13 . . . . . . . . . . . . . . . . . . . . . . . . 47 125 A.14. 13 to 14 . . . . . . . . . . . . . . . . . . . . . . . . 47 126 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 48 127 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 48 129 1. Introduction 131 This document defines three YANG 1.1 [RFC7950] modules: the first 132 defines a grouping for a generic SSH client, the second defines a 133 grouping for a generic SSH server, and the third defines identities 134 and groupings common to both the client and the server. It is 135 intended that these groupings will be used by applications using the 136 SSH protocol [RFC4252], [RFC4253], and [RFC4254]. For instance, 137 these groupings could be used to help define the data model for an 138 OpenSSH [OPENSSH] server or a NETCONF over SSH [RFC6242] based 139 server. 141 The client and server YANG modules in this document each define one 142 grouping, which is focused on just SSH-specific configuration, and 143 specifically avoids any transport-level configuration, such as what 144 ports to listen on or connect to. This affords applications the 145 opportunity to define their own strategy for how the underlying TCP 146 connection is established. For instance, applications supporting 147 NETCONF Call Home [RFC8071] could use the "ssh-server-grouping" 148 grouping for the SSH parts it provides, while adding data nodes for 149 the TCP-level call-home configuration. 151 The modules defined in this document use groupings defined in 152 [I-D.ietf-netconf-keystore] enabling keys to be either locally 153 defined or a reference to globally configured values. 155 The modules defined in this document optionally support [RFC6187] 156 enabling X.509v3 certificate based host keys and public keys. 158 2. Terminology 160 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 161 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 162 "OPTIONAL" in this document are to be interpreted as described in BCP 163 14 [RFC2119] [RFC8174] when, and only when, they appear in all 164 capitals, as shown here. 166 3. The SSH Client Model 168 3.1. Tree Diagram 170 This section provides a tree diagram [RFC8340] for the "ietf-ssh- 171 client" module that does not have groupings expanded. 173 =========== NOTE: '\' line wrapping per BCP XX (RFC XXXX) =========== 175 module: ietf-ssh-client 177 grouping ssh-client-grouping 178 +-- client-identity 179 | +-- username? string 180 | +-- (auth-type) 181 | +--:(password) 182 | | +-- password? string 183 | +--:(public-key) 184 | | +-- public-key 185 | | +---u ks:local-or-keystore-asymmetric-key-grouping 186 | +--:(certificate) 187 | +-- certificate {sshcmn:ssh-x509-certs}? 188 | +---u ks:local-or-keystore-end-entity-cert-with-key-\ 189 grouping 190 +-- server-authentication 191 | +-- ssh-host-keys? ts:host-keys-ref {ts:ssh-host-keys}? 192 | +-- ca-certs? ts:certificates-ref 193 | | {sshcmn:ssh-x509-certs,ts:x509-certificates}? 194 | +-- server-certs? ts:certificates-ref 195 | {sshcmn:ssh-x509-certs,ts:x509-certificates}? 196 +-- transport-params {ssh-client-transport-params-config}? 197 | +---u sshcmn:transport-params-grouping 198 +-- keepalives! {ssh-client-keepalives}? 199 +-- max-wait? uint16 200 +-- max-attempts? uint8 202 3.2. Example Usage 204 This section presents two examples showing the ssh-client-grouping 205 populated with some data. These examples are effectively the same 206 except the first configures the client identity using a local key 207 while the second uses a key configured in a keystore. Both examples 208 are consistent with the examples presented in Section 2 of 209 [I-D.ietf-netconf-trust-anchors] and Section 3.2 of 210 [I-D.ietf-netconf-keystore]. 212 The following example configures the client identity using a local 213 key: 215 =========== NOTE: '\' line wrapping per BCP XX (RFC XXXX) =========== 217 220 221 222 foobar 223 224 225 ct:rsa2048 227 base64encodedvalue== 228 base64encodedvalue== 229 230 231 233 234 235 explicitly-trusted-ssh-host-keys 236 238 239 240 algs:ssh-rsa 241 242 243 244 algs:diffie-hellman-group-exchange-sha256 245 246 247 248 algs:aes256-ctr 249 algs:aes192-ctr 250 algs:aes128-ctr 251 algs:aes256-cbc 252 algs:aes192-cbc 253 algs:aes128-cbc 254 255 256 algs:hmac-sha2-256 257 algs:hmac-sha2-512 258 259 261 262 30 263 3 264 266 267 The following example configures the client identity using a key from 268 the keystore: 270 274 275 276 foobar 277 278 ex-rsa-key 279 280 282 283 284 explicitly-trusted-ssh-host-keys 285 287 288 289 algs:ssh-rsa 290 291 292 293 algs:diffie-hellman-group-exchange-sha256 294 295 296 297 algs:aes256-ctr 298 algs:aes192-ctr 299 algs:aes128-ctr 300 algs:aes256-cbc 301 algs:aes192-cbc 302 algs:aes128-cbc 303 304 305 algs:hmac-sha2-256 306 algs:hmac-sha2-512 307 308 310 311 30 312 3 313 315 317 3.3. YANG Module 319 This YANG module has normative references to 320 [I-D.ietf-netconf-trust-anchors], and [I-D.ietf-netconf-keystore]. 322 file "ietf-ssh-client@2019-06-07.yang" 323 module ietf-ssh-client { 324 yang-version 1.1; 325 namespace "urn:ietf:params:xml:ns:yang:ietf-ssh-client"; 326 prefix sshc; 328 import ietf-ssh-common { 329 prefix sshcmn; 330 revision-date 2019-06-07; // stable grouping definitions 331 reference 332 "RFC XXXX: YANG Groupings for SSH Clients and SSH Servers"; 333 } 335 import ietf-truststore { 336 prefix ts; 337 reference 338 "RFC YYYY: A YANG Data Model for a Truststore"; 339 } 341 import ietf-keystore { 342 prefix ks; 343 reference 344 "RFC ZZZZ: A YANG Data Model for a Keystore"; 345 } 347 import ietf-netconf-acm { 348 prefix nacm; 349 reference 350 "RFC 8341: Network Configuration Access Control Model"; 351 } 353 organization 354 "IETF NETCONF (Network Configuration) Working Group"; 356 contact 357 "WG Web: 358 WG List: 359 Author: Kent Watsen 360 Author: Gary Wu "; 362 description 363 "This module defines reusable groupings for SSH clients that 364 can be used as a basis for specific SSH client instances. 366 Copyright (c) 2019 IETF Trust and the persons identified 367 as authors of the code. All rights reserved. 369 Redistribution and use in source and binary forms, with 370 or without modification, is permitted pursuant to, and 371 subject to the license terms contained in, the Simplified 372 BSD License set forth in Section 4.c of the IETF Trust's 373 Legal Provisions Relating to IETF Documents 374 (https://trustee.ietf.org/license-info). 376 This version of this YANG module is part of RFC XXXX 377 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC 378 itself for full legal notices.; 380 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 381 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 382 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 383 are to be interpreted as described in BCP 14 (RFC 2119) 384 (RFC 8174) when, and only when, they appear in all 385 capitals, as shown here."; 387 revision 2019-06-07 { 388 description 389 "Initial version"; 390 reference 391 "RFC XXXX: YANG Groupings for SSH Clients and SSH Servers"; 392 } 394 // Features 396 feature ssh-client-transport-params-config { 397 description 398 "SSH transport layer parameters are configurable on an SSH 399 client."; 400 } 402 feature ssh-client-keepalives { 403 description 404 "Per socket SSH keepalive parameters are configurable for 405 SSH clients on the server implementing this feature."; 406 } 408 // Groupings 410 grouping ssh-client-grouping { 411 description 412 "A reusable grouping for configuring a SSH client without 413 any consideration for how an underlying TCP session is 414 established. 416 Note that this grouping uses fairly typical descendent 417 node names such that a stack of 'uses' statements will 418 have name conflicts. It is intended that the consuming 419 data model will resolve the issue (e.g., by wrapping 420 the 'uses' statement in a container called 421 'ssh-client-parameters'). This model purposely does 422 not do this itself so as to provide maximum flexibility 423 to consuming models."; 425 container client-identity { 426 nacm:default-deny-write; 427 description 428 "The credentials used by the client to authenticate to 429 the SSH server."; 430 leaf username { 431 type string; 432 description 433 "The username of this user. This will be the username 434 used, for instance, to log into an SSH server."; 435 } 436 choice auth-type { 437 mandatory true; 438 description 439 "The authentication type."; 440 leaf password { 441 nacm:default-deny-all; 442 type string; 443 description 444 "A password to be used for client authentication."; 445 } 446 container public-key { 447 uses ks:local-or-keystore-asymmetric-key-grouping; 448 description 449 "A locally-defined or referenced asymmetric key 450 pair to be used for client authentication."; 451 reference 452 "RFC ZZZZ: YANG Data Model for a Centralized 453 Keystore Mechanism"; 454 } 455 container certificate { 456 if-feature "sshcmn:ssh-x509-certs"; 457 uses 458 ks:local-or-keystore-end-entity-cert-with-key-grouping; 459 description 460 "A locally-defined or referenced certificate 461 to be used for client authentication."; 463 reference 464 "RFC ZZZZ: YANG Data Model for a Centralized 465 Keystore Mechanism"; 466 } 467 } 468 } // container client-identity 470 container server-authentication { 471 nacm:default-deny-write; 472 must 'ssh-host-keys or ca-certs or server-certs'; 473 description 474 "Trusted server identities."; 475 leaf ssh-host-keys { 476 if-feature "ts:ssh-host-keys"; 477 type ts:host-keys-ref; 478 description 479 "A reference to a list of SSH host keys used by the 480 SSH client to authenticate SSH server host keys. 481 A server host key is authenticated if it is an 482 exact match to a configured SSH host key."; 483 reference 484 "RFC YYYY: YANG Data Model for Global Trust Anchors"; 485 } 486 leaf ca-certs { 487 if-feature "sshcmn:ssh-x509-certs"; 488 if-feature "ts:x509-certificates"; 489 type ts:certificates-ref; 490 description 491 "A reference to a list of certificate authority (CA) 492 certificates used by the SSH client to authenticate 493 SSH server certificates. A server certificate is 494 authenticated if it has a valid chain of trust to 495 a configured CA certificate."; 496 reference 497 "RFC YYYY: YANG Data Model for Global Trust Anchors"; 498 } 499 leaf server-certs { 500 if-feature "sshcmn:ssh-x509-certs"; 501 if-feature "ts:x509-certificates"; 502 type ts:certificates-ref; 503 description 504 "A reference to a list of server certificates used by 505 the SSH client to authenticate SSH server certificates. 506 A server certificate is authenticated if it is an 507 exact match to a configured server certificate."; 508 reference 509 "RFC YYYY: YANG Data Model for Global Trust Anchors"; 510 } 512 } // container server-authentication 514 container transport-params { 515 nacm:default-deny-write; 516 if-feature "ssh-client-transport-params-config"; 517 description 518 "Configurable parameters of the SSH transport layer."; 519 uses sshcmn:transport-params-grouping; 520 } // container transport-parameters 522 container keepalives { 523 nacm:default-deny-write; 524 if-feature "ssh-client-keepalives"; 525 presence "Indicates that keepalives are enabled."; 526 description 527 "Configures the keep-alive policy, to proactively test 528 the aliveness of the SSH server. An unresponsive TLS 529 server is dropped after approximately max-wait * 530 max-attempts seconds."; 531 leaf max-wait { 532 type uint16 { 533 range "1..max"; 534 } 535 units "seconds"; 536 default "30"; 537 description 538 "Sets the amount of time in seconds after which if 539 no data has been received from the SSH server, a 540 TLS-level message will be sent to test the 541 aliveness of the SSH server."; 542 } 543 leaf max-attempts { 544 type uint8; 545 default "3"; 546 description 547 "Sets the maximum number of sequential keep-alive 548 messages that can fail to obtain a response from 549 the SSH server before assuming the SSH server is 550 no longer alive."; 551 } 552 } // container keepalives 553 } // grouping ssh-client-grouping 554 } 555 557 4. The SSH Server Model 559 4.1. Tree Diagram 561 This section provides a tree diagram [RFC8340] for the "ietf-ssh- 562 server" module that does not have groupings expanded. 564 =========== NOTE: '\' line wrapping per BCP XX (RFC XXXX) =========== 566 module: ietf-ssh-server 568 grouping ssh-server-grouping 569 +-- server-identity 570 | +-- host-key* [name] 571 | +-- name? string 572 | +-- (host-key-type) 573 | +--:(public-key) 574 | | +-- public-key 575 | | +---u ks:local-or-keystore-asymmetric-key-grouping 576 | +--:(certificate) 577 | +-- certificate {sshcmn:ssh-x509-certs}? 578 | +---u ks:local-or-keystore-end-entity-cert-with-k\ 579 ey-grouping 580 +-- client-authentication 581 | +-- supported-authentication-methods 582 | | +-- publickey? empty 583 | | +-- passsword? empty 584 | | +-- hostbased? empty 585 | | +-- none? empty 586 | | +-- other* string 587 | +-- (local-or-external) 588 | +--:(local) {local-client-auth-supported}? 589 | | +-- users 590 | | +-- user* [name] 591 | | +-- name? string 592 | | +-- password? ianach:crypt-hash 593 | | +-- authorized-key* [name] 594 | | +-- name? string 595 | | +-- algorithm string 596 | | +-- key-data binary 597 | +--:(external) {external-client-auth-supported}? 598 | +-- client-auth-defined-elsewhere? empty 599 +-- transport-params {ssh-server-transport-params-config}? 600 | +---u sshcmn:transport-params-grouping 601 +-- keepalives! {ssh-server-keepalives}? 602 +-- max-wait? uint16 603 +-- max-attempts? uint8 605 4.2. Example Usage 607 This section presents two examples showing the ssh-server-grouping 608 populated with some data. These examples are effectively the same 609 except the first configures the server identity using a local key 610 while the second uses a key configured in a keystore. Both examples 611 are consistent with the examples presented in Section 2 of 612 [I-D.ietf-netconf-trust-anchors] and Section 3.2 of 613 [I-D.ietf-netconf-keystore]. 615 The following example configures the server identity using a local 616 key: 618 =========== NOTE: '\' line wrapping per BCP XX (RFC XXXX) =========== 620 624 625 626 627 deployment-specific-certificate 628 629 630 ct:rsa2048 632 base64encodedvalue== 633 base64encodedvalue== 634 635 636 637 639 640 641 642 643 644 645 646 647 mary 648 649 650 651 655 657 658 659 algs:ssh-rsa 660 661 662 663 algs:diffie-hellman-group-exchange-sha256 664 665 666 667 algs:aes256-ctr 668 algs:aes192-ctr 669 algs:aes128-ctr 670 algs:aes256-cbc 671 algs:aes192-cbc 672 algs:aes128-cbc 673 674 675 algs:hmac-sha2-256 676 algs:hmac-sha2-512 677 678 680 682 The following example configures the server identity using a key from 683 the keystore: 685 689 690 691 692 deployment-specific-certificate 693 694 ex-rsa-key 695 696 697 699 700 701 702 703 704 705 706 707 mary 708 709 710 711 715 717 718 719 algs:ssh-rsa 720 721 722 723 algs:diffie-hellman-group-exchange-sha256 724 725 726 727 algs:aes256-ctr 728 algs:aes192-ctr 729 algs:aes128-ctr 730 algs:aes256-cbc 731 algs:aes192-cbc 732 algs:aes128-cbc 733 734 735 algs:hmac-sha2-256 736 algs:hmac-sha2-512 737 738 740 742 4.3. YANG Module 744 This YANG module has normative references to 745 [I-D.ietf-netconf-trust-anchors] and [I-D.ietf-netconf-keystore] and 746 informative references to [RFC4253] and [RFC7317]. 748 file "ietf-ssh-server@2019-06-07.yang" 749 module ietf-ssh-server { 750 yang-version 1.1; 751 namespace "urn:ietf:params:xml:ns:yang:ietf-ssh-server"; 752 prefix sshs; 754 import ietf-ssh-common { 755 prefix sshcmn; 756 revision-date 2019-06-07; // stable grouping definitions 757 reference 758 "RFC XXXX: YANG Groupings for SSH Clients and SSH Servers"; 759 } 760 /* 761 import ietf-truststore { 762 prefix ta; 763 reference 764 "RFC YYYY: A YANG Data Model for a Truststore"; 765 } 766 */ 767 import ietf-keystore { 768 prefix ks; 769 reference 770 "RFC ZZZZ: A YANG Data Model for a Keystore"; 771 } 773 import iana-crypt-hash { 774 prefix ianach; 775 reference 776 "RFC 7317: A YANG Data Model for System Management"; 777 } 779 import ietf-netconf-acm { 780 prefix nacm; 781 reference 782 "RFC 8341: Network Configuration Access Control Model"; 783 } 785 organization 786 "IETF NETCONF (Network Configuration) Working Group"; 788 contact 789 "WG Web: 790 WG List: 791 Author: Kent Watsen 792 Author: Gary Wu "; 794 description 795 "This module defines reusable groupings for SSH servers that 796 can be used as a basis for specific SSH server instances. 798 Copyright (c) 2019 IETF Trust and the persons identified 799 as authors of the code. All rights reserved. 801 Redistribution and use in source and binary forms, with 802 or without modification, is permitted pursuant to, and 803 subject to the license terms contained in, the Simplified 804 BSD License set forth in Section 4.c of the IETF Trust's 805 Legal Provisions Relating to IETF Documents 806 (https://trustee.ietf.org/license-info). 808 This version of this YANG module is part of RFC XXXX 809 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC 810 itself for full legal notices.; 812 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 813 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 814 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 815 are to be interpreted as described in BCP 14 (RFC 2119) 816 (RFC 8174) when, and only when, they appear in all 817 capitals, as shown here."; 819 revision 2019-06-07 { 820 description 821 "Initial version"; 822 reference 823 "RFC XXXX: YANG Groupings for SSH Clients and SSH Servers"; 824 } 826 // Features 828 feature ssh-server-transport-params-config { 829 description 830 "SSH transport layer parameters are configurable on an SSH 831 server."; 832 } 834 feature ssh-server-keepalives { 835 description 836 "Per socket SSH keepalive parameters are configurable for 837 SSH servers on the server implementing this feature."; 838 } 840 feature local-client-auth-supported { 841 description 842 "Indicates that the SSH server supports local configuration 843 of client credentials."; 844 } 845 feature external-client-auth-supported { 846 description 847 "Indicates that the SSH server supports external configuration 848 of client credentials."; 849 } 851 // Groupings 853 grouping ssh-server-grouping { 854 description 855 "A reusable grouping for configuring a SSH server without 856 any consideration for how underlying TCP sessions are 857 established. 859 Note that this grouping uses fairly typical descendent 860 node names such that a stack of 'uses' statements will 861 have name conflicts. It is intended that the consuming 862 data model will resolve the issue (e.g., by wrapping 863 the 'uses' statement in a container called 864 'ssh-server-parameters'). This model purposely does 865 not do this itself so as to provide maximum flexibility 866 to consuming models."; 868 container server-identity { 869 nacm:default-deny-write; 870 description 871 "The list of host-keys the SSH server will present when 872 establishing a SSH connection."; 873 list host-key { 874 key "name"; 875 min-elements 1; 876 ordered-by user; 877 description 878 "An ordered list of host keys the SSH server will use to 879 construct its ordered list of algorithms, when sending 880 its SSH_MSG_KEXINIT message, as defined in Section 7.1 881 of RFC 4253."; 882 reference 883 "RFC 4253: The Secure Shell (SSH) Transport Layer 884 Protocol"; 885 leaf name { 886 type string; 887 description 888 "An arbitrary name for this host-key"; 889 } 890 choice host-key-type { 891 mandatory true; 892 description 893 "The type of host key being specified"; 894 container public-key { 895 uses ks:local-or-keystore-asymmetric-key-grouping; 896 description 897 "A locally-defined or referenced asymmetric key pair 898 to be used for the SSH server's host key."; 899 reference 900 "RFC ZZZZ: YANG Data Model for a Centralized 901 Keystore Mechanism"; 902 } 903 container certificate { 904 if-feature "sshcmn:ssh-x509-certs"; 905 uses 906 ks:local-or-keystore-end-entity-cert-with-key-grouping; 907 description 908 "A locally-defined or referenced end-entity 909 certificate to be used for the SSH server's 910 host key."; 911 reference 912 "RFC ZZZZ: YANG Data Model for a Centralized 913 Keystore Mechanism"; 914 } 915 } 916 } 917 } // container server-identity 919 container client-authentication { 920 nacm:default-deny-write; 921 description 922 "Specifies if SSH client authentication is required or 923 optional, and specifies if the SSH client authentication 924 credentials are configured locally or externally."; 925 container supported-authentication-methods { 926 description 927 "Indicates which authentication methods the server 928 supports."; 929 leaf publickey { 930 type empty; 931 description 932 "Indicates that the 'publickey' method is supported. 933 Note that RFC 6187 X.509v3 Certificates for SSH uses 934 the 'publickey' method name."; 935 reference 936 "RFC 4252: The Secure Shell (SSH) Authentication 937 Protocol. 938 RFC 6187: X.509v3 Certificates for Secure Shell 939 Authentication."; 940 } 941 leaf passsword { 942 type empty; 943 description 944 "Indicates that the 'password' method is supported."; 945 reference 946 "RFC 4252: The Secure Shell (SSH) Authentication 947 Protocol."; 948 } 949 leaf hostbased { 950 type empty; 951 description 952 "Indicates that the 'hostbased' method is supported."; 953 reference 954 "RFC 4252: The Secure Shell (SSH) Authentication 955 Protocol."; 956 } 957 leaf none { 958 type empty; 959 description 960 "Indicates that the 'none' method is supported."; 961 reference 962 "RFC 4252: The Secure Shell (SSH) Authentication 963 Protocol."; 964 } 965 leaf-list other { 966 type string; 967 description 968 "Indicates a supported method name not defined by 969 RFC 4253."; 970 reference 971 "RFC 4252: The Secure Shell (SSH) Authentication 972 Protocol."; 973 } 974 } 975 choice local-or-external { 976 mandatory true; 977 description 978 "Indicates if the client credentials are configured 979 locally or externally."; 980 case local { 981 if-feature "local-client-auth-supported"; 982 description 983 "Client credentials are configured locally."; 984 container users { 985 description 986 "A list of locally configured users."; 987 list user { 988 key name; 989 description 990 "The list of local users configured on this device."; 992 leaf name { 993 type string; 994 description 995 "The user name string identifying this entry."; 996 } 997 leaf password { 998 type ianach:crypt-hash; 999 description 1000 "The password for this entry."; 1001 } 1002 list authorized-key { 1003 key name; 1004 description 1005 "A list of public SSH keys for this user. These 1006 keys are allowed for SSH authentication, as 1007 described in RFC 4253."; 1008 reference 1009 "RFC 4253: The Secure Shell (SSH) Transport Layer 1010 Protocol"; 1011 leaf name { 1012 type string; 1013 description 1014 "An arbitrary name for the SSH key."; 1015 } 1016 leaf algorithm { 1017 type string; 1018 mandatory true; 1019 description 1020 "The public key algorithm name for this SSH key. 1022 Valid values are the values in the IANA 'Secure 1023 Shell (SSH) Protocol Parameters' registry, 1024 Public Key Algorithm Names."; 1025 reference 1026 "IANA 'Secure Shell (SSH) Protocol Parameters' 1027 registry, Public Key Algorithm Names"; 1028 } 1029 leaf key-data { 1030 type binary; 1031 mandatory true; 1032 description 1033 "The binary public key data for this SSH key, as 1034 specified by RFC 4253, Section 6.6, i.e.: 1036 string certificate or public key format 1037 identifier 1038 byte[n] key/certificate data."; 1039 reference 1040 "RFC 4253: The Secure Shell (SSH) Transport Layer 1041 Protocol"; 1042 } 1043 } 1044 } // list user 1045 /* 1046 if-feature "sshcmn:ssh-x509-certs"; 1047 description 1048 "A reference to a list of certificate authority 1049 (CA) certificates and a reference to a list of 1050 client certificates."; 1051 leaf ca-certs { 1052 if-feature "ts:x509-certificates"; 1053 type ts:certificates-ref; // local or remote 1054 description 1055 "A reference to a list of certificate authority (CA) 1056 certificates used by the SSH server to authenticate 1057 SSH client certificates. A client certificate is 1058 authenticated if it has a valid chain of trust to 1059 a configured CA certificate."; 1060 reference 1061 "RFC YYYY: YANG Data Model for Global Trust Anchors"; 1062 } 1063 leaf client-certs { 1064 if-feature "ts:x509-certificates"; 1065 type ts:certificates-ref; // local or remote 1066 description 1067 "A reference to a list of client certificates 1068 used by the SSH server to authenticate SSH 1069 client certificates. A clients certificate 1070 is authenticated if it is an exact match to 1071 a configured client certificate."; 1072 reference 1073 "RFC YYYY: YANG Data Model for Global Trust Anchors"; 1074 } 1075 */ 1076 } // container users 1077 } // case local 1078 case external { 1079 if-feature "external-client-auth-supported"; 1080 description 1081 "Client credentials are configured externally, such 1082 as via RADIUS, RFC 7317, or another mechanism."; 1083 leaf client-auth-defined-elsewhere { 1084 type empty; 1085 description 1086 "Indicates that client credentials are configured 1087 elsewhere."; 1088 } 1089 } 1090 } // choice local-or-external 1091 } // container client-authentication 1093 container transport-params { 1094 nacm:default-deny-write; 1095 if-feature "ssh-server-transport-params-config"; 1096 description 1097 "Configurable parameters of the SSH transport layer."; 1098 uses sshcmn:transport-params-grouping; 1099 } // container transport-params 1101 container keepalives { 1102 nacm:default-deny-write; 1103 if-feature "ssh-server-keepalives"; 1104 presence "Indicates that keepalives are enabled."; 1105 description 1106 "Configures the keep-alive policy, to proactively test 1107 the aliveness of the SSL client. An unresponsive SSL 1108 client is dropped after approximately max-wait * 1109 max-attempts seconds."; 1110 leaf max-wait { 1111 type uint16 { 1112 range "1..max"; 1113 } 1114 units "seconds"; 1115 default "30"; 1116 description 1117 "Sets the amount of time in seconds after which 1118 if no data has been received from the SSL client, 1119 a SSL-level message will be sent to test the 1120 aliveness of the SSL client."; 1121 } 1122 leaf max-attempts { 1123 type uint8; 1124 default "3"; 1125 description 1126 "Sets the maximum number of sequential keep-alive 1127 messages that can fail to obtain a response from 1128 the SSL client before assuming the SSL client is 1129 no longer alive."; 1130 } 1131 } // container keepalives 1132 } // grouping server-identity-grouping 1134 } 1135 1137 5. The SSH Common Model 1139 The SSH common model presented in this section contains identities 1140 and groupings common to both SSH clients and SSH servers. The 1141 transport-params-grouping can be used to configure the list of SSH 1142 transport algorithms permitted by the SSH client or SSH server. The 1143 lists of algorithms are ordered such that, if multiple algorithms are 1144 permitted by the client, the algorithm that appears first in its list 1145 that is also permitted by the server is used for the SSH transport 1146 layer connection. The ability to restrict the algorithms allowed is 1147 provided in this grouping for SSH clients and SSH servers that are 1148 capable of doing so and may serve to make SSH clients and SSH servers 1149 compliant with security policies. 1151 [I-D.ietf-netconf-crypto-types] defines six categories of 1152 cryptographic algorithms (hash-algorithm, symmetric-key-encryption- 1153 algorithm, mac-algorithm, asymmetric-key-encryption-algorithm, 1154 signature-algorithm, key-negotiation-algorithm) and lists several 1155 widely accepted algorithms for each of them. The SSH client and 1156 server models use one or more of these algorithms. The SSH common 1157 model includes four parameters for configuring its permitted SSH 1158 algorithms, which are: host-key-alg, key-exchange-alg, encryption-alg 1159 and mac-alg. The following tables are provided, in part, to define 1160 the subset of algorithms defined in the crypto-types model used by 1161 SSH and, in part, to ensure compatibility of configured SSH 1162 cryptographic parameters for configuring its permitted SSH algorithms 1163 ("sshcmn" representing SSH common model, and "ct" representing 1164 crypto-types model which the SSH client/server model is based on): 1166 +-------------------------------+-------------------------------+ 1167 | sshcmn:host-key-alg | ct:signature-algorithm | 1168 +-------------------------------+-------------------------------+ 1169 | dsa-sha1 | dsa-sha1 | 1170 | rsa-pkcs1-sha1 | rsa-pkcs1-sha1 | 1171 | rsa-pkcs1-sha256 | rsa-pkcs1-sha256 | 1172 | rsa-pkcs1-sha512 | rsa-pkcs1-sha512 | 1173 | ecdsa-secp256r1-sha256 | ecdsa-secp256r1-sha256 | 1174 | ecdsa-secp384r1-sha384 | ecdsa-secp384r1-sha384 | 1175 | ecdsa-secp521r1-sha512 | ecdsa-secp521r1-sha512 | 1176 | x509v3-rsa-pkcs1-sha1 | x509v3-rsa-pkcs1-sha1 | 1177 | x509v3-rsa2048-pkcs1-sha256 | x509v3-rsa2048-pkcs1-sha1 | 1178 | x509v3-ecdsa-secp256r1-sha256 | x509v3-ecdsa-secp256r1-sha256 | 1179 | x509v3-ecdsa-secp384r1-sha384 | x509v3-ecdsa-secp384r1-sha384 | 1180 | x509v3-ecdsa-secp521r1-sha512 | x509v3-ecdsa-secp521r1-sha512 | 1181 +-------------------------------+-------------------------------+ 1183 Table 1 The SSH Host-key-alg Compatibility Matrix 1185 +-------------------------------+-------------------------------+ 1186 | sshcmn:key-exchange-alg | ct:key-negotiation-algorithm | 1187 +-------------------------------+-------------------------------+ 1188 | diffie-hellman-group14-sha1 | diffie-hellman-group14-sha1 | 1189 | diffie-hellman-group14-sha256 | diffie-hellman-group14-sha256 | 1190 | diffie-hellman-group15-sha512 | diffie-hellman-group15-sha512 | 1191 | diffie-hellman-group16-sha512 | diffie-hellman-group16-sha512 | 1192 | diffie-hellman-group17-sha512 | diffie-hellman-group17-sha512 | 1193 | diffie-hellman-group18-sha512 | diffie-hellman-group18-sha512 | 1194 | ecdh-sha2-secp256r1 | ecdh-sha2-secp256r1 | 1195 | ecdh-sha2-secp384r1 | ecdh-sha2-secp384r1 | 1196 +-------------------------------+-------------------------------+ 1198 Table 2 The SSH Key-exchange-alg Compatibility Matrix 1200 +-----------------------+---------------------------------------+ 1201 | sshcmn:encryption-alg | ct:symmetric-key-encryption-algorithm | 1202 +-----------------------+---------------------------------------+ 1203 | aes-128-cbc | aes-128-cbc | 1204 | aes-192-cbc | aes-192-cbc | 1205 | aes-256-cbc | aes-256-cbc | 1206 | aes-128-ctr | aes-128-ctr | 1207 | aes-192-ctr | aes-192-ctr | 1208 | aes-256-ctr | aes-256-ctr | 1209 +-----------------------+---------------------------------------+ 1211 Table 3 The SSH Encryption-alg Compatibility Matrix 1212 +----------------+-------------------+ 1213 | sshcmn:mac-alg | ct:mac-algorithm | 1214 +----------------+-------------------+ 1215 | hmac-sha1 | hmac-sha1 | 1216 | hmac-sha1-96 | hmac-sha1-96 | 1217 | hmac-sha2-256 | hmac-sha2-256 | 1218 | hmac-sha2-512 | hmac-sha2-512 | 1219 +----------------+-------------------+ 1221 Table 4 The SSH Mac-alg Compatibility Matrix 1223 As is seen in the tables above, the names of the "sshcmn" algorithms 1224 are all identical to the names of algorithms defined in 1225 [I-D.ietf-netconf-crypto-types]. While appearing to be redundant, it 1226 is important to realize that not all the algorithms defined in 1227 [I-D.ietf-netconf-crypto-types] are supported by SSH. That is, the 1228 algorithms supported by SSH are a subset of the algorithms defined in 1229 [I-D.ietf-netconf-crypto-types]. The algorithms used by SSH are 1230 redefined in this document in order to constrain the algorithms that 1231 may be selected to just the ones used by SSH. 1233 Features are defined for algorithms that are OPTIONAL or are not 1234 widely supported by popular implementations. Note that the list of 1235 algorithms is not exhaustive. As well, some algorithms that are 1236 REQUIRED by [RFC4253] are missing, notably "ssh-dss" and "diffie- 1237 hellman-group1-sha1" due to their weak security and there being 1238 alternatives that are widely supported. 1240 5.1. Tree Diagram 1242 The following tree diagram [RFC8340] provides an overview of the data 1243 model for the "ietf-ssh-common" module. 1245 module: ietf-ssh-common 1247 grouping transport-params-grouping 1248 +-- host-key 1249 | +-- host-key-alg* identityref 1250 +-- key-exchange 1251 | +-- key-exchange-alg* identityref 1252 +-- encryption 1253 | +-- encryption-alg* identityref 1254 +-- mac 1255 +-- mac-alg* identityref 1257 5.2. Example Usage 1259 This following example illustrates how the transport-params-grouping 1260 appears when populated with some data. 1262 1265 1266 algs:x509v3-rsa2048-sha256 1267 algs:ssh-rsa 1268 1269 1270 1271 algs:diffie-hellman-group-exchange-sha256 1272 1273 1274 1275 algs:aes256-ctr 1276 algs:aes192-ctr 1277 algs:aes128-ctr 1278 algs:aes256-cbc 1279 algs:aes192-cbc 1280 algs:aes128-cbc 1281 1282 1283 algs:hmac-sha2-256 1284 algs:hmac-sha2-512 1285 1286 1288 5.3. YANG Module 1290 This YANG module has normative references to [RFC4253], [RFC4344], 1291 [RFC4419], [RFC5656], [RFC6187], and [RFC6668]. 1293 file "ietf-ssh-common@2019-06-07.yang" 1294 module ietf-ssh-common { 1295 yang-version 1.1; 1296 namespace "urn:ietf:params:xml:ns:yang:ietf-ssh-common"; 1297 prefix sshcmn; 1299 organization 1300 "IETF NETCONF (Network Configuration) Working Group"; 1302 contact 1303 "WG Web: 1304 WG List: 1305 Author: Kent Watsen 1306 Author: Gary Wu "; 1308 description 1309 "This module defines a common features, identities, and 1310 groupings for Secure Shell (SSH). 1312 Copyright (c) 2019 IETF Trust and the persons identified 1313 as authors of the code. All rights reserved. 1315 Redistribution and use in source and binary forms, with 1316 or without modification, is permitted pursuant to, and 1317 subject to the license terms contained in, the Simplified 1318 BSD License set forth in Section 4.c of the IETF Trust's 1319 Legal Provisions Relating to IETF Documents 1320 (https://trustee.ietf.org/license-info). 1322 This version of this YANG module is part of RFC XXXX 1323 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC 1324 itself for full legal notices.; 1326 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1327 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 1328 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 1329 are to be interpreted as described in BCP 14 (RFC 2119) 1330 (RFC 8174) when, and only when, they appear in all 1331 capitals, as shown here."; 1333 revision 2019-06-07 { 1334 description 1335 "Initial version"; 1336 reference 1337 "RFC XXXX: YANG Groupings for SSH Clients and SSH Servers"; 1338 } 1340 // Features 1342 feature ssh-ecc { 1343 description 1344 "Elliptic Curve Cryptography is supported for SSH."; 1345 reference 1346 "RFC 5656: Elliptic Curve Algorithm Integration in the 1347 Secure Shell Transport Layer"; 1348 } 1350 feature ssh-x509-certs { 1351 description 1352 "X.509v3 certificates are supported for SSH per RFC 6187."; 1354 reference 1355 "RFC 6187: X.509v3 Certificates for Secure Shell 1356 Authentication"; 1357 } 1359 feature ssh-dh-group-exchange { 1360 description 1361 "Diffie-Hellman Group Exchange is supported for SSH."; 1362 reference 1363 "RFC 4419: Diffie-Hellman Group Exchange for the 1364 Secure Shell (SSH) Transport Layer Protocol"; 1365 } 1367 feature ssh-ctr { 1368 description 1369 "SDCTR encryption mode is supported for SSH."; 1370 reference 1371 "RFC 4344: The Secure Shell (SSH) Transport Layer 1372 Encryption Modes"; 1373 } 1375 feature ssh-sha2 { 1376 description 1377 "The SHA2 family of cryptographic hash functions is 1378 supported for SSH."; 1379 reference 1380 "FIPS PUB 180-4: Secure Hash Standard (SHS)"; 1381 } 1383 // Identities 1385 identity public-key-alg-base { 1386 description 1387 "Base identity used to identify public key algorithms."; 1388 } 1390 identity ssh-dss { 1391 base public-key-alg-base; 1392 description 1393 "Digital Signature Algorithm using SHA-1 as the 1394 hashing algorithm."; 1395 reference 1396 "RFC 4253: 1397 The Secure Shell (SSH) Transport Layer Protocol"; 1398 } 1400 identity ssh-rsa { 1401 base public-key-alg-base; 1402 description 1403 "RSASSA-PKCS1-v1_5 signature scheme using SHA-1 as the 1404 hashing algorithm."; 1405 reference 1406 "RFC 4253: 1407 The Secure Shell (SSH) Transport Layer Protocol"; 1408 } 1410 identity ecdsa-sha2-nistp256 { 1411 base public-key-alg-base; 1412 if-feature "ssh-ecc and ssh-sha2"; 1413 description 1414 "Elliptic Curve Digital Signature Algorithm (ECDSA) using the 1415 nistp256 curve and the SHA2 family of hashing algorithms."; 1416 reference 1417 "RFC 5656: Elliptic Curve Algorithm Integration in the 1418 Secure Shell Transport Layer"; 1419 } 1421 identity ecdsa-sha2-nistp384 { 1422 base public-key-alg-base; 1423 if-feature "ssh-ecc and ssh-sha2"; 1424 description 1425 "Elliptic Curve Digital Signature Algorithm (ECDSA) using the 1426 nistp384 curve and the SHA2 family of hashing algorithms."; 1427 reference 1428 "RFC 5656: Elliptic Curve Algorithm Integration in the 1429 Secure Shell Transport Layer"; 1430 } 1432 identity ecdsa-sha2-nistp521 { 1433 base public-key-alg-base; 1434 if-feature "ssh-ecc and ssh-sha2"; 1435 description 1436 "Elliptic Curve Digital Signature Algorithm (ECDSA) using the 1437 nistp521 curve and the SHA2 family of hashing algorithms."; 1438 reference 1439 "RFC 5656: Elliptic Curve Algorithm Integration in the 1440 Secure Shell Transport Layer"; 1441 } 1443 identity x509v3-ssh-rsa { 1444 base public-key-alg-base; 1445 if-feature "ssh-x509-certs"; 1446 description 1447 "RSASSA-PKCS1-v1_5 signature scheme using a public key stored 1448 in an X.509v3 certificate and using SHA-1 as the hashing 1449 algorithm."; 1451 reference 1452 "RFC 6187: X.509v3 Certificates for Secure Shell 1453 Authentication"; 1454 } 1456 identity x509v3-rsa2048-sha256 { 1457 base public-key-alg-base; 1458 if-feature "ssh-x509-certs and ssh-sha2"; 1459 description 1460 "RSASSA-PKCS1-v1_5 signature scheme using a public key stored 1461 in an X.509v3 certificate and using SHA-256 as the hashing 1462 algorithm. RSA keys conveyed using this format MUST have a 1463 modulus of at least 2048 bits."; 1464 reference 1465 "RFC 6187: X.509v3 Certificates for Secure Shell 1466 Authentication"; 1467 } 1469 identity x509v3-ecdsa-sha2-nistp256 { 1470 base public-key-alg-base; 1471 if-feature "ssh-ecc and ssh-x509-certs and ssh-sha2"; 1472 description 1473 "Elliptic Curve Digital Signature Algorithm (ECDSA) 1474 using the nistp256 curve with a public key stored in 1475 an X.509v3 certificate and using the SHA2 family of 1476 hashing algorithms."; 1477 reference 1478 "RFC 6187: X.509v3 Certificates for Secure Shell 1479 Authentication"; 1480 } 1482 identity x509v3-ecdsa-sha2-nistp384 { 1483 base public-key-alg-base; 1484 if-feature "ssh-ecc and ssh-x509-certs and ssh-sha2"; 1485 description 1486 "Elliptic Curve Digital Signature Algorithm (ECDSA) 1487 using the nistp384 curve with a public key stored in 1488 an X.509v3 certificate and using the SHA2 family of 1489 hashing algorithms."; 1490 reference 1491 "RFC 6187: X.509v3 Certificates for Secure Shell 1492 Authentication"; 1493 } 1495 identity x509v3-ecdsa-sha2-nistp521 { 1496 base public-key-alg-base; 1497 if-feature "ssh-ecc and ssh-x509-certs and ssh-sha2"; 1498 description 1499 "Elliptic Curve Digital Signature Algorithm (ECDSA) 1500 using the nistp521 curve with a public key stored in 1501 an X.509v3 certificate and using the SHA2 family of 1502 hashing algorithms."; 1503 reference 1504 "RFC 6187: X.509v3 Certificates for Secure Shell 1505 Authentication"; 1506 } 1508 identity key-exchange-alg-base { 1509 description 1510 "Base identity used to identify key exchange algorithms."; 1511 } 1513 identity diffie-hellman-group14-sha1 { 1514 base key-exchange-alg-base; 1515 description 1516 "Diffie-Hellman key exchange with SHA-1 as HASH and 1517 Oakley Group 14 (2048-bit MODP Group)."; 1518 reference 1519 "RFC 4253: The Secure Shell (SSH) Transport Layer Protocol"; 1520 } 1522 identity diffie-hellman-group-exchange-sha1 { 1523 base key-exchange-alg-base; 1524 if-feature "ssh-dh-group-exchange"; 1525 description 1526 "Diffie-Hellman Group and Key Exchange with SHA-1 as HASH."; 1527 reference 1528 "RFC 4419: Diffie-Hellman Group Exchange for the 1529 Secure Shell (SSH) Transport Layer Protocol"; 1530 } 1532 identity diffie-hellman-group-exchange-sha256 { 1533 base key-exchange-alg-base; 1534 if-feature "ssh-dh-group-exchange and ssh-sha2"; 1535 description 1536 "Diffie-Hellman Group and Key Exchange with SHA-256 as HASH."; 1537 reference 1538 "RFC 4419: Diffie-Hellman Group Exchange for the 1539 Secure Shell (SSH) Transport Layer Protocol"; 1540 } 1542 identity ecdh-sha2-nistp256 { 1543 base key-exchange-alg-base; 1544 if-feature "ssh-ecc and ssh-sha2"; 1545 description 1546 "Elliptic Curve Diffie-Hellman (ECDH) key exchange using the 1547 nistp256 curve and the SHA2 family of hashing algorithms."; 1548 reference 1549 "RFC 5656: Elliptic Curve Algorithm Integration in the 1550 Secure Shell Transport Layer"; 1551 } 1553 identity ecdh-sha2-nistp384 { 1554 base key-exchange-alg-base; 1555 if-feature "ssh-ecc and ssh-sha2"; 1556 description 1557 "Elliptic Curve Diffie-Hellman (ECDH) key exchange using the 1558 nistp384 curve and the SHA2 family of hashing algorithms."; 1559 reference 1560 "RFC 5656: Elliptic Curve Algorithm Integration in the 1561 Secure Shell Transport Layer"; 1562 } 1564 identity ecdh-sha2-nistp521 { 1565 base key-exchange-alg-base; 1566 if-feature "ssh-ecc and ssh-sha2"; 1567 description 1568 "Elliptic Curve Diffie-Hellman (ECDH) key exchange using the 1569 nistp521 curve and the SHA2 family of hashing algorithms."; 1570 reference 1571 "RFC 5656: Elliptic Curve Algorithm Integration in the 1572 Secure Shell Transport Layer"; 1573 } 1575 identity encryption-alg-base { 1576 description 1577 "Base identity used to identify encryption algorithms."; 1578 } 1580 identity triple-des-cbc { 1581 base encryption-alg-base; 1582 description 1583 "Three-key 3DES in CBC mode."; 1584 reference 1585 "RFC 4253: The Secure Shell (SSH) Transport Layer Protocol"; 1586 } 1588 identity aes128-cbc { 1589 base encryption-alg-base; 1590 description 1591 "AES in CBC mode, with a 128-bit key."; 1592 reference 1593 "RFC 4253: The Secure Shell (SSH) Transport Layer Protocol"; 1594 } 1595 identity aes192-cbc { 1596 base encryption-alg-base; 1597 description 1598 "AES in CBC mode, with a 192-bit key."; 1599 reference 1600 "RFC 4253: The Secure Shell (SSH) Transport Layer Protocol"; 1601 } 1603 identity aes256-cbc { 1604 base encryption-alg-base; 1605 description 1606 "AES in CBC mode, with a 256-bit key."; 1607 reference 1608 "RFC 4253: The Secure Shell (SSH) Transport Layer Protocol"; 1609 } 1611 identity aes128-ctr { 1612 base encryption-alg-base; 1613 if-feature "ssh-ctr"; 1614 description 1615 "AES in SDCTR mode, with 128-bit key."; 1616 reference 1617 "RFC 4344: The Secure Shell (SSH) Transport Layer Encryption 1618 Modes"; 1619 } 1621 identity aes192-ctr { 1622 base encryption-alg-base; 1623 if-feature "ssh-ctr"; 1624 description 1625 "AES in SDCTR mode, with 192-bit key."; 1626 reference 1627 "RFC 4344: The Secure Shell (SSH) Transport Layer Encryption 1628 Modes"; 1629 } 1631 identity aes256-ctr { 1632 base encryption-alg-base; 1633 if-feature "ssh-ctr"; 1634 description 1635 "AES in SDCTR mode, with 256-bit key."; 1636 reference 1637 "RFC 4344: The Secure Shell (SSH) Transport Layer Encryption 1638 Modes"; 1639 } 1641 identity mac-alg-base { 1642 description 1643 "Base identity used to identify message authentication 1644 code (MAC) algorithms."; 1645 } 1647 identity hmac-sha1 { 1648 base mac-alg-base; 1649 description 1650 "HMAC-SHA1"; 1651 reference 1652 "RFC 4253: The Secure Shell (SSH) Transport Layer Protocol"; 1653 } 1655 identity hmac-sha2-256 { 1656 base mac-alg-base; 1657 if-feature "ssh-sha2"; 1658 description 1659 "HMAC-SHA2-256"; 1660 reference 1661 "RFC 6668: SHA-2 Data Integrity Verification for the 1662 Secure Shell (SSH) Transport Layer Protocol"; 1663 } 1665 identity hmac-sha2-512 { 1666 base mac-alg-base; 1667 if-feature "ssh-sha2"; 1668 description 1669 "HMAC-SHA2-512"; 1670 reference 1671 "RFC 6668: SHA-2 Data Integrity Verification for the 1672 Secure Shell (SSH) Transport Layer Protocol"; 1673 } 1675 // Groupings 1677 grouping transport-params-grouping { 1678 description 1679 "A reusable grouping for SSH transport parameters."; 1680 reference 1681 "RFC 4253: The Secure Shell (SSH) Transport Layer Protocol"; 1682 container host-key { 1683 description 1684 "Parameters regarding host key."; 1685 leaf-list host-key-alg { 1686 type identityref { 1687 base public-key-alg-base; 1688 } 1689 ordered-by user; 1690 description 1691 "Acceptable host key algorithms in order of descending 1692 preference. The configured host key algorithms should 1693 be compatible with the algorithm used by the configured 1694 private key. Please see Section 5 of RFC XXXX for 1695 valid combinations. 1697 If this leaf-list is not configured (has zero elements) 1698 the acceptable host key algorithms are implementation- 1699 defined."; 1700 reference 1701 "RFC XXXX: YANG Groupings for SSH Clients and SSH Servers"; 1702 } 1703 } 1704 container key-exchange { 1705 description 1706 "Parameters regarding key exchange."; 1707 leaf-list key-exchange-alg { 1708 type identityref { 1709 base key-exchange-alg-base; 1710 } 1711 ordered-by user; 1712 description 1713 "Acceptable key exchange algorithms in order of descending 1714 preference. 1716 If this leaf-list is not configured (has zero elements) 1717 the acceptable key exchange algorithms are implementation 1718 defined."; 1719 } 1720 } 1721 container encryption { 1722 description 1723 "Parameters regarding encryption."; 1724 leaf-list encryption-alg { 1725 type identityref { 1726 base encryption-alg-base; 1727 } 1728 ordered-by user; 1729 description 1730 "Acceptable encryption algorithms in order of descending 1731 preference. 1733 If this leaf-list is not configured (has zero elements) 1734 the acceptable encryption algorithms are implementation 1735 defined."; 1736 } 1737 } 1738 container mac { 1739 description 1740 "Parameters regarding message authentication code (MAC)."; 1741 leaf-list mac-alg { 1742 type identityref { 1743 base mac-alg-base; 1744 } 1745 ordered-by user; 1746 description 1747 "Acceptable MAC algorithms in order of descending 1748 preference. 1750 If this leaf-list is not configured (has zero elements) 1751 the acceptable MAC algorithms are implementation- 1752 defined."; 1753 } 1754 } 1755 } 1756 } 1757 1759 6. Security Considerations 1761 The YANG modules defined in this document are designed to be accessed 1762 via YANG based management protocols, such as NETCONF [RFC6241] and 1763 RESTCONF [RFC8040]. Both of these protocols have mandatory-to- 1764 implement secure transport layers (e.g., SSH, TLS) with mutual 1765 authentication. 1767 The NETCONF access control model (NACM) [RFC8341] provides the means 1768 to restrict access for particular users to a pre-configured subset of 1769 all available protocol operations and content. 1771 Since the modules in this document only define groupings, these 1772 considerations are primarily for the designers of other modules that 1773 use these groupings. 1775 There are a number of data nodes defined in the YANG modules that are 1776 writable/creatable/deletable (i.e., config true, which is the 1777 default). These data nodes may be considered sensitive or vulnerable 1778 in some network environments. Write operations (e.g., edit-config) 1779 to these data nodes without proper protection can have a negative 1780 effect on network operations. These are the subtrees and data nodes 1781 and their sensitivity/vulnerability: 1783 *: All of the nodes defined by the grouping statement in both the 1784 "ietf-ssh-client" and "ietf-ssh-server" modules are sensitive 1785 to write operations. For instance, the addition or removal of 1786 references to keys, certificates, trusted anchors, etc., or 1787 even the modification of transport or keepalive parameters can 1788 dramatically alter the implemented security policy. For this 1789 reason, all the nodes are protected the NACM extension 1790 "default-deny-write". 1792 Some of the readable data nodes in the YANG modules may be considered 1793 sensitive or vulnerable in some network environments. It is thus 1794 important to control read access (e.g., via get, get-config, or 1795 notification) to these data nodes. These are the subtrees and data 1796 nodes and their sensitivity/vulnerability: 1798 ssh-client-grouping/client-identity/: This subtree in the "ietf- 1799 ssh-client" module contains nodes that are additionally 1800 sensitive to read operations such that, in normal use cases, 1801 they should never be returned to a client. Specifically, the 1802 descendent nodes 'password', 'public-key/local-definition/ 1803 private-key' and 'certificate/local-definition/private-key'. 1804 For this reason, all of these node are protected by the NACM 1805 extension "default-deny-all". 1807 ssh-server-grouping/server-identity/: This subtree in the "ietf- 1808 ssh-server" module contains nodes that are additionally 1809 sensitive to read operations such that, in normal use cases, 1810 they should never be returned to a client. Specifically, the 1811 descendent nodes 'host-key/public-key/local-definition/private- 1812 key' and 'host-key/certificate/local-definition/private-key'. 1813 For this reason, both of these node are protected by the NACM 1814 extension "default-deny-all". 1816 Some of the operations in this YANG module may be considered 1817 sensitive or vulnerable in some network environments. It is thus 1818 important to control access to these operations. These are the 1819 operations and their sensitivity/vulnerability: 1821 *: The groupings defined in this document include "action" 1822 statements that come from groupings defined in 1823 [I-D.ietf-netconf-crypto-types]. Please consult that document 1824 for the security considerations of the "action" statements 1825 defined by the "grouping" statements defined in this document. 1827 7. IANA Considerations 1829 7.1. The IETF XML Registry 1831 This document registers three URIs in the "ns" subregistry of the 1832 IETF XML Registry [RFC3688]. Following the format in [RFC3688], the 1833 following registrations are requested: 1835 URI: urn:ietf:params:xml:ns:yang:ietf-ssh-client 1836 Registrant Contact: The NETCONF WG of the IETF. 1837 XML: N/A, the requested URI is an XML namespace. 1839 URI: urn:ietf:params:xml:ns:yang:ietf-ssh-server 1840 Registrant Contact: The NETCONF WG of the IETF. 1841 XML: N/A, the requested URI is an XML namespace. 1843 URI: urn:ietf:params:xml:ns:yang:ietf-ssh-common 1844 Registrant Contact: The NETCONF WG of the IETF. 1845 XML: N/A, the requested URI is an XML namespace. 1847 7.2. The YANG Module Names Registry 1849 This document registers three YANG modules in the YANG Module Names 1850 registry [RFC6020]. Following the format in [RFC6020], the following 1851 registrations are requested: 1853 name: ietf-ssh-client 1854 namespace: urn:ietf:params:xml:ns:yang:ietf-ssh-client 1855 prefix: sshc 1856 reference: RFC XXXX 1858 name: ietf-ssh-server 1859 namespace: urn:ietf:params:xml:ns:yang:ietf-ssh-server 1860 prefix: sshs 1861 reference: RFC XXXX 1863 name: ietf-ssh-common 1864 namespace: urn:ietf:params:xml:ns:yang:ietf-ssh-common 1865 prefix: sshcmn 1866 reference: RFC XXXX 1868 8. References 1870 8.1. Normative References 1872 [I-D.ietf-netconf-crypto-types] 1873 Watsen, K. and H. Wang, "Common YANG Data Types for 1874 Cryptography", draft-ietf-netconf-crypto-types-06 (work in 1875 progress), April 2019. 1877 [I-D.ietf-netconf-keystore] 1878 Watsen, K., "YANG Data Model for a Centralized Keystore 1879 Mechanism", draft-ietf-netconf-keystore-09 (work in 1880 progress), April 2019. 1882 [I-D.ietf-netconf-trust-anchors] 1883 Watsen, K., "YANG Data Model for Global Trust Anchors", 1884 draft-ietf-netconf-trust-anchors-04 (work in progress), 1885 April 2019. 1887 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1888 Requirement Levels", BCP 14, RFC 2119, 1889 DOI 10.17487/RFC2119, March 1997, 1890 . 1892 [RFC4344] Bellare, M., Kohno, T., and C. Namprempre, "The Secure 1893 Shell (SSH) Transport Layer Encryption Modes", RFC 4344, 1894 DOI 10.17487/RFC4344, January 2006, 1895 . 1897 [RFC4419] Friedl, M., Provos, N., and W. Simpson, "Diffie-Hellman 1898 Group Exchange for the Secure Shell (SSH) Transport Layer 1899 Protocol", RFC 4419, DOI 10.17487/RFC4419, March 2006, 1900 . 1902 [RFC5656] Stebila, D. and J. Green, "Elliptic Curve Algorithm 1903 Integration in the Secure Shell Transport Layer", 1904 RFC 5656, DOI 10.17487/RFC5656, December 2009, 1905 . 1907 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1908 the Network Configuration Protocol (NETCONF)", RFC 6020, 1909 DOI 10.17487/RFC6020, October 2010, 1910 . 1912 [RFC6187] Igoe, K. and D. Stebila, "X.509v3 Certificates for Secure 1913 Shell Authentication", RFC 6187, DOI 10.17487/RFC6187, 1914 March 2011, . 1916 [RFC6668] Bider, D. and M. Baushke, "SHA-2 Data Integrity 1917 Verification for the Secure Shell (SSH) Transport Layer 1918 Protocol", RFC 6668, DOI 10.17487/RFC6668, July 2012, 1919 . 1921 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1922 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1923 . 1925 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1926 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1927 May 2017, . 1929 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 1930 Access Control Model", STD 91, RFC 8341, 1931 DOI 10.17487/RFC8341, March 2018, 1932 . 1934 8.2. Informative References 1936 [OPENSSH] Project, T. O., "OpenSSH", 2016, . 1938 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1939 DOI 10.17487/RFC3688, January 2004, 1940 . 1942 [RFC4252] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) 1943 Authentication Protocol", RFC 4252, DOI 10.17487/RFC4252, 1944 January 2006, . 1946 [RFC4253] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) 1947 Transport Layer Protocol", RFC 4253, DOI 10.17487/RFC4253, 1948 January 2006, . 1950 [RFC4254] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) 1951 Connection Protocol", RFC 4254, DOI 10.17487/RFC4254, 1952 January 2006, . 1954 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1955 and A. Bierman, Ed., "Network Configuration Protocol 1956 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1957 . 1959 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 1960 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 1961 . 1963 [RFC7317] Bierman, A. and M. Bjorklund, "A YANG Data Model for 1964 System Management", RFC 7317, DOI 10.17487/RFC7317, August 1965 2014, . 1967 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1968 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1969 . 1971 [RFC8071] Watsen, K., "NETCONF Call Home and RESTCONF Call Home", 1972 RFC 8071, DOI 10.17487/RFC8071, February 2017, 1973 . 1975 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 1976 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 1977 . 1979 Appendix A. Change Log 1981 A.1. 00 to 01 1983 o Noted that '0.0.0.0' and '::' might have special meanings. 1985 o Renamed "keychain" to "keystore". 1987 A.2. 01 to 02 1989 o Removed the groupings 'listening-ssh-client-grouping' and 1990 'listening-ssh-server-grouping'. Now modules only contain the 1991 transport-independent groupings. 1993 o Simplified the "client-auth" part in the ietf-ssh-client module. 1994 It now inlines what it used to point to keystore for. 1996 o Added cipher suites for various algorithms into new 'ietf-ssh- 1997 common' module. 1999 A.3. 02 to 03 2001 o Removed 'RESTRICTED' enum from 'password' leaf type. 2003 o Added a 'must' statement to container 'server-auth' asserting that 2004 at least one of the various auth mechanisms must be specified. 2006 o Fixed description statement for leaf 'trusted-ca-certs'. 2008 A.4. 03 to 04 2010 o Change title to "YANG Groupings for SSH Clients and SSH Servers" 2012 o Added reference to RFC 6668 2014 o Added RFC 8174 to Requirements Language Section. 2016 o Enhanced description statement for ietf-ssh-server's "trusted-ca- 2017 certs" leaf. 2019 o Added mandatory true to ietf-ssh-client's "client-auth" 'choice' 2020 statement. 2022 o Changed the YANG prefix for module ietf-ssh-common from 'sshcom' 2023 to 'sshcmn'. 2025 o Removed the compression algorithms as they are not commonly 2026 configurable in vendors' implementations. 2028 o Updating descriptions in transport-params-grouping and the 2029 servers's usage of it. 2031 o Now tree diagrams reference ietf-netmod-yang-tree-diagrams 2033 o Updated YANG to use typedefs around leafrefs to common keystore 2034 paths 2036 o Now inlines key and certificates (no longer a leafref to keystore) 2038 A.5. 04 to 05 2040 o Merged changes from co-author. 2042 A.6. 05 to 06 2044 o Updated to use trust anchors from trust-anchors draft (was 2045 keystore draft) 2047 o Now uses new keystore grouping enabling asymmetric key to be 2048 either locally defined or a reference to the keystore. 2050 A.7. 06 to 07 2052 o factored the ssh-[client|server]-groupings into more reusable 2053 groupings. 2055 o added if-feature statements for the new "ssh-host-keys" and 2056 "x509-certificates" features defined in draft-ietf-netconf-trust- 2057 anchors. 2059 A.8. 07 to 08 2061 o Added a number of compatibility matrices to Section 5 (thanks 2062 Frank!) 2064 o Clarified that any configured "host-key-alg" values need to be 2065 compatible with the configured private key. 2067 A.9. 08 to 09 2069 o Updated examples to reflect update to groupings defined in the 2070 keystore -09 draft. 2072 o Add SSH keepalives features and groupings. 2074 o Prefixed top-level SSH grouping nodes with 'ssh-' and support 2075 mashups. 2077 o Updated copyright date, boilerplate template, affiliation, and 2078 folding algorithm. 2080 A.10. 09 to 10 2082 o Reformatted the YANG modules. 2084 A.11. 10 to 11 2086 o Reformatted lines causing folding to occur. 2088 A.12. 11 to 12 2090 o Collapsed all the inner groupings into the top-level grouping. 2092 o Added a top-level "demux container" inside the top-level grouping. 2094 o Added NACM statements and updated the Security Considerations 2095 section. 2097 o Added "presence" statements on the "keepalive" containers, as was 2098 needed to address a validation error that appeared after adding 2099 the "must" statements into the NETCONF/RESTCONF client/server 2100 modules. 2102 o Updated the boilerplate text in module-level "description" 2103 statement to match copyeditor convention. 2105 A.13. 12 to 13 2107 o Removed the "demux containers", floating the nacm:default-deny- 2108 write to each descendent node, and adding a note to model 2109 designers regarding the potential need to add their own demux 2110 containers. 2112 o Fixed a couple references (section 2 --> section 3) 2114 o In the server model, replaced with and introduced 'local-or-external' choice. 2117 A.14. 13 to 14 2119 o Updated to reflect changes in trust-anchors drafts (e.g., s/trust- 2120 anchors/truststore/g + s/pinned.//) 2122 Acknowledgements 2124 The authors would like to thank for following for lively discussions 2125 on list and in the halls (ordered by last name): Andy Bierman, Martin 2126 Bjorklund, Benoit Claise, Mehmet Ersue, Balazs Kovacs, David 2127 Lamparter, Alan Luchuk, Ladislav Lhotka, Radek Krejci, Tom Petch, 2128 Juergen Schoenwaelder, Phil Shafer, Sean Turner, Michal Vasko, and 2129 Bert Wijnen. 2131 Authors' Addresses 2133 Kent Watsen 2134 Watsen Networks 2136 EMail: kent+ietf@watsen.net 2138 Gary Wu 2139 Cisco Systems 2141 EMail: garywu@cisco.com 2143 Liang Xia 2144 Huawei 2146 EMail: frank.xialiang@huawei.com