`MotorClientEncryption`¶

Warning

Motor will be deprecated on May 14th, 2026, one year after the production release of the PyMongo Async driver. Critical bug fixes will be made until May 14th, 2027. We strongly recommend that Motor users migrate to the PyMongo Async driver while Motor is still supported. To learn more, see the migration guide.

class motor.motor_tornado.MotorClientEncryption(kms_providers, key_vault_namespace, key_vault_client, codec_options, io_loop=None, kms_tls_options=None)¶

Explicit client-side field level encryption.

Takes the same constructor arguments as pymongo.encryption.ClientEncryption, as well as:

Parameters:

io_loop (optional): Special event loop instance to use instead of default.

coroutine add_key_alt_name(id: Binary, key_alt_name: str) → Any¶

Add key_alt_name to the set of alternate names in the key document with UUID key_id.

Parameters:

id – The UUID of a key a which must be a Binary with subtype 4 ( UUID_SUBTYPE).
key_alt_name – The key alternate name to add.

Returns:

The previous version of the key document.

coroutine close() → None¶

Release resources.

Note that using this class in a with-statement will automatically call close():

async with AsyncIOMotorClientEncryption(...) as client_encryption:
    encrypted = await client_encryption.encrypt(value, ...)
    decrypted = await client_encryption.decrypt(encrypted)

coroutine create_data_key(kms_provider: str, master_key: Mapping[str, Any] | None = None, key_alt_names: Sequence[str] | None = None, key_material: bytes | None = None) → Binary¶

Create and insert a new data key into the key vault collection.

Takes the same arguments as pymongo.encryption.ClientEncryption.create_data_key, with only the following slight difference using async syntax. The following example shows creating and referring to a data key by alternate name:

await client_encryption.create_data_key("local", keyAltNames=["name1"])
# reference the key with the alternate name
await client_encryption.encrypt("457-55-5462", keyAltName="name1",
                                algorithm=Algorithm.AEAD_AES_256_CBC_HMAC_SHA_512_Random)

async create_encrypted_collection(database, name, encrypted_fields, kms_provider=None, master_key=None, **kwargs)¶

Create a collection with encryptedFields.

Warning

This function does not update the encryptedFieldsMap in the client’s AutoEncryptionOpts, thus the user must create a new client after calling this function with the encryptedFields returned.

Normally collection creation is automatic. This method should only be used to specify options on creation. EncryptionError will be raised if the collection already exists.

Parameters:

database: the database in which to create a collection
name: the name of the collection to create

encrypted_fields (dict): Document that describes the encrypted fields for Queryable Encryption. For example:

{
  "escCollection": "enxcol_.encryptedCollection.esc",
  "ecocCollection": "enxcol_.encryptedCollection.ecoc",
  "fields": [
      {
          "path": "firstName",
          "keyId": Binary.from_uuid(UUID('00000000-0000-0000-0000-000000000000')),
          "bsonType": "string",
          "queries": {"queryType": "equality"}
      },
      {
          "path": "ssn",
          "keyId": Binary.from_uuid(UUID('04104104-1041-0410-4104-104104104104')),
          "bsonType": "string"
      }
    ]
}

The “keyId” may be set to None to auto-generate the data keys.

kms_provider (optional): the KMS provider to be used
master_key (optional): Identifies a KMS-specific key used to encrypt the new data key. If the kmsProvider is “local” the master_key is not applicable and may be omitted.
**kwargs (optional): additional keyword arguments are the same as “create_collection”.

All optional create collection command parameters should be passed as keyword arguments to this method. See the documentation for create_collection() for all valid options.

Raises:

EncryptedCollectionError: When either data-key creation or creating the collection fails.

Added in version 3.2.

coroutine decrypt(value: Binary) → Any¶

Decrypt an encrypted value.

Parameters:: (Binary) (value`) – The encrypted value, a Binary with subtype 6.
Returns:: The decrypted BSON value.

coroutine delete_key(id: Binary) → DeleteResult¶

Delete a key document in the key vault collection that has the given key_id.

Parameters:: (Binary) (id`) – The UUID of a key a which must be a Binary with subtype 4 ( UUID_SUBTYPE).
Returns:: The delete result.

Encrypt a BSON value with a given key and algorithm.

Note that exactly one of key_id or key_alt_name must be provided.

Parameters:

value – The BSON value to encrypt.
(string) (algorithm`) – The encryption algorithm to use. See Algorithm for some valid options.
key_id – Identifies a data key by _id which must be a Binary with subtype 4 ( UUID_SUBTYPE).
key_alt_name – Identifies a key vault document by ‘keyAltName’.
(str) (query_type`) – The query type to execute. See QueryType for valid options.
(int) (contention_factor`) – The contention factor to use when the algorithm is Algorithm.INDEXED. An integer value must be given when the Algorithm.INDEXED algorithm is used.
range_opts – Index options for range queries. See RangeOpts for some valid options.

Returns:

The encrypted value, a Binary with subtype 6.

Encrypt a BSON expression with a given key and algorithm.

Note that exactly one of key_id or key_alt_name must be provided.

Parameters:

expression – The BSON aggregate or match expression to encrypt.
(string) (algorithm`) – The encryption algorithm to use. See Algorithm for some valid options.
key_id – Identifies a data key by _id which must be a Binary with subtype 4 ( UUID_SUBTYPE).
key_alt_name – Identifies a key vault document by ‘keyAltName’.
(str) (query_type`) – The query type to execute. See QueryType for valid options.
(int) (contention_factor`) – The contention factor to use when the algorithm is Algorithm.INDEXED. An integer value must be given when the Algorithm.INDEXED algorithm is used.
range_opts – Index options for range queries. See RangeOpts for some valid options.

Returns:

The encrypted expression, a RawBSONDocument.

coroutine get_key(id: Binary) → RawBSONDocument | None¶

Get a data key by id.

Parameters:: (Binary) (id`) – The UUID of a key a which must be a Binary with subtype 4 ( UUID_SUBTYPE).
Returns:: The key document.

coroutine get_key_by_alt_name(key_alt_name: str) → RawBSONDocument | None¶

Get a key document in the key vault collection that has the given key_alt_name.

Parameters:: key_alt_name – (str): The key alternate name of the key to get.
Returns:: The key document.

coroutine remove_key_alt_name(id: Binary, key_alt_name: str) → RawBSONDocument | None¶

Remove key_alt_name from the set of keyAltNames in the key document with UUID id.

Also removes the keyAltNames field from the key document if it would otherwise be empty.

Parameters:

id – The UUID of a key a which must be a Binary with subtype 4 ( UUID_SUBTYPE).
key_alt_name – The key alternate name to remove.

Returns:

Returns the previous version of the key document.

coroutine rewrap_many_data_key(filter: Mapping[str, Any], provider: str | None = None, master_key: Mapping[str, Any] | None = None) → RewrapManyDataKeyResult¶

Decrypts and encrypts all matching data keys in the key vault with a possibly new master_key value.

Parameters:

filter – A document used to filter the data keys.
provider – The new KMS provider to use to encrypt the data keys, or None to use the current KMS provider(s).
master_key – The master key fields corresponding to the new KMS provider when provider is not None.

Returns:

A RewrapManyDataKeyResult.

This method allows you to re-encrypt all of your data-keys with a new CMK, or master key. Note that this does not require re-encrypting any of the data in your encrypted collections, but rather refreshes the key that protects the keys that encrypt the data:

client_encryption.rewrap_many_data_key(
    filter={"keyAltNames": "optional filter for which keys you want to update"},
    master_key={
        "provider": "azure",  # replace with your cloud provider
        "master_key": {
            # put the rest of your master_key options here
            "key": "<your new key>"
        },
    },
)

MotorClientEncryption¶

`MotorClientEncryption`¶