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