transport/transport-ssh/src/main/yang/ietf-ssh-client@2022-12-12.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 reusable groupings for SSH clients that
  46      can be used as a basis for specific SSH client instances.
  47
  48      Copyright (c) 2022 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 2022-12-12 {
  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 stack 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:local-or-keystore-asymmetric-key-grouping {
 171           refine "local-or-keystore/local/local-definition" {
 172             must 'derived-from-or-self(public-key-format,'
 173                + ' "ct:ssh-public-key-format")';
 174           }
 175           refine "local-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:local-or-keystore-asymmetric-key-grouping {
 205           refine "local-or-keystore/local/local-definition" {
 206             must 'derived-from-or-self(public-key-format,'
 207                + ' "ct:ssh-public-key-format")';
 208           }
 209           refine "local-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 ks:local-or-keystore-end-entity-cert-with-key-grouping {
 235           refine "local-or-keystore/local/local-definition" {
 236             must 'derived-from-or-self(public-key-format,'
 237                + ' "ct:subject-public-key-info-format")';
 238           }
 239           refine "local-or-keystore/keystore/keystore-reference"
 240                + "/asymmetric-key" {
 241             must 'derived-from-or-self(deref(.)/../ks:public-key-'
 242                + 'format, "ct:subject-public-key-info-format")';
 243           }
 244         }
 245       }
 246     } // container client-identity
 247
 248     container server-authentication {
 249       nacm:default-deny-write;
 250       must 'ssh-host-keys or ca-certs or ee-certs';
 251       description
 252         "Specifies how the SSH client can authenticate SSH servers.
 253          Any combination of authentication methods is additive and
 254          unordered.";
 255       container ssh-host-keys {
 256         presence
 257           "Indicates that the SSH host key have been configured.
 258            This statement is present so the mandatory descendant
 259            nodes do not imply that this node must be configured.";
 260         description
 261           "A bag of SSH host keys used by the SSH client to
 262            authenticate SSH server host keys.  A server host key
 263            is authenticated if it is an exact match to a
 264            configured SSH host key.";
 265         reference
 266           "RFC BBBB: A YANG Data Model for a Truststore";
 267         uses ts:local-or-truststore-public-keys-grouping {
 268           refine
 269             "local-or-truststore/local/local-definition/public-key" {
 270             must 'derived-from-or-self(public-key-format,'
 271                + ' "ct:ssh-public-key-format")';
 272           }
 273           refine
 274             "local-or-truststore/truststore/truststore-reference" {
 275             must 'not(deref(.)/../ts:public-key/ts:public-key-'
 276                + 'format[not(derived-from-or-self(., "ct:ssh-'
 277                + 'public-key-format"))])';
 278           }
 279         }
 280       }
 281       container ca-certs {
 282         if-feature "sshcmn:ssh-x509-certs";
 283         presence
 284           "Indicates that the CA certificates have been configured.
 285            This statement is present so the mandatory descendant
 286            nodes do not imply that this node must be configured.";
 287         description
 288           "A set of certificate authority (CA) certificates used by
 289            the SSH client to authenticate SSH servers.  A server
 290            is authenticated if its certificate has a valid chain
 291            of trust to a configured CA certificate.";
 292         reference
 293           "RFC BBBB: A YANG Data Model for a Truststore";
 294         uses ts:local-or-truststore-certs-grouping;
 295       }
 296       container ee-certs {
 297         if-feature "sshcmn:ssh-x509-certs";
 298         presence
 299           "Indicates that the EE certificates have been configured.
 300            This statement is present so the mandatory descendant
 301            nodes do not imply that this node must be configured.";
 302         description
 303           "A set of end-entity certificates used by the SSH client
 304            to authenticate SSH servers.  A server is authenticated
 305            if its certificate is an exact match to a configured
 306            end-entity certificate.";
 307         reference
 308           "RFC BBBB: A YANG Data Model for a Truststore";
 309         uses ts:local-or-truststore-certs-grouping;
 310       }
 311     } // container server-authentication
 312
 313     container transport-params {
 314       nacm:default-deny-write;
 315       if-feature "sshcmn:transport-params";
 316       description
 317         "Configurable parameters of the SSH transport layer.";
 318       uses sshcmn:transport-params-grouping;
 319     } // container transport-parameters
 320
 321     container keepalives {
 322       nacm:default-deny-write;
 323       if-feature "ssh-client-keepalives";
 324       presence
 325         "Indicates that the SSH client proactively tests the
 326          aliveness of the remote SSH server.";
 327       description
 328         "Configures the keep-alive policy, to proactively test
 329          the aliveness of the SSH server.  An unresponsive SSH
 330          server is dropped after approximately max-wait *
 331          max-attempts seconds.  Per Section 4 of RFC 4254,
 332          the SSH client SHOULD send an SSH_MSG_GLOBAL_REQUEST
 333          message with a purposely nonexistent 'request name'
 334          value (e.g., keepalive@ietf.org) and the 'want reply'
 335          value set to '1'.";
 336       reference
 337         "RFC 4254: The Secure Shell (SSH) Connection Protocol";
 338       leaf max-wait {
 339         type uint16 {
 340           range "1..max";
 341         }
 342         units "seconds";
 343         default "30";
 344         description
 345           "Sets the amount of time in seconds after which if
 346            no data has been received from the SSH server, a
 347            SSH-level message will be sent to test the
 348            aliveness of the SSH server.";
 349       }
 350       leaf max-attempts {
 351         type uint8;
 352         default "3";
 353         description
 354           "Sets the maximum number of sequential keep-alive
 355            messages that can fail to obtain a response from
 356            the SSH server before assuming the SSH server is
 357            no longer alive.";
 358       }
 359     } // container keepalives
 360   } // grouping ssh-client-grouping
 361
 362 }