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