Using external certificates for communication between CTE Agent and CipherTrust Manager

Overview

CipherTrust Transparent Encryption can now use an external certificate, available at a user-defined path, to communicate with CipherTrust Manager.

Prerequisites

The external certificate must be:

• On the file system

• In PEM format

A key pair must already exist for the client:

• Must have Encryption type of either:

  • sha256WithRSAEncryption

  • ecdsa-with-SHA384

• Must be Encrypted with a pass phrase

Initial setup

1. Obtain your external CA certificate.

2. Create a certificate using the external CA certificate and key.

CipherTrust Manager Setup

To setup CipherTrust Manager to communicate through an external certificate:

1. Import the CA certificate into the CipherTrust Manager, click CA > External > Add External CA.

   In the Add External CA dialog, copy and paste the <ca_certificate_name>.pem file content from the UI page and provide a user-friendly name.

   For more information, see Using an Externally Generated Server Certificate for an Interface

2. Add the CA certificate to the list of trusted sources for the web interface, click Admin Settings > Interfaces > web > Edit > External Trusted CAs.

3. Restart the web server, click Admin Settings > Services > web > Restart.

4. Create a registration token for the CTE agent, using the API > Client-Management > Tokens > post.

   You must use the API to create the token. The UI Registration Token window does not allow you to select an external certificate.

   1. Paste in the value of the "ca_id" field, which can be found using CA > External > "..." > View.

   2. Delete the "label" from the sample body then click POST.

CTE Agent setup

1. Create a directory on the system to hold the required files, for example:

   • /root/cert_files (Linux/AIX)

   • c:\temp\cert_files (Windows)

2. Copy or create the following files in this directory:

   • client_cert.pem

   • client_key.pem

   • passphrase - this is currently expected as plain text

3. For Linux/AIX systems, to add the directory path to the environment, type:

   $ export EXTERNAL_CERT_DIR=/root/cert_files
   

4. For Windows system, invoke registerhost.exe from the command line and add this argument:

   c:\> register_host.exe -extcertdir=c:\temp\cert_files
   

5. Register the CTE client with the CM server as normal. If this is being done as part of an installation, then the above steps should be done before the installation, or, on windows, added to the registration parameters passed to the installer.

Post Registration

During registration, the certificate file is uploaded to the CipherTrust Manager, and the certificate and key files are imported into the CTE pem store. The key is decoded using the provided passphrase, then re-encoded using a random key using the normal CTE key security mechanisms for TLS keys. There is no need to keep the input files after registration is successful, so for security reasons they should be removed / shredded.

Certificate Renewal

The location of the external certificate files (i.e. the EXTERNAL_CERT_DIR or -extcertdir parameters) will be recorded in the CTE agent configuration file, agent.conf. When the current certificate is approaching expiration date (i.e. approx. 60 days prior to expiration) the CTE agent will look in this directory for an updated set of files.

If a new certificate file is present, then the file will be read and pushed to the CM, and if accepted, then the certificate and key will be imported into the CTE pem store, and the VMD process restarted to use the new certificate.

If no new certificate is present, a WARNING level message will be written to the logs and/or uploaded to the CM as per the logging settings, and the CTE agent will check again after 24 hours.

If the user wishes to change the directory path to store the new certificates, then the entry in the agent.conf file should be updated and the vmd service restarted. Alternatively, the user can update the external certificate set using the following command (this will not update the saved path):

    # vmutil -a vmd -d <ext_cert_Dir> updatecerts

If the user fails to update the certificate set prior to expiration then communication with the CM may be blocked, and re-registration will be required.

Any renewed certificates must have exactly the same common name field as the original certificate, or the CM will reject the update.