YANG Groupings for TLS Clients and TLS Servers
Extracted elements (29)
The cipher-suite leaf-list is 'ordered-by user' so that preference ordering is explicit and deterministic: during the TLS handshake, the first mutually supported cipher suite in the configured list is selected. An empty list leaves acceptable cipher suites implementation-defined.
The groupings intentionally omit a wrapping container around their 'uses' statements to maximize flexibility for consuming models; consuming modules are expected to resolve potential node name conflicts by wrapping in their own container (e.g., 'tls-client-parameters').
The three IETF modules define 'generic' (least-common-denominator) TLS client/server configurations; advanced features are deliberately left to augmentations by consuming modules, keeping the core groupings minimal and broadly reusable across HTTPS, NETCONF/TLS, and RESTCONF.
The tls-client-grouping and tls-server-grouping intentionally avoid any transport-level configuration (addresses, ports) so that consuming applications can define their own TCP connection strategy; for example, NETCONF Call Home can add TCP call-home configuration alongside the TLS grouping.
The tls12 feature is marked 'status deprecated' because TLS 1.2 (RFC 5246) is obsoleted by TLS 1.3 (RFC 8446) but remains in common use; its retention allows configuration while the deprecation status signals it is NOT RECOMMENDED to enable.
Each of the four authentication methods (X.509 certificates, raw public keys, TLS 1.2 PSKs, TLS 1.3 EPSKs) for both client and server is independently feature-gated, allowing implementations to advertise only the authentication methods they support, consistent with RFC 5280, RFC 7250, RFC 4279, and RFC 8446.
To support both TLS 1.2 and TLS 1.3 simultaneously, the hello-params-grouping cipher-suites configuration should address three parameters: TLS Cipher Suites, TLS SignatureScheme, and TLS Supported Groups, since these cover the algorithm negotiation for both protocol versions.
EPSKs MUST NOT be imported for (D)TLS 1.2 or prior versions; the tls13-epsk container is exclusively for TLS 1.3 EPSKs.
For EPSKs, the hash algorithm MUST be set when the PSK is established (defaulting to SHA-256 if undefined), and each PSK MUST only be used with a single hash function. The server MUST ensure it selects a compatible PSK and cipher suite.
If the client-authentication presence container is not configured on the TLS server, the server SHOULD NOT request that TLS clients provide authentication credentials.
When an EPSK is derived from an external protocol or sequence of protocols, the context leaf MUST include a channel binding for the deriving protocols (per RFC 5056) to mitigate Selfie-style reflection attacks.
When PSKs are provisioned out of band, the PSK identity and the KDF hash algorithm to be used with the PSK MUST also be provisioned out of band.
When the test-peer-aliveness presence container is configured in tls-client-grouping, the TLS client MUST send HeartbeatRequest messages as defined in RFC 6520; an unresponsive server is dropped after approximately max-wait * max-attempts seconds.
The client-authentication presence container in tls-server-grouping (feature client-auth-supported) has a YANG must constraint requiring at least one of ca-certs, ee-certs, raw-public-keys, tls12-psks, or tls13-epsks; its absence signals that the server will not request client credentials.
The client-identity presence container supports a mandatory choice among four authentication methods: certificate (X.509 via inline-or-keystore-end-entity-cert-with-key-grouping), raw-public-key (RFC 7250), tls12-psk (with psk_identity leaf), and tls13-epsk (with external-identity, hash, context, target-protocol, target-kdf leaves). Each method is individually feature-gated.
The epsk-supported-hash typedef enumerates sha-256 and sha-384, representing the hash algorithms supported by an External Pre-Shared Key (EPSK) instance per RFC 8446 §4.2.11; sha-256 is the default for the hash leaf in tls13-epsk containers.
The 'hello-params-grouping' grouping configures permitted TLS versions via min/max identityref leaves and an 'ordered-by user' cipher-suite leaf-list of type tls-cipher-suite-algorithm. It is consumed by both tls-client-grouping and tls-server-grouping.
The 'ietf-tls-client' module defines tls-client-grouping with four top-level containers: client-identity (optional presence), server-authentication (YANG must constraint requiring at least one method), hello-params (feature-gated), and keepalives (feature-gated).
The 'ietf-tls-common' module defines features (tls12, tls13, hello-params, algorithm-discovery, asymmetric-key-pair-generation), TLS version identities (tls12, tls13 derived from tls-version-base), the epsk-supported-hash typedef, and the hello-params-grouping shared by both client and server modules.
The 'ietf-tls-common' module exposes two protocol-accessible nodes: the read-only 'supported-algorithms' container (feature algorithm-discovery) listing cipher suites supported by the device, and the 'generate-asymmetric-key-pair' RPC (feature asymmetric-key-pair-generation) for on-device key generation with cleartext, encrypted, or hidden output options.
The 'ietf-tls-server' module defines tls-server-grouping with server-identity (mandatory choice of certificate, raw-private-key, tls12-psk with id-hint leaf, or tls13-epsk), client-authentication (optional presence, feature client-auth-supported), hello-params, and keepalives.
The keepalives container in tls-client-grouping (feature tls-client-keepalives) configures peer-allowed-to-send (empty leaf permitting inbound HeartbeatRequest) and test-peer-aliveness (presence container with max-wait uint16 default 30s and max-attempts uint8 default 3) using TLS Heartbeat per RFC 6520.
The server-authentication container has a YANG must constraint requiring at least one of ca-certs, ee-certs, raw-public-keys, tls12-psks, or tls13-epsks. PSK-based server authentication requires no extra configuration as the key is shared with client-identity.
The tls13-epsk container (in both client and server modules) captures the EPSK tuple: base key via inline-or-keystore-symmetric-key-grouping, mandatory external-identity string, hash (default sha-256), context string, target-protocol uint16, and target-kdf uint16, satisfying RFC 8446 §4.2.11, RFC 9257 §6, and RFC 9258 §5.1.
RFC 9645 registers four YANG modules in both the IETF XML Registry and the YANG Module Names Registry: ietf-tls-common, ietf-tls-client, ietf-tls-server (all IETF-maintained), and iana-tls-cipher-suite-algs (IANA-maintained).
The 'iana-tls-cipher-suite-algs' YANG module is generated and maintained by IANA using the script in Appendix A, providing YANG enumerations derived from the IANA TLS Cipher Suite registry; this document does not publish the initial version — IANA does.
All writable sensitive data nodes in the TLS client and server groupings (client-identity, server-authentication, hello-params, keepalives, server-identity, client-authentication) carry 'nacm:default-deny-write' to restrict unauthorized modifications via the NETCONF Access Control Model (RFC 8341).
Cleartext private keys returned by the generate-asymmetric-key-pair RPC or configured inline in key definitions introduce exposure risk; the encrypted and hidden private-key-encoding options (leveraging RFC 9642 keystore) are the safer alternatives. Configured cipher suites must be compatible with the private key algorithm in use.
The iana-tls-cipher-suite-algs YANG module enumerates cipher suites from an IANA-maintained registry; implementations must ensure only cryptographically strong cipher suites are enabled, as weakly configured cipher-suite lists can compromise TLS session security.