Vault module
Layer 5. Objects. Objects
Overview
Section titled “Overview”SHC’s vault provides encrypted secrets storage with support for multiple providers.
Encryption
Section titled “Encryption”Envelope encryption, and there is exactly one at-rest format.
- One Argon2id key-encryption key (KEK) derived per unlock from the
user-provided vault password plus one cluster-wide
kek_salt, cached in memory until lock. - A random per-row AES-256-GCM data-encryption key (DEK), wrapped by the KEK and stored beside the payload. A read is an unwrap + decrypt: no KDF per row.
- Stored form:
v2:+ base64( version byte, DEK nonce, wrapped DEK, payload nonce, payload ciphertext ). Thev2:tag exists so a value written by a pre-envelope release is recognised and refused by name (X400980VLTFMT) instead of failing as corrupt ciphertext. - The
kek_saltis never regenerated once envelope data exists; a new salt derives a different KEK and orphans every value, so those paths fail closed and point at avault_configrestore.
The retired format. Before v0.0.16 rows were PBKDF2-480k Fernet (AES-128-CBC + HMAC-SHA256). It has no reader and no writer: no
crypto_formatwrite epoch, no dual-format box, no fallback, and the bidirectionalshc vault migrateverb is deleted. The flip is a one-waymake migratestep that REFUSES to apply while any retired-format row or verifier survives. Both production estates measured 100% envelope before the retirement landed.Fernet does survive for one unrelated job: the password-based export bundle (
shc vault export/importand the backup manifest’s inline secrets bundle), where the caller supplies the password and another cluster has to be able to read the bytes. That ismodules/vault/crypto.go, and it is not an at-rest format.
Secret Scoping
Section titled “Secret Scoping”Path depth determines scope:
{tenant}/{secret}→ tenant scope (2 levels){tenant}/{stack}/{secret}→ stack scope (3 levels){tenant}/envs/{environment}/{secret}→ environment scope (4 levels){tenant}/{stack}/{environment}/{secret}→ deployment scope (4 levels)
Resolution order (specific to general):
- Deployment (tenant + stack + environment)
- Stack (tenant + stack)
- Environment (tenant + environment)
- Tenant
Note: “system” is a tenant, not a special scope. “envs” is reserved and cannot be used as a stack name.
Secret References
Section titled “Secret References”In config files:
database: password: !ref+vault://db_passwordsmtp: api_key: !ref+env://SMTP_API_KEY?default=test-keyExternal Providers
Section titled “External Providers”Supported providers:
| Provider | Config Key | Required Settings | Transport |
|---|---|---|---|
| Built-in encrypted database | local (default) | vault.password | Database |
| Pass (password-store) | pass | None (uses ~/.password-store) | CLI (apt) |
| SOPS | sops | file_path | CLI |
| Doppler | doppler | token, project, config | HTTP |
| Infisical | infisical | client_id, client_secret, project_id, environment | HTTP |
| 1Password Connect | 1password | connect_host, connect_token, vault_uuid | HTTP |
| HashiCorp Vault | hashicorp | address, token or role_id/secret_id | HTTP/SDK |
| AWS Secrets Manager | aws | region | SDK (boto3) |
| Azure Key Vault | azure | vault_url | SDK |
| Google Secret Manager | gcp | project_id | SDK |
| Bitwarden Secrets Manager | bitwarden | access_token, organization_id | SDK |
Configure per scope in config.yaml:
vault: provider: aws aws: region: us-east-1
# Or use multiple providersvault: provider: doppler # default providers: doppler: token: dop_... project: myproject config: prod sops: file_path: /etc/shc/secrets.yaml age_key_file: /etc/shc/age.keyProvider Chaining
Section titled “Provider Chaining”Vault providers can reference secrets from other providers in their configuration. This enables bootstrapping complex setups where credentials for one provider are stored in another.
vault: providers: # Pass has no dependencies - initialized first pass: gpg_id: ABCD1234
# AWS credentials stored in pass aws: region: us-east-1 access_key_id: ref+vault://aws_access_key secret_access_key: ref+vault://aws_secret_key
# HashiCorp token from pass or aws hashicorp: address: https://vault.example.com token: ref+vault://hc_tokenResolution algorithm:
- Providers with no vault refs are initialized first
- Remaining providers are iteratively resolved using already-resolved ones
- Process continues until all resolved or no progress (circular/missing deps)
Vault paths follow scoping rules (tenant/stack/secret), not provider names. Auto-resolution tries all resolved providers in order until one succeeds.
Explicit provider (discouraged): ref+vault://secret?provider=pass targets specific provider via query param.
Export/Import
Section titled “Export/Import”Export format (.vlt):
{ "version": "1", "encrypted": true, "secrets": { "db_password": "Z0FBQUFCYWJjMTIz..." }}