Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

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:

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>