NETCONF Over TLS

The NETCONF over TLS protocol is defined in RFC 7589

If the server image is built with the WITH_OPENSSL=1 parameter (or EVERYTHING=1 parameter) then NETCONF over TLS support will be available.

RFC 9918 Transport Policy

RFC 9918 updates NETCONF over TLS to recommend TLS 1.3 while retaining mutually authenticated TLS 1.2 support. The negotiating OpenSSL methods allow TLS 1.3 when supported by the linked library and its policy. NETCONF early data is explicitly disabled on TLS 1.3 builds.

In normal mutual authentication mode the server requires a client certificate during the handshake, then applies the certificate-to-name mapping and allowed-user checks before admitting the NETCONF session. The existing common-authentication and DEBUG compatibility modes remain explicit exceptions to secure operation.

The default minimum TLS version is set to 1.2 during negotiation on OpenSSL builds supporting protocol bounds. --tls-v1.3-only raises the minimum to 1.3 and fails initialization when the library cannot support it. --tls-deprecated-ok retains its compatibility behavior when 1.3-only mode is disabled. Negotiated versions are also checked before admission.

Invalid --tls-cipherlist settings, failures to load or match the server certificate/key, and failures to install configured CRL verification flags fail TLS initialization. The cipher-list option affects TLS 1.2 and earlier; TLS 1.3 suites remain subject to OpenSSL defaults and system policy. No new server CLI parameter is required for these fixes. Supported binaries still require TLS 1.2/1.3 interoperability, mandatory cipher, early-data rejection, certificate-negative, and NETCONF framing/closure qualification; these changes do not certify conformance.

TLS Configuration

The following CLI and configuration parameters are available to support NETCONF over TLS sessions:

CLI Parameters for NETCONF over TLS

Parameter

Default

Description

--cert-default-user

DEBUG only default user-name to use if no user-certmap found for an incoming NETCONF over TLS session

--cert-usermap

Map a client user-name to a X.509 fingerprint for the client certificate. Required for each user name to be used with NETCONF over TLS. Use yumaworks-cert-usermap.yang to configure X.509 cert-to-name entries at runtime.

--insecure-ok

false

DEBUG only option to accept client certificates that cannot be verified in the local truststore

--netconf-tls-address

0.0.0.0

The IP address to listen for NETCONF over TLS sessions.

--netconf-tls-certificate

$HOME/.ssl/netconfd-pro.crt

The public certificate file that must be provided to use NETCONF over TLS

--netconf-tls-key

$HOME/.ssl/netconfd-pro.key

The private certificate file that must be provided to use NETCONF over TLS

--netconf-tls-port

6513

The TCP port to listen for NETCONF over TLS sessions.

--netconf-tls-trust-store

$HOME/.ssl/trust-store.pem

The file or directory to look for client certificates to determine if they are trusted

--with-netconf-tls

false

This flag must be set to true to enable NETCONF over TLS

--tcp-connect-timeout

10

The number of seconds to wait for the TCP connect function to finish

--tcp-keepalive-count

0

The number of TCP keepalive requests that can be missed for a TCP connection

--tcp-keepalive-enabled

false

Controls whether TCP keepalive requests will be used

--tcp-keepalive-interval

0

The number of seconds to wait between TCP keepalive requests

--tls-autosan-mode

false

Automatically use a valid Subject Alternate Name as the username

--tls-cipherlist

Specifies advanced OpenSSL cipher configuration settings.

--tls-common-auth

false

Specifies TLS Common Authentication should be used instead of Mutual Authentication.

--tls-crl-missing-ok

false

Specifies whether missing CRL Distribution Point is an error

--tls-crl-mode

off

Specifies how Certificate Revocation List processing is done

--tls-debug

false

Enable extended NETCONF over TLS logging information

--tls-deprecated-ok

false

Allow deprecated versions of TLS to be used

--tls-v1.3-only

false

Require TLS version 1.3 to be used for NETCONF over TLS sessions

RPC Operations for NETCONF over TLS

The <reload-netconf-tls-keypair> operation can be used to update the server certificate and key files while the server is running, without any disruption to existing NETCONF over TLS sessions.

The yumaworks-server.yang module must be loaded for this operation to be available. The --tls-debug parameter can also be changed at run-time if this module is loaded.

YANG Module for NETCONF over TLS

The yumaworks-cert-usermap.yang module provides YANG configuration of the certificate to user name mappings. This YANG module implements the Client Identity procedures defined in section 6 of RFC 7589.

The 'cert-to-name' grouping defined in the ietf-x509-cert-to-name.yang module is adapted for use with NETCONF over TLS, even though RFC 7407 is defined for SNMP over TLS configuration. The TLS usage is the same in both protocols.

The Subject Alternate Name (SAN) fields described in RFC 7589 are supported. The Common Name (CN) field is supported but it is deprecated and SAN fields should be used instead.

Note

When checking a client X.509 certificate for a username mapping:

  • The server will check all --cert-usermap parameters first.

  • The server will then check all 'cert-to-name' list entries.