You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* chore: prepare 1.0.3 release
Bumps the gem version and updates the changelog for a documentation-focused release with a clearer README.
* docs: adjust 1.0.3 changelog wording
Keeps the 1.0.3 release notes focused on README usability improvements.
ActiveCipherStorage is a Ruby gem for Rails Active Storage encryption and decryption. It encrypts files before they are stored, decrypts them when they are read, and supports AWS S3, streaming downloads, multipart uploads, AES-256-GCM envelope encryption, AWS KMS, and custom key providers.
5
+
Active Cipher Storage is published as the `active_cipher_storage` Ruby gem.
6
6
7
-
ActiveCipherStorage supports three upload paths:
7
+
It adds Rails Active Storage encryption and decryption without changing the way your Rails app attaches files. Files are encrypted before they are stored in AWS S3 or another storage service, and decrypted when your app reads them back.
8
8
9
-
-**Rails Active Storage** — application code keeps using normal attachment APIs while the storage service encrypts on upload and decrypts on download.
10
-
-**Direct S3 clients** — service objects and non-Rails apps can call `put_encrypted`, `get_decrypted`, and `stream_decrypted`.
11
-
-**Frontend chunk uploads** — the frontend sends plaintext chunks to your backend; the backend encrypts those chunks and uploads encrypted S3 multipart parts.
9
+
This solves a common Rails security problem: sensitive files should be protected before they leave your application.
10
+
11
+
It works with normal Rails Active Storage attachments, direct S3 uploads from Ruby service objects, streaming downloads, and backend-managed multipart uploads for large files.
12
+
13
+
## Features
14
+
15
+
- Encrypt files before uploading them to S3 or Active Storage.
16
+
- Decrypt files automatically when downloading.
17
+
- Works with Rails Active Storage.
18
+
- Supports direct AWS S3 client usage.
19
+
- Handles large files with streaming AES-256-GCM encryption.
20
+
- Supports backend-managed multipart uploads for frontend chunk upload flows.
Decryption reverses the flow: the KMS provider unwraps the DEK from the header, then AES-GCM verifies the auth tag and decrypts the ciphertext.
68
-
69
-
Every encrypted payload uses the same self-describing format, whether it came from Active Storage, the direct S3 adapter, or the backend chunk upload API.
61
+
Every file gets its own random data encryption key. The file is encrypted with AES-256-GCM, and that data key is wrapped by your configured key provider.
62
+
63
+
The encrypted file is self-contained. It stores:
64
+
65
+
- a small Active Cipher Storage header,
66
+
- the encrypted data key,
67
+
- the ciphertext,
68
+
- authentication tags used to detect tampering.
69
+
70
+
When the file is downloaded, the gem reads the header, asks the key provider to unwrap the data key, verifies the AES-GCM authentication tag, and returns plaintext to your app.
71
+
72
+
The same format is used for Rails Active Storage uploads, direct S3 uploads, streaming downloads, and multipart upload flows.
70
73
71
74
## Installation
72
75
76
+
Add the gem to your Gemfile:
77
+
73
78
```ruby
74
-
# Gemfile
75
79
gem "active_cipher_storage"
80
+
```
76
81
77
-
# For AWS KMS provider:
78
-
gem "aws-sdk-kms"
82
+
If you use AWS KMS or the direct S3 adapter, add the AWS SDK gems you need:
79
83
80
-
# For standalone S3 adapter:
84
+
```ruby
85
+
gem "aws-sdk-kms"
81
86
gem "aws-sdk-s3"
82
87
```
83
88
@@ -87,7 +92,11 @@ bundle install
87
92
88
93
## Rails / Active Storage setup
89
94
90
-
### 1. Configure a KMS provider
95
+
Use this path when you want Rails Active Storage to encrypt attachments automatically.
96
+
97
+
Your model, controller, and view code can keep using normal Active Storage APIs. The only change is the storage service configuration.
Active Storage transparently encrypts on upload and decrypts on download. Existing plaintext objects are still readable: if a blob does not start with the `ACS\x01` magic header, the service returns it unchanged.
166
+
Active Storage now encrypts on upload and decrypts on download.
167
+
168
+
Existing plaintext objects are still readable. If a blob does not start with the `ACS\x01` magic header, the service returns it unchanged.
158
169
159
170
`config.encrypt_uploads` controls new Active Storage writes only. When disabled, new uploads are stored as plaintext and marked with `"encrypted": false` metadata. Reads continue to auto-detect by payload header, so existing encrypted blobs still decrypt correctly and existing plaintext blobs still download unchanged.
160
171
161
172
Direct Active Storage browser uploads are intentionally disabled because they bypass the backend encryption layer.
162
173
163
174
## Standalone S3 usage
164
175
165
-
No Rails required.
176
+
You can also use Active Cipher Storage without Rails.
177
+
178
+
This is useful for background jobs, service objects, scripts, or non-Rails Ruby apps that upload encrypted files directly to S3.
For large files where the frontend sends data in separate HTTP requests, use `EncryptedMultipartUpload`. Each frontend chunk is encrypted by the backend as an authenticated ACS frame and buffered until the S3 multipart minimum part size is met, then flushed as an encrypted S3 multipart part.
213
+
For large files, many apps upload from the browser in chunks.
214
+
215
+
Active Cipher Storage supports that flow, but the browser still does not get encryption keys. The frontend sends plaintext chunks to your Rails app, and your backend encrypts those chunks before uploading encrypted multipart parts to S3.
201
216
202
-
This flow is backend-managed. The frontend never receives encryption keys and never uploads plaintext directly to S3.
217
+
Use `EncryptedMultipartUpload` for this backend-managed upload flow.
@@ -255,25 +270,28 @@ class UploadsController < ApplicationController
255
270
end
256
271
```
257
272
258
-
**Session storage:**
273
+
**Session storage**
274
+
259
275
By default, session state is held in process memory (`MemorySessionStore`). This is intended for one active backend-managed upload lifecycle and is not durable across process restarts or deploys.
260
276
261
277
For multi-process deployments where chunks for the same active upload may land on different workers or hosts, pass a shared store:
262
278
263
279
```ruby
264
-
# Rails.cache backed by Redis — allows cross-worker active upload sessions
280
+
# Rails.cache backed by Redis allows cross-worker active upload sessions.
store:Rails.cache # any object with read/write/delete
269
285
)
270
286
```
271
287
272
-
**Security:** The plaintext DEK is never stored in the session. Only the KMS-wrapped encrypted DEK is persisted; it is decrypted fresh for each chunk and zeroed immediately after use.
288
+
**Security:** The plaintext data key is never stored in the session. Only the KMS-wrapped encrypted data key is persisted; it is decrypted fresh for each chunk and zeroed immediately after use.
273
289
274
290
## Streaming download
275
291
276
-
`stream_decrypted` pipes S3 bytes through the decryptor and yields plaintext chunks on the fly. Memory usage is bounded by one ACS chunk (default 5 MiB) regardless of file size.
292
+
Use `stream_decrypted` when you need to send a large encrypted file to a client without loading the whole file into memory.
293
+
294
+
The adapter reads encrypted bytes from S3, decrypts authenticated chunks as they arrive, and yields plaintext chunks to your block. Memory usage stays bounded by one Active Cipher Storage chunk, which is 5 MiB by default.
277
295
278
296
```ruby
279
297
s3 =ActiveCipherStorage::Adapters::S3Adapter.new(
@@ -302,13 +320,15 @@ File.open("output.bin", "wb") do |f|
302
320
end
303
321
```
304
322
305
-
`stream_decrypted` handles S3 delivering data in any chunk size — the internal `StreamingDecryptor` buffers incoming bytes and emits plaintext only when a complete, authenticated ACS frame is available.
323
+
`stream_decrypted` handles S3 delivering data in any chunk size. The internal decryptor buffers incoming bytes and emits plaintext only when a complete, authenticated frame is available.
306
324
307
325
Use `stream_decrypted` for chunked ACS objects. If the object is non-chunked, call `get_decrypted`; streaming a non-chunked or non-ACS/plaintext object raises `InvalidFormat` with a clear error.
308
326
309
327
## Manual encrypt / decrypt
310
328
311
-
Use `Cipher` (in-memory) or `StreamCipher` (chunked, constant memory):
329
+
If you do not need Rails or S3 integration, you can use the lower-level cipher classes directly.
330
+
331
+
Use `Cipher` for small files and `StreamCipher` for large files:
312
332
313
333
```ruby
314
334
require"active_cipher_storage"
@@ -317,15 +337,15 @@ ActiveCipherStorage.configure do |c|
0 commit comments