transport/transport-ssh/src/main/yang/ietf-ssh-client@2023-04-17.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-04-17 {
  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
  89        The 'publickey' authentication type is required by
  90        RFC 4252, but common implementations enable it to
  91        be disabled.";
  92     reference
  93       "RFC 4252:
  94         The Secure Shell (SSH) Authentication Protocol";
  95   }
  96
  97   feature client-ident-password {
  98     description
  99       "Indicates that the 'password' authentication type, per
 100        RFC 4252, is supported for client identification.";
 101     reference
 102       "RFC 4252:
 103         The Secure Shell (SSH) Authentication Protocol";
 104   }
 105
 106   feature client-ident-hostbased {
 107     description
 108       "Indicates that the 'hostbased' authentication type, per
 109        RFC 4252, is supported for client identification.";
 110     reference
 111       "RFC 4252:
 112         The Secure Shell (SSH) Authentication Protocol";
 113   }
 114
 115   feature client-ident-none {
 116     description
 117       "Indicates that the 'none' authentication type, per
 118        RFC 4252, is supported for client identification.";
 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 'derived-from-or-self(public-key-format,'
 173                + ' "ct:ssh-public-key-format")';
 174           }
 175           refine "inline-or-keystore/keystore/keystore-reference" {
 176             must 'derived-from-or-self(deref(.)/../ks:public-key-'
 177                + 'format, "ct:ssh-public-key-format")';
 178           }
 179         }
 180       }
 181       container password {
 182         if-feature "client-ident-password";
 183         presence
 184           "Indicates that password-based authentication has been
 185            configured.  This statement is present so the mandatory
 186            descendant nodes do not imply that this node must be
 187            configured.";
 188         description
 189           "A password to be used to authenticate the client's
 190            identity.";
 191         uses ct:password-grouping;
 192       }
 193       container hostbased {
 194         if-feature "client-ident-hostbased";
 195         presence
 196           "Indicates that hostbased authentication is configured.
 197            This statement is present so the mandatory descendant
 198            nodes do not imply that this node must be configured.";
 199         description
 200           "A locally-defined or referenced asymmetric key
 201            pair to be used for host identification.";
 202         reference
 203           "RFC CCCC: A YANG Data Model for a Keystore";
 204         uses ks:inline-or-keystore-asymmetric-key-grouping {
 205           refine "inline-or-keystore/inline/inline-definition" {
 206             must 'derived-from-or-self(public-key-format,'
 207                + ' "ct:ssh-public-key-format")';
 208           }
 209           refine "inline-or-keystore/keystore/keystore-reference" {
 210             must 'derived-from-or-self(deref(.)/../ks:public-key-'
 211                + 'format, "ct:ssh-public-key-format")';
 212           }
 213         }
 214       }
 215       leaf none {
 216         if-feature "client-ident-none";
 217         type empty;
 218         description
 219           "Indicates that 'none' algorithm is used for client
 220            identification.";
 221       }
 222       container certificate {
 223         if-feature "sshcmn:ssh-x509-certs";
 224         presence
 225           "Indicates that certificate-based authentication has been
 226            configured.  This statement is present so the mandatory
 227            descendant nodes do not imply that this node must be
 228            configured.";
 229         description
 230           "A locally-defined or referenced certificate
 231            to be used for client identification.";
 232         reference
 233           "RFC CCCC: A YANG Data Model for a Keystore";
 234         uses
 235           ks:inline-or-keystore-end-entity-cert-with-key-grouping {
 236           refine "inline-or-keystore/inline/inline-definition" {
 237             must 'derived-from-or-self(public-key-format,'
 238                + ' "ct:subject-public-key-info-format")';
 239           }
 240           refine "inline-or-keystore/keystore/keystore-reference"
 241                + "/asymmetric-key" {
 242             must 'derived-from-or-self(deref(.)/../ks:public-key-'
 243                + 'format, "ct:subject-public-key-info-format")';
 244           }
 245         }
 246       }
 247     } // container client-identity
 248
 249     container server-authentication {
 250       nacm:default-deny-write;
 251       must 'ssh-host-keys or ca-certs or ee-certs';
 252       description
 253         "Specifies how the SSH client can authenticate SSH servers.
 254          Any combination of authentication methods is additive and
 255          unordered.";
 256       container ssh-host-keys {
 257         presence
 258           "Indicates that the SSH host key have been configured.
 259            This statement is present so the mandatory descendant
 260            nodes do not imply that this node must be configured.";
 261         description
 262           "A bag of SSH host keys used by the SSH client to
 263            authenticate SSH server host keys.  A server host key
 264            is authenticated if it is an exact match to a
 265            configured SSH host key.";
 266         reference
 267           "RFC BBBB: A YANG Data Model for a Truststore";
 268         uses ts:inline-or-truststore-public-keys-grouping {
 269           refine
 270             "inline-or-truststore/inline/inline-definition/public"
 271             + "-key" {
 272             must 'derived-from-or-self(public-key-format,'
 273                + ' "ct:ssh-public-key-format")';
 274           }
 275           refine
 276             "inline-or-truststore/truststore/truststore-reference" {
 277             must 'not(deref(.)/../ts:public-key/ts:public-key-'
 278                + 'format[not(derived-from-or-self(., "ct:ssh-'
 279                + 'public-key-format"))])';
 280           }
 281         }
 282       }
 283       container ca-certs {
 284         if-feature "sshcmn:ssh-x509-certs";
 285         presence
 286           "Indicates that the CA certificates have been configured.
 287            This statement is present so the mandatory descendant
 288            nodes do not imply that this node must be configured.";
 289         description
 290           "A set of certificate authority (CA) certificates used by
 291            the SSH client to authenticate SSH servers.  A server
 292            is authenticated if its certificate has a valid chain
 293            of trust to a configured CA certificate.";
 294         reference
 295           "RFC BBBB: A YANG Data Model for a Truststore";
 296         uses ts:inline-or-truststore-certs-grouping;
 297       }
 298       container ee-certs {
 299         if-feature "sshcmn:ssh-x509-certs";
 300         presence
 301           "Indicates that the EE certificates have been configured.
 302            This statement is present so the mandatory descendant
 303            nodes do not imply that this node must be configured.";
 304         description
 305           "A set of end-entity certificates used by the SSH client
 306            to authenticate SSH servers.  A server is authenticated
 307            if its certificate is an exact match to a configured
 308            end-entity certificate.";
 309         reference
 310           "RFC BBBB: A YANG Data Model for a Truststore";
 311         uses ts:inline-or-truststore-certs-grouping;
 312       }
 313     } // container server-authentication
 314
 315     container transport-params {
 316       nacm:default-deny-write;
 317       if-feature "sshcmn:transport-params";
 318       description
 319         "Configurable parameters of the SSH transport layer.";
 320       uses sshcmn:transport-params-grouping;
 321     } // container transport-parameters
 322
 323     container keepalives {
 324       nacm:default-deny-write;
 325       if-feature "ssh-client-keepalives";
 326       presence
 327         "Indicates that the SSH client proactively tests the
 328          aliveness of the remote SSH server.";
 329       description
 330         "Configures the keep-alive policy, to proactively test
 331          the aliveness of the SSH server.  An unresponsive SSH
 332          server is dropped after approximately max-wait *
 333          max-attempts seconds.  Per Section 4 of RFC 4254,
 334          the SSH client SHOULD send an SSH_MSG_GLOBAL_REQUEST
 335          message with a purposely nonexistent 'request name'
 336          value (e.g., keepalive@ietf.org) and the 'want reply'
 337          value set to '1'.";
 338       reference
 339         "RFC 4254: The Secure Shell (SSH) Connection Protocol";
 340       leaf max-wait {
 341         type uint16 {
 342           range "1..max";
 343         }
 344         units "seconds";
 345         default "30";
 346         description
 347           "Sets the amount of time in seconds after which if
 348            no data has been received from the SSH server, a
 349            SSH-level message will be sent to test the
 350            aliveness of the SSH server.";
 351       }
 352       leaf max-attempts {
 353         type uint8;
 354         default "3";
 355         description
 356           "Sets the maximum number of sequential keep-alive
 357            messages that can fail to obtain a response from
 358            the SSH server before assuming the SSH server is
 359            no longer alive.";
 360       }
 361     } // container keepalives
 362   } // grouping ssh-client-grouping
 363
 364 }