Virtru Private Keystore (for Virtru Solutions): Reference - Upgrade SSL certs for CKS

Step 1: Backup Your CKS

Log into the VPK server. 
Before making any updates, perform a full backup of all directories and files.

Commands:

cd /var/virtru
mkdir backup
cd backup
cp -r /var/virtru/cks .

Step 2: Generate a New Certificate Request (CSR)

Option A: (Recommended) Generate a new key + CSR

If you need a renewed SSL certificate, generate a CSR to send to your certificate authority. Enter the relevant company information. Leave the password blank when prompted during key generation.

Commands:

cd /var/virtru/cks/ssl
openssl req -new -newkey rsa:2048 -nodes -keyout cks.example.com.key -out cks.example.com.csr

• OpenSSL will prompt you for the following details:
  • Country Name: (e.g., US)
  • State or Province Name: (e.g., California)
  • Locality Name: (e.g., San Francisco)
  • Organization Name: (e.g., Example Inc.)
  • Organizational Unit Name: (e.g., IT)
  • Common Name: (e.g., cks.example.com)

Once complete, you’ll have two files:

• Private key: cks.example.com.key
• CSR: cks.example.com.csr

Send the CSR to your certificate authority (i.e., DigiCert, GoDaddy etc.) to obtain the new certificate bundle.

Option B (Optional): Re-use an existing key to make a new CSR

• i) Go to your SSL folder

cd /var/virtru/cks/ssl

• ii) Verify the existing key information (This confirms the key type, size, and that the file is valid):

openssl rsa -in cks.example.com.key -noout -text

• Look for the Private-Key section (e.g., 2048 bit, 4096 bit, or ECC key).
• There should not be a passphrase associated with your private key.
• iii) Generate the new CSR
  • Enter this command to use the existing key to create a new CSR:

openssl req -new -key cks.example.com.key -out cks.example.com_new.csr -sha256

• Replace filenames as needed.
• Leave the password field blank.
• When prompted, enter your organization info. The Common Name (CN) should be the FQDN (e.g., cks.example.com).
  • Subject → Country, State, Org, Common Name (CN/FQDN)
  • Public Key Info → Algorithm (RSA/ECDSA) and key size

  • Requested Extensions → e.g., Subject Alternative Names (if included)

    To inspect the contents of an existing CSR file, you can use:

    openssl req -in cks.example.com.csr -noout -text

    Check that the Subject and all fields are correct.

• iv) Submit the CSR
  • Send the CSR (cks.example.com_new.csr) to your Certificate Authority (DigiCert, GoDaddy, etc.) to issue the new certificate.

Step 3: Validate the Certificate and Private Key

Commands:

1. Validate the Private Key:

openssl rsa -modulus -noout -in cks.example.com.key | openssl md5

2. Validate the Certificate:

openssl x509 -modulus -noout -in cks.example.com.crt | openssl md5

3. Validate the Certificate Signing Request file:

openssl req -in cks.example.com.csr -noout -modulus | openssl md5

Compare the Output:

• The MD5 hashes from the private key, certificate signing request file, and the certificate received from the CA provider should match. If they do, the certificate and private key are correctly paired.
• Example:

MD5(stdin)= 6c1560a0ff7a6e2562fe551ff419436e

Step 4: Convert the Certificate Bundle to the Correct Format

The VPK CKS requires the SSL certificate in .crt and .key formats:

• .crt: Public certificate and intermediate/root certificates combined.
• .key: Private key.

Ensure the .crt file follows this order:

1. Your CKS certificate (must match your CKS server's FQDN)
2. Intermediate certificate (if one is provided)
3. Root CA certificate

Commands:

cd /var/virtru/cks/ssl
cat [path-to-public-crt][path-to-intermediate-crt][path-to-root-crt] > cks.example.com.crt
cat [path-to-private-key] > cks.example.com.key

cat public_crt.pem intermediate.crt root.crt > cks.example.com.crt

chmod 644 cks.example.com.key

Step 5: Stop Your Running CKS

Stop and remove the running Docker container to ensure the certificate changes take effect. 

If you are running multiple CKS servers, remove one server from the load balancer and complete the certificate replacement on that server first. Once you confirm the update is successful, repeat the process on the next server—one server at a time.

Commands:

cd /var/virtru/cks
docker ps -a
docker stop <container-ID>
docker rm <container-ID>

Step 6: Start the CKS Containers

After placing the new certificate files in the ssl directory, restart the CKS.

Commands:

cd /var/virtru/cks
sh run.sh

Step 7: Check the Logs (Optional)

Verify that the Docker containers start without errors and do not continuously restart.

Commands:

cd /var/virtru/cks
docker logs <container-ID> -f

Step 8: Validate the CKS Setup (Optional)

1. Test the /status Endpoint:

Using curl or a browser, validate the /status endpoint and check for the updated certificate date.

Commands:

curl https://cks.example.com/status

Open in a browser:

https://cks.example.com/status

2. Validate TLS Configuration:

Verify that the correct certificates are being used.

Commands:

openssl rsa -noout -in cks.example.com.key -text

openssl x509 -noout -in cks.example.com.crt -text

openssl s_client -starttls smtp -crlf -connect <server FQDN or IP>:<port>

Example Output:

--- SSL handshake has read 1528 bytes and written 360 bytes ---
New, TLSv1/SSLv3, Cipher is DHE-RSA-AES256-SHA
Server public key is 1024 bit
Secure Renegotiation IS supported
...
Verify return code: 0 (ok)

Conclusion

Following these steps ensures your Virtru Private Keystore (CKS) is updated with a valid TLS certificate, providing secure communication and maintaining compliance.