Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

NETCONF Sessions over Transport Layer Security (TLS)

 
Summary

Network Configuration Protocol (NETCONF) clients can use the Transport Layer Security (TLS) protocol with mutual X.509 certificate-based authentication to establish a NETCONF session with supported devices running Junos OS.

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

    Note

    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

How to Establish a NETCONF Session over TLS

A configuration management server is used to remotely configure the device running Junos OS. You can establish a NETCONF session over TLS between a configuration management server and supported devices running Junos OS. The configuration management server is the NETCONF and TLS client, and the device running Junos OS is the NETCONF and TLS server.

Before the client and server can establish a NETCONF session over TLS, you must satisfy the requirements discussed in the following sections:

  1. Install TLS Client Software on the Configuration Management Server

  2. Obtain X.509 Certificates for the Server and Client

  3. Install the Server’s Local Certificate in the Junos OS PKI

  4. Install the CA Certificates in the Junos OS PKI

  5. Enable the NETCONF Service over TLS

  6. Configure the TLS Client-to-NETCONF Username Mapping

  7. Configure the Default NETCONF Username Mapping

  8. Configure the User Account for the NETCONF User

  9. Start the NETCONF-over-TLS Session

Install TLS Client Software on the Configuration Management Server

To establish a NETCONF session using TLS, the configuration management server must first establish a TLS connection with the device running Junos OS. Thus, the configuration management server requires software for managing the TLS protocol. For example, you can install and use the OpenSSL toolkit, which is a toolkit for the Transport Layer Security (TLS) and Secure Sockets Layer (SSL) protocols. It is licensed under an Apache-style license.

For more information about OpenSSL, see https://www.openssl.org.

Obtain X.509 Certificates for the Server and Client

The TLS protocol uses X.509 public key certificates to authenticate the identity of the server and the client. To establish a NETCONF session over TLS, both the server running Junos OS and the client must have X.509 certificates, and the certificates must be signed by a valid certificate authority (CA). Self-signed certificates are not accepted for NETCONF sessions over TLS.

To use OpenSSL to obtain a certificate:

  1. Generate a private key.
    user@cms:~$ openssl genrsa -out client.key 2048
    Note

    Devices running Junos OS do not support using Elliptic Curve Digital Signature Algorithm (ECDSA) keys in NETCONF sessions over TLS.

  2. Generate a certificate signing request (CSR), which contains your public key and information about your identity.
    user@cms:~$ openssl req -new -key client.key -out client.csr
  3. Send the CSR to a certificate authority (CA) to request an X.509 certificate, or sign the client CSR with a CA to generate the client certificate, for example:
    user@cms:~$ openssl x509 -req -in client.csr -CA clientRootCA.crt -CAkey clientRootCA.key -CAcreateserial -out client.crt

The Junos OS public key infrastructure (PKI) provides an infrastructure for digital certificate management. You can use the Junos OS PKI to generate the required key pair and CSR for the server’s local certificate, or you can generate them off box. You then send the CSR to a CA to request the certificate.

For information about the Junos OS PKI and the different methods for obtaining certificates, see Digital Certificates with PKI Overview and related documentation.

Install the Server’s Local Certificate in the Junos OS PKI

The server’s local certificate is the X.509 certificate for the device running Junos OS that is acting as the NETCONF and TLS server. You must install the local certificate for the device in the Junos OS PKI.

To manually install the server’s local certificate on the device running Junos OS:

  1. Copy the certificate and private key to the device running Junos OS.
  2. Load the certificate from the specified file using the Junos OS PKI.

    Specify the file paths to the certificate and private key or key pair, and define a unique identifier for the certificate.

    user@host> request security pki local-certificate load filename /var/tmp/server.crt key /var/tmp/server.key certificate-id netconf-server-cert
  3. (Optional) Verify the certificate.
    user@host> show security pki local-certificate certificate-id netconf-server-cert

Install the CA Certificates in the Junos OS PKI

A digital certificate is an electronic means for verifying your identity through a trusted third party, known as a certificate authority (CA). When establishing a NETCONF session over TLS, the client and server must have X.509 digital certificates to authenticate their identity. You must configure the root CA required to validate the client certificate as well as any CAs required to validate the server’s local certificate in the Junos OS public key infrastructure (PKI). This requires configuring a certificate authority profile and loading the corresponding CA certificate and certificate revocation list (CRL) for each CA. Doing this enables Junos OS to validate a certificate against the CA.

Note

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

To manually configure a CA profile and load the corresponding CA certificate and CRL:

  1. Download the CA certificates and any required CA certificate revocation lists (CRLs) to the device running Junos OS.
  2. Configure a trusted CA profile for each required CA, for example:
  3. Load the CA certificate associated with the client’s root CA profile in the Junos OS PKI, and specify the location of the certificate file.
    user@host> request security pki ca-certificate load ca-profile clientRootCA filename /var/tmp/clientRootCA.crt
  4. Load the CA certificates associated with the server’s CA profiles in the Junos OS PKI, and specify the location of the certificate file.
    • If the certificate chain only has a root CA, load the root CA certificate.

      user@host> request security pki ca-certificate load ca-profile serverRootCA filename /var/tmp/serverRootCA.crt
    • If the certificate chain includes intermediate CAs, you only need to load the intermediate CA certificates.

      user@host> request security pki ca-certificate load ca-profile serverIntCA filename /var/tmp/serverIntCA.crt
  5. Load the CRL for a given CA profile where required, for example:
  6. (Optional) Verify the CA certificate.
    user@host> show security pki ca-certificate ca-profile clientRootCA detail

Enable the NETCONF Service over TLS

To enable NETCONF over TLS:

  1. Configure the server’s local certificate ID, and reference the ID that was defined when the certificate was installed.
  2. Define how the server should derive the NETCONF username for a given client.
  3. (Optional) Configure trace options for NETCONF sessions over TLS, for example:
  4. Commit the configuration.

Configure the TLS Client-to-NETCONF Username Mapping

You can define the mapping between the client certificate and the NETCONF username for specific clients. If you do not define a mapping for a specific client, then you must define a default mapping in order for the client to establish a NETCONF session over TLS.

To define the mapping to derive the NETCONF username for a given client:

  1. Determine the fingerprint for the client’s certificate by executing the command appropriate for your environment on the configuration management server and the format of the certificate, for example:
    user@cms:~$ openssl x509 -noout -fingerprint -sha256 -in client.crt
  2. Determine the fingerprint’s hashing algorithm identifier as defined in RFC 5246, The Transport Layer Security (TLS) Protocol Version 1.2.

    This examples uses the SHA-256 hashing algorithm, which corresponds to the identifier value of 4.

    • md5: 1

    • sha1: 2

    • sha224: 3

    • sha256: 4

    • sha384: 5

    • sha512: 6

  3. On the device running Junos OS, define a unique identifier for the client.
  4. Configure the client’s certificate fingerprint in x509c2n:tls-fingerprint format.

    The fingerprint’s first octet is the hashing algorithm identifier, and the remaining octets are the result of the hashing algorithm.

  5. Configure the map type that defines how the server derives the NETCONF username for that client.
  6. If the map type is specified, configure the NETCONF username to use for that client.
  7. Commit the configuration.

Configure the Default NETCONF Username Mapping

You can define a default mapping that is used to derive the NETCONF username when a client does not match a client configured at the [edit system services netconf tls client-identity] hierarchy level.

To define the default mapping to derive the NETCONF username:

  1. Configure the default map type that the server uses to derive the NETCONF username.
  2. If the map type is specified, configure the default NETCONF username.
  3. Commit the configuration.

Configure the User Account for the NETCONF User

When establishing a NETCONF session over TLS, the server maps the client certificate to the NETCONF user that performs the operations on the device for that session. Junos OS supports local users and LDAP remote users for NETCONF-over-TLS sessions. After the TLS session is established, the server maps the client certificate to the configured or default username specified at the [edit system services netconf tls] hierarchy level. That username must either have a user account defined locally on the device, or it must be authenticated by an LDAP server, which then maps it to a local user template account that is defined locally on the device. The following instructions explain how to create a user account on devices running Junos OS.

To create a user account for the NETCONF user on a device running Junos OS:

  1. Configure the user statement with a unique username, and include the class statement to specify a login class that has the permissions required for all actions to be performed by the user. For example:
  2. (Optional) Configure the uid and full-name statements to specify the user’s ID and name.
  3. Commit the configuration to activate the user account on the device.
  4. Repeat the preceding steps on each device running Junos OS where the client establishes NETCONF sessions over TLS.

Start the NETCONF-over-TLS Session

The configuration management server acts as the NETCONF and TLS client. You can use any software for managing the TLS protocol to initiate the NETCONF-over-TLS session with the device running Junos OS.

To start the NETCONF-over-TLS session:

  1. Initiate the connection to the NETCONF server on port 6513, and provide the client’s certificate and key, the root CA certificate for the server, and all intermediate CA certificates required to validate the client certificate.
    user@cms:~$ openssl s_client -connect 198.51.100.1:6513 -CAfile all_CAs -cert client.crt -key client.key -tls1_2
  2. Verify that the session maps to the correct NETCONF user.

    The server emits the NETCONF username for that session during the session establishment.

  3. Perform NETCONF operations as necessary.
    <rpc><get-configuration/></rpc>
  4. Close the NETCONF session and TLS connection.
    <rpc><close-session/></rpc>