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