Skip to main content
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

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

KeyPurposeStorage
KEK (Master Key)Wraps/unwraps DEKsExternal KMS or environment variable
DEK (Data Key)Encrypts/decrypts secretsEncrypted in database (per organisation)

​
Cryptographic specifications

ComponentAlgorithm
Secret encryptionAES-256-GCM
DEK wrappingProvider-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 ProviderRecommended Settings
AWS KMSEnable key deletion protection, restrict IAM to kms:Encrypt and kms:Decrypt only
Azure Key VaultEnable purge protection, use RBAC with minimal permissions
GCP KMSSet key destruction duration, restrict IAM roles

​
Configuration

​
Provider selection

Set SECRETS_PROVIDER to choose the encryption backend:
ProviderValueDescription
Environment VariableenvMaster key from environment (simple deployments)
AWS KMSaws-kmsAWS Key Management Service
Azure Key Vaultazure-keyvaultAzure Key Vault
GCP KMSgcp-kmsGoogle Cloud KMS

​
Environment variables

​
Provider selection (required)

VariableDescription
SECRETS_PROVIDERProvider to use: env, aws-kms, azure-keyvault, or gcp-kms

​
Environment variable provider (env)

VariableDescription
SECRETS_MASTER_KEYMaster key passphrase (any string, min 32 chars recommended)

​
AWS KMS provider (aws-kms)

VariableDescription
SECRETS_AWS_KMS_KEY_IDAWS KMS key ID or ARN
SECRETS_AWS_KMS_REGIONAWS region (optional, falls back to AWS_REGION)

​
Azure Key Vault provider (azure-keyvault)

VariableDescription
SECRETS_AZURE_KEYVAULT_URLKey Vault URL (e.g., https://myvault.vault.azure.net)
SECRETS_AZURE_KEYVAULT_KEY_NAMEKey name in the vault

​
GCP KMS provider (gcp-kms)

VariableDescription
SECRETS_GCP_KMS_KEY_NAMEFull resource name: projects/*/locations/*/keyRings/*/cryptoKeys/*

​
Cache settings

VariableDefaultDescription
SECRETS_DEK_CACHE_TTL_MINUTES240How long to cache decrypted DEKs in memory

​
Example configurations

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

​
Limits

LimitValue
Maximum secret value size32 KB
Maximum secrets per organisation1,000