libmongocrypt-helper 1.7.4.0.1002 → 1.11.0.0.1001

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

@@ -0,0 +1,265 @@
+from pymongocrypt.compat import unicode_type
+
+
+class MongoCryptOptions:
+    def __init__(
+        self,
+        kms_providers,
+        schema_map=None,
+        encrypted_fields_map=None,
+        bypass_query_analysis=False,
+        crypt_shared_lib_path=None,
+        crypt_shared_lib_required=False,
+        bypass_encryption=False,
+    ):
+        """Options for :class:`MongoCrypt`.
+
+        :Parameters:
+          - `kms_providers`: Map of KMS provider options. The kms_providers
+            map values differ by provider:
+              - `aws`: Map with "accessKeyId" and "secretAccessKey" as strings,
+                 and optionally a "sessionToken" for temporary credentials.
+              - `azure`: Map with "clientId" and "clientSecret" as strings.
+              - `gcp`: Map with "email" as a string and "privateKey" as
+                a byte array or a base64-encoded string.
+              - `kmip`: Map with "endpoint" as a string.
+              - `local`: Map with "key" as a 96-byte array or the equivalent
+                base64-encoded string.
+
+            KMS providers may be specified with an optional name suffix
+            separated by a colon, for example "kmip:name". Named KMS providers
+            do not support automatic credential lookup.
+          - `schema_map`: Optional map of collection namespace ("db.coll") to
+            JSON Schema.  By default, a collection's JSONSchema is periodically
+            polled with the listCollections command. But a JSONSchema may be
+            specified locally with the schemaMap option.
+
+            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.
+
+            Schemas supplied in the schemaMap only apply to configuring
+            automatic encryption for client side encryption. Other validation
+            rules in the JSON schema will not be enforced by the driver and
+            will result in an error.
+          - `encrypted_fields_map`: Optional map encoded to BSON `bytes`.
+          - `bypass_query_analysis`: If ``True``, disable automatic analysis of
+            outgoing commands. Set `bypass_query_analysis` to use explicit
+            encryption on indexed fields without the MongoDB Enterprise Advanced
+            licensed crypt_shared library.
+          - `crypt_shared_lib_path`: Optional string path to the crypt_shared
+            library.
+          - `crypt_shared_lib_required`: Whether to require a crypt_shared
+            library.
+          - `bypass_encryption`: Whether to bypass encryption.
+
+        .. versionremoved:: 1.11
+           Removed the ``enable_range_v2`` parameter.
+
+        .. versionadded:: 1.10
+           Added the ``enable_range_v2`` parameter.
+
+        .. versionadded:: 1.3
+           Added the ``crypt_shared_lib_path``, ``crypt_shared_lib_path``, and
+           ``bypass_encryption`` parameters.
+
+        .. versionadded:: 1.1
+           Support for "azure" and "gcp" kms_providers.
+           Support for temporary AWS credentials via "sessionToken".
+
+        .. versionchanged:: 1.1
+           For kmsProvider "local", the "key" field can now be specified
+           as either a 96-byte array or the equivalent base64-encoded string.
+        """
+        if not isinstance(kms_providers, dict):
+            raise ValueError("kms_providers must be a dict")
+        if not kms_providers:
+            raise ValueError("at least one KMS provider must be configured")
+
+        for name, provider in kms_providers.items():
+            # Account for provider names like "local:myname".
+            provider_type = name.split(":")[0]
+            if provider_type in ("aws", "gcp", "azure", "kmip", "local"):
+                if not isinstance(provider, dict):
+                    raise ValueError(f"kms_providers[{name!r}] must be a dict")
+            if provider_type == "aws":
+                if len(provider):
+                    if (
+                        "accessKeyId" not in provider
+                        or "secretAccessKey" not in provider
+                    ):
+                        raise ValueError(
+                            f"kms_providers[{name!r}] must contain "
+                            "'accessKeyId' and 'secretAccessKey'"
+                        )
+            elif provider_type == "azure":
+                if len(provider):
+                    if "clientId" not in provider or "clientSecret" not in provider:
+                        raise ValueError(
+                            f"kms_providers[{name!r}] must contain "
+                            "'clientId' and 'clientSecret'"
+                        )
+            elif provider_type == "gcp":
+                if len(provider):
+                    if "email" not in provider or "privateKey" not in provider:
+                        raise ValueError(
+                            f"kms_providers[{name!r}] must contain "
+                            "'email' and 'privateKey'"
+                        )
+                    if not isinstance(provider["privateKey"], (bytes, unicode_type)):
+                        raise TypeError(
+                            f"kms_providers[{name!r}]['privateKey'] must "
+                            "be an instance of bytes or str"
+                        )
+            elif provider_type == "kmip":
+                if "endpoint" not in provider:
+                    raise ValueError(f"kms_providers[{name!r}] must contain 'endpoint'")
+                if not isinstance(provider["endpoint"], (str, unicode_type)):
+                    raise TypeError(
+                        f"kms_providers[{name!r}]['endpoint'] must "
+                        "be an instance of str"
+                    )
+            elif provider_type == "local":
+                if "key" not in provider:
+                    raise ValueError(f"kms_providers[{name!r}] must contain 'key'")
+                if not isinstance(provider["key"], (bytes, unicode_type)):
+                    raise TypeError(
+                        f"kms_providers[{name!r}]['key'] must be an "
+                        "instance of bytes or str"
+                    )
+
+        if schema_map is not None and not isinstance(schema_map, bytes):
+            raise TypeError("schema_map must be bytes or None")
+
+        if encrypted_fields_map is not None and not isinstance(
+            encrypted_fields_map, bytes
+        ):
+            raise TypeError("encrypted_fields_map must be bytes or None")
+
+        self.kms_providers = kms_providers
+        self.schema_map = schema_map
+        self.encrypted_fields_map = encrypted_fields_map
+        self.bypass_query_analysis = bypass_query_analysis
+        self.crypt_shared_lib_path = crypt_shared_lib_path
+        self.crypt_shared_lib_required = crypt_shared_lib_required
+        self.bypass_encryption = bypass_encryption
+
+
+class ExplicitEncryptOpts:
+    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 "range" 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(
+                    f"query_type must be str or None, not: {type(query_type)}"
+                )
+        self.query_type = query_type
+        if contention_factor is not None and not isinstance(contention_factor, int):
+            raise TypeError(
+                f"contention_factor must be an int or None, not: {type(contention_factor)}"
+            )
+        self.contention_factor = contention_factor
+        if range_opts is not None and not isinstance(range_opts, bytes):
+            raise TypeError(
+                f"range_opts must be an bytes or None, not: {type(range_opts)}"
+            )
+        self.range_opts = range_opts
+        self.is_expression = is_expression
+
+
+class DataKeyOpts:
+    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

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

@@ -12,145 +12,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from abc import abstractmethod
+# Alias file for import compatibility
 
-from pymongocrypt.binding import lib
-from pymongocrypt.compat import ABC
-from pymongocrypt.errors import MongoCryptError
-
-
-class MongoCryptCallback(ABC):
-    """Callback ABC to perform I/O on behalf of libbmongocrypt."""
-
-    @abstractmethod
-    def kms_request(self, kms_context):
-        """Complete a KMS request.
-
-        :Parameters:
-          - `kms_context`: A :class:`MongoCryptKmsContext`.
-
-        :Returns:
-          None
-        """
-        pass
-
-    @abstractmethod
-    def collection_info(self, database, filter):
-        """Get the collection info for a namespace.
-
-        The returned collection info is passed to libmongocrypt which reads
-        the JSON schema.
-
-        :Parameters:
-          - `database`: The database on which to run listCollections.
-          - `filter`: The filter to pass to listCollections.
-
-        :Returns:
-          The first document from the listCollections command response as BSON.
-        """
-        pass
-
-    @abstractmethod
-    def mark_command(self, database, cmd):
-        """Mark a command for encryption.
-
-        :Parameters:
-          - `database`: The database on which to run this command.
-          - `cmd`: The BSON command to run.
-
-        :Returns:
-          The marked command response from mongocryptd.
-        """
-        pass
-
-    @abstractmethod
-    def fetch_keys(self, filter):
-        """Yields one or more keys from the key vault.
-
-        :Parameters:
-          - `filter`: The filter to pass to find.
-
-        :Returns:
-          A generator which yields the requested keys from the key vault.
-        """
-        pass
-
-    @abstractmethod
-    def insert_data_key(self, data_key):
-        """Insert a data key into the key vault.
-
-        :Parameters:
-          - `data_key`: The data key document to insert.
-
-        :Returns:
-          The _id of the inserted data key document.
-        """
-        pass
-
-    @abstractmethod
-    def bson_encode(self, doc):
-        """Encode a document to BSON.
-
-        A document can be any mapping type (like :class:`dict`).
-
-        :Parameters:
-          - `doc`: mapping type representing a document
-
-        :Returns:
-          The encoded BSON bytes.
-        """
-        pass
-
-    @abstractmethod
-    def close(self):
-        """Release resources."""
-        pass
-
-
-def run_state_machine(ctx, callback):
-    """Run the libmongocrypt state machine until completion.
-
-    :Parameters:
-      - `ctx`: A :class:`MongoCryptContext`.
-      - `callback`: A :class:`MongoCryptCallback`.
-
-    :Returns:
-      The completed libmongocrypt operation.
-    """
-    while True:
-        state = ctx.state
-        # Check for terminal states first.
-        if state == lib.MONGOCRYPT_CTX_ERROR:
-            ctx._raise_from_status()
-        elif state == lib.MONGOCRYPT_CTX_READY:
-            return ctx.finish()
-        elif state == lib.MONGOCRYPT_CTX_DONE:
-            return None
-
-        if state == lib.MONGOCRYPT_CTX_NEED_MONGO_COLLINFO:
-            list_colls_filter = ctx.mongo_operation()
-            coll_info = callback.collection_info(
-                ctx.database, list_colls_filter)
-            if coll_info:
-                ctx.add_mongo_operation_result(coll_info)
-            ctx.complete_mongo_operation()
-        elif state == lib.MONGOCRYPT_CTX_NEED_MONGO_MARKINGS:
-            mongocryptd_cmd = ctx.mongo_operation()
-            result = callback.mark_command(ctx.database, mongocryptd_cmd)
-            ctx.add_mongo_operation_result(result)
-            ctx.complete_mongo_operation()
-        elif state == lib.MONGOCRYPT_CTX_NEED_MONGO_KEYS:
-            key_filter = ctx.mongo_operation()
-            for key in callback.fetch_keys(key_filter):
-                ctx.add_mongo_operation_result(key)
-            ctx.complete_mongo_operation()
-        elif state == lib.MONGOCRYPT_CTX_NEED_KMS:
-            for kms_ctx in ctx.kms_contexts():
-                with kms_ctx:
-                    callback.kms_request(kms_ctx)
-            ctx.complete_kms()
-        elif state == lib.MONGOCRYPT_CTX_NEED_KMS_CREDENTIALS:
-            creds = ctx.ask_for_kms_credentials()
-            ctx.provide_kms_providers(callback.bson_encode(creds))
-        else:
-            raise MongoCryptError('unknown state: %r' % (state,))
+from pymongocrypt.synchronous.state_machine import *

data/ext/libmongocrypt/libmongocrypt/bindings/python/pymongocrypt/synchronous/auto_encrypter.py

@@ -0,0 +1,61 @@
+# Copyright 2024-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.synchronous.state_machine import run_state_machine
+
+
+class AutoEncrypter:
+    def __init__(self, callback, mongo_crypt_opts):
+        """Encrypts and decrypts MongoDB commands.
+
+        This class is used by a driver to support automatic encryption and
+        decryption of MongoDB commands.
+
+        :Parameters:
+          - `callback`: A :class:`MongoCryptCallback`.
+          - `mongo_crypt_opts`: A :class:`MongoCryptOptions`.
+        """
+        self.callback = callback
+        self.mongocrypt = MongoCrypt(mongo_crypt_opts, 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, 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 close(self):
+        """Cleanup resources."""
+        self.mongocrypt.close()
+        self.callback.close()

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

@@ -0,0 +1,156 @@
+# Copyright 2024-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, timezone
+
+try:
+    from pymongo_auth_aws.auth import aws_temp_credentials
+
+    _HAVE_AUTH_AWS = True
+except ImportError:
+    _HAVE_AUTH_AWS = False
+
+import httpx
+
+from pymongocrypt.errors import MongoCryptError
+
+_azure_creds = namedtuple("_azure_creds", ["access_token", "expires_utc"])
+_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"}
+    client = httpx.Client()
+    try:
+        response = client.get(url, headers=headers)
+    except Exception as e:
+        msg = "unable to retrieve GCP credentials: %s" % e
+        raise MongoCryptError(msg) from e
+    finally:
+        client.close()
+
+    if response.status_code != 200:
+        msg = f"Unable to retrieve GCP credentials: expected StatusCode 200, got StatusCode: {response.status_code}. Response body:\n{response.content}"
+        raise MongoCryptError(msg)
+    try:
+        data = response.json()
+    except Exception as e:
+        raise MongoCryptError(
+            f"unable to retrieve GCP credentials: error reading response body\n{response.content}"
+        ) from e
+
+    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_utc - datetime.now(tz=timezone.utc) < 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"}
+    client = httpx.Client()
+    try:
+        response = client.get(url, headers=headers)
+    except Exception as e:
+        msg = "Failed to acquire IMDS access token: %s" % e
+        raise MongoCryptError(msg) from e
+    finally:
+        client.close()
+
+    if response.status_code != 200:
+        msg = "Failed to acquire IMDS access token."
+        raise MongoCryptError(msg)
+    try:
+        data = response.json()
+    except Exception as e:
+        raise MongoCryptError("Azure IMDS response must be in JSON format.") from e
+
+    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 as e:
+        raise MongoCryptError(
+            'Azure IMDS response must contain "expires_in" integer, but was %s.'
+            % response.content
+        ) from e
+
+    expires_utc = datetime.now(tz=timezone.utc) + timedelta(seconds=expires_in)
+    _azure_creds_cache = _azure_creds(data["access_token"], expires_utc)
+    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