Transit Auto Unseal Primer: Vault-to-Vault Unseal Design and Operations

Transit Auto Unseal shines in environments where cloud KMS is not an option, or when you want to keep the cryptographic boundary entirely between Vault clusters. The unsealer Vault handles encrypt/decrypt with the Transit secrets engine, and the target Vault automatically unseals at startup.

This article walks end-to-end through the mechanism, prerequisites, concrete setup, availability and security operations, and troubleshooting. It also calls out exam-relevant points from an Ops perspective.

How Transit Auto Unseal Works and the Vault-to-Vault Pattern

Transit Auto Unseal protects the target Vault's master key (the key required for decryption) with the Transit secrets engine on another Vault cluster. At init time the master key is encrypted by Transit and stored, and at startup the target calls Transit's decrypt API to auto-unseal. There is no need to manually gather Shamir key shares.

A common misconception is that this is Vault-to-Vault replication. The unsealer Vault only provides cryptographic operations and does not share the target's storage or secrets. Since the Transit cluster's availability directly determines whether the target can restart, an HA configuration behind a load balancer and proper monitoring are essential.

• Transit is just the crypto API provider. Data lives in the target Vault's own storage
• Target Vault startup and restart require Transit's decrypt API (already-running nodes are unaffected)
• Apply least privilege: limit to encrypt/decrypt/rewrap on the specific key only
• Protect the Transit connection with mTLS or a pinned CA, and trace decrypt calls via audit logs

Vault-to-Vault (Transit Auto Unseal) high-level architecture

Target Vault seal configuration (excerpt from vault.hcl)

seal "transit" {
  address        = "https://vault-transit.example.com:8200"
  token          = "s.XXXXXXXXXXXXXXXX"  # In production use a least-privilege token, delivered with strict file permissions
  mount_path     = "transit/"            # Transit engine mount path
  key_name       = "vault-unseal"       # Dedicated unseal key name
  tls_ca_cert    = "/etc/vault/ca-transit.pem"
  tls_server_name= "vault-transit.example.com"
  # namespace   = "admin"               # Set only when using Enterprise Namespaces
}

# Reference: storage example (Raft)
storage "raft" {
  path = "/var/lib/vault/data"
}

listener "tcp" {
  address     = "0.0.0.0:8200"
  tls_disable = 0
  tls_cert_file = "/etc/vault/tls/vault.crt"
  tls_key_file  = "/etc/vault/tls/vault.key"
}

Prerequisites and Design Decisions (Network / Security)

Transit Auto Unseal requires that the target Vault can reach the unsealer Vault's HTTPS endpoint, that certificate validation succeeds, and that a least-privilege token is available. Use an HA configuration behind a load balancer and design for outages and rollovers.

From a security boundary perspective, a leaked Transit token has a large blast radius. Store it with 0600 file permissions or via OS-level secret management, and if possible combine it with host-side KMS/TPM disk protection. Make Transit keys non-deletable and non-exportable, and enable audit logs to trace access.

• Network: open only 8200/tcp (HTTPS) from the target to Transit
• TLS: mTLS or strict CA pinning, plus SNI match (tls_server_name)
• Policy: only update on transit/encrypt and decrypt (plus rewrap if needed)
• Token: use a periodic token for auto-renewal, with monitoring on minimum TTL and renewal
• Audit: enable an audit device on the unsealer side to track API calls

Minimal firewall / security opening (conceptual)

# Example: only outbound from target to the unsealer (LB)
# egress allow: tcp dst=vault-transit.example.com:8200
# ingress deny: (apply your existing operational policy to target ingress)
# When using mTLS, distribute a client cert to the target and require validation on the unsealer

Preparing the Unsealer Vault (Transit Engine, Keys, Policy, Token)

On the Vault cluster acting as the unsealer, enable the Transit secrets engine and create a dedicated unseal key. Next, define a least-privilege policy allowing only encrypt/decrypt (and rewrap if needed), and issue a periodic token bound to that policy.

In production, use a load-balanced endpoint for the address and verify certificate and hostname validation up front. Disable key deletion and export, and rotate keys on a planned schedule (described below).

• When creating the key, set exportable=false and deletion_allowed=false
• Limit the policy to the target key and avoid wildcards
• Use a periodic token so it can auto-renew past expiration (monitoring required)
• Track decrypt requests through the unsealer's audit logs

From enabling Transit to issuing the policy and token (example)

# Enable the Transit engine
vault secrets enable transit

# Create the dedicated unseal key (no deletion, no export)
vault write -f transit/keys/vault-unseal deletion_allowed=false exportable=false

# Create the least-privilege policy
vault policy write transit-unseal - <<'EOF'
path "transit/decrypt/vault-unseal" { capabilities = ["update"] }
path "transit/encrypt/vault-unseal" { capabilities = ["update"] }
path "transit/rewrap/vault-unseal"  { capabilities = ["update"] }
EOF

# Issue a periodic token (e.g., 24h). Run with appropriate parent privileges
vault token create -policy=transit-unseal -period=24h -orphan
# Safely deliver the output token to the target Vault (mind permissions, audit, and storage)

Bootstrapping the Target Vault (Init and Verification)

Add a seal "transit" stanza to vault.hcl on the target Vault and start the service. The first vault operator init encrypts the master key with Transit, and subsequent startups auto-unseal. When using Raft (Integrated Storage), note that the output is a Recovery Key, not Unseal Keys.

After startup, confirm that vault status shows sealed=false, that decrypt calls to Transit appear in the audit log, and that the token auto-renews.

• vault operator init with minimal recovery-shares/threshold quickly bootstraps a test environment
• In production, restrict permissions so only the vault server process user can read the seal token
• Right after init, destroy the root token or store it strictly (only for the minimum required period)

Init and status check (Raft example)

# After starting the Vault service, init (Raft outputs a Recovery Key)
vault operator init -recovery-shares=1 -recovery-threshold=1

# Verify auto unseal
vault status
# Expected: Sealed: false, HA: active/standby, etc.

# Verify calls via Transit-side audit (e.g., file audit)
# Check that transit/decrypt entries appear in /var/log/vault_audit.log

Operational Design Essentials (Availability, Updates, Audit)

Availability: if the Transit cluster goes down, the target cannot unseal during a restart. Combine an HA configuration behind a load balancer with health checks, network reachability monitoring, and certificate expiration monitoring. Already-running nodes are not affected, but rolling restarts will get stuck.

Updates: you can rotate the Transit key while preserving compatibility. Decryption is keyed by the version embedded in the ciphertext, so no immediate action is required. Either restart the target during a planned outage to re-encrypt with the latest key, or wait until the next natural restart.

Audit: enable audit devices on the unsealer side and continuously monitor access to transit/encrypt and decrypt. Dashboard your metrics and logs so you can catch token renewal failures (expirations) and privilege violations early.

• Transit runs HA behind a load balancer; use /v1/sys/health for health checks
• Use a periodic token plus observability over auto-renewal (alert on renewal failure)
• Announce key rotation in advance and test before any change-freeze period begins
• Recommend WORM-equivalent storage for audit logs

Key rotation and health check examples

# Rotate the Transit key (unsealer side)
vault write -f transit/keys/vault-unseal/rotate

# Transit cluster health (via LB)
curl -sS https://vault-transit.example.com:8200/v1/sys/health | jq .

# Verify token renewals (e.g., logs / metrics)
# Set up forwarding of renewal success/failure counts to your monitoring backend

Security Pitfalls and Ops Exam Tips

Over-privileged Transit tokens, mount_path mistakes, and disabling certificate validation are classic ways to lose points. Exams often test the impact of Transit downtime on target restartability, policy minimization, and enabling audit.

When using Enterprise Namespaces, forgetting to set namespace in the seal config produces permission errors (403/404). Behind a load balancer, SNI mismatches cause TLS handshake failures. Both leave clear traces in the logs, so use the messages to triage.

• Wrong mount_path or key_name often produces 404 or permission denied
• TLS fails on tls_server_name mismatch or missing CA
• Note: allowing only transit/decrypt makes the init-time encrypt fail
• Tokens with a max TTL expire in long-running ops; use periodic instead

Privilege verification and error log samples

# Check token capabilities (expected: update only)
vault token capabilities $(vault token lookup -format=json | jq -r .data.id) transit/decrypt/vault-unseal

# Typical log examples (excerpt, pseudo)
# permission denied: path=transit/encrypt/vault-unseal (policy missing)
# TLS handshake error: remote error: tls: bad certificate

Troubleshooting and Verification Checklist

If the target cannot unseal, first verify Transit reachability (DNS, port, certificates), then policy capabilities, and finally token validity. Logs record success or failure of decrypt API calls.

Clock drift (no NTP), proxy-routed connections, and missing namespace specifications are also common causes. Use sys/health to check the unsealer's status and confirm the cluster is not itself sealed.

• Connectivity: curl /v1/sys/health, SNI match, CA validation
• Authorization: inspect capabilities for each of transit/encrypt, decrypt, and rewrap
• Expiration: token lookup for ttl/period and whether renewal logs exist
• Namespace: when using Enterprise, the seal config's namespace must match
• LB: configure health checks so the destination follows leader election

Verification command set

# Unsealer-side health
curl -sS https://vault-transit.example.com:8200/v1/sys/health | jq .

# Target-side state
vault status

# Token info
vault token lookup

# Confirm the Transit path exists (with credentials that have permission)
vault read transit/keys/vault-unseal  # If you lack read permission, a policy deny is also fine (favor least privilege)

Check Your Understanding

Frequently Asked Questions