idnits 2.17.1 draft-ietf-netconf-ssh-client-server-10.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 (March 9, 2019) is 1873 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-02 == 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: September 10, 2019 Cisco Systems 6 L. Xia 7 Huawei 8 March 9, 2019 10 YANG Groupings for SSH Clients and SSH Servers 11 draft-ietf-netconf-ssh-client-server-10 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-03-09" --> 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 September 10, 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 . . . . . . . . . . . . . . . . . . . . . . 14 99 4.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 17 100 5. The SSH Common Model . . . . . . . . . . . . . . . . . . . . 22 101 5.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 24 102 5.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 25 103 5.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 25 104 6. Security Considerations . . . . . . . . . . . . . . . . . . . 35 105 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 36 106 7.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 36 107 7.2. The YANG Module Names Registry . . . . . . . . . . . . . 37 108 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 37 109 8.1. Normative References . . . . . . . . . . . . . . . . . . 37 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 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 42 123 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 42 125 1. Introduction 127 This document defines three YANG 1.1 [RFC7950] modules: the first 128 defines a grouping for a generic SSH client, the second defines a 129 grouping for a generic SSH server, and the third defines identities 130 and groupings common to both the client and the server. It is 131 intended that these groupings will be used by applications using the 132 SSH protocol [RFC4252], [RFC4253], and [RFC4254]. For instance, 133 these groupings could be used to help define the data model for an 134 OpenSSH [OPENSSH] server or a NETCONF over SSH [RFC6242] based 135 server. 137 The client and server YANG modules in this document each define one 138 grouping, which is focused on just SSH-specific configuration, and 139 specifically avoids any transport-level configuration, such as what 140 ports to listen on or connect to. This affords applications the 141 opportunity to define their own strategy for how the underlying TCP 142 connection is established. For instance, applications supporting 143 NETCONF Call Home [RFC8071] could use the "ssh-server-grouping" 144 grouping for the SSH parts it provides, while adding data nodes for 145 the TCP-level call-home configuration. 147 The modules defined in this document use groupings defined in 148 [I-D.ietf-netconf-keystore] enabling keys to be either locally 149 defined or a reference to globally configured values. 151 The modules defined in this document optionally support [RFC6187] 152 enabling X.509v3 certificate based host keys and public keys. 154 2. Terminology 156 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 157 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 158 "OPTIONAL" in this document are to be interpreted as described in BCP 159 14 [RFC2119] [RFC8174] when, and only when, they appear in all 160 capitals, as shown here. 162 3. The SSH Client Model 164 3.1. Tree Diagram 166 This section provides a tree diagram [RFC8340] for the "ietf-ssh- 167 client" module that does not have groupings expanded. 169 module: ietf-ssh-client 171 grouping ssh-client-grouping 172 +---u client-identity-grouping 173 +---u server-auth-grouping 174 +---u transport-params-grouping 175 +---u keepalives-grouping 176 grouping client-identity-grouping 177 +-- ssh-client-identity 178 +-- username? string 179 +-- (auth-type) 180 +--:(password) 181 | +-- password? string 182 +--:(public-key) 183 | +-- public-key 184 | +---u client-identity-grouping 185 +--:(certificate) 186 +-- certificate {sshcmn:ssh-x509-certs}? 187 +---u client-identity-grouping 188 grouping server-auth-grouping 189 +-- ssh-server-auth 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 grouping transport-params-grouping 197 +-- ssh-transport-params {ssh-client-transport-params-config}? 198 +---u transport-params-grouping 199 grouping keepalives-grouping 200 +-- ssh-keepalives {ssh-client-keepalives}? 201 +-- max-wait? uint16 202 +-- max-attempts? uint8 204 3.2. Example Usage 206 This section presents two examples showing the ssh-client-grouping 207 populated with some data. These examples are effectively the same 208 except the first configures the client identity using a local key 209 while the second uses a key configured in a keystore. Both examples 210 are consistent with the examples presented in Section 3 of 211 [I-D.ietf-netconf-trust-anchors] and Section 3.2 of 212 [I-D.ietf-netconf-keystore]. 214 The following example configures the client identity using a local 215 key: 217 ========== NOTE: '\\' line wrapping per BCP XX (RFC XXXX) =========== 219 223 224 225 foobar 226 227 228 ct:rsa2048 230 base64encodedvalue== 231 base64encodedvalue== 232 233 234 236 237 238 explicitly-trusted-ssh-host-keys 240 242 243 244 algs:ssh-rsa 245 246 247 248 algs:diffie-hellman-group-exchange-sha256 249 250 251 252 algs:aes256-ctr 253 algs:aes192-ctr 254 algs:aes128-ctr 255 algs:aes256-cbc 256 algs:aes192-cbc 257 algs:aes128-cbc 258 259 260 algs:hmac-sha2-256 261 algs:hmac-sha2-512 262 263 264 265 30 266 3 267 269 271 The following example configures the client identity using a key from 272 the keystore: 274 ========== NOTE: '\\' line wrapping per BCP XX (RFC XXXX) =========== 276 280 281 282 foobar 283 284 ex-rsa-key 285 286 288 289 290 explicitly-trusted-ssh-host-keys 292 294 295 296 algs:ssh-rsa 297 298 299 300 algs:diffie-hellman-group-exchange-sha256 301 302 303 304 algs:aes256-ctr 305 algs:aes192-ctr 306 algs:aes128-ctr 307 algs:aes256-cbc 308 algs:aes192-cbc 309 algs:aes128-cbc 310 311 312 algs:hmac-sha2-256 313 algs:hmac-sha2-512 314 315 317 318 30 319 3 320 322 324 3.3. YANG Module 326 This YANG module has normative references to 327 [I-D.ietf-netconf-trust-anchors], and [I-D.ietf-netconf-keystore]. 329 file "ietf-ssh-client@2019-03-09.yang" 330 module ietf-ssh-client { 331 yang-version 1.1; 332 namespace "urn:ietf:params:xml:ns:yang:ietf-ssh-client"; 333 prefix sshc; 335 import ietf-ssh-common { 336 prefix sshcmn; 337 revision-date 2019-03-09; // stable grouping definitions 338 reference 339 "RFC XXXX: YANG Groupings for SSH Clients and SSH Servers"; 340 } 342 import ietf-trust-anchors { 343 prefix ta; 344 reference 345 "RFC YYYY: YANG Data Model for Global Trust Anchors"; 346 } 348 import ietf-keystore { 349 prefix ks; 350 reference 351 "RFC ZZZZ: 352 YANG Data Model for a Centralized Keystore Mechanism"; 353 } 355 organization 356 "IETF NETCONF (Network Configuration) Working Group"; 358 contact 359 "WG Web: 360 WG List: 361 Author: Kent Watsen 362 Author: Gary Wu "; 364 description 365 "This module defines reusable groupings for SSH clients that 366 can be used as a basis for specific SSH client instances. 368 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 369 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 370 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 371 are to be interpreted as described in BCP 14 [RFC2119] 372 [RFC8174] when, and only when, they appear in all 373 capitals, as shown here. 375 Copyright (c) 2019 IETF Trust and the persons identified as 376 authors of the code. All rights reserved. 378 Redistribution and use in source and binary forms, with or 379 without modification, is permitted pursuant to, and subject 380 to the license terms contained in, the Simplified BSD 381 License set forth in Section 4.c of the IETF Trust's 382 Legal Provisions Relating to IETF Documents 383 (http://trustee.ietf.org/license-info). 385 This version of this YANG module is part of RFC XXXX; see 386 the RFC itself for full legal notices."; 388 revision 2019-03-09 { 389 description 390 "Initial version"; 391 reference 392 "RFC XXXX: YANG Groupings for SSH Clients and SSH Servers"; 393 } 395 // Features 397 feature ssh-client-transport-params-config { 398 description 399 "SSH transport layer parameters are configurable on an SSH 400 client."; 401 } 403 feature ssh-client-keepalives { 404 description 405 "Per socket SSH keepalive parameters are configurable for 406 SSH clients on the server implementing this feature."; 407 } 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."; 415 uses client-identity-grouping; 416 uses server-auth-grouping; 417 uses transport-params-grouping; 418 uses keepalives-grouping; 419 } 421 grouping client-identity-grouping { 422 description 423 "A reusable grouping for configuring a SSH client identity."; 424 container ssh-client-identity { 425 description 426 "The credentials used by the client to authenticate to 427 the SSH server."; 428 leaf username { 429 type string; 430 description 431 "The username of this user. This will be the username 432 used, for instance, to log into an SSH server."; 433 } 434 choice auth-type { 435 mandatory true; 436 description 437 "The authentication type."; 438 leaf password { 439 type string; 440 description 441 "A password to be used for client authentication."; 442 } 443 container public-key { 444 uses ks:local-or-keystore-asymmetric-key-grouping; 445 description 446 "A locally-defined or referenced asymmetric key pair 447 to be used for client authentication."; 448 reference 449 "RFC ZZZZ: 450 YANG Data Model for a Centralized Keystore Mechanism"; 451 } 452 container certificate { 453 if-feature "sshcmn:ssh-x509-certs"; 454 uses ks:local-or-keystore-end-entity-cert-with-key-grouping; 455 description 456 "A locally-defined or referenced certificate 457 to be used for client authentication."; 458 reference 459 "RFC ZZZZ 460 YANG Data Model for a Centralized Keystore Mechanism"; 461 } 462 } 463 } 464 } 466 grouping server-auth-grouping { 467 description 468 "A reusable grouping for configuring SSH server 469 authentication."; 470 container ssh-server-auth { 471 must 'pinned-ssh-host-keys or pinned-ca-certs or ' 472 + 'pinned-server-certs'; 473 description 474 "Trusted server identities."; 475 leaf pinned-ssh-host-keys { 476 if-feature "ta:ssh-host-keys"; 477 type ta:pinned-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 exact 482 match to a configured SSH host key."; 483 reference 484 "RFC YYYY: YANG Data Model for Global Trust Anchors"; 485 } 486 leaf pinned-ca-certs { 487 if-feature "sshcmn:ssh-x509-certs"; 488 if-feature "ta:x509-certificates"; 489 type ta:pinned-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 } 500 leaf pinned-server-certs { 501 if-feature "sshcmn:ssh-x509-certs"; 502 if-feature "ta:x509-certificates"; 503 type ta:pinned-certificates-ref; 504 description 505 "A reference to a list of server certificates used by 506 the SSH client to authenticate SSH server certificates. 507 A server certificate is authenticated if it is an 508 exact match to a configured server certificate."; 509 reference 510 "RFC YYYY: YANG Data Model for Global Trust Anchors"; 511 } 512 } 513 } 515 grouping transport-params-grouping { 516 description 517 "A reusable grouping for configuring a SSH transport 518 parameters."; 519 container ssh-transport-params { 520 if-feature "ssh-client-transport-params-config"; 521 description 522 "Configurable parameters of the SSH transport layer."; 523 uses sshcmn:transport-params-grouping; 524 } 525 } 527 grouping keepalives-grouping { 528 description 529 "A reusable grouping for configuring SSH client keepalive 530 parameters."; 531 container ssh-keepalives { 532 if-feature "ssh-client-keepalives"; 533 description 534 "Configures the keep-alive policy, to proactively test the 535 aliveness of the SSH server. An unresponsive TLS server is 536 dropped after approximately max-wait * max-attempts seconds."; 537 leaf max-wait { 538 type uint16 { 539 range "1..max"; 540 } 541 units "seconds"; 542 default "30"; 543 description 544 "Sets the amount of time in seconds after which if no data 545 has been received from the SSH server, a TLS-level message 546 will be sent to test the aliveness of the SSH server."; 547 } 548 leaf max-attempts { 549 type uint8; 550 default "3"; 551 description 552 "Sets the maximum number of sequential keep-alive messages 553 that can fail to obtain a response from the SSH server 554 before assuming the SSH server is no longer alive."; 555 } 556 } 557 } 558 } 559 561 4. The SSH Server Model 563 4.1. Tree Diagram 565 This section provides a tree diagram [RFC8340] for the "ietf-ssh- 566 server" module that does not have groupings expanded. 568 module: ietf-ssh-server 570 grouping ssh-server-grouping 571 +---u server-identity-grouping 572 +---u client-auth-grouping 573 +---u transport-params-grouping 574 +---u keepalives-grouping 575 grouping server-identity-grouping 576 +-- ssh-server-identity 577 +-- host-key* [name] 578 +-- name? string 579 +-- (host-key-type) 580 +--:(public-key) 581 | +-- public-key 582 | +---u server-identity-grouping 583 +--:(certificate) 584 +-- certificate {sshcmn:ssh-x509-certs}? 585 +---u server-identity-grouping 586 grouping client-auth-grouping 587 +-- ssh-client-cert-auth {sshcmn:ssh-x509-certs}? 588 +-- pinned-ca-certs? ta:pinned-certificates-ref 589 | {ta:x509-certificates}? 590 +-- pinned-client-certs? ta:pinned-certificates-ref 591 {ta:x509-certificates}? 592 grouping transport-params-grouping 593 +-- ssh-transport-params {ssh-server-transport-params-config}? 594 +---u transport-params-grouping 595 grouping keepalives-grouping 596 +-- ssh-keepalives {ssh-server-keepalives}? 597 +-- max-wait? uint16 598 +-- max-attempts? uint8 600 4.2. Example Usage 602 This section presents two examples showing the ssh-server-grouping 603 populated with some data. These examples are effectively the same 604 except the first configures the server identity using a local key 605 while the second uses a key configured in a keystore. Both examples 606 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 619 620 621 deployment-specific-certificate 622 623 624 ct:rsa2048 626 base64encodedvalue== 627 base64encodedvalue== 628 629 630 631 633 634 635 explicitly-trusted-client-ca-certs 637 explicitly-trusted-client-certs 639 641 642 643 algs:ssh-rsa 644 645 646 647 algs:diffie-hellman-group-exchange-sha256 649 650 651 652 algs:aes256-ctr 653 algs:aes192-ctr 654 algs:aes128-ctr 655 algs:aes256-cbc 656 algs:aes192-cbc 657 algs:aes128-cbc 658 659 660 algs:hmac-sha2-256 661 algs:hmac-sha2-512 662 663 665 667 The following example configures the server identity using a key from 668 the keystore: 670 ========== NOTE: '\\' line wrapping per BCP XX (RFC XXXX) =========== 672 675 676 677 678 deployment-specific-certificate 679 680 ex-rsa-key 681 682 683 685 686 687 explicitly-trusted-client-ca-certs 689 explicitly-trusted-client-certs 691 693 694 695 algs:ssh-rsa 696 697 698 699 algs:diffie-hellman-group-exchange-sha256 700 701 702 703 algs:aes256-ctr 704 algs:aes192-ctr 705 algs:aes128-ctr 706 algs:aes256-cbc 707 algs:aes192-cbc 708 algs:aes128-cbc 709 710 711 algs:hmac-sha2-256 712 algs:hmac-sha2-512 713 714 716 718 4.3. YANG Module 720 This YANG module has normative references to 721 [I-D.ietf-netconf-trust-anchors] and [I-D.ietf-netconf-keystore] and 722 informative references to [RFC4253] and [RFC7317]. 724 file "ietf-ssh-server@2019-03-09.yang" 725 ========== NOTE: '\\' line wrapping per BCP XX (RFC XXXX) =========== 727 module ietf-ssh-server { 728 yang-version 1.1; 729 namespace "urn:ietf:params:xml:ns:yang:ietf-ssh-server"; 730 prefix sshs; 732 import ietf-ssh-common { 733 prefix sshcmn; 734 revision-date 2019-03-09; // stable grouping definitions 735 reference 736 "RFC XXXX: YANG Groupings for SSH Clients and SSH Servers"; 737 } 739 import ietf-trust-anchors { 740 prefix ta; 741 reference 742 "RFC YYYY: YANG Data Model for Global Trust Anchors"; 743 } 745 import ietf-keystore { 746 prefix ks; 747 reference 748 "RFC ZZZZ: 749 YANG Data Model for a Centralized Keystore Mechanism"; 750 } 752 organization 753 "IETF NETCONF (Network Configuration) Working Group"; 755 contact 756 "WG Web: 757 WG List: 758 Author: Kent Watsen 759 Author: Gary Wu "; 761 description 762 "This module defines reusable groupings for SSH servers that 763 can be used as a basis for specific SSH server instances. 765 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 766 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 767 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 768 are to be interpreted as described in BCP 14 [RFC2119] 769 [RFC8174] when, and only when, they appear in all 770 capitals, as shown here. 772 Copyright (c) 2019 IETF Trust and the persons identified as 773 authors of the code. All rights reserved. 775 Redistribution and use in source and binary forms, with or 776 without modification, is permitted pursuant to, and subject 777 to the license terms contained in, the Simplified BSD 778 License set forth in Section 4.c of the IETF Trust's 779 Legal Provisions Relating to IETF Documents 780 (http://trustee.ietf.org/license-info). 782 This version of this YANG module is part of RFC XXXX; see 783 the RFC itself for full legal notices."; 785 revision 2019-03-09 { 786 description 787 "Initial version"; 788 reference 789 "RFC XXXX: YANG Groupings for SSH Clients and SSH Servers"; 790 } 792 // Features 794 feature ssh-server-transport-params-config { 795 description 796 "SSH transport layer parameters are configurable on an SSH 797 server."; 798 } 800 feature ssh-server-keepalives { 801 description 802 "Per socket SSH keepalive parameters are configurable for 803 SSH servers on the server implementing this feature."; 804 } 806 // Groupings 808 grouping ssh-server-grouping { 809 description 810 "A reusable grouping for configuring a SSH server without 811 any consideration for how underlying TCP sessions are 812 established."; 813 uses server-identity-grouping; 814 uses client-auth-grouping; 815 uses transport-params-grouping; 816 uses keepalives-grouping; 817 } 819 grouping server-identity-grouping { 820 description 821 "A reusable grouping for configuring an SSH server identity."; 822 container ssh-server-identity { 823 description 824 "The list of host-keys the SSH server will present when 825 establishing a SSH connection."; 826 list host-key { 827 key "name"; 828 min-elements 1; 829 ordered-by user; 830 description 831 "An ordered list of host keys the SSH server will use to 832 construct its ordered list of algorithms, when sending 833 its SSH_MSG_KEXINIT message, as defined in Section 7.1 834 of RFC 4253."; 835 reference 836 "RFC 4253: The Secure Shell (SSH) Transport Layer 837 Protocol"; 838 leaf name { 839 type string; 840 description 841 "An arbitrary name for this host-key"; 842 } 843 choice host-key-type { 844 mandatory true; 845 description 846 "The type of host key being specified"; 847 container public-key { 848 uses ks:local-or-keystore-asymmetric-key-grouping; 849 description 850 "A locally-defined or referenced asymmetric key pair 851 to be used for the SSH server's host key."; 852 reference 853 "RFC ZZZZ: YANG Data Model for a Centralized 854 Keystore Mechanism"; 855 } 856 container certificate { 857 if-feature "sshcmn:ssh-x509-certs"; 858 uses ks:local-or-keystore-end-entity-cert-with-key-group\ 859 \ing; 860 description 861 "A locally-defined or referenced end-entity 862 certificate to be used for the SSH server's 863 host key."; 864 reference 865 "RFC ZZZZ: YANG Data Model for a Centralized 866 Keystore Mechanism"; 867 } 868 } 869 } 870 } 871 } 873 grouping client-auth-grouping { 874 description 875 "A reusable grouping for configuring a SSH client 876 authentication."; 877 container ssh-client-cert-auth { 878 if-feature "sshcmn:ssh-x509-certs"; 879 description 880 "A reference to a list of pinned certificate authority (CA) 881 certificates and a reference to a list of pinned client 882 certificates. 884 Note: password and public-key based client authentication 885 are not configured in this YANG module as they are 886 expected to be configured by the ietf-system module 887 defined in RFC 7317."; 888 reference 889 "RFC 7317: A YANG Data Model for System Management"; 890 leaf pinned-ca-certs { 891 if-feature "ta:x509-certificates"; 892 type ta:pinned-certificates-ref; 893 description 894 "A reference to a list of certificate authority (CA) 895 certificates used by the SSH server to authenticate 896 SSH client certificates. A client certificate is 897 authenticated if it has a valid chain of trust to 898 a configured pinned CA certificate."; 899 reference 900 "RFC YYYY: YANG Data Model for Global Trust Anchors"; 901 } 902 leaf pinned-client-certs { 903 if-feature "ta:x509-certificates"; 904 type ta:pinned-certificates-ref; 905 description 906 "A reference to a list of client certificates used by 907 the SSH server to authenticate SSH client certificates. 908 A clients certificate is authenticated if it is an 909 exact match to a configured pinned client certificate."; 911 reference 912 "RFC YYYY: YANG Data Model for Global Trust Anchors"; 913 } 914 } 915 } 917 grouping transport-params-grouping { 918 description 919 "A reusable grouping for configuring a SSH transport 920 parameters."; 921 container ssh-transport-params { 922 if-feature "ssh-server-transport-params-config"; 923 description 924 "Configurable parameters of the SSH transport layer."; 925 uses sshcmn:transport-params-grouping; 926 } 927 } 929 grouping keepalives-grouping { 930 description 931 "A reusable grouping for configuring SSH server keepalive 932 parameters."; 933 container ssh-keepalives { 934 if-feature "ssh-server-keepalives"; 935 description 936 "Configures the keep-alive policy, to proactively test the 937 aliveness of the SSL client. An unresponsive SSL client is 938 dropped after approximately max-wait * max-attempts seconds\ 939 \."; 940 leaf max-wait { 941 type uint16 { 942 range "1..max"; 943 } 944 units "seconds"; 945 default "30"; 946 description 947 "Sets the amount of time in seconds after which if no data 948 has been received from the SSL client, a SSL-level message 949 will be sent to test the aliveness of the SSL client."; 950 } 951 leaf max-attempts { 952 type uint8; 953 default "3"; 954 description 955 "Sets the maximum number of sequential keep-alive messages 956 that can fail to obtain a response from the SSL client 957 before assuming the SSL client is no longer alive."; 958 } 960 } 961 } 962 } 963 965 5. The SSH Common Model 967 The SSH common model presented in this section contains identities 968 and groupings common to both SSH clients and SSH servers. The 969 transport-params-grouping can be used to configure the list of SSH 970 transport algorithms permitted by the SSH client or SSH server. The 971 lists of algorithms are ordered such that, if multiple algorithms are 972 permitted by the client, the algorithm that appears first in its list 973 that is also permitted by the server is used for the SSH transport 974 layer connection. The ability to restrict the algorithms allowed is 975 provided in this grouping for SSH clients and SSH servers that are 976 capable of doing so and may serve to make SSH clients and SSH servers 977 compliant with security policies. 979 [I-D.ietf-netconf-crypto-types] defines six categories of 980 cryptographic algorithms (hash-algorithm, symmetric-key-encryption- 981 algorithm, mac-algorithm, asymmetric-key-encryption-algorithm, 982 signature-algorithm, key-negotiation-algorithm) and lists several 983 widely accepted algorithms for each of them. The SSH client and 984 server models use one or more of these algorithms. The SSH common 985 model includes four parameters for configuring its permitted SSH 986 algorithms, which are: host-key-alg, key-exchange-alg, encryption-alg 987 and mac-alg. The following tables are provided, in part, to define 988 the subset of algorithms defined in the crypto-types model used by 989 SSH and, in part, to ensure compatibility of configured SSH 990 cryptographic parameters for configuring its permitted SSH algorithms 991 ("sshcmn" representing SSH common model, and "ct" representing 992 crypto-types model which the SSH client/server model is based on): 994 +-------------------------------+-------------------------------+ 995 | sshcmn:host-key-alg | ct:signature-algorithm | 996 +-------------------------------+-------------------------------+ 997 | dsa-sha1 | dsa-sha1 | 998 | rsa-pkcs1-sha1 | rsa-pkcs1-sha1 | 999 | rsa-pkcs1-sha256 | rsa-pkcs1-sha256 | 1000 | rsa-pkcs1-sha512 | rsa-pkcs1-sha512 | 1001 | ecdsa-secp256r1-sha256 | ecdsa-secp256r1-sha256 | 1002 | ecdsa-secp384r1-sha384 | ecdsa-secp384r1-sha384 | 1003 | ecdsa-secp521r1-sha512 | ecdsa-secp521r1-sha512 | 1004 | x509v3-rsa-pkcs1-sha1 | x509v3-rsa-pkcs1-sha1 | 1005 | x509v3-rsa2048-pkcs1-sha256 | x509v3-rsa2048-pkcs1-sha1 | 1006 | x509v3-ecdsa-secp256r1-sha256 | x509v3-ecdsa-secp256r1-sha256 | 1007 | x509v3-ecdsa-secp384r1-sha384 | x509v3-ecdsa-secp384r1-sha384 | 1008 | x509v3-ecdsa-secp521r1-sha512 | x509v3-ecdsa-secp521r1-sha512 | 1009 +-------------------------------+-------------------------------+ 1011 Table 1 The SSH Host-key-alg Compatibility Matrix 1013 +-------------------------------+-------------------------------+ 1014 | sshcmn:key-exchange-alg | ct:key-negotiation-algorithm | 1015 +-------------------------------+-------------------------------+ 1016 | diffie-hellman-group14-sha1 | diffie-hellman-group14-sha1 | 1017 | diffie-hellman-group14-sha256 | diffie-hellman-group14-sha256 | 1018 | diffie-hellman-group15-sha512 | diffie-hellman-group15-sha512 | 1019 | diffie-hellman-group16-sha512 | diffie-hellman-group16-sha512 | 1020 | diffie-hellman-group17-sha512 | diffie-hellman-group17-sha512 | 1021 | diffie-hellman-group18-sha512 | diffie-hellman-group18-sha512 | 1022 | ecdh-sha2-secp256r1 | ecdh-sha2-secp256r1 | 1023 | ecdh-sha2-secp384r1 | ecdh-sha2-secp384r1 | 1024 +-------------------------------+-------------------------------+ 1026 Table 2 The SSH Key-exchange-alg Compatibility Matrix 1028 +-----------------------+---------------------------------------+ 1029 | sshcmn:encryption-alg | ct:symmetric-key-encryption-algorithm | 1030 +-----------------------+---------------------------------------+ 1031 | aes-128-cbc | aes-128-cbc | 1032 | aes-192-cbc | aes-192-cbc | 1033 | aes-256-cbc | aes-256-cbc | 1034 | aes-128-ctr | aes-128-ctr | 1035 | aes-192-ctr | aes-192-ctr | 1036 | aes-256-ctr | aes-256-ctr | 1037 +-----------------------+---------------------------------------+ 1039 Table 3 The SSH Encryption-alg Compatibility Matrix 1040 +----------------+-------------------+ 1041 | sshcmn:mac-alg | ct:mac-algorithm | 1042 +----------------+-------------------+ 1043 | hmac-sha1 | hmac-sha1 | 1044 | hmac-sha1-96 | hmac-sha1-96 | 1045 | hmac-sha2-256 | hmac-sha2-256 | 1046 | hmac-sha2-512 | hmac-sha2-512 | 1047 +----------------+-------------------+ 1049 Table 4 The SSH Mac-alg Compatibility Matrix 1051 As is seen in the tables above, the names of the "sshcmn" algorithms 1052 are all identical to the names of algorithms defined in 1053 [I-D.ietf-netconf-crypto-types]. While appearing to be redundant, it 1054 is important to realize that not all the algorithms defined in 1055 [I-D.ietf-netconf-crypto-types] are supported by SSH. That is, the 1056 algorithms supported by SSH are a subset of the algorithms defined in 1057 [I-D.ietf-netconf-crypto-types]. The algorithms used by SSH are 1058 redefined in this document in order to constrain the algorithms that 1059 may be selected to just the ones used by SSH. 1061 Features are defined for algorithms that are OPTIONAL or are not 1062 widely supported by popular implementations. Note that the list of 1063 algorithms is not exhaustive. As well, some algorithms that are 1064 REQUIRED by [RFC4253] are missing, notably "ssh-dss" and "diffie- 1065 hellman-group1-sha1" due to their weak security and there being 1066 alternatives that are widely supported. 1068 5.1. Tree Diagram 1070 The following tree diagram [RFC8340] provides an overview of the data 1071 model for the "ietf-ssh-common" module. 1073 module: ietf-ssh-common 1075 grouping transport-params-grouping 1076 +-- host-key 1077 | +-- host-key-alg* identityref 1078 +-- key-exchange 1079 | +-- key-exchange-alg* identityref 1080 +-- encryption 1081 | +-- encryption-alg* identityref 1082 +-- mac 1083 +-- mac-alg* identityref 1085 5.2. Example Usage 1087 This following example illustrates how the transport-params-grouping 1088 appears when populated with some data. 1090 1093 1094 algs:x509v3-rsa2048-sha256 1095 algs:ssh-rsa 1096 1097 1098 1099 algs:diffie-hellman-group-exchange-sha256 1100 1101 1102 1103 algs:aes256-ctr 1104 algs:aes192-ctr 1105 algs:aes128-ctr 1106 algs:aes256-cbc 1107 algs:aes192-cbc 1108 algs:aes128-cbc 1109 1110 1111 algs:hmac-sha2-256 1112 algs:hmac-sha2-512 1113 1114 1116 5.3. YANG Module 1118 This YANG module has normative references to [RFC4253], [RFC4344], 1119 [RFC4419], [RFC5656], [RFC6187], and [RFC6668]. 1121 file "ietf-ssh-common@2019-03-09.yang" 1122 module ietf-ssh-common { 1123 yang-version 1.1; 1124 namespace "urn:ietf:params:xml:ns:yang:ietf-ssh-common"; 1125 prefix sshcmn; 1127 organization 1128 "IETF NETCONF (Network Configuration) Working Group"; 1130 contact 1131 "WG Web: 1132 WG List: 1133 Author: Kent Watsen 1134 Author: Gary Wu "; 1136 description 1137 "This module defines a common features, identities, and 1138 groupings for Secure Shell (SSH). 1140 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1141 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 1142 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 1143 are to be interpreted as described in BCP 14 [RFC2119] 1144 [RFC8174] when, and only when, they appear in all 1145 capitals, as shown here. 1147 Copyright (c) 2019 IETF Trust and the persons identified as 1148 authors of the code. All rights reserved. 1150 Redistribution and use in source and binary forms, with or 1151 without modification, is permitted pursuant to, and subject 1152 to the license terms contained in, the Simplified BSD 1153 License set forth in Section 4.c of the IETF Trust's 1154 Legal Provisions Relating to IETF Documents 1155 (http://trustee.ietf.org/license-info). 1157 This version of this YANG module is part of RFC XXXX; see 1158 the RFC itself for full legal notices."; 1160 revision 2019-03-09 { 1161 description 1162 "Initial version"; 1163 reference 1164 "RFC XXXX: YANG Groupings for SSH Clients and SSH Servers"; 1165 } 1167 // Features 1169 feature ssh-ecc { 1170 description 1171 "Elliptic Curve Cryptography is supported for SSH."; 1172 reference 1173 "RFC 5656: Elliptic Curve Algorithm Integration in the 1174 Secure Shell Transport Layer"; 1175 } 1177 feature ssh-x509-certs { 1178 description 1179 "X.509v3 certificates are supported for SSH per RFC 6187."; 1180 reference 1181 "RFC 6187: X.509v3 Certificates for Secure Shell 1182 Authentication"; 1183 } 1185 feature ssh-dh-group-exchange { 1186 description 1187 "Diffie-Hellman Group Exchange is supported for SSH."; 1188 reference 1189 "RFC 4419: Diffie-Hellman Group Exchange for the 1190 Secure Shell (SSH) Transport Layer Protocol"; 1191 } 1193 feature ssh-ctr { 1194 description 1195 "SDCTR encryption mode is supported for SSH."; 1196 reference 1197 "RFC 4344: The Secure Shell (SSH) Transport Layer 1198 Encryption Modes"; 1199 } 1201 feature ssh-sha2 { 1202 description 1203 "The SHA2 family of cryptographic hash functions is 1204 supported for SSH."; 1205 reference 1206 "FIPS PUB 180-4: Secure Hash Standard (SHS)"; 1207 } 1209 // Identities 1211 identity public-key-alg-base { 1212 description 1213 "Base identity used to identify public key algorithms."; 1214 } 1216 identity ssh-dss { 1217 base public-key-alg-base; 1218 description 1219 "Digital Signature Algorithm using SHA-1 as the 1220 hashing algorithm."; 1221 reference 1222 "RFC 4253: 1223 The Secure Shell (SSH) Transport Layer Protocol"; 1224 } 1226 identity ssh-rsa { 1227 base public-key-alg-base; 1228 description 1229 "RSASSA-PKCS1-v1_5 signature scheme using SHA-1 as the 1230 hashing algorithm."; 1231 reference 1232 "RFC 4253: 1233 The Secure Shell (SSH) Transport Layer Protocol"; 1234 } 1236 identity ecdsa-sha2-nistp256 { 1237 base public-key-alg-base; 1238 if-feature "ssh-ecc and ssh-sha2"; 1239 description 1240 "Elliptic Curve Digital Signature Algorithm (ECDSA) using the 1241 nistp256 curve and the SHA2 family of hashing algorithms."; 1242 reference 1243 "RFC 5656: Elliptic Curve Algorithm Integration in the 1244 Secure Shell Transport Layer"; 1245 } 1247 identity ecdsa-sha2-nistp384 { 1248 base public-key-alg-base; 1249 if-feature "ssh-ecc and ssh-sha2"; 1250 description 1251 "Elliptic Curve Digital Signature Algorithm (ECDSA) using the 1252 nistp384 curve and the SHA2 family of hashing algorithms."; 1253 reference 1254 "RFC 5656: Elliptic Curve Algorithm Integration in the 1255 Secure Shell Transport Layer"; 1256 } 1258 identity ecdsa-sha2-nistp521 { 1259 base public-key-alg-base; 1260 if-feature "ssh-ecc and ssh-sha2"; 1261 description 1262 "Elliptic Curve Digital Signature Algorithm (ECDSA) using the 1263 nistp521 curve and the SHA2 family of hashing algorithms."; 1264 reference 1265 "RFC 5656: Elliptic Curve Algorithm Integration in the 1266 Secure Shell Transport Layer"; 1267 } 1269 identity x509v3-ssh-rsa { 1270 base public-key-alg-base; 1271 if-feature "ssh-x509-certs"; 1272 description 1273 "RSASSA-PKCS1-v1_5 signature scheme using a public key stored 1274 in an X.509v3 certificate and using SHA-1 as the hashing 1275 algorithm."; 1276 reference 1277 "RFC 6187: X.509v3 Certificates for Secure Shell 1278 Authentication"; 1279 } 1281 identity x509v3-rsa2048-sha256 { 1282 base public-key-alg-base; 1283 if-feature "ssh-x509-certs and ssh-sha2"; 1284 description 1285 "RSASSA-PKCS1-v1_5 signature scheme using a public key stored 1286 in an X.509v3 certificate and using SHA-256 as the hashing 1287 algorithm. RSA keys conveyed using this format MUST have a 1288 modulus of at least 2048 bits."; 1289 reference 1290 "RFC 6187: X.509v3 Certificates for Secure Shell 1291 Authentication"; 1292 } 1294 identity x509v3-ecdsa-sha2-nistp256 { 1295 base public-key-alg-base; 1296 if-feature "ssh-ecc and ssh-x509-certs and ssh-sha2"; 1297 description 1298 "Elliptic Curve Digital Signature Algorithm (ECDSA) 1299 using the nistp256 curve with a public key stored in 1300 an X.509v3 certificate and using the SHA2 family of 1301 hashing algorithms."; 1302 reference 1303 "RFC 6187: X.509v3 Certificates for Secure Shell 1304 Authentication"; 1305 } 1307 identity x509v3-ecdsa-sha2-nistp384 { 1308 base public-key-alg-base; 1309 if-feature "ssh-ecc and ssh-x509-certs and ssh-sha2"; 1310 description 1311 "Elliptic Curve Digital Signature Algorithm (ECDSA) 1312 using the nistp384 curve with a public key stored in 1313 an X.509v3 certificate and using the SHA2 family of 1314 hashing algorithms."; 1315 reference 1316 "RFC 6187: X.509v3 Certificates for Secure Shell 1317 Authentication"; 1318 } 1320 identity x509v3-ecdsa-sha2-nistp521 { 1321 base public-key-alg-base; 1322 if-feature "ssh-ecc and ssh-x509-certs and ssh-sha2"; 1323 description 1324 "Elliptic Curve Digital Signature Algorithm (ECDSA) 1325 using the nistp521 curve with a public key stored in 1326 an X.509v3 certificate and using the SHA2 family of 1327 hashing algorithms."; 1328 reference 1329 "RFC 6187: X.509v3 Certificates for Secure Shell 1330 Authentication"; 1331 } 1333 identity key-exchange-alg-base { 1334 description 1335 "Base identity used to identify key exchange algorithms."; 1336 } 1338 identity diffie-hellman-group14-sha1 { 1339 base key-exchange-alg-base; 1340 description 1341 "Diffie-Hellman key exchange with SHA-1 as HASH and 1342 Oakley Group 14 (2048-bit MODP Group)."; 1343 reference 1344 "RFC 4253: The Secure Shell (SSH) Transport Layer Protocol"; 1345 } 1347 identity diffie-hellman-group-exchange-sha1 { 1348 base key-exchange-alg-base; 1349 if-feature "ssh-dh-group-exchange"; 1350 description 1351 "Diffie-Hellman Group and Key Exchange with SHA-1 as HASH."; 1352 reference 1353 "RFC 4419: Diffie-Hellman Group Exchange for the 1354 Secure Shell (SSH) Transport Layer Protocol"; 1355 } 1357 identity diffie-hellman-group-exchange-sha256 { 1358 base key-exchange-alg-base; 1359 if-feature "ssh-dh-group-exchange and ssh-sha2"; 1360 description 1361 "Diffie-Hellman Group and Key Exchange with SHA-256 as HASH."; 1362 reference 1363 "RFC 4419: Diffie-Hellman Group Exchange for the 1364 Secure Shell (SSH) Transport Layer Protocol"; 1365 } 1367 identity ecdh-sha2-nistp256 { 1368 base key-exchange-alg-base; 1369 if-feature "ssh-ecc and ssh-sha2"; 1370 description 1371 "Elliptic Curve Diffie-Hellman (ECDH) key exchange using the 1372 nistp256 curve and the SHA2 family of hashing algorithms."; 1374 reference 1375 "RFC 5656: Elliptic Curve Algorithm Integration in the 1376 Secure Shell Transport Layer"; 1377 } 1379 identity ecdh-sha2-nistp384 { 1380 base key-exchange-alg-base; 1381 if-feature "ssh-ecc and ssh-sha2"; 1382 description 1383 "Elliptic Curve Diffie-Hellman (ECDH) key exchange using the 1384 nistp384 curve and the SHA2 family of hashing algorithms."; 1385 reference 1386 "RFC 5656: Elliptic Curve Algorithm Integration in the 1387 Secure Shell Transport Layer"; 1388 } 1390 identity ecdh-sha2-nistp521 { 1391 base key-exchange-alg-base; 1392 if-feature "ssh-ecc and ssh-sha2"; 1393 description 1394 "Elliptic Curve Diffie-Hellman (ECDH) key exchange using the 1395 nistp521 curve and the SHA2 family of hashing algorithms."; 1396 reference 1397 "RFC 5656: Elliptic Curve Algorithm Integration in the 1398 Secure Shell Transport Layer"; 1399 } 1401 identity encryption-alg-base { 1402 description 1403 "Base identity used to identify encryption algorithms."; 1404 } 1406 identity triple-des-cbc { 1407 base encryption-alg-base; 1408 description 1409 "Three-key 3DES in CBC mode."; 1410 reference 1411 "RFC 4253: The Secure Shell (SSH) Transport Layer Protocol"; 1412 } 1414 identity aes128-cbc { 1415 base encryption-alg-base; 1416 description 1417 "AES in CBC mode, with a 128-bit key."; 1418 reference 1419 "RFC 4253: The Secure Shell (SSH) Transport Layer Protocol"; 1420 } 1421 identity aes192-cbc { 1422 base encryption-alg-base; 1423 description 1424 "AES in CBC mode, with a 192-bit key."; 1425 reference 1426 "RFC 4253: The Secure Shell (SSH) Transport Layer Protocol"; 1427 } 1429 identity aes256-cbc { 1430 base encryption-alg-base; 1431 description 1432 "AES in CBC mode, with a 256-bit key."; 1433 reference 1434 "RFC 4253: The Secure Shell (SSH) Transport Layer Protocol"; 1435 } 1437 identity aes128-ctr { 1438 base encryption-alg-base; 1439 if-feature "ssh-ctr"; 1440 description 1441 "AES in SDCTR mode, with 128-bit key."; 1442 reference 1443 "RFC 4344: The Secure Shell (SSH) Transport Layer Encryption 1444 Modes"; 1445 } 1447 identity aes192-ctr { 1448 base encryption-alg-base; 1449 if-feature "ssh-ctr"; 1450 description 1451 "AES in SDCTR mode, with 192-bit key."; 1452 reference 1453 "RFC 4344: The Secure Shell (SSH) Transport Layer Encryption 1454 Modes"; 1455 } 1457 identity aes256-ctr { 1458 base encryption-alg-base; 1459 if-feature "ssh-ctr"; 1460 description 1461 "AES in SDCTR mode, with 256-bit key."; 1462 reference 1463 "RFC 4344: The Secure Shell (SSH) Transport Layer Encryption 1464 Modes"; 1465 } 1467 identity mac-alg-base { 1468 description 1469 "Base identity used to identify message authentication 1470 code (MAC) algorithms."; 1471 } 1473 identity hmac-sha1 { 1474 base mac-alg-base; 1475 description 1476 "HMAC-SHA1"; 1477 reference 1478 "RFC 4253: The Secure Shell (SSH) Transport Layer Protocol"; 1479 } 1481 identity hmac-sha2-256 { 1482 base mac-alg-base; 1483 if-feature "ssh-sha2"; 1484 description 1485 "HMAC-SHA2-256"; 1486 reference 1487 "RFC 6668: SHA-2 Data Integrity Verification for the 1488 Secure Shell (SSH) Transport Layer Protocol"; 1489 } 1491 identity hmac-sha2-512 { 1492 base mac-alg-base; 1493 if-feature "ssh-sha2"; 1494 description 1495 "HMAC-SHA2-512"; 1496 reference 1497 "RFC 6668: SHA-2 Data Integrity Verification for the 1498 Secure Shell (SSH) Transport Layer Protocol"; 1499 } 1501 // Groupings 1503 grouping transport-params-grouping { 1504 description 1505 "A reusable grouping for SSH transport parameters."; 1506 reference 1507 "RFC 4253: The Secure Shell (SSH) Transport Layer Protocol"; 1508 container host-key { 1509 description 1510 "Parameters regarding host key."; 1511 leaf-list host-key-alg { 1512 type identityref { 1513 base public-key-alg-base; 1514 } 1515 ordered-by user; 1516 description 1517 "Acceptable host key algorithms in order of descending 1518 preference. The configured host key algorithms should 1519 be compatible with the algorithm used by the configured 1520 private key. Please see Section 5 of RFC XXXX for 1521 valid combinations. 1523 If this leaf-list is not configured (has zero elements) 1524 the acceptable host key algorithms are implementation- 1525 defined."; 1526 reference 1527 "RFC XXXX: YANG Groupings for SSH Clients and SSH Servers"; 1528 } 1529 } 1530 container key-exchange { 1531 description 1532 "Parameters regarding key exchange."; 1533 leaf-list key-exchange-alg { 1534 type identityref { 1535 base key-exchange-alg-base; 1536 } 1537 ordered-by user; 1538 description 1539 "Acceptable key exchange algorithms in order of descending 1540 preference. 1542 If this leaf-list is not configured (has zero elements) 1543 the acceptable key exchange algorithms are implementation 1544 defined."; 1545 } 1546 } 1547 container encryption { 1548 description 1549 "Parameters regarding encryption."; 1550 leaf-list encryption-alg { 1551 type identityref { 1552 base encryption-alg-base; 1553 } 1554 ordered-by user; 1555 description 1556 "Acceptable encryption algorithms in order of descending 1557 preference. 1559 If this leaf-list is not configured (has zero elements) 1560 the acceptable encryption algorithms are implementation 1561 defined."; 1562 } 1563 } 1564 container mac { 1565 description 1566 "Parameters regarding message authentication code (MAC)."; 1567 leaf-list mac-alg { 1568 type identityref { 1569 base mac-alg-base; 1570 } 1571 ordered-by user; 1572 description 1573 "Acceptable MAC algorithms in order of descending 1574 preference. 1576 If this leaf-list is not configured (has zero elements) 1577 the acceptable MAC algorithms are implementation- 1578 defined."; 1579 } 1580 } 1581 } 1582 } 1583 1585 6. Security Considerations 1587 The YANG modules defined in this document are designed to be accessed 1588 via YANG based management protocols, such as NETCONF [RFC6241] and 1589 RESTCONF [RFC8040]. Both of these protocols have mandatory-to- 1590 implement secure transport layers (e.g., SSH, TLS) with mutual 1591 authentication. 1593 The NETCONF access control model (NACM) [RFC8341] provides the means 1594 to restrict access for particular users to a pre-configured subset of 1595 all available protocol operations and content. 1597 Since the modules defined in this document define only groupings, 1598 these considerations are primarily for the designers of other modules 1599 that use these groupings. 1601 There are a number of data nodes defined in the YANG modules that are 1602 writable/creatable/deletable (i.e., config true, which is the 1603 default). These data nodes may be considered sensitive or vulnerable 1604 in some network environments. Write operations (e.g., edit-config) 1605 to these data nodes without proper protection can have a negative 1606 effect on network operations. These are the subtrees and data nodes 1607 and their sensitivity/vulnerability: 1609 /: The entire data tree defined by all the modules defined in this 1610 draft are sensitive to write operations. For instance, the 1611 addition or removal of references to keys, certificates, 1612 trusted anchors, etc., can dramatically alter the implemented 1613 security policy. However, no NACM annotations are applied as 1614 the data SHOULD be editable by users other than a designated 1615 'recovery session'. 1617 Some of the readable data nodes in the YANG modules may be considered 1618 sensitive or vulnerable in some network environments. It is thus 1619 important to control read access (e.g., via get, get-config, or 1620 notification) to these data nodes. These are the subtrees and data 1621 nodes and their sensitivity/vulnerability: 1623 /client-auth/password: This node in the 'ietf-ssh-client' module 1624 is additionally sensitive to read operations such that, in 1625 normal use cases, it should never be returned to a client. The 1626 only time this node should be returned is to support backup/ 1627 restore type workflows. However, no NACM annotations are 1628 applied as the data SHOULD be writable by users other than a 1629 designated 'recovery session'. 1631 Some of the RPC operations in this YANG module may be considered 1632 sensitive or vulnerable in some network environments. It is thus 1633 important to control access to these operations. These are the 1634 operations and their sensitivity/vulnerability: 1636 NONE 1638 7. IANA Considerations 1640 7.1. The IETF XML Registry 1642 This document registers three URIs in the "ns" subregistry of the 1643 IETF XML Registry [RFC3688]. Following the format in [RFC3688], the 1644 following registrations are requested: 1646 URI: urn:ietf:params:xml:ns:yang:ietf-ssh-client 1647 Registrant Contact: The NETCONF WG of the IETF. 1648 XML: N/A, the requested URI is an XML namespace. 1650 URI: urn:ietf:params:xml:ns:yang:ietf-ssh-server 1651 Registrant Contact: The NETCONF WG of the IETF. 1652 XML: N/A, the requested URI is an XML namespace. 1654 URI: urn:ietf:params:xml:ns:yang:ietf-ssh-common 1655 Registrant Contact: The NETCONF WG of the IETF. 1656 XML: N/A, the requested URI is an XML namespace. 1658 7.2. The YANG Module Names Registry 1660 This document registers three YANG modules in the YANG Module Names 1661 registry [RFC6020]. Following the format in [RFC6020], the following 1662 registrations are requested: 1664 name: ietf-ssh-client 1665 namespace: urn:ietf:params:xml:ns:yang:ietf-ssh-client 1666 prefix: sshc 1667 reference: RFC XXXX 1669 name: ietf-ssh-server 1670 namespace: urn:ietf:params:xml:ns:yang:ietf-ssh-server 1671 prefix: sshs 1672 reference: RFC XXXX 1674 name: ietf-ssh-common 1675 namespace: urn:ietf:params:xml:ns:yang:ietf-ssh-common 1676 prefix: sshcmn 1677 reference: RFC XXXX 1679 8. References 1681 8.1. Normative References 1683 [I-D.ietf-netconf-crypto-types] 1684 Watsen, K. and H. Wang, "Common YANG Data Types for 1685 Cryptography", draft-ietf-netconf-crypto-types-02 (work in 1686 progress), October 2018. 1688 [I-D.ietf-netconf-keystore] 1689 Watsen, K., "YANG Data Model for a Centralized Keystore 1690 Mechanism", draft-ietf-netconf-keystore-08 (work in 1691 progress), March 2019. 1693 [I-D.ietf-netconf-trust-anchors] 1694 Watsen, K., "YANG Data Model for Global Trust Anchors", 1695 draft-ietf-netconf-trust-anchors-03 (work in progress), 1696 March 2019. 1698 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1699 Requirement Levels", BCP 14, RFC 2119, 1700 DOI 10.17487/RFC2119, March 1997, 1701 . 1703 [RFC4344] Bellare, M., Kohno, T., and C. Namprempre, "The Secure 1704 Shell (SSH) Transport Layer Encryption Modes", RFC 4344, 1705 DOI 10.17487/RFC4344, January 2006, 1706 . 1708 [RFC4419] Friedl, M., Provos, N., and W. Simpson, "Diffie-Hellman 1709 Group Exchange for the Secure Shell (SSH) Transport Layer 1710 Protocol", RFC 4419, DOI 10.17487/RFC4419, March 2006, 1711 . 1713 [RFC5656] Stebila, D. and J. Green, "Elliptic Curve Algorithm 1714 Integration in the Secure Shell Transport Layer", 1715 RFC 5656, DOI 10.17487/RFC5656, December 2009, 1716 . 1718 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1719 the Network Configuration Protocol (NETCONF)", RFC 6020, 1720 DOI 10.17487/RFC6020, October 2010, 1721 . 1723 [RFC6187] Igoe, K. and D. Stebila, "X.509v3 Certificates for Secure 1724 Shell Authentication", RFC 6187, DOI 10.17487/RFC6187, 1725 March 2011, . 1727 [RFC6668] Bider, D. and M. Baushke, "SHA-2 Data Integrity 1728 Verification for the Secure Shell (SSH) Transport Layer 1729 Protocol", RFC 6668, DOI 10.17487/RFC6668, July 2012, 1730 . 1732 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1733 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1734 . 1736 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1737 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1738 May 2017, . 1740 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 1741 Access Control Model", STD 91, RFC 8341, 1742 DOI 10.17487/RFC8341, March 2018, 1743 . 1745 8.2. Informative References 1747 [OPENSSH] Project, T. O., "OpenSSH", 2016, . 1749 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1750 DOI 10.17487/RFC3688, January 2004, 1751 . 1753 [RFC4252] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) 1754 Authentication Protocol", RFC 4252, DOI 10.17487/RFC4252, 1755 January 2006, . 1757 [RFC4253] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) 1758 Transport Layer Protocol", RFC 4253, DOI 10.17487/RFC4253, 1759 January 2006, . 1761 [RFC4254] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) 1762 Connection Protocol", RFC 4254, DOI 10.17487/RFC4254, 1763 January 2006, . 1765 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1766 and A. Bierman, Ed., "Network Configuration Protocol 1767 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1768 . 1770 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 1771 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 1772 . 1774 [RFC7317] Bierman, A. and M. Bjorklund, "A YANG Data Model for 1775 System Management", RFC 7317, DOI 10.17487/RFC7317, August 1776 2014, . 1778 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1779 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1780 . 1782 [RFC8071] Watsen, K., "NETCONF Call Home and RESTCONF Call Home", 1783 RFC 8071, DOI 10.17487/RFC8071, February 2017, 1784 . 1786 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 1787 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 1788 . 1790 Appendix A. Change Log 1792 A.1. 00 to 01 1794 o Noted that '0.0.0.0' and '::' might have special meanings. 1796 o Renamed "keychain" to "keystore". 1798 A.2. 01 to 02 1800 o Removed the groupings 'listening-ssh-client-grouping' and 1801 'listening-ssh-server-grouping'. Now modules only contain the 1802 transport-independent groupings. 1804 o Simplified the "client-auth" part in the ietf-ssh-client module. 1805 It now inlines what it used to point to keystore for. 1807 o Added cipher suites for various algorithms into new 'ietf-ssh- 1808 common' module. 1810 A.3. 02 to 03 1812 o Removed 'RESTRICTED' enum from 'password' leaf type. 1814 o Added a 'must' statement to container 'server-auth' asserting that 1815 at least one of the various auth mechanisms must be specified. 1817 o Fixed description statement for leaf 'trusted-ca-certs'. 1819 A.4. 03 to 04 1821 o Change title to "YANG Groupings for SSH Clients and SSH Servers" 1823 o Added reference to RFC 6668 1825 o Added RFC 8174 to Requirements Language Section. 1827 o Enhanced description statement for ietf-ssh-server's "trusted-ca- 1828 certs" leaf. 1830 o Added mandatory true to ietf-ssh-client's "client-auth" 'choice' 1831 statement. 1833 o Changed the YANG prefix for module ietf-ssh-common from 'sshcom' 1834 to 'sshcmn'. 1836 o Removed the compression algorithms as they are not commonly 1837 configurable in vendors' implementations. 1839 o Updating descriptions in transport-params-grouping and the 1840 servers's usage of it. 1842 o Now tree diagrams reference ietf-netmod-yang-tree-diagrams 1844 o Updated YANG to use typedefs around leafrefs to common keystore 1845 paths 1847 o Now inlines key and certificates (no longer a leafref to keystore) 1849 A.5. 04 to 05 1851 o Merged changes from co-author. 1853 A.6. 05 to 06 1855 o Updated to use trust anchors from trust-anchors draft (was 1856 keystore draft) 1858 o Now uses new keystore grouping enabling asymmetric key to be 1859 either locally defined or a reference to the keystore. 1861 A.7. 06 to 07 1863 o factored the ssh-[client|server]-groupings into more reusable 1864 groupings. 1866 o added if-feature statements for the new "ssh-host-keys" and 1867 "x509-certificates" features defined in draft-ietf-netconf-trust- 1868 anchors. 1870 A.8. 07 to 08 1872 o Added a number of compatibility matrices to Section 5 (thanks 1873 Frank!) 1875 o Clarified that any configured "host-key-alg" values need to be 1876 compatible with the configured private key. 1878 A.9. 08 to 09 1880 o Updated examples to reflect update to groupings defined in the 1881 keystore -09 draft. 1883 o Add SSH keepalives features and groupings. 1885 o Prefixed top-level SSH grouping nodes with 'ssh-' and support 1886 mashups. 1888 o Updated copyright date, boilerplate template, affiliation, and 1889 folding algorithm. 1891 A.10. 09 to 10 1893 o Reformatted the YANG module 1895 Acknowledgements 1897 The authors would like to thank for following for lively discussions 1898 on list and in the halls (ordered by last name): Andy Bierman, Martin 1899 Bjorklund, Benoit Claise, Mehmet Ersue, Balazs Kovacs, David 1900 Lamparter, Alan Luchuk, Ladislav Lhotka, Radek Krejci, Tom Petch, 1901 Juergen Schoenwaelder, Phil Shafer, Sean Turner, Michal Vasko, and 1902 Bert Wijnen. 1904 Authors' Addresses 1906 Kent Watsen 1907 Watsen Networks 1909 EMail: kent+ietf@watsen.net 1911 Gary Wu 1912 Cisco Systems 1914 EMail: garywu@cisco.com 1916 Liang Xia 1917 Huawei 1919 EMail: frank.xialiang@huawei.com