YANG Groupings for SSH Clients and SSH Servers
Extracted elements (29)
The four IANA algorithm YANG modules are not published within this RFC; instead, Appendix A provides a generating script for IANA to produce and maintain these modules directly, keeping YANG enumerations synchronized with IANA registry updates without requiring RFC updates.
The groupings intentionally avoid wrapping 'uses' statements in a named container to provide maximum flexibility to consuming models; consuming modules are expected to resolve name conflicts by wrapping the 'uses' statement in an appropriately named container (e.g., 'ssh-client-parameters').
The ssh-client-grouping and ssh-server-grouping explicitly exclude all transport-level configuration (ports, addresses) to allow consuming modules to define their own TCP connection strategy, enabling reuse in diverse scenarios such as NETCONF Call Home (RFC 8071) without modification.
Optional support for RFC 6187 (X.509v3 Certificates for SSH Authentication) is gated by the 'ssh-x509-certs' feature in ietf-ssh-common; when enabled, clients may authenticate via certificates and servers may validate client certificates against CA or end-entity trust anchors.
These SSH groupings are designed to be used in conjunction with transport-level groupings from RFC 9643 (YANG Groupings for TCP Clients and TCP Servers), which provides remote/local address and port configuration. The SSH modules focus exclusively on SSH-layer parameters.
Enabling the 'client-ident-none' feature (SSH client) or 'local-user-auth-none' feature (SSH server) is NOT RECOMMENDED, as the 'none' authentication method provides no credential-based security.
The SSH client and server SHOULD send SSH_MSG_GLOBAL_REQUEST with a purposely nonexistent 'request name' value (e.g., [email protected]) and 'want reply' set to '1' to perform keepalive aliveness testing, per Section 4 of RFC 4254.
The SSH server SHOULD derive the list of authentication method names returned to the SSH client from the descendant nodes configured in the local user entry, per Sections 5.1 and 5.2 of RFC 4252.
Whenever a choice among authentication methods arises for either client or server, implementations SHOULD use a default ordering that prioritizes automation over human interaction.
Algorithm typedefs (ssh-public-key-algorithm, ssh-key-exchange-algorithm, ssh-encryption-algorithm, ssh-mac-algorithm) each accept either an IANA-maintained enumeration value from the corresponding IANA module or a locally defined string of 1-64 characters that MUST contain '@', per RFC 4250 Section 4.6.1.
Local user authentication in 'client-authentication/users/user' supports: public-keys (set of SSH public keys for exact-match), hashed-password (ianach:crypt-hash type with read-only last-modified timestamp), hostbased (set of host keys), and none — each gated by its own feature dependent on 'local-users-supported'.
The 'client-identity' container supports five authentication methods, each enabled by a separate feature: public-key (inline or keystore reference), password, hostbased (inline or keystore reference), none, and certificate (X.509v3, requires ssh-x509-certs feature). Methods are unordered.
The 'generate-asymmetric-key-pair' RPC (feature-gated) requests the device to generate an asymmetric key pair for a specified SSH public key algorithm, with mandatory choice of private-key-encoding: cleartext, encrypted (via keystore reference), or hidden. Output is either the key pair or an instance-identifier pointing to the hidden key's location.
The 'ietf-ssh-common' YANG module defines four features (ssh-x509-certs, transport-params, asymmetric-key-pair-generation, algorithm-discovery), four algorithm typedefs, the 'transport-params-grouping' grouping, an operational 'supported-algorithms' container, and a 'generate-asymmetric-key-pair' RPC. It is imported by both ietf-ssh-client and ietf-ssh-server.
The 'keepalives' presence container configures SSH-layer aliveness probing using SSH_MSG_GLOBAL_REQUEST, with leaf max-wait (uint16, default 30 seconds) and max-attempts (uint8, default 3); an unresponsive peer is dropped after approximately max-wait * max-attempts seconds.
The 'server-authentication' container has a YANG must constraint requiring at least one of ssh-host-keys, ca-certs (X.509 CA certs, feature-gated), or ee-certs (end-entity certs, feature-gated) to be present; server host keys are authenticated by exact match against configured SSH host keys.
The 'server-identity/host-key' list is ordered-by user and requires min-elements 1; each entry presents either a public-key (inline or keystore asymmetric key) or a certificate (X.509v3, feature-gated). The server uses this ordered list to construct its SSH_MSG_KEXINIT algorithm list per RFC 4253 Section 7.1.
The 'ssh-client-grouping' grouping in ietf-ssh-client defines four containers: 'client-identity' (username and authentication methods), 'server-authentication' (trust anchors for server validation), 'transport-params' (feature-gated, references transport-params-grouping), and 'keepalives' (feature-gated, aliveness testing). All containers carry nacm:default-deny-write.
The 'ssh-server-grouping' grouping in ietf-ssh-server defines four containers: 'server-identity' (ordered list of host keys with min-elements 1), 'client-authentication' (local users and X.509 trust anchors), 'transport-params' (feature-gated), and 'keepalives' (feature-gated).
The 'supported-algorithms' read-only container (feature-gated by 'algorithm-discovery') exposes operational state listing all public-key, encryption, key-exchange, and MAC algorithms supported by the implementation.
The 'transport-params-grouping' grouping configures four ordered (ordered-by user) leaf-lists of acceptable SSH algorithms: host-key-alg, key-exchange-alg, encryption-alg, and mac-alg, each in decreasing order of preference. If a leaf-list has zero elements, acceptable algorithms are implementation-defined.
The 'iana-ssh-encryption-algs' YANG module provides YANG enumerations for IANA's SSH encryption algorithm registry. IANA publishes and maintains this module; RFC 9644 provides only the generating script (Appendix A), not the initial module content.
The 'iana-ssh-key-exchange-algs' YANG module provides YANG enumerations for IANA's SSH key exchange algorithm registry. IANA publishes and maintains this module.
The 'iana-ssh-mac-algs' YANG module provides YANG enumerations for IANA's SSH MAC algorithm registry. IANA publishes and maintains this module.
The 'iana-ssh-public-key-algs' YANG module provides YANG enumerations for IANA's SSH public key algorithm registry. IANA publishes and maintains this module.
All writable data nodes in the ssh-client-grouping and ssh-server-grouping containers (client-identity, server-authentication, transport-params, keepalives, server-identity, client-authentication) are annotated with nacm:default-deny-write, restricting write access to users with explicit NACM permissions.
Private keys in client identity and server identity configuration are sensitive; the 'generate-asymmetric-key-pair' RPC supports encrypted or hidden encoding options to avoid exposure of cleartext private key material via NETCONF.
The IANA SSH algorithm YANG modules may enumerate deprecated or weak algorithms; operators SHOULD use the transport-params-grouping to explicitly restrict acceptable algorithms to strong, current options rather than relying on implementation defaults.
The three IETF YANG modules define groupings only and will not be deployed standalone; their security implications are context-dependent, and designers of modules that import these groupings must conduct their own security analysis.