Requirements
This article assumes that you have a fully functioning Virtru Private Keystore (CKS) running version 2.x on Linux using Docker. You will need administrative access to the server and permission to manage the CKS container. If you are running version 1.x, upgrading to 3.x, you can safely ignore the guidance in this document.
About
This article walks you through upgrading your keystore from CKS 2.x to 3.0.0, including the required key-file permission changes.
Before upgrading, set your CKS key files to 644. After confirming that you can still decrypt an existing encrypted email or file, you can complete the optional but recommended cleanup at the end of this article.
The commands below use the standard installation directory, /var/virtru/cks, and container name, Virtru_CKS. Replace these values if your installation uses a different directory or container name.
Back Up Your Keystore
Before making any changes, back up your CKS directory, including your existing keys, TLS files, and deployment configuration. Preserve the current file permissions and ownership.
For a standard installation, you can create a backup with:
sudo cp -a /var/virtru/cks /var/virtru/cks-backup-before-3.0.0
If the backup directory already exists, choose a different backup name.
Upgrade Steps
1. Verify that your keystore is working
Confirm that you can decrypt an existing encrypted email or file through this keystore. If you use an authenticated rewrap test to verify CKS, confirm that the test succeeds.
Use the same verification method after each change below.
2. Record the current permissions and ownership
On the host server, check the permissions, owner, and group assigned to your keys directory and key files:
sudo ls -ld /var/virtru/cks/keys sudo ls -ltr /var/virtru/cks/keys
If your installation has an SSL directory, record its permissions and ownership as well:
sudo ls -ld /var/virtru/cks/ssl sudo ls -ltr /var/virtru/cks/ssl
Save this output for reference during the upgrade. SSL file and directory permissions do not need to change as part of this procedure.
3. Update your key-file permissions
Navigate to the host directory mounted at /app/keys:
cd /var/virtru/cks/keys
Set the CKS private and public key files to 644:
sudo chmod 644 *.pub *.pem
This command updates the .pem and .pub files directly in the keys directory. Keep your existing keys.
Check the permissions again:
ls -ltr
Your private and public key files should show -rw-r--r--, which corresponds to 644.
4. Verify decryption before upgrading
With CKS 2.x still running, confirm that you can decrypt the same existing email or file, or repeat your authenticated rewrap test.
If verification fails, resolve the permission issue before continuing.
5. Update the CKS image
Navigate to your keystore installation directory and open the run.sh script:
cd /var/virtru/cks nano run.sh
Update the CKS image tag to the version 3.0.0 tag listed in the CKS release notes. Keep your existing key mounts, TLS mounts, authentication settings, and required storage.
Save the file and exit the editor. If you are using nano, press Ctrl+O, then Enter to save, and Ctrl+X to exit.
Stop and remove the existing container:
docker stop Virtru_CKS docker rm Virtru_CKS
Start the new container:
sh run.sh
Verify that the container is running:
docker ps --filter name=Virtru_CKS
Confirm that you can decrypt the same existing email or file, or repeat your authenticated rewrap test.
Once verification succeeds, the upgrade is complete. Repeat these steps on each server in your environment, verifying each server before upgrading the next.
Optional but Recommended Cleanup
The following cleanup is optional but recommended. Complete it after upgrading and confirming that CKS 3.0.0 is working. If you make these changes, apply them and verify decryption again as described below.
Remove obsolete environment variables
CKS 3.0.0 no longer includes the bundled KAS service, its provisioning tools, or PostgreSQL. The environment variables used by these components are no longer needed and are not removed automatically during the upgrade.
Open the environment file referenced by --env-file in your run.sh script. For a standard installation, this is /var/virtru/cks/env/cks.env:
sudo nano /var/virtru/cks/env/cks.env
Remove the following entries if they are present:
KAS_ROOT_KEYKAS_AUTH_ISSUERKAS_AUTH_AUDIENCEKAS_URIACM_ENDPOINTDATA_HARBOR_ENDPOINTWRAPPING_KEY_IDKEY_IDKEY_ALGORITHMKAS_PUBLIC_KEY_FILEKAS_PRIVATE_KEY_FILEKAS_LOG_LEVELKAS_LOG_TYPEKAS_LOG_OUTPUTDSP_DB_HOSTDSP_DB_PORTDSP_DB_DATABASEDSP_DB_USERDSP_DB_PASSWORDDSP_DB_SSLMODEDSP_DB_SCHEMA
Keep the settings still used by CKS, including JWT/HMAC authentication, HSM settings, token-store configuration, and key and TLS paths. Save the environment file and exit the editor.
Update key-directory ownership
After confirming that CKS 3.0.0 is working, review the keys directory's owner and permissions.
If the directory is owned by the legacy supervisor account, update its owner. Replace USERNAME with the account or numeric UID that should own the keys directory:
sudo chown -R USERNAME:USERNAME /var/virtru/cks/keys
Apply cleanup and verify CKS
If you edited cks.env, recreate the container using your updated startup script so Docker reads the edited environment file:
cd /var/virtru/cks docker stop Virtru_CKS docker rm Virtru_CKS sh run.sh
If you changed only key-directory ownership or permissions, restart the existing container:
docker restart Virtru_CKS
Verify that the container is running and that the permissions remain correct:
docker ps --filter name=Virtru_CKS sudo ls -ld /var/virtru/cks/keys sudo ls -ltr /var/virtru/cks/keys
Confirm that you can decrypt the same existing email or file, or repeat your authenticated rewrap test. If your installation generates keys on writable storage, also verify that key generation still works.
Once verification succeeds, cleanup is complete. Repeat these cleanup steps on each server where you make cleanup changes.
If you cannot decrypt after a change, review the most recent change and check the CKS logs for permission or missing-key errors. Contact Virtru Support if you need assistance.