Skip to content

Commit c41aefe

Browse files
author
Emily Giurleo
authored
add explicit encryption example (#1730)
1 parent ef35731 commit c41aefe

File tree

1 file changed

+73
-1
lines changed

1 file changed

+73
-1
lines changed

source/tutorials/client-side-encryption.txt

Lines changed: 73 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -165,7 +165,79 @@ or creating a schema map, see later sections of this tutorial.
165165

166166
Explicit Encryption
167167
-------------------
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`_,
169241

170242
Creating a Master Key
171243
---------------------

0 commit comments

Comments
 (0)