encryption – Client side encryption

Support for explicit client side encryption.

Support for client side encryption is in beta. Backwards-breaking changesmay be made before the final release.

  • class pymongo.encryption.Algorithm
  • An enum that defines the supported encryption algorithms.
  • class pymongo.encryption.ClientEncryption(kms_providers, key_vault_namespace, key_vault_client, codec_options)
  • Explicit client side encryption.

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

Note

Support for client side encryption is in beta.Backwards-breaking changes may be made before the final release.

Parameters:

  • kms_providers: Map of KMS provider options. Two KMS providersare supported: “aws” and “local”. The kmsProviders map valuesdiffer by provider:
  • aws: Map with “accessKeyId” and “secretAccessKey” as strings.These are the AWS access key ID and AWS secret access key usedto generate KMS messages.
  • local: Map with “key” as a 96-byte array or string. “key”is the master key used to encrypt/decrypt data keys. This keyshould be generated and stored as securely as possible.

  • key_vault_namespace: The namespace for the key vault collection.The key vault collection contains all data keys used for encryptionand decryption. Data keys are stored as documents in this MongoDBcollection. Data keys are protected with encryption by a KMSprovider.

  • key_vault_client: A MongoClient connected to a MongoDB clustercontaining the key_vault_namespace collection.

  • codec_options: An instance ofCodecOptions to use when encoding avalue for encryption and decoding the decrypted BSON value.

New in version 3.9.

  • close()
  • Release resources.

Note that using this class in a with-statement will automatically callclose():

  1. with ClientEncryption(...) as client_encryption:
  2.     encrypted = client_encryption.encrypt(value, ...)
  3.     decrypted = client_encryption.decrypt(encrypted)
  • createdata_key(_kms_provider, master_key=None, key_alt_names=None)
  • Create and insert a new data key into the key vault collection.

Parameters:

  1. -

kms_provider: The KMS provider to use. Supported values are“aws” and “local”.

  1. -

master_key: The master_key identifies a KMS-specific key usedto encrypt the new data key. If the kmsProvider is “local” themaster_key is not applicable and may be omitted.If the kms_provider is “aws”, master_key is required and musthave the following fields:

  • region (string): The AWS region as a string.
  • key (string): The Amazon Resource Name (ARN) to the AWScustomer master key (CMK).
  1. -

key_alt_names (optional): An optional list of string alternatenames used to reference a key. If a key is created with alternatenames, then encryption may refer to the key by the unique alternatename instead of by key_id. The following example shows creatingand referring to a data key by alternate name:

  1. client_encryption.create_data_key("local", keyAltNames=["name1"])
  2. # reference the key with the alternate name
  3. client_encryption.encrypt("457-55-5462", keyAltName="name1",
  4.                           algorithm=Algorithm.Random)

Returns:The _id of the created data key document.

  • decrypt(value)
  • Decrypt an encrypted value.

Parameters:

  1. - _value_ (Binary): The encrypted value, a[<code>Binary</code>]($c99850b71a0da5ec.md#bson.binary.Binary) with subtype 6.Returns:

The decrypted BSON value.

  • encrypt(value, algorithm, key_id=None, key_alt_name=None)
  • Encrypt a BSON value with a given key and algorithm.

Note that exactly one of key_id or key_alt_name must beprovided.

Parameters:

  1. - _value_: The BSON value to encrypt.
  2. - _algorithm_ (string): The encryption algorithm to use. See[<code>Algorithm</code>](https://api.mongodb.com/python/current/api/pymongo/#pymongo.encryption.Algorithm) for some valid options.
  3. - _key_id_: Identifies a data key by <code>_id</code> which must be a[<code>Binary</code>]($c99850b71a0da5ec.md#bson.binary.Binary) with subtype 4 ([<code>UUID_SUBTYPE</code>]($c99850b71a0da5ec.md#bson.binary.UUID_SUBTYPE)).
  4. - _key_alt_name_: Identifies a key vault document by ‘keyAltName’.Returns:

The encrypted value, a Binary with subtype 6.