idnits 2.17.1 draft-ietf-netconf-ssh-client-server-13.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 599 has weird spacing: '...gorithm str...' == Line 1048 has weird spacing: '... string cer...' -- The document date (April 29, 2019) is 1823 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 (~~), 6 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF Working Group K. Watsen 3 Internet-Draft Watsen Networks 4 Intended status: Standards Track G. Wu 5 Expires: October 31, 2019 Cisco Systems 6 L. Xia 7 Huawei 8 April 29, 2019 10 YANG Groupings for SSH Clients and SSH Servers 11 draft-ietf-netconf-ssh-client-server-13 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-29" --> 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 31, 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 . . . . . . . . . . . . . . . . . . . . 26 101 5.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 28 102 5.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 29 103 5.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 29 104 6. Security Considerations . . . . . . . . . . . . . . . . . . . 39 105 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 40 106 7.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 40 107 7.2. The YANG Module Names Registry . . . . . . . . . . . . . 41 108 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 41 109 8.1. Normative References . . . . . . . . . . . . . . . . . . 41 110 8.2. Informative References . . . . . . . . . . . . . . . . . 43 111 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 45 112 A.1. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 45 113 A.2. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 45 114 A.3. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 45 115 A.4. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 45 116 A.5. 04 to 05 . . . . . . . . . . . . . . . . . . . . . . . . 46 117 A.6. 05 to 06 . . . . . . . . . . . . . . . . . . . . . . . . 46 118 A.7. 06 to 07 . . . . . . . . . . . . . . . . . . . . . . . . 46 119 A.8. 07 to 08 . . . . . . . . . . . . . . . . . . . . . . . . 46 120 A.9. 08 to 09 . . . . . . . . . . . . . . . . . . . . . . . . 46 121 A.10. 09 to 10 . . . . . . . . . . . . . . . . . . . . . . . . 47 122 A.11. 10 to 11 . . . . . . . . . . . . . . . . . . . . . . . . 47 123 A.12. 11 to 12 . . . . . . . . . . . . . . . . . . . . . . . . 47 124 A.13. 12 to 13 . . . . . . . . . . . . . . . . . . . . . . . . 47 125 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 47 126 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 48 128 1. Introduction 130 This document defines three YANG 1.1 [RFC7950] modules: the first 131 defines a grouping for a generic SSH client, the second defines a 132 grouping for a generic SSH server, and the third defines identities 133 and groupings common to both the client and the server. It is 134 intended that these groupings will be used by applications using the 135 SSH protocol [RFC4252], [RFC4253], and [RFC4254]. For instance, 136 these groupings could be used to help define the data model for an 137 OpenSSH [OPENSSH] server or a NETCONF over SSH [RFC6242] based 138 server. 140 The client and server YANG modules in this document each define one 141 grouping, which is focused on just SSH-specific configuration, and 142 specifically avoids any transport-level configuration, such as what 143 ports to listen on or connect to. This affords applications the 144 opportunity to define their own strategy for how the underlying TCP 145 connection is established. For instance, applications supporting 146 NETCONF Call Home [RFC8071] could use the "ssh-server-grouping" 147 grouping for the SSH parts it provides, while adding data nodes for 148 the TCP-level call-home configuration. 150 The modules defined in this document use groupings defined in 151 [I-D.ietf-netconf-keystore] enabling keys to be either locally 152 defined or a reference to globally configured values. 154 The modules defined in this document optionally support [RFC6187] 155 enabling X.509v3 certificate based host keys and public keys. 157 2. Terminology 159 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 160 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 161 "OPTIONAL" in this document are to be interpreted as described in BCP 162 14 [RFC2119] [RFC8174] when, and only when, they appear in all 163 capitals, as shown here. 165 3. The SSH Client Model 167 3.1. Tree Diagram 169 This section provides a tree diagram [RFC8340] for the "ietf-ssh- 170 client" module that does not have groupings expanded. 172 =========== NOTE: '\' line wrapping per BCP XX (RFC XXXX) =========== 174 module: ietf-ssh-client 176 grouping ssh-client-grouping 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-key-\ 188 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 2 of 209 [I-D.ietf-netconf-trust-anchors] and Section 3.2 of 210 [I-D.ietf-netconf-keystore]. 212 The following example configures the client identity using a local 213 key: 215 =========== NOTE: '\' line wrapping per BCP XX (RFC XXXX) =========== 217 220 221 222 foobar 223 224 225 ct:rsa2048 227 base64encodedvalue== 228 base64encodedvalue== 229 230 231 233 234 235 explicitly-trusted-ssh-host-keys 237 239 240 241 algs:ssh-rsa 242 243 244 245 algs:diffie-hellman-group-exchange-sha256 246 247 248 249 algs:aes256-ctr 250 algs:aes192-ctr 251 algs:aes128-ctr 252 algs:aes256-cbc 253 algs:aes192-cbc 254 algs:aes128-cbc 255 256 257 algs:hmac-sha2-256 258 algs:hmac-sha2-512 259 260 262 263 30 264 3 265 267 268 The following example configures the client identity using a key from 269 the keystore: 271 =========== NOTE: '\' line wrapping per BCP XX (RFC XXXX) =========== 273 277 278 279 foobar 280 281 ex-rsa-key 282 283 285 286 287 explicitly-trusted-ssh-host-keys 289 291 292 293 algs:ssh-rsa 294 295 296 297 algs:diffie-hellman-group-exchange-sha256 298 299 300 301 algs:aes256-ctr 302 algs:aes192-ctr 303 algs:aes128-ctr 304 algs:aes256-cbc 305 algs:aes192-cbc 306 algs:aes128-cbc 307 308 309 algs:hmac-sha2-256 310 algs:hmac-sha2-512 311 312 314 315 30 316 3 317 319 321 3.3. YANG Module 323 This YANG module has normative references to 324 [I-D.ietf-netconf-trust-anchors], and [I-D.ietf-netconf-keystore]. 326 file "ietf-ssh-client@2019-04-29.yang" 327 module ietf-ssh-client { 328 yang-version 1.1; 329 namespace "urn:ietf:params:xml:ns:yang:ietf-ssh-client"; 330 prefix sshc; 332 import ietf-ssh-common { 333 prefix sshcmn; 334 revision-date 2019-04-29; // stable grouping definitions 335 reference 336 "RFC XXXX: YANG Groupings for SSH Clients and SSH Servers"; 337 } 339 import ietf-trust-anchors { 340 prefix ta; 341 reference 342 "RFC YYYY: YANG Data Model for Global Trust Anchors"; 343 } 345 import ietf-keystore { 346 prefix ks; 347 reference 348 "RFC ZZZZ: 349 YANG Data Model for a Centralized Keystore Mechanism"; 350 } 352 import ietf-netconf-acm { 353 prefix nacm; 354 reference 355 "RFC 8341: Network Configuration Access Control Model"; 356 } 358 organization 359 "IETF NETCONF (Network Configuration) Working Group"; 361 contact 362 "WG Web: 363 WG List: 364 Author: Kent Watsen 365 Author: Gary Wu "; 367 description 368 "This module defines reusable groupings for SSH clients that 369 can be used as a basis for specific SSH client instances. 371 Copyright (c) 2019 IETF Trust and the persons identified 372 as authors of the code. All rights reserved. 374 Redistribution and use in source and binary forms, with 375 or without modification, is permitted pursuant to, and 376 subject to the license terms contained in, the Simplified 377 BSD License set forth in Section 4.c of the IETF Trust's 378 Legal Provisions Relating to IETF Documents 379 (https://trustee.ietf.org/license-info). 381 This version of this YANG module is part of RFC XXXX 382 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC 383 itself for full legal notices.; 385 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 386 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 387 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 388 are to be interpreted as described in BCP 14 (RFC 2119) 389 (RFC 8174) when, and only when, they appear in all 390 capitals, as shown here."; 392 revision 2019-04-29 { 393 description 394 "Initial version"; 395 reference 396 "RFC XXXX: YANG Groupings for SSH Clients and SSH Servers"; 397 } 399 // Features 401 feature ssh-client-transport-params-config { 402 description 403 "SSH transport layer parameters are configurable on an SSH 404 client."; 405 } 407 feature ssh-client-keepalives { 408 description 409 "Per socket SSH keepalive parameters are configurable for 410 SSH clients on the server implementing this feature."; 411 } 412 // Groupings 414 grouping ssh-client-grouping { 415 description 416 "A reusable grouping for configuring a SSH client without 417 any consideration for how an underlying TCP session is 418 established. 420 Note that this grouping uses fairly typical descendent 421 node names such that a stack of 'uses' statements will 422 have name conflicts. It is intended that the consuming 423 data model will resolve the issue (e.g., by wrapping 424 the 'uses' statement in a container called 425 'ssh-client-parameters'). This model purposely does 426 not do this itself so as to provide maximum flexibility 427 to consuming models."; 429 container client-identity { 430 nacm:default-deny-write; 431 description 432 "The credentials used by the client to authenticate to 433 the SSH server."; 434 leaf username { 435 type string; 436 description 437 "The username of this user. This will be the username 438 used, for instance, to log into an SSH server."; 439 } 440 choice auth-type { 441 mandatory true; 442 description 443 "The authentication type."; 444 leaf password { 445 nacm:default-deny-all; 446 type string; 447 description 448 "A password to be used for client authentication."; 449 } 450 container public-key { 451 uses ks:local-or-keystore-asymmetric-key-grouping; 452 description 453 "A locally-defined or referenced asymmetric key 454 pair to be used for client authentication."; 455 reference 456 "RFC ZZZZ: YANG Data Model for a Centralized 457 Keystore Mechanism"; 458 } 459 container certificate { 460 if-feature "sshcmn:ssh-x509-certs"; 461 uses 462 ks:local-or-keystore-end-entity-cert-with-key-grouping; 463 description 464 "A locally-defined or referenced certificate 465 to be used for client authentication."; 466 reference 467 "RFC ZZZZ: YANG Data Model for a Centralized 468 Keystore Mechanism"; 469 } 470 } 471 } // container client-identity 473 container server-authentication { 474 nacm:default-deny-write; 475 must 'pinned-ssh-host-keys or pinned-ca-certs or ' 476 + 'pinned-server-certs'; 477 description 478 "Trusted server identities."; 479 leaf pinned-ssh-host-keys { 480 if-feature "ta:ssh-host-keys"; 481 type ta:pinned-host-keys-ref; 482 description 483 "A reference to a list of SSH host keys used by the 484 SSH client to authenticate SSH server host keys. 485 A server host key is authenticated if it is an 486 exact match to a configured SSH host key."; 487 reference 488 "RFC YYYY: YANG Data Model for Global Trust Anchors"; 489 } 490 leaf pinned-ca-certs { 491 if-feature "sshcmn:ssh-x509-certs"; 492 if-feature "ta:x509-certificates"; 493 type ta:pinned-certificates-ref; 494 description 495 "A reference to a list of certificate authority (CA) 496 certificates used by the SSH client to authenticate 497 SSH server certificates. A server certificate is 498 authenticated if it has a valid chain of trust to 499 a configured CA certificate."; 500 reference 501 "RFC YYYY: YANG Data Model for Global Trust Anchors"; 502 } 503 leaf pinned-server-certs { 504 if-feature "sshcmn:ssh-x509-certs"; 505 if-feature "ta:x509-certificates"; 506 type ta:pinned-certificates-ref; 507 description 508 "A reference to a list of server certificates used by 509 the SSH client to authenticate SSH server certificates. 510 A server certificate is authenticated if it is an 511 exact match to a configured server certificate."; 512 reference 513 "RFC YYYY: YANG Data Model for Global Trust Anchors"; 514 } 515 } // container server-authentication 517 container transport-params { 518 nacm:default-deny-write; 519 if-feature "ssh-client-transport-params-config"; 520 description 521 "Configurable parameters of the SSH transport layer."; 522 uses sshcmn:transport-params-grouping; 523 } // container transport-parameters 525 container keepalives { 526 nacm:default-deny-write; 527 if-feature "ssh-client-keepalives"; 528 presence "Indicates that keepalives are enabled."; 529 description 530 "Configures the keep-alive policy, to proactively test 531 the aliveness of the SSH server. An unresponsive TLS 532 server is dropped after approximately max-wait * 533 max-attempts seconds."; 534 leaf max-wait { 535 type uint16 { 536 range "1..max"; 537 } 538 units "seconds"; 539 default "30"; 540 description 541 "Sets the amount of time in seconds after which if 542 no data has been received from the SSH server, a 543 TLS-level message will be sent to test the 544 aliveness of the SSH server."; 545 } 546 leaf max-attempts { 547 type uint8; 548 default "3"; 549 description 550 "Sets the maximum number of sequential keep-alive 551 messages that can fail to obtain a response from 552 the SSH server before assuming the SSH server is 553 no longer alive."; 554 } 555 } // container keepalives 557 } // grouping ssh-client-grouping 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 =========== NOTE: '\' line wrapping per BCP XX (RFC XXXX) =========== 570 module: ietf-ssh-server 572 grouping ssh-server-grouping 573 +-- server-identity 574 | +-- host-key* [name] 575 | +-- name? string 576 | +-- (host-key-type) 577 | +--:(public-key) 578 | | +-- public-key 579 | | +---u ks:local-or-keystore-asymmetric-key-grouping 580 | +--:(certificate) 581 | +-- certificate {sshcmn:ssh-x509-certs}? 582 | +---u ks:local-or-keystore-end-entity-cert-with-k\ 583 ey-grouping 584 +-- client-authentication 585 | +-- supported-authentication-methods 586 | | +-- publickey? empty 587 | | +-- passsword? empty 588 | | +-- hostbased? empty 589 | | +-- none? empty 590 | | +-- other* string 591 | +-- (local-or-external) 592 | +--:(local) {local-client-auth-supported}? 593 | | +-- users 594 | | +-- user* [name] 595 | | +-- name? string 596 | | +-- password? ianach:crypt-hash 597 | | +-- authorized-key* [name] 598 | | +-- name? string 599 | | +-- algorithm string 600 | | +-- key-data binary 601 | +--:(external) {external-client-auth-supported}? 602 | +-- client-auth-defined-elsewhere? empty 603 +-- transport-params {ssh-server-transport-params-config}? 604 | +---u sshcmn:transport-params-grouping 605 +-- keepalives! {ssh-server-keepalives}? 606 +-- max-wait? uint16 607 +-- max-attempts? uint8 609 4.2. Example Usage 611 This section presents two examples showing the ssh-server-grouping 612 populated with some data. These examples are effectively the same 613 except the first configures the server identity using a local key 614 while the second uses a key configured in a keystore. Both examples 615 are consistent with the examples presented in Section 2 of 617 [I-D.ietf-netconf-trust-anchors] and Section 3.2 of 618 [I-D.ietf-netconf-keystore]. 620 The following example configures the server identity using a local 621 key: 623 =========== NOTE: '\' line wrapping per BCP XX (RFC XXXX) =========== 625 629 630 631 632 deployment-specific-certificate 633 634 635 ct:rsa2048 637 base64encodedvalue== 638 base64encodedvalue== 639 640 641 642 644 645 646 647 648 649 650 651 652 mary 653 654 655 656 662 664 665 666 algs:ssh-rsa 667 668 669 670 algs:diffie-hellman-group-exchange-sha256 671 672 673 674 algs:aes256-ctr 675 algs:aes192-ctr 676 algs:aes128-ctr 677 algs:aes256-cbc 678 algs:aes192-cbc 679 algs:aes128-cbc 680 681 682 algs:hmac-sha2-256 683 algs:hmac-sha2-512 684 685 687 689 The following example configures the server identity using a key from 690 the keystore: 692 =========== NOTE: '\' line wrapping per BCP XX (RFC XXXX) =========== 694 698 699 700 701 deployment-specific-certificate 702 703 ex-rsa-key 704 705 706 708 709 710 711 712 713 714 715 716 mary 717 718 719 720 726 728 729 730 algs:ssh-rsa 731 732 733 734 algs:diffie-hellman-group-exchange-sha256 735 736 737 738 algs:aes256-ctr 739 algs:aes192-ctr 740 algs:aes128-ctr 741 algs:aes256-cbc 742 algs:aes192-cbc 743 algs:aes128-cbc 744 745 746 algs:hmac-sha2-256 747 algs:hmac-sha2-512 748 749 751 753 4.3. YANG Module 755 This YANG module has normative references to 756 [I-D.ietf-netconf-trust-anchors] and [I-D.ietf-netconf-keystore] and 757 informative references to [RFC4253] and [RFC7317]. 759 file "ietf-ssh-server@2019-04-29.yang" 760 module ietf-ssh-server { 761 yang-version 1.1; 762 namespace "urn:ietf:params:xml:ns:yang:ietf-ssh-server"; 763 prefix sshs; 765 import ietf-ssh-common { 766 prefix sshcmn; 767 revision-date 2019-04-29; // stable grouping definitions 768 reference 769 "RFC XXXX: YANG Groupings for SSH Clients and SSH Servers"; 770 } 771 /* 772 import ietf-trust-anchors { 773 prefix ta; 774 reference 775 "RFC YYYY: YANG Data Model for Global Trust Anchors"; 776 } 777 */ 778 import ietf-keystore { 779 prefix ks; 780 reference 781 "RFC ZZZZ: 782 YANG Data Model for a Centralized Keystore Mechanism"; 783 } 785 import iana-crypt-hash { 786 prefix ianach; 787 reference 788 "RFC 7317: A YANG Data Model for System Management"; 789 } 791 import ietf-netconf-acm { 792 prefix nacm; 793 reference 794 "RFC 8341: Network Configuration Access Control Model"; 795 } 797 organization 798 "IETF NETCONF (Network Configuration) Working Group"; 800 contact 801 "WG Web: 802 WG List: 803 Author: Kent Watsen 804 Author: Gary Wu "; 806 description 807 "This module defines reusable groupings for SSH servers that 808 can be used as a basis for specific SSH server instances. 810 Copyright (c) 2019 IETF Trust and the persons identified 811 as authors of the code. All rights reserved. 813 Redistribution and use in source and binary forms, with 814 or without modification, is permitted pursuant to, and 815 subject to the license terms contained in, the Simplified 816 BSD License set forth in Section 4.c of the IETF Trust's 817 Legal Provisions Relating to IETF Documents 818 (https://trustee.ietf.org/license-info). 820 This version of this YANG module is part of RFC XXXX 821 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC 822 itself for full legal notices.; 824 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 825 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 826 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 827 are to be interpreted as described in BCP 14 (RFC 2119) 828 (RFC 8174) when, and only when, they appear in all 829 capitals, as shown here."; 831 revision 2019-04-29 { 832 description 833 "Initial version"; 834 reference 835 "RFC XXXX: YANG Groupings for SSH Clients and SSH Servers"; 836 } 838 // Features 840 feature ssh-server-transport-params-config { 841 description 842 "SSH transport layer parameters are configurable on an SSH 843 server."; 844 } 846 feature ssh-server-keepalives { 847 description 848 "Per socket SSH keepalive parameters are configurable for 849 SSH servers on the server implementing this feature."; 850 } 852 feature local-client-auth-supported { 853 description 854 "Indicates that the SSH server supports local configuration 855 of client credentials."; 856 } 857 feature external-client-auth-supported { 858 description 859 "Indicates that the SSH server supports external configuration 860 of client credentials."; 861 } 863 // Groupings 865 grouping ssh-server-grouping { 866 description 867 "A reusable grouping for configuring a SSH server without 868 any consideration for how underlying TCP sessions are 869 established. 871 Note that this grouping uses fairly typical descendent 872 node names such that a stack of 'uses' statements will 873 have name conflicts. It is intended that the consuming 874 data model will resolve the issue (e.g., by wrapping 875 the 'uses' statement in a container called 876 'ssh-server-parameters'). This model purposely does 877 not do this itself so as to provide maximum flexibility 878 to consuming models."; 880 container server-identity { 881 nacm:default-deny-write; 882 description 883 "The list of host-keys the SSH server will present when 884 establishing a SSH connection."; 885 list host-key { 886 key "name"; 887 min-elements 1; 888 ordered-by user; 889 description 890 "An ordered list of host keys the SSH server will use to 891 construct its ordered list of algorithms, when sending 892 its SSH_MSG_KEXINIT message, as defined in Section 7.1 893 of RFC 4253."; 894 reference 895 "RFC 4253: The Secure Shell (SSH) Transport Layer 896 Protocol"; 897 leaf name { 898 type string; 899 description 900 "An arbitrary name for this host-key"; 901 } 902 choice host-key-type { 903 mandatory true; 904 description 905 "The type of host key being specified"; 906 container public-key { 907 uses ks:local-or-keystore-asymmetric-key-grouping; 908 description 909 "A locally-defined or referenced asymmetric key pair 910 to be used for the SSH server's host key."; 911 reference 912 "RFC ZZZZ: YANG Data Model for a Centralized 913 Keystore Mechanism"; 914 } 915 container certificate { 916 if-feature "sshcmn:ssh-x509-certs"; 917 uses 918 ks:local-or-keystore-end-entity-cert-with-key-grouping; 919 description 920 "A locally-defined or referenced end-entity 921 certificate to be used for the SSH server's 922 host key."; 923 reference 924 "RFC ZZZZ: YANG Data Model for a Centralized 925 Keystore Mechanism"; 926 } 927 } 928 } 929 } // container server-identity 931 container client-authentication { 932 nacm:default-deny-write; 933 description 934 "Specifies if SSH client authentication is required or 935 optional, and specifies if the SSH client authentication 936 credentials are configured locally or externally."; 937 container supported-authentication-methods { 938 description 939 "Indicates which authentication methods the server 940 supports."; 941 leaf publickey { 942 type empty; 943 description 944 "Indicates that the 'publickey' method is supported. 945 Note that RFC 6187 X.509v3 Certificates for SSH uses 946 the 'publickey' method name."; 947 reference 948 "RFC 4252: The Secure Shell (SSH) Authentication 949 Protocol. 950 RFC 6187: X.509v3 Certificates for Secure Shell 951 Authentication."; 952 } 953 leaf passsword { 954 type empty; 955 description 956 "Indicates that the 'password' method is supported."; 957 reference 958 "RFC 4252: The Secure Shell (SSH) Authentication 959 Protocol."; 960 } 961 leaf hostbased { 962 type empty; 963 description 964 "Indicates that the 'hostbased' method is supported."; 965 reference 966 "RFC 4252: The Secure Shell (SSH) Authentication 967 Protocol."; 968 } 969 leaf none { 970 type empty; 971 description 972 "Indicates that the 'none' method is supported."; 973 reference 974 "RFC 4252: The Secure Shell (SSH) Authentication 975 Protocol."; 976 } 977 leaf-list other { 978 type string; 979 description 980 "Indicates a supported method name not defined by 981 RFC 4253."; 982 reference 983 "RFC 4252: The Secure Shell (SSH) Authentication 984 Protocol."; 985 } 986 } 987 choice local-or-external { 988 mandatory true; 989 description 990 "Indicates if the client credentials are configured 991 locally or externally."; 992 case local { 993 if-feature "local-client-auth-supported"; 994 description 995 "Client credentials are configured locally."; 996 container users { 997 description 998 "A list of locally configured users."; 999 list user { 1000 key name; 1001 description 1002 "The list of local users configured on this device."; 1004 leaf name { 1005 type string; 1006 description 1007 "The user name string identifying this entry."; 1008 } 1009 leaf password { 1010 type ianach:crypt-hash; 1011 description 1012 "The password for this entry."; 1013 } 1014 list authorized-key { 1015 key name; 1016 description 1017 "A list of public SSH keys for this user. These 1018 keys are allowed for SSH authentication, as 1019 described in RFC 4253."; 1020 reference 1021 "RFC 4253: The Secure Shell (SSH) Transport Layer 1022 Protocol"; 1023 leaf name { 1024 type string; 1025 description 1026 "An arbitrary name for the SSH key."; 1027 } 1028 leaf algorithm { 1029 type string; 1030 mandatory true; 1031 description 1032 "The public key algorithm name for this SSH key. 1034 Valid values are the values in the IANA 'Secure 1035 Shell (SSH) Protocol Parameters' registry, 1036 Public Key Algorithm Names."; 1037 reference 1038 "IANA 'Secure Shell (SSH) Protocol Parameters' 1039 registry, Public Key Algorithm Names"; 1040 } 1041 leaf key-data { 1042 type binary; 1043 mandatory true; 1044 description 1045 "The binary public key data for this SSH key, as 1046 specified by RFC 4253, Section 6.6, i.e.: 1048 string certificate or public key format 1049 identifier 1050 byte[n] key/certificate data."; 1051 reference 1052 "RFC 4253: The Secure Shell (SSH) Transport Layer 1053 Protocol"; 1054 } 1055 } 1056 } // list user 1057 /* 1058 if-feature "sshcmn:ssh-x509-certs"; 1059 description 1060 "A reference to a list of pinned certificate authority 1061 (CA) certificates and a reference to a list of pinned 1062 client certificates."; 1063 leaf pinned-ca-certs { 1064 if-feature "ta:x509-certificates"; 1065 type ta:pinned-certificates-ref; // local or remote 1066 description 1067 "A reference to a list of certificate authority (CA) 1068 certificates used by the SSH server to authenticate 1069 SSH client certificates. A client certificate is 1070 authenticated if it has a valid chain of trust to 1071 a configured pinned CA certificate."; 1072 reference 1073 "RFC YYYY: YANG Data Model for Global Trust Anchors"; 1074 } 1075 leaf pinned-client-certs { 1076 if-feature "ta:x509-certificates"; 1077 type ta:pinned-certificates-ref; // local or remote 1078 description 1079 "A reference to a list of client certificates 1080 used by the SSH server to authenticate SSH 1081 client certificates. A clients certificate 1082 is authenticated if it is an exact match to 1083 a configured pinned client certificate."; 1084 reference 1085 "RFC YYYY: YANG Data Model for Global Trust Anchors"; 1086 } 1087 */ 1088 } // container users 1089 } // case local 1090 case external { 1091 if-feature "external-client-auth-supported"; 1092 description 1093 "Client credentials are configured externally, such 1094 as via RADIUS, RFC 7317, or another mechanism."; 1095 leaf client-auth-defined-elsewhere { 1096 type empty; 1097 description 1098 "Indicates that client credentials are configured 1099 elsewhere."; 1100 } 1101 } 1102 } // choice local-or-external 1103 } // container client-authentication 1105 container transport-params { 1106 nacm:default-deny-write; 1107 if-feature "ssh-server-transport-params-config"; 1108 description 1109 "Configurable parameters of the SSH transport layer."; 1110 uses sshcmn:transport-params-grouping; 1111 } // container transport-params 1113 container keepalives { 1114 nacm:default-deny-write; 1115 if-feature "ssh-server-keepalives"; 1116 presence "Indicates that keepalives are enabled."; 1117 description 1118 "Configures the keep-alive policy, to proactively test 1119 the aliveness of the SSL client. An unresponsive SSL 1120 client is dropped after approximately max-wait * 1121 max-attempts seconds."; 1122 leaf max-wait { 1123 type uint16 { 1124 range "1..max"; 1125 } 1126 units "seconds"; 1127 default "30"; 1128 description 1129 "Sets the amount of time in seconds after which 1130 if no data has been received from the SSL client, 1131 a SSL-level message will be sent to test the 1132 aliveness of the SSL client."; 1133 } 1134 leaf max-attempts { 1135 type uint8; 1136 default "3"; 1137 description 1138 "Sets the maximum number of sequential keep-alive 1139 messages that can fail to obtain a response from 1140 the SSL client before assuming the SSL client is 1141 no longer alive."; 1142 } 1143 } // container keepalives 1144 } // grouping server-identity-grouping 1146 } 1147 1149 5. The SSH Common Model 1151 The SSH common model presented in this section contains identities 1152 and groupings common to both SSH clients and SSH servers. The 1153 transport-params-grouping can be used to configure the list of SSH 1154 transport algorithms permitted by the SSH client or SSH server. The 1155 lists of algorithms are ordered such that, if multiple algorithms are 1156 permitted by the client, the algorithm that appears first in its list 1157 that is also permitted by the server is used for the SSH transport 1158 layer connection. The ability to restrict the algorithms allowed is 1159 provided in this grouping for SSH clients and SSH servers that are 1160 capable of doing so and may serve to make SSH clients and SSH servers 1161 compliant with security policies. 1163 [I-D.ietf-netconf-crypto-types] defines six categories of 1164 cryptographic algorithms (hash-algorithm, symmetric-key-encryption- 1165 algorithm, mac-algorithm, asymmetric-key-encryption-algorithm, 1166 signature-algorithm, key-negotiation-algorithm) and lists several 1167 widely accepted algorithms for each of them. The SSH client and 1168 server models use one or more of these algorithms. The SSH common 1169 model includes four parameters for configuring its permitted SSH 1170 algorithms, which are: host-key-alg, key-exchange-alg, encryption-alg 1171 and mac-alg. The following tables are provided, in part, to define 1172 the subset of algorithms defined in the crypto-types model used by 1173 SSH and, in part, to ensure compatibility of configured SSH 1174 cryptographic parameters for configuring its permitted SSH algorithms 1175 ("sshcmn" representing SSH common model, and "ct" representing 1176 crypto-types model which the SSH client/server model is based on): 1178 +-------------------------------+-------------------------------+ 1179 | sshcmn:host-key-alg | ct:signature-algorithm | 1180 +-------------------------------+-------------------------------+ 1181 | dsa-sha1 | dsa-sha1 | 1182 | rsa-pkcs1-sha1 | rsa-pkcs1-sha1 | 1183 | rsa-pkcs1-sha256 | rsa-pkcs1-sha256 | 1184 | rsa-pkcs1-sha512 | rsa-pkcs1-sha512 | 1185 | ecdsa-secp256r1-sha256 | ecdsa-secp256r1-sha256 | 1186 | ecdsa-secp384r1-sha384 | ecdsa-secp384r1-sha384 | 1187 | ecdsa-secp521r1-sha512 | ecdsa-secp521r1-sha512 | 1188 | x509v3-rsa-pkcs1-sha1 | x509v3-rsa-pkcs1-sha1 | 1189 | x509v3-rsa2048-pkcs1-sha256 | x509v3-rsa2048-pkcs1-sha1 | 1190 | x509v3-ecdsa-secp256r1-sha256 | x509v3-ecdsa-secp256r1-sha256 | 1191 | x509v3-ecdsa-secp384r1-sha384 | x509v3-ecdsa-secp384r1-sha384 | 1192 | x509v3-ecdsa-secp521r1-sha512 | x509v3-ecdsa-secp521r1-sha512 | 1193 +-------------------------------+-------------------------------+ 1195 Table 1 The SSH Host-key-alg Compatibility Matrix 1197 +-------------------------------+-------------------------------+ 1198 | sshcmn:key-exchange-alg | ct:key-negotiation-algorithm | 1199 +-------------------------------+-------------------------------+ 1200 | diffie-hellman-group14-sha1 | diffie-hellman-group14-sha1 | 1201 | diffie-hellman-group14-sha256 | diffie-hellman-group14-sha256 | 1202 | diffie-hellman-group15-sha512 | diffie-hellman-group15-sha512 | 1203 | diffie-hellman-group16-sha512 | diffie-hellman-group16-sha512 | 1204 | diffie-hellman-group17-sha512 | diffie-hellman-group17-sha512 | 1205 | diffie-hellman-group18-sha512 | diffie-hellman-group18-sha512 | 1206 | ecdh-sha2-secp256r1 | ecdh-sha2-secp256r1 | 1207 | ecdh-sha2-secp384r1 | ecdh-sha2-secp384r1 | 1208 +-------------------------------+-------------------------------+ 1210 Table 2 The SSH Key-exchange-alg Compatibility Matrix 1212 +-----------------------+---------------------------------------+ 1213 | sshcmn:encryption-alg | ct:symmetric-key-encryption-algorithm | 1214 +-----------------------+---------------------------------------+ 1215 | aes-128-cbc | aes-128-cbc | 1216 | aes-192-cbc | aes-192-cbc | 1217 | aes-256-cbc | aes-256-cbc | 1218 | aes-128-ctr | aes-128-ctr | 1219 | aes-192-ctr | aes-192-ctr | 1220 | aes-256-ctr | aes-256-ctr | 1221 +-----------------------+---------------------------------------+ 1223 Table 3 The SSH Encryption-alg Compatibility Matrix 1224 +----------------+-------------------+ 1225 | sshcmn:mac-alg | ct:mac-algorithm | 1226 +----------------+-------------------+ 1227 | hmac-sha1 | hmac-sha1 | 1228 | hmac-sha1-96 | hmac-sha1-96 | 1229 | hmac-sha2-256 | hmac-sha2-256 | 1230 | hmac-sha2-512 | hmac-sha2-512 | 1231 +----------------+-------------------+ 1233 Table 4 The SSH Mac-alg Compatibility Matrix 1235 As is seen in the tables above, the names of the "sshcmn" algorithms 1236 are all identical to the names of algorithms defined in 1237 [I-D.ietf-netconf-crypto-types]. While appearing to be redundant, it 1238 is important to realize that not all the algorithms defined in 1239 [I-D.ietf-netconf-crypto-types] are supported by SSH. That is, the 1240 algorithms supported by SSH are a subset of the algorithms defined in 1241 [I-D.ietf-netconf-crypto-types]. The algorithms used by SSH are 1242 redefined in this document in order to constrain the algorithms that 1243 may be selected to just the ones used by SSH. 1245 Features are defined for algorithms that are OPTIONAL or are not 1246 widely supported by popular implementations. Note that the list of 1247 algorithms is not exhaustive. As well, some algorithms that are 1248 REQUIRED by [RFC4253] are missing, notably "ssh-dss" and "diffie- 1249 hellman-group1-sha1" due to their weak security and there being 1250 alternatives that are widely supported. 1252 5.1. Tree Diagram 1254 The following tree diagram [RFC8340] provides an overview of the data 1255 model for the "ietf-ssh-common" module. 1257 module: ietf-ssh-common 1259 grouping transport-params-grouping 1260 +-- host-key 1261 | +-- host-key-alg* identityref 1262 +-- key-exchange 1263 | +-- key-exchange-alg* identityref 1264 +-- encryption 1265 | +-- encryption-alg* identityref 1266 +-- mac 1267 +-- mac-alg* identityref 1269 5.2. Example Usage 1271 This following example illustrates how the transport-params-grouping 1272 appears when populated with some data. 1274 1277 1278 algs:x509v3-rsa2048-sha256 1279 algs:ssh-rsa 1280 1281 1282 1283 algs:diffie-hellman-group-exchange-sha256 1284 1285 1286 1287 algs:aes256-ctr 1288 algs:aes192-ctr 1289 algs:aes128-ctr 1290 algs:aes256-cbc 1291 algs:aes192-cbc 1292 algs:aes128-cbc 1293 1294 1295 algs:hmac-sha2-256 1296 algs:hmac-sha2-512 1297 1298 1300 5.3. YANG Module 1302 This YANG module has normative references to [RFC4253], [RFC4344], 1303 [RFC4419], [RFC5656], [RFC6187], and [RFC6668]. 1305 file "ietf-ssh-common@2019-04-29.yang" 1306 module ietf-ssh-common { 1307 yang-version 1.1; 1308 namespace "urn:ietf:params:xml:ns:yang:ietf-ssh-common"; 1309 prefix sshcmn; 1311 organization 1312 "IETF NETCONF (Network Configuration) Working Group"; 1314 contact 1315 "WG Web: 1316 WG List: 1317 Author: Kent Watsen 1318 Author: Gary Wu "; 1320 description 1321 "This module defines a common features, identities, and 1322 groupings for Secure Shell (SSH). 1324 Copyright (c) 2019 IETF Trust and the persons identified 1325 as authors of the code. All rights reserved. 1327 Redistribution and use in source and binary forms, with 1328 or without modification, is permitted pursuant to, and 1329 subject to the license terms contained in, the Simplified 1330 BSD License set forth in Section 4.c of the IETF Trust's 1331 Legal Provisions Relating to IETF Documents 1332 (https://trustee.ietf.org/license-info). 1334 This version of this YANG module is part of RFC XXXX 1335 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC 1336 itself for full legal notices.; 1338 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1339 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 1340 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 1341 are to be interpreted as described in BCP 14 (RFC 2119) 1342 (RFC 8174) when, and only when, they appear in all 1343 capitals, as shown here."; 1345 revision 2019-04-29 { 1346 description 1347 "Initial version"; 1348 reference 1349 "RFC XXXX: YANG Groupings for SSH Clients and SSH Servers"; 1350 } 1352 // Features 1354 feature ssh-ecc { 1355 description 1356 "Elliptic Curve Cryptography is supported for SSH."; 1357 reference 1358 "RFC 5656: Elliptic Curve Algorithm Integration in the 1359 Secure Shell Transport Layer"; 1360 } 1362 feature ssh-x509-certs { 1363 description 1364 "X.509v3 certificates are supported for SSH per RFC 6187."; 1366 reference 1367 "RFC 6187: X.509v3 Certificates for Secure Shell 1368 Authentication"; 1369 } 1371 feature ssh-dh-group-exchange { 1372 description 1373 "Diffie-Hellman Group Exchange is supported for SSH."; 1374 reference 1375 "RFC 4419: Diffie-Hellman Group Exchange for the 1376 Secure Shell (SSH) Transport Layer Protocol"; 1377 } 1379 feature ssh-ctr { 1380 description 1381 "SDCTR encryption mode is supported for SSH."; 1382 reference 1383 "RFC 4344: The Secure Shell (SSH) Transport Layer 1384 Encryption Modes"; 1385 } 1387 feature ssh-sha2 { 1388 description 1389 "The SHA2 family of cryptographic hash functions is 1390 supported for SSH."; 1391 reference 1392 "FIPS PUB 180-4: Secure Hash Standard (SHS)"; 1393 } 1395 // Identities 1397 identity public-key-alg-base { 1398 description 1399 "Base identity used to identify public key algorithms."; 1400 } 1402 identity ssh-dss { 1403 base public-key-alg-base; 1404 description 1405 "Digital Signature Algorithm using SHA-1 as the 1406 hashing algorithm."; 1407 reference 1408 "RFC 4253: 1409 The Secure Shell (SSH) Transport Layer Protocol"; 1410 } 1412 identity ssh-rsa { 1413 base public-key-alg-base; 1414 description 1415 "RSASSA-PKCS1-v1_5 signature scheme using SHA-1 as the 1416 hashing algorithm."; 1417 reference 1418 "RFC 4253: 1419 The Secure Shell (SSH) Transport Layer Protocol"; 1420 } 1422 identity ecdsa-sha2-nistp256 { 1423 base public-key-alg-base; 1424 if-feature "ssh-ecc and ssh-sha2"; 1425 description 1426 "Elliptic Curve Digital Signature Algorithm (ECDSA) using the 1427 nistp256 curve and the SHA2 family of hashing algorithms."; 1428 reference 1429 "RFC 5656: Elliptic Curve Algorithm Integration in the 1430 Secure Shell Transport Layer"; 1431 } 1433 identity ecdsa-sha2-nistp384 { 1434 base public-key-alg-base; 1435 if-feature "ssh-ecc and ssh-sha2"; 1436 description 1437 "Elliptic Curve Digital Signature Algorithm (ECDSA) using the 1438 nistp384 curve and the SHA2 family of hashing algorithms."; 1439 reference 1440 "RFC 5656: Elliptic Curve Algorithm Integration in the 1441 Secure Shell Transport Layer"; 1442 } 1444 identity ecdsa-sha2-nistp521 { 1445 base public-key-alg-base; 1446 if-feature "ssh-ecc and ssh-sha2"; 1447 description 1448 "Elliptic Curve Digital Signature Algorithm (ECDSA) using the 1449 nistp521 curve and the SHA2 family of hashing algorithms."; 1450 reference 1451 "RFC 5656: Elliptic Curve Algorithm Integration in the 1452 Secure Shell Transport Layer"; 1453 } 1455 identity x509v3-ssh-rsa { 1456 base public-key-alg-base; 1457 if-feature "ssh-x509-certs"; 1458 description 1459 "RSASSA-PKCS1-v1_5 signature scheme using a public key stored 1460 in an X.509v3 certificate and using SHA-1 as the hashing 1461 algorithm."; 1463 reference 1464 "RFC 6187: X.509v3 Certificates for Secure Shell 1465 Authentication"; 1466 } 1468 identity x509v3-rsa2048-sha256 { 1469 base public-key-alg-base; 1470 if-feature "ssh-x509-certs and ssh-sha2"; 1471 description 1472 "RSASSA-PKCS1-v1_5 signature scheme using a public key stored 1473 in an X.509v3 certificate and using SHA-256 as the hashing 1474 algorithm. RSA keys conveyed using this format MUST have a 1475 modulus of at least 2048 bits."; 1476 reference 1477 "RFC 6187: X.509v3 Certificates for Secure Shell 1478 Authentication"; 1479 } 1481 identity x509v3-ecdsa-sha2-nistp256 { 1482 base public-key-alg-base; 1483 if-feature "ssh-ecc and ssh-x509-certs and ssh-sha2"; 1484 description 1485 "Elliptic Curve Digital Signature Algorithm (ECDSA) 1486 using the nistp256 curve with a public key stored in 1487 an X.509v3 certificate and using the SHA2 family of 1488 hashing algorithms."; 1489 reference 1490 "RFC 6187: X.509v3 Certificates for Secure Shell 1491 Authentication"; 1492 } 1494 identity x509v3-ecdsa-sha2-nistp384 { 1495 base public-key-alg-base; 1496 if-feature "ssh-ecc and ssh-x509-certs and ssh-sha2"; 1497 description 1498 "Elliptic Curve Digital Signature Algorithm (ECDSA) 1499 using the nistp384 curve with a public key stored in 1500 an X.509v3 certificate and using the SHA2 family of 1501 hashing algorithms."; 1502 reference 1503 "RFC 6187: X.509v3 Certificates for Secure Shell 1504 Authentication"; 1505 } 1507 identity x509v3-ecdsa-sha2-nistp521 { 1508 base public-key-alg-base; 1509 if-feature "ssh-ecc and ssh-x509-certs and ssh-sha2"; 1510 description 1511 "Elliptic Curve Digital Signature Algorithm (ECDSA) 1512 using the nistp521 curve with a public key stored in 1513 an X.509v3 certificate and using the SHA2 family of 1514 hashing algorithms."; 1515 reference 1516 "RFC 6187: X.509v3 Certificates for Secure Shell 1517 Authentication"; 1518 } 1520 identity key-exchange-alg-base { 1521 description 1522 "Base identity used to identify key exchange algorithms."; 1523 } 1525 identity diffie-hellman-group14-sha1 { 1526 base key-exchange-alg-base; 1527 description 1528 "Diffie-Hellman key exchange with SHA-1 as HASH and 1529 Oakley Group 14 (2048-bit MODP Group)."; 1530 reference 1531 "RFC 4253: The Secure Shell (SSH) Transport Layer Protocol"; 1532 } 1534 identity diffie-hellman-group-exchange-sha1 { 1535 base key-exchange-alg-base; 1536 if-feature "ssh-dh-group-exchange"; 1537 description 1538 "Diffie-Hellman Group and Key Exchange with SHA-1 as HASH."; 1539 reference 1540 "RFC 4419: Diffie-Hellman Group Exchange for the 1541 Secure Shell (SSH) Transport Layer Protocol"; 1542 } 1544 identity diffie-hellman-group-exchange-sha256 { 1545 base key-exchange-alg-base; 1546 if-feature "ssh-dh-group-exchange and ssh-sha2"; 1547 description 1548 "Diffie-Hellman Group and Key Exchange with SHA-256 as HASH."; 1549 reference 1550 "RFC 4419: Diffie-Hellman Group Exchange for the 1551 Secure Shell (SSH) Transport Layer Protocol"; 1552 } 1554 identity ecdh-sha2-nistp256 { 1555 base key-exchange-alg-base; 1556 if-feature "ssh-ecc and ssh-sha2"; 1557 description 1558 "Elliptic Curve Diffie-Hellman (ECDH) key exchange using the 1559 nistp256 curve and the SHA2 family of hashing algorithms."; 1560 reference 1561 "RFC 5656: Elliptic Curve Algorithm Integration in the 1562 Secure Shell Transport Layer"; 1563 } 1565 identity ecdh-sha2-nistp384 { 1566 base key-exchange-alg-base; 1567 if-feature "ssh-ecc and ssh-sha2"; 1568 description 1569 "Elliptic Curve Diffie-Hellman (ECDH) key exchange using the 1570 nistp384 curve and the SHA2 family of hashing algorithms."; 1571 reference 1572 "RFC 5656: Elliptic Curve Algorithm Integration in the 1573 Secure Shell Transport Layer"; 1574 } 1576 identity ecdh-sha2-nistp521 { 1577 base key-exchange-alg-base; 1578 if-feature "ssh-ecc and ssh-sha2"; 1579 description 1580 "Elliptic Curve Diffie-Hellman (ECDH) key exchange using the 1581 nistp521 curve and the SHA2 family of hashing algorithms."; 1582 reference 1583 "RFC 5656: Elliptic Curve Algorithm Integration in the 1584 Secure Shell Transport Layer"; 1585 } 1587 identity encryption-alg-base { 1588 description 1589 "Base identity used to identify encryption algorithms."; 1590 } 1592 identity triple-des-cbc { 1593 base encryption-alg-base; 1594 description 1595 "Three-key 3DES in CBC mode."; 1596 reference 1597 "RFC 4253: The Secure Shell (SSH) Transport Layer Protocol"; 1598 } 1600 identity aes128-cbc { 1601 base encryption-alg-base; 1602 description 1603 "AES in CBC mode, with a 128-bit key."; 1604 reference 1605 "RFC 4253: The Secure Shell (SSH) Transport Layer Protocol"; 1606 } 1607 identity aes192-cbc { 1608 base encryption-alg-base; 1609 description 1610 "AES in CBC mode, with a 192-bit key."; 1611 reference 1612 "RFC 4253: The Secure Shell (SSH) Transport Layer Protocol"; 1613 } 1615 identity aes256-cbc { 1616 base encryption-alg-base; 1617 description 1618 "AES in CBC mode, with a 256-bit key."; 1619 reference 1620 "RFC 4253: The Secure Shell (SSH) Transport Layer Protocol"; 1621 } 1623 identity aes128-ctr { 1624 base encryption-alg-base; 1625 if-feature "ssh-ctr"; 1626 description 1627 "AES in SDCTR mode, with 128-bit key."; 1628 reference 1629 "RFC 4344: The Secure Shell (SSH) Transport Layer Encryption 1630 Modes"; 1631 } 1633 identity aes192-ctr { 1634 base encryption-alg-base; 1635 if-feature "ssh-ctr"; 1636 description 1637 "AES in SDCTR mode, with 192-bit key."; 1638 reference 1639 "RFC 4344: The Secure Shell (SSH) Transport Layer Encryption 1640 Modes"; 1641 } 1643 identity aes256-ctr { 1644 base encryption-alg-base; 1645 if-feature "ssh-ctr"; 1646 description 1647 "AES in SDCTR mode, with 256-bit key."; 1648 reference 1649 "RFC 4344: The Secure Shell (SSH) Transport Layer Encryption 1650 Modes"; 1651 } 1653 identity mac-alg-base { 1654 description 1655 "Base identity used to identify message authentication 1656 code (MAC) algorithms."; 1657 } 1659 identity hmac-sha1 { 1660 base mac-alg-base; 1661 description 1662 "HMAC-SHA1"; 1663 reference 1664 "RFC 4253: The Secure Shell (SSH) Transport Layer Protocol"; 1665 } 1667 identity hmac-sha2-256 { 1668 base mac-alg-base; 1669 if-feature "ssh-sha2"; 1670 description 1671 "HMAC-SHA2-256"; 1672 reference 1673 "RFC 6668: SHA-2 Data Integrity Verification for the 1674 Secure Shell (SSH) Transport Layer Protocol"; 1675 } 1677 identity hmac-sha2-512 { 1678 base mac-alg-base; 1679 if-feature "ssh-sha2"; 1680 description 1681 "HMAC-SHA2-512"; 1682 reference 1683 "RFC 6668: SHA-2 Data Integrity Verification for the 1684 Secure Shell (SSH) Transport Layer Protocol"; 1685 } 1687 // Groupings 1689 grouping transport-params-grouping { 1690 description 1691 "A reusable grouping for SSH transport parameters."; 1692 reference 1693 "RFC 4253: The Secure Shell (SSH) Transport Layer Protocol"; 1694 container host-key { 1695 description 1696 "Parameters regarding host key."; 1697 leaf-list host-key-alg { 1698 type identityref { 1699 base public-key-alg-base; 1700 } 1701 ordered-by user; 1702 description 1703 "Acceptable host key algorithms in order of descending 1704 preference. The configured host key algorithms should 1705 be compatible with the algorithm used by the configured 1706 private key. Please see Section 5 of RFC XXXX for 1707 valid combinations. 1709 If this leaf-list is not configured (has zero elements) 1710 the acceptable host key algorithms are implementation- 1711 defined."; 1712 reference 1713 "RFC XXXX: YANG Groupings for SSH Clients and SSH Servers"; 1714 } 1715 } 1716 container key-exchange { 1717 description 1718 "Parameters regarding key exchange."; 1719 leaf-list key-exchange-alg { 1720 type identityref { 1721 base key-exchange-alg-base; 1722 } 1723 ordered-by user; 1724 description 1725 "Acceptable key exchange algorithms in order of descending 1726 preference. 1728 If this leaf-list is not configured (has zero elements) 1729 the acceptable key exchange algorithms are implementation 1730 defined."; 1731 } 1732 } 1733 container encryption { 1734 description 1735 "Parameters regarding encryption."; 1736 leaf-list encryption-alg { 1737 type identityref { 1738 base encryption-alg-base; 1739 } 1740 ordered-by user; 1741 description 1742 "Acceptable encryption algorithms in order of descending 1743 preference. 1745 If this leaf-list is not configured (has zero elements) 1746 the acceptable encryption algorithms are implementation 1747 defined."; 1748 } 1749 } 1750 container mac { 1751 description 1752 "Parameters regarding message authentication code (MAC)."; 1753 leaf-list mac-alg { 1754 type identityref { 1755 base mac-alg-base; 1756 } 1757 ordered-by user; 1758 description 1759 "Acceptable MAC algorithms in order of descending 1760 preference. 1762 If this leaf-list is not configured (has zero elements) 1763 the acceptable MAC algorithms are implementation- 1764 defined."; 1765 } 1766 } 1767 } 1768 } 1769 1771 6. Security Considerations 1773 The YANG modules defined in this document are designed to be accessed 1774 via YANG based management protocols, such as NETCONF [RFC6241] and 1775 RESTCONF [RFC8040]. Both of these protocols have mandatory-to- 1776 implement secure transport layers (e.g., SSH, TLS) with mutual 1777 authentication. 1779 The NETCONF access control model (NACM) [RFC8341] provides the means 1780 to restrict access for particular users to a pre-configured subset of 1781 all available protocol operations and content. 1783 Since the modules in this document only define groupings, these 1784 considerations are primarily for the designers of other modules that 1785 use these groupings. 1787 There are a number of data nodes defined in the YANG modules that are 1788 writable/creatable/deletable (i.e., config true, which is the 1789 default). These data nodes may be considered sensitive or vulnerable 1790 in some network environments. Write operations (e.g., edit-config) 1791 to these data nodes without proper protection can have a negative 1792 effect on network operations. These are the subtrees and data nodes 1793 and their sensitivity/vulnerability: 1795 *: All of the nodes defined by the grouping statement in both the 1796 "ietf-ssh-client" and "ietf-ssh-server" modules are sensitive 1797 to write operations. For instance, the addition or removal of 1798 references to keys, certificates, trusted anchors, etc., or 1799 even the modification of transport or keepalive parameters can 1800 dramatically alter the implemented security policy. For this 1801 reason, all the nodes are protected the NACM extension 1802 "default-deny-write". 1804 Some of the readable data nodes in the YANG modules may be considered 1805 sensitive or vulnerable in some network environments. It is thus 1806 important to control read access (e.g., via get, get-config, or 1807 notification) to these data nodes. These are the subtrees and data 1808 nodes and their sensitivity/vulnerability: 1810 ssh-client-grouping/client-identity/: This subtree in the "ietf- 1811 ssh-client" module contains nodes that are additionally 1812 sensitive to read operations such that, in normal use cases, 1813 they should never be returned to a client. Specifically, the 1814 descendent nodes 'password', 'public-key/local-definition/ 1815 private-key' and 'certificate/local-definition/private-key'. 1816 For this reason, all of these node are protected by the NACM 1817 extension "default-deny-all". 1819 ssh-server-grouping/server-identity/: This subtree in the "ietf- 1820 ssh-server" module contains nodes that are additionally 1821 sensitive to read operations such that, in normal use cases, 1822 they should never be returned to a client. Specifically, the 1823 descendent nodes 'host-key/public-key/local-definition/private- 1824 key' and 'host-key/certificate/local-definition/private-key'. 1825 For this reason, both of these node are protected by the NACM 1826 extension "default-deny-all". 1828 Some of the operations in this YANG module may be considered 1829 sensitive or vulnerable in some network environments. It is thus 1830 important to control access to these operations. These are the 1831 operations and their sensitivity/vulnerability: 1833 *: The groupings defined in this document include "action" 1834 statements that come from groupings defined in 1835 [I-D.ietf-netconf-crypto-types]. Please consult that document 1836 for the security considerations of the "action" statements 1837 defined by the "grouping" statements defined in this document. 1839 7. IANA Considerations 1841 7.1. The IETF XML Registry 1843 This document registers three URIs in the "ns" subregistry of the 1844 IETF XML Registry [RFC3688]. Following the format in [RFC3688], the 1845 following registrations are requested: 1847 URI: urn:ietf:params:xml:ns:yang:ietf-ssh-client 1848 Registrant Contact: The NETCONF WG of the IETF. 1849 XML: N/A, the requested URI is an XML namespace. 1851 URI: urn:ietf:params:xml:ns:yang:ietf-ssh-server 1852 Registrant Contact: The NETCONF WG of the IETF. 1853 XML: N/A, the requested URI is an XML namespace. 1855 URI: urn:ietf:params:xml:ns:yang:ietf-ssh-common 1856 Registrant Contact: The NETCONF WG of the IETF. 1857 XML: N/A, the requested URI is an XML namespace. 1859 7.2. The YANG Module Names Registry 1861 This document registers three YANG modules in the YANG Module Names 1862 registry [RFC6020]. Following the format in [RFC6020], the following 1863 registrations are requested: 1865 name: ietf-ssh-client 1866 namespace: urn:ietf:params:xml:ns:yang:ietf-ssh-client 1867 prefix: sshc 1868 reference: RFC XXXX 1870 name: ietf-ssh-server 1871 namespace: urn:ietf:params:xml:ns:yang:ietf-ssh-server 1872 prefix: sshs 1873 reference: RFC XXXX 1875 name: ietf-ssh-common 1876 namespace: urn:ietf:params:xml:ns:yang:ietf-ssh-common 1877 prefix: sshcmn 1878 reference: RFC XXXX 1880 8. References 1882 8.1. Normative References 1884 [I-D.ietf-netconf-crypto-types] 1885 Watsen, K. and H. Wang, "Common YANG Data Types for 1886 Cryptography", draft-ietf-netconf-crypto-types-05 (work in 1887 progress), March 2019. 1889 [I-D.ietf-netconf-keystore] 1890 Watsen, K., "YANG Data Model for a Centralized Keystore 1891 Mechanism", draft-ietf-netconf-keystore-08 (work in 1892 progress), March 2019. 1894 [I-D.ietf-netconf-trust-anchors] 1895 Watsen, K., "YANG Data Model for Global Trust Anchors", 1896 draft-ietf-netconf-trust-anchors-03 (work in progress), 1897 March 2019. 1899 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1900 Requirement Levels", BCP 14, RFC 2119, 1901 DOI 10.17487/RFC2119, March 1997, 1902 . 1904 [RFC4344] Bellare, M., Kohno, T., and C. Namprempre, "The Secure 1905 Shell (SSH) Transport Layer Encryption Modes", RFC 4344, 1906 DOI 10.17487/RFC4344, January 2006, 1907 . 1909 [RFC4419] Friedl, M., Provos, N., and W. Simpson, "Diffie-Hellman 1910 Group Exchange for the Secure Shell (SSH) Transport Layer 1911 Protocol", RFC 4419, DOI 10.17487/RFC4419, March 2006, 1912 . 1914 [RFC5656] Stebila, D. and J. Green, "Elliptic Curve Algorithm 1915 Integration in the Secure Shell Transport Layer", 1916 RFC 5656, DOI 10.17487/RFC5656, December 2009, 1917 . 1919 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1920 the Network Configuration Protocol (NETCONF)", RFC 6020, 1921 DOI 10.17487/RFC6020, October 2010, 1922 . 1924 [RFC6187] Igoe, K. and D. Stebila, "X.509v3 Certificates for Secure 1925 Shell Authentication", RFC 6187, DOI 10.17487/RFC6187, 1926 March 2011, . 1928 [RFC6668] Bider, D. and M. Baushke, "SHA-2 Data Integrity 1929 Verification for the Secure Shell (SSH) Transport Layer 1930 Protocol", RFC 6668, DOI 10.17487/RFC6668, July 2012, 1931 . 1933 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1934 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1935 . 1937 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1938 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1939 May 2017, . 1941 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 1942 Access Control Model", STD 91, RFC 8341, 1943 DOI 10.17487/RFC8341, March 2018, 1944 . 1946 8.2. Informative References 1948 [OPENSSH] Project, T. O., "OpenSSH", 2016, . 1950 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1951 DOI 10.17487/RFC3688, January 2004, 1952 . 1954 [RFC4252] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) 1955 Authentication Protocol", RFC 4252, DOI 10.17487/RFC4252, 1956 January 2006, . 1958 [RFC4253] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) 1959 Transport Layer Protocol", RFC 4253, DOI 10.17487/RFC4253, 1960 January 2006, . 1962 [RFC4254] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) 1963 Connection Protocol", RFC 4254, DOI 10.17487/RFC4254, 1964 January 2006, . 1966 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1967 and A. Bierman, Ed., "Network Configuration Protocol 1968 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1969 . 1971 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 1972 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 1973 . 1975 [RFC7317] Bierman, A. and M. Bjorklund, "A YANG Data Model for 1976 System Management", RFC 7317, DOI 10.17487/RFC7317, August 1977 2014, . 1979 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1980 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1981 . 1983 [RFC8071] Watsen, K., "NETCONF Call Home and RESTCONF Call Home", 1984 RFC 8071, DOI 10.17487/RFC8071, February 2017, 1985 . 1987 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 1988 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 1989 . 1991 Appendix A. Change Log 1993 A.1. 00 to 01 1995 o Noted that '0.0.0.0' and '::' might have special meanings. 1997 o Renamed "keychain" to "keystore". 1999 A.2. 01 to 02 2001 o Removed the groupings 'listening-ssh-client-grouping' and 2002 'listening-ssh-server-grouping'. Now modules only contain the 2003 transport-independent groupings. 2005 o Simplified the "client-auth" part in the ietf-ssh-client module. 2006 It now inlines what it used to point to keystore for. 2008 o Added cipher suites for various algorithms into new 'ietf-ssh- 2009 common' module. 2011 A.3. 02 to 03 2013 o Removed 'RESTRICTED' enum from 'password' leaf type. 2015 o Added a 'must' statement to container 'server-auth' asserting that 2016 at least one of the various auth mechanisms must be specified. 2018 o Fixed description statement for leaf 'trusted-ca-certs'. 2020 A.4. 03 to 04 2022 o Change title to "YANG Groupings for SSH Clients and SSH Servers" 2024 o Added reference to RFC 6668 2026 o Added RFC 8174 to Requirements Language Section. 2028 o Enhanced description statement for ietf-ssh-server's "trusted-ca- 2029 certs" leaf. 2031 o Added mandatory true to ietf-ssh-client's "client-auth" 'choice' 2032 statement. 2034 o Changed the YANG prefix for module ietf-ssh-common from 'sshcom' 2035 to 'sshcmn'. 2037 o Removed the compression algorithms as they are not commonly 2038 configurable in vendors' implementations. 2040 o Updating descriptions in transport-params-grouping and the 2041 servers's usage of it. 2043 o Now tree diagrams reference ietf-netmod-yang-tree-diagrams 2045 o Updated YANG to use typedefs around leafrefs to common keystore 2046 paths 2048 o Now inlines key and certificates (no longer a leafref to keystore) 2050 A.5. 04 to 05 2052 o Merged changes from co-author. 2054 A.6. 05 to 06 2056 o Updated to use trust anchors from trust-anchors draft (was 2057 keystore draft) 2059 o Now uses new keystore grouping enabling asymmetric key to be 2060 either locally defined or a reference to the keystore. 2062 A.7. 06 to 07 2064 o factored the ssh-[client|server]-groupings into more reusable 2065 groupings. 2067 o added if-feature statements for the new "ssh-host-keys" and 2068 "x509-certificates" features defined in draft-ietf-netconf-trust- 2069 anchors. 2071 A.8. 07 to 08 2073 o Added a number of compatibility matrices to Section 5 (thanks 2074 Frank!) 2076 o Clarified that any configured "host-key-alg" values need to be 2077 compatible with the configured private key. 2079 A.9. 08 to 09 2081 o Updated examples to reflect update to groupings defined in the 2082 keystore -09 draft. 2084 o Add SSH keepalives features and groupings. 2086 o Prefixed top-level SSH grouping nodes with 'ssh-' and support 2087 mashups. 2089 o Updated copyright date, boilerplate template, affiliation, and 2090 folding algorithm. 2092 A.10. 09 to 10 2094 o Reformatted the YANG modules. 2096 A.11. 10 to 11 2098 o Reformatted lines causing folding to occur. 2100 A.12. 11 to 12 2102 o Collapsed all the inner groupings into the top-level grouping. 2104 o Added a top-level "demux container" inside the top-level grouping. 2106 o Added NACM statements and updated the Security Considerations 2107 section. 2109 o Added "presence" statements on the "keepalive" containers, as was 2110 needed to address a validation error that appeared after adding 2111 the "must" statements into the NETCONF/RESTCONF client/server 2112 modules. 2114 o Updated the boilerplate text in module-level "description" 2115 statement to match copyeditor convention. 2117 A.13. 12 to 13 2119 o Removed the "demux containers", floating the nacm:default-deny- 2120 write to each descendent node, and adding a note to model 2121 designers regarding the potential need to add their own demux 2122 containers. 2124 o Fixed a couple references (section 2 --> section 3) 2126 o In the server model, replaced with and introduced 'local-or-external' choice. 2129 Acknowledgements 2131 The authors would like to thank for following for lively discussions 2132 on list and in the halls (ordered by last name): Andy Bierman, Martin 2133 Bjorklund, Benoit Claise, Mehmet Ersue, Balazs Kovacs, David 2134 Lamparter, Alan Luchuk, Ladislav Lhotka, Radek Krejci, Tom Petch, 2135 Juergen Schoenwaelder, Phil Shafer, Sean Turner, Michal Vasko, and 2136 Bert Wijnen. 2138 Authors' Addresses 2140 Kent Watsen 2141 Watsen Networks 2143 EMail: kent+ietf@watsen.net 2145 Gary Wu 2146 Cisco Systems 2148 EMail: garywu@cisco.com 2150 Liang Xia 2151 Huawei 2153 EMail: frank.xialiang@huawei.com