Skip to main content
Welcome to Virtru's support portal. As we work to make this page more accessible to screen readers, please contact us at support@virtru.com for technical support.

Reference: Virtru Private Keystore (for Google Workspace CSE) Key Rotation for Existing Customers (Non-CKS)

  • Updated

Prerequisites

As an existing CSE customer, you will first need to upgrade your CSE container to v5.4.0 or later. Steps to upgrade to the latest CSE version can be found here:

 

Next you will need to define the SECRET_KEYS_PATH in your cse.env file, run a predefined command to store the existing secret (this is necessary for existing policies can be unwrapped), and comment out the SECRET_KEY env variable that was written when you first installed CSE.

 

Steps to Import Current CSE Key

1. Append your cse.env file with the variable below, and comment out the existing ‘SECRET_KEY’ variable

SECRET_KEYS_PATH=/app/cse/secrets.json

 

Sample .env file after making the required updates:

HMAC_TOKEN_ID=yourtokenID
HMAC_TOKEN_SECRET=yourtokenSecret
#CKS_HMAC_TOKEN_ID=
#CKS_HMAC_TOKEN_SECRET=
JWKS_AUTHN_ISSUERS=eyAiaHR0cHM6229hY2NvdW50cy5nb29nbGUuY29tIjogImh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL29hdXRoMi92My9jZXJ0cyIgfQo=
JWKS_AUTHZ_ISSUERS=eyAiZ3N1aXRlY3N22XRva2VuaXNzdWVyLWRyaXZlQHN5c3RlbS5nc2VydmljZWFjY291bnQuY29tIjogImh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL3NlcnZpY2VfYWNjb3VudHMvdjEvandrL2dzdWl0ZWNzZS10b2tlbmlzc3Vlci1kcml2ZUBzeXN0ZW0uZ3NlcnZpY2VhY2NvdW50LmNvbSIsImdzdWl0ZWNzZS10b2tlbmlzc3Vlci1tZWV0QHN5c3RlbS5nc2VydmljZWFjY291bnQuY29tIjogImh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL3NlcnZpY2VfYWNjb3VudHMvdjEvandrL2dzdWl0ZWNzZS10b2tlbmlzc3Vlci1tZWV0QHN5c3RlbS5nc2VydmljZWFjY291bnQuY29tIiwiZ3N1aXRlY3NlLXRva2VuaXNzdWVyLWNhbGVuZGFyQHN5c3RlbS5nc2VydmljZWFjY291bnQuY29tIjogImh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL3NlcnZpY2VfYWNjb3VudHMvdjEvandrL2dzdWl0ZWNzZS10b2tlbmlzc3Vlci1jYWxlbmRhckBzeXN0ZW0uZ3NlcnZpY2VhY2NvdW50LmNvbSIgfQo=
JWT_AUD=eyAiYXV0aG4iOiAiNjcxN222MDI3OTE1LWU2b2RqMGpvcTF2MjhmY2Y4Z2s3Y203MTZvdjVkMGdtLmFwcHMuZ29vZ2xldXNlcmNvbnRlbnQuY29tIiwgImF1dGh6IjogImNzZS1hdXRob3JpemF0aW9uIiB9Cg==
JWT_KACLS_URL=https://csesrv.yourdomain.com
TAKEOUT_CLAIM=cse_takeout
ACM_URL=https://api.virtru.com/acm/api
ACCOUNTS_URL=https://api.virtru.com/accounts/api
#CKS_URL=
PORT=9000
USE_SSL=true
USE_CKS=false
#SECRET_KEY=my-existing-secret-name:a6rRVqAPt8DKp3oB25xzjOlDZOz5t/wBMT8KuhRM=
SECRET_KEYS_PATH=/app/cse/secrets.json

 

2. Create the file ‘secrets.json’ in your CSE working directory.

vi secrets.json

The file contents should be the below:

{}

 

3. Update the permissions on secrets.json file

chmod 646 secrets.json

 

4. Stop, and remove the CSE container

docker stop <containerID> 
docker rm <containerID>

 

4. Run the store-secret command to store your existing secret key value

The format for the key value is below and can be found in your cse.env file

  • -n = Name of the Key value (this can be named to your preference)

  • -v = Key Value (found in existing cse.env file)

  • --active = Flag that sets key as active

Example Command to store existing secret:

docker run --env-file /var/virtru/cse/cse.env --mount type=bind,source=/var/virtru/cse/secrets.json,target=/app/cse/secrets.json -p 443:9000 virtru/cse:v5.4.0 store-secret -n my-existing-secret-name -v a6rRVqAPt8DKp3oB25xzjOlDZOz5t/wBMT8KuhRM= --active

 

Expected Output:

RUNNING COMMAND: store-secret

A new secret has been successfully generated and stored in the secrets file.

New Secret:

my-existing-secret-name

 

5. Print the secret.json file after running store secret. Ensure that your secret is set to active

cat secrets.json

Expected Result

{"active":"my-existing-secret-name","secrets":[{"name":"my-existing-secret-name","value":"a6rRVqAPt8DKp3oB25xzjOlDZOz5t/wBMT8KuhRM="}]}

 

6. Clear out any temporary CSE containers created while importing the secret

docker ps
docker rm <containerID>

 

 

Steps to Generate New CSE Key and Perform Rotation

1. Generate additional key value while mounting secrets.json file. This will automatically set this newly generated key to active, effectively rotating the key CSE will use to protect your data.

docker run --env-file /var/virtru/cse/cse.env --mount type=bind,source=/var/virtru/cse/secrets.json,target=/app/cse/secrets.json -p 443:9000 virtru/cse:v5.4.0 generate-secret


Expected Output:

RUNNING COMMAND: generate-secret

A new secret has been successfully generated and stored in the secrets file.

New Secret:

46dde40711581519

Existing Secret:

my-existing-secret-name

 

In the secrets.json file, you will see a new secret key value defined, as well as the existing key that was imported during the steps at the beginning of this document.

{"active":"46dde40711581519","secrets":[{"name":"my-existing-secret-name","value":"urVUMN6OOdRryyeaba6K725LlSkOA1+dCm9gjf85bLs="},{"name":"46dde40711581519","value":"ndNx8qyGvolkt+9mDfKtX20q7xTBZdIrDNiNVIfnad12"}]}

 

2. Clear out any temporary CSE containers created while generating the new secret

docker ps
docker rm <containerID>

 

3. Update your existing run.sh script to mount the secrets.json file that contains your CSE keys (Line 6 is where the update should be made)

docker run --detach \
--env-file ./cse.env \
-p 443:9000 \
-v /var/virtru/cse/server.cert:/run/secrets/server.cert \
-v /var/virtru/cse/server.key:/run/secrets/server.key \
-v /var/virtru/cse/secrets.json:/app/cse/secrets.json \
--restart unless-stopped \
--name cse-5.4.0 \
virtru/cse:v5.4.0

 

4. Execute the run.sh script to start your CSE container after completing the key rotation

sh run.sh

 

5. Check your Docker status to see that the container starts as expected

docker ps

Example Healthy Output

CONTAINER ID  IMAGE NAMES          COMMAND                  CREATED         STATUS         PORTS                                     NAMES                 

9155beb69ec8   virtru/cse:v5.4.0   "/bin/bash /app/cse/…"   2 seconds ago   Up 2 seconds   0.0.0.0:443->9000/tcp, :::443->9000/tcp   cse-5.4.0

 

6. Log in to your Google Workspace and create an encrypted piece of content to ensure the updated key is successfully wrapping your content

 

7. Check the logs for successful creation and wrap of your content. Example of logs can be found below

docker logs <containerID> -f
{"timestamp":"2023-03-24T15:20:16.564Z","level":"INFO","data":["Wrap requested by \"testuser@virtrudeploy.com\" on resource \"//googleapis.com/drive/files/1FRteBRUta3451j0camPGPhhVXT1AUcDV-\" with reason \"\"",{"requestId":"2023-03-24T15:20:16.431Z-dd077861-8047-48c4-8346-0b286fb3c602"}],"context":{},"pid":15,"cluster":{"workerId":1,"worker":15}}, 

create policy: 49.07ms

{"timestamp":"2023-03-24T15:20:16.614Z","level":"INFO","data":["Policy created for \"//googleapis.com/drive/files/1FRteBRUta3451j0camPGPhhVXT1AUcDV-\" with policy id \"3b6d3bdb-4333-4ebe-a233-3093c58d35af\"",{"requestId":"2023-03-24T15:20:16.431Z-dd077861-8047-48c4-8346-0b286fb3c602"}],"context":{},"pid":15,"cluster":{"workerId":1,"worker":15}},

wrap: 185.557ms

 

For HA Implementation: Steps to use your new key across multiple CSE servers

If you have multiple CSE servers and are conducting a key rotation, you will need to complete the following steps to ensure all servers are using the same secret key value.

1. Copy your newly created secrets.json file from your primary CSE server to the working directory on your next CSE server

 

2. Update your cse.env file on your next server to include the new variable, and comment out the existing SECRET_KEY variable

SECRET_KEYS_PATH=/app/cse/secrets.json

#SECRET_KEY=my-existing-secret-name:a6rRVqAPt8DKp3oB25xzjOlDZOz5t/wBMT8KuhRM=

 

3. Update your run.sh file to match your primary CSE servers working directory configuration. The script should include the same version number and mount your secrets.json inside the container

Example Script:

docker run --detach \
--env-file ./cse.env \
-p 443:9000 \
-v /var/virtru/cse/server.cert:/run/secrets/server.cert \
-v /var/virtru/cse/server.key:/run/secrets/server.key \
-v /var/virtru/cse/secrets.json:/app/cse/secrets.json \
--restart unless-stopped \
--name cse-5.4.0 \
virtru/cse:v5.4.0
4. Stop, remove and start your CSE server to pick up the changes made
docker stop <containerID>
docker rm <contianerID>
sh run.sh
5. Log in to your Google Workspace and create an encrypted piece of content to ensure the updated key is successfully wrapping your content
6. Repeat as needed for additional CSE servers in your environment

Related articles