Key Management and Rotation

ActiveCipherStorage uses envelope encryption.

Each file is encrypted with a random data encryption key. That data key is wrapped by a provider and stored in the encrypted file header. The provider can be an environment-variable master key, AWS KMS, or a custom implementation.

Providers

Environment Variable Provider

Use this for local development, tests, or simple deployments:

ActiveCipherStorage.configure do |config|
  config.provider = :env
end

Set a Base64-encoded 32-byte master key:

ACTIVE_CIPHER_STORAGE_MASTER_KEY=<base64-encoded-key>

AWS KMS Provider

Use AWS KMS when you want managed key storage, key policies, audit logs, and KMS-based data key generation.

provider = ActiveCipherStorage::Providers::AwsKmsProvider.new(
  key_id: ENV.fetch("AWS_KMS_KEY_ID")
)

ActiveCipherStorage.configure do |config|
  config.provider = provider
end

Custom Provider

Implement the provider interface when you need a different KMS or secret-management backend.

Key Rotation

ActiveCipherStorage can rotate encrypted data keys by rewriting only the encrypted header. It does not need to rewrite the full file body.

This keeps rotation efficient for large encrypted files stored in S3.

Security Model

• Files use AES-256-GCM authenticated encryption.
• Each encryption operation uses a fresh data key and IV.
• The plaintext data key is not stored.
• Tampered ciphertext fails authentication during decrypt.
• Streaming payloads validate frame order and reject trailing data.