Virtru Private Keystore (for Virtru Solutions): Fresh Install with KAS

Purpose

Use this runbook to install a new Virtru Private keystore (VPK) deployment using including the optional Key Access Service (KAS) configuration during setup. Enable KAS when the deployment will integrate with Virtru Collaborate, including policy features such as attribute-based access control.

Prerequisites

Before starting, confirm you have:

• A Linux host or VM for VPK.
• Docker installed and running.
• Outbound internet access from the host to download the setup scripts and VPK container image.
• Network access allowing inbound HTTPS traffic to the VPK host.
• A DNS record for the VPK fully qualified domain name (FQDN), for example cks.example.com.
• Your Virtru Org ID (Your Virtru Representative will deliver this to you)
• A support email address and support URL to associate with the VPK deployment.

Information to Collect Before Running the Script

Have the following values available before you begin:

Step 1: Connect to the VPK Host

SSH to the host that will run VPK.

ssh <user>@<cks-host>

Run the remaining commands from that host.

Step 2: Download the Latest Setup Scripts

Download the bootstrap download script.

curl -s https://raw.githubusercontent.com/virtru/cks-setup-script/main/download.sh -o download.sh

Run the download script.

bash ./download.sh

The download creates a local cks-setup-scripts directory containing the latest release scripts, including setup-cks-latest.sh.

Step 3: Run the Setup Script

Start the setup wizard. The wizard will guide you through each required value.

bash ./cks-setup-scripts/setup-cks-latest.sh

Step 4: Enter the Working Directory

When asked for the working directory, enter the directory where the VPK configuration, keys, certificates, and generated run script should be stored. The default working directory is /var/virtru/cks.

Prompt:

Enter Working Directory:

Example:

/var/virtru/cks

If the directory already exists, you will be asked whether to replace it.

Step 5: Enter the VPK FQDN

When asked for the service URL, enter the public hostname where VPK will be available.

Prompt:

Define CKS URL (FQDN):
  Enter the URL the CKS will listen on.
  Enter URL [cks.domain.com]:

Example:

cks.example.com

Do not include https:// in this value.

Step 6: Enter Support Contact Details

Enter the support email and support URL when asked.

Prompts:

Enter the support email for your CKS Deployment:
Enter the support url for your CKS Deployment:

Examples:

support@example.com
https://support.example.com

Step 7: Enter your Virtru Org ID

When asked, enter your Virtru Org ID.

Prompt:

Enter your Virtru Org ID:

Enter the 36-character Org ID from your Virtru Representative

Step 8: Choose Whether to Enable KAS

You will be asked whether to enable KAS.

Prompt:

Do you want to enable KAS [yes/no]?

Answer yes if this VPK deployment should include KAS support for DSP.

When KAS is enabled, setup automatically configures these standard KAS values:

Setup also generates these values automatically:

• KAS_ROOT_KEY
• DSP_DB_PASSWORD

Important: KAS deployments also require KEY_ID. This is the key identifier provisioned in Virtru SaaS DSP. Confirm the correct KEY_ID with Virtru and add it to env/cks.env before starting the container if it is not already present.

Step 9: Choose Whether to Enable HMAC Authentication

You will be asked whether to enable HMAC authentication.

Prompt:

Do you want to enable auth via HMAC [yes/no]?

Answer based on your deployment requirements.

• Answer yes if HMAC authentication is required for CSE-to-VPK support.
• Answer no if the deployment only requires JWT authentication.

JWT authentication is enabled by default.

Step 10: Complete the Certificate Prompts

The setup script uses OpenSSL to generate a self-signed certificate for VPK. OpenSSL will ask for certificate subject values such as country, state, locality, organization, organizational unit, common name, and email address.

Enter your certificate details when asked.

Note: You will need a certificate signed by a trusted CA for VIrtru services to safely connect to your VPK. Replace the generated certificate and key files after setup according to your certificate management process.

Step 11: Choose the VPK Rewrap Key Type

Prompt:

Enter Key Type [RSA/ECC] (default RSA):

Options:

• Press Enter or type RSA to generate RSA keys.
• Type ECC to generate ECC P-256 keys.

The generated keys are saved under the working directory's keys folder.

Step 12: Review the Setup Summary

After setup completes, review the summary output.

The summary includes:

• Root directory
• VPK FQDN
• Certificate expiration date
• Key path
• Key fingerprint
• JWT status
• HMAC status
• Virtru Org ID
• KAS configuration, if KAS was enabled
• Support URL
• Support email

Confirm these values are correct before starting the container.

Step 13: Review Generated Files

Setup creates the following important files in the working directory:

If KAS was enabled, env/cks.env will also include the KAS, DSP database, and KAS key file variables.

For KAS deployments, confirm KEY_ID is present in env/cks.env before starting VPK.

KEY_ID=<key-id-provisioned-in-virtru-saas-dsp>

Step 14: Send Required Information to Virtru

Provide send_to_virtru.tar.gz to your Virtru representative.

The archive includes:

• The generated public key.
• HMAC token information if HMAC authentication was enabled.

Step 15: Start the VPK Container

Run the generated run.sh file from the working directory.

bash /var/virtru/cks/run.sh

If you used a different working directory, replace /var/virtru/cks with that path.

The generated Docker command starts a container named Virtru_CKS and maps host port 443 to the container's internal Caddy listener on port 9000.

Step 16: Monitor Startup Logs

Follow the container logs.

docker logs -f Virtru_CKS

For a VPK-only deployment, confirm VPK starts successfully.

For a VPK with KAS deployment, confirm the logs show the VPK, KAS, PostgreSQL, and Caddy services starting successfully.

Step 17: Validate the Deployment

From a network location that can reach the VPK FQDN, verify the service responds over HTTPS.

curl https://<CKS_FQDN>/status

Replace <CKS_FQDN> with your VPK hostname.

Rollback or Re-run Guidance

For a fresh install that has not gone live, the setup script can be re-run into a new empty working directory.

Do not overwrite a working directory that contains production keys unless Virtru and your team have confirmed that replacing those keys is acceptable.

Troubleshooting

Docker container does not start

Check whether another service is already using host port 443.

docker logs Virtru_CKS
docker ps -a

KAS does not appear to start

Confirm KAS was enabled during setup and that KAS_ROOT_KEY exists in env/cks.env.

grep KAS_ROOT_KEY /var/virtru/cks/env/cks.env

VPK endpoints fail after startup

Review the container logs and confirm the keys, ssl, and env/cks.env files are mounted from the expected working directory.

docker logs Virtru_CKS