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: KAS Key Metadata File

  • Updated

Purpose

This article reviews the purpose of the new KAS key metadata file, key-metadata.json, for Virtru Private Keystore (VPK) deployments with Key Access Service (KAS) enabled.

The key metadata file is the persistent ledger that records which VPK keys have been bootstrapped into KAS and which key is currently active. KAS uses this file during startup to rebuild its internal PostgreSQL key store.

Important: Back up /var/virtru/cks/keys/key-metadata.json after first boot and after every key rotation.

Note: This path uses the default host working directory, /var/virtru/cks. If your deployment uses a different working directory, replace /var/virtru/cks with your host path.

When This Applies

This article applies only to VPK deployments with KAS enabled.

KAS is enabled when KAS_ROOT_KEY is set in cks.env. If KAS_ROOT_KEY is not set, KAS remains disabled and this metadata file is not part of the active VPK runtime path.

Why the File Exists

KAS uses an internal PostgreSQL database as its runtime key store. That database is intentionally ephemeral and does not need to be backed up.

Instead, KAS rebuilds PostgreSQL on startup from three durable sources:

  • The key files in the host directory /var/virtru/cks/keys/
  • The KAS_ROOT_KEY value from cks.env
  • The key metadata file at /var/virtru/cks/keys/key-metadata.json

The metadata file tells KAS which keys should be imported and which key should be treated as active.

What Happens During Startup

When a KAS-enabled VPK container starts, KAS uses the metadata file persisted at /var/virtru/cks/keys/key-metadata.json to determine which keys should exist in PostgreSQL.

Backup Recommendations

For KAS-enabled VPK deployments, include these items in your backup process:

ItemRequired?Why
/var/virtru/cks/keys/*.pub and /var/virtru/cks/keys/*.pemRequiredThese are the raw key files. Loss of private key material is unrecoverable.
KAS_ROOT_KEYRequiredThis value is required to wrap private keys during bootstrap.
/var/virtru/cks/keys/key-metadata.jsonRequired after first boot and after every key rotationThis file records all bootstrapped keys and the active key.
cks.envStrongly recommendedThis preserves the rest of the VPK and KAS runtime configuration.

You do not need to back up the internal PostgreSQL database. KAS reconstructs it from the key files, KAS_ROOT_KEY, and key-metadata.json.

How to Snapshot the Metadata File

Copy the metadata file from the host working directory after first boot and after every key rotation.

cp /var/virtru/cks/keys/key-metadata.json ./key-metadata.json

Important: Treat loss of /var/virtru/cks/keys/key-metadata.json as an operational incident. The current active key may continue to work until restart, but older rotated keys may be missing after PostgreSQL is rebuilt.

Troubleshooting

The metadata file is missing

If /var/virtru/cks/keys/key-metadata.json is missing, do not restart the KAS-enabled VPK deployment unless directed by Virtru support.

A restart may rebuild PostgreSQL without older rotated keys, which can prevent decryption of TDFs encrypted with those keys.

A backup was not taken after key rotation

Copy the current metadata file from the host working directory as soon as possible and store it with the rest of your VPK backup material.

cp /var/virtru/cks/keys/key-metadata.json ./key-metadata.json

If the deployment has already restarted and older keys are missing, contact Virtru support for recovery guidance.

Related articles