The document describes how client-side encryption works in MongoDB. It explains that the client encrypts data before sending it to MongoDB using encrypted data keys stored in a key vault collection. It also covers how JSON schemas can specify encryption rules for fields using properties like keyId, algorithm, and bsonType. The schemas help ensure data is encrypted as intended before being inserted or updated.

1. Introducing…

2. Step 1
db.coll.insert({
_id: 1,
name: "Todd",
ssn: "457-55-5462"
})

3. Step 2
doc = db.coll.find({
ssn: "457-55-5642"
})

4. Step 3
print (doc)

5. {
_id: 1
name: "Todd",
ssn: "457-55-5462"
}

7. Client Side Encryption
Encrypt before sending. Decrypt after receiving.

8. Client Side Encryption
Encrypt before sending. Decrypt after receiving.
db.coll.insert({
name: "Todd",
ssn: "457-55-5462"
})
{
insert: "coll",
documents: [{
name: "Todd",
ssn: BinData("a10x…", "06")
}]
}
You see: MongoDB sees:

9. Client Side Encryption
How does this differ from…?
•… encryption in-transit (TLS)
•… encryption at-rest (encrypted storage engine)

10. Client Disk
{ ssn: "457-55-5462" } { ssn: "457-55-5462" }
Attacker
Steal disk
Listen to traffic
MongoDB
send over socket
insert: { ssn: "457-55-5462" }
{ ok: 1 }
Malicious admin
db.coll.find()

11. Client Disk
send over socket:
insert: { ssn: "457-55-5462" }
write to disk
{ ssn: "457-55-5462" }
MongoDB
Boundary of unencrypted data

12. Client Disk
send over socket:
insert: { ssn: "457-55-5462" }
write to disk
<ciphertext>
MongoDB
Boundary of unencrypted data
Enabling encrypted storage engine

13. Client Disk
send over socket:
<ciphertext>
write to disk
<ciphertext>
MongoDB
Encrypted storage engine
+
TLS

14. Client Disk
send over socket:
insert: { ssn: <ciphertext> }
write to disk
{ ssn: <ciphertext> }
MongoDB
Client Side Encryption

15. But why?

16. But why?
Store private data in the public cloud.

17. But why?
Store private stuff in public storage.
Storage Unit
Store private data in the public cloud.
Key to Unit
Held by you and
management
Police
Comes with a warrant

18. But why?
Support GDPR right-to-be-forgotten.

19. What is possible?
db.coll.insert({
name: "Todd",
ssn: "457-55-5462"
})
{
insert: "coll",
documents: [{
name: "Todd",
ssn: BinData("a10x…", "06")
}]
}
You see: MongoDB sees:
Insert

20. What is possible?
db.coll.update({}, {
$set: { ssn: "457-55-5462" }
})
{
update: "coll",
updates: [{
q:{},
u: {
$set: { ssn: BinData("a10x…", "06") }
}
}]
}
You see: MongoDB sees:
Update that overwrites value

21. What is possible?
db.coll.aggregate([{
$project: { name_ssn: {$concat: [ "$name", " - ", "$ssn" ] } }
}]
Aggregate acting on the data

22. What is possible?
Find with equality query
* For deterministic encryption
db.coll.find({ssn: "457-55-5462" }) {
find: "coll",
filter: { ssn: BinData("a10x…", "06") }
}
You see: MongoDB sees:

23. What is possible?
Find with equality query
* For deterministic encryption
db.test.find(
{
$and: [
{
$or: [
{ ssn : { $in : [ "457-55-5462", "153-96-2097" ]} },
{ ssn: { $exists: false } }
]
},
{ name: "Todd" }
]
}
)
You see:

24. What is possible?
Find with equality query
* For deterministic encryption
MongoDB sees:
{
find: "coll",
filter: {
$and: [
{
$or: [
{ ssn : { $in : [ BinData("a10x…", "06"), BinData("8dk1…", "06") ]} },
{ ssn: { $exists: false } }
]
},
{ name: "Todd" }
]
}
}

25. But how does it work?

26. encrypted_client = MongoClient(client_side_encryption_opts=opts)

27. Curtain #1
The Key Vault

28. Storage Unit Key to Unit
Held by you and
management

29. Vault key
Held only by you
Vault

30. Storage Unit
Vault
Vault key
Held only by you
Unit key
Held by you and
management

31. Storage Unit
Vault keys
Held only by you
Unit key
Held by you and
management

32. Vault keys
Held only by you
Vault keys Key vault
Key vault key
Held only by you

33. Storage Unit
Key vault key
Held only by you
Unit key
Held by you and
management

34. Storage Unit
MongoDB
collection
Key Management
Service (KMS)
MongoDB
credentials
Encrypted
data keys
VaultUnit key Vault keys Key vault key
Encrypted
data
Key vault
MongoDB
key vault
collection

35. db.coll.insert({
name: "Todd",
ssn: "457-55-5462"
})
1. Get encrypted data key from key vault collection
2. Decrypt data key with KMS
3. Encrypt "457-55-5462" with decrypted keyMaterial
4. Send insert to MongoDB

36. Key Vault Collection
{
_id: <UUID>,
keyAltNames: <string[]>,
keyMaterial: <BinData>,
creationDate: <Date>,
updateDate: <Date>
masterKey: <Document>
}
keyAltNames are alternate string identifiers.keyAltNames are alternate string identifiers.
masterKey identifies the KMS key
keyMaterial is the data key (encrypted with KMS)

37. What if
… a data key is compromised?
Data is safe, the key can't be decrypted without KMS

38. What if
… malicious DB admin drops key vault?
Then you lose access.
MongoDB key vault can be on a separate cluster.
…but

39. Curtain #2
JSON Schema

40. JSON Schema
Describes JSON
{
bsonType: "object",
properties: {
a: {
bsonType: "int"
maximum: 10
}
b: { bsonType: "string" }
},
required: ["a", "b"]
}
{
a: 5,
b: "hi"
}
{
a: 11,
b: false
}

41. JSON Schema "encrypt"
{
bsonType: "object",
properties: {
ssn: {
encrypt: { … }
}
},
required: ["ssn"]
}

42. encrypt: {
keyId: <UUID[]> or <string>,
algorithm: <string>
bsonType: <string> or <string[]>
}
bsonType indicates the type of underlying data.
E.g. "string" or [ "string", "objectId" ]
algorithm indicates how to encrypt.
"AEAD_AES_256_CBC_HMAC_SHA_512-Random" or
AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"
keyId indicates the key used to encrypt.
UUID("E0A8…") or "/fieldName"

43. keyId
encrypt: {
bsonType: "string"
keyId: [ UUID(1) ]
algorithm: "AEAD…"
}
Schema
{
_id: UUID(1)
keyAltNames: [ "Todd" ]
keyMaterial: BinData("AQIC…")
}
Key Vault Document

44. keyId
encrypt: {
bsonType: "string"
keyId: "/name"
algorithm: "AEAD…"
}
Schema
{
_id: UUID(1)
keyAltNames: [ "Todd" ]
keyMaterial: BinData("AQIC…")
}
Key Vault Document
{
name: "Todd",
ssn: "457-55-5462"
}
Document to insert

45. algorithm
AEAD_AES_256_CBC_HMAC_SHA_512-Random
AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic
Deterministic can satisfy equality queries.
Random is more secure.

46. bsonType
Only one type may be specified. Additional types are excluded:. "bool", "double",
"decimal128", "object", "array", "javascriptWithScope"
DETERMINISTIC restrictions
Single value types (undefined, null, minkey, maxkey) are prohibited.
Restrictions

47. Setting the JSON Schema
db.createCollection("coll", { validator: { $jsonSchema: … } } )

48. What if
… malicious DB admin sends you a bad schema?
Client is tricked into sending unencrypted data.

49. encryption_schema = {…}
client = MongoClient(schema_map={
"db.encrypted": encryption_schema
}, …)
Set it locally

50. Thanks