> ## 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)<br/>AWS KMS / Azure Key Vault /<br/>GCP KMS / Environment"]

    KEK -->|wraps/unwraps| DEK_A["DEK-A<br/>(Organisation A)"]
    KEK -->|wraps/unwraps| DEK_B["DEK-B<br/>(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

<Warning>
  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.
</Warning>

**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

<CodeGroup>
  ```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
  ```
</CodeGroup>

## Limits

| Limit | Value |
| - | - |
| Maximum secret value size | 32 KB |
| Maximum secrets per organisation | 1,000 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.