Certificates

The Certificates Page provides access to the following pages:

The Automated Certification Management Environment protocol is used for automatic certification of devices and GigaVUE-FM. Refer to the following sections for details.

To enable secure and confidential communication between GigaVUE-FM, GigaVUE-OS devices and other network entities, it is important to deploy, manage and update the required certificates. By default, GigaVUE-FM and the GigaVUE-OS devices come up with self-signed certificates. However, you can also deploy custom certificates signed by the Certificate Authorities (CA). This requires you to manually install the certificates and map the certificates to the web.

Starting in software version 5.13.01, GigaVUE-FM and the devices support Automated Certificate Management Environment (ACME) protocol that allows automatic certificate signing and deployment between Certificate Authorities (CAs) and GigaVUE-FM, GigaVUE-OS devices web servers. If your devices and GigaVUE-FM instances are running software version 5.13.00 or lower, ensure to add all the devices to GigaVUE-FM, upgrade the devices and GigaVUE-FM to software version 5.13.01 for the ACME protocol to be functional.

How ACME Works

The ACME protocol is based on the principle of client-server communication:

  • ACME Server: Runs at a Certificate Authority, for example, Step-ca . The ACME server responds to the client requests and executes the requested actions (issue, renew, revoke) once the client is authorized.
  • ACME Client: Runs on the user’s server or device that needs to be protected by the PKI certificate. The ACME client uses the ACME protocol to request the ACME server running in CA to perform the certificate management tasks such as issue, renew, revoke of certificates.

An ACME server and a client must be appropriately configured. The client sends requests to the server and the server receives the requests and issues certificates for the client. The ACME server and the client communicate over a secure HTTPS connection using JSON messages.

Note:  For more details about the Automatic Certificate Management Environment protocol, refer to RFC 8555.

ACME Configuration in GigaVUE-FM and the Devices

ACME client is configured in both GigaVUE-FM and the GigaVUE-OS devices, and takes care of the following operations by contacting the ACME server that runs in a Certificate Authority:

  • Issue of Certificates
  • Renewal of Certificates
  • Certificate Revocation

The following diagram shows how ACME works in GigaVUE-FM and the devices:

Refer to the following table for a summary of the ACME process in devices and GigaVUE-FM:

Task In Device In GigaVUE-FM
Certificate Issuance and Renewal

The ACME Client is installed in the devices and takes care of automatic issue/renew/revoke of the HTTPS certification of the devices.

Issuance:

After the certificate is downloaded, the device will automatically update the ACME issued certificate for web operation.

Renewal:

  • Both manual and automatic renewals are supported.
  • Auto renewal timers are started in the device based on the configured value (default is 1/3rd days before the certification expiry).

    • Note:  If the user provided auto renew days is > (expiry date – today date), then default renewal days will be calculated (1/3rd days before expiry).

  • Both public and private keys are renewed.

The ACME client is installed in GigaVUE-FM and takes care of automatic issue/renew/revoke of the HTTPS certification of GigaVUE-FM (standalone GigaVUE-FM instances and also instances in a HA group).

Issuance:

After the certificate is downloaded, GigaVUE-FM will automatically update the ACME issued certificate for web operation.

Renewal:

  • Both manual and automatic renewals are supported.
  • Auto renewal timers are started in GigaVUE-FM based on the configured value (default is 1/3rd days before the certification expiry).

 
Certificate Revocation

Upon receiving revoke command (from GigaVUE‑FM), the device:

  • Re-issues a new certificate and maps it for the HTTPS operations.
  • Sends a revocation request to the ACME server and deletes the same from the device cache.

    • Note:  The certificate revocation process renews the certificate first followed by the revocation. This is to avoid the down time of the web server .

Revoke operation in GigaVUE-FM:

  • Initiates re-issue of new certificate
  • Followed by revocation of the existing certificate.

Once the re-issue and revoke operation is successful, the newly issued ACME certificate will be activated as the Web certificate. If revoke fails, GigaVUE-FM will fall back to default certification mode.
Clear Certificate Clear operation clears the ACME issued certificate from the devices and maps the web certificate to the default certificate. This command also cancels the auto-renewal timers that are started by the ACME client in the device Deleting the ACME issued certificate results in GigaVUE-FM falling back to the default certification mechanism.

 

The ACME client configured in the device takes care of certificate issuance, renewal and revocation for the devices.

Pre-requisites

The following are the pre-requisites for ACME configuration:

  • DNS must be configured.
  • ACME server's root and intermediate certificates must have been installed and added to the CA list (Refer to CA List page).

Notes

  • Device uses its domain name to download (Issue) a certificate from a CA.
  • Certificate revocation and renewal (manual renewal) requires domain name and box id as input.
  • Classic mode supports rsa-2048 and rsa-4096 certificate algorithms. Secured crypto & FIPS mode support prime256v1 and secp384r1 certificate algorithm.

Limitations

The following are the limitations:

  • ACME certificate can be issued only for single domain. Mltiple domain name as Subject Alt name is not allowed.
  • It is not possible to issue a new certificate based on CSR.
  • Command to modify the renewal-period for the already issued certificate is not available.
  • Managing multiple server certificate using ACME is not supported.
  • Only web certificates used in the device will be managed by ACME.

Add Root CA Certificate of ACME Server

You must add the root CA certificate before using the ACME protocol for certificate issuance and renewal.

CLI Command

Invoke the following command to add the root CA certificate of the ACME server to the nodes:

config# crypto certificate name <cert name> public-cert pem <PEM string>

Invoke the following command to add the root CA certificate of the ACME server to all the nodes in a cluster:

config# crypto certificate ca-list default-ca-list name <cert name>

 

Certificate Issuance

Gigamon devices handle the issuance of web server certificate as per the ACME protocol.

CLI Command

Invoke the following command from CLI to generate a fresh certificate and its corresponding private key:

config# crypto certificate acme issue box-id <box-id> domain <xyz.gigamon.com> ca-url <url> {algorithm <rsa-2048 | rsa-4096 | ec-prime256v1 | ec-secp384r1>} {renew-days <1-365> } {root-cert <cert_name>}

 

You can specify the number of days (1 to 365 days), when the device should contact the ACME server to renew the certificate before its expiration (default is 1/3rd of the number of days before expiry).

Note:  Certificate issuance process is a time consuming process (because of authorization/challenge involved). After user executes issue command, a message "Issuance in progress. Check status using show crypto acme client info {box-id <box-id>}" is displayed.

If the command is successful:

  • The device generates a private key and downloads the signed certificate from the CA server.
  • The certificate is installed in the default certificate location. The certificate will be renamed as acme-https-crt.
  • The new certificate is used only for web communications.
  • SNMP traps will be sent to syslog-server and GigaVUE-FM. The traps are sent before start of an operation (issue, renew and revoke) and after the operation is completed, (success / failure).
  • Use Show crypto certificate to view the newly downloaded certificate.
  • Use show crypto acme client info to view the status of the certificate.

If the command fails:

  • The existing certificate (previously used on the system) will be used for web communication.
  • If the challenge process takes a longer time, the acme-client will be timed out and appropriate error messages will be displayed. This is also reflected in show crypto acme client info.
  • In case of failures in downloading the certificate from ACME server, you must correct the errors and execute the certificate issue command again to download the certificate.
Refer to the GigaVUE CLI Reference Guide for details about the command.

Certificate Renewal

Renewal of web server certificate is handled in the device as follows:

  • The device periodically auto-renews the certificates based on the auto renew interval configured during the issue of certificate. By default, auto-renewal happens one-third of the days before expiry.
  • You can also manually renew the certificate using the domain name that is used during the certificate issuance phase.

Note:  The ACME client in the device takes care of renewing certificates that are issued only by ACME. Other user provided certificates (eg., LDAP, TACACS) will not be auto-renewed by the ACME client.

CLI Command

Invoke the following command to renew a certificate:

config# crypto certificate acme renew {box-id <box-id>} domain <domain-name>

If the command is successful:

  • The CA renews the certificate and its corresponding private key as well.
  • The device replaces the certificates in the HTTPS certificate path.
  • SNMP trap is sent to GigaVUE-FM to indicate that the certificate has been successfully renewed. Syslogs will be sent to syslog server and GigaVUE-FM.

Certificate Revocation

To revoke a certificate, the device sends a signed revocation request indicating the certificate to be revoked. If the request is valid, the server will revoke the certificate. To avoid the downtime of the devices' web server, the revoke CLI command:

  • Internally renews the certificate
  • Followed by revoking the compromised certificate.

If the renew operation fails, the device will switch to default certificate.

CLI Command

Invoke the following command to revoke a certificate:

config# crypto certificate acme revoke {box-id <box-id>} domain xyz.gigamon.com

If the command execution is successful, SNMP trap is sent to GigaVUE-FM to indicate that the certificate has been revoked.

Clear ACME

Clear operation clears the ACME issued certificate from the devices and maps the web certificate to the default certificate. This command also cancels the auto-renewal timers that are started by the ACME client in the device.

CLI Command

crypto acme client clear

You cannot switch to another certificate for web communication when ACME certificate is used for web. This is to avoid unnecessary auto-renewals.

View Certificate Status

The ACME operations such as issue, renew and revoke are time-consuming. Therefore, to know the status of the ACME operations use the following command:

show crypto acme client info box-id <box-id>

Example for Certificate Issuance

show crypto acme client info box-id 4

Box Id 4:

==========

ACME Issued Certificate Info

============================

https:

Domain : 10.60.95.2

Cert Name : acme-https.crt

Acme-Server : https://10.115.72.233:8080/acme/acme/directory

First-Issued : 2021/10/11 16:14:46

Next Renewal : 2021/12/10 23:26:47

Expires : 2022/01/09 16:14:48

Renewal Days : System Computed

Last Succesful Renewal : n/a

Last Failed Renewal : n/a

Last Request Status Since Bootup

================================

Domain : 10.60.95.2

Acme-Server : https://10.115.72.233:8080/acme/acme/directory

Request-Status : Success

Type of Request : Issue

Troubleshooting Scenarios

Use the following table to troubleshoot issue(s) that you might encounter during the ACME certification process:

Problem

Solution

Failure in ACME certification renew/revoke operation
  • Check the device log/GigaVUE-FM events and see if this is due to wrong account registration.
  • Clear the ACME issued certificate and issue a fresh certificate.

Configuration from GigaVUE-FM GUI

You can configure ACME certification for the devices from GigaVUE-FM GUI or from the respective device GUI.

  • Global configuration from the GigaVUE-FM GUI allows you to configure the ACME certificate for all the devices managed by GigaVUE-FM.
  • Configuration of ACME from the devices allows you to configure the ACME certificate for the specific devices.

Note:  For global configuration of ACME for devices from GigaVUE-FM, root/intermediate certificate of CA must be configured in the Trust Store page of GigaVUE-FM.

Refer to the following GUI screens for details:

ACME configuration in GigaVUE-FM is required for the following:

  • Web certification of GigaVUE-FM
  • Communication between the individual GigaVUE-FM instances in case of High Availability.

Pre-requisites

The following are the pre-requisites for ACME configuration:

  • Only super-admin users and admin users can Issue, Renew, Revoke and Delete certificates.
  • DNS must be configured. GigaVUE-FM and the devices will perform DNS look up for fetching the DNS name.
  • The trust chain of CA authority must be configured in both GigaVUE-FM and devices.
  • Root certificate for a CA must be installed as a prerequisite for requesting the certificate.

The following table summarizes about ACME implementation in GigaVUE-FM:

Task Description Refer to...
Certificate Issuance

GigaVUE-FM uses the rootca and the user specified ACME server address along with its domain name or user provided CSR to download the requested certificate.

After the CA issues the certificate, GigaVUE-FM:

  • Copies the certificate to the HTTPS certificate path
  • Generates cms.p12 file using the following command:

    • openssl pkcs12 -export -name CMS -out cms.p12 -inkey localhost.key -in localhost.crt -passout pass:cms123

  • Uploads the cms.p12 generated file in the directory.

    • Note:   Appropriate error message will be displayed if downloading the certificate from the CA server times out. The tomcat and httpd will be restarted for the new certificates to take effect.
Certificate Renewal

GigaVUE-FM supports both manual and automatic renewal of ACME certificates. Renewal of GigaVUE-FM's web certificate server certificate is handled as follows:

  • Manual Renewal: You can manually renew the certificate using the domain name that is used during issuance phase.
  • Automatic Renewal: You can configure the auto-renewal period during the certificate Issuance phase. However, you can modify the renewal days.

    Note:  By default, auto-renewal is 1/3rd of the certificate validity period.

  • Once the CA renews the certificate, the device will replace the certificates in the certificate path.

  • GigaVUE-FM generates the cms.p12 file and once cms.p12 is generated, it would be uploaded in the directory.

Note:  If downloading the certificate from the CA server times out, appropriate error messages will be displayed. You must retry renewal of the certificates. The tomcat and httpd will be restarted for the new certificates to take effect.

 Refer to Certificate Renewal.
Certificate Revocation

To revoke a certificate, GigaVUE-FM sends a signed revocation request indicating the certificate to be revoked. If the request is valid, server will revoke the certificate.

Note:  The revoke operation will internally perform a re-issue of new certificate first and then it will initiate the revoke of old certificate. If the operation fails, GigaVUE-FM will fall back to default certificate.

Refer to Certificate Revocation.
Certificate Deletion Once the certificate is deleted, GigaVUE-FM will fall back to the default certification mechanism.  

Note:  If DHCP is enabled in GigaVUE-FM and if the IP address of GigaVUE-FM changes, you must re-issue the certificate because the manual renewal and revoke operations will not work. This is because, GigaVUE-FM GUI passes the old IP address as the domain name instead of the new IP address during the first manual renew and revoke after the change in IP address (due to which DNS resolution fails). Therefore, to re-issue the certificate you must provide the Fully Qualified Domain Name (FQDN) of the new IP address and issue the new certificate. GigaVUE-FM then updates the new IP with FQDN in the database and deletes the old entry.