MotorClientEncryption

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: bson.binary.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: Optional[Mapping[str, Any]] = None, key_alt_names: Optional[Sequence[str]] = None, key_material: Optional[bytes] = None) → bson.binary.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)
coroutine decrypt(value: bson.binary.Binary) → Any

Decrypt an encrypted value.

Parameters

  • value (Binary): The encrypted value, a Binary with subtype 6.

Returns

The decrypted BSON value.

coroutine delete_key(id: bson.binary.Binary) → pymongo.results.DeleteResult

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

Parameters

  • id (Binary): The UUID of a key a which must be a Binary with subtype 4 ( UUID_SUBTYPE).

Returns

The delete result.

coroutine encrypt(value: Any, algorithm: str, key_id: Optional[bson.binary.Binary] = None, key_alt_name: Optional[str] = None, query_type: Optional[str] = None, contention_factor: Optional[int] = None) → bson.binary.Binary

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.

  • algorithm (string): 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’.

  • query_type (str): (BETA) The query type to execute. See QueryType for valid options.

  • contention_factor (int): (BETA) The contention factor to use when the algorithm is Algorithm.INDEXED. An integer value must be given when the Algorithm.INDEXED algorithm is used.

Note

query_type and contention_factor are part of the Queryable Encryption beta. Backwards-breaking changes may be made before the final release.

Returns

The encrypted value, a Binary with subtype 6.

coroutine get_key(id: bson.binary.Binary) → Optional[bson.raw_bson.RawBSONDocument]

Get a data key by id.

Parameters

  • id (Binary): 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) → Optional[bson.raw_bson.RawBSONDocument]

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: bson.binary.Binary, key_alt_name: str) → Optional[bson.raw_bson.RawBSONDocument]

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: Optional[str] = None, master_key: Optional[Mapping[str, Any]] = None) → pymongo.encryption.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.