> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gorules.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Secrets management
> Configure envelope encryption with KEK/DEK hierarchy to protect deployment credentials and user-defined secrets.
GoRules BRMS uses **envelope encryption** with a KEK/DEK (Key Encryption Key / Data Encryption Key) hierarchy to protect sensitive data such as deployment credentials and user-defined secrets.
## Architecture
```mermaid theme={null}
flowchart TB
KEK["KEK (Master Key)
AWS KMS / Azure Key Vault /
GCP KMS / Environment"]
KEK -->|wraps/unwraps| DEK_A["DEK-A
(Organisation A)"]
KEK -->|wraps/unwraps| DEK_B["DEK-B
(Organisation B)"]
DEK_A -->|encrypts/decrypts| Secrets_A["Secrets A"]
DEK_B -->|encrypts/decrypts| Secrets_B["Secrets B"]
```
**Flow:**
1. KEK (in KMS) wraps/unwraps the DEKs
2. Each organisation has its own DEK
3. DEK encrypts/decrypts that organisation's secrets
4. Secrets are stored encrypted in the database
## Key hierarchy
| Key | Purpose | Storage |
| -------------------- | ------------------------- | ---------------------------------------- |
| **KEK** (Master Key) | Wraps/unwraps DEKs | External KMS or environment variable |
| **DEK** (Data Key) | Encrypts/decrypts secrets | Encrypted in database (per organisation) |
## Cryptographic specifications
| Component | Algorithm |
| ----------------- | ------------------------------------------------------------------- |
| Secret encryption | AES-256-GCM |
| DEK wrapping | Provider-managed (AWS KMS, Azure Key Vault, GCP KMS) or AES-256-GCM |
## Multi-tenant isolation
Each organisation has its own unique DEK (Data Encryption Key):
* **Cryptographic isolation**: Organisation A's DEK cannot decrypt Organisation B's secrets
* **Breach containment**: If one DEK is compromised, only that organisation's secrets are affected
* **No cross-tenant access**: Even with database access, secrets from other organisations remain encrypted with different keys
## Key management
The KEK (master key) must never be deleted or changed. If the KEK is lost or changed, **all DEKs become unrecoverable** and all encrypted secrets are permanently lost.
**Best practices:**
* **Restrict access**: Only automated systems should have access to the KEK. Human access should be emergency-only.
* **Never delete**: Configure key deletion protection in your KMS provider.
* **Backup carefully**: If using environment variable provider, ensure the master key is securely backed up.
* **Audit access**: Enable KMS audit logging to track all key operations.
| KMS Provider | Recommended Settings |
| --------------- | ------------------------------------------------------------------------------------ |
| AWS KMS | Enable key deletion protection, restrict IAM to `kms:Encrypt` and `kms:Decrypt` only |
| Azure Key Vault | Enable purge protection, use RBAC with minimal permissions |
| GCP KMS | Set key destruction duration, restrict IAM roles |
## Configuration
### Provider selection
Set `SECRETS_PROVIDER` to choose the encryption backend:
| Provider | Value | Description |
| -------------------- | ---------------- | ------------------------------------------------ |
| Environment Variable | `env` | Master key from environment (simple deployments) |
| AWS KMS | `aws-kms` | AWS Key Management Service |
| Azure Key Vault | `azure-keyvault` | Azure Key Vault |
| GCP KMS | `gcp-kms` | Google Cloud KMS |
### Environment variables
#### Provider selection (required)
| Variable | Description |
| ------------------ | ----------------------------------------------------------------- |
| `SECRETS_PROVIDER` | Provider to use: `env`, `aws-kms`, `azure-keyvault`, or `gcp-kms` |
#### Environment variable provider (`env`)
| Variable | Description |
| -------------------- | ------------------------------------------------------------ |
| `SECRETS_MASTER_KEY` | Master key passphrase (any string, min 32 chars recommended) |
#### AWS KMS provider (`aws-kms`)
| Variable | Description |
| ------------------------ | ------------------------------------------------- |
| `SECRETS_AWS_KMS_KEY_ID` | AWS KMS key ID or ARN |
| `SECRETS_AWS_KMS_REGION` | AWS region (optional, falls back to `AWS_REGION`) |
#### Azure Key Vault provider (`azure-keyvault`)
| Variable | Description |
| --------------------------------- | ------------------------------------------------------- |
| `SECRETS_AZURE_KEYVAULT_URL` | Key Vault URL (e.g., `https://myvault.vault.azure.net`) |
| `SECRETS_AZURE_KEYVAULT_KEY_NAME` | Key name in the vault |
#### GCP KMS provider (`gcp-kms`)
| Variable | Description |
| -------------------------- | -------------------------------------------------------------------- |
| `SECRETS_GCP_KMS_KEY_NAME` | Full resource name: `projects/*/locations/*/keyRings/*/cryptoKeys/*` |
#### Cache settings
| Variable | Default | Description |
| ------------------------------- | ------- | ------------------------------------------ |
| `SECRETS_DEK_CACHE_TTL_MINUTES` | `240` | How long to cache decrypted DEKs in memory |
### Example configurations
```bash AWS KMS theme={null}
SECRETS_PROVIDER=aws-kms
SECRETS_AWS_KMS_KEY_ID=arn:aws:kms:us-east-1:123456789:key/12345-abcd-6789
SECRETS_AWS_KMS_REGION=us-east-1
```
```bash Azure Key Vault theme={null}
SECRETS_PROVIDER=azure-keyvault
SECRETS_AZURE_KEYVAULT_URL=https://mycompany-vault.vault.azure.net
SECRETS_AZURE_KEYVAULT_KEY_NAME=gorules-master-key
```
```bash GCP KMS theme={null}
SECRETS_PROVIDER=gcp-kms
SECRETS_GCP_KMS_KEY_NAME=projects/my-project/locations/us-east1/keyRings/my-ring/cryptoKeys/gorules-key
```
```bash Environment Variable theme={null}
SECRETS_PROVIDER=env
SECRETS_MASTER_KEY=your-secure-passphrase-at-least-32-characters
```
## Limits
| Limit | Value |
| -------------------------------- | ----- |
| Maximum secret value size | 32 KB |
| Maximum secrets per organisation | 1,000 |