Managing TLS Certificate, KeyStore, and TrustStore Files

This chapter contains the following sections:

About the TLS Certificate, KeyStore, and TrustStore Files


Note

To support onePK devices, all connections to Cisco Nexus Data Broker that use onePK or OpenFlow agents require Transport Layer Security (TLS). For NX-API devices, TLS is optional.

Enabling the TLS connections between Cisco Nexus Data Broker and the OpenFlow or onePK switches requires TLS KeyStore and TrustStore files. The TLS KeyStore and TLS TrustStore files are password protected.

Cisco Nexus 3000, 3100, and 3500 Series switches require additional credentials, including Private Key, Certificate, and Certificate Authority (CA).

  • The TLS KeyStore file contains the private key and certificate information used by Cisco Nexus Data Broker.

  • The TLS TrustStore file contains the Certification Authority (CA) certificates used to sign the certificates on the connecting switches.

If TLS connections are required in your Cisco Nexus Data Broker implementation, all of the connections in the network must be TLS encrypted, and you must run Cisco Nexus Data Broker with TLS enabled (see Starting the Application with TLS Enabled). After Cisco Nexus Data Broker is started with TLS, you must run the TLS KeyStore password configuration command (see Providing the TLS KeyStore and TrustStore Passwords) to provide the passwords for Cisco Nexus Data Broker to unlock the KeyStore files.

Preparing to Generate the TLS Credentials

OpenFlow and Cisco onePK switches require cryptographic configuration to enable TLS.

The NX-API protocol plugin now supports TLS for secure communication to the devices. You can connect to the NX-API protocol plugin on the secure port 443. All configuration, discovery, and statisitcs collection is done using secure communication. Cisco Nexus Data Broker should be configured with the required certificates and it should be started in the secure mode. When Cisco Nexus Data Broker is started in TLS mode, all devices support the TLS connection. The normal unencrypted connection to the switches is not accepted.


Caution

Self-signed certificates are appropriate only for testing in small deployments. For additional security and more granular controls over individual certificate use and revocation, you should use certificates generated by your organization's Certificate Authority. In addition, you should never use the keys and certificates generated by this procedure in a production environment.

Before You Begin

Ensure that OpenSSL is installed on the Linux host where these steps will be performed.

Procedure
    Step 1   Create a TLS directory, and then navigate to it:

    mkdir -p TLS

    cd TLS

    Step 2   Create three directories under mypersonalca and two prerequisite files:

    mkdir -p mypersonalca/certs

    mkdir -p mypersonalca/private

    mkdir -p mypersonalca/crl

    echo "01" > mypersonalca/serial

    touch mypersonalca/index.txt

    Step 3   Create the CA configuration file (ca.cnf).

    The following is an example of the content of the Example.conf file: 

    [ req ]
default_bits            = 2048                  # Size of keys
default_keyfile         = example.key           # name of generated keys
default_md              = sha1                  # message digest algorithm
string_mask             = nombstr               # permitted characters
distinguished_name      = req_distinguished_name
req_extensions          = v3_req
x509_extensions         = v3_req


[ req_distinguished_name ]
# Variable name           Prompt string
#----------------------   ----------------------------------
0.organizationName      = Organization Name (company)
organizationalUnitName  = Organizational Unit Name (department, division)
emailAddress            = Email Address
emailAddress_max        = 40
localityName            = Locality Name (city, district)
stateOrProvinceName     = State or Province Name (full name)
countryName             = Country Name (2 letter code)
countryName_min         = 2
countryName_max         = 2
commonName              = Common Name (hostname, IP, or your name)
commonName_max          = 64


# Default values for the above, for consistency and less typing.
# Variable name                   Value
#------------------------------   ------------------------------
commonName_default              = www.cisco.com
0.organizationName_default      = Cisco
localityName_default            = San Jose
stateOrProvinceName_default     = CA
countryName_default             = US
emailAddress_default            = webmaster@cisco.com


[ v3_ca ]
basicConstraints        = CA:TRUE
subjectKeyIdentifier    = hash
authorityKeyIdentifier  = keyid:always,issuer:always



[ v3_req ]
# Extensions to add to a certificate request
basicConstraints = CA:FALSE
keyUsage = nonRepudiation, digitalSignature, keyEncipherment


# Some CAs do not yet support subjectAltName in CSRs.
# Instead the additional names are form entries on web
# pages where one requests the certificate...
subjectAltName          = @alt_names


[alt_names]
# NXAPI Device IPs to be supported/managed by NDB
IP.1   = 1.1.1.1
IP.2   = 2.2.2.2
IP.3   = 3.3.3.3
IP.4   = 4.4.4.4


[ server ]
# Make a cert with nsCertType set to "server"
basicConstraints=CA:FALSE
nsCertType                      = server
nsComment                       = "OpenSSL Generated Server Certificate"
subjectKeyIdentifier=hash
authorityKeyIdentifier=keyid,issuer:always


[ client ]
# Make a cert with nsCertType set to "client"
basicConstraints=CA:FALSE
nsCertType                      = client
nsComment                       = "OpenSSL Generated Client Certificate"
subjectKeyIdentifier=hash
authorityKeyIdentifier=keyid,issuer:always
    Step 4   Before saving the file, some changes need to be made that are specific to the devices. One critical change is to change the [alt_names] section to be relevant to the device IP address, because these IP addresses should be specified in the configuration file. If you need more or fewer IP/DNS names, you can add or remove the lines.
    Note    This step is applicable to NX-API only.
    What to Do Next

    Create the TLS certificate file.

    Creating the TLS Private Key, Certificate, and Certification Authority

    Before You Begin

    Complete the steps in Preparing to Generate the TLS Credentials.

    Procedure
      Step 1   Generate the TLS private key and Certification Authority (CA) files by entering the openssl req -x509 -nodes -days 3650 -newkey rsa:2048 -out mypersonalca/certs/ca.pem -outform PEM -keyout mypersonalca/private/ca.key command.

      This step generates the TLS private key in PEM format with a key length of 2048 bits, and the CA file.

      Step 2   Generate the certificate key and certificate request files by entering the openssl req -newkey rsa:2048 -keyout cert.key -keyform PEM -out cert.req -outform PEM command. This step generates the controller key (cert.key) and certificate request (cert.req) files in PEM format.
      Important:

      You must specify a PEM pass phrase that is 4 to 1024 alphanumeric characters in length, for example, cisco123.

      You must also specify a common name in this step to complete Step 3. An example of a common name is the hostname of the server where Cisco Nexus Data Broker is running.

      Step 3   Generate the certificate file by entering the openssl ca -batch -notext -in cert.req -out cert.pem -config ca.cnf command. This step generates the certificate (cert.pem) file in PEM format using the certificate request (cert.req) and the certificate configuration (ca.cnf) files as inputs, and creates the certificates file (cert.pem) as output.

      The following is an example of the console response: 

      Using configuration from ca.cnf                                                              
Check that the request matches the signature                                                 
Signature ok                                                                                 
The Subject's Distinguished Name is as follows                                               
countryName           :PRINTABLE:'AU'                                                        
stateOrProvinceName   :ASN.1 12:'Some-State'                                                 
organizationName      :ASN.1 12:'Internet Widgits Pty Ltd'
commonName            :ASN.1 12:'localhost'
      What to Do Next

      Generate and import the certificate files on your Cisco Nexus 3000, 3100, or 3500 Series switches.

      Configuring the Cryptographic Keys on the Switch

      Before You Begin

      Create the TLS certificate.

      Procedure
         Command or ActionPurpose
        Step 1switch(config)# ip domain-name domain-name  

        Configures the domain name for the switch.

         
        Step 2switch(config)# crypto key generate rsa label myKey2 exportable modulus 2048  

        Generates the cryptographic key.

         
        Step 3switch(config)# crypto ca trustpoint myCA  

        Enters the trustpoint configuration mode and installs the trustpoint file on the switch.

         
        Step 4switch(config-trustpoint)# rsakeypair myKey2  

        Installs the key files on the switch.

         
        Step 5switch(config-trustpoint)# exit  

        Exits trustpoint configuration mode.

         
        Step 6switch# show crypto ca trustpoints   (Optional)

        Verifies creation of the trustpoint files.

         
        Step 7switch# show crypto key mypubkey rsa   (Optional)

        Verifies creation of the key files.

         
        Step 8From the console, enter the cat mypersonalca/certs/ca.pem command.  

        Displays the certificate file on the machine hosting the generated TLS certificates.

         
        Step 9switch(config)# crypto ca authenticate myCA  

        Copies the CA certificate (ca.pem) to the switch to use as input.

        Note   

        When copying the CA certificate, include the lines -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----. End the input with a line that contains only END OF INPUT.

         
        Step 10 switch(config)# crypto ca enroll myCA  

        Generates the certificate request on the switch.

         
        Step 11From the console, enter the openssl ca -in n3k-cert.req -out newcert.pem -config ./ca.cnf command.  

        Copies the certificate request from the switch to the file n3k-cert.req on your Linux machine, and then uses it to generate the switch certificate.

         
        Step 12switch(config)# crypto ca import myCA certificate  

        Copies the certificate (newcert.pem) to the switch.

         
        Step 13From the console, enter the cat newcert.pem command.  

        Displays the certificate on the Linux console.

         
        Step 14switch# show crypto ca certificates  

        Displays the certificates on the switch.

         
        What to Do Next

        Enable TLS for Cisco onePK and OpenFlow switches.

        Enabling TLS for onePK and OpenFlow Switches


        Note

        This step is not applicable for NX-API.

        Before You Begin

        • Create the TLS certificate.

        • Configure the cryptographic keys on the switch.

        Procedure
           Command or ActionPurpose
          Step 1switch(config)# onep  

          Enters onePK configuration mode on the switch.

           
          Step 2switch(config-onep)# transport type tls  

          Enables TLS for onePK switches.

           
          Step 3switch# exit  

          Exits onePK configuration mode.

           
          Step 4switch# show onep status   (Optional)

          Displays the onePK configuration.

           
          Step 5switch(config)# openflow  

          Enters OpenFlow agent configuration mode on the switch.

           
          Step 6switch(config-ofa)# switch 1  

          Enters OpenFlow agent configuration mode for switch 1.

           
          Step 7switch(config-ofa)# tls trust-point local myCA remote myCA  

          Enables TLS certificate authority on the switch.

           
          Step 8switch(config-ofa-switch)# pipeline {201/203}  

          Configures the pipeline.

          Note   

          Set the pipeline to 201 for Cisco Nexus 3000 and 3100 Series switches. This is the default value, and only expert users should set the number to any value other than 201.

          Set the pipeline to 203 for Cisco Nexus 3500 Series switches. This is the default value, and only expert users should set the number to any value other than 203.

           
          Step 9switch(config-ofa-switch)# controller ipv4 {A.B.C.D} port 6653 vrf management security tls  

          Enables TLS for OpenFlow switches.

          A.B.C.D is the IP address of the controller.

          Note   

          For more information about configuring TLS for OpenFlow (Cisco Nexus 3000, 3100, or 3500 Series switches), see the configuration guide for the switches in your environment.

           
          What to Do Next

          Create the TLS KeyStore file.

          Configuring the NX-API Certificate

          Before You Begin

          Generate the certificate key and the certificate request files.


          Note

          This step is applicable for NX-API only.

          Procedure
             Command or ActionPurpose
            Step 1Copy the server.key and server.crt into the respective devices and install using the nxapi certificate httpskey keyfile bootflash:///server.key command where bootflash:/// is a file location of server.key.    
            What to Do Next

            Create the TLS KeyStore File.

            Creating the TLS KeyStore File


            Note

            The TLS KeyStore file should be placed in the configuration directory of Cisco Nexus Data Broker.

            Before You Begin

            Complete the steps in Configuring the Cryptographic Keys on the Switch.

            Procedure
              Step 1   Copy cert.key to xnc-privatekey.pem.

              This command copies the cert.key file that was generated in the "Creating the TLS Private Key, Certificate, and Certificate Authority" section. This file contains the Cisco Nexus Data Broker private key.

              Step 2   Copy cert.pem to xnc-cert.pem.

              This command makes a copy of the cert.pem file that was generated in the "Creating the TLS Private Key, Certificate, and Certificate Authority" section. This file contains the Cisco Nexus Data Broker certificate.

              Step 3   Create the xnc.pem file, which contains the private key and certificate, by entering the cat xnc-privatekey.pem xnc-cert.pem > xnc.pem command.
              Step 4   Convert the PEM file xnc.pem file to the file xnc.p12 file by entering the openssl pkcs12 -export -out xnc.p12 -in xnc.pem command.
              Step 5   Enter a password at the prompt.
              Note   

              This is the Export password. Use the same password that you entered in Step 2 of "Creating the TLS Private Key, Certificate, and Certification Authority". The password must contain at least 6 characters, for example, cisco123. You must use the same password for this step and for Step 7.

              The xnc.pem file is converted to a password-protected .p12 file.

              Step 6   Convert the xnc.p12 to a Java KeyStore (tlsKeyStore) file by entering the keytool -importkeystore -srckeystore xnc.p12 -srcstoretype pkcs12 -destkeystore tlsKeyStore -deststoretype jks command.

              This command converts the xnc.p12 file to a password-protected tlsKeyStore file

              Step 7   Enter a password at the prompt.
              Note   

              Use the same password that you entered in Step 5.

              Creating the TLS TrustStore File


              Note

              The TLS TrustStore file should be placed in the application configuration directory.

              Procedure
                Step 1   Copy the mypersonalca/certs/ca.pem file to sw-cacert.pem.
                Step 2   Convert the sw-cacert.pem file to a Java TrustStore (tlsTrustStore) file by entering the keytool -import -alias swca1 -file sw-cacert.pem -keystore tlsTrustStore command.
                Step 3   Enter a password at the prompt.

                The sw-cacert.pem file is converted into a password-protected Java TrustStore (tlsTrustStore) file.

                Note   

                The password must be at least six characters long, for example, cisco123.

                Step 4   If the switches in your network use more than one CA certificate, repeat Step 1 through Step 3 for each CA certificate required.

                Starting the Application with TLS Enabled

                Before You Begin

                • Generate and import certificate files on the switches.

                • Enable TLS on the OpenFlow or onePK switches.

                • Create and deploy TLS KeyStore and TLS TrustStore files for the Cisco Nexus Data Broker application.

                • Make sure that the TLS KeyStore (tlsKeyStore) and TLS TrustStore (tlsTrustStore) files are located in the ./configuration directory.

                Procedure
                  Step 1   From the console, start Cisco Nexus Data Broker by entering the ./runxnc.sh -tls -tlskeystore ./configuration/tlsKeyStore -tlstruststore ./configuration/tlsTrustStore command.
                  Note   

                  You will not see any network elements until you provide the TLS KeyStore and TrustStore passwords as described in the next section.

                  Step 2   Cisco Nexus Data Broker is started with TLS enabled.

                  Providing the TLS KeyStore and TrustStore Passwords

                  The TLS KeyStore and TrustStore passwords are sent to the Cisco Nexus Data Broker so that it can read the password-protected TLS KeyStore and TrustStore files.

                  Procedure
                    Step 1   Open a command window where you installed Cisco Nexus Data Broker.
                    Step 2   Navigate to the xnc/bin directory.
                    Step 3   Provide the TLS KeyStore and TLS TrustStore passwords by entering the ./xnc config-keystore-passwords [--user {user} --password {password} --url {url} --verbose --prompt --keystore-password {keystore_password} --truststore-password {truststore_password}] command.

                    Enter the following information:

                    • The Cisco Nexus Data Broker username {user}—The user name.

                    • The Cisco Nexus Data Broker password {password}—The password for the user. For example, the default admin password is admin.

                    • The Cisco Nexus Data Broker web URL {url}—The web URL of the application. For example, the default URL is https://Nexus_Data_Broker_IP:8443.

                      Note   

                      Only HTTPS is enabled by default. If you want to use HTTP, enable it by editing the XML file.

                    • The TLS KeyStore password {keystore_password}—The TLS KeyStore password.

                    • The TLS TrustStore password {truststore_password}—The TLS TrustStore password.