idnits 2.17.1 draft-ietf-netconf-ssh-client-server-12.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (April 7, 2019) is 1840 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-05 == Outdated reference: A later version (-35) exists of draft-ietf-netconf-keystore-08 == Outdated reference: A later version (-28) exists of draft-ietf-netconf-trust-anchors-03 Summary: 0 errors (**), 0 flaws (~~), 4 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: October 9, 2019 Cisco Systems 6 L. Xia 7 Huawei 8 April 7, 2019 10 YANG Groupings for SSH Clients and SSH Servers 11 draft-ietf-netconf-ssh-client-server-12 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-04-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 October 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 . . . . . . . . . . . . . . . . . . . . . . . 8 96 4. The SSH Server Model . . . . . . . . . . . . . . . . . . . . 13 97 4.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 13 98 4.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 13 99 4.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 16 100 5. The SSH Common Model . . . . . . . . . . . . . . . . . . . . 21 101 5.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 23 102 5.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 24 103 5.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 24 104 6. Security Considerations . . . . . . . . . . . . . . . . . . . 34 105 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 35 106 7.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 36 107 7.2. The YANG Module Names Registry . . . . . . . . . . . . . 36 108 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 36 109 8.1. Normative References . . . . . . . . . . . . . . . . . . 36 110 8.2. Informative References . . . . . . . . . . . . . . . . . 38 111 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 40 112 A.1. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 40 113 A.2. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 40 114 A.3. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 40 115 A.4. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 40 116 A.5. 04 to 05 . . . . . . . . . . . . . . . . . . . . . . . . 41 117 A.6. 05 to 06 . . . . . . . . . . . . . . . . . . . . . . . . 41 118 A.7. 06 to 07 . . . . . . . . . . . . . . . . . . . . . . . . 41 119 A.8. 07 to 08 . . . . . . . . . . . . . . . . . . . . . . . . 41 120 A.9. 08 to 09 . . . . . . . . . . . . . . . . . . . . . . . . 41 121 A.10. 09 to 10 . . . . . . . . . . . . . . . . . . . . . . . . 42 122 A.11. 10 to 11 . . . . . . . . . . . . . . . . . . . . . . . . 42 123 A.12. 11 to 12 . . . . . . . . . . . . . . . . . . . . . . . . 42 124 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 42 125 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 42 127 1. Introduction 129 This document defines three YANG 1.1 [RFC7950] modules: the first 130 defines a grouping for a generic SSH client, the second defines a 131 grouping for a generic SSH server, and the third defines identities 132 and groupings common to both the client and the server. It is 133 intended that these groupings will be used by applications using the 134 SSH protocol [RFC4252], [RFC4253], and [RFC4254]. For instance, 135 these groupings could be used to help define the data model for an 136 OpenSSH [OPENSSH] server or a NETCONF over SSH [RFC6242] based 137 server. 139 The client and server YANG modules in this document each define one 140 grouping, which is focused on just SSH-specific configuration, and 141 specifically avoids any transport-level configuration, such as what 142 ports to listen on or connect to. This affords applications the 143 opportunity to define their own strategy for how the underlying TCP 144 connection is established. For instance, applications supporting 145 NETCONF Call Home [RFC8071] could use the "ssh-server-grouping" 146 grouping for the SSH parts it provides, while adding data nodes for 147 the TCP-level call-home configuration. 149 The modules defined in this document use groupings defined in 150 [I-D.ietf-netconf-keystore] enabling keys to be either locally 151 defined or a reference to globally configured values. 153 The modules defined in this document optionally support [RFC6187] 154 enabling X.509v3 certificate based host keys and public keys. 156 2. Terminology 158 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 159 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 160 "OPTIONAL" in this document are to be interpreted as described in BCP 161 14 [RFC2119] [RFC8174] when, and only when, they appear in all 162 capitals, as shown here. 164 3. The SSH Client Model 166 3.1. Tree Diagram 168 This section provides a tree diagram [RFC8340] for the "ietf-ssh- 169 client" module that does not have groupings expanded. 171 =========== NOTE: '\' line wrapping per BCP XX (RFC XXXX) =========== 173 module: ietf-ssh-client 175 grouping ssh-client-grouping 176 +-- ssh-client-parameters 177 +-- client-identity 178 | +-- username? string 179 | +-- (auth-type) 180 | +--:(password) 181 | | +-- password? string 182 | +--:(public-key) 183 | | +-- public-key 184 | | +---u ks:local-or-keystore-asymmetric-key-grouping 185 | +--:(certificate) 186 | +-- certificate {sshcmn:ssh-x509-certs}? 187 | +---u ks:local-or-keystore-end-entity-cert-with-k\ 188 ey-grouping 189 +-- server-authentication 190 | +-- pinned-ssh-host-keys? ta:pinned-host-keys-ref 191 | | {ta:ssh-host-keys}? 192 | +-- pinned-ca-certs? ta:pinned-certificates-ref 193 | | {sshcmn:ssh-x509-certs,ta:x509-certificates}? 194 | +-- pinned-server-certs? ta:pinned-certificates-ref 195 | {sshcmn:ssh-x509-certs,ta: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 3 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 222 223 224 foobar 225 226 227 ct:rsa2048 229 base64encodedvalue== 230 base64encodedvalue== 231 232 233 235 236 237 explicitly-trusted-ssh-host-keys 239 241 242 243 algs:ssh-rsa 244 245 246 247 algs:diffie-hellman-group-exchange-sha256 248 249 250 251 algs:aes256-ctr 252 algs:aes192-ctr 253 algs:aes128-ctr 254 algs:aes256-cbc 255 algs:aes192-cbc 256 algs:aes128-cbc 257 258 259 algs:hmac-sha2-256 260 algs:hmac-sha2-512 261 262 264 265 30 266 3 268 270 271 273 The following example configures the client identity using a key from 274 the keystore: 276 =========== NOTE: '\' line wrapping per BCP XX (RFC XXXX) =========== 278 281 283 284 285 foobar 286 287 ex-rsa-key 288 289 291 292 293 explicitly-trusted-ssh-host-keys 295 297 298 299 algs:ssh-rsa 300 301 302 303 algs:diffie-hellman-group-exchange-sha256 304 305 306 307 algs:aes256-ctr 308 algs:aes192-ctr 309 algs:aes128-ctr 310 algs:aes256-cbc 311 algs:aes192-cbc 312 algs:aes128-cbc 313 314 315 algs:hmac-sha2-256 316 algs:hmac-sha2-512 317 318 320 321 30 322 3 323 325 326 328 3.3. YANG Module 330 This YANG module has normative references to 331 [I-D.ietf-netconf-trust-anchors], and [I-D.ietf-netconf-keystore]. 333 file "ietf-ssh-client@2019-04-07.yang" 334 module ietf-ssh-client { 335 yang-version 1.1; 336 namespace "urn:ietf:params:xml:ns:yang:ietf-ssh-client"; 337 prefix sshc; 339 import ietf-ssh-common { 340 prefix sshcmn; 341 revision-date 2019-04-07; // stable grouping definitions 342 reference 343 "RFC XXXX: YANG Groupings for SSH Clients and SSH Servers"; 344 } 346 import ietf-trust-anchors { 347 prefix ta; 348 reference 349 "RFC YYYY: YANG Data Model for Global Trust Anchors"; 350 } 352 import ietf-keystore { 353 prefix ks; 354 reference 355 "RFC ZZZZ: 356 YANG Data Model for a Centralized Keystore Mechanism"; 357 } 359 import ietf-netconf-acm { 360 prefix nacm; 361 reference 362 "RFC 8341: Network Configuration Access Control Model"; 363 } 364 organization 365 "IETF NETCONF (Network Configuration) Working Group"; 367 contact 368 "WG Web: 369 WG List: 370 Author: Kent Watsen 371 Author: Gary Wu "; 373 description 374 "This module defines reusable groupings for SSH clients that 375 can be used as a basis for specific SSH client instances. 377 Copyright (c) 2019 IETF Trust and the persons identified 378 as authors of the code. All rights reserved. 380 Redistribution and use in source and binary forms, with 381 or without modification, is permitted pursuant to, and 382 subject to the license terms contained in, the Simplified 383 BSD License set forth in Section 4.c of the IETF Trust's 384 Legal Provisions Relating to IETF Documents 385 (https://trustee.ietf.org/license-info). 387 This version of this YANG module is part of RFC XXXX 388 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC 389 itself for full legal notices.; 391 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 392 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 393 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 394 are to be interpreted as described in BCP 14 (RFC 2119) 395 (RFC 8174) when, and only when, they appear in all 396 capitals, as shown here."; 398 revision 2019-04-07 { 399 description 400 "Initial version"; 401 reference 402 "RFC XXXX: YANG Groupings for SSH Clients and SSH Servers"; 403 } 405 // Features 407 feature ssh-client-transport-params-config { 408 description 409 "SSH transport layer parameters are configurable on an SSH 410 client."; 411 } 412 feature ssh-client-keepalives { 413 description 414 "Per socket SSH keepalive parameters are configurable for 415 SSH clients on the server implementing this feature."; 416 } 418 // Groupings 420 grouping ssh-client-grouping { 421 description 422 "A reusable grouping for configuring a SSH client without 423 any consideration for how an underlying TCP session is 424 established."; 426 container ssh-client-parameters { 427 nacm:default-deny-write; 429 description 430 "A container to hold SSH client configuration."; 432 container client-identity { 433 description 434 "The credentials used by the client to authenticate to 435 the SSH server."; 436 leaf username { 437 type string; 438 description 439 "The username of this user. This will be the username 440 used, for instance, to log into an SSH server."; 441 } 442 choice auth-type { 443 mandatory true; 444 description 445 "The authentication type."; 446 leaf password { 447 nacm:default-deny-all; 448 type string; 449 description 450 "A password to be used for client authentication."; 451 } 452 container public-key { 453 uses ks:local-or-keystore-asymmetric-key-grouping; 454 description 455 "A locally-defined or referenced asymmetric key 456 pair to be used for client authentication."; 457 reference 458 "RFC ZZZZ: YANG Data Model for a Centralized 459 Keystore Mechanism"; 461 } 462 container certificate { 463 if-feature "sshcmn:ssh-x509-certs"; 464 uses 465 ks:local-or-keystore-end-entity-cert-with-key-grouping; 466 description 467 "A locally-defined or referenced certificate 468 to be used for client authentication."; 469 reference 470 "RFC ZZZZ: YANG Data Model for a Centralized 471 Keystore Mechanism"; 472 } 473 } 474 } // container client-identity 476 container server-authentication { 477 must 'pinned-ssh-host-keys or pinned-ca-certs or ' 478 + 'pinned-server-certs'; 479 description 480 "Trusted server identities."; 481 leaf pinned-ssh-host-keys { 482 if-feature "ta:ssh-host-keys"; 483 type ta:pinned-host-keys-ref; 484 description 485 "A reference to a list of SSH host keys used by the 486 SSH client to authenticate SSH server host keys. 487 A server host key is authenticated if it is an 488 exact match to a configured SSH host key."; 489 reference 490 "RFC YYYY: YANG Data Model for Global Trust Anchors"; 491 } 492 leaf pinned-ca-certs { 493 if-feature "sshcmn:ssh-x509-certs"; 494 if-feature "ta:x509-certificates"; 495 type ta:pinned-certificates-ref; 496 description 497 "A reference to a list of certificate authority (CA) 498 certificates used by the SSH client to authenticate 499 SSH server certificates. A server certificate is 500 authenticated if it has a valid chain of trust to 501 a configured CA certificate."; 502 reference 503 "RFC YYYY: YANG Data Model for Global Trust Anchors"; 504 } 506 leaf pinned-server-certs { 507 if-feature "sshcmn:ssh-x509-certs"; 508 if-feature "ta:x509-certificates"; 509 type ta:pinned-certificates-ref; 510 description 511 "A reference to a list of server certificates used by 512 the SSH client to authenticate SSH server certificates. 513 A server certificate is authenticated if it is an 514 exact match to a configured server certificate."; 515 reference 516 "RFC YYYY: YANG Data Model for Global Trust Anchors"; 517 } 518 } // container server-authentication 520 container transport-params { 521 if-feature "ssh-client-transport-params-config"; 522 description 523 "Configurable parameters of the SSH transport layer."; 524 uses sshcmn:transport-params-grouping; 525 } // container transport-parameters 527 container keepalives { 528 if-feature "ssh-client-keepalives"; 529 presence "Indicates that keepalives are enabled."; 530 description 531 "Configures the keep-alive policy, to proactively test 532 the aliveness of the SSH server. An unresponsive TLS 533 server is dropped after approximately max-wait * 534 max-attempts seconds."; 535 leaf max-wait { 536 type uint16 { 537 range "1..max"; 538 } 539 units "seconds"; 540 default "30"; 541 description 542 "Sets the amount of time in seconds after which if 543 no data has been received from the SSH server, a 544 TLS-level message will be sent to test the 545 aliveness of the SSH server."; 546 } 547 leaf max-attempts { 548 type uint8; 549 default "3"; 550 description 551 "Sets the maximum number of sequential keep-alive 552 messages that can fail to obtain a response from 553 the SSH server before assuming the SSH server is 554 no longer alive."; 555 } 556 } // container keepalives 558 } // container ssh-client-parameters 559 } // grouping ssh-client-grouping 560 } 561 563 4. The SSH Server Model 565 4.1. Tree Diagram 567 This section provides a tree diagram [RFC8340] for the "ietf-ssh- 568 server" module that does not have groupings expanded. 570 =========== NOTE: '\' line wrapping per BCP XX (RFC XXXX) =========== 572 module: ietf-ssh-server 574 grouping ssh-server-grouping 575 +-- ssh-server-parameters 576 +-- server-identity 577 | +-- host-key* [name] 578 | +-- name? string 579 | +-- (host-key-type) 580 | +--:(public-key) 581 | | +-- public-key 582 | | +---u ks:local-or-keystore-asymmetric-key-grou\ 583 ping 584 | +--:(certificate) 585 | +-- certificate {sshcmn:ssh-x509-certs}? 586 | +---u ks:local-or-keystore-end-entity-cert-wit\ 587 h-key-grouping 588 +-- client-cert-auth {sshcmn:ssh-x509-certs}? 589 | +-- pinned-ca-certs? ta:pinned-certificates-ref 590 | | {ta:x509-certificates}? 591 | +-- pinned-client-certs? ta:pinned-certificates-ref 592 | {ta:x509-certificates}? 593 +-- transport-params {ssh-server-transport-params-config}? 594 | +---u sshcmn:transport-params-grouping 595 +-- keepalives! {ssh-server-keepalives}? 596 +-- max-wait? uint16 597 +-- max-attempts? uint8 599 4.2. Example Usage 601 This section presents two examples showing the ssh-server-grouping 602 populated with some data. These examples are effectively the same 603 except the first configures the server identity using a local key 604 while the second uses a key configured in a keystore. Both examples 605 are consistent with the examples presented in Section 3 of 607 [I-D.ietf-netconf-trust-anchors] and Section 3.2 of 608 [I-D.ietf-netconf-keystore]. 610 The following example configures the server identity using a local 611 key: 613 =========== NOTE: '\' line wrapping per BCP XX (RFC XXXX) =========== 615 618 620 621 622 623 deployment-specific-certificate 624 625 626 ct:rsa2048 628 base64encodedvalue== 629 base64encodedvalue== 630 631 632 633 635 636 637 explicitly-trusted-client-ca-certs 639 explicitly-trusted-client-certs 641 643 644 645 algs:ssh-rsa 646 647 648 649 algs:diffie-hellman-group-exchange-sha256 650 651 652 653 algs:aes256-ctr 654 algs:aes192-ctr 655 algs:aes128-ctr 656 algs:aes256-cbc 657 algs:aes192-cbc 658 algs:aes128-cbc 659 660 661 algs:hmac-sha2-256 662 algs:hmac-sha2-512 663 664 666 667 669 The following example configures the server identity using a key from 670 the keystore: 672 =========== NOTE: '\' line wrapping per BCP XX (RFC XXXX) =========== 674 677 679 680 681 682 deployment-specific-certificate 683 684 ex-rsa-key 685 686 687 689 690 691 explicitly-trusted-client-ca-certs 693 explicitly-trusted-client-certs 695 697 698 699 algs:ssh-rsa 700 701 702 703 algs:diffie-hellman-group-exchange-sha256 704 705 706 707 algs:aes256-ctr 708 algs:aes192-ctr 709 algs:aes128-ctr 710 algs:aes256-cbc 711 algs:aes192-cbc 712 algs:aes128-cbc 713 714 715 algs:hmac-sha2-256 716 algs:hmac-sha2-512 717 718 720 721 723 4.3. YANG Module 725 This YANG module has normative references to 726 [I-D.ietf-netconf-trust-anchors] and [I-D.ietf-netconf-keystore] and 727 informative references to [RFC4253] and [RFC7317]. 729 file "ietf-ssh-server@2019-04-07.yang" 730 module ietf-ssh-server { 731 yang-version 1.1; 732 namespace "urn:ietf:params:xml:ns:yang:ietf-ssh-server"; 733 prefix sshs; 735 import ietf-ssh-common { 736 prefix sshcmn; 737 revision-date 2019-04-07; // stable grouping definitions 738 reference 739 "RFC XXXX: YANG Groupings for SSH Clients and SSH Servers"; 740 } 742 import ietf-trust-anchors { 743 prefix ta; 744 reference 745 "RFC YYYY: YANG Data Model for Global Trust Anchors"; 746 } 748 import ietf-keystore { 749 prefix ks; 750 reference 751 "RFC ZZZZ: 752 YANG Data Model for a Centralized Keystore Mechanism"; 753 } 755 import ietf-netconf-acm { 756 prefix nacm; 757 reference 758 "RFC 8341: Network Configuration Access Control Model"; 759 } 761 organization 762 "IETF NETCONF (Network Configuration) Working Group"; 764 contact 765 "WG Web: 766 WG List: 767 Author: Kent Watsen 768 Author: Gary Wu "; 770 description 771 "This module defines reusable groupings for SSH servers that 772 can be used as a basis for specific SSH server instances. 774 Copyright (c) 2019 IETF Trust and the persons identified 775 as authors of the code. All rights reserved. 777 Redistribution and use in source and binary forms, with 778 or without modification, is permitted pursuant to, and 779 subject to the license terms contained in, the Simplified 780 BSD License set forth in Section 4.c of the IETF Trust's 781 Legal Provisions Relating to IETF Documents 782 (https://trustee.ietf.org/license-info). 784 This version of this YANG module is part of RFC XXXX 785 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC 786 itself for full legal notices.; 788 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 789 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 790 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 791 are to be interpreted as described in BCP 14 (RFC 2119) 792 (RFC 8174) when, and only when, they appear in all 793 capitals, as shown here."; 795 revision 2019-04-07 { 796 description 797 "Initial version"; 798 reference 799 "RFC XXXX: YANG Groupings for SSH Clients and SSH Servers"; 800 } 802 // Features 804 feature ssh-server-transport-params-config { 805 description 806 "SSH transport layer parameters are configurable on an SSH 807 server."; 808 } 810 feature ssh-server-keepalives { 811 description 812 "Per socket SSH keepalive parameters are configurable for 813 SSH servers on the server implementing this feature."; 814 } 816 // Groupings 818 grouping ssh-server-grouping { 819 description 820 "A reusable grouping for configuring a SSH server without 821 any consideration for how underlying TCP sessions are 822 established."; 824 container ssh-server-parameters { 825 nacm:default-deny-write; 827 description 828 "A container to hold SSH server configuration."; 830 container server-identity { 831 description 832 "The list of host-keys the SSH server will present when 833 establishing a SSH connection."; 834 list host-key { 835 key "name"; 836 min-elements 1; 837 ordered-by user; 838 description 839 "An ordered list of host keys the SSH server will use to 840 construct its ordered list of algorithms, when sending 841 its SSH_MSG_KEXINIT message, as defined in Section 7.1 842 of RFC 4253."; 843 reference 844 "RFC 4253: The Secure Shell (SSH) Transport Layer 845 Protocol"; 846 leaf name { 847 type string; 848 description 849 "An arbitrary name for this host-key"; 850 } 851 choice host-key-type { 852 mandatory true; 853 description 854 "The type of host key being specified"; 855 container public-key { 856 uses ks:local-or-keystore-asymmetric-key-grouping; 857 description 858 "A locally-defined or referenced asymmetric key pair 859 to be used for the SSH server's host key."; 860 reference 861 "RFC ZZZZ: YANG Data Model for a Centralized 862 Keystore Mechanism"; 863 } 864 container certificate { 865 if-feature "sshcmn:ssh-x509-certs"; 866 uses 867 ks:local-or-keystore-end-entity-cert-with-key-grouping; 868 description 869 "A locally-defined or referenced end-entity 870 certificate to be used for the SSH server's 871 host key."; 872 reference 873 "RFC ZZZZ: YANG Data Model for a Centralized 874 Keystore Mechanism"; 875 } 876 } 877 } 878 } // container server-identity 880 // FIXME: support other auth mechs too? (passwd, key, etc.) 881 container client-cert-auth { 882 if-feature "sshcmn:ssh-x509-certs"; 883 description 884 "A reference to a list of pinned certificate authority (CA) 885 certificates and a reference to a list of pinned client 886 certificates. 888 Note: password and public-key based client authentication 889 are not configured in this YANG module as they are 890 expected to be configured by the ietf-system module 891 defined in RFC 7317."; 892 reference 893 "RFC 7317: A YANG Data Model for System Management"; 894 leaf pinned-ca-certs { 895 if-feature "ta:x509-certificates"; 896 type ta:pinned-certificates-ref; 897 description 898 "A reference to a list of certificate authority (CA) 899 certificates used by the SSH server to authenticate 900 SSH client certificates. A client certificate is 901 authenticated if it has a valid chain of trust to 902 a configured pinned CA certificate."; 903 reference 904 "RFC YYYY: YANG Data Model for Global Trust Anchors"; 905 } 906 leaf pinned-client-certs { 907 if-feature "ta:x509-certificates"; 908 type ta:pinned-certificates-ref; 909 description 910 "A reference to a list of client certificates used by 911 the SSH server to authenticate SSH client certificates. 912 A clients certificate is authenticated if it is an 913 exact match to a configured pinned client certificate."; 914 reference 915 "RFC YYYY: YANG Data Model for Global Trust Anchors"; 916 } 917 } // container client-cert-auth 919 container transport-params { 920 if-feature "ssh-server-transport-params-config"; 921 description 922 "Configurable parameters of the SSH transport layer."; 923 uses sshcmn:transport-params-grouping; 924 } // container transport-params 926 container keepalives { 927 if-feature "ssh-server-keepalives"; 928 presence "Indicates that keepalives are enabled."; 929 description 930 "Configures the keep-alive policy, to proactively test 931 the aliveness of the SSL client. An unresponsive SSL 932 client is dropped after approximately max-wait * 933 max-attempts seconds."; 934 leaf max-wait { 935 type uint16 { 936 range "1..max"; 937 } 938 units "seconds"; 939 default "30"; 940 description 941 "Sets the amount of time in seconds after which 942 if no data has been received from the SSL client, 943 a SSL-level message will be sent to test the 944 aliveness of the SSL client."; 945 } 946 leaf max-attempts { 947 type uint8; 948 default "3"; 949 description 950 "Sets the maximum number of sequential keep-alive 951 messages that can fail to obtain a response from 952 the SSL client before assuming the SSL client is 953 no longer alive."; 954 } 955 } // container keepalives 956 } // container ssh-server-parameters 957 } // grouping server-identity-grouping 958 } 959 961 5. The SSH Common Model 963 The SSH common model presented in this section contains identities 964 and groupings common to both SSH clients and SSH servers. The 965 transport-params-grouping can be used to configure the list of SSH 966 transport algorithms permitted by the SSH client or SSH server. The 967 lists of algorithms are ordered such that, if multiple algorithms are 968 permitted by the client, the algorithm that appears first in its list 969 that is also permitted by the server is used for the SSH transport 970 layer connection. The ability to restrict the algorithms allowed is 971 provided in this grouping for SSH clients and SSH servers that are 972 capable of doing so and may serve to make SSH clients and SSH servers 973 compliant with security policies. 975 [I-D.ietf-netconf-crypto-types] defines six categories of 976 cryptographic algorithms (hash-algorithm, symmetric-key-encryption- 977 algorithm, mac-algorithm, asymmetric-key-encryption-algorithm, 978 signature-algorithm, key-negotiation-algorithm) and lists several 979 widely accepted algorithms for each of them. The SSH client and 980 server models use one or more of these algorithms. The SSH common 981 model includes four parameters for configuring its permitted SSH 982 algorithms, which are: host-key-alg, key-exchange-alg, encryption-alg 983 and mac-alg. The following tables are provided, in part, to define 984 the subset of algorithms defined in the crypto-types model used by 985 SSH and, in part, to ensure compatibility of configured SSH 986 cryptographic parameters for configuring its permitted SSH algorithms 987 ("sshcmn" representing SSH common model, and "ct" representing 988 crypto-types model which the SSH client/server model is based on): 990 +-------------------------------+-------------------------------+ 991 | sshcmn:host-key-alg | ct:signature-algorithm | 992 +-------------------------------+-------------------------------+ 993 | dsa-sha1 | dsa-sha1 | 994 | rsa-pkcs1-sha1 | rsa-pkcs1-sha1 | 995 | rsa-pkcs1-sha256 | rsa-pkcs1-sha256 | 996 | rsa-pkcs1-sha512 | rsa-pkcs1-sha512 | 997 | ecdsa-secp256r1-sha256 | ecdsa-secp256r1-sha256 | 998 | ecdsa-secp384r1-sha384 | ecdsa-secp384r1-sha384 | 999 | ecdsa-secp521r1-sha512 | ecdsa-secp521r1-sha512 | 1000 | x509v3-rsa-pkcs1-sha1 | x509v3-rsa-pkcs1-sha1 | 1001 | x509v3-rsa2048-pkcs1-sha256 | x509v3-rsa2048-pkcs1-sha1 | 1002 | x509v3-ecdsa-secp256r1-sha256 | x509v3-ecdsa-secp256r1-sha256 | 1003 | x509v3-ecdsa-secp384r1-sha384 | x509v3-ecdsa-secp384r1-sha384 | 1004 | x509v3-ecdsa-secp521r1-sha512 | x509v3-ecdsa-secp521r1-sha512 | 1005 +-------------------------------+-------------------------------+ 1007 Table 1 The SSH Host-key-alg Compatibility Matrix 1009 +-------------------------------+-------------------------------+ 1010 | sshcmn:key-exchange-alg | ct:key-negotiation-algorithm | 1011 +-------------------------------+-------------------------------+ 1012 | diffie-hellman-group14-sha1 | diffie-hellman-group14-sha1 | 1013 | diffie-hellman-group14-sha256 | diffie-hellman-group14-sha256 | 1014 | diffie-hellman-group15-sha512 | diffie-hellman-group15-sha512 | 1015 | diffie-hellman-group16-sha512 | diffie-hellman-group16-sha512 | 1016 | diffie-hellman-group17-sha512 | diffie-hellman-group17-sha512 | 1017 | diffie-hellman-group18-sha512 | diffie-hellman-group18-sha512 | 1018 | ecdh-sha2-secp256r1 | ecdh-sha2-secp256r1 | 1019 | ecdh-sha2-secp384r1 | ecdh-sha2-secp384r1 | 1020 +-------------------------------+-------------------------------+ 1022 Table 2 The SSH Key-exchange-alg Compatibility Matrix 1024 +-----------------------+---------------------------------------+ 1025 | sshcmn:encryption-alg | ct:symmetric-key-encryption-algorithm | 1026 +-----------------------+---------------------------------------+ 1027 | aes-128-cbc | aes-128-cbc | 1028 | aes-192-cbc | aes-192-cbc | 1029 | aes-256-cbc | aes-256-cbc | 1030 | aes-128-ctr | aes-128-ctr | 1031 | aes-192-ctr | aes-192-ctr | 1032 | aes-256-ctr | aes-256-ctr | 1033 +-----------------------+---------------------------------------+ 1035 Table 3 The SSH Encryption-alg Compatibility Matrix 1036 +----------------+-------------------+ 1037 | sshcmn:mac-alg | ct:mac-algorithm | 1038 +----------------+-------------------+ 1039 | hmac-sha1 | hmac-sha1 | 1040 | hmac-sha1-96 | hmac-sha1-96 | 1041 | hmac-sha2-256 | hmac-sha2-256 | 1042 | hmac-sha2-512 | hmac-sha2-512 | 1043 +----------------+-------------------+ 1045 Table 4 The SSH Mac-alg Compatibility Matrix 1047 As is seen in the tables above, the names of the "sshcmn" algorithms 1048 are all identical to the names of algorithms defined in 1049 [I-D.ietf-netconf-crypto-types]. While appearing to be redundant, it 1050 is important to realize that not all the algorithms defined in 1051 [I-D.ietf-netconf-crypto-types] are supported by SSH. That is, the 1052 algorithms supported by SSH are a subset of the algorithms defined in 1053 [I-D.ietf-netconf-crypto-types]. The algorithms used by SSH are 1054 redefined in this document in order to constrain the algorithms that 1055 may be selected to just the ones used by SSH. 1057 Features are defined for algorithms that are OPTIONAL or are not 1058 widely supported by popular implementations. Note that the list of 1059 algorithms is not exhaustive. As well, some algorithms that are 1060 REQUIRED by [RFC4253] are missing, notably "ssh-dss" and "diffie- 1061 hellman-group1-sha1" due to their weak security and there being 1062 alternatives that are widely supported. 1064 5.1. Tree Diagram 1066 The following tree diagram [RFC8340] provides an overview of the data 1067 model for the "ietf-ssh-common" module. 1069 module: ietf-ssh-common 1071 grouping transport-params-grouping 1072 +-- host-key 1073 | +-- host-key-alg* identityref 1074 +-- key-exchange 1075 | +-- key-exchange-alg* identityref 1076 +-- encryption 1077 | +-- encryption-alg* identityref 1078 +-- mac 1079 +-- mac-alg* identityref 1081 5.2. Example Usage 1083 This following example illustrates how the transport-params-grouping 1084 appears when populated with some data. 1086 1089 1090 algs:x509v3-rsa2048-sha256 1091 algs:ssh-rsa 1092 1093 1094 1095 algs:diffie-hellman-group-exchange-sha256 1096 1097 1098 1099 algs:aes256-ctr 1100 algs:aes192-ctr 1101 algs:aes128-ctr 1102 algs:aes256-cbc 1103 algs:aes192-cbc 1104 algs:aes128-cbc 1105 1106 1107 algs:hmac-sha2-256 1108 algs:hmac-sha2-512 1109 1110 1112 5.3. YANG Module 1114 This YANG module has normative references to [RFC4253], [RFC4344], 1115 [RFC4419], [RFC5656], [RFC6187], and [RFC6668]. 1117 file "ietf-ssh-common@2019-04-07.yang" 1118 module ietf-ssh-common { 1119 yang-version 1.1; 1120 namespace "urn:ietf:params:xml:ns:yang:ietf-ssh-common"; 1121 prefix sshcmn; 1123 organization 1124 "IETF NETCONF (Network Configuration) Working Group"; 1126 contact 1127 "WG Web: 1128 WG List: 1129 Author: Kent Watsen 1130 Author: Gary Wu "; 1132 description 1133 "This module defines a common features, identities, and 1134 groupings for Secure Shell (SSH). 1136 Copyright (c) 2019 IETF Trust and the persons identified 1137 as authors of the code. All rights reserved. 1139 Redistribution and use in source and binary forms, with 1140 or without modification, is permitted pursuant to, and 1141 subject to the license terms contained in, the Simplified 1142 BSD License set forth in Section 4.c of the IETF Trust's 1143 Legal Provisions Relating to IETF Documents 1144 (https://trustee.ietf.org/license-info). 1146 This version of this YANG module is part of RFC XXXX 1147 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC 1148 itself for full legal notices.; 1150 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1151 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 1152 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 1153 are to be interpreted as described in BCP 14 (RFC 2119) 1154 (RFC 8174) when, and only when, they appear in all 1155 capitals, as shown here."; 1157 revision 2019-04-07 { 1158 description 1159 "Initial version"; 1160 reference 1161 "RFC XXXX: YANG Groupings for SSH Clients and SSH Servers"; 1162 } 1164 // Features 1166 feature ssh-ecc { 1167 description 1168 "Elliptic Curve Cryptography is supported for SSH."; 1169 reference 1170 "RFC 5656: Elliptic Curve Algorithm Integration in the 1171 Secure Shell Transport Layer"; 1172 } 1174 feature ssh-x509-certs { 1175 description 1176 "X.509v3 certificates are supported for SSH per RFC 6187."; 1178 reference 1179 "RFC 6187: X.509v3 Certificates for Secure Shell 1180 Authentication"; 1181 } 1183 feature ssh-dh-group-exchange { 1184 description 1185 "Diffie-Hellman Group Exchange is supported for SSH."; 1186 reference 1187 "RFC 4419: Diffie-Hellman Group Exchange for the 1188 Secure Shell (SSH) Transport Layer Protocol"; 1189 } 1191 feature ssh-ctr { 1192 description 1193 "SDCTR encryption mode is supported for SSH."; 1194 reference 1195 "RFC 4344: The Secure Shell (SSH) Transport Layer 1196 Encryption Modes"; 1197 } 1199 feature ssh-sha2 { 1200 description 1201 "The SHA2 family of cryptographic hash functions is 1202 supported for SSH."; 1203 reference 1204 "FIPS PUB 180-4: Secure Hash Standard (SHS)"; 1205 } 1207 // Identities 1209 identity public-key-alg-base { 1210 description 1211 "Base identity used to identify public key algorithms."; 1212 } 1214 identity ssh-dss { 1215 base public-key-alg-base; 1216 description 1217 "Digital Signature Algorithm using SHA-1 as the 1218 hashing algorithm."; 1219 reference 1220 "RFC 4253: 1221 The Secure Shell (SSH) Transport Layer Protocol"; 1222 } 1224 identity ssh-rsa { 1225 base public-key-alg-base; 1226 description 1227 "RSASSA-PKCS1-v1_5 signature scheme using SHA-1 as the 1228 hashing algorithm."; 1229 reference 1230 "RFC 4253: 1231 The Secure Shell (SSH) Transport Layer Protocol"; 1232 } 1234 identity ecdsa-sha2-nistp256 { 1235 base public-key-alg-base; 1236 if-feature "ssh-ecc and ssh-sha2"; 1237 description 1238 "Elliptic Curve Digital Signature Algorithm (ECDSA) using the 1239 nistp256 curve and the SHA2 family of hashing algorithms."; 1240 reference 1241 "RFC 5656: Elliptic Curve Algorithm Integration in the 1242 Secure Shell Transport Layer"; 1243 } 1245 identity ecdsa-sha2-nistp384 { 1246 base public-key-alg-base; 1247 if-feature "ssh-ecc and ssh-sha2"; 1248 description 1249 "Elliptic Curve Digital Signature Algorithm (ECDSA) using the 1250 nistp384 curve and the SHA2 family of hashing algorithms."; 1251 reference 1252 "RFC 5656: Elliptic Curve Algorithm Integration in the 1253 Secure Shell Transport Layer"; 1254 } 1256 identity ecdsa-sha2-nistp521 { 1257 base public-key-alg-base; 1258 if-feature "ssh-ecc and ssh-sha2"; 1259 description 1260 "Elliptic Curve Digital Signature Algorithm (ECDSA) using the 1261 nistp521 curve and the SHA2 family of hashing algorithms."; 1262 reference 1263 "RFC 5656: Elliptic Curve Algorithm Integration in the 1264 Secure Shell Transport Layer"; 1265 } 1267 identity x509v3-ssh-rsa { 1268 base public-key-alg-base; 1269 if-feature "ssh-x509-certs"; 1270 description 1271 "RSASSA-PKCS1-v1_5 signature scheme using a public key stored 1272 in an X.509v3 certificate and using SHA-1 as the hashing 1273 algorithm."; 1275 reference 1276 "RFC 6187: X.509v3 Certificates for Secure Shell 1277 Authentication"; 1278 } 1280 identity x509v3-rsa2048-sha256 { 1281 base public-key-alg-base; 1282 if-feature "ssh-x509-certs and ssh-sha2"; 1283 description 1284 "RSASSA-PKCS1-v1_5 signature scheme using a public key stored 1285 in an X.509v3 certificate and using SHA-256 as the hashing 1286 algorithm. RSA keys conveyed using this format MUST have a 1287 modulus of at least 2048 bits."; 1288 reference 1289 "RFC 6187: X.509v3 Certificates for Secure Shell 1290 Authentication"; 1291 } 1293 identity x509v3-ecdsa-sha2-nistp256 { 1294 base public-key-alg-base; 1295 if-feature "ssh-ecc and ssh-x509-certs and ssh-sha2"; 1296 description 1297 "Elliptic Curve Digital Signature Algorithm (ECDSA) 1298 using the nistp256 curve with a public key stored in 1299 an X.509v3 certificate and using the SHA2 family of 1300 hashing algorithms."; 1301 reference 1302 "RFC 6187: X.509v3 Certificates for Secure Shell 1303 Authentication"; 1304 } 1306 identity x509v3-ecdsa-sha2-nistp384 { 1307 base public-key-alg-base; 1308 if-feature "ssh-ecc and ssh-x509-certs and ssh-sha2"; 1309 description 1310 "Elliptic Curve Digital Signature Algorithm (ECDSA) 1311 using the nistp384 curve with a public key stored in 1312 an X.509v3 certificate and using the SHA2 family of 1313 hashing algorithms."; 1314 reference 1315 "RFC 6187: X.509v3 Certificates for Secure Shell 1316 Authentication"; 1317 } 1319 identity x509v3-ecdsa-sha2-nistp521 { 1320 base public-key-alg-base; 1321 if-feature "ssh-ecc and ssh-x509-certs and ssh-sha2"; 1322 description 1323 "Elliptic Curve Digital Signature Algorithm (ECDSA) 1324 using the nistp521 curve with a public key stored in 1325 an X.509v3 certificate and using the SHA2 family of 1326 hashing algorithms."; 1327 reference 1328 "RFC 6187: X.509v3 Certificates for Secure Shell 1329 Authentication"; 1330 } 1332 identity key-exchange-alg-base { 1333 description 1334 "Base identity used to identify key exchange algorithms."; 1335 } 1337 identity diffie-hellman-group14-sha1 { 1338 base key-exchange-alg-base; 1339 description 1340 "Diffie-Hellman key exchange with SHA-1 as HASH and 1341 Oakley Group 14 (2048-bit MODP Group)."; 1342 reference 1343 "RFC 4253: The Secure Shell (SSH) Transport Layer Protocol"; 1344 } 1346 identity diffie-hellman-group-exchange-sha1 { 1347 base key-exchange-alg-base; 1348 if-feature "ssh-dh-group-exchange"; 1349 description 1350 "Diffie-Hellman Group and Key Exchange with SHA-1 as HASH."; 1351 reference 1352 "RFC 4419: Diffie-Hellman Group Exchange for the 1353 Secure Shell (SSH) Transport Layer Protocol"; 1354 } 1356 identity diffie-hellman-group-exchange-sha256 { 1357 base key-exchange-alg-base; 1358 if-feature "ssh-dh-group-exchange and ssh-sha2"; 1359 description 1360 "Diffie-Hellman Group and Key Exchange with SHA-256 as HASH."; 1361 reference 1362 "RFC 4419: Diffie-Hellman Group Exchange for the 1363 Secure Shell (SSH) Transport Layer Protocol"; 1364 } 1366 identity ecdh-sha2-nistp256 { 1367 base key-exchange-alg-base; 1368 if-feature "ssh-ecc and ssh-sha2"; 1369 description 1370 "Elliptic Curve Diffie-Hellman (ECDH) key exchange using the 1371 nistp256 curve and the SHA2 family of hashing algorithms."; 1372 reference 1373 "RFC 5656: Elliptic Curve Algorithm Integration in the 1374 Secure Shell Transport Layer"; 1375 } 1377 identity ecdh-sha2-nistp384 { 1378 base key-exchange-alg-base; 1379 if-feature "ssh-ecc and ssh-sha2"; 1380 description 1381 "Elliptic Curve Diffie-Hellman (ECDH) key exchange using the 1382 nistp384 curve and the SHA2 family of hashing algorithms."; 1383 reference 1384 "RFC 5656: Elliptic Curve Algorithm Integration in the 1385 Secure Shell Transport Layer"; 1386 } 1388 identity ecdh-sha2-nistp521 { 1389 base key-exchange-alg-base; 1390 if-feature "ssh-ecc and ssh-sha2"; 1391 description 1392 "Elliptic Curve Diffie-Hellman (ECDH) key exchange using the 1393 nistp521 curve and the SHA2 family of hashing algorithms."; 1394 reference 1395 "RFC 5656: Elliptic Curve Algorithm Integration in the 1396 Secure Shell Transport Layer"; 1397 } 1399 identity encryption-alg-base { 1400 description 1401 "Base identity used to identify encryption algorithms."; 1402 } 1404 identity triple-des-cbc { 1405 base encryption-alg-base; 1406 description 1407 "Three-key 3DES in CBC mode."; 1408 reference 1409 "RFC 4253: The Secure Shell (SSH) Transport Layer Protocol"; 1410 } 1412 identity aes128-cbc { 1413 base encryption-alg-base; 1414 description 1415 "AES in CBC mode, with a 128-bit key."; 1416 reference 1417 "RFC 4253: The Secure Shell (SSH) Transport Layer Protocol"; 1418 } 1419 identity aes192-cbc { 1420 base encryption-alg-base; 1421 description 1422 "AES in CBC mode, with a 192-bit key."; 1423 reference 1424 "RFC 4253: The Secure Shell (SSH) Transport Layer Protocol"; 1425 } 1427 identity aes256-cbc { 1428 base encryption-alg-base; 1429 description 1430 "AES in CBC mode, with a 256-bit key."; 1431 reference 1432 "RFC 4253: The Secure Shell (SSH) Transport Layer Protocol"; 1433 } 1435 identity aes128-ctr { 1436 base encryption-alg-base; 1437 if-feature "ssh-ctr"; 1438 description 1439 "AES in SDCTR mode, with 128-bit key."; 1440 reference 1441 "RFC 4344: The Secure Shell (SSH) Transport Layer Encryption 1442 Modes"; 1443 } 1445 identity aes192-ctr { 1446 base encryption-alg-base; 1447 if-feature "ssh-ctr"; 1448 description 1449 "AES in SDCTR mode, with 192-bit key."; 1450 reference 1451 "RFC 4344: The Secure Shell (SSH) Transport Layer Encryption 1452 Modes"; 1453 } 1455 identity aes256-ctr { 1456 base encryption-alg-base; 1457 if-feature "ssh-ctr"; 1458 description 1459 "AES in SDCTR mode, with 256-bit key."; 1460 reference 1461 "RFC 4344: The Secure Shell (SSH) Transport Layer Encryption 1462 Modes"; 1463 } 1465 identity mac-alg-base { 1466 description 1467 "Base identity used to identify message authentication 1468 code (MAC) algorithms."; 1469 } 1471 identity hmac-sha1 { 1472 base mac-alg-base; 1473 description 1474 "HMAC-SHA1"; 1475 reference 1476 "RFC 4253: The Secure Shell (SSH) Transport Layer Protocol"; 1477 } 1479 identity hmac-sha2-256 { 1480 base mac-alg-base; 1481 if-feature "ssh-sha2"; 1482 description 1483 "HMAC-SHA2-256"; 1484 reference 1485 "RFC 6668: SHA-2 Data Integrity Verification for the 1486 Secure Shell (SSH) Transport Layer Protocol"; 1487 } 1489 identity hmac-sha2-512 { 1490 base mac-alg-base; 1491 if-feature "ssh-sha2"; 1492 description 1493 "HMAC-SHA2-512"; 1494 reference 1495 "RFC 6668: SHA-2 Data Integrity Verification for the 1496 Secure Shell (SSH) Transport Layer Protocol"; 1497 } 1499 // Groupings 1501 grouping transport-params-grouping { 1502 description 1503 "A reusable grouping for SSH transport parameters."; 1504 reference 1505 "RFC 4253: The Secure Shell (SSH) Transport Layer Protocol"; 1506 container host-key { 1507 description 1508 "Parameters regarding host key."; 1509 leaf-list host-key-alg { 1510 type identityref { 1511 base public-key-alg-base; 1512 } 1513 ordered-by user; 1514 description 1515 "Acceptable host key algorithms in order of descending 1516 preference. The configured host key algorithms should 1517 be compatible with the algorithm used by the configured 1518 private key. Please see Section 5 of RFC XXXX for 1519 valid combinations. 1521 If this leaf-list is not configured (has zero elements) 1522 the acceptable host key algorithms are implementation- 1523 defined."; 1524 reference 1525 "RFC XXXX: YANG Groupings for SSH Clients and SSH Servers"; 1526 } 1527 } 1528 container key-exchange { 1529 description 1530 "Parameters regarding key exchange."; 1531 leaf-list key-exchange-alg { 1532 type identityref { 1533 base key-exchange-alg-base; 1534 } 1535 ordered-by user; 1536 description 1537 "Acceptable key exchange algorithms in order of descending 1538 preference. 1540 If this leaf-list is not configured (has zero elements) 1541 the acceptable key exchange algorithms are implementation 1542 defined."; 1543 } 1544 } 1545 container encryption { 1546 description 1547 "Parameters regarding encryption."; 1548 leaf-list encryption-alg { 1549 type identityref { 1550 base encryption-alg-base; 1551 } 1552 ordered-by user; 1553 description 1554 "Acceptable encryption algorithms in order of descending 1555 preference. 1557 If this leaf-list is not configured (has zero elements) 1558 the acceptable encryption algorithms are implementation 1559 defined."; 1560 } 1561 } 1562 container mac { 1563 description 1564 "Parameters regarding message authentication code (MAC)."; 1565 leaf-list mac-alg { 1566 type identityref { 1567 base mac-alg-base; 1568 } 1569 ordered-by user; 1570 description 1571 "Acceptable MAC algorithms in order of descending 1572 preference. 1574 If this leaf-list is not configured (has zero elements) 1575 the acceptable MAC algorithms are implementation- 1576 defined."; 1577 } 1578 } 1579 } 1580 } 1581 1583 6. Security Considerations 1585 The YANG modules defined in this document are designed to be accessed 1586 via YANG based management protocols, such as NETCONF [RFC6241] and 1587 RESTCONF [RFC8040]. Both of these protocols have mandatory-to- 1588 implement secure transport layers (e.g., SSH, TLS) with mutual 1589 authentication. 1591 The NETCONF access control model (NACM) [RFC8341] provides the means 1592 to restrict access for particular users to a pre-configured subset of 1593 all available protocol operations and content. 1595 Since the modules in this document only define groupings, these 1596 considerations are primarily for the designers of other modules that 1597 use these groupings. 1599 There are a number of data nodes defined in the YANG modules that are 1600 writable/creatable/deletable (i.e., config true, which is the 1601 default). These data nodes may be considered sensitive or vulnerable 1602 in some network environments. Write operations (e.g., edit-config) 1603 to these data nodes without proper protection can have a negative 1604 effect on network operations. These are the subtrees and data nodes 1605 and their sensitivity/vulnerability: 1607 *: The entire subtree defined by the grouping statement in both 1608 the "ietf-ssh-client" and "ietf-ssh-server" modules is 1609 sensitive to write operations. For instance, the addition or 1610 removal of references to keys, certificates, trusted anchors, 1611 etc., or even the modification of transport or keepalive 1612 parameters can dramatically alter the implemented security 1613 policy. For this reason, this node is protected the NACM 1614 extension "default-deny-write". 1616 Some of the readable data nodes in the YANG modules may be considered 1617 sensitive or vulnerable in some network environments. It is thus 1618 important to control read access (e.g., via get, get-config, or 1619 notification) to these data nodes. These are the subtrees and data 1620 nodes and their sensitivity/vulnerability: 1622 /ssh-client-parameters/client-identity/: This subtree in the 1623 "ietf-ssh-client" module contains nodes that are additionally 1624 sensitive to read operations such that, in normal use cases, 1625 they should never be returned to a client. Some of these nodes 1626 (i.e., public-key/local-definition/private-key and certificate/ 1627 local-definition/private-key) are already protected by the NACM 1628 extension "default-deny-all" set in the "grouping" statements 1629 defined in [I-D.ietf-netconf-crypto-types]. However, since the 1630 "password" node is defined in this module, the NACM extension 1631 "default-deny-all" has been applied it here. 1633 /ssh-server-parameters/server-identity/: This subtree in the 1634 "ietf-ssh-server" module contains nodes that are additionally 1635 sensitive to read operations such that, in normal use cases, 1636 they should never be returned to a client. All of these nodes 1637 (i.e., host-key/public-key/local-definition/private-key and 1638 host-key/certificate/local-definition/private-key) are already 1639 protected by the NACM extension "default-deny-all" set in the 1640 "grouping" statements defined in 1641 [I-D.ietf-netconf-crypto-types]. 1643 Some of the operations in this YANG module may be considered 1644 sensitive or vulnerable in some network environments. It is thus 1645 important to control access to these operations. These are the 1646 operations and their sensitivity/vulnerability: 1648 *: The groupings defined in this document include "action" 1649 statements that come from groupings defined in 1650 [I-D.ietf-netconf-crypto-types]. Please consult that document 1651 for the security considerations of the "action" statements 1652 defined by the "grouping" statements defined in this document. 1654 7. IANA Considerations 1655 7.1. The IETF XML Registry 1657 This document registers three URIs in the "ns" subregistry of the 1658 IETF XML Registry [RFC3688]. Following the format in [RFC3688], the 1659 following registrations are requested: 1661 URI: urn:ietf:params:xml:ns:yang:ietf-ssh-client 1662 Registrant Contact: The NETCONF WG of the IETF. 1663 XML: N/A, the requested URI is an XML namespace. 1665 URI: urn:ietf:params:xml:ns:yang:ietf-ssh-server 1666 Registrant Contact: The NETCONF WG of the IETF. 1667 XML: N/A, the requested URI is an XML namespace. 1669 URI: urn:ietf:params:xml:ns:yang:ietf-ssh-common 1670 Registrant Contact: The NETCONF WG of the IETF. 1671 XML: N/A, the requested URI is an XML namespace. 1673 7.2. The YANG Module Names Registry 1675 This document registers three YANG modules in the YANG Module Names 1676 registry [RFC6020]. Following the format in [RFC6020], the following 1677 registrations are requested: 1679 name: ietf-ssh-client 1680 namespace: urn:ietf:params:xml:ns:yang:ietf-ssh-client 1681 prefix: sshc 1682 reference: RFC XXXX 1684 name: ietf-ssh-server 1685 namespace: urn:ietf:params:xml:ns:yang:ietf-ssh-server 1686 prefix: sshs 1687 reference: RFC XXXX 1689 name: ietf-ssh-common 1690 namespace: urn:ietf:params:xml:ns:yang:ietf-ssh-common 1691 prefix: sshcmn 1692 reference: RFC XXXX 1694 8. References 1696 8.1. Normative References 1698 [I-D.ietf-netconf-crypto-types] 1699 Watsen, K. and H. Wang, "Common YANG Data Types for 1700 Cryptography", draft-ietf-netconf-crypto-types-05 (work in 1701 progress), March 2019. 1703 [I-D.ietf-netconf-keystore] 1704 Watsen, K., "YANG Data Model for a Centralized Keystore 1705 Mechanism", draft-ietf-netconf-keystore-08 (work in 1706 progress), March 2019. 1708 [I-D.ietf-netconf-trust-anchors] 1709 Watsen, K., "YANG Data Model for Global Trust Anchors", 1710 draft-ietf-netconf-trust-anchors-03 (work in progress), 1711 March 2019. 1713 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1714 Requirement Levels", BCP 14, RFC 2119, 1715 DOI 10.17487/RFC2119, March 1997, 1716 . 1718 [RFC4344] Bellare, M., Kohno, T., and C. Namprempre, "The Secure 1719 Shell (SSH) Transport Layer Encryption Modes", RFC 4344, 1720 DOI 10.17487/RFC4344, January 2006, 1721 . 1723 [RFC4419] Friedl, M., Provos, N., and W. Simpson, "Diffie-Hellman 1724 Group Exchange for the Secure Shell (SSH) Transport Layer 1725 Protocol", RFC 4419, DOI 10.17487/RFC4419, March 2006, 1726 . 1728 [RFC5656] Stebila, D. and J. Green, "Elliptic Curve Algorithm 1729 Integration in the Secure Shell Transport Layer", 1730 RFC 5656, DOI 10.17487/RFC5656, December 2009, 1731 . 1733 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1734 the Network Configuration Protocol (NETCONF)", RFC 6020, 1735 DOI 10.17487/RFC6020, October 2010, 1736 . 1738 [RFC6187] Igoe, K. and D. Stebila, "X.509v3 Certificates for Secure 1739 Shell Authentication", RFC 6187, DOI 10.17487/RFC6187, 1740 March 2011, . 1742 [RFC6668] Bider, D. and M. Baushke, "SHA-2 Data Integrity 1743 Verification for the Secure Shell (SSH) Transport Layer 1744 Protocol", RFC 6668, DOI 10.17487/RFC6668, July 2012, 1745 . 1747 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1748 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1749 . 1751 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1752 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1753 May 2017, . 1755 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 1756 Access Control Model", STD 91, RFC 8341, 1757 DOI 10.17487/RFC8341, March 2018, 1758 . 1760 8.2. Informative References 1762 [OPENSSH] Project, T. O., "OpenSSH", 2016, . 1764 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1765 DOI 10.17487/RFC3688, January 2004, 1766 . 1768 [RFC4252] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) 1769 Authentication Protocol", RFC 4252, DOI 10.17487/RFC4252, 1770 January 2006, . 1772 [RFC4253] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) 1773 Transport Layer Protocol", RFC 4253, DOI 10.17487/RFC4253, 1774 January 2006, . 1776 [RFC4254] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) 1777 Connection Protocol", RFC 4254, DOI 10.17487/RFC4254, 1778 January 2006, . 1780 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1781 and A. Bierman, Ed., "Network Configuration Protocol 1782 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1783 . 1785 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 1786 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 1787 . 1789 [RFC7317] Bierman, A. and M. Bjorklund, "A YANG Data Model for 1790 System Management", RFC 7317, DOI 10.17487/RFC7317, August 1791 2014, . 1793 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1794 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1795 . 1797 [RFC8071] Watsen, K., "NETCONF Call Home and RESTCONF Call Home", 1798 RFC 8071, DOI 10.17487/RFC8071, February 2017, 1799 . 1801 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 1802 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 1803 . 1805 Appendix A. Change Log 1807 A.1. 00 to 01 1809 o Noted that '0.0.0.0' and '::' might have special meanings. 1811 o Renamed "keychain" to "keystore". 1813 A.2. 01 to 02 1815 o Removed the groupings 'listening-ssh-client-grouping' and 1816 'listening-ssh-server-grouping'. Now modules only contain the 1817 transport-independent groupings. 1819 o Simplified the "client-auth" part in the ietf-ssh-client module. 1820 It now inlines what it used to point to keystore for. 1822 o Added cipher suites for various algorithms into new 'ietf-ssh- 1823 common' module. 1825 A.3. 02 to 03 1827 o Removed 'RESTRICTED' enum from 'password' leaf type. 1829 o Added a 'must' statement to container 'server-auth' asserting that 1830 at least one of the various auth mechanisms must be specified. 1832 o Fixed description statement for leaf 'trusted-ca-certs'. 1834 A.4. 03 to 04 1836 o Change title to "YANG Groupings for SSH Clients and SSH Servers" 1838 o Added reference to RFC 6668 1840 o Added RFC 8174 to Requirements Language Section. 1842 o Enhanced description statement for ietf-ssh-server's "trusted-ca- 1843 certs" leaf. 1845 o Added mandatory true to ietf-ssh-client's "client-auth" 'choice' 1846 statement. 1848 o Changed the YANG prefix for module ietf-ssh-common from 'sshcom' 1849 to 'sshcmn'. 1851 o Removed the compression algorithms as they are not commonly 1852 configurable in vendors' implementations. 1854 o Updating descriptions in transport-params-grouping and the 1855 servers's usage of it. 1857 o Now tree diagrams reference ietf-netmod-yang-tree-diagrams 1859 o Updated YANG to use typedefs around leafrefs to common keystore 1860 paths 1862 o Now inlines key and certificates (no longer a leafref to keystore) 1864 A.5. 04 to 05 1866 o Merged changes from co-author. 1868 A.6. 05 to 06 1870 o Updated to use trust anchors from trust-anchors draft (was 1871 keystore draft) 1873 o Now uses new keystore grouping enabling asymmetric key to be 1874 either locally defined or a reference to the keystore. 1876 A.7. 06 to 07 1878 o factored the ssh-[client|server]-groupings into more reusable 1879 groupings. 1881 o added if-feature statements for the new "ssh-host-keys" and 1882 "x509-certificates" features defined in draft-ietf-netconf-trust- 1883 anchors. 1885 A.8. 07 to 08 1887 o Added a number of compatibility matrices to Section 5 (thanks 1888 Frank!) 1890 o Clarified that any configured "host-key-alg" values need to be 1891 compatible with the configured private key. 1893 A.9. 08 to 09 1895 o Updated examples to reflect update to groupings defined in the 1896 keystore -09 draft. 1898 o Add SSH keepalives features and groupings. 1900 o Prefixed top-level SSH grouping nodes with 'ssh-' and support 1901 mashups. 1903 o Updated copyright date, boilerplate template, affiliation, and 1904 folding algorithm. 1906 A.10. 09 to 10 1908 o Reformatted the YANG modules. 1910 A.11. 10 to 11 1912 o Reformatted lines causing folding to occur. 1914 A.12. 11 to 12 1916 o Collapsed all the inner groupings into the top-level grouping. 1918 o Added a top-level "demux container" inside the top-level grouping. 1920 o Added NACM statements and updated the Security Considerations 1921 section. 1923 o Added "presence" statements on the "keepalive" containers, as was 1924 needed to address a validation error that appeared after adding 1925 the "must" statements into the NETCONF/RESTCONF client/server 1926 modules. 1928 o Updated the boilerplate text in module-level "description" 1929 statement to match copyeditor convention. 1931 Acknowledgements 1933 The authors would like to thank for following for lively discussions 1934 on list and in the halls (ordered by last name): Andy Bierman, Martin 1935 Bjorklund, Benoit Claise, Mehmet Ersue, Balazs Kovacs, David 1936 Lamparter, Alan Luchuk, Ladislav Lhotka, Radek Krejci, Tom Petch, 1937 Juergen Schoenwaelder, Phil Shafer, Sean Turner, Michal Vasko, and 1938 Bert Wijnen. 1940 Authors' Addresses 1942 Kent Watsen 1943 Watsen Networks 1945 EMail: kent+ietf@watsen.net 1946 Gary Wu 1947 Cisco Systems 1949 EMail: garywu@cisco.com 1951 Liang Xia 1952 Huawei 1954 EMail: frank.xialiang@huawei.com