Client-Side Field Level Encryption

    With field level encryption, applications can encrypt fields in documents prior to transmitting data over the wire to the server. Client-side field level encryption supports workloads where applications must guarantee that unauthorized parties, including server administrators, cannot read the encrypted data.

    See also

    The MongoDB documentation on

    client-side-field-level-encryption

    To get started using client-side field level encryption in your project, you will need to install the library as well as the driver itself. Install both the driver and a compatible version of pymongocrypt like this:

    Note that installing on Linux requires pip 19 or later for manylinux2010 wheel support. For more information about installing pymongocrypt see the installation instructions on the project’s PyPI page.

    mongocryptd

    mongocryptd performs the following:

    • Parses the automatic encryption rules specified to the database connection. If the JSON schema contains invalid automatic encryption syntax or any document validation syntax, mongocryptd returns an error.
    • Uses the specified automatic encryption rules to mark fields in read and write operations for encryption.
    • Rejects read/write operations that may return unexpected or incorrect results when applied to an encrypted field. For supported and unsupported operations, see Read/Write Support with Automatic Field Level Encryption.

    A MongoClient configured with auto encryption will automatically spawn the mongocryptd process from the application’s PATH. Applications can control the spawning behavior as part of the automatic encryption options. For example to set the path to the mongocryptd process:

    1. auto_encryption_opts = AutoEncryptionOpts(
    2.         ...,
    3.         mongocryptd_spawn_path='/path/to/mongocryptd')

    To control the logging output of mongocryptd pass options using mongocryptd_spawn_args:

    If your application wishes to manage the mongocryptd process manually, it is possible to disable spawning mongocryptd:

    1. auto_encryption_opts = AutoEncryptionOpts(
    2.         ...,
    3.         mongocryptd_bypass_spawn=True,
    4.         # URI of the local ``mongocryptd`` process.
    5.         mongocryptd_uri='mongodb://localhost:27020')

    mongocryptd is only responsible for supporting automatic client-side field level encryption and does not itself perform any encryption or decryption.

    Automatic client-side field level encryption is enabled by creating a with the auto_encryption_opts option set to an instance of AutoEncryptionOpts. The following examples show how to setup automatic client-side field level encryption using to create a new encryption data key.

    Automatic client-side field level encryption requires MongoDB 4.2 enterprise or a MongoDB 4.2 Atlas cluster. The community version of the server supports automatic decryption as well as Explicit Encryption.

    Providing Local Automatic Encryption Rules

    The following example shows how to specify automatic encryption rules via the schema_map option. The automatic encryption rules are expressed using a strict subset of the JSON Schema syntax.

    Supplying a schema_map provides more security than relying on JSON Schemas obtained from the server. It protects against a malicious server advertising a false JSON Schema, which could trick the client into sending unencrypted data that should be encrypted.

    JSON Schemas supplied in the schema_map only apply to configuring automatic client-side field level encryption. Other validation rules in the JSON schema will not be enforced by the driver and will result in an error.:

    Server-Side Field Level Encryption Enforcement

    The MongoDB 4.2 server supports using schema validation to enforce encryption of specific fields in a collection. This schema validation will prevent an application from inserting unencrypted values for any fields marked with the "encrypt" JSON schema keyword.

    The following example shows how to setup automatic client-side field level encryption using ClientEncryption to create a new encryption data key and create a collection with the :

    1. import os
    3. from bson.codec_options import CodecOptions
    4. from bson.binary import STANDARD
    6. from pymongo import MongoClient
    7. from pymongo.encryption import (Algorithm,
    8.                                 ClientEncryption)
    9. from pymongo.encryption_options import AutoEncryptionOpts
    10. from pymongo.errors import OperationFailure
    11. from pymongo.write_concern import WriteConcern
    14. def main():
    15.     # The MongoDB namespace (db.collection) used to store the
    16.     # encrypted documents in this example.
    17.     encrypted_namespace = "test.coll"
    19.     # This must be the same master key that was used to create
    20.     # the encryption key.
    21.     local_master_key = os.urandom(96)
    22.     kms_providers = {"local": {"key": local_master_key}}
    24.     # The MongoDB namespace (db.collection) used to store
    25.     # the encryption data keys.
    26.     key_vault_namespace = "encryption.__pymongoTestKeyVault"
    27.     key_vault_db_name, key_vault_coll_name = key_vault_namespace.split(".", 1)
    29.     # The MongoClient used to access the key vault (key_vault_namespace).
    30.     key_vault_client = MongoClient()
    31.     key_vault = key_vault_client[key_vault_db_name][key_vault_coll_name]
    32.     # Ensure that two data keys cannot share the same keyAltName.
    33.     key_vault.drop()
    34.     key_vault.create_index(
    35.         "keyAltNames",
    36.         unique=True,
    37.         partialFilterExpression={"keyAltNames": {"$exists": True}})
    39.     client_encryption = ClientEncryption(
    40.         kms_providers,
    41.         key_vault_namespace,
    43.         # The CodecOptions class used for encrypting and decrypting.
    44.         # This should be the same CodecOptions instance you have configured
    45.         # encrypt() or decrypt() in this example so we can use any
    46.         # CodecOptions.
    47.         CodecOptions())
    49.     # Create a new data key and json schema for the encryptedField.
    50.     data_key_id = client_encryption.create_data_key(
    51.         'local', key_alt_names=['pymongo_encryption_example_2'])
    52.     json_schema = {
    53.         "properties": {
    54.             "encryptedField": {
    55.                 "encrypt": {
    56.                     "keyId": [data_key_id],
    57.                     "bsonType": "string",
    58.                     "algorithm":
    59.                         Algorithm.AEAD_AES_256_CBC_HMAC_SHA_512_Deterministic
    60.                 }
    61.             }
    62.         },
    63.         "bsonType": "object"
    64.     }
    66.     auto_encryption_opts = AutoEncryptionOpts(
    67.         kms_providers, key_vault_namespace)
    68.     client = MongoClient(auto_encryption_opts=auto_encryption_opts)
    69.     db_name, coll_name = encrypted_namespace.split(".", 1)
    70.     db = client[db_name]
    71.     # Clear old data
    72.     db.drop_collection(coll_name)
    73.     # Create the collection with the encryption JSON Schema.
    74.     db.create_collection(
    75.         coll_name,
    76.         # uuid_representation=STANDARD is required to ensure that any
    77.         # UUIDs in the $jsonSchema document are encoded to BSON Binary
    78.         # with the standard UUID subtype 4. This is only needed when
    79.         # running the "create" collection command with an encryption
    80.         # JSON Schema.
    81.         codec_options=CodecOptions(uuid_representation=STANDARD),
    82.         write_concern=WriteConcern(w="majority"),
    83.         validator={"$jsonSchema": json_schema})
    84.     coll = client[db_name][coll_name]
    86.     coll.insert_one({"encryptedField": "123456789"})
    87.     print('Decrypted document: %s' % (coll.find_one(),))
    88.     unencrypted_coll = MongoClient()[db_name][coll_name]
    89.     print('Encrypted document: %s' % (unencrypted_coll.find_one(),))
    90.     try:
    91.         unencrypted_coll.insert_one({"encryptedField": "123456789"})
    92.     except OperationFailure as exc:
    93.         print('Unencrypted insert failed: %s' % (exc.details,))
    96. if __name__ == "__main__":
    97.     main()

    Although automatic encryption requires MongoDB 4.2 enterprise or a MongoDB 4.2 Atlas cluster, automatic decryption is supported for all users. To configure automatic decryption without automatic encryption set bypass_auto_encryption=True in AutoEncryptionOpts:

    1. import os
    3. from pymongo import MongoClient
    4. from pymongo.encryption import (Algorithm,
    5.                                 ClientEncryption)
    6. from pymongo.encryption_options import AutoEncryptionOpts
    9. def main():
    10.     # the encryption key.
    11.     local_master_key = os.urandom(96)
    12.     kms_providers = {"local": {"key": local_master_key}}
    14.     # The MongoDB namespace (db.collection) used to store
    15.     # the encryption data keys.
    16.     key_vault_namespace = "encryption.__pymongoTestKeyVault"
    17.     key_vault_db_name, key_vault_coll_name = key_vault_namespace.split(".", 1)
    19.     # bypass_auto_encryption=True disable automatic encryption but keeps
    20.     # the automatic _decryption_ behavior. bypass_auto_encryption will
    21.     # also disable spawning mongocryptd.
    22.     auto_encryption_opts = AutoEncryptionOpts(
    23.         kms_providers, key_vault_namespace, bypass_auto_encryption=True)
    25.     client = MongoClient(auto_encryption_opts=auto_encryption_opts)
    26.     coll = client.test.coll
    27.     # Clear old data
    28.     coll.drop()
    30.     # Set up the key vault (key_vault_namespace) for this example.
    31.     key_vault = client[key_vault_db_name][key_vault_coll_name]
    32.     # Ensure that two data keys cannot share the same keyAltName.
    33.     key_vault.drop()
    34.     key_vault.create_index(
    35.         "keyAltNames",
    36.         unique=True,
    37.         partialFilterExpression={"keyAltNames": {"$exists": True}})
    39.     client_encryption = ClientEncryption(
    40.         kms_providers,
    41.         key_vault_namespace,
    42.         # The MongoClient to use for reading/writing to the key vault.
    43.         # This can be the same MongoClient used by the main application.
    44.         client,
    45.         # The CodecOptions class used for encrypting and decrypting.
    46.         # This should be the same CodecOptions instance you have configured
    47.         # on MongoClient, Database, or Collection.
    48.         coll.codec_options)
    50.     # Create a new data key for the encryptedField.
    51.     data_key_id = client_encryption.create_data_key(
    52.         'local', key_alt_names=['pymongo_encryption_example_4'])
    54.     # Explicitly encrypt a field:
    55.     encrypted_field = client_encryption.encrypt(
    56.         "123456789",
    57.         Algorithm.AEAD_AES_256_CBC_HMAC_SHA_512_Deterministic,
    58.         key_alt_name='pymongo_encryption_example_4')
    59.     coll.insert_one({"encryptedField": encrypted_field})
    60.     # Automatically decrypts any encrypted fields.
    61.     doc = coll.find_one()
    62.     print('Decrypted document: %s' % (doc,))
    63.     unencrypted_coll = MongoClient().test.coll
    64.     print('Encrypted document: %s' % (unencrypted_coll.find_one(),))
    66.     # Cleanup resources.
    67.     client_encryption.close()
    68.     client.close()