@@ -165,7 +165,79 @@ or creating a schema map, see later sections of this tutorial.
165
165
166
166
Explicit Encryption
167
167
-------------------
168
- Documentation for explicit encryption will be provided soon.
168
+ Explicit encryption is a feature that allows users to encrypt and decrypt
169
+ individual pieces of data such as strings, integers, or symbols. Explicit
170
+ encryption is a community feature and does not require an enterprise build
171
+ of the MongoDB server to use. To perform all explicit encryption and decryption
172
+ operations, use an instance of the ClientEncryption class.
173
+
174
+ The following is an example of using explicit encryption with a local encryption
175
+ master key to encrypt a piece of data before inserting it into the database,
176
+ and then decrypting it after reading it from the database.
177
+
178
+ .. code-block:: ruby
179
+
180
+ require 'mongo'
181
+
182
+ # Generate a local encryption master key
183
+ # To reuse this master key, persist it to a file or environment variable
184
+ # on your machine.
185
+ local_master_key = Base64.encode64(SecureRandom.random_bytes(96))
186
+
187
+ kms_providers = {
188
+ local: {
189
+ key: local_master_key
190
+ }
191
+ }
192
+
193
+ # Create an encryption data key and insert it into the key vault collection
194
+ key_vault_client = Mongo::Client.new(['localhost:27017'])
195
+
196
+ client_encryption = Mongo::ClientEncryption.new(
197
+ key_vault_client,
198
+ {
199
+ key_vault_namespace: 'admin.datakeys',
200
+ kms_providers: kms_providers
201
+ }
202
+ )
203
+
204
+ data_key_id = client_encryption.create_data_key('local')
205
+
206
+ # The value to encrypt
207
+ value = 'sensitive data'
208
+
209
+ # Encrypt the value
210
+ encrypted_value = client_encryption.encrypt(
211
+ 'sensitive data',
212
+ {
213
+ key_id: data_key_id,
214
+ algorithm: "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"
215
+ }
216
+ )
217
+
218
+ # Create the client you will use to read and write the data to MongoDB
219
+ client = Mongo::Client.new(['localhost:27017'])
220
+ collection = client.use(:encryption_db)[:encryption_coll]
221
+ collection.drop # Make sure there is no data in the collection
222
+
223
+ # Insert the encrypted value into the collection
224
+ collection.insert_one(encrypted_field: encrypted_value)
225
+
226
+ # Use the client to read the encrypted value from the database, then
227
+ # use the ClientEncryption object to decrypt it
228
+ find_result = collection.find(encrypted_field: encrypted_value).first['encrypted_field']
229
+ # => <BSON::Binary...> (the find result is encrypted)
230
+
231
+ unencrypted_result = client_encryption.decrypt(find_result)
232
+ # => "sensitive data"
233
+
234
+ For more information about creating an encryption master key, creating a data key,
235
+ or creating a schema map, see later sections of this tutorial.
236
+
237
+ .. seealso::
238
+ `Creating A Master Key`_,
239
+ `Creating A Data Key`_,
240
+ `Creating A Schema Map`_,
169
241
170
242
Creating a Master Key
171
243
---------------------
0 commit comments