Installing a New External Certificate

Use this procedure to replace the current KeyControl SSL certificate with a new externally-signed SSL certificate. If you want to use a new, self-signed SSL certificate generated by the Public CA included with KeyControl, see Installing a New Self-Signed Certificate.

Before You Begin 

  • If you generated the Certificate Signing Request (CSR) through KeyControl, you need to make sure you have the resulting SSL certificate and the CA certificate in Base64-encoded pem format files accessible to the KeyControl node that you are logged into. If you generated the CSR through some other means, make sure you have both of the Base64-encoded pem format certificates and the Base64-encoded pem format private key file that goes with the certificates. For more information, see Creating a Certificate Signing Request.
  • If you generated the SSL certificate from openssl or other third-party tool, make sure the certificate is formatted as a web server certificate. KeyControl registration may fail for some VMs if the SSL certificate is formatted as a Certificate Authority certificate.
  • We strongly recommend that you verify all VMs registered with KeyControl are online and accessible before you install a new SSL certificate on KeyControl. During the installation process, KeyControl sends an updated version of the CA certificate to each of the registered VMs at their next heartbeat. If all VMs are online, this process is fairly simple and ensures that there is no interruption in the communication between the VMs and KeyControl. If any VMs are inaccessible, however, the CA certificate may need to be manually updated on those VMs after the SSL certificate installation on KeyControl is complete because the old CA certificate installed on the VMs will no longer be able to verify KeyControl's identity and all communication coming from KeyControl will be rejected by the VMs.

Procedure 

  1. Log into the KeyControl webGUI using an account with Domain Admin privileges.
  2. In the top menu bar, click Cluster.

  3. Click the Servers tab and select a KeyControl node.

    Note: You can use SSL certificates signed by different certificate authorities on individual KeyControl nodes. However, HyTrust recommends that all of the SSL certificates be signed by the same Certificate Authority so that only one CA certificate is required on the VMs registered with KeyControl.

  4. Select Actions > Install Certificate.

  5. In the Certificate tab of the Certificate Installation dialog box, specify the options you want to use.

    Field

    Description
    SSL Certificate The SSL certificate file in Base64-encoded pem format. This certificate must be valid for the installation to succeed.

    CA Certificate

    The certificate of the CA that issued the SSL certificate in Base64-encoded pem format. The VMs registered with KeyControl use the CA certificate to verify communication with KeyControl.

    Important: Before KeyControl installs the certificate, it checks with the certificate authority to make sure that the SSL certificate can be validated. If the CA certificate file you are uploading contains just the certificate of the root certificate authority, make sure that the SSL certificate file contains the entire chain of intermediate CA certificates as well as the SSL certificate for the selected KeyControl node.

  6. If you did not create the certificate signing request with KeyControl:

    1. Click the Private Key tab and click Load File, then navigate to the private key file you want to use. KeyControl never stores the private key in clear text.
    2. If the private key file is encrypted, enter the user-specified password for the key file in the Password field. This password is not stored in the KeyControl object store or on the local file system.

  7. Click Install Certificate.

    If there are any VMs already registered with the system, KeyControl automatically distributes the new CA certificate to those VMs on their next heartbeat and tracks the progress of the install in the Certificate State field. KeyControl updates the installation status shown in the webGUI every 5 minutes. The state can be:

    • IN PROGRESS — The install is in progress. The table displays one line for each KeyControl node showing the total number of VMs, the number of VMs that timed out and could not be reached, and the number that are waiting for the web service to restart.

      If a new VM is added to KeyControl or a previously-inaccessible VM comes back online during this phase, KeyControl automatically sends the appropriate CA certificate to that VM as soon as there is a successful VM heartbeat.

      The length of time this phase takes depends on heartbeat duration configured for the registered VMs and whether all of those VMs are accessible. KeyControl polls for responses once every 5 minutes. If all VMs have had a successful heartbeat during that time, KeyControl completes this phase and changes the installation status to RESTART PENDING. If one or more VMs have not yet been contacted or if their heartbeat has failed, KeyControl waits another 5 minutes and polls again.

      This process continues until all registered VMs have either been successfully contacted or have failed 4 consecutive heartbeats. If even one VM is inaccessible, the entire installation process remains in this phase until that VM either comes back online or has failed the fourth scheduled heartbeat. In the latter case, KeyControl considers the installation request to have timed out for that VM and it sets the installation status to TIMED OUT.

      For example, If you are using the default heartbeat duration of 5 minutes, that means KeyControl will wait at least 20 minutes until it considers the request to have timed out. If you have increased the heartbeat duration for any of the VMs registered with KeyControl, then this step will take longer. If you have increased the heartbeat for a particular VM to 1 day, KeyControl may have to wait up to 24 hours before the next scheduled VM heartbeat occurs and it can update the status of the installation request to RESTART PENDING. If that VM is inaccessible, KeyControl has to wait for 4 days before it stops trying to update that VM. It is only when the last VM has been contacted or has timed out that KeyControl concludes this phase.

      Tip: If you do not want to wait for the next scheduled heartbeat on a particular VM, log into that VM as an administrator and issue the hcl heartbeat command on that VM. This allows KeyControl to update the certificate information on the VM immediately.

    • RESTART PENDING — The install is completed and the new certificate will be used as soon as the web service is restarted. KeyControl has successfully sent the new CA certificate to all registered VMs, so there should be no interruption in service once the web service restarts.
    • TIMED OUT — At least one of the VMs associated with the KeyControl node could not be reached and the new CA certificate could not be sent to those VMs. When a VM times out, KeyControl sends an alert to the Cloud Admins associated with that VM. The Cloud Admins are responsible for updating the KeyControl CA certificate on the unreachable VMs. For more information, see Troubleshooting Certificate Issues.

  8. When the installation is complete, click the Restart Web Service button or select Actions > Restart Web Service and confirm the request at the prompt. After the web service restarts, KeyControl will use the new certificate.

    KeyControl restarts the web server which may interrupt the browser connection to the webGUI. When the restart is finished you are returned to the webGUI login page.

    Tip: If you are using Chrome, the connection status in your browser may still show as insecure. To fix this, open the KeyControl webGUI login page in a new tab.

  9. If you want to verify that the new certificate was properly installed, select Actions > View Current Certificate.