libmongocrypt-helper 1.7.0.0.1001 → 1.7.4.0.1000

data/ext/libmongocrypt/libmongocrypt/bindings/python/pymongocrypt/compat.py

@@ -0,0 +1,61 @@
+# Copyright 2019-present MongoDB, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Utility functions and definitions for Python compatibility."""
+
+import base64
+import sys
+
+PY3 = sys.version_info[0] == 3
+
+if PY3:
+    from abc import ABC
+    unicode_type = str
+else:
+    from abc import ABCMeta as _ABCMeta
+    ABC = _ABCMeta('ABC', (object,), {})
+    unicode_type = unicode
+
+
+def str_to_bytes(string):
+    """Convert a str (or unicode) to bytes."""
+    if isinstance(string, bytes):
+        return string
+    return string.encode('utf-8')
+
+
+def safe_bytearray_or_base64(data):
+    """Convert the given value to a type that, when BSON-encoded can be safely
+    passed to libmongocrypt functions that expect a BSON document containing
+    BSON Binary data or a base64-encoded string.
+
+    pymongo.bson encodes bytes to BSON string in Python 2, while the
+    libmongocrypt API expects BSON Binary or a base64 encoded string.
+    To avoid needing to import bson.Binary, we return a base64 encoded string
+    when using Python 2.
+    """
+    # On Python 3 byte-arrays are encoded as BSON Binary and
+    # base64 encoded strings can be passed as-is.
+    if PY3:
+        return data
+
+    # On Python 2 unicode literals are assumed to contain base64-encoded
+    # strings that can be passed to libmongocrypt as-is.
+    if isinstance(data, unicode_type):
+        return data
+
+    # On Python 2, all other types are assumed to contain raw bytes.
+    # To avoid importing bson.binary.Binary, we convert these to
+    # base64 strings.
+    return unicode_type(base64.b64encode(data))

data/ext/libmongocrypt/libmongocrypt/bindings/python/pymongocrypt/credentials.py

@@ -0,0 +1,136 @@
+# Copyright 2022-present MongoDB, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+import os
+from collections import namedtuple
+from datetime import datetime, timedelta
+
+try:
+    from pymongo_auth_aws.auth import aws_temp_credentials
+    _HAVE_AUTH_AWS = True
+except ImportError:
+    _HAVE_AUTH_AWS = False
+
+from pymongocrypt.errors import MongoCryptError
+
+import requests
+
+
+_azure_creds = namedtuple("_azure_creds", ["access_token", "expires_in"])
+_azure_creds_cache = None
+
+
+def _get_gcp_credentials():
+    """Get on-demand GCP credentials"""
+    metadata_host = os.getenv("GCE_METADATA_HOST") or "metadata.google.internal"
+    url = "http://%s/computeMetadata/v1/instance/service-accounts/default/token" % metadata_host
+
+    headers = {"Metadata-Flavor": "Google"}
+    try:
+        response = requests.get(url, headers=headers)
+    except Exception as e:
+        msg = "unable to retrieve GCP credentials: %s" % e
+        raise MongoCryptError(msg)
+
+    if response.status_code != 200:
+        msg = "Unable to retrieve GCP credentials: expected StatusCode 200, got StatusCode: %s. Response body:\n%s" % (response.status_code, response.content)
+        raise MongoCryptError(msg)
+    try:
+        data = response.json()
+    except Exception:
+        raise MongoCryptError("unable to retrieve GCP credentials: error reading response body\n%s" % response.content)
+
+    if not data.get("access_token"):
+        msg = "unable to retrieve GCP credentials: got unexpected empty accessToken from GCP Metadata Server. Response body: %s" % response.content
+        raise MongoCryptError(msg)
+
+    return {'accessToken': data['access_token']}
+
+
+def _get_azure_credentials():
+    """Get on-demand Azure credentials"""
+    global _azure_creds_cache
+    # Credentials are considered expired when: Expiration - now < 1 mins.
+    creds = _azure_creds_cache
+    if creds:
+        if creds.expires_in - datetime.utcnow() < timedelta(seconds=60):
+            _azure_creds_cache = None
+        else:
+            return { 'accessToken': creds.access_token }
+
+    url = "http://169.254.169.254/metadata/identity/oauth2/token"
+    url += "?api-version=2018-02-01"
+    url += "&resource=https://vault.azure.net"
+    headers = { "Metadata": "true", "Accept": "application/json" }
+    try:
+        response = requests.get(url, headers=headers)
+    except Exception as e:
+        msg = "Failed to acquire IMDS access token: %s" % e
+        raise MongoCryptError(msg)
+
+    if response.status_code != 200:
+        msg = "Failed to acquire IMDS access token."
+        raise MongoCryptError(msg)
+    try:
+        data = response.json()
+    except Exception:
+        raise MongoCryptError("Azure IMDS response must be in JSON format.")
+
+    for key in ["access_token", "expires_in"]:
+        if not data.get(key):
+            msg = "Azure IMDS response must contain %s, but was %s."
+            msg = msg % (key, response.content)
+            raise MongoCryptError(msg)
+
+    try:
+        expires_in = int(data["expires_in"])
+    except ValueError:
+        raise MongoCryptError('Azure IMDS response must contain "expires_in" integer, but was %s.' % response.content)
+
+    expiration_time = datetime.utcnow() + timedelta(seconds=expires_in)
+    _azure_creds_cache = _azure_creds(data['access_token'], expiration_time)
+    return { 'accessToken': data['access_token'] }
+
+
+def _ask_for_kms_credentials(kms_providers):
+    """Get on-demand kms credentials.
+
+    This is a separate function so it can be overridden in unit tests."""
+    global _azure_creds_cache
+    on_demand_aws = 'aws' in kms_providers and not len(kms_providers['aws'])
+    on_demand_gcp = 'gcp' in kms_providers and not len(kms_providers['gcp'])
+    on_demand_azure = 'azure' in kms_providers and not len(kms_providers['azure'])
+
+    if not any([on_demand_aws, on_demand_gcp, on_demand_azure]):
+        return {}
+    creds = {}
+    if on_demand_aws:
+        if not _HAVE_AUTH_AWS:
+            raise RuntimeError(
+                "On-demand AWS credentials require pymongo-auth-aws: "
+                "install with: python -m pip install 'pymongo[aws]'"
+            )
+        aws_creds = aws_temp_credentials()
+        creds_dict = {"accessKeyId": aws_creds.username, "secretAccessKey": aws_creds.password}
+        if aws_creds.token:
+            creds_dict["sessionToken"] = aws_creds.token
+        creds['aws'] = creds_dict
+    if on_demand_gcp:
+        creds['gcp'] = _get_gcp_credentials()
+    if on_demand_azure:
+        try:
+            creds['azure'] = _get_azure_credentials()
+        except Exception:
+            _azure_creds_cache = None
+            raise
+    return creds

data/ext/libmongocrypt/libmongocrypt/bindings/python/pymongocrypt/crypto.py

@@ -0,0 +1,162 @@
+# Copyright 2019-present MongoDB, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Internal crypto callbacks for libmongocrypt."""
+
+import os
+import traceback
+
+from cryptography.hazmat.backends import default_backend
+from cryptography.hazmat.primitives.asymmetric import padding
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+from cryptography.hazmat.primitives.hashes import Hash, SHA256, SHA512
+from cryptography.hazmat.primitives.hmac import HMAC
+from cryptography.hazmat.primitives.serialization import load_der_private_key
+
+from pymongocrypt.binary import _to_bytes, _write_bytes
+from pymongocrypt.binding import ffi, lib
+from pymongocrypt.compat import str_to_bytes
+
+
+def _callback_error_handler(exception, exc_value, tb):
+    """Set the mongocrypt_status_t on error."""
+    # From cffi docs: "First check if traceback is not None (it is None e.g.
+    # if the whole function ran successfully but there was an error converting
+    # the value returned: this occurs after the call)."
+    if tb is not None:
+        status = tb.tb_frame.f_locals['status']
+        msg = str_to_bytes(''.join(traceback.format_exception(
+            exception, exc_value, tb)))
+        lib.mongocrypt_status_set(
+            status, lib.MONGOCRYPT_STATUS_ERROR_CLIENT, 1, msg, -1)
+
+    return False
+
+
+def _aes_256_encrypt(key, mode, input, output, bytes_written):
+    cipher = Cipher(algorithms.AES(_to_bytes(key)), mode,
+                    backend=default_backend())
+    encryptor = cipher.encryptor()
+    data = encryptor.update(_to_bytes(input)) + encryptor.finalize()
+    _write_bytes(output, data)
+    bytes_written[0] = len(data)
+
+
+def _aes_256_decrypt(key, mode, input, output, bytes_written):
+    cipher = Cipher(algorithms.AES(_to_bytes(key)), mode,
+                    backend=default_backend())
+    decryptor = cipher.decryptor()
+    data = decryptor.update(_to_bytes(input)) + decryptor.finalize()
+    _write_bytes(output, data)
+    bytes_written[0] = len(data)
+
+
+@ffi.callback(
+    "bool(void *, mongocrypt_binary_t *, mongocrypt_binary_t *,"
+    "     mongocrypt_binary_t *, mongocrypt_binary_t *, uint32_t *,"
+    "     mongocrypt_status_t *)",
+    onerror=_callback_error_handler)
+def aes_256_cbc_encrypt(ctx, key, iv, input, output, bytes_written, status):
+    # Note that libmongocrypt pads the input before calling this method.
+    _aes_256_encrypt(key, modes.CBC(_to_bytes(iv)), input, output, bytes_written)
+    return True
+
+
+@ffi.callback(
+    "bool(void *, mongocrypt_binary_t *, mongocrypt_binary_t *,"
+    "     mongocrypt_binary_t *, mongocrypt_binary_t *, uint32_t *,"
+    "     mongocrypt_status_t *)",
+    onerror=_callback_error_handler)
+def aes_256_cbc_decrypt(ctx, key, iv, input, output, bytes_written, status):
+    # Note that libmongocrypt pads the input before calling this method.
+    _aes_256_decrypt(key, modes.CBC(_to_bytes(iv)), input, output, bytes_written)
+    return True
+
+
+@ffi.callback(
+    "bool(void *, mongocrypt_binary_t *, mongocrypt_binary_t *,"
+    "     mongocrypt_binary_t *, mongocrypt_binary_t *, uint32_t *,"
+    "     mongocrypt_status_t *)",
+    onerror=_callback_error_handler)
+def aes_256_ctr_encrypt(ctx, key, iv, input, output, bytes_written, status):
+    _aes_256_encrypt(key, modes.CTR(_to_bytes(iv)), input, output, bytes_written)
+    return True
+
+
+@ffi.callback(
+    "bool(void *, mongocrypt_binary_t *, mongocrypt_binary_t *,"
+    "     mongocrypt_binary_t *, mongocrypt_binary_t *, uint32_t *,"
+    "     mongocrypt_status_t *)",
+    onerror=_callback_error_handler)
+def aes_256_ctr_decrypt(ctx, key, iv, input, output, bytes_written, status):
+    _aes_256_decrypt(key, modes.CTR(_to_bytes(iv)), input, output, bytes_written)
+    return True
+
+
+@ffi.callback(
+    "bool(void *, mongocrypt_binary_t *, mongocrypt_binary_t *, "
+    "     mongocrypt_binary_t *, mongocrypt_status_t *)",
+    onerror=_callback_error_handler)
+def hmac_sha_256(ctx, key, input, output, status):
+    h = HMAC(_to_bytes(key), SHA256(), backend=default_backend())
+    h.update(_to_bytes(input))
+    data = h.finalize()
+    _write_bytes(output, data)
+    return True
+
+
+@ffi.callback(
+    "bool(void *, mongocrypt_binary_t *, mongocrypt_binary_t *, "
+    "     mongocrypt_binary_t *, mongocrypt_status_t *)",
+    onerror=_callback_error_handler)
+def hmac_sha_512(ctx, key, input, output, status):
+    h = HMAC(_to_bytes(key), SHA512(), backend=default_backend())
+    h.update(_to_bytes(input))
+    data = h.finalize()
+    _write_bytes(output, data)
+    return True
+
+
+@ffi.callback(
+    "bool(void *, mongocrypt_binary_t *, mongocrypt_binary_t *, "
+    "     mongocrypt_status_t *)",
+    onerror=_callback_error_handler)
+def sha_256(ctx, input, output, status):
+    digest = Hash(SHA256(), backend=default_backend())
+    digest.update(_to_bytes(input))
+    data = digest.finalize()
+    _write_bytes(output, data)
+    return True
+
+
+@ffi.callback(
+    "bool(void *, mongocrypt_binary_t *, uint32_t, mongocrypt_status_t *)",
+    onerror=_callback_error_handler)
+def secure_random(ctx, output, count, status):
+    data = os.urandom(int(count))
+    _write_bytes(output, data)
+    return True
+
+
+@ffi.callback(
+    "bool(void *, mongocrypt_binary_t *, mongocrypt_binary_t *, "
+    "     mongocrypt_binary_t *, mongocrypt_status_t *)",
+    onerror=_callback_error_handler)
+def sign_rsaes_pkcs1_v1_5(ctx, key, input, output, status):
+    rsa_private_key = load_der_private_key(
+        _to_bytes(key), password=None, backend=default_backend())
+    signature = rsa_private_key.sign(
+        _to_bytes(input), padding=padding.PKCS1v15(), algorithm=SHA256())
+    _write_bytes(output, signature)
+    return True

data/ext/libmongocrypt/libmongocrypt/bindings/python/pymongocrypt/errors.py

@@ -0,0 +1,39 @@
+# Copyright 2019-present MongoDB, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from pymongocrypt.binding import ffi, lib, _to_string
+
+
+class MongoCryptError(Exception):
+    def __init__(self, msg, code=-1):
+        """Top level Exception for all MongoCrypt errors.
+
+        :Parameters:
+          - `msg`: An error message.
+          - `code`: The mongocrypt_status_t code.
+        """
+        super(MongoCryptError, self).__init__(msg)
+        self.code = code
+
+    @classmethod
+    def from_status(cls, status):
+        """Constructs an error from a mongocrypt_status_t.
+
+        :Parameters:
+          - `status`: A CFFI mongocrypt_status_t.
+        """
+        if lib.mongocrypt_status_ok(status):
+            raise ValueError("status must not be ok")
+        msg = _to_string(lib.mongocrypt_status_message(status, ffi.NULL))
+        return cls(msg, lib.mongocrypt_status_code(status))

data/ext/libmongocrypt/libmongocrypt/bindings/python/pymongocrypt/explicit_encrypter.py

@@ -0,0 +1,248 @@
+# Copyright 2019-present MongoDB, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from pymongocrypt.mongocrypt import MongoCrypt
+from pymongocrypt.state_machine import run_state_machine
+
+
+class ExplicitEncryptOpts(object):
+    def __init__(self, algorithm, key_id=None, key_alt_name=None,
+                 query_type=None, contention_factor=None, range_opts=None,
+                 is_expression=False):
+        """Options for explicit encryption.
+
+        :Parameters:
+          - `algorithm` (str): The algorithm to use.
+          - `key_id`: The data key _id.
+          - `key_alt_name` (bytes): Identifies a key vault document by
+            'keyAltName'. Must be BSON encoded document in the form:
+            { "keyAltName" : (BSON UTF8 value) }
+          - `query_type` (str): The query type to execute.
+          - `contention_factor` (int): The contention factor to use
+            when the algorithm is "Indexed".
+          - `range_opts` (bytes): Options for explicit encryption
+            with the "rangePreview" algorithm encoded as a BSON document.
+          - `is_expression` (boolean): True if this is an encryptExpression()
+            context. Defaults to False.
+
+        .. versionchanged:: 1.3
+           Added the `query_type` and `contention_factor` parameters.
+        .. versionchanged:: 1.5
+           Added the `range_opts` and `is_expression` parameters.
+        """
+        self.algorithm = algorithm
+        self.key_id = key_id
+        self.key_alt_name = key_alt_name
+        if query_type is not None:
+            if not isinstance(query_type, str):
+                raise TypeError(
+                    'query_type must be str or None, not: %r' % (type(query_type),))
+        self.query_type = query_type
+        if contention_factor is not None and not isinstance(contention_factor, int):
+            raise TypeError(
+                'contention_factor must be an int or None, not: %r' % (type(contention_factor),))
+        self.contention_factor = contention_factor
+        if range_opts is not None and not isinstance(range_opts, bytes):
+            raise TypeError(
+                'range_opts must be an bytes or None, not: %r' % (type(contention_factor),))
+        self.range_opts = range_opts
+        self.is_expression = is_expression
+
+
+class DataKeyOpts(object):
+    def __init__(self, master_key=None, key_alt_names=None, key_material=None):
+        """Options for creating encryption keys.
+
+        :Parameters:
+          - `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".
+
+            If the `kms_provider` is "azure" it is required and has the
+            following fields::
+
+              - `keyVaultEndpoint` (string): Required. Host with optional
+                 port, e.g. "example.vault.azure.net".
+              - `keyName` (string): Required. Key name in the key vault.
+              - `keyVersion` (string): Optional. Version of the key to use.
+
+            If the `kms_provider` is "gcp" it is required and has the
+            following fields::
+
+              - `projectId` (string): Required. The Google cloud project ID.
+              - `location` (string): Required. The GCP location, e.g. "us-east1".
+              - `keyRing` (string): Required. Name of the key ring that contains
+                the key to use.
+              - `keyName` (string): Required. Name of the key to use.
+              - `keyVersion` (string): Optional. Version of the key to use.
+              - `endpoint` (string): Optional. Host with optional port.
+                Defaults to "cloudkms.googleapis.com".
+
+            If the `kms_provider` is "kmip" it is optional and has the
+            following fields::
+
+              - `keyId` (string): Optional. `keyId` is the KMIP Unique
+                Identifier to a 96 byte KMIP Secret Data managed object. If
+                keyId is omitted, the driver creates a random 96 byte KMIP
+                Secret Data managed object.
+              - `endpoint` (string): Optional. Host with optional
+                 port, e.g. "example.vault.azure.net:".
+
+          - `key_alt_names`: An optional list of bytes suitable to be passed to
+            mongocrypt_ctx_setopt_key_alt_name. Each element must be BSON
+            encoded document in the form: { "keyAltName" : (BSON UTF8 value) }
+
+          - `key_material`: An optional binary value of 96 bytes to use as
+            custom key material for the data key being created. If
+            ``key_material`` is given, the custom key material is used for
+            encrypting and decrypting data. Otherwise, the key material for the
+            new data key is generated from a cryptographically secure random
+            device.
+        """
+        self.master_key = master_key
+        self.key_alt_names = key_alt_names
+        self.key_material = key_material
+
+
+class ExplicitEncrypter(object):
+    def __init__(self, callback, mongo_crypt_opts):
+        """Encrypts and decrypts BSON values.
+
+        This class is used by a driver to support explicit encryption and
+        decryption of individual fields in a BSON document.
+
+        :Parameters:
+          - `callback`: A :class:`MongoCryptCallback`.
+          - `mongo_crypt_opts`: A :class:`MongoCryptOptions`.
+        """
+        self.callback = callback
+        if mongo_crypt_opts.schema_map is not None:
+            raise ValueError("mongo_crypt_opts.schema_map must be None")
+        self.mongocrypt = MongoCrypt(mongo_crypt_opts, callback)
+
+    def create_data_key(self, kms_provider, master_key=None,
+                        key_alt_names=None, key_material=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 class:`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``.
+          - `key_material`: (optional) See class:`DataKeyOpts`.
+
+        :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}))
+
+        if key_material is not None:
+            key_material = self.callback.bson_encode({'keyMaterial': key_material})
+
+        opts = DataKeyOpts(master_key, encoded_names, key_material)
+        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 rewrap_many_data_key(self, filter, provider=None, master_key=None):
+        """Decrypts and encrypts all matching data keys with a possibly new `master_key` value.
+
+        :Parameters:
+          - `filter`: A document used to filter the data keys.
+          - `provider`: (optional) The name of a different kms provider.
+          - `master_key`: Optional document for the given provider.
+
+        :Returns:
+          A binary document with the rewrap data.
+        """
+        with self.mongocrypt.rewrap_many_data_key_context(filter, provider, master_key) as ctx:
+            return run_state_machine(ctx, self.callback)
+
+    def encrypt(self, value, algorithm, key_id=None, key_alt_name=None,
+                query_type=None, contention_factor=None, range_opts=None,
+                is_expression=False):
+        """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'.
+          - `query_type` (str): The query type to execute.
+          - `contention_factor` (int): The contention factor to use
+            when the algorithm is "Indexed".
+          - `range_opts` (bytes): Options for explicit encryption
+            with the "rangePreview" algorithm encoded as a BSON document.
+          - `is_expression` (boolean): True if this is an encryptExpression()
+            context. Defaults to False.
+
+        :Returns:
+          The encrypted BSON value.
+
+        .. versionchanged:: 1.3
+           Added the `query_type` and `contention_factor` parameters.
+        .. versionchanged:: 1.5
+           Added the `range_opts` and `is_expression` parameters.
+        """
+        # 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, query_type, contention_factor,
+            range_opts, is_expression)
+        with self.mongocrypt.explicit_encryption_context(value, opts) 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 close(self):
+        """Cleanup resources."""
+        self.mongocrypt.close()