Skip to content

Commit 7e82e8d

Browse files
DOCSP-23491 - Explain DEK on Manual Encryption Page (#1395)
* adding dek note * feedback * fixed link * fixed link again * fixed link again
1 parent 1f152be commit 7e82e8d

File tree

9 files changed

+54
-29
lines changed

9 files changed

+54
-29
lines changed

source/core/csfle/quick-start.txt

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,8 @@ Procedure
100100

101101
.. step:: Create a {+dek-long+}
102102

103+
.. _csfle-quick-start-create-dek:
104+
103105
.. include:: /includes/quick-start/dek.rst
104106

105107
.. see:: Complete Code
Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
.. note::
2+
3+
The ``data_key_id`` variable in the following examples refers to a
4+
{+dek-long+} (DEK). To learn how to generate a DEK with your Local Key
5+
Provider, see the :ref:`Quick Start <csfle-quick-start-create-dek>`. To learn how to create a
6+
DEK with a specific {+kms-long+}, see :ref:`csfle-tutorials`.
7+
Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
.. note::
2+
3+
The ``dataKeyId`` variable in the following examples refers to a
4+
{+dek-long+} (DEK). To learn how to generate a DEK with your Local Key
5+
Provider, see the :ref:`Quick Start <csfle-quick-start-create-dek>`. To learn how to create a
6+
DEK with a specific {+kms-long+}, see :ref:`csfle-tutorials`.
7+

source/includes/fundamentals/manual-encryption/example/encFields.rst

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@ your document and insert your document into MongoDB:
1111
.. tab::
1212
:tabid: java-sync
1313

14+
.. include:: /includes/fundamentals/manual-encryption/example/dek-note.rst
15+
1416
.. literalinclude:: /includes/fundamentals/manual-encryption/manual-enc.java
1517
:language: java
1618
:start-after: start_enc_and_insert
@@ -19,6 +21,8 @@ your document and insert your document into MongoDB:
1921
.. tab::
2022
:tabid: nodejs
2123

24+
.. include:: /includes/fundamentals/manual-encryption/example/dek-note.rst
25+
2226
.. literalinclude:: /includes/fundamentals/manual-encryption/manual-enc.js
2327
:language: javascript
2428
:start-after: start_enc_and_insert
@@ -27,6 +31,8 @@ your document and insert your document into MongoDB:
2731
.. tab::
2832
:tabid: python
2933

34+
.. include:: /includes/fundamentals/manual-encryption/example/dek-note-python.rst
35+
3036
.. literalinclude:: /includes/fundamentals/manual-encryption/manual-enc.py
3137
:language: python
3238
:start-after: start_enc_and_insert
@@ -35,6 +41,8 @@ your document and insert your document into MongoDB:
3541
.. tab::
3642
:tabid: csharp
3743

44+
.. include:: /includes/fundamentals/manual-encryption/example/dek-note.rst
45+
3846
.. literalinclude:: /includes/fundamentals/manual-encryption/manual-enc.cs
3947
:dedent:
4048
:language: csharp
@@ -44,6 +52,8 @@ your document and insert your document into MongoDB:
4452
.. tab::
4553
:tabid: go
4654

55+
.. include:: /includes/fundamentals/manual-encryption/example/dek-note.rst
56+
4757
.. literalinclude:: /includes/fundamentals/manual-encryption/manual-enc.go
4858
:dedent:
4959
:language: go
@@ -53,6 +63,8 @@ your document and insert your document into MongoDB:
5363
.. tab::
5464
:tabid: shell
5565

66+
.. include:: /includes/fundamentals/manual-encryption/example/dek-note.rst
67+
5668
.. literalinclude:: /includes/fundamentals/manual-encryption/manual-enc-shell.js
5769
:language: javascript
5870
:start-after: start_enc_and_insert

source/includes/fundamentals/manual-encryption/manual-enc-shell.js

Lines changed: 5 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -18,26 +18,23 @@ const autoEncryptionOpts = {
1818
keyVaultNamespace: keyVaultNamespace,
1919
kmsProviders: kmsProviders,
2020
};
21-
const encryptedClient = Mongo(
22-
connectionString,
23-
autoEncryptionOpts
24-
);
21+
const encryptedClient = Mongo(connectionString, autoEncryptionOpts);
2522
// end_mongoclient
2623
// start_client_enc
2724
const clientEncryption = encryptedClient.getClientEncryption();
2825
// end_client_enc
2926

3027
const keyVault = encryptedClient.getKeyVault();
31-
const keyId = keyVault.createKey("aws", masterKey);
28+
const dataKeyId = keyVault.createKey("aws", masterKey);
3229

3330
// start_enc_and_insert
3431
const encName = clientEncryption.encrypt(
35-
keyId,
32+
dataKeyId,
3633
"Greg",
3734
"AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"
3835
);
3936
const encFoods = clientEncryption.encrypt(
40-
keyId,
37+
dataKeyId,
4138
["Cheese", "Grapes"],
4239
"AEAD_AES_256_CBC_HMAC_SHA_512-Random"
4340
);
@@ -48,7 +45,7 @@ db.getSiblingDB(database).getCollection(collection).insertOne({
4845
// end_enc_and_insert
4946
// start_find_decrypt
5047
const encNameQuery = clientEncryption.encrypt(
51-
keyId,
48+
dataKeyId,
5249
"Greg",
5350
"AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"
5451
);

source/includes/fundamentals/manual-encryption/manual-enc.cs

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ public static void Main()
2121

2222
// start-credentials
2323
var kmsProviders = new Dictionary<string, IReadOnlyDictionary<string, object>>();
24-
var provider = "aws";
24+
var provider = "aws";
2525
var awsAccessKey = Environment.GetEnvironmentVariable("AWS_ACCESS_KEY_ID");
2626
var awsSecretAccessKey = Environment.GetEnvironmentVariable("AWS_SECRET_ACCESS_KEY");
2727
var awsKmsOptions = new Dictionary<string, object>
@@ -52,27 +52,27 @@ public static void Main()
5252

5353
List<string> keyNames = new List<string>();
5454
keyNames.Add("manual-enc-test");
55-
var uuidOfDek = clientEncryption.CreateDataKey(provider, dataKeyOptions.With(keyNames), CancellationToken.None);
55+
var dataKeyId = clientEncryption.CreateDataKey(provider, dataKeyOptions.With(keyNames), CancellationToken.None);
5656

5757
// start_enc_and_insert
5858
var encryptedName = clientEncryption.Encrypt(
5959
"Greg",
60-
new EncryptOptions(algorithm : "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic", keyId : uuidOfDek),
60+
new EncryptOptions(algorithm: "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic", keyId: dataKeyId),
6161
CancellationToken.None);
6262
var encryptedFoods = clientEncryption.Encrypt(
63-
new BsonArray{"Cheese", "Grapes"},
64-
new EncryptOptions(algorithm : "AEAD_AES_256_CBC_HMAC_SHA_512-Random", keyId : uuidOfDek),
63+
new BsonArray { "Cheese", "Grapes" },
64+
new EncryptOptions(algorithm: "AEAD_AES_256_CBC_HMAC_SHA_512-Random", keyId: dataKeyId),
6565
CancellationToken.None);
66-
collection.InsertOne(new BsonDocument {{"name", encryptedName}, {"age", 83}, {"foods", encryptedFoods}});
66+
collection.InsertOne(new BsonDocument { { "name", encryptedName }, { "age", 83 }, { "foods", encryptedFoods } });
6767
// end_enc_and_insert
6868

6969
// start_find_decrypt
7070
var nameToQuery = "Greg";
7171
var encryptedNameToQuery = clientEncryption.Encrypt(
7272
nameToQuery,
73-
new EncryptOptions(algorithm : "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic", keyId : uuidOfDek),
73+
new EncryptOptions(algorithm: "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic", keyId: dataKeyId),
7474
CancellationToken.None);
75-
var doc = collection.Find(new BsonDocument{{"name", encryptedNameToQuery}}).Single();
75+
var doc = collection.Find(new BsonDocument { { "name", encryptedNameToQuery } }).Single();
7676
Console.WriteLine($"Encrypted document: {doc}");
7777
doc["name"] = clientEncryption.Decrypt(doc["name"].AsBsonBinaryData, CancellationToken.None);
7878
doc["foods"] = clientEncryption.Decrypt(doc["foods"].AsBsonBinaryData, CancellationToken.None);

source/includes/fundamentals/manual-encryption/manual-enc.go

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ func main() {
5757
dataKeyOpts := options.DataKey().
5858
SetMasterKey(masterKey).
5959
SetKeyAltNames([]string{KeyAltName})
60-
dataKeyID, err := clientEnc.CreateDataKey(context.TODO(), provider, dataKeyOpts)
60+
dataKeyId, err := clientEnc.CreateDataKey(context.TODO(), provider, dataKeyOpts)
6161
if err != nil {
6262
panic(fmt.Errorf("create data key error %v", err))
6363
}
@@ -70,7 +70,7 @@ func main() {
7070
nameRawValue := bson.RawValue{Type: nameRawValueType, Value: nameRawValueData}
7171
nameEncryptionOpts := options.Encrypt().
7272
SetAlgorithm("AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic").
73-
SetKeyID(dataKeyID)
73+
SetKeyID(dataKeyId)
7474
nameEncryptedField, err := clientEnc.Encrypt(
7575
context.TODO(),
7676
nameRawValue,
@@ -85,7 +85,7 @@ func main() {
8585
foodsRawValue := bson.RawValue{Type: foodsRawValueType, Value: foodsRawValueData}
8686
encryptionOpts := options.Encrypt().
8787
SetAlgorithm("AEAD_AES_256_CBC_HMAC_SHA_512-Random").
88-
SetKeyID(dataKeyID)
88+
SetKeyID(dataKeyId)
8989
foodsEncryptedField, err := clientEnc.Encrypt(
9090
context.TODO(),
9191
foodsRawValue,
@@ -110,7 +110,7 @@ func main() {
110110
nameQueryRawValue := bson.RawValue{Type: nameQueryRawValueType, Value: nameQueryRawValueData}
111111
nameQueryEncryptionOpts := options.Encrypt().
112112
SetAlgorithm("AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic").
113-
SetKeyID(dataKeyID)
113+
SetKeyID(dataKeyId)
114114
nameQueryEncryptedField, err := clientEnc.Encrypt(
115115
context.TODO(),
116116
nameQueryRawValue,

source/includes/fundamentals/manual-encryption/manual-enc.js

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -39,19 +39,19 @@ async function main() {
3939
kmsProviders,
4040
});
4141
// end_client_enc
42-
const keyId = await encryption.createDataKey(provider, {
42+
const dataKeyId = await encryption.createDataKey(provider, {
4343
masterKey: masterKey,
4444
keyAltNames: ["manual-enc-demo"],
4545
});
46-
console.log(keyId);
46+
console.log(dataKeyId);
4747
// start_enc_and_insert
4848
encryptedName = await encryption.encrypt("Greg", {
4949
algorithm: "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
50-
keyId: keyId,
50+
keyId: dataKeyId,
5151
});
5252
encryptedFoods = await encryption.encrypt(["Cheese", "Grapes"], {
5353
algorithm: "AEAD_AES_256_CBC_HMAC_SHA_512-Random",
54-
keyId: keyId,
54+
keyId: dataKeyId,
5555
});
5656
await collection.insertOne({
5757
name: encryptedName,
@@ -62,7 +62,7 @@ async function main() {
6262
// start_find_decrypt
6363
queryEncryptedName = await encryption.encrypt("Greg", {
6464
algorithm: "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
65-
keyId: keyId,
65+
keyId: dataKeyId,
6666
});
6767
let doc = await collection.findOne({ name: queryEncryptedName });
6868
console.log("Encrypted Document: ", doc);

source/includes/fundamentals/manual-encryption/manual-enc.py

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -27,20 +27,20 @@ def main():
2727

2828
refreshKeyVault(client)
2929
# Create a new data key and json schema for the encryptedField.
30-
uuid_of_data_encryption_key = client_encryption.create_data_key(
30+
data_key_id = client_encryption.create_data_key(
3131
"local", key_alt_names=["pymongo_encryption_example_3"]
3232
)
3333

3434
# start_enc_and_insert
3535
encrypted_name = client_encryption.encrypt(
3636
"Greg",
3737
Algorithm.AEAD_AES_256_CBC_HMAC_SHA_512_Deterministic,
38-
key_id=uuid_of_data_encryption_key,
38+
key_id=data_key_id,
3939
)
4040
encrypted_foods = client_encryption.encrypt(
4141
["Cheese", "Grapes"],
4242
Algorithm.AEAD_AES_256_CBC_HMAC_SHA_512_Random,
43-
key_id=uuid_of_data_encryption_key,
43+
key_id=data_key_id,
4444
)
4545
coll.insert_one({"name": encrypted_name, "age": 83, "foods": encrypted_foods})
4646
# end_enc_and_insert
@@ -50,7 +50,7 @@ def main():
5050
encrypted_name_to_query = client_encryption.encrypt(
5151
name_to_query,
5252
Algorithm.AEAD_AES_256_CBC_HMAC_SHA_512_Deterministic,
53-
key_id=uuid_of_data_encryption_key,
53+
key_id=data_key_id,
5454
)
5555
doc = client.employees.foods.find_one({"name": encrypted_name_to_query})
5656
print("Encrypted document: %s" % (doc,))

0 commit comments

Comments
 (0)