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