def encrypt(self, value, algorithm, key_id=None, key_alt_name=None):
"""Encrypts a BSON value.
Note that exactly one of ``key_id`` or ``key_alt_name`` must be
provided.
:Parameters:
- `value` (bytes): The BSON value to encrypt.
- `algorithm` (string): The encryption algorithm to use. See
:class:`Algorithm` for some valid options.
- `key_id` (bytes): The bytes of the binary subtype 4 ``_id`` data
key. For example, ``uuid.bytes`` or ``bytes(bson_binary)``.
- `key_alt_name` (string): Identifies a key vault document by
'keyAltName'.
:Returns:
The encrypted BSON value.
"""
# CDRIVER-3275 key_alt_name needs to be wrapped in a bson document.
if key_alt_name is not None:
key_alt_name = self.callback.bson_encode(
{'keyAltName': key_alt_name})
opts = ExplicitEncryptOpts(algorithm, key_id, key_alt_name)
with self.mongocrypt.explicit_encryption_context(value, opts) as ctx:
return run_state_machine(ctx, self.callback)
def create_data_key(self,
kms_provider,
master_key=None,
key_alt_names=None):
"""Creates a data key used for explicit encryption.
:Parameters:
- `kms_provider`: The KMS provider to use. Supported values are
"aws", "azure", "gcp", "kmip", and "local".
- `master_key`: See DataKeyOpts.
- `key_alt_names` (optional): An optional list of string alternate
names used to reference a key. If a key is created with alternate
names, then encryption may refer to the key by the unique
alternate name instead of by ``_id``.
:Returns:
The _id of the created data key document.
"""
# CDRIVER-3275 each key_alt_name needs to be wrapped in a bson
# document.
encoded_names = []
if key_alt_names is not None:
for name in key_alt_names:
encoded_names.append(
self.callback.bson_encode({'keyAltName': name}))
opts = DataKeyOpts(master_key, encoded_names)
with self.mongocrypt.data_key_context(kms_provider, opts) as ctx:
key = run_state_machine(ctx, self.callback)
return self.callback.insert_data_key(key)
def decrypt(self, response):
"""Decrypt a MongoDB command response.
:Parameters:
- `response`: A MongoDB command response as BSON.
:Returns:
The decrypted command response.
"""
with self.mongocrypt.decryption_context(response) as ctx:
return run_state_machine(ctx, self.callback)
def encrypt(self, database, cmd):
"""Encrypt a MongoDB command.
:Parameters:
- `database`: The database for this command.
- `cmd`: A MongoDB command as BSON.
:Returns:
The encrypted command.
"""
with self.mongocrypt.encryption_context(database, cmd) as ctx:
return run_state_machine(ctx, self.callback)
def decrypt(self, value):
"""Decrypts a BSON value.
:Parameters:
- `value`: The encoded document to decrypt, which must be in the
form { "v" : encrypted BSON value }}.
:Returns:
The decrypted BSON value.
"""
with self.mongocrypt.explicit_decryption_context(value) as ctx:
return run_state_machine(ctx, self.callback)
def create_data_key(self, kms_provider, master_key=None,
key_alt_names=None):
"""Creates a data key used for explicit encryption.
:Parameters:
- `kms_provider`: The KMS provider to use. Supported values are
"aws" and "local".
- `master_key`: 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. If the `kms_provider` is "aws"
it is required and has the following fields::
- `region` (string): Required. The AWS region, e.g. "us-east-1".
- `key` (string): Required. The Amazon Resource Name (ARN) to
the AWS customer.
- `endpoint` (string): Optional. An alternate host to send KMS
requests to. May include port number, e.g.
"kms.us-east-1.amazonaws.com:443".
- `key_alt_names` (optional): An optional list of string alternate
names used to reference a key. If a key is created with alternate
names, then encryption may refer to the key by the unique
alternate name instead of by ``_id``.
:Returns:
The _id of the created data key document.
"""
# CDRIVER-3275 each key_alt_name needs to be wrapped in a bson
# document.
encoded_names = []
if key_alt_names is not None:
for name in key_alt_names:
encoded_names.append(
self.callback.bson_encode({'keyAltName': name}))
opts = DataKeyOpts(master_key, encoded_names)
with self.mongocrypt.data_key_context(kms_provider, opts) as ctx:
key = run_state_machine(ctx, self.callback)
return self.callback.insert_data_key(key)