Replace TLS certificates

Overview

PeerGFS employs TLS encryption to secure data transmission between the PMC, Agents, and brokers, as well as for accessing the PMC web user interface.  TLS utilizes keys and certificates to authenticate hosts and encrypt data.  The deployment of PeerGFS includes default certificates.  If preferred, you can update these certificates with new ones that are either self-signed or signed by a Certificate Authority (CA).

This article provides step-by-step instructions for replacing and, if desired, generating new keys and certificates.

Using Self-Signed Certificates

Replacing a Web Client Certificate

On initial installation, the Peer Management Center's web interface has a default certificate used for TLS authentication.  If preferred, you can replace this certificate with one that is either self-signed or signed by a Certificate Authority (CA).  Follow the instructions below to replace it with a self-signed certificate.

To generate a new key and certificate for the PMC's web interface:

1. Use PowerShell to navigate to the tools directory within the installation folder on the PMC.

2. Run the script GenLocalKey.ps1 passing the argument -web and follow the prompts displayed.
   

3. Restart the Peer Management Center Web Service to apply the new certificate and private key.

Replacing an API Certificate

To replace the API certificate, replace the web client certificate using the procedure above. In earlier versions, the default API certificate could not be changed separately.

Replacing Broker Certificates

Upon initial installation, each PeerGFS broker is equipped with a self-signed private key, enabling Agents to establish an encrypted TLS connection.  You can replace the default key and certificate with a new key and either a self-signed or CA-signed certificate.  Follow the instructions below to replace the default key and certificate with a new key and self-signed certificate.

Task 1: Generate Broker Keys

To generate a new self-signed certificate and private key pair on a broker (including the PMC):

1. Navigate to the tools directory using PowerShell on the broker server.

2. Run the script GenLocalKey.ps1 and follow the prompts to generate the new private key and certificate pair.
   On completion, details of the certificate location are displayed.  For example:
   
   If the window is accidentally closed, the certificate will be located in the Broker/keys directory within the installation folder.

   

   To use the newly created certificate, the Peer Management Broker Service must be restarted.  However, for minimal disruption, this should be done after the certificate has been distributed in Task 2.  If you restart a broker at this point, Agents will be disconnected since the new certificate has not yet been applied.
   

Task 2: Upload Certificate to Agents and Remote Brokers

After generating the certificate in Task 1, upload the certificate to the appropriate locations using the ImportRemoteCert.ps1 script.  Pass the saved certificate file and the host name as parameters to the script. 

To upload the certificate:

1. Connect to the desired connecting server (Agent or secondary broker).

2. Copy the generated certificate to this server.

3. Ensure your certificate file is named after the appropriate broker host name from Task 1.  For instance, if your broker's host name is example-host, the certificate file should be named example-host.cer.

4. Ensure you have the necessary permissions to run the ImportRemoteCert.ps1 script and import the certificate.

5. Using PowerShell, navigate to the tools folder in the root of the PeerGFS installation directory.

6. Run the ImportRemoteCert.ps1 script with the following commands, substituting <hostname> with the host name of the broker whose certificate you are importing.

   PowerShell

   # Define the hostname and certificate file path
   $hostname = "example-host"
   $certificateFilePath = "$hostname.cer"
   
   # Run the ImportRemoteCert.ps1 script
   .\ImportRemoteCert.ps1 -CertificatePath $certificateFilePath -Hostname $hostname
   

   Make sure the ImportRemoteCert.ps1 script is in the current directory or provide the full path to it.  Adjust the $hostname and $certificateFilePath variables according to your actual host name and certificate file.  For example:
   

7. Apply the certificate update based on the component you're updating:
   • If you are updating an Agent, restart the Peer Agent Service (as shown below). 
   • If you are updating a broker, restart the Peer Management Broker Service.
   
   When all services have been restarted, the Agent will connect using the new key and certificate and come online.

Using Your Own Certificate or CA-Signed Certificate

If you prefer to use your own certificate or a certificate signed by a Certificate Authority (CA) rather than a self-signed certificate, follow these steps. This section assumes you are familiar with the process of signing and managing certificates.

To import a private key and signed certificate, follow these steps:

1. Generate a PKCS12 file. 

   Use this step as an example for creating a PKCS12 file. If you already have a PKCS12 file or use another method to create one, skip this step.
   To import a CA-signed certificate, you must combine the signed certificate, typically provided as a .pem or .crt file, with its corresponding private key into a PKCS12 file. The following example shows how to create the PKCS12 file.

   openssl pkcs12 -export -in broker.crt -inkey broker.key -out broker.p12 -name hostname -CAfile ca.crt -caname root
   

   Where:
      • -in specifies the signed certificate file, broker.crt in this example.
      • -inkey specifies the private key file, broker.key in this example.
      • -out specifies the output PKCS12 file, broker.p12 in this example.
      • -name specifies the alias assigned to the key entry in the PKCS12 file. In this example, hostname is used as the alias.
      • -CAfile specifies the CA root certificate, ca.crt in this example.
      • -caname specifies the alias assigned to the CA certificate, root in this example.
   Running this command will prompt you to set a passphrase for the output file.  Record this passphrase; it is required in the next step.

2. Import the PKCS12 file:

   To import your own generated key, a PKCS12 file (.p12) must be used. If your organization provides a .pfx file, rename the file extension to .p12 before importing it.
   Using the PKCS12 (.p12) file, perform Task 1. Generate Broker Keys and Task 2. Upload Certificates to Agents and Remote Brokers from above. When running GenLocalKey.ps1 in Task 1, include the -key, -alias, and -pass arguments as shown below:
   

3. Follow the same process for the web UI, adding the -web option when running the GenLocalKey.ps1 script.

   PowerShell

   .\GenLocalKey.ps1 -key broker.p12 -alias <alias> -pass <passphrase> -web
   

4. If you are using a certificate that was not issued by a trusted CA and you want to prevent browser security warnings, import the appropriate root certificate into the trusted certificate store used by the browser.

Related articles