Encryption and Secret Sources
All sensitive credential values in Zerq are encrypted at rest using AES-256-GCM. This page explains the encryption model and how to configure secret sources.
AES-256-GCM encryption at rest
Every sensitive field in every credential is individually encrypted before being written to the database:
- Algorithm: AES-256-GCM (authenticated encryption with associated data)
- Key size: 256-bit (32 bytes), base64-encoded
- Nonce: Unique per-value — each field gets a fresh nonce on every write
- Integrity: GCM authentication tag prevents tampering
- At rest: Ciphertext + nonce stored in the database
- At runtime: Decrypted in-memory only at the moment the gateway needs to make an outbound request
The encryption key is provided via the ENCRYPTION_KEY environment variable on the backend gateway process. If this variable is missing or wrong, credential decryption fails at runtime with an internal error.
Key rotation
To rotate the encryption key:
- Generate a new 32-byte key and base64-encode it
- Re-encrypt all credentials using a migration step
- Update the
ENCRYPTION_KEYenvironment variable - Restart the gateway
Never log, expose, or commit the ENCRYPTION_KEY value. If compromised, all stored credentials must be re-encrypted with a new key.
What is encrypted
The following fields are encrypted for each credential type:
| Credential type | Encrypted fields |
|---|---|
| Basic Auth | password |
| API Key | api_key |
| OAuth2 Client Credentials | client_secret |
| mTLS Client Certificate | client_cert_pem, client_key_pem, ca_cert_pem |
| MongoDB | uri (connection string) |
| PostgreSQL | Full DSN string |
| SQL Server | Full connection string |
| Oracle | Connection string / DSN |
| Redis | password |
| SMTP | password |
| SendGrid | api_key |
| Kafka | sasl_password, ssl_key_pem, ssl_cert_pem, ssl_ca_pem |
Non-sensitive fields (host, port, username, database name) are stored unencrypted for display purposes.
Secret sources
Zerq supports two sources for credential values:
1. Direct value (stored encrypted)
Enter the value directly in the Management UI. Zerq encrypts it before saving to the database. The UI never displays the value again after saving (show/hide only applies to unencrypted client credentials, not backend credential secrets).
2. Environment variable reference
Instead of storing the value, reference a container environment variable by name. Zerq reads the environment variable at runtime when it needs the value.
See Env-Backed Secrets for the full per-field env-var pattern.
Credentials in UI
- Sensitive fields are masked in the Management UI
- Admin users with credential edit permissions can update values but cannot view them
- All create, update, and delete actions on credentials are written to the audit log
Related docs
- Env-Backed Secrets — reference environment variables per credential field
- Credentials Overview — how credentials are attached and scoped
- Secret Management — platform-wide secrets strategy