Skip to content

PYTHON-3299 Add Automatic Queryable Encryption Example to Docs #964

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 9 commits into from
Jun 7, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion doc/changelog.rst
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ PyMongo 4.2 brings a number of improvements including:

- Support for MongoDB 6.0.
- Support for the Queryable Encryption beta with MongoDB 6.0. Note that backwards-breaking
changes may be made before the final release.
changes may be made before the final release. See :ref:`automatic-queryable-client-side-encryption` for example usage.
- Provisional (beta) support for :func:`pymongo.timeout` to apply a single timeout
to an entire block of pymongo operations.

Expand Down Expand Up @@ -41,6 +41,7 @@ in this release.
.. _PYTHON-2885: https://jira.mongodb.org/browse/PYTHON-2885
.. _PYTHON-3167: https://jira.mongodb.org/browse/PYTHON-3167
.. _PyMongo 4.2 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=33196
.. _Queryable Encryption: automatic-queryable-client-side-encryption

Changes in Version 4.1.1
-------------------------
Expand Down
1 change: 1 addition & 0 deletions doc/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -85,6 +85,7 @@
# so this link results in a 404.
linkcheck_ignore = [
"https://github.com/mongodb/specifications/blob/master/source/server-discovery-and-monitoring/server-monitoring.rst#requesting-an-immediate-check",
"https://github.com/mongodb/libmongocrypt/blob/master/bindings/python/README.rst#installing-from-source",
r"https://wiki.centos.org/[\w/]*",
]

Expand Down
73 changes: 73 additions & 0 deletions doc/examples/encryption.rst
Original file line number Diff line number Diff line change
Expand Up @@ -336,6 +336,79 @@ data key and create a collection with the
if __name__ == "__main__":
main()

.. _automatic-queryable-client-side-encryption:

Automatic Queryable Encryption (Beta)
`````````````````````````````````````

PyMongo 4.2 brings beta support for Queryable Encryption with MongoDB 6.0.

Queryable Encryption is the second version of Client-Side Field Level Encryption.
Data is encrypted client-side. Queryable Encryption supports indexed encrypted fields,
which are further processed server-side.

You must have MongoDB 6.0rc8+ Enterprise to preview the capability.

Until PyMongo 4.2 release is finalized, it can be installed using::

pip install "pymongo@git+ssh://[email protected]/mongodb/[email protected]#egg=pymongo[encryption]"

Additionally, ``libmongocrypt`` must be installed from `source <https://github.com/mongodb/libmongocrypt/blob/master/bindings/python/README.rst#installing-from-source>`_.

Automatic encryption in Queryable Encryption is configured with an ``encrypted_fields`` mapping, as demonstrated by the following example::

import os
from bson.codec_options import CodecOptions
from pymongo import MongoClient
from pymongo.encryption import Algorithm, ClientEncryption, QueryType
from pymongo.encryption_options import AutoEncryptionOpts


local_master_key = os.urandom(96)
kms_providers = {"local": {"key": local_master_key}}
key_vault_namespace = "keyvault.datakeys"
key_vault_client = MongoClient()
client_encryption = ClientEncryption(
kms_providers, key_vault_namespace, key_vault_client, CodecOptions()
)
key_vault = key_vault_client["keyvault"]["datakeys"]
key_vault.drop()
key1_id = client_encryption.create_data_key("local", key_alt_names=["firstName"])
key2_id = client_encryption.create_data_key("local", key_alt_names=["lastName"])

encrypted_fields_map = {
"default.encryptedCollection": {
"escCollection": "encryptedCollection.esc",
"eccCollection": "encryptedCollection.ecc",
"ecocCollection": "encryptedCollection.ecoc",
"fields": [
{
"path": "firstName",
"bsonType": "string",
"keyId": key1_id,
"queries": [{"queryType": "equality"}],
},
{
"path": "lastName",
"bsonType": "string",
"keyId": key2_id,
}
]
}
}

auto_encryption_opts = AutoEncryptionOpts(
kms_providers, key_vault_namespace, encrypted_fields_map=encrypted_fields_map)
client = MongoClient(auto_encryption_opts=auto_encryption_opts)
client.default.drop_collection('encryptedCollection')
coll = client.default.create_collection('encryptedCollection')
coll.insert_one({ "_id": 1, "firstName": "Jane", "lastName": "Doe" })
docs = list(coll.find({"firstName": "Jane"}))
print(docs)

In the above example, the ``firstName`` and ``lastName`` fields are
automatically encrypted and decrypted.

.. _explicit-client-side-encryption:

Explicit Encryption
Expand Down