# `encryption` – Client-Side Field Level Encryption

Support for explicit client-side field level encryption.

class pymongo.encryption.Algorithm(*values)

  An enum that defines the supported encryption algorithms.

  AEAD_AES_256_CBC_HMAC_SHA_512_Deterministic = 'AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic'

    AEAD_AES_256_CBC_HMAC_SHA_512_Deterministic.

  AEAD_AES_256_CBC_HMAC_SHA_512_Random = 'AEAD_AES_256_CBC_HMAC_SHA_512-Random'

    AEAD_AES_256_CBC_HMAC_SHA_512_Random.

  INDEXED = 'Indexed'

    Indexed.

    Added in version 4.2.

  RANGE = 'Range'

    Range.

    Added in version 4.9.

  RANGEPREVIEW = 'RangePreview'

    DEPRECATED - RangePreview.

    Note

    Support for RangePreview is deprecated. Use `Algorithm.RANGE` instead.

    Added in version 4.4.

  TEXTPREVIEW = 'TextPreview'

    BETA - TextPreview.

    Added in version 4.15.

  UNINDEXED = 'Unindexed'

    Unindexed.

    Added in version 4.2.

class pymongo.encryption.ClientEncryption(kms_providers, key_vault_namespace, key_vault_client, codec_options, kms_tls_options=None, key_expiration_ms=None)

  Explicit client-side field level encryption.

  The ClientEncryption class encapsulates explicit operations on a key vault collection that cannot be done directly on a MongoClient. Similar to configuring auto encryption on a MongoClient, it is constructed with a MongoClient (to a MongoDB cluster containing the key vault collection), KMS provider configuration, and keyVaultNamespace. It provides an API for explicitly encrypting and decrypting values, and creating data keys. It does not provide an API to query keys from the key vault collection, as this can be done directly on the MongoClient.

  See explicit client-side encryption for an example.

  Parameters:

    - kms_providers (Mapping[str, Any]) –

      Map of KMS provider options. The kms_providers map values differ by provider:

      > - aws: Map with “accessKeyId” and “secretAccessKey” as strings. These are the AWS access key ID and AWS secret access key used to generate KMS messages. An optional “sessionToken” may be included to support temporary AWS credentials.

      > - azure: Map with “tenantId”, “clientId”, and “clientSecret” as strings. Additionally, “identityPlatformEndpoint” may also be specified as a string (defaults to ‘login.microsoftonline.com’). These are the Azure Active Directory credentials used to generate Azure Key Vault messages.

      > - gcp: Map with “email” as a string and “privateKey” as bytes or a base64 encoded string. Additionally, “endpoint” may also be specified as a string (defaults to ‘oauth2.googleapis.com’). These are the credentials used to generate Google Cloud KMS messages.

      > - kmip: Map with “endpoint” as a host with required port. For example: `{"endpoint": "example.com:443"}`.

      > - local: Map with “key” as bytes (96 bytes in length) or a base64 encoded string which decodes to 96 bytes. “key” is the master key used to encrypt/decrypt data keys. This key should be generated and stored as securely as possible.

      KMS providers may be specified with an optional name suffix separated by a colon, for example “kmip:name” or “aws:name”. Named KMS providers do not support CSFLE on-demand credentials.

    - key_vault_namespace (str) – The namespace for the key vault collection. The key vault collection contains all data keys used for encryption and decryption. Data keys are stored as documents in this MongoDB collection. Data keys are protected with encryption by a KMS provider.

    - key_vault_client (MongoClient[_DocumentTypeArg]) – A MongoClient connected to a MongoDB cluster containing the key_vault_namespace collection.

    - codec_options (CodecOptions[_DocumentTypeArg]) – An instance of `CodecOptions` to use when encoding a value for encryption and decoding the decrypted BSON value. This should be the same CodecOptions instance configured on the MongoClient, Database, or Collection used to access application data.

    - kms_tls_options (Optional[Mapping[str, Any]]) –

      A map of KMS provider names to TLS options to use when creating secure connections to KMS providers. Accepts the same TLS options as `pymongo.mongo_client.MongoClient`. For example, to override the system default CA file:

          kms_tls_options={'kmip': {'tlsCAFile': certifi.where()}}

      Or to supply a client certificate:

          kms_tls_options={'kmip': {'tlsCertificateKeyFile': 'client.pem'}}

    - key_expiration_ms (Optional[int]) – The cache expiration time for data encryption keys. Defaults to `None` which defers to libmongocrypt’s default which is currently 60000. Set to 0 to disable key expiration.

  Changed in version 4.12: Added the key_expiration_ms parameter.

  Changed in version 4.0: Added the kms_tls_options parameter and the “kmip” KMS provider.

  Added in version 3.9.

  add_key_alt_name(id, key_alt_name)

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

    Parameters:

      - id (Binary) – The UUID of a key a which must be a `Binary` with subtype 4 ( `UUID_SUBTYPE`).

      - key_alt_name (str) – The key alternate name to add.

    Returns:

      The previous version of the key document.

    Return type:

      Any

    Added in version 4.2.

  close()

    Release resources.

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

        with ClientEncryption(...) as client_encryption:
            encrypted = client_encryption.encrypt(value, ...)
            decrypted = client_encryption.decrypt(encrypted)

    Return type:

      None

  create_data_key(kms_provider, master_key=None, key_alt_names=None, key_material=None)

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

    Parameters:

      - kms_provider (str) – The KMS provider to use. Supported values are “aws”, “azure”, “gcp”, “kmip”, “local”, or a named provider like “kmip:name”.

      - master_key (Mapping[str, Any] | None) –

        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 type 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 type 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 type 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 type 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:".
            - `delegated` (bool): Optional. If True (recommended), the
              KMIP server will perform encryption and decryption. If
              delegated is not provided, defaults to false.

      - key_alt_names (Sequence[str] | None) –

        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 `key_id`. The following example shows creating and referring to a data key by alternate name:

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

      - key_material (bytes | None) – Sets the custom key material to be used by the data key for encryption and decryption.

    Returns:

      The `_id` of the created data key document as a `Binary` with subtype `UUID_SUBTYPE`.

    Return type:

      Binary

    Changed in version 4.2: Added the key_material parameter.

  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 (Database[_DocumentTypeArg]) – the database to create the collection

      - name (str) – the name of the collection to create

      - encrypted_fields (Mapping[str, Any]) –

        Document that describes the encrypted fields for

          Queryable Encryption. The “keyId” may be set to `None` to auto-generate the data keys. For example:

        param kms_provider:

          the KMS provider to be used

        param 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.

        param kwargs:

          additional keyword arguments are the same as “create_collection”.

      - kms_provider (str | None)

      - master_key (Mapping[str, Any] | None)

      - kwargs (Any)

    Return type:

      tuple[Collection[_DocumentTypeArg], Mapping[str, Any]]

    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.

    Parameters:

      - database (Database[_DocumentTypeArg])

      - name (str)

      - encrypted_fields (Mapping[str, Any])

      - kms_provider (str | None)

      - master_key (Mapping[str, Any] | None)

      - kwargs (Any)

    Return type:

      tuple[Collection[_DocumentTypeArg], Mapping[str, Any]]

    Added in version 4.4.

  decrypt(value)

    Decrypt an encrypted value.

    Parameters:

      - (Binary) (value`) – The encrypted value, a `Binary` with subtype 6.

      - value (Binary)

    Returns:

      The decrypted BSON value.

    Return type:

      Any

  delete_key(id)

    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`).

      - id (Binary)

    Returns:

      The delete result.

    Return type:

      DeleteResult

    Added in version 4.2.

  encrypt(value, algorithm, key_id=None, key_alt_name=None, query_type=None, contention_factor=None, range_opts=None, text_opts=None)

    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 (Any) – The BSON value to encrypt.

      - (string) (algorithm`) – The encryption algorithm to use. See `Algorithm` for some valid options.

      - key_id (Binary | UUID | None) – Identifies a data key by `_id` which must be a `Binary` with subtype 4 ( `UUID_SUBTYPE`).

      - key_alt_name (str | None) – 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 (RangeOpts | None) – Index options for range queries. See `RangeOpts` for some valid options.

      - text_opts (TextOpts | None) – Index options for textPreview queries. See `TextOpts` for some valid options.

      - algorithm (str)

      - query_type (str | None)

      - contention_factor (int | None)

    Returns:

      The encrypted value, a `Binary` with subtype 6.

    Return type:

      Binary

    Changed in version 4.9: Added the text_opts parameter.

    Changed in version 4.9: Added the range_opts parameter.

    Changed in version 4.7: `key_id` can now be passed in as a `uuid.UUID`.

    Changed in version 4.2: Added the query_type and contention_factor parameters.

  encrypt_expression(expression, algorithm, key_id=None, key_alt_name=None, query_type=None, contention_factor=None, range_opts=None)

    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 (Mapping[str, Any]) – The BSON aggregate or match expression to encrypt.

      - (string) (algorithm`) – The encryption algorithm to use. See `Algorithm` for some valid options.

      - key_id (Binary | UUID | None) – Identifies a data key by `_id` which must be a `Binary` with subtype 4 ( `UUID_SUBTYPE`).

      - key_alt_name (str | None) – 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 (RangeOpts | None) – Index options for range queries. See `RangeOpts` for some valid options.

      - algorithm (str)

      - query_type (str | None)

      - contention_factor (int | None)

    Returns:

      The encrypted expression, a `RawBSONDocument`.

    Return type:

      RawBSONDocument

    Changed in version 4.9: Added the range_opts parameter.

    Changed in version 4.7: `key_id` can now be passed in as a `uuid.UUID`.

    Added in version 4.4.

  get_key(id)

    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`).

      - id (Binary)

    Returns:

      The key document.

    Return type:

      RawBSONDocument | None

    Added in version 4.2.

  get_key_by_alt_name(key_alt_name)

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

    Parameters:

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

    Returns:

      The key document.

    Return type:

      RawBSONDocument | None

    Added in version 4.2.

  get_keys()

    Get all of the data keys.

    Returns:

      An instance of `Cursor` over the data key documents.

    Return type:

      Cursor[RawBSONDocument]

    Added in version 4.2.

  remove_key_alt_name(id, key_alt_name)

    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 (Binary) – The UUID of a key a which must be a `Binary` with subtype 4 ( `UUID_SUBTYPE`).

      - key_alt_name (str) – The key alternate name to remove.

    Returns:

      Returns the previous version of the key document.

    Return type:

      RawBSONDocument | None

    Added in version 4.2.

  rewrap_many_data_key(filter, provider=None, master_key=None)

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

    Parameters:

      - filter (Mapping[str, Any]) – A document used to filter the data keys.

      - provider (str | None) – The new KMS provider to use to encrypt the data keys, or `None` to use the current KMS provider(s).

      - master_key (Mapping[str, Any] | None) – The master key fields corresponding to the new KMS provider when `provider` is not `None`.

    Returns:

      A `RewrapManyDataKeyResult`.

    Return type:

      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>"
                },
            },
        )

    Added in version 4.2.

class pymongo.encryption.QueryType(*values)

  An enum that defines the supported values for explicit encryption query_type.

  Added in version 4.2.

  EQUALITY = 'equality'

    Used to encrypt a value for an equality query.

  PREFIXPREVIEW = 'prefixPreview'

    BETA - Used to encrypt a value for a prefixPreview query.

    Added in version 4.15.

  RANGE = 'range'

    Used to encrypt a value for a range query.

    Added in version 4.9.

  RANGEPREVIEW = 'RangePreview'

    DEPRECATED - Used to encrypt a value for a rangePreview query.

    Note

    Support for RangePreview is deprecated. Use `QueryType.RANGE` instead.

    Added in version 4.4.

  SUBSTRINGPREVIEW = 'substringPreview'

    BETA - Used to encrypt a value for a substringPreview query.

    Added in version 4.15.

  SUFFIXPREVIEW = 'suffixPreview'

    BETA - Used to encrypt a value for a suffixPreview query.

    Added in version 4.15.

class pymongo.encryption.RewrapManyDataKeyResult(bulk_write_result=None)

  Result object returned by a `rewrap_many_data_key()` operation.

  Added in version 4.2.

  Parameters:

    bulk_write_result (Optional[BulkWriteResult])

  property bulk_write_result: BulkWriteResult | None

    The result of the bulk write operation used to update the key vault collection with one or more rewrapped data keys. If `rewrap_many_data_key()` does not find any matching keys to rewrap, no bulk write operation will be executed and this field will be `None`.