Encryption

Protect sensitive data with envelope encryption and KMS integration.

Table of contents

  1. Overview
  2. Encryption at Rest
    1. What’s Encrypted
    2. Algorithm
  3. KMS Providers
  4. EnvKeyProvider (Development)
    1. Configuration
  5. AWS KMS
    1. Prerequisites
    2. IAM Policy
    3. Configuration
    4. Environment Variables
  6. HashiCorp Vault
    1. Prerequisites
    2. Vault Setup
    3. Configuration
  7. GCP Cloud KMS
    1. Prerequisites
    2. IAM Permissions
    3. Configuration
  8. Azure Key Vault
    1. Prerequisites
    2. Configuration
    3. Environment Variables
  9. Envelope Encryption
    1. Benefits
  10. TLS Configuration
    1. Self-Signed (Development)
    2. Custom Certificates
  11. Memory Protection
    1. SecretBytes
    2. Properties
  12. Security Best Practices
    1. Key Management
    2. Network Security
  13. Next Steps

Overview

Rustberg implements defense-in-depth encryption:

Layer Protection Implementation
In Transit Network traffic TLS 1.3 (rustls)
At Rest Stored data AES-256-GCM
In Memory Secrets Zeroize on drop
Key Management Master keys KMS providers

Encryption at Rest

What’s Encrypted

Data Encrypted Notes
API key metadata ✅ Name, tenant, roles
Table properties ✅ With EncryptedCatalog
Namespace properties ✅ With EncryptedCatalog
Index data ❌ Performance optimization

Algorithm

  • Cipher: AES-256-GCM (Galois/Counter Mode)
  • Key Size: 256 bits (32 bytes)
  • Nonce: 96 bits, random per encryption
  • Tag: 128 bits (authentication)

KMS Providers

Rustberg supports 5 KMS providers:

Provider Feature Flag Use Case
EnvKeyProvider Default Development
AWS KMS aws-kms AWS production
HashiCorp Vault vault-kms Multi-cloud
GCP Cloud KMS gcp-kms GCP production
Azure Key Vault azure-kms Azure production

EnvKeyProvider (Development)

Simple key provider using environment variable:

# Generate 32-byte key (base64)
export RUSTBERG_MASTER_KEY=$(openssl rand -base64 32)

# Start Rustberg
./rustberg --storage file:///data

Configuration 

[kms]
provider = "env"
key_env_var = "RUSTBERG_MASTER_KEY"

EnvKeyProvider is for development only. Use cloud KMS in production.

AWS KMS

Prerequisites

  1. Create a KMS key in AWS Console
  2. Configure IAM permissions

IAM Policy 

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "kms:Encrypt",
        "kms:Decrypt",
        "kms:GenerateDataKey"
      ],
      "Resource": "arn:aws:kms:us-east-1:123456789:key/your-key-id"
    }
  ]
}

Configuration 

[kms]
provider = "aws"
key_id = "arn:aws:kms:us-east-1:123456789:key/your-key-id"
aws_region = "us-east-1"

Environment Variables 

export AWS_ACCESS_KEY_ID=your_key
export AWS_SECRET_ACCESS_KEY=your_secret
export AWS_REGION=us-east-1

HashiCorp Vault

Prerequisites

  1. Running Vault instance
  2. Transit secrets engine enabled
  3. Named encryption key created

Vault Setup 

# Enable Transit engine
vault secrets enable transit

# Create encryption key
vault write -f transit/keys/rustberg-key

# Create policy
vault policy write rustberg - <<EOF
path "transit/encrypt/rustberg-key" {
  capabilities = ["update"]
}
path "transit/decrypt/rustberg-key" {
  capabilities = ["update"]
}
EOF

# Create token
vault token create -policy=rustberg

Configuration 

[kms]
provider = "vault"
vault_addr = "https://vault.example.com:8200"
vault_token_env = "VAULT_TOKEN"
key_name = "rustberg-key"
transit_mount = "transit"

GCP Cloud KMS

Prerequisites

  1. Create a key ring and crypto key in GCP Console
  2. Configure service account permissions

IAM Permissions 

gcloud kms keys add-iam-policy-binding rustberg-key \
  --keyring=rustberg-keyring \
  --location=global \
  --member=serviceAccount:rustberg@project.iam.gserviceaccount.com \
  --role=roles/cloudkms.cryptoKeyEncrypterDecrypter

Configuration 

[kms]
provider = "gcp"
project_id = "your-project"
location = "global"
key_ring = "rustberg-keyring"
crypto_key = "rustberg-key"

Azure Key Vault

Prerequisites

  1. Create a Key Vault in Azure Portal
  2. Create an RSA key for encryption
  3. Configure access policies

Configuration 

[kms]
provider = "azure"
vault_url = "https://rustberg-vault.vault.azure.net"
key_name = "rustberg-key"

Environment Variables 

export AZURE_CLIENT_ID=your-client-id
export AZURE_CLIENT_SECRET=your-client-secret
export AZURE_TENANT_ID=your-tenant-id

Envelope Encryption

Rustberg uses envelope encryption for efficiency:

┌─────────────────────────────────────────────────────────┐
│                  Envelope Encryption                     │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  1. Generate random Data Encryption Key (DEK)           │
│     DEK = random(32 bytes)                              │
│                                                          │
│  2. Encrypt data with DEK (fast, local)                 │
│     ciphertext = AES-256-GCM(data, DEK)                 │
│                                                          │
│  3. Wrap DEK with KMS (one API call)                    │
│     wrapped_dek = KMS.encrypt(DEK)                      │
│                                                          │
│  4. Store: ciphertext + wrapped_dek                     │
│                                                          │
└─────────────────────────────────────────────────────────┘

Benefits

Benefit Why
Performance AES-GCM is fast (hardware accelerated)
Reduced KMS calls One wrap/unwrap per DEK, not per record
Key rotation Re-wrap DEKs without re-encrypting data
Cost Fewer KMS API calls

TLS Configuration

Self-Signed (Development) 

# Generate self-signed certificate
./rustberg generate-cert --common-name localhost

# Start with the generated certificate
./rustberg \
  --tls-cert ./cert.pem \
  --tls-key ./key.pem

Custom Certificates 

./rustberg \
  --tls-cert /path/to/cert.pem \
  --tls-key /path/to/key.pem

TLS is required in production. Use --insecure-http only for development.

Memory Protection

SecretBytes

Sensitive data uses SecretBytes wrapper:

use rustberg::crypto::secrets::SecretBytes;

let secret = SecretBytes::new(api_key.as_bytes());
// Secret is automatically zeroed when dropped

Properties

Property Implementation
Zeroize on drop Memory cleared when out of scope
No Debug Cannot accidentally log secrets
No Clone Prevents uncontrolled copies

Security Best Practices

Key Management

  • Never store keys in source control
  • Use cloud KMS in production
  • Rotate keys annually minimum
  • Audit key usage via KMS logs

Network Security

  • Always use TLS in production
  • Validate server certificates
  • Use private networks when possible

Next Steps