transport/transport-ssh/src/main/yang/ietf-ssh-client@2023-12-28.yang

   1 module ietf-ssh-client {
   2   yang-version 1.1;
   3   namespace "urn:ietf:params:xml:ns:yang:ietf-ssh-client";
   4   prefix sshc;
   5
   6   import ietf-netconf-acm {
   7     prefix nacm;
   8     reference
   9       "RFC 8341: Network Configuration Access Control Model";
  10   }
  11
  12   import ietf-crypto-types {
  13     prefix ct;
  14     reference
  15       "RFC AAAA: YANG Data Types and Groupings for Cryptography";
  16   }
  17
  18   import ietf-truststore {
  19     prefix ts;
  20     reference
  21       "RFC BBBB: A YANG Data Model for a Truststore";
  22   }
  23
  24   import ietf-keystore {
  25     prefix ks;
  26     reference
  27       "RFC CCCC: A YANG Data Model for a Keystore";
  28   }
  29
  30   import ietf-ssh-common {
  31     prefix sshcmn;
  32     reference
  33       "RFC EEEE: YANG Groupings for SSH Clients and SSH Servers";
  34   }
  35
  36   organization
  37     "IETF NETCONF (Network Configuration) Working Group";
  38
  39   contact
  40     "WG Web:   https://datatracker.ietf.org/wg/netconf
  41      WG List:  NETCONF WG list <mailto:netconf@ietf.org>
  42      Author:   Kent Watsen <mailto:kent+ietf@watsen.net>";
  43
  44   description
  45     "This module defines a reusable grouping for SSH clients that
  46      can be used as a basis for specific SSH client instances.
  47
  48      Copyright (c) 2023 IETF Trust and the persons identified
  49      as authors of the code. All rights reserved.
  50
  51      Redistribution and use in source and binary forms, with
  52      or without modification, is permitted pursuant to, and
  53      subject to the license terms contained in, the Revised
  54      BSD License set forth in Section 4.c of the IETF Trust's
  55      Legal Provisions Relating to IETF Documents
  56      (https://trustee.ietf.org/license-info).
  57
  58      This version of this YANG module is part of RFC EEEE
  59      (https://www.rfc-editor.org/info/rfcEEEE); see the RFC
  60      itself for full legal notices.
  61
  62      The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL',
  63      'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED',
  64      'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document
  65      are to be interpreted as described in BCP 14 (RFC 2119)
  66      (RFC 8174) when, and only when, they appear in all
  67      capitals, as shown here.";
  68
  69   revision 2023-12-28 {
  70     description
  71       "Initial version";
  72     reference
  73       "RFC EEEE: YANG Groupings for SSH Clients and SSH Servers";
  74   }
  75
  76   // Features
  77
  78   feature ssh-client-keepalives {
  79     description
  80       "Per socket SSH keepalive parameters are configurable for
  81        SSH clients on the server implementing this feature.";
  82   }
  83
  84   feature client-ident-publickey {
  85     description
  86       "Indicates that the 'publickey' authentication type, per
  87        RFC 4252, is supported for client identification.
  88        The 'publickey' authentication type is required by
  89        RFC 4252, but common implementations allow it to
  90        be disabled.";
  91     reference
  92       "RFC 4252:
  93         The Secure Shell (SSH) Authentication Protocol";
  94   }
  95
  96   feature client-ident-password {
  97     description
  98       "Indicates that the 'password' authentication type, per
  99        RFC 4252, is supported for client identification.";
 100     reference
 101       "RFC 4252:
 102         The Secure Shell (SSH) Authentication Protocol";
 103   }
 104
 105   feature client-ident-hostbased {
 106     description
 107       "Indicates that the 'hostbased' authentication type, per
 108        RFC 4252, is supported for client identification.";
 109     reference
 110       "RFC 4252:
 111         The Secure Shell (SSH) Authentication Protocol";
 112   }
 113
 114   feature client-ident-none {
 115     description
 116       "Indicates that the 'none' authentication type, per
 117        RFC 4252, is supported for client identification.
 118        It is NOT RECOMMENDED to enable this feature.";
 119     reference
 120       "RFC 4252:
 121         The Secure Shell (SSH) Authentication Protocol";
 122   }
 123
 124   // Groupings
 125
 126   grouping ssh-client-grouping {
 127     description
 128       "A reusable grouping for configuring a SSH client without
 129        any consideration for how an underlying TCP session is
 130        established.
 131
 132        Note that this grouping uses fairly typical descendant
 133        node names such that a nesting of 'uses' statements will
 134        have name conflicts.  It is intended that the consuming
 135        data model will resolve the issue (e.g., by wrapping
 136        the 'uses' statement in a container called
 137        'ssh-client-parameters').  This model purposely does
 138        not do this itself so as to provide maximum flexibility
 139        to consuming models.";
 140
 141     container client-identity {
 142       nacm:default-deny-write;
 143       description
 144         "The username and authentication methods for the client.
 145          The authentication methods are unordered.  Clients may
 146          initially send any configured method or, per RFC 4252,
 147          Section 5.2, send the 'none' method to prompt the server
 148          to provide a list of productive methods.  Whenever a
 149          choice amongst methods arises, implementations SHOULD
 150          use a default ordering that prioritizes automation
 151          over human-interaction.";
 152       leaf username {
 153         type string;
 154         description
 155           "The username of this user.  This will be the username
 156            used, for instance, to log into an SSH server.";
 157       }
 158       container public-key {
 159         if-feature "client-ident-publickey";
 160         presence
 161           "Indicates that publickey-based authentication has been
 162            configured.  This statement is present so the mandatory
 163            descendant nodes do not imply that this node must be
 164            configured.";
 165         description
 166           "A locally-defined or referenced asymmetric key
 167            pair to be used for client identification.";
 168         reference
 169           "RFC CCCC: A YANG Data Model for a Keystore";
 170         uses ks:inline-or-keystore-asymmetric-key-grouping {
 171           refine "inline-or-keystore/inline/inline-definition" {
 172             must 'not(public-key-format) or derived-from-or-self'
 173                + '(public-key-format, "ct:ssh-public-key-format")';
 174           }
 175           refine "inline-or-keystore/central-keystore/"
 176                + "central-keystore-reference" {
 177             must 'not(deref(.)/../ks:public-key-format) or derived-'
 178                + 'from-or-self(deref(.)/../ks:public-key-format, '
 179                + '"ct:ssh-public-key-format")';
 180           }
 181         }
 182       }
 183       container password {
 184         if-feature "client-ident-password";
 185         presence
 186           "Indicates that password-based authentication has been
 187            configured.  This statement is present so the mandatory
 188            descendant nodes do not imply that this node must be
 189            configured.";
 190         description
 191           "A password to be used to authenticate the client's
 192            identity.";
 193         uses ct:password-grouping;
 194       }
 195       container hostbased {
 196         if-feature "client-ident-hostbased";
 197         presence
 198           "Indicates that hostbased authentication is configured.
 199            This statement is present so the mandatory descendant
 200            nodes do not imply that this node must be configured.";
 201         description
 202           "A locally-defined or referenced asymmetric key
 203            pair to be used for host identification.";
 204         reference
 205           "RFC CCCC: A YANG Data Model for a Keystore";
 206         uses ks:inline-or-keystore-asymmetric-key-grouping {
 207           refine "inline-or-keystore/inline/inline-definition" {
 208             must 'not(public-key-format) or derived-from-or-self('
 209                + 'public-key-format, "ct:ssh-public-key-format")';
 210           }
 211           refine "inline-or-keystore/central-keystore/"
 212                + "central-keystore-reference" {
 213             must 'not(deref(.)/../ks:public-key-format) or derived-'
 214                + 'from-or-self(deref(.)/../ks:public-key-format, '
 215                + '"ct:ssh-public-key-format")';
 216           }
 217         }
 218       }
 219       leaf none {
 220         if-feature "client-ident-none";
 221         type empty;
 222         description
 223           "Indicates that 'none' algorithm is used for client
 224            identification.";
 225       }
 226       container certificate {
 227         if-feature "sshcmn:ssh-x509-certs";
 228         presence
 229           "Indicates that certificate-based authentication has been
 230            configured.  This statement is present so the mandatory
 231            descendant nodes do not imply that this node must be
 232            configured.";
 233         description
 234           "A locally-defined or referenced certificate
 235            to be used for client identification.";
 236         reference
 237           "RFC CCCC: A YANG Data Model for a Keystore";
 238         uses
 239           ks:inline-or-keystore-end-entity-cert-with-key-grouping {
 240           refine "inline-or-keystore/inline/inline-definition" {
 241             must 'not(public-key-format) or derived-from-or-self('
 242                + 'public-key-format, "ct:subject-public-key-info-'
 243                + 'format")';
 244           }
 245           refine "inline-or-keystore/central-keystore/"
 246                + "central-keystore-reference/asymmetric-key" {
 247             must 'not(deref(.)/../ks:public-key-format) or derived-'
 248                + 'from-or-self(deref(.)/../ks:public-key-format, '
 249                + '"ct:subject-public-key-info-format")';
 250           }
 251         }
 252       }
 253     } // container client-identity
 254
 255     container server-authentication {
 256       nacm:default-deny-write;
 257       must 'ssh-host-keys or ca-certs or ee-certs';
 258       description
 259         "Specifies how the SSH client can authenticate SSH servers.
 260          Any combination of authentication methods is additive and
 261          unordered.";
 262       container ssh-host-keys {
 263         presence
 264           "Indicates that the SSH host key have been configured.
 265            This statement is present so the mandatory descendant
 266            nodes do not imply that this node must be configured.";
 267         description
 268           "A bag of SSH host keys used by the SSH client to
 269            authenticate SSH server host keys.  A server host key
 270            is authenticated if it is an exact match to a
 271            configured SSH host key.";
 272         reference
 273           "RFC BBBB: A YANG Data Model for a Truststore";
 274         uses ts:inline-or-truststore-public-keys-grouping {
 275           refine
 276             "inline-or-truststore/inline/inline-definition/public"
 277             + "-key" {
 278             must 'derived-from-or-self(public-key-format,'
 279                + ' "ct:ssh-public-key-format")';
 280           }
 281           refine "inline-or-truststore/central-truststore/"
 282                + "central-truststore-reference" {
 283             must 'not(deref(.)/../ts:public-key/ts:public-key-'
 284                + 'format[not(derived-from-or-self(., "ct:ssh-'
 285                + 'public-key-format"))])';
 286           }
 287         }
 288       }
 289       container ca-certs {
 290         if-feature "sshcmn:ssh-x509-certs";
 291         presence
 292           "Indicates that the CA certificates have been configured.
 293            This statement is present so the mandatory descendant
 294            nodes do not imply that this node must be configured.";
 295         description
 296           "A set of certificate authority (CA) certificates used by
 297            the SSH client to authenticate SSH servers.  A server
 298            is authenticated if its certificate has a valid chain
 299            of trust to a configured CA certificate.";
 300         reference
 301           "RFC BBBB: A YANG Data Model for a Truststore";
 302         uses ts:inline-or-truststore-certs-grouping;
 303       }
 304       container ee-certs {
 305         if-feature "sshcmn:ssh-x509-certs";
 306         presence
 307           "Indicates that the EE certificates have been configured.
 308            This statement is present so the mandatory descendant
 309            nodes do not imply that this node must be configured.";
 310         description
 311           "A set of end-entity certificates used by the SSH client
 312            to authenticate SSH servers.  A server is authenticated
 313            if its certificate is an exact match to a configured
 314            end-entity certificate.";
 315         reference
 316           "RFC BBBB: A YANG Data Model for a Truststore";
 317         uses ts:inline-or-truststore-certs-grouping;
 318       }
 319     } // container server-authentication
 320
 321     container transport-params {
 322       nacm:default-deny-write;
 323       if-feature "sshcmn:transport-params";
 324       description
 325         "Configurable parameters of the SSH transport layer.";
 326       uses sshcmn:transport-params-grouping;
 327     } // container transport-parameters
 328
 329     container keepalives {
 330       nacm:default-deny-write;
 331       if-feature "ssh-client-keepalives";
 332       presence
 333         "Indicates that the SSH client proactively tests the
 334          aliveness of the remote SSH server.";
 335       description
 336         "Configures the keep-alive policy, to proactively test
 337          the aliveness of the SSH server.  An unresponsive SSH
 338          server is dropped after approximately max-wait *
 339          max-attempts seconds.  Per Section 4 of RFC 4254,
 340          the SSH client SHOULD send an SSH_MSG_GLOBAL_REQUEST
 341          message with a purposely nonexistent 'request name'
 342          value (e.g., keepalive@ietf.org) and the 'want reply'
 343          value set to '1'.";
 344       reference
 345         "RFC 4254: The Secure Shell (SSH) Connection Protocol";
 346       leaf max-wait {
 347         type uint16 {
 348           range "1..max";
 349         }
 350         units "seconds";
 351         default "30";
 352         description
 353           "Sets the amount of time in seconds after which if
 354            no data has been received from the SSH server, a
 355            SSH-level message will be sent to test the
 356            aliveness of the SSH server.";
 357       }
 358       leaf max-attempts {
 359         type uint8;
 360         default "3";
 361         description
 362           "Sets the maximum number of sequential keep-alive
 363            messages that can fail to obtain a response from
 364            the SSH server before assuming the SSH server is
 365            no longer alive.";
 366       }
 367     } // container keepalives
 368   } // grouping ssh-client-grouping
 369
 370 }