Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 
ON THIS PAGE
 

NETCONF Sessions over Transport Layer Security (TLS)

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 Junos devices.

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

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

  • Secures the connection and exchange of NETCONF messages

  • 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 Junos devices, 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 is 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 to better manage and automate devices in large-scale networks.

NETCONF-over-TLS sessions with Junos devices have the following requirements:

  • NETCONF client that supports TLS version 1.2

  • The server and client must have X.509 public key certificates that are signed by a certificate authority

  • The Junos public key infrastructure (PKI) must have the appropriate local and CA certificates loaded

  • The Junos device 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 Junos devices, 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 CA certificates

    Note:

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

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

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 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 process tls-proxyd 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 devices execute 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, the Junos device uses the default map type to derive the NETCONF username.

Junos devices support the following map types:

  • 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 user template account that is defined locally on the Junos 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 Junos device 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 CA certificate 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.

See Also

How to Establish a NETCONF Session over TLS

A network management system (NMS) is used to remotely manage the Junos device. You can establish a NETCONF session over TLS between a network management system and supported Junos devices. The NMS is the NETCONF and TLS client, and the Junos device 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:

Install TLS Client Software on the Network Management System

To establish a NETCONF session using TLS, the network management system must first establish a TLS connection with the Junos device. Thus, the network management system 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 and the client must have an X.509 certificate, and the certificate 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 for the NETCONF client:

  1. Generate a private key, and specify the key length in bits.
    Note:

    Junos devices do not support using Elliptic Curve Digital Signature Algorithm (ECDSA) keys in NETCONF sessions over TLS.
  2. If you are defining the NETCONF username in the client's certificate, update your openssl.cnf or equivalent configuration file to define the subjectAltName=dirName extension and specify the NETCONF username.
  3. Generate a certificate signing request (CSR), which contains the entity's public key and information about their identity.
  4. Generate the certificate by doing one of the following:

    • Submit the CSR to a certificate authority to request an X.509 certificate, and provide the configuration file to include any additional extensions.

    • Sign the CSR with a CA to generate the client certificate, and include the -extfile and -extensions options if you need to reference your configuration file and extensions.

  5. Verify that the Common Name (CN) field and extensions, if provided, are correct.

Similarly, generate the server certificate.

  1. Generate a private key, and specify the key length in bits.

  2. Generate a certificate signing request (CSR).

  3. Generate the certificate by doing one of the following:

    • Submit the CSR to a certificate authority to request an X.509 certificate.

    • Sign the CSR with a CA to generate the server certificate.

The Junos OS public key infrastructure (PKI) provides an infrastructure for digital certificate management. You can also use the Junos OS PKI to generate the required key pair and CSR for the server’s local 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 PKI

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

To install the server’s local certificate in the Junos PKI:

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

    Define a unique certificate identifier, and specify the file paths to the certificate and the private key or key pair. For example:

  3. (Optional) Verify the certificate.

Install the CA Certificates in the Junos 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 each have an X.509 digital certificate to authenticate their identity. You must configure the root CA certificate required to validate the client certificate in the Junos public key infrastructure (PKI). You must also configure any CAs required to validate the server’s local certificate in the Junos PKI. Thus, for each CA, you configure a certificate authority profile and load the corresponding CA certificate and certificate revocation list (CRL). This configuration enables the Junos device to validate a certificate against the CA.

Note:

If the server certificate chain does not include intermediate CAs, you must configure the root CA certificate. 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 Junos device.
  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 PKI, and specify the location of the certificate file.
  4. Load the CA certificates associated with the server’s CA profile in the Junos PKI, and specify the location of the certificate file.

    • If the certificate chain only has a root CA, load the root CA certificate.

    • If the certificate chain includes intermediate CAs, you only need to load the intermediate CA certificates.

  5. Load the CRL for a given CA profile where required, for example:
    Note:

    If you do not configure a certificate revocation list for a given CA profile, then you must disable revocation checks by configuring the revocation-check disable statement at the [edit security pki ca-profile profile-name] hierarchy level.
  6. (Optional) Verify the CA certificate.

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 network management system and the format of the certificate, for example:
  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 Junos device, 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. The NETCONF user 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 Junos devices.

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

  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, the following configuration defines two users: netconf-user and netconf-default-user.

  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 Junos device where the client establishes NETCONF sessions over TLS.

See Also

Start the NETCONF-over-TLS Session

The network management system 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 Junos device.

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.
  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.
  4. Close the NETCONF session and TLS connection.