The Day in the Life of a Secret

1. The key hierarchy

Versus Vault uses envelope encryption. A secret value is never encrypted directly under a shared key. Instead, each secret version is sealed with its own random 256-bit data encryption key (DEK) using AES-256-GCM (authenticated encryption with a fresh 96-bit nonce). That per-secret DEK is then wrapped — encrypted — under a master key-encryption key (KEK), again with AES-256-GCM.

The KEK is either an explicit 256-bit key supplied as VAULT_KEK, or is derived from the deployment's SECRET_KEY using PBKDF2-HMAC-SHA256 with 200,000 iterationsand a vault-specific salt. The sealed blob is self-describing (it carries a kek_ref tag), so the master key can be rotated by re-wrapping DEKs without ever re-encrypting ciphertext, and a future HSM-backed KEK can be introduced without a format change.

The security consequences of this design:

• Blast-radius containment. Every secret has a unique DEK. Recovering the plaintext of one sealed value tells you nothing about any other.
• Authenticated, not just confidential. AES-256-GCM detects tampering — a modified ciphertext fails to decrypt rather than returning garbage.
• Key rotation without downtime. Rotating the KEK re-wraps the small DEKs, not the (potentially large) secret bodies.

2. Writing a secret

Writes go through one enforced service entry point. The caller's capability is asserted, the value is sealed with a fresh DEK, and a new version is written copy-on-write — the prior version is retained, never overwritten — and the operation is appended to the tamper-evident audit chain, all inside a single database transaction.

3. Reading a secret — a person

When a human reads a secret in the UI, the request passes three independent authorization gates before any key material is unwrapped:

1. Module entitlement — is the Secret Vault module licensed (on-prem) or included in the tenant's plan (SaaS)? If not, the request is refused with 402 before anything else runs.
2. RBAC level — the user's role level governs whether the vault is even visible (vault.view / vault.read).
3. Path policy capability — a per-path policy (glob → role → capabilities) must grant the read capability on that specific secret path.

Only after all three pass is the DEK unwrapped, the value decrypted, and the read written to the audit chain.

4. Reading a secret — a machine (service account)

A computer never uses a human's session. It authenticates as an app principal(Versus's service-account model) using the OAuth-style client-credentials pattern:

A minimal service-account read looks like this:

# 1. exchange client credentials for a short-lived bearer
TOKEN=$(curl -s https://versus.example.com/api/vault/token \
  -H 'Content-Type: application/json' \
  -d '{"client_id":"ci-runner","client_secret":"'"$CI_SECRET"'"}' \
  | jq -r .access_token)

# 2. fetch a secret the principal is entitled to (optionally a single field)
curl -s "https://versus.example.com/api/vault/fetch?ref=vault://root/apps/ci/db&field=password" \
  -H "Authorization: Bearer $TOKEN"
# → {"ref":"vault://root/apps/ci/db","value":"…","version":3}

5. The secret-type catalog

Not every secret lives in the same place, and that is deliberate. Application secrets live in the vault, where they are envelope-encrypted, versioned, policy-gated, and rotatable. TLS private keys use the certificate-lifecycle keystore's own AES-256-GCM envelope. A small number of bootstrap keys are process-level: they are what unlock the vault, so they cannot be stored inside it.

The bootstrap keys — the field/KEK master keys, the database URL — are sourced from the environment and are meant to be delivered by a secrets manager (Kubernetes sealed-secrets, an external-secrets operator backed by Vault/KMS) and escrowed. Losing the field/KEK master key means encrypted data is unrecoverable, so it is treated as a disaster-recovery asset.

6. Site-bound devices — the three collector vault modes

Many managed devices sit on networks Versus cannot reach directly; a lightweight collectorreaches them from inside. Device credentials for those targets are resolved on the collectorin one of three modes, chosen per collector, so a customer can decide exactly where device secrets live.

• Mode A — local. A file vault on the collector, sealed with AES-256-GCM under a key derived (HKDF-SHA256) from the collector's own enrolled identity key. The data key is never written to disk, and the secret never leaves the customer network.
• Mode B — cloud-relayed. The control plane hands the collector a per-task encrypted blob, held only in memory and cleared after each task.
• Mode C — external. The collector fetches from the customer's own HashiCorp Vault (KV-v2, AppRole auth); Versus stores only the lookup path, never the value.

All collector traffic is outbound TLS 1.2+, authenticated with a short-lived ES256 bearer token the collector signs with its enrollment key (a certificate-derived identity, not a client certificate) — there are no inbound firewall exceptions into the customer network.

7. How logins validate — the secrets behind authentication

Authentication is itself a consumer of secrets. Each backend uses a different one:

• Local — the password is verified against a one-way PBKDF2-SHA256hash. The plaintext is never stored and never recoverable.
• LDAP / Active Directory — a service account binds with an encrypted bind password (held in the auth backend's encrypted config, not plaintext), locates the user, then verifies the user's own password by re-binding as them.
• OIDC / SAML — the relying party validates the identity provider's RS256-signed ID token against the IdP's published JWKS.

Every path then enforces TOTP MFA (RFC-6238) — the per-user authenticator seed is itself an encrypted secret — and mints a short-lived, rotating JWT for the single-page app.

8. Privileged accounts — check-out & break-glass

Secrets marked privileged (device admin passwords, root accounts) get two extra controls. Exclusive check-out hands the credential to exactly one holder at a time (a database row-lock guarantees exclusivity) and auto-rotates it on check-in, so a password that was on someone's screen is dead the moment they return it. Break-glass reveal is dual-control: a reveal request must be approved by a different person, and the approval yields a single-use token valid for only minutes.

8a. Where a privileged account actually lives — and how the target validates it

A question every network and security reviewer asks: when someone checks a privileged password out of the vault and logs into a device, how does that device validate it against Versus? It doesn't — and it shouldn't. Versus Vault is a credential store (PAM), not the authentication authority for other systems. The device validates against whatever store already owns that account; Versus holds a synchronized copy and controls who may retrieve it. Where Versus syncs the credential therefore depends on where the account's authority is.

• Case A — a local account on the target. The device holds its own copy (a device-local admin, a database sa). Versus rotates it by pushing the new credential to that target and verifying — each target synced individually. The device authenticates locally; Versus is not in the login path.
• Case B — a directory- / AAA-delegated account (the common enterprise pattern). Most organisations give each administrator a second, elevated identity — often prefixed PRV- or EDM- (e.g. PRV-jsmith) — used only for privileged device access, separate from their day-to-day account. That elevated account typically lives in Cisco ISE (in ISE's internal identity store, or in Active Directory that ISE federates to), and the network devices are configured to authenticate administrators against ISE via TACACS+ / RADIUS. Here the authority is ISE/AD, not the device. Versus vaults and rotates that account once, at the authority; every device that trusts ISE honours the change automatically the next time someone logs in — zero per-device syncs.

Versus connects to these authorities through the Authentication Providers integration (Integrations → Identity & Access): Cisco ISE, Cisco ACS, Active Directory / LDAP, Aruba ClearPass, Microsoft NPS / FreeRADIUS, Okta, Entra ID, Ping, Duo, RSA SecurID, and the major PAM stores. Marking a provider vault-managed tells Versus to vault, rotate, and audit the privileged and service accounts it holds — so a PRV- account is checked out, used, returned, and rotated at ISE/AD, and the devices simply keep asking ISE.

9. Rotation

Rotation is verify-before-commit: Versus generates a new credential, applies it to the target device or system, and confirms the new credential actually works before writing the new vault version. If verification fails, the previous credential is restored — a botched rotation never locks you out of a device. A scheduler rotates on a policy interval (90 days by default) and skips secrets that are actively checked out.

10. Tamper-evident audit

Every vault operation — write, read, check-out, reveal, rotate — appends an audit event whose SHA-256 hash covers both its own contents and the previous event's hash. That makes the log a hash-linked chain: deleting or editing any historical entry breaks every hash after it, and a verifier walks the chain to report the exact point of tampering. This is in addition to the flat operational audit log used elsewhere in the platform.

11. Granting access — roles & entitlements

Access to a secret is the intersection of three layers, configured in different places:

A path policy maps a path glob (e.g. apps/ci/**) to a role and a set of capabilities. Roles come from Versus's RBAC; for federated logins, the identity provider's group → role mapping assigns them automatically at each login. Every user also gets a personal namespace — personal/<username>/** — scoped to them alone via ${user} templating, so individuals have private secret storage without an admin creating a policy per person.

12. Self-service access through App Builder

You can publish a no-code App Builder app that gives entitled users a simple "copy this secret" surface — no admin console required. The picker only lists secrets the requester can actually read (it is filtered by the same per-path policy), and the copy goes through the identical policy assertion and audit as any other read. Access is entitlement-gated end to end; the app never widens what a user is allowed to see.

13. Transport & trust boundaries

Secrets in flight are protected end to end. The public API terminates TLS on the app server (a co-located reverse proxy; the app's plain listener is never exposed on the network). Collectors authenticate with a short-lived ES256 bearer token (TLS 1.2+) signed with their enrollment key — a certificate-derived identity, not a client certificate. The vault API requires an authenticated bearer — a human JWT for people, an app-principal token for machines.

What protects the vault. The vault encrypts what it stores, but it is itself unlocked by the master KEK, which is unlocked by VAULT_KEK/SECRET_KEY. Those bootstrap keys therefore sit at the root of trust and must be delivered by your secrets manager and escrowed. This is inherent to any software vault — a key has to come from somewhere the vault can read at boot.

14. Hardware-backed keys & external KMS

For the highest-assurance deployments, the master KEK and TLS private keys can be anchored in hardware. Versus integrates with external key stores at two layers, and we are explicit about which is native versus an integration:

• External KMS / HashiCorp Vault for bootstrap keys — the field/KEK master keys and database URL are delivered from your KMS or secrets operator at deploy time (sealed-secrets / external-secrets), rather than living in a raw environment variable. This is a deployment integration, configured in your orchestration layer.
• HSM-backed KEK / non-exportable TLS keys — the certificate-lifecycle module models HSM custody (Thales, Entrust, AWS/Azure/Google Cloud HSM, PKCS#11) so that private keys can be generated and used inside an HSM and never exported. Binding the vault's master KEK to an HSM is the top item on the vault key-management roadmap; today the KEK is a strong software key (VAULT_KEK or PBKDF2-derived).
• Collector Mode C — for device credentials, the customer's own HashiCorp Vault is a first-class backend today (see §6).