Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

Understanding NETCONF-over-TLS Connections


Benefits of NETCONF over TLS

  • Enables remote management of devices using mutual certificate-based authentication

  • Enables you to more easily manage networks on a larger scale than when using NETCONF over SSH

  • Secures the connection and exchange of NETCONF messages

  • Uses public-key infrastructure to provide mutual TLS certificate-based authentication for both the client and the server

  • Ensures data integrity for exchanged messages

NETCONF over TLS Overview

You can establish a Network Configuration Protocol (NETCONF) session over Transport Layer Security (TLS) on certain devices running Junos OS, as an alternative to establishing a NETCONF session over SSH. TLS is a cryptographic protocol that uses mutual certificate-based authentication and provides a secure and reliable connection between two devices. It is a successor to the Secure Sockets Layer (SSL) protocol. When you establish a NETCONF session over TLS, the NETCONF server acts as the TLS server, and the NETCONF client must act as the TLS client.

NETCONF sessions over TLS provide some advantages over sessions that use SSH. Whereas SSH authenticates a client by using credentials (username and password) or keys, TLS uses certificates to mutually authenticate both the client and the server. Certificates can provide additional information about a client, and they can be used to securely authenticate one device to another. Thus, while NETCONF sessions over SSH work well for manually managing individual devices, NETCONF sessions that use TLS enable secure device-to-device communication for more effectively managing and automating devices in large-scale networks.

NETCONF-over-TLS sessions on devices running Junos OS require the following:

  • NETCONF client that supports TLS version 1.2

  • The server and client must have X.509 public key certificates, and the certificates must not be self-signed

  • The Junos OS public key infrastructure (PKI) has the appropriate certificates loaded for the server and for any necessary certificate authorities (CAs)

  • The device running Junos OS is configured for NETCONF over TLS and defines a default or specific certificate-to-NETCONF-username mapping for a client

  • The NETCONF username corresponds to a valid Junos OS user account

TLS uses X.509 digital certificates for server and client authentication. A digital certificate is an electronic means for verifying your identity through a trusted third party, known as a certificate authority or certification authority (CA). A certificate authority issues digital certificates, which can be used to establish a secure connection between two endpoints through certificate validation. The X.509 standard defines the format for the certificates. To establish a NETCONF session over TLS on supported devices running Junos OS, both the server and the client must have a valid X.509 certificate, and the certificates must be signed by a CA. Self-signed certificates cannot be used to establish NETCONF sessions over TLS.

The Junos OS PKI provides an infrastructure for digital certificate management. To establish a TLS connection, you must install the following in the Junos OS PKI:

  • NETCONF server’s local certificate and its intermediate CAs


    If the server certificate chain does not include intermediate CAs, you must configure the root CA.

  • NETCONF client’s root CA required to validate the NETCONF client certificate

After the server verifies the identity of the client and establishes the TLS connection, it must derive the NETCONF username for that client before it can establish the NETCONF session. The NETCONF username is the Junos OS user account under whose access privileges and permissions the NETCONF operations are performed. You can configure a list of client certificate-to-NETCONF username mappings, and you can also configure a default NETCONF username mapping. Junos OS uses the default mapping when a client certificate does not match any of the configured clients. If the server extracts a valid NETCONF username, it then establishes the NETCONF session. For more information about deriving the NETCONF username, see Understanding the TLS Client-to-NETCONF Username Mapping.

The Junos OS tls-proxyd process handles the TLS connection. It performs the TLS handshake, encrypts and decrypts the traffic, determines the NETCONF username, and fetches the authorization parameters for the NETCONF user. The tls-proxyd process works in conjunction with the management process (mgd) to create and manage the NETCONF session. The NETCONF-over-TLS session workflow is outlined in NETCONF-over-TLS Connection Workflow.

For more information about NETCONF over TLS, see RFC 7589, Using the NETCONF Protocol over Transport Layer Security (TLS) with Mutual X.509 Authentication.

For more information about the Transport Layer Security protocol, see RFC 5246, The Transport Layer Security (TLS) Protocol Version 1.2.

Understanding the TLS Client-to-NETCONF Username Mapping

The authenticated identity of the NETCONF-over-TLS client is the NETCONF username. Junos OS executes the NETCONF operations under the account privileges of this user. You can configure the method used to derive the NETCONF username for individual clients, and you can also define a default method to derive the NETCONF username for those clients that do not match a configured client.

You can configure the mapping of client certificates to NETCONF usernames at the [edit system services netconf tls client-identity] hierarchy level. For each client, you configure the certificate fingerprint and a map type. If the fingerprint of a client certificate matches a configured fingerprint, Junos OS uses the corresponding map type to derive the NETCONF username. You can configure only one fingerprint per client, and each client fingerprint must be unique. For example:

The configured certificate fingerprint uses x509c2n:tls-fingerprint format as defined in RFC 7407, A YANG Data Model for SNMP Configuration. In this format, the first octet is the hashing algorithm identifier, and the remaining octets are the result of the hashing algorithm. The hashing algorithm identifier, which is shown here for reference, is defined in RFC 5246, The Transport Layer Security (TLS) Protocol Version 1.2.

  • md5: 1

  • sha1: 2

  • sha224: 3

  • sha256: 4

  • sha384: 5

  • sha512: 6

You can also configure a default mapping for the NETCONF username at the [edit system services netconf tls default-client-identity] hierarchy level. If the fingerprint of a client certificate does not match any configured clients, Junos OS uses the default map type to derive the NETCONF username.

The following map types are supported:

  • san-dirname-cn—Use the common name (CN) defined for the SubjectAltName’s (SAN) DirName field (DirName:/CN) in the client certificate as the NETCONF username.

  • specified—Use the NETCONF username defined in the username statement at the same hierarchy level.

After the server verifies the identity of the client and establishes the TLS connection, it derives the NETCONF username. It first matches the fingerprint for each configured client against the fingerprint of the presented certificate. If there is a match, it uses the corresponding map type to derive the NETCONF username. If none of the configured fingerprints match that of the client’s certificate, the default map type is used to derive the NETCONF username.

After the server determines the username, it fetches the authorization for the user locally or remotely. The username must either have a user account defined locally on the device, or it must be authenticated by a Lightweight Directory Access Protocol (LDAP) server, which then maps it to a local user template account that is defined locally on the device. If the extracted username is not a valid local or remote user, then the TLS connection is terminated.

NETCONF-over-TLS Connection Workflow

The device running Junos OS acts as the TLS and NETCONF server. The server listens for incoming NETCONF-over-TLS connections on TCP port 6513. The NETCONF client, which is also the TLS client, initiates a connection with the server on that port.

The client and server perform the following actions to establish and use the NETCONF session over TLS:

  1. The client sends a TLS ClientHello message to initiate the TLS handshake.

  2. The server sends a ServerHello message, the server certificate chain, and a CertificateRequest message to request a certificate from the client.

  3. The client verifies the identity of the server and sends the client certificate chain.

  4. The server verifies the client certificate chain with the client’s root CA, which has been preconfigured on the server.

  5. The server derives the NETCONF username for that client.

  6. If the NETCONF username is valid, the server starts the NETCONF session, and the server and client exchange NETCONF <hello> messages.

  7. The client performs NETCONF operations using the access privileges and permissions of the NETCONF user.

  8. The client executes the <close-session> operation to end the NETCONF session, which subsequently closes the TLS connection.

The server fails to establish the NETCONF session over TLS in the following scenarios:

  • The server or client certificate is expired or self-signed

  • The client doesn’t provide a certificate

  • The client doesn’t send its intermediate CA certificates

  • The client’s root certificate authority is not configured on the server

  • The server cannot map the client certificate to a configured or default map type to derive the NETCONF username

  • The server uses the san-dirname-cn map type to derive the NETCONF username for the client, but the client’s certificate does not specify a username in the corresponding field

Related Documentation