NX-API and POAP Certificates

Cisco NX-OS switches require an SSL certificate to function in NX-API HTTPS mode. You can generate the SSL certificates and get it signed by your CA. You can install the certificates manually using CLI commands on switch console or use Cisco Nexus Dashboard Fabric Controller to install these on switches.

Cisco Nexus Dashboard Fabric Controller provides a Web UI framework to upload NX-API certificates to Nexus Dashboard Fabric Controller. Later, you can install the certificates on the switches that are managed by Nexus Dashboard Fabric Controller.


Note

This feature is supported on switches running on Cisco NXOS version 9.2(3) or higher.

Certificate Generation and Management

For each switch, the data center administrator generates an ASCII (base64) encoded certificate. This certificate comprises two files:

  • .key file that contains the private key

  • .crt/.cer/.pem file that contains the certificate

Cisco Nexus Dashboard Fabric Controller also supports a single certificate file that contains an embedded key file, that is, the .crt/.cer/.pem file, which can also contain the contents of the .key file.

Nexus Dashboard Fabric Controller doesn’t support binary encoded certificates, that is, the certificates with the .der extension are not supported. You can protect the key file with a password for encryption. Cisco Nexus Dashboard Fabric Controller does not mandate encryption; however, as this is stored on Nexus Dashboard Fabric Controller, we recommend that you encrypt the key file. Nexus Dashboard Fabric Controller supports AES encryption.

You can either choose CA-signed certificates or self-signed certificates. Cisco Nexus Dashboard Fabric Controller does not mandate the signing; however, the security guidelines suggest you use the CA-signed certificates.

You can generate multiple certificates meant for multiple switches, to upload to Nexus Dashboard Fabric Controller. Ensure that you name the certificates appropriately, to help you choose the switch meant for that certificate.

You can upload one certificate and the corresponding key file, or bulk upload multiple certificates and key files. After the upload is complete, you can view the upload list before installing these on the switches. If a certificate file that contains an embedded key file is uploaded, Nexus Dashboard Fabric Controller derives the key automatically.

Certificate and the key file must have the same filename. For example, if a certificate filename is mycert.pem, the key filename must be mycert.key. If the certificate and key pair filenames are not the same, then Nexus Dashboard Fabric Controller will not be able to install the certificate on the switch.

Cisco Nexus Dashboard Fabric Controller allows you to bulk install the certificates to the switches. Because bulk installation uses the same password, all encrypted keys must be encrypted with the same password. If the password is different for a key, you cannot install the certificate in bulk mode. Bulk mode installation allows you to install encrypted and unencrypted keys certificates together, but all the encrypted keys must have the same password.

When you install a new certificate on the switch, it replaces the existing certificate and replaces it with the new certificate.

You can install the same certificate on multiple switches; however, you cannot use the bulk upload feature.


Note

Nexus Dashboard Fabric Controller doesn’t enforce the validity of certificates or options provided in it. It is up to you and the requirements on the switch to follow the convention. For example, if a certificate is generated for Switch-1 but it is installed on Switch-2, Nexus Dashboard Fabric Controller doesn’t enforce it; switches may choose to accept or reject a certificate based on the parameters in the certificate.

NX-API Certificate Verification by Cisco Nexus Dashboard Fabric Controller

From release 12.0.1a onwards, Cisco Nexus Dashboard Fabric Controller supports a capability to verify NX-API certificates offered by switches. The NX-API requests done by Cisco Nexus Dashboard Fabric Controller require SSL connection, and switches act like SSL server and offer server certificate as part of SSL negotiations. If provided a corresponding CA certificate, Cisco Nexus Dashboard Fabric Controller can verify it.


Note

By default, NX-API certificate verification is not enabled because it requires all switches in the data center to have the CA-signed certificates installed, and Cisco Nexus Dashboard Fabric Controller is fed all the corresponding CA certificates.

Cisco Nexus Dashboard Fabric Controller NX-API certificate management provides two functionalities named as Switch Certificates and CA Certificates to manage the same.

Switch NXAPI Certificates

Uploading Certificates

To upload the certificates onto Nexus Dashboard Fabric Controller, perform the following steps:

  1. Click Upload Certificate to upload the appropriate certificate file.

  2. Browse your local directory and choose the certificate key pair that you must upload to Nexus Dashboard Fabric Controller.

    You can choose certificates with extension .cer/.crt/.pem + .key file separately.

    Cisco Nexus Dashboard Fabric Controller also allows you to upload a single certificate file that contains an embedded key file. The key file is automatically derived after upload.

  3. Click Upload to upload the selected files to Nexus Dashboard Fabric Controller.

    A successful upload message appears. The uploaded certificates are listed in the table.

    The table shows the Status as UPLOADED. If the certificate is uploaded without the key file, the status shows KEY_MISSING.

Assigning Switches and Installing Certificates

To install certificates on the switches using Cisco Nexus Dashboard Fabric Controller Web UI, perform the following steps:

  1. Select one or multiple certificates check box.

  2. From the Actions drop-down list, select Assign Switch & Install.

  3. In the NX API Certificate Credentials field, provide the password which was used to encrypt the key while generating the certificates.

    The Password field is mandatory, however, if the keys were not encrypted using a password, any random string you can enter, for example, test, install, and so on. In case of unencrypted files, passwords are not used, but you still need to enter any random string because it is bulk mode.


    Note

    You can install unencrypted and encrypted keys and a certificate in a single bulk install; however, you must provide the key password used for encrypted keys.

  4. For each certificate, click on the Assign arrow and select the switch to associate with the certificate.

  5. Click Install Certificates to install all the certificates on their respective switches.

Unlinking and Deleting Certificates

After the certificates are installed on the switch, Nexus Dashboard Fabric Controller cannot uninstall the certificate from Nexus Dashboard Fabric Controller. However, you can always install a new certificate on the switch. The certificates that are not installed on the switches can be deleted. To delete the certificate installed on the switch, you must unlink the certificate from the switch, and then delete it from Nexus Dashboard Fabric Controller.


Note

Unlinking the certificate from the switch does not delete the certificate on the switch. The certificate still exists on the switch. Cisco Nexus Dashboard Fabric Controller cannot delete the certificate on the Switch.

To delete certificates from Nexus Dashboard Fabric Controller repository, perform the following steps:

  1. Select the certificate(s) that you need to delete.

  2. From the Actions drop-down list, select Unlink.

    A confirmation message appears.

  3. Click OK to unlink the selected certificates from the switches.

    The status column shows UPLOADED. The Switch column shows NOT_INSTALLED.

  4. Select the certificate that is now unlinked from the Switch.

  5. From the Actions drop-down list, select Delete.

    The certificate is deleted from Nexus Dashboard Fabric Controller.

CA Certificates

Uploading Certificates

To upload the certificates onto Nexus Dashboard Fabric Controller, perform the following steps:

  1. On CA Certificates tab, click Upload Certificate to upload the appropriate license file.

    For Secure POAP enabled switches, you must upload Root CA Certificate files. You can upload multiple files at a single instance. Ensure that the Root CA certificate bundle is shared by the NX-API feature, for easy accesible to POAP or uploading new will be accesible for NX-API accordingly.

  2. Browse your local directory and choose the certificate-key pair that you must upload to Nexus Dashboard Fabric Controller.

    You can upload certificates with the .cer/.crt/.pem file extensions.


    Note

    Root CA certificates are public certificates and do not contain keys. Switches require these Root CA bundles to verify NDFC POAP server certificate which is signed by one of the Root CA in the bundle.

  3. Click Upload to upload the selected files to Nexus Dashboard Fabric Controller.

    A successful upload message appears. The uploaded certificates are listed in the table.

Deleting Certificates

To delete CA certificates, choose Actions from drop-down list, click Delete. Similarly, you can upload the new certificate to replace previous certificate. Ensure that you install these certificates on Bench Router (BR), as NDFC doesn’t assign the Root CA certificate bundle on the Bench Router.

Enabling NX-API Certificate Verification

The NX-API certificate verification is enabled using the toggle button on the CA Certificates page. However, this must be done only after all the switches managed by Cisco Nexus Dashboard Fabric Controller are installed with CA-signed certificates and the corresponding CA Root certificates (one or more) are uploaded to Cisco Nexus Dashboard Fabric Controller. When this is enabled, the Cisco Nexus Dashboard Fabric Controller SSL client starts verifying the certificates that are offered by the switches. If the verification fails, the NX-API calls will also fail.


Note

  • Verification of the NX-API certificates cannot be enforced per switch; it is for either all or none. Hence, it is important that the verification is enabled only when all the switches have their corresponding CA-signed certificates installed.

  • It is also required that all the CA certificates are installed on the Cisco Nexus Dashboard Fabric Controller.

  • When an NX-API call fails for a given switch because of verification issues, you can use the toggle button to disable enforcement, and all goes back to the previous state without any consequences.

  • Because of the above points, you must enable the enforcement during a maintenance window.

Actions Performed on Certificates

To bootstrap switches using the secure POAP feature, you must upload CA certificates. These certificates are assigned for bench router mechanism to validate switches.

  1. Choose appropriate certificate, from Actions drop-down list, and choose Install Certificate Bundle to POAP Bench Router (BR).

    The Install Certificate Bundle to POAP Bench Router (BR) window appears.

  2. Click Assign, and choose relevant switches in the Assign window.

  3. Choose Actions > Delete to delete certificate from Cisco Nexus Dashboard Fabric Controller.

POAP Certificates

When you bootstrap switches using secure POAP, ensure that you upload POAP server certificates on NDFC. This certificate is offered to Transport Layer Security (TLS) clients (switches).


Note

NDFC supports encrypted certificates only. Ensure that the POAP server certificate key is encrypted.

To perform various operations on POAP Certificate window, perform the following steps:

Procedure

Step 1

Click Upload Certificate to upload the appropriate file.

Step 2

Browse your local directory and choose the certificate-key pair to upload on Nexus Dashboard Fabric Controller.

You can upload certificates only with file extensions such as .pem/ .cer/.crt The key file extension is .key.

Step 3

Enter an appropriate password and click Upload to upload the selected files on Nexus Dashboard Fabric Controller.

The successful upload message appears. You can view the uploaded certificates in the table.

Step 4

Choose the required file, and click Delete to delete the certificate.

To install a new POAP server certificate, you must delete the existing certificate and then upload the new POAP server certificate on NDFC.