Rails Active Storage Encryption

ActiveCipherStorage provides transparent encryption and decryption for Rails Active Storage attachments.

Application code can keep using normal Active Storage APIs such as has_one_attached, attach, and download. The storage service encrypts bytes before they are written to storage and decrypts them when they are read.

Why Use It

Rails Active Storage stores uploaded files in services such as S3, local disk, or compatible object storage. ActiveCipherStorage adds an application-side encryption layer so files are encrypted before they leave the Rails process.

This is useful when you need:

• Rails Active Storage encryption for user uploads.
• Encrypted file storage in S3.
• AES-256-GCM authenticated encryption.
• AWS KMS or custom key provider integration.
• Compatibility with existing plaintext blobs.

Basic Setup

Add the gem:

gem "active_cipher_storage"

Configure a provider:

ActiveCipherStorage.configure do |config|
  config.provider = :env
  config.chunk_size = 5 * 1024 * 1024
  config.encrypt_uploads = true
end

Use the encrypted service in config/storage.yml:

encrypted_s3:
  service: ActiveCipherStorage
  inner:
    service: S3
    bucket: <%= ENV.fetch("AWS_BUCKET") %>
    region: <%= ENV.fetch("AWS_REGION") %>

Set Active Storage to use it:

config.active_storage.service = :encrypted_s3

Plaintext Compatibility

Downloads auto-detect the payload format. If a file starts with the ActiveCipherStorage header, it is decrypted. If not, it is returned as plaintext.

This lets existing Rails Active Storage blobs keep working while new uploads are encrypted.

Disabling Encryption for New Uploads

Set:

config.encrypt_uploads = false

New Active Storage uploads will be stored as plaintext and marked with encrypted: false metadata. Existing encrypted blobs still decrypt correctly.