kms_encrypted 1.0.1 → 1.2.2
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/CHANGELOG.md +30 -9
- data/LICENSE.txt +1 -1
- data/README.md +448 -9
- data/lib/kms_encrypted.rb +5 -0
- data/lib/kms_encrypted/box.rb +1 -1
- data/lib/kms_encrypted/client.rb +1 -3
- data/lib/kms_encrypted/clients/test.rb +2 -0
- data/lib/kms_encrypted/database.rb +3 -2
- data/lib/kms_encrypted/model.rb +67 -10
- data/lib/kms_encrypted/version.rb +1 -1
- metadata +12 -139
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 1f8fd21d9b3a411372d965975296ad6cfe7564754e52beee03834348ad87527f
|
4
|
+
data.tar.gz: b002b56976dd236017c753b6af64af9d8defd5399e0e4dfdfcb8e49faefdd380
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 6bb3def681881896ee1efd604d8c13ef450c92c7ac6a894f1ad02d9c655d7b9dc4cd54e541eb2f5feec457760cefe3f39bafd4270225bfee72602aca7f299589
|
7
|
+
data.tar.gz: d34b859b0237a6e038dfbff7a5e12c27aabf2c2171a20b4d1273626042698e49564e8e64a1a90a7d8df8829a7a74d2af99797d740abc519ca670fd68541525b4
|
data/CHANGELOG.md
CHANGED
@@ -1,10 +1,31 @@
|
|
1
|
-
## 1.
|
1
|
+
## 1.2.2 (2021-05-17)
|
2
|
+
|
3
|
+
- Added `key_id` method
|
4
|
+
|
5
|
+
## 1.2.1 (2020-09-28)
|
6
|
+
|
7
|
+
- Fixed `Version not active` error when switching keys
|
8
|
+
|
9
|
+
## 1.2.0 (2020-08-18)
|
10
|
+
|
11
|
+
- Raise error when trying to rotate key used for encrypted files
|
12
|
+
|
13
|
+
## 1.1.1 (2020-04-16)
|
14
|
+
|
15
|
+
- Fixed `SystemStackError` with `reload` and CarrierWave
|
16
|
+
|
17
|
+
## 1.1.0 (2019-07-09)
|
18
|
+
|
19
|
+
- Added support for Lockbox
|
20
|
+
- Dropped support for Rails 4.2
|
21
|
+
|
22
|
+
## 1.0.1 (2019-01-21)
|
2
23
|
|
3
24
|
- Added support for encryption and decryption outside models
|
4
25
|
- Added support for dynamic keys
|
5
26
|
- Fixed issue with inheritance
|
6
27
|
|
7
|
-
## 1.0.0
|
28
|
+
## 1.0.0 (2018-12-17)
|
8
29
|
|
9
30
|
- Added versioning
|
10
31
|
- Added `context_hash` method
|
@@ -15,38 +36,38 @@ Breaking changes
|
|
15
36
|
- ActiveSupport notifications were changed from `generate_data_key` and `decrypt_data_key` to `encrypt` and `decrypt`
|
16
37
|
- AWS KMS uses the `Encrypt` operation instead of `GenerateDataKey`
|
17
38
|
|
18
|
-
## 0.3.0
|
39
|
+
## 0.3.0 (2018-11-11)
|
19
40
|
|
20
41
|
- Added support for Vault
|
21
42
|
- Removed `KmsEncrypted.kms_client` and `KmsEncrypted.client_options` in favor of `KmsEncrypted.aws_client`
|
22
43
|
- Removed `KmsEncrypted::Google.kms_client` in favor of `KmsEncrypted.google_client`
|
23
44
|
|
24
|
-
## 0.2.0
|
45
|
+
## 0.2.0 (2018-02-23)
|
25
46
|
|
26
47
|
- Added support for Google KMS
|
27
48
|
|
28
|
-
## 0.1.4
|
49
|
+
## 0.1.4 (2017-12-03)
|
29
50
|
|
30
51
|
- Added `kms_keys` method to models
|
31
52
|
- Reset data keys when record is reloaded
|
32
53
|
- Added `kms_client`
|
33
54
|
- Added ActiveSupport notifications
|
34
55
|
|
35
|
-
## 0.1.3
|
56
|
+
## 0.1.3 (2017-12-01)
|
36
57
|
|
37
58
|
- Added test key
|
38
59
|
- Added `client_options`
|
39
60
|
- Allow private or protected `kms_encryption_context` method
|
40
61
|
|
41
|
-
## 0.1.2
|
62
|
+
## 0.1.2 (2017-09-25)
|
42
63
|
|
43
64
|
- Use `KMS_KEY_ID` env variable by default
|
44
65
|
|
45
|
-
## 0.1.1
|
66
|
+
## 0.1.1 (2017-09-23)
|
46
67
|
|
47
68
|
- Added key rotation
|
48
69
|
- Added support for multiple keys per record
|
49
70
|
|
50
|
-
## 0.1.0
|
71
|
+
## 0.1.0 (2017-09-23)
|
51
72
|
|
52
73
|
- First release
|
data/LICENSE.txt
CHANGED
data/README.md
CHANGED
@@ -1,6 +1,6 @@
|
|
1
1
|
# KMS Encrypted
|
2
2
|
|
3
|
-
Simple, secure key management for [attr_encrypted](https://github.com/attr-encrypted/attr_encrypted)
|
3
|
+
Simple, secure key management for [Lockbox](https://github.com/ankane/lockbox) and [attr_encrypted](https://github.com/attr-encrypted/attr_encrypted)
|
4
4
|
|
5
5
|
With KMS Encrypted:
|
6
6
|
|
@@ -14,23 +14,453 @@ Supports [AWS KMS](https://aws.amazon.com/kms/), [Google Cloud KMS](https://clou
|
|
14
14
|
|
15
15
|
Check out [this post](https://ankane.org/sensitive-data-rails) for more info on securing sensitive data with Rails
|
16
16
|
|
17
|
-
[![Build Status](https://
|
17
|
+
[![Build Status](https://github.com/ankane/kms_encrypted/workflows/build/badge.svg?branch=master)](https://github.com/ankane/kms_encrypted/actions)
|
18
18
|
|
19
19
|
## How It Works
|
20
20
|
|
21
|
-
This approach uses a key management service (KMS) to manage encryption keys and attr_encrypted to do the encryption.
|
21
|
+
This approach uses a key management service (KMS) to manage encryption keys and Lockbox / attr_encrypted to do the encryption.
|
22
22
|
|
23
|
-
To encrypt an attribute, we first generate a data key and encrypt it with the KMS. This is known as [envelope encryption](https://cloud.google.com/kms/docs/envelope-encryption). We pass the unencrypted version to
|
23
|
+
To encrypt an attribute, we first generate a data key and encrypt it with the KMS. This is known as [envelope encryption](https://cloud.google.com/kms/docs/envelope-encryption). We pass the unencrypted version to the encryption library and store the encrypted version in the `encrypted_kms_key` column. For each record, we generate a different data key.
|
24
24
|
|
25
|
-
To decrypt an attribute, we first decrypt the data key with the KMS. Once we have the decrypted key, we pass it to
|
25
|
+
To decrypt an attribute, we first decrypt the data key with the KMS. Once we have the decrypted key, we pass it to the encryption library to decrypt the data. We can easily track decryptions since we have a different data key for each record.
|
26
|
+
|
27
|
+
## Installation
|
28
|
+
|
29
|
+
Add this line to your application’s Gemfile:
|
30
|
+
|
31
|
+
```ruby
|
32
|
+
gem 'kms_encrypted'
|
33
|
+
```
|
34
|
+
|
35
|
+
And follow the instructions for your key management service:
|
36
|
+
|
37
|
+
- [AWS KMS](#aws-kms)
|
38
|
+
- [Google Cloud KMS](#google-cloud-kms)
|
39
|
+
- [Vault](#vault)
|
40
|
+
|
41
|
+
### AWS KMS
|
42
|
+
|
43
|
+
Add this line to your application’s Gemfile:
|
44
|
+
|
45
|
+
```ruby
|
46
|
+
gem 'aws-sdk-kms'
|
47
|
+
```
|
48
|
+
|
49
|
+
Create an [Amazon Web Services](https://aws.amazon.com/) account if you don’t have one. KMS works great whether or not you run your infrastructure on AWS.
|
50
|
+
|
51
|
+
Create a [KMS master key](https://console.aws.amazon.com/iam/home#/encryptionKeys) and set it in your environment along with your AWS credentials ([dotenv](https://github.com/bkeepers/dotenv) is great for this)
|
52
|
+
|
53
|
+
```sh
|
54
|
+
KMS_KEY_ID=arn:aws:kms:...
|
55
|
+
AWS_ACCESS_KEY_ID=...
|
56
|
+
AWS_SECRET_ACCESS_KEY=...
|
57
|
+
```
|
58
|
+
|
59
|
+
You can also use the alias
|
60
|
+
|
61
|
+
```sh
|
62
|
+
KMS_KEY_ID=alias/my-alias
|
63
|
+
```
|
64
|
+
|
65
|
+
### Google Cloud KMS
|
66
|
+
|
67
|
+
Add this line to your application’s Gemfile:
|
68
|
+
|
69
|
+
```ruby
|
70
|
+
gem 'google-apis-cloudkms_v1'
|
71
|
+
```
|
72
|
+
|
73
|
+
Create a [Google Cloud Platform](https://cloud.google.com/) account if you don’t have one. KMS works great whether or not you run your infrastructure on GCP.
|
74
|
+
|
75
|
+
Create a [KMS key ring and key](https://console.cloud.google.com/iam-admin/kms) and set it in your environment along with your GCP credentials ([dotenv](https://github.com/bkeepers/dotenv) is great for this)
|
76
|
+
|
77
|
+
```sh
|
78
|
+
KMS_KEY_ID=projects/.../locations/.../keyRings/.../cryptoKeys/...
|
79
|
+
```
|
80
|
+
|
81
|
+
The Google API client logs requests by default. Be sure to turn off the logger in production or it will leak the plaintext.
|
82
|
+
|
83
|
+
```ruby
|
84
|
+
Google::Apis.logger = Logger.new(nil)
|
85
|
+
```
|
86
|
+
|
87
|
+
### Vault
|
88
|
+
|
89
|
+
Add this line to your application’s Gemfile:
|
90
|
+
|
91
|
+
```ruby
|
92
|
+
gem 'vault'
|
93
|
+
```
|
94
|
+
|
95
|
+
Enable the [transit](https://www.vaultproject.io/docs/secrets/transit/index.html) secrets engine
|
96
|
+
|
97
|
+
```sh
|
98
|
+
vault secrets enable transit
|
99
|
+
```
|
100
|
+
|
101
|
+
And create a key
|
102
|
+
|
103
|
+
```sh
|
104
|
+
vault write -f transit/keys/my-key derived=true
|
105
|
+
```
|
106
|
+
|
107
|
+
Set it in your environment along with your Vault credentials ([dotenv](https://github.com/bkeepers/dotenv) is great for this)
|
108
|
+
|
109
|
+
```sh
|
110
|
+
KMS_KEY_ID=vault/my-key
|
111
|
+
VAULT_ADDR=http://127.0.0.1:8200
|
112
|
+
VAULT_TOKEN=secret
|
113
|
+
```
|
26
114
|
|
27
115
|
## Getting Started
|
28
116
|
|
29
|
-
|
117
|
+
Create a migration to add a column for the encrypted KMS data keys
|
118
|
+
|
119
|
+
```ruby
|
120
|
+
add_column :users, :encrypted_kms_key, :text
|
121
|
+
```
|
122
|
+
|
123
|
+
And update your model
|
124
|
+
|
125
|
+
```ruby
|
126
|
+
class User < ApplicationRecord
|
127
|
+
has_kms_key
|
128
|
+
|
129
|
+
# Lockbox fields
|
130
|
+
encrypts :email, key: :kms_key
|
131
|
+
|
132
|
+
# Lockbox files
|
133
|
+
encrypts_attached :license, key: :kms_key
|
134
|
+
|
135
|
+
# attr_encrypted fields
|
136
|
+
attr_encrypted :email, key: :kms_key
|
137
|
+
end
|
138
|
+
```
|
139
|
+
|
140
|
+
For each encrypted attribute, use the `kms_key` method for its key.
|
141
|
+
|
142
|
+
## Auditing & Alerting
|
143
|
+
|
144
|
+
### Context
|
145
|
+
|
146
|
+
Encryption context is used in auditing to identify the data being decrypted. This is the model name and id by default. You can customize this with:
|
147
|
+
|
148
|
+
```ruby
|
149
|
+
class User < ApplicationRecord
|
150
|
+
def kms_encryption_context
|
151
|
+
{
|
152
|
+
model_name: model_name.to_s,
|
153
|
+
model_id: id
|
154
|
+
}
|
155
|
+
end
|
156
|
+
end
|
157
|
+
```
|
158
|
+
|
159
|
+
The context is used as part of the encryption and decryption process, so it must be a value that doesn’t change. Otherwise, you won’t be able to decrypt. You can [rotate the context](#switching-context) without downtime if needed.
|
160
|
+
|
161
|
+
### Order of Events
|
162
|
+
|
163
|
+
Since the default context includes the id, the data key cannot be encrypted until the record has an id. For new records, the default flow is:
|
164
|
+
|
165
|
+
1. Start a database transaction
|
166
|
+
2. Insert the record, getting back the id
|
167
|
+
3. Call KMS to encrypt the data key, passing the id as part of the context
|
168
|
+
4. Update the `encrypted_kms_key` column
|
169
|
+
5. Commit the database transaction
|
170
|
+
|
171
|
+
With Postgres, you can avoid a network call inside a transaction with:
|
172
|
+
|
173
|
+
```ruby
|
174
|
+
class User < ApplicationRecord
|
175
|
+
has_kms_key eager_encrypt: :fetch_id
|
176
|
+
end
|
177
|
+
```
|
178
|
+
|
179
|
+
This changes the flow to:
|
180
|
+
|
181
|
+
1. Prefetch the id with the Postgres `nextval` function
|
182
|
+
2. Call KMS to encrypt the data key, passing the id as part of the context
|
183
|
+
3. Insert the record with the id and encrypted data key
|
184
|
+
|
185
|
+
If you don’t need the id from the database for context, you can use:
|
186
|
+
|
187
|
+
```ruby
|
188
|
+
class User < ApplicationRecord
|
189
|
+
has_kms_key eager_encrypt: true
|
190
|
+
end
|
191
|
+
```
|
192
|
+
|
193
|
+
### AWS KMS
|
194
|
+
|
195
|
+
[AWS CloudTrail](https://aws.amazon.com/cloudtrail/) logs all decryption calls. You can view them in the [CloudTrail console](https://console.aws.amazon.com/cloudtrail/home#/events?EventName=Decrypt). Note that it can take 20 minutes for events to show up. You can also use the AWS CLI.
|
196
|
+
|
197
|
+
```sh
|
198
|
+
aws cloudtrail lookup-events --lookup-attributes AttributeKey=EventName,AttributeValue=Decrypt
|
199
|
+
```
|
200
|
+
|
201
|
+
If you haven’t already, enable CloudTrail storage to S3 to ensure events are accessible after 90 days. Later, you can use Amazon Athena and this [table structure](https://www.1strategy.com/blog/2017/07/25/auditing-aws-activity-with-cloudtrail-and-athena/) to query them.
|
202
|
+
|
203
|
+
Read more about [encryption context here](https://docs.aws.amazon.com/kms/latest/developerguide/encryption-context.html).
|
204
|
+
|
205
|
+
#### Alerting
|
206
|
+
|
207
|
+
Set up alerts for suspicious behavior. To get near real-time alerts (20-30 second delay), use CloudWatch Events.
|
208
|
+
|
209
|
+
First, create a new SNS topic with a name like "decryptions". We’ll use this shortly.
|
210
|
+
|
211
|
+
Next, open [CloudWatch Events](https://console.aws.amazon.com/cloudwatch/home#rules:) and create a rule to match “Events by Service”. Choose “Key Management Service (KMS)” as the service name and “AWS API Call via CloudTrail” as the event type. For operations, select “Specific Operations” and enter “Decrypt”.
|
212
|
+
|
213
|
+
Select the SNS topic created earlier as the target and save the rule.
|
214
|
+
|
215
|
+
To set up an alarm, go to [this page](https://console.aws.amazon.com/cloudwatch/home?#metricsV2:graph=%7E();namespace=AWS/Events;dimensions=RuleName) in CloudWatch Metrics. Find the rule and check “Invocations”. On the “Graphed Metrics” tab, change the statistic to “Sum” and the period to “1 minute”. Finally, click the bell icon to create an alarm for high number of decryptions.
|
216
|
+
|
217
|
+
While the alarm we created isn’t super sophisticated, this setup provides a great foundation for alerting as your organization grows.
|
218
|
+
|
219
|
+
You can use the SNS topic or another target to send events to a log provider or [SIEM](https://en.wikipedia.org/wiki/Security_information_and_event_management), where can you do more advanced anomaly detection.
|
220
|
+
|
221
|
+
You should also use other tools to detect breaches, like an [IDS](https://www.alienvault.com/blogs/security-essentials/open-source-intrusion-detection-tools-a-quick-overview). You can use [Amazon GuardDuty](https://aws.amazon.com/guardduty/) if you run infrastructure on AWS.
|
222
|
+
|
223
|
+
### Google Cloud KMS
|
224
|
+
|
225
|
+
Follow the [instructions here](https://cloud.google.com/kms/docs/logging) to set up data access logging. There is not currently a way to see what data is being decrypted, since the additional authenticated data is not logged. For this reason, we recommend another KMS provider.
|
226
|
+
|
227
|
+
### Vault
|
228
|
+
|
229
|
+
Follow the [instructions here](https://www.vaultproject.io/docs/audit/) to set up data access logging.
|
230
|
+
|
231
|
+
**Note:** Vault will only verify this value if `derived` was set to true when creating the key. If this is not done, the context cannot be trusted.
|
232
|
+
|
233
|
+
Context will show up hashed in the audit logs. To get the hash for a record, use:
|
30
234
|
|
31
|
-
|
32
|
-
|
33
|
-
|
235
|
+
```ruby
|
236
|
+
KmsEncrypted.context_hash(record.kms_encryption_context, path: "file")
|
237
|
+
```
|
238
|
+
|
239
|
+
The `path` option should point to your audit device. Common paths are `file`, `syslog`, and `socket`.
|
240
|
+
|
241
|
+
## Separate Permissions
|
242
|
+
|
243
|
+
A great feature of KMS is the ability to grant encryption and decryption permission separately.
|
244
|
+
|
245
|
+
Be extremely selective of servers you allow to decrypt.
|
246
|
+
|
247
|
+
For servers that can only encrypt, clear out the existing data and data key before assigning new values (otherwise, you’ll get a decryption error).
|
248
|
+
|
249
|
+
```ruby
|
250
|
+
# Lockbox
|
251
|
+
user.email_ciphertext = nil
|
252
|
+
user.encrypted_kms_key = nil
|
253
|
+
|
254
|
+
# attr_encrypted
|
255
|
+
user.encrypted_email = nil
|
256
|
+
user.encrypted_email_iv = nil
|
257
|
+
user.encrypted_kms_key = nil
|
258
|
+
```
|
259
|
+
|
260
|
+
### AWS KMS
|
261
|
+
|
262
|
+
To encrypt the data, use an IAM policy with:
|
263
|
+
|
264
|
+
```json
|
265
|
+
{
|
266
|
+
"Version": "2012-10-17",
|
267
|
+
"Statement": [
|
268
|
+
{
|
269
|
+
"Sid": "EncryptData",
|
270
|
+
"Effect": "Allow",
|
271
|
+
"Action": "kms:Encrypt",
|
272
|
+
"Resource": "arn:aws:kms:..."
|
273
|
+
}
|
274
|
+
]
|
275
|
+
}
|
276
|
+
```
|
277
|
+
|
278
|
+
To decrypt the data, use an IAM policy with:
|
279
|
+
|
280
|
+
```json
|
281
|
+
{
|
282
|
+
"Version": "2012-10-17",
|
283
|
+
"Statement": [
|
284
|
+
{
|
285
|
+
"Sid": "DecryptData",
|
286
|
+
"Effect": "Allow",
|
287
|
+
"Action": "kms:Decrypt",
|
288
|
+
"Resource": "arn:aws:kms:..."
|
289
|
+
}
|
290
|
+
]
|
291
|
+
}
|
292
|
+
```
|
293
|
+
|
294
|
+
### Google Cloud KMS
|
295
|
+
|
296
|
+
todo: document
|
297
|
+
|
298
|
+
### Vault
|
299
|
+
|
300
|
+
To encrypt the data, use a policy with:
|
301
|
+
|
302
|
+
```hcl
|
303
|
+
path "transit/encrypt/my-key"
|
304
|
+
{
|
305
|
+
capabilities = ["create", "update"]
|
306
|
+
}
|
307
|
+
```
|
308
|
+
|
309
|
+
To decrypt the data, use a policy with:
|
310
|
+
|
311
|
+
```hcl
|
312
|
+
path "transit/decrypt/my-key"
|
313
|
+
{
|
314
|
+
capabilities = ["create", "update"]
|
315
|
+
}
|
316
|
+
```
|
317
|
+
|
318
|
+
Apply a policy with:
|
319
|
+
|
320
|
+
```sh
|
321
|
+
vault policy write encrypt encrypt.hcl
|
322
|
+
```
|
323
|
+
|
324
|
+
And create a token with specific policies with:
|
325
|
+
|
326
|
+
```sh
|
327
|
+
vault token create -policy=encrypt -policy=decrypt -no-default-policy
|
328
|
+
```
|
329
|
+
|
330
|
+
## Testing
|
331
|
+
|
332
|
+
For testing, you can prevent network calls to KMS by setting:
|
333
|
+
|
334
|
+
```sh
|
335
|
+
KMS_KEY_ID=insecure-test-key
|
336
|
+
```
|
337
|
+
|
338
|
+
In a Rails application, you can also create `config/initializers/kms_encrypted.rb` with:
|
339
|
+
|
340
|
+
```ruby
|
341
|
+
KmsEncrypted.key_id = Rails.env.test? ? "insecure-test-key" : ENV["KMS_KEY_ID"]
|
342
|
+
```
|
343
|
+
|
344
|
+
## Key Rotation
|
345
|
+
|
346
|
+
Key management services allow you to rotate the master key without any code changes.
|
347
|
+
|
348
|
+
AWS KMS supports [automatic key rotation](https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html).
|
349
|
+
|
350
|
+
For Google Cloud, use the Google Cloud Console or API.
|
351
|
+
|
352
|
+
For Vault, use:
|
353
|
+
|
354
|
+
```sh
|
355
|
+
vault write -f transit/keys/my-key/rotate
|
356
|
+
```
|
357
|
+
|
358
|
+
New data will be encrypted with the new master key version. To encrypt existing data with new master key version, run:
|
359
|
+
|
360
|
+
```ruby
|
361
|
+
User.find_each do |user|
|
362
|
+
user.rotate_kms_key!
|
363
|
+
end
|
364
|
+
```
|
365
|
+
|
366
|
+
**Note:** This method does not rotate encrypted files, so avoid calling `rotate_kms_key!` on models with file uploads for now.
|
367
|
+
|
368
|
+
### Switching Keys
|
369
|
+
|
370
|
+
You can change keys within your current KMS or move to a different KMS without downtime. Update your model:
|
371
|
+
|
372
|
+
```ruby
|
373
|
+
class User < ApplicationRecord
|
374
|
+
has_kms_key version: 2, key_id: ENV["KMS_KEY_ID_V2"],
|
375
|
+
previous_versions: {
|
376
|
+
1 => {key_id: ENV["KMS_KEY_ID"]}
|
377
|
+
}
|
378
|
+
end
|
379
|
+
```
|
380
|
+
|
381
|
+
New data will be encrypted with the new key. To update existing data, use:
|
382
|
+
|
383
|
+
```ruby
|
384
|
+
User.where("encrypted_kms_key NOT LIKE 'v2:%'").find_each do |user|
|
385
|
+
user.rotate_kms_key!
|
386
|
+
end
|
387
|
+
```
|
388
|
+
|
389
|
+
Once all data is updated, you can remove the `previous_versions` option.
|
390
|
+
|
391
|
+
### Switching Context
|
392
|
+
|
393
|
+
You can change your encryption context without downtime. Update your model:
|
394
|
+
|
395
|
+
```ruby
|
396
|
+
class User < ApplicationRecord
|
397
|
+
has_kms_key version: 2,
|
398
|
+
previous_versions: {
|
399
|
+
1 => {key_id: ENV["KMS_KEY_ID"]}
|
400
|
+
}
|
401
|
+
|
402
|
+
def kms_encryption_context(version:)
|
403
|
+
if version == 1
|
404
|
+
# previous context method
|
405
|
+
else
|
406
|
+
# new context method
|
407
|
+
end
|
408
|
+
end
|
409
|
+
end
|
410
|
+
```
|
411
|
+
|
412
|
+
New data will be encrypted with the new context. To update existing data, use:
|
413
|
+
|
414
|
+
```ruby
|
415
|
+
User.where("encrypted_kms_key NOT LIKE 'v2:%'").find_each do |user|
|
416
|
+
user.rotate_kms_key!
|
417
|
+
end
|
418
|
+
```
|
419
|
+
|
420
|
+
Once all data is updated, you can remove the `previous_versions` option.
|
421
|
+
|
422
|
+
## Multiple Keys Per Record
|
423
|
+
|
424
|
+
You may want to protect different columns with different data keys (or even master keys).
|
425
|
+
|
426
|
+
To do this, add another column
|
427
|
+
|
428
|
+
```ruby
|
429
|
+
add_column :users, :encrypted_kms_key_phone, :text
|
430
|
+
```
|
431
|
+
|
432
|
+
And update your model
|
433
|
+
|
434
|
+
```ruby
|
435
|
+
class User < ApplicationRecord
|
436
|
+
has_kms_key
|
437
|
+
has_kms_key name: :phone, key_id: "..."
|
438
|
+
|
439
|
+
# Lockbox
|
440
|
+
encrypts :email, key: :kms_key
|
441
|
+
encrypts :phone, key: :kms_key_phone
|
442
|
+
|
443
|
+
# attr_encrypted
|
444
|
+
attr_encrypted :email, key: :kms_key
|
445
|
+
attr_encrypted :phone, key: :kms_key_phone
|
446
|
+
end
|
447
|
+
```
|
448
|
+
|
449
|
+
To rotate keys, use:
|
450
|
+
|
451
|
+
```ruby
|
452
|
+
user.rotate_kms_key_phone!
|
453
|
+
```
|
454
|
+
|
455
|
+
For custom context, use:
|
456
|
+
|
457
|
+
```ruby
|
458
|
+
class User < ApplicationRecord
|
459
|
+
def kms_encryption_context_phone
|
460
|
+
# some hash
|
461
|
+
end
|
462
|
+
end
|
463
|
+
```
|
34
464
|
|
35
465
|
## Outside Models
|
36
466
|
|
@@ -98,3 +528,12 @@ Everyone is encouraged to help improve this project. Here are a few ways you can
|
|
98
528
|
- Fix bugs and [submit pull requests](https://github.com/ankane/kms_encrypted/pulls)
|
99
529
|
- Write, clarify, or fix documentation
|
100
530
|
- Suggest or add new features
|
531
|
+
|
532
|
+
To get started with development and testing:
|
533
|
+
|
534
|
+
```sh
|
535
|
+
git clone https://github.com/ankane/kms_encrypted.git
|
536
|
+
cd kms_encrypted
|
537
|
+
bundle install
|
538
|
+
bundle exec rake test
|
539
|
+
```
|
data/lib/kms_encrypted.rb
CHANGED
@@ -27,6 +27,7 @@ module KmsEncrypted
|
|
27
27
|
attr_writer :aws_client
|
28
28
|
attr_writer :google_client
|
29
29
|
attr_writer :vault_client
|
30
|
+
attr_writer :key_id
|
30
31
|
|
31
32
|
def aws_client
|
32
33
|
@aws_client ||= Aws::KMS::Client.new(
|
@@ -54,6 +55,10 @@ module KmsEncrypted
|
|
54
55
|
@vault_client ||= ::Vault::Client.new
|
55
56
|
end
|
56
57
|
|
58
|
+
def key_id
|
59
|
+
@key_id ||= ENV["KMS_KEY_ID"]
|
60
|
+
end
|
61
|
+
|
57
62
|
# hash is independent of key, but specific to audit device
|
58
63
|
def context_hash(context, path:)
|
59
64
|
context = Base64.encode64(context.to_json)
|
data/lib/kms_encrypted/box.rb
CHANGED
@@ -3,7 +3,7 @@ module KmsEncrypted
|
|
3
3
|
attr_reader :key_id, :version, :previous_versions
|
4
4
|
|
5
5
|
def initialize(key_id: nil, version: nil, previous_versions: nil)
|
6
|
-
@key_id = key_id ||
|
6
|
+
@key_id = key_id || KmsEncrypted.key_id
|
7
7
|
@version = version || 1
|
8
8
|
@previous_versions = previous_versions || {}
|
9
9
|
end
|
data/lib/kms_encrypted/client.rb
CHANGED
@@ -1,11 +1,9 @@
|
|
1
1
|
module KmsEncrypted
|
2
2
|
class Client
|
3
|
-
delegate :encrypt, :decrypt, to: :client
|
4
|
-
|
5
3
|
attr_reader :key_id, :data_key
|
6
4
|
|
7
5
|
def initialize(key_id: nil, legacy_context: false, data_key: false)
|
8
|
-
@key_id = key_id ||
|
6
|
+
@key_id = key_id || KmsEncrypted.key_id
|
9
7
|
@legacy_context = legacy_context
|
10
8
|
@data_key = data_key
|
11
9
|
end
|
@@ -12,6 +12,8 @@ module KmsEncrypted
|
|
12
12
|
def decrypt(ciphertext, context: nil)
|
13
13
|
prefix, plaintext, stored_context = ciphertext.split(":")
|
14
14
|
|
15
|
+
decryption_failed! if prefix != PREFIX
|
16
|
+
|
15
17
|
context = generate_context(context) if context
|
16
18
|
decryption_failed! if context != stored_context
|
17
19
|
|
@@ -43,11 +43,12 @@ module KmsEncrypted
|
|
43
43
|
def decrypt(ciphertext)
|
44
44
|
# determine version for context
|
45
45
|
m = /\Av(\d+):/.match(ciphertext)
|
46
|
-
|
47
|
-
context = (options[:upgrade_context] && !m) ? {} : context(
|
46
|
+
ciphertext_version = m ? m[1].to_i : 1
|
47
|
+
context = (options[:upgrade_context] && !m) ? {} : context(ciphertext_version)
|
48
48
|
|
49
49
|
KmsEncrypted::Box.new(
|
50
50
|
key_id: key_id,
|
51
|
+
version: version,
|
51
52
|
previous_versions: previous_versions
|
52
53
|
).decrypt(ciphertext, context: context)
|
53
54
|
end
|
data/lib/kms_encrypted/model.rb
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
module KmsEncrypted
|
2
2
|
module Model
|
3
3
|
def has_kms_key(name: nil, key_id: nil, eager_encrypt: false, version: 1, previous_versions: nil, upgrade_context: false)
|
4
|
-
key_id ||=
|
4
|
+
key_id ||= KmsEncrypted.key_id
|
5
5
|
|
6
6
|
key_method = name ? "kms_key_#{name}" : "kms_key"
|
7
7
|
key_column = "encrypted_#{key_method}"
|
@@ -55,16 +55,17 @@ module KmsEncrypted
|
|
55
55
|
end
|
56
56
|
end
|
57
57
|
|
58
|
-
# same pattern as attr_encrypted reload
|
59
58
|
if method_defined?(:reload)
|
60
|
-
|
61
|
-
|
62
|
-
|
63
|
-
|
64
|
-
|
59
|
+
m = Module.new do
|
60
|
+
define_method(:reload) do |*args, &block|
|
61
|
+
result = super(*args, &block)
|
62
|
+
self.class.kms_keys.keys.each do |key_method|
|
63
|
+
instance_variable_set("@#{key_method}", nil)
|
64
|
+
end
|
65
|
+
result
|
65
66
|
end
|
66
|
-
result
|
67
67
|
end
|
68
|
+
prepend m
|
68
69
|
end
|
69
70
|
end
|
70
71
|
|
@@ -106,11 +107,67 @@ module KmsEncrypted
|
|
106
107
|
}
|
107
108
|
end
|
108
109
|
|
110
|
+
# automatically detects attributes and files where the encryption key is:
|
111
|
+
# 1. a symbol that matches kms key method exactly
|
112
|
+
# does not detect attributes and files where the encryption key is:
|
113
|
+
# 1. callable (warns)
|
114
|
+
# 2. a symbol that internally calls kms key method
|
115
|
+
# it could try to get the exact key and compare
|
116
|
+
# (there's a very small chance this could have false positives)
|
117
|
+
# but bias towards simplicity for now
|
118
|
+
# TODO possibly raise error for callable keys in 2.0
|
119
|
+
# with option to override/specify attributes
|
109
120
|
define_method("rotate_#{key_method}!") do
|
110
121
|
# decrypt
|
111
122
|
plaintext_attributes = {}
|
112
|
-
|
113
|
-
|
123
|
+
|
124
|
+
# attr_encrypted
|
125
|
+
if self.class.respond_to?(:encrypted_attributes)
|
126
|
+
self.class.encrypted_attributes.each do |key, v|
|
127
|
+
if v[:key] == key_method.to_sym
|
128
|
+
plaintext_attributes[key] = send(key)
|
129
|
+
elsif v[:key].respond_to?(:call)
|
130
|
+
warn "[kms_encrypted] Can't detect if encrypted attribute uses this key"
|
131
|
+
end
|
132
|
+
end
|
133
|
+
end
|
134
|
+
|
135
|
+
# lockbox attributes
|
136
|
+
# only checks key, not previous versions
|
137
|
+
if self.class.respond_to?(:lockbox_attributes)
|
138
|
+
self.class.lockbox_attributes.each do |key, v|
|
139
|
+
if v[:key] == key_method.to_sym
|
140
|
+
plaintext_attributes[key] = send(key)
|
141
|
+
elsif v[:key].respond_to?(:call)
|
142
|
+
warn "[kms_encrypted] Can't detect if encrypted attribute uses this key"
|
143
|
+
end
|
144
|
+
end
|
145
|
+
end
|
146
|
+
|
147
|
+
# lockbox attachments
|
148
|
+
# only checks key, not previous versions
|
149
|
+
if self.class.respond_to?(:lockbox_attachments)
|
150
|
+
self.class.lockbox_attachments.each do |key, v|
|
151
|
+
if v[:key] == key_method.to_sym
|
152
|
+
# can likely add support at some point, but may be complicated
|
153
|
+
# ideally use rotate_encryption! from Lockbox
|
154
|
+
# but needs access to both old and new keys
|
155
|
+
# also need to update database atomically
|
156
|
+
raise KmsEncrypted::Error, "Can't rotate key used for encrypted files"
|
157
|
+
elsif v[:key].respond_to?(:call)
|
158
|
+
warn "[kms_encrypted] Can't detect if encrypted attachment uses this key"
|
159
|
+
end
|
160
|
+
end
|
161
|
+
end
|
162
|
+
|
163
|
+
# CarrierWave uploaders
|
164
|
+
if self.class.respond_to?(:uploaders)
|
165
|
+
self.class.uploaders.each do |_, uploader|
|
166
|
+
# for simplicity, only checks if key is callable
|
167
|
+
if uploader.respond_to?(:lockbox_options) && uploader.lockbox_options[:key].respond_to?(:call)
|
168
|
+
warn "[kms_encrypted] Can't detect if encrypted uploader uses this key"
|
169
|
+
end
|
170
|
+
end
|
114
171
|
end
|
115
172
|
|
116
173
|
# reset key
|
metadata
CHANGED
@@ -1,14 +1,14 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: kms_encrypted
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 1.
|
4
|
+
version: 1.2.2
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- Andrew Kane
|
8
|
-
autorequire:
|
8
|
+
autorequire:
|
9
9
|
bindir: bin
|
10
10
|
cert_chain: []
|
11
|
-
date:
|
11
|
+
date: 2021-05-17 00:00:00.000000000 Z
|
12
12
|
dependencies:
|
13
13
|
- !ruby/object:Gem::Dependency
|
14
14
|
name: activesupport
|
@@ -16,142 +16,16 @@ dependencies:
|
|
16
16
|
requirements:
|
17
17
|
- - ">="
|
18
18
|
- !ruby/object:Gem::Version
|
19
|
-
version: '
|
19
|
+
version: '5'
|
20
20
|
type: :runtime
|
21
21
|
prerelease: false
|
22
22
|
version_requirements: !ruby/object:Gem::Requirement
|
23
23
|
requirements:
|
24
24
|
- - ">="
|
25
25
|
- !ruby/object:Gem::Version
|
26
|
-
version: '
|
27
|
-
|
28
|
-
|
29
|
-
requirement: !ruby/object:Gem::Requirement
|
30
|
-
requirements:
|
31
|
-
- - ">="
|
32
|
-
- !ruby/object:Gem::Version
|
33
|
-
version: '0'
|
34
|
-
type: :development
|
35
|
-
prerelease: false
|
36
|
-
version_requirements: !ruby/object:Gem::Requirement
|
37
|
-
requirements:
|
38
|
-
- - ">="
|
39
|
-
- !ruby/object:Gem::Version
|
40
|
-
version: '0'
|
41
|
-
- !ruby/object:Gem::Dependency
|
42
|
-
name: rake
|
43
|
-
requirement: !ruby/object:Gem::Requirement
|
44
|
-
requirements:
|
45
|
-
- - ">="
|
46
|
-
- !ruby/object:Gem::Version
|
47
|
-
version: '0'
|
48
|
-
type: :development
|
49
|
-
prerelease: false
|
50
|
-
version_requirements: !ruby/object:Gem::Requirement
|
51
|
-
requirements:
|
52
|
-
- - ">="
|
53
|
-
- !ruby/object:Gem::Version
|
54
|
-
version: '0'
|
55
|
-
- !ruby/object:Gem::Dependency
|
56
|
-
name: minitest
|
57
|
-
requirement: !ruby/object:Gem::Requirement
|
58
|
-
requirements:
|
59
|
-
- - ">="
|
60
|
-
- !ruby/object:Gem::Version
|
61
|
-
version: '0'
|
62
|
-
type: :development
|
63
|
-
prerelease: false
|
64
|
-
version_requirements: !ruby/object:Gem::Requirement
|
65
|
-
requirements:
|
66
|
-
- - ">="
|
67
|
-
- !ruby/object:Gem::Version
|
68
|
-
version: '0'
|
69
|
-
- !ruby/object:Gem::Dependency
|
70
|
-
name: sqlite3
|
71
|
-
requirement: !ruby/object:Gem::Requirement
|
72
|
-
requirements:
|
73
|
-
- - ">="
|
74
|
-
- !ruby/object:Gem::Version
|
75
|
-
version: '0'
|
76
|
-
type: :development
|
77
|
-
prerelease: false
|
78
|
-
version_requirements: !ruby/object:Gem::Requirement
|
79
|
-
requirements:
|
80
|
-
- - ">="
|
81
|
-
- !ruby/object:Gem::Version
|
82
|
-
version: '0'
|
83
|
-
- !ruby/object:Gem::Dependency
|
84
|
-
name: activerecord
|
85
|
-
requirement: !ruby/object:Gem::Requirement
|
86
|
-
requirements:
|
87
|
-
- - ">="
|
88
|
-
- !ruby/object:Gem::Version
|
89
|
-
version: '0'
|
90
|
-
type: :development
|
91
|
-
prerelease: false
|
92
|
-
version_requirements: !ruby/object:Gem::Requirement
|
93
|
-
requirements:
|
94
|
-
- - ">="
|
95
|
-
- !ruby/object:Gem::Version
|
96
|
-
version: '0'
|
97
|
-
- !ruby/object:Gem::Dependency
|
98
|
-
name: attr_encrypted
|
99
|
-
requirement: !ruby/object:Gem::Requirement
|
100
|
-
requirements:
|
101
|
-
- - ">="
|
102
|
-
- !ruby/object:Gem::Version
|
103
|
-
version: '0'
|
104
|
-
type: :development
|
105
|
-
prerelease: false
|
106
|
-
version_requirements: !ruby/object:Gem::Requirement
|
107
|
-
requirements:
|
108
|
-
- - ">="
|
109
|
-
- !ruby/object:Gem::Version
|
110
|
-
version: '0'
|
111
|
-
- !ruby/object:Gem::Dependency
|
112
|
-
name: aws-sdk-kms
|
113
|
-
requirement: !ruby/object:Gem::Requirement
|
114
|
-
requirements:
|
115
|
-
- - ">="
|
116
|
-
- !ruby/object:Gem::Version
|
117
|
-
version: '0'
|
118
|
-
type: :development
|
119
|
-
prerelease: false
|
120
|
-
version_requirements: !ruby/object:Gem::Requirement
|
121
|
-
requirements:
|
122
|
-
- - ">="
|
123
|
-
- !ruby/object:Gem::Version
|
124
|
-
version: '0'
|
125
|
-
- !ruby/object:Gem::Dependency
|
126
|
-
name: google-api-client
|
127
|
-
requirement: !ruby/object:Gem::Requirement
|
128
|
-
requirements:
|
129
|
-
- - ">="
|
130
|
-
- !ruby/object:Gem::Version
|
131
|
-
version: '0'
|
132
|
-
type: :development
|
133
|
-
prerelease: false
|
134
|
-
version_requirements: !ruby/object:Gem::Requirement
|
135
|
-
requirements:
|
136
|
-
- - ">="
|
137
|
-
- !ruby/object:Gem::Version
|
138
|
-
version: '0'
|
139
|
-
- !ruby/object:Gem::Dependency
|
140
|
-
name: vault
|
141
|
-
requirement: !ruby/object:Gem::Requirement
|
142
|
-
requirements:
|
143
|
-
- - ">="
|
144
|
-
- !ruby/object:Gem::Version
|
145
|
-
version: '0'
|
146
|
-
type: :development
|
147
|
-
prerelease: false
|
148
|
-
version_requirements: !ruby/object:Gem::Requirement
|
149
|
-
requirements:
|
150
|
-
- - ">="
|
151
|
-
- !ruby/object:Gem::Version
|
152
|
-
version: '0'
|
153
|
-
description:
|
154
|
-
email: andrew@chartkick.com
|
26
|
+
version: '5'
|
27
|
+
description:
|
28
|
+
email: andrew@ankane.org
|
155
29
|
executables: []
|
156
30
|
extensions: []
|
157
31
|
extra_rdoc_files: []
|
@@ -175,7 +49,7 @@ homepage: https://github.com/ankane/kms_encrypted
|
|
175
49
|
licenses:
|
176
50
|
- MIT
|
177
51
|
metadata: {}
|
178
|
-
post_install_message:
|
52
|
+
post_install_message:
|
179
53
|
rdoc_options: []
|
180
54
|
require_paths:
|
181
55
|
- lib
|
@@ -183,16 +57,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
|
|
183
57
|
requirements:
|
184
58
|
- - ">="
|
185
59
|
- !ruby/object:Gem::Version
|
186
|
-
version: '2.
|
60
|
+
version: '2.4'
|
187
61
|
required_rubygems_version: !ruby/object:Gem::Requirement
|
188
62
|
requirements:
|
189
63
|
- - ">="
|
190
64
|
- !ruby/object:Gem::Version
|
191
65
|
version: '0'
|
192
66
|
requirements: []
|
193
|
-
|
194
|
-
|
195
|
-
signing_key:
|
67
|
+
rubygems_version: 3.2.3
|
68
|
+
signing_key:
|
196
69
|
specification_version: 4
|
197
|
-
summary: Simple, secure key management for attr_encrypted
|
70
|
+
summary: Simple, secure key management for Lockbox and attr_encrypted
|
198
71
|
test_files: []
|