Package com.mongodb

Class AutoEncryptionSettings

java.lang.Object
com.mongodb.AutoEncryptionSettings
public final class AutoEncryptionSettings extends Object
The client-side automatic encryption settings. In-use encryption enables an application to specify what fields in a collection must be encrypted, and the driver automatically encrypts commands sent to MongoDB and decrypts responses.

Automatic encryption is an enterprise only feature that only applies to operations on a collection. Automatic encryption is not supported for operations on a database or view and will result in error. To bypass automatic encryption, set bypassAutoEncryption=true in AutoEncryptionSettings.

Explicit encryption/decryption and automatic decryption is a community feature, enabled with the new com.mongodb.client.vault.ClientEncryption type.

A MongoClient configured with bypassAutoEncryption=true will still automatically decrypt.

If automatic encryption fails on an operation, use a MongoClient configured with bypassAutoEncryption=true and use ClientEncryption#encrypt to manually encrypt values.

Enabling client side encryption reduces the maximum document and message size (using a maxBsonObjectSize of 2MiB and maxMessageSizeBytes of 6MB) and may have a negative performance impact.

Automatic encryption requires the authenticated user to have the listCollections privilege action.

Supplying an encryptedFieldsMap provides more security than relying on an encryptedFields obtained from the server. It protects against a malicious server advertising false encryptedFields.

Since:
3.11

  • Method Details

    • builder

      public static AutoEncryptionSettings.Builder builder()
      Convenience method to create a Builder.
      Returns:
      a builder

    • getKeyVaultMongoClientSettings

      @Nullable public MongoClientSettings getKeyVaultMongoClientSettings()
      Gets the key vault settings.

      The key vault collection is assumed to reside on the same MongoDB cluster as the encrypted collections. But the optional keyVaultMongoClientSettings can be used to route data key queries to a separate MongoDB cluster, or the same cluster but using a different credential.

      Returns:
      the key vault settings, which may be null to indicate that the same MongoClient should be used to access the key vault collection as is used for the rest of the application.

    • getKeyVaultNamespace

      public String getKeyVaultNamespace()
      Gets the key vault namespace.

      The key vault namespace refers to a collection that contains all data keys used for encryption and decryption (aka the key vault collection). Data keys are stored as documents in a special MongoDB collection. Data keys are protected with encryption by a KMS provider (AWS, Azure, GCP KMS or a local master key).

      Returns:
      the key vault namespace, which may not be null

    • getKmsProviders

      public Map<String,Map<String,Object>> getKmsProviders()
      Gets the map of KMS provider properties.

      Multiple KMS providers can be specified within this map. Each KMS provider is identified by a unique key. Keys are formatted as either "KMS provider type" or "KMS provider type:KMS provider name" (e.g., "aws" or "aws:myname"). The KMS provider name must only contain alphanumeric characters (a-z, A-Z, 0-9), underscores (_), and must not be empty.

      Supported KMS provider types include "aws", "azure", "gcp", and "local". The provider name is optional and allows for the configuration of multiple providers of the same type under different names (e.g., "aws:name1" and "aws:name2" could represent different AWS accounts).

      The kmsProviders map values differ by provider type. The following properties are supported for each provider type:

      For "aws", the properties are:

      • accessKeyId: a String, the AWS access key identifier
      • secretAccessKey: a String, the AWS secret access key
      • sessionToken: an optional String, the AWS session token

      For "azure", the properties are:

      • tenantId: a String, the tenantId that identifies the organization for the account.
      • clientId: a String, the clientId to authenticate a registered application.
      • clientSecret: a String, the client secret to authenticate a registered application.
      • identityPlatformEndpoint: optional String, a host with optional port. e.g. "example.com" or "example.com:443". Generally used for private Azure instances.

      For "gcp", the properties are:

      • email: a String, the service account email to authenticate.
      • privateKey: a String or byte[], the encoded PKCS#8 encrypted key
      • endpoint: optional String, a host with optional port. e.g. "example.com" or "example.com:443".

      For "kmip", the properties are:

      • endpoint: a String, the endpoint as a host with required port. e.g. "example.com:443".

      For "local", the properties are:

      • key: byte[] of length 96, the local key

      It is also permitted for the value of a kms provider to be an empty map, in which case the driver will first

      However, KMS providers containing a name (e.g., "aws:myname") do not support dynamically obtaining KMS properties from the Supplier or environment.
      Returns:
      map of KMS provider properties
      See Also:

    • getKmsProviderPropertySuppliers

      public Map<String,Supplier<Map<String,Object>>> getKmsProviderPropertySuppliers()
      This method is similar to getKmsProviders(), but instead of getting properties for KMS providers, it gets Suppliers of properties.

      If getKmsProviders() returns empty properties for a KMS provider, the driver will use a Supplier of properties configured for the KMS provider to obtain non-empty properties.

      Returns:
      A Map where keys identify KMS providers, and values specify Suppliers of properties for the KMS providers.
      Since:
      4.6

    • getKmsProviderSslContextMap

      public Map<String,SSLContext> getKmsProviderSslContextMap()
      Gets the KMS provider to SSLContext map.

      If a KMS provider is mapped to a non-null SSLContext, the context will be used to establish a TLS connection to the KMS. Otherwise, the default context will be used.

      Returns:
      the KMS provider to SSLContext map
      Since:
      4.4

    • getSchemaMap

      public Map<String,BsonDocument> getSchemaMap()
      Gets the map of namespace to local JSON schema.

      Automatic encryption is configured with an "encrypt" field in a collection's JSONSchema. By default, a collection's JSONSchema is periodically polled with the listCollections command. But a JSONSchema may be specified locally with the schemaMap option.

      The key into the map is the full namespace of the collection, which is &lt;database name>.&lt;collection name>. For example, if the database name is "test" and the collection name is "users", then the namesspace is "test.users".

      Supplying a schemaMap 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.

      Returns:
      map of namespace to local JSON schema

    • getExtraOptions

      public Map<String,Object> getExtraOptions()
      Gets the extra options that control the behavior of auto-encryption components.

      The extraOptions currently only relate to the mongocryptd process. The following options keys are supported:

      • mongocryptdURI: a String which defaults to "mongodb://%2Fvar%2Fmongocryptd.sock" if domain sockets are available or "mongodb://localhost:27020" otherwise.
      • mongocryptdBypassSpawn: a boolean which defaults to false. If true, the driver will not attempt to automatically spawn a mongocryptd process
      • mongocryptdSpawnPath: specifies the full path to the mongocryptd executable. By default the driver spawns mongocryptd from the system path.
      • mongocryptdSpawnArgs: Used to control the behavior of mongocryptd when the driver spawns it. By default, the driver spawns mongocryptd with the single command line argument "--idleShutdownTimeoutSecs=60"
      • cryptSharedLibPath: Optional, override the path used to load the crypt shared library. Note: All MongoClient objects in the same process should use the same setting for cryptSharedLibPath, as it is an error to load more that one crypt shared library simultaneously in a single operating system process.
      • cryptSharedLibRequired: boolean, if 'true', refuse to continue encryption without a crypt shared library.
      Returns:
      the extra options map

    • isBypassAutoEncryption

      public boolean isBypassAutoEncryption()
      Gets whether auto-encryption should be bypassed. Even when this option is true, auto-decryption is still enabled.

      This option is useful for cases where the driver throws an exception because it is unable to prove that the command does not contain any fields that should be automatically encrypted, but the application is able to determine that it does not. For these cases, the application can construct a MongoClient with AutoEncryptionSettings with bypassAutoEncryption enabled.

      Returns:
      true if auto-encryption should be bypassed

    • getEncryptedFieldsMap

      @Nullable public Map<String,BsonDocument> getEncryptedFieldsMap()
      Gets the mapping of a collection namespace to encryptedFields.

      Note: only applies to Queryable Encryption. Automatic encryption in Queryable Encryption is configured with the encryptedFields.

      If a collection is present in both the encryptedFieldsMap and schemaMap, the driver will error.

      If a collection is present on the encryptedFieldsMap, the behavior of collection.createCollection() and collection.drop() is altered.

      If a collection is not present on the encryptedFieldsMap a server-side collection encryptedFieldsMap may be used by the driver.

      Returns:
      the mapping of the collection namespaces to encryptedFields
      Since:
      4.7
      Since server release
      7.0

    • isBypassQueryAnalysis

      public boolean isBypassQueryAnalysis()
      Gets whether automatic analysis of outgoing commands is set.

      Set bypassQueryAnalysis to true to use explicit encryption on indexed fields without the MongoDB Enterprise Advanced licensed crypt shared library.

      Returns:
      true if query analysis should be bypassed
      Since:
      4.7
      Since server release
      7.0

    • toString

      public String toString()
      Overrides:
      toString in class Object