MongoClient Options for Queryable Encryption

On this page

Overview

Automatic Encryption Options

This version of the documentation is archived and no longer supported. View the current documentation to learn how to upgrade your version of MongoDB server.

Queryable Encryption with equality queries is generally available (GA) in MongoDB 7.0 and later. The Queryable Encryption Public Preview, released in version 6.0, is no longer supported. Data encrypted using the Public Preview is incompatible with the feature release. For more information, see Compatibility Changes in MongoDB 7.0.

Overview

On this page, you can learn about the Queryable Encryption-specific configuration options for MongoClient instances.

Automatic Encryption Options

The following table describes the structure of an AutoEncryptionOptions object:

Property	Data Type	Required?	Description
`keyVaultNamespace`	`String`	Yes	The full namespace of the Key Vault collection.
`kmsProviders`	`Object`	Yes	The Key Management System (KMS) used by Queryable Encryption for managing your Customer Master Keys (CMKs). To learn more about `kmsProviders` objects, see KMS Providers. To learn more about Customer Master Keys, see Keys and Key Vaults.
`bypassAutoEncryption`	`Boolean`	No	Specify `true` to bypass automatic encryption rules and perform explicit (manual) per-field encryption.
`bypassQueryAnalysis`	`Boolean`	No	Disables automatic analysis of outgoing commands. Specify `true` to use explicit encryption without the Automatic Encryption Shared Library.
`encryptedFieldsMap`	`Object`	No	A schema that specifies which fields to automatically encrypt and the types of queries allowed on those fields. To learn how to construct an encryption schema, see Field Encryption and Queryability.
`extraOptions`	`Object`	No	Configuration options for the encryption library. To use the Automatic Encryption Shared Library instead of `mongocryptd`, specify the full absolute or relative file path to the library file in the `cryptSharedLibPath` property of this object. If the driver can't load the Automatic Encryption Shared Library from this path, creating the `MongoClient` will fail.
`keyVaultClient`	`MongoClient`	No	Specifies the `MongoClient` that should connect to the MongoDB instance hosting your Key Vault collection. If you omit this option, the driver uses the current `MongoClient` instance. To learn more about Key Vault collections, see Key Vault Collections.
`tlsOptions`	`Object`	No	The TLS options to use when connecting to the KMS provider.

The following table describes the properties in an AutoEncryptionOptions object:

Property	Data Type	Required?	Description
`KeyVaultNamespace`	`CollectionNamespace`	Yes	The full namespace of the Key Vault collection.
`KmsProviders`	`IReadOnlyDictionary`	Yes	The Key Management System (KMS) used by Queryable Encryption for managing your Customer Master Keys (CMKs). To learn more about `KmsProviders` objects, see KMS Providers. To learn more about Customer Master Keys, see Keys and Key Vaults.
`BypassAutoEncryption`	`Boolean`	No	Specify `true` to bypass automatic encryption rules and perform explicit (manual) per-field encryption.
`BypassQueryAnalysis`	`Boolean`	No	Disables automatic analysis of outgoing commands. Set this property to `true` to use explicit encryption without the Automatic Encryption Shared Library.
`EncryptedFieldsMap`	`IReadOnlyDictionary`	No	A schema that specifies which fields to automatically encrypt and the types of queries allowed on those fields. To learn how to construct an encryption schema, see Field Encryption and Queryability.
`ExtraOptions`	`IReadOnlyDictionary`	No	Configuration options for the encryption library. To use the Automatic Encryption Shared Library instead of `mongocryptd`, specify the full absolute or relative file path to the library file in the `cryptSharedLibPath` property. If the driver can't load the Automatic Encryption Shared Library from this path, creating the `MongoClient` will fail.
`KeyVaultClient`	`IMongoClient`	No	Specifies the `MongoClient` that should connect to the MongoDB instance hosting your Key Vault collection. If you omit this option, the driver uses the current `MongoClient` instance. To learn more about Key Vault collections, see Key Vault Collections.
`TlsOptions`	`IReadOnlyDictionary`	No	The TLS options to use when connecting to the KMS provider.

Note

API Documentation

For more information on these automatic encryption options, see the API documentation for the AutoEncryptionOptions class.

The following table describes the options in an AutoEncryptionOptions object:

Option	Data Type	Required?	Description
`KeyVaultNamespace`	`String`	Yes	The full namespace of the Key Vault collection.
`KmsProviders`	`map[string]map[string]interface{}`	Yes	The Key Management System (KMS) used by Queryable Encryption for managing your Customer Master Keys (CMKs). To learn more about `KmsProviders` objects, see KMS Providers. To learn more about Customer Master Keys, see Keys and Key Vaults.
`BypassAutoEncryption`	`*bool`	No	Specify `true` to bypass automatic encryption rules and perform explicit (manual) per-field encryption.
`BypassQueryAnalysis`	`*bool`	No	Disables automatic analysis of outgoing commands. Specify `true` to use explicit encryption without the Automatic Encryption Shared Library.
`EncryptedFieldsMap`	`map[string]interface{}`	No	A schema that specifies which fields to automatically encrypt and the types of queries allowed on those fields. To learn how to construct an encryption schema, see Field Encryption and Queryability.
`ExtraOptions`	`map[string]interface{}`	No	Configuration options for the encryption library. To use the Automatic Encryption Shared Library instead of `mongocryptd`, specify the full absolute or relative file path to the library file in the `cryptSharedLibPath` property. If the driver can't load the Automatic Encryption Shared Library from this path, creating the `MongoClient` will fail.
`KeyVaultClientOptions`	`*ClientOptions`	No	Options for a new internal `mongo.Client` to connect to the MongoDB instance hosting your Key Vault collection. If you omit this option, the driver uses the current `MongoClient` instance. To learn more about Key Vault collections, see Key Vault Collections.
`TlsConfig`	`map[string]*tls.Config`	No	The TLS options to use when connecting to the KMS provider.

Note

API Documentation

For more information on these automatic encryption options, see the API documentation for the AutoEncryptionOptions type.

The following table describes the methods available on the AutoEncryptionSettings builder:

Method	Data Type	Required?	Description
`keyVaultNamespace`	`String`	Yes	The full namespace of the Key Vault collection.
`kmsProviders`	`Map`	Yes	The Key Management System (KMS) used by Queryable Encryption for managing your Customer Master Keys (CMKs). To learn more about `kmsProviders` objects, see KMS Providers. To learn more about Customer Master Keys, see Keys and Key Vaults.
`bypassAutoEncryption`	`Boolean`	No	Specify `true` to bypass automatic encryption rules and perform explicit (manual) per-field encryption.
`bypassQueryAnalysis`	`Boolean`	No	Disables automatic analysis of outgoing commands. Specify `true` to use explicit encryption without the Automatic Encryption Shared Library.
`encryptedFieldsMap`	`Map`	No	A schema that specifies which fields to automatically encrypt and the types of queries allowed on those fields. To learn how to construct an encryption schema, see Field Encryption and Queryability.
`extraOptions`	`Map`	No	Configuration options for the encryption library. To use the Automatic Encryption Shared Library instead of `mongocryptd`, specify the full absolute or relative file path to the library file in the `cryptSharedLibPath` property.
`keyVaultMongoClientSettings`	`MongoClientSettings`	No	Settings for a new `MongoClient` instance to connect to the MongoDB instance hosting your Key Vault collection. If you omit this option, the driver uses the current `MongoClient` instance. To learn more about Key Vault collections, see Key Vault Collections.
`kmsProviderPropertySuppliers`	`Map`	No	Similar to the `kmsProviders()` method, but configures a `Supplier` for each property instead.
`kmsProviderSslContextMap`	`Map`	No	The SSL context to use for authentication.

Note

API Documentation

For more information on these automatic encryption options, see the API documentation for the AutoEncryptionSettings.Builder class.

The following table describes the structure of an AutoEncryptionOptions object:

Property	Data Type	Required?	Description
`keyVaultNamespace`	`String`	Yes	The full namespace of the Key Vault collection.
`kmsProviders`	`Object`	Yes	The Key Management System (KMS) used by Queryable Encryption for managing your Customer Master Keys (CMKs). To learn more about `kmsProviders` objects, see KMS Providers. To learn more about Customer Master Keys, see Keys and Key Vaults.
`bypassAutoEncryption`	`Boolean`	No	Specify `true` to bypass automatic encryption rules and perform explicit (manual) per-field encryption.
`bypassQueryAnalysis`	`Boolean`	No	Disables automatic analysis of outgoing commands. Specify `true` to use explicit encryption without the Automatic Encryption Shared Library. Defaults to `false` if not specified.
`encryptedFieldsMap`	`Object`	No	A schema that specifies which fields to automatically encrypt and the types of queries allowed on those fields. To learn how to construct an encryption schema, see Field Encryption and Queryability.
`extraOptions`	`Object`	No	Configuration options for the encryption library. To use the Automatic Encryption Shared Library instead of `mongocryptd`, specify the full absolute or relative file path to the library file in the `cryptSharedLibPath` property of this object. If the driver can't load the Automatic Encryption Shared Library from this path, creating the `MongoClient` will fail.
`keyVaultClient`	`MongoClient`	No	Specifies the `MongoClient` that should connect to the MongoDB instance hosting your Key Vault collection. If you omit this option, the driver uses the current `MongoClient` instance. To learn more about Key Vault collections, see Key Vault Collections.
`tlsOptions`	`Object`	No	The TLS options to use when connecting to the KMS provider.

Note

API Documentation

For more information on these automatic encryption options, see the API documentation for the AutoEncryptionOptions interface.

The following table describes the parameters of the AutoEncryptionOpts class:

Parameter	Data Type	Required?	Description
`key_vault_namespace`	`String`	Yes	The full namespace of the Key Vault collection.
`kms_providers`	`Mapping[string, Any]`	Yes	The Key Management System (KMS) used by Queryable Encryption for managing your Customer Master Keys (CMKs). To learn more about `kms_Providers` maps, see KMS Providers. To learn more about Customer Master Keys, see Keys and Key Vaults.
`bypass_auto_encryption`	`Boolean`	No	Specify `True` to bypass automatic encryption rules and perform explicit (manual) per-field encryption.
`bypass_query_analysis`	`Boolean`	No	Disables automatic analysis of outgoing commands. Specify `True` to use explicit encryption without the Automatic Encryption Shared Library.
`encrypted_fields_map`	`Mapping`	No	A schema that specifies which fields to automatically encrypt and the types of queries allowed on those fields. To learn how to construct an encryption schema, see Field Encryption and Queryability.
`crypt_shared_lib_path`	`String`	No	Specify the full absolute or relative file path to the library file in the this parameter to use the Automatic Encryption Shared Library instead of `mongocryptd`, If the driver can't load the Automatic Encryption Shared Library from this path, it raises an error.
`crypt_shared_lib_required`	`Boolean`	No	If you specify `True`, the driver raises an error if `libmongocrypt` can't load the Automatic Encryption Shared Library.
`key_vault_client`	`MongoClient`	No	Specifies the `MongoClient` that should connect to the MongoDB instance hosting your Key Vault collection. If you omit this option, the driver uses the current `MongoClient` instance. To learn more about Key Vault collections, see Key Vault Collections.
`kms_tls_options`	`Mapping[string, Any]`	No	The TLS options to use when connecting to the KMS provider.
`mongocryptd_uri`	`String`	No	The MongoDB URI used to connect to the local `mongocryptd` process, if using `mongocryptd` for encryption.
`mongocryptd_bypass_spawn`	`Boolean`	No	If you specify `True` for this parameter, the encrypted `MongoClient` does not attempt to spawn the `mongocryptd` process, if using `mongocryptd` for encryption.
`mongocryptd_spawn_path`	`String`	No	Used for spawning the `mongocryptd` process, if using `mongocryptd` for encryption.
`mongocryptd_spawn_args`	`String`	No	A list of string arguments to use when spawning the `mongocryptd` process, if using `mongocryptd` for encryption.

Note

API Documentation

For more information on these automatic encryption options, see the API documentation for the AutoEncryptionOpts class.

Back

Supported Operations for Queryable Encryption

Automatic Encryption Shared Library for Queryable Encryption