Cisco APIC Security Configuration Guide, Release 6.1(x)

The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.

• Trademarks
• New and Changed Information
• Overview
• Access, Authentication, and Accounting
• Restricting Access Using Security Domains and Node Rules
• RADIUS, TACACS+, LDAP, RSA, SAML, OAuth 2, and DUO
• 802.1X
• Port Security
• First Hop Security
• Protocol Authentication
• Control Plane Traffic
• Fabric Security
• Endpoint Security Groups
• Security Policies
• Data Plane Policing
• HTTPS Access
• Additional ACI Security Features

Book Title

Cisco APIC Security Configuration Guide, Release 6.1(x)

HTTPS Access

• PDF - Complete Book (9.23 MB)PDF - This Chapter (1.12 MB) View with Adobe Reader on a variety of devices
• ePub - Complete Book (5.59 MB) View in various apps on iPhone, iPad, Android, Sony Reader, or Windows Phone
• Mobi - Complete Book (12.8 MB) View on Kindle device or Kindle app on multiple devices

Results

Chapter: HTTPS Access

• HTTPS Access
• Overview
• Configuring Custom Certificate Guidelines
• Modifying the SSL Cipher Configuration
  • Mapping the Cisco APIC SSL Configuration Options to the Cipher List Formatting
  • Testing the Cipher List Format Before Modifying the Cisco APIC SSL Configuration
  • Determining the Supported SSL Ciphers Using the CLI

  HTTPS Access

  This chapter contains the following sections:

  Overview

  This article provides an example of how to configure a custom certificate for HTTPS access when using Cisco ACI .

  Configuring Custom Certificate Guidelines

  • Exporting a private key that is used to generate a Certificate Signing Request (CSR) on the Cisco Application Policy Infrastructure Controller ( APIC ) is not supported. If you want to use the same certificate on multiple servers through a wildcard in the Subject Alternative Name (SAN) field, such as "*cisco.com," by sharing the private key that was used to generate the CSR for the certificate, generate the private key outside of Cisco Application Centric Infrastructure ( ACI ) fabric and import it to the Cisco ACI fabric.
  • You must download and install the public intermediate and root CA certificates before generating a Certificate Signing Request (CSR). Although a root CA Certificate is not technically required to generate a CSR, Cisco requires the root CA certificate before generating the CSR to prevent mismatches between the intended CA authority and the actual one used to sign the CSR. The Cisco APIC verifies that the certificate submitted is signed by the configured CA.
  • To use the same public and private keys for a renewed certificate generation, you must satisfy the following guidelines:
    • You must preserve the originating CSR as it contains the public key that pairs with the private key in the key ring.
    • The same CSR used for the originating certificate must be resubmitted for the renewed certificate if you want to re-use the public and private keys on the Cisco APIC .
    • Do not delete the original key ring when using the same public and private keys for the renewed certificate. Deleting the key ring will automatically delete the associated private key used with CSRs.

    Modifying the SSL Cipher Configuration

    SSL ciphers can be enabled, disabled, or removed entirely. Depending on the desired cipher settings, you should understand which exact combination is required. Disabling and enabling ciphers in a manner that results in no ciphers remaining is a misconfiguration and will result in NGINX failing validation.

    NGINX uses the OpenSSL cipher list format. For information about the format, go to the OpenSSL website.

    Mapping the Cisco APIC SSL Configuration Options to the Cipher List Formatting

    Enabling a cipher results in the cipher being written to the NGINX configuration file. Disabling a cipher results in the cipher being written in the NGINX configuration file with a preceding exclamation mark (!). For example, disabling "EEDCH" will cause it to be written as "!EEDCH". Removing a cipher will result in the cipher not being written the NGINX configuration file at all.

    As stated in the OpenSSL cipher list format document, "If ! is used then the ciphers are permanently deleted from the list. The ciphers deleted can never reappear in the list even if they are explicitly stated." This can result in the removal of combination ciphers referencing the one that was set to "Disabled," regardless of the ciphers' "Enabled" state.

    Example: Disabling "EEDCH," but enabling "EECDH+aRSA+SHA384." This will cause the following to be written to the NGINX configuration file: "!EEDCH:EECDH+aRSA+SHA384". The "!EEDCH" will prevent "EECDH+aRSA+SHA384" from ever being added. This will result in no ciphers being used, which will fail NGINX validation and prevent NGINX updates from succeeding, such as applying custom HTTPS certificates.

    Testing the Cipher List Format Before Modifying the Cisco APIC SSL Configuration

    Before making any cipher modifications to the Cisco Application Policy Infrastructure Controller ( APIC ), validate the results of the planned cipher combination using the openssl ciphers -V ' cipher_list ' command and ensure that the cipher output matches your desired result.

    apic# openssl ciphers -V 'EECDH+aRSA+SHA256:EECDH+aRSA+SHA384' 0xC0,0x27 - ECDHE-RSA-AES128-SHA256 TLSv1.2 Kx=ECDH Au=RSA Enc=AES(128) Mac=SHA256 0xC0,0x28 - ECDHE-RSA-AES256-SHA384 TLSv1.2 Kx=ECDH Au=RSA Enc=AES(256) Mac=SHA384

    If your tested cipher list results in an error or "no cipher match," do not apply this configuration to the Cisco APIC . Doing so can result in NGINX issues with symptoms including making the Cisco APIC GUI inaccessible and breaking custom certificate application.

    apic# openssl ciphers -V '!EECDH:EECDH+aRSA+SHA256:EECDH+aRSA+SHA384' Error in cipher list 132809172158128:error:1410D0B9:SSL routines:SSL_CTX_set_cipher_list:no cipher match:ssl_lib.c:1383:

    Configuring a Custom Certificate for Cisco ACI HTTPS Access Using the GUI

    The downtime affects access to the Cisco Application Policy Infrastructure Controller ( APIC ) cluster and switches from external users or systems and not the Cisco APIC to switch connectivity. There will be an impact to external connectivity due to the NGINX processes running on the switches, but not the fabric data plane. Access to the Cisco APIC , configuration, management, troubleshooting, and such are impacted. The NGINX web server running on the Cisco APIC and switches restart during this operation.

    Before you begin

    Determine from which authority that you obtain the trusted certification so that you can create the appropriate Certificate Authority.

    Procedure

    On the menu bar, click the Admin > AAA .

    In the Navigation pane, select Security .

    In the Work pane, choose Certificate Authorities > Actions > Create Certificate Authority .

    In the Create Certificate Authority screen, in the Name field, enter a name for the certificate authority.

    (Optional) Enter a Description for the certificate authority.

    In the Certificate Chain field, copy the intermediate and root certificates for the certificate authority that will sign the Certificate Signing Request (CSR) for the Cisco APIC .

    The certificate has to be in Base64 encoded X.509 CER (Cisco Emergency Responder) format. The intermediate certificate is placed before the root CA certificate. It should look similar to the following example:

    -----BEGIN CERTIFICATE----- -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- -----END CERTIFICATE-----

    In the Work pane, choose Key Rings > Actions > Create Key Ring .

    The Key Rings enables you to manage:

    1. Private keys (imported from an external device or internally generated on the Cisco APIC ).
    2. CSR generated by the private key.
    3. Certificate signed through the CSR.

    In the Create Key Ring dialog box, in the Name field, enter a name.

    (Optional) Enter a Description for the key ring.

    In the Certificate Authority field, click Select Certificate Authority to choose the certificate authority that you created earlier, or click Create Certificate Authority .

    Choose the required radio button for the Private Key field.

    1. Generate New Key.
    2. Import Existing Key.

    Enter a Private Key. This option is displayed only if you chose the Import Existing Key option for Private Key .

    Choose the required radio button for Key Type if you chose the Generate New Key option for the Private Key field.

    1. RSA (Rivest, Shamir, and Adleman).
    2. ECC (Elliptic-curve cryptography) also known as ECDSA (Elliptic Curve Digital Signature Algorithm).

    In the Certificate field, do not add any content if you want to generate a CSR using the Cisco APIC through the key ring. If you already have the signed certificate content that was signed by the CA from the previous steps by generating a private key and CSR outside of the Cisco APIC , you can add it to the Certificate field.

    Select the required key strength for the cipher. This option is displayed only if you have selected the Generate New Key option in the Private Key field. Modulus drop-down list for RSA or ECC Curve checking the radio buttons for ECC Key Type .

    1. If you chose RSA for the Key Type , from the Modulus drop-down list, choose a modulus value.
    2. If you chose ECC for the Key Type , from the list of ECC Curve radio buttons, choose an appropriate curve.

    Click Save ( Create Key Ring screen).

    In the Work pane, choose Key Rings > key_ring_name (or you could also double click the required key ring row).

    If you have not entered the signed certificate and the private key, in the Work pane, in the Key Rings area, the Admin State for the key ring that is created displays Started , waiting for you to generate a CSR. Proceed to step 19.

    If you entered both the signed certificate and the private key, in the Key Rings area, the Admin State for the key ring that is created displays Completed . Proceed to step 22.

    Click the expand button, a new screen with the selected key ring is displayed.

    In the Certificate Request pane, click Create Certificate Request .

    The Request Certificate window is displayed.

    1. In the Subject field, enter the Common Name ( CN ) of the CSR. You can enter the fully qualified domain name (FQDN) of the Cisco APIC s using a wildcard, but in a modern certificate, we recommend that you enter an identifiable name of the certificate and enter the FQDN of all Cisco APIC s in the Alternate Subject Name field (also known as the – Subject Alternative Name) because many modern browsers expect the FQDN in the SAN field.
    2. In the Alternate Subject Name field, enter the FQDN of all Cisco APIC s, such as " DNS:apic1.example.com,DNS:apic2.example.com,DNS:apic3.example.com " or " DNS:*example.com ". Alternatively, if you want SAN to match an IP address, enter the Cisco APIC s' IP addresses with the following format:

    IP:192.168.2.1

    The Certificate Request Settings pane now displays the information that you entered above (step 19).

    In the Work pane, choose Key Rings > key_ring_name (or you could also double click the required key ring row).

    A new screen with the selected Key Rings is displayed with the Certificate details.

    After the key is verified sucessfully, in the Work pane, the Admin State changes to Completed and is now ready for use in the HTTP policy.

    On the menu bar, select Fabric > Fabric Policies .

    In the Navigation pane, click Policies > Pod > Management Access > default .

    In the Work pane, in the Admin Key Ring drop-down list, choose the desired key ring.

    (Optional) For Certificate based authentication, in the Client Certificate TP drop-down list, choose the previously created Local User policy and click Enabled for Client Certificate Authentication state .

    What to do next

    Be wary of the expiration date of the certificate and take the required action before it expires. To retain the same key pair for the renewed certificate, preserve the CSR. CSR contains the public key that pairs with the private key in the key ring. Resubmit the same CSR, before the certificate expires. Do not delete or create a new key ring. Deleting the key ring deletes the private key that is stored in the Cisco APIC .

    Configuring the Default SSL Protocols and Diffie-Hellman Key Exchange Using the GUI

    This procedure configures the default SSL protocols and Diffie-Hellman key exchange. You must configure these parameters based on the security policy of your organization and the needs of any applications that you use.

    Procedure

    On the menu bar, choose Fabric > Fabric Policies .

    In the Navigation pane, choose Policies > Pod > Management Access > default .

    In the Work pane, find the HTTPS section.

    1. For SSL Protocols , put a check in the boxes for the transport layer security (TLS) versions that your network allows. Leave the box empty for any TLS version that your network does not allow.
    2. In the 6.0(1) release, for DH Param , choose the desired key size (in bits). Choosing one of the key sizes enables the standard Diffie-Hellman (DH) key exchange in addition to the elliptic-curve Diffie-Hellman (ECDH) key exchange and uses the chosen number of bits for the DH key exchange. Choosing None instead uses only the elliptic-curve ECDH key exchange. In any case, ECDH always uses 256 bits. Beginning with the 6.0(2) release, the DH parameters are dynamically determined during the communication handshake with the client. You no longer manually choose the key size.
    3. Click Submit .

    Enabling Certificate Based Authentication Using the NX-OS CLI

    Procedure

    To enable Certificate Based authentication:

    Example:

    To enable CAC for https access: configure terminal comm-policy default https client-cert-ca client-cert-state-enable To disable: configure terminal comm-policy default https no client-cert-state-enable no client-cert-ca

    About SSL Ciphers

    The Cisco Application Centric Infrastructure (ACI) Representational State Transfer (REST) Application Programming Interface (API) has gone through an evolution from the day the solution debuted to recent versions where the HTTPS/SSL/TLS support has gotten increasingly more stringent. This document is intended to cover the evolution of HTTPS, SSL, and TLS support on the Cisco ACI REST API and provide customers with a guide of what is required for a client to utilize the REST API securely.

    HTTPS is a protocol that utilizes either Secure Socket Layers (SSL) or Transport Layer Security (TLS) to form a secure connection for a HTTP session. SSL or TLS is used to encrypt the traffic between a client and a HTTP server. In addition, servers that support HTTPS have a certificate that can usually be used by the client to verify the server's authenticity. This is the opposite of the client authenticating with the server. In this case, the server is saying, "I am server_xyz and here is the certificate that proves it." The client can then utilize that certificate to verify the server is "server_xyz."

    There are other important aspects to SSL/TLS that involve the supported encryption ciphers available in each protocol as well as the inherent security of the SSL or TLS protocols. SSL has gone through three iterations - SSLv1, SSLv2 and SSLv3 - all of which are now considered insecure. TLS has gone through three iterations - TLSv1, TLSv1.1 and TLSv1.2 - of which only TLSv1.1 and TLSv1.2 are considered "secure." Ideally, a client should utilize the highest available TLS version it can and the server should support only TLSv1.1 and TLSv1.2. However, most servers must keep TLSv1 for outdated clients.

    Almost all modern browsers support both TLSv1.1 and TLSv1.2. However, a client that utilizes HTTPS may not be a browser. The client may be a java application or a python script that communicates with a web server and must negotiate HTTPS/TLS. In this type of a situation, the questions of what is supported and where becomes much more important.

    Determining the Supported SSL Ciphers Using the CLI

    Before you begin

    This section describes how to use the CLI to determine which SSL ciphers are supported.