For AI agents: a documentation index is available at https://www.mongodb.com/docs/llms.txt — markdown versions of all pages are available by appending .md to any URL path.
Docs Menu
Docs Home
/ /
Reference
Docs Home
/ /
Client-Side Field Level Encryption
/
Reference
Docs Home
/
Development
/
In-Use Encryption
/
Client-Side Field Level Encryption
/
Reference

Install and Configure a CSFLE Query Analysis Component

MongoDB uses the Automatic Encryption Shared Library (recommended) or the mongocryptd executable process to translate queries into encrypted queries, and to encrypt or decrypt data.

Before You Begin

To use CSFLE with automatic encryption, you must first choose the query analysis component you want MongoDB to use to encrypt the fields.

  • crypt_shared, the recommended CSFLE library.

  • mongocryptd, which is included in MongoDB Enterprise Server installations.

    Important

    mongocryptd is Deprecated

    Starting in MongoDB 9.0, mongocryptd is deprecated. Use the Automatic Encryption Shared Library instead.

The libmongocrypt library and MongoDB drivers require the Automatic Encryption Shared Library or mongocryptd to interpret encrypted queries. For more information, see Install libmongocrypt for CSFLE.

Steps

Select the query analysis component you want to use and follow the steps to install and configure a CSFLE query analysis component.

1

Download the Automatic Encryption Shared Library

Download the Automatic Encryption Shared Library from the MongoDB Download Center by selecting the version and platform, then the library:

  1. In the Version dropdown, select the version labeled as "current."

  2. In the Platform dropdown, select your platform.

  3. In the Package dropdown, select crypt_shared.

  4. Click Download.

Tip

To view an expanded list of available releases and packages, see MongoDB Enterprise Downloads.

2

Configure Automatic Encryption Shared Library

You can configure how your driver searches for the Automatic Encryption Shared Library through the following parameters:

Name
Description

cryptSharedLibPath

Specifies the absolute path to the Automatic Encryption Shared Library package, crypt_shared.

Default: undefined

cryptSharedLibRequired

Specifies if the driver must use the Automatic Encryption Shared Library. If true, the driver raises an error if the Automatic Encryption Shared Library is unavailable. If false, the driver performs the following sequence of actions:

  1. Attempts to use the Automatic Encryption Shared Library.

  2. If the Automatic Encryption Shared Library is unavailable, the driver attempts to spawn and connect to mongocryptd.

Default: false

To view an example demonstrating how to configure these parameters, see the Quick Start.

1

Install mongocryptd

For supported Linux Operating Systems: To install the Server package, follow the install on Linux tutorial and install the mongodb-enterprise server package. Alternatively, specify mongodb-enterprise-cryptd instead to install only the mongocryptd binary. The package manager installs the binaries to a location in the system PATH.

For OSX: To install the Server package, follow the install on MacOS tutorial. The package manager installs binaries to a location in the system PATH.

For Windows: To install the Server package, follow the install on Windows tutorial. You must add the mongocryptd package to your system PATH after installation. Follow the documented best practices for your Windows installation to add the mongocryptd binary to the system PATH.

To install from an official tarball / ZIP archive: To install from an official archive, follow the documented best practices for your operating system to add the mongocryptd binary to your system PATH.

2

Configure mongocryptd

If the driver has access to the mongocryptd process, it spawns the process by default. Your application must have write permissions on the working directory to create the mongocryptd.pid file.

Important

Start on Boot

If possible, start mongocryptd on boot, rather than launching it on demand.

Configure how the driver starts mongocryptd through the following parameters:

Name
Description

port

The port from which mongocryptd listens for messages.
Default: 27020

idleShutdownTimeoutSecs

Number of idle seconds the mongocryptd process waits before exiting.
Default: 60

mongocryptdURI

The URI on which to run the mongocryptd process.
Default: "mongodb://localhost:27020"

mongocryptdBypassSpawn

When true, prevents the driver from automatically spawning mongocryptd.
Default: false

mongocryptdSpawnPath

The full path to mongocryptd.
Default: Defaults to empty string and spawns from the system path.

If a mongocryptd process is already running on the port specified by the driver, the driver may log a warning and continue without spawning a new process. Any settings specified by the driver only apply once the existing process exits and a new encrypted client attempts to connect.

Example

The following code-snippet sets the listening port configuration of mongocryptd:

autoEncryption: {
  ...
  extraOptions: {
    mongocryptdSpawnArgs: ["--port", "30000"],
    mongocryptdURI: 'mongodb://localhost:30000',
  }

Note

In the NodeJS driver, the mongocryptdURI must match the listening port.

The following code-snippet sets the default timeout configuration of mongocryptd:

autoEncryption: {
  ...
  extraOptions: {
    mongocryptdSpawnArgs: ["--idleShutdownTimeoutSecs", "75"]
  }
1

Install mongocryptd

For supported Linux Operating Systems: To install the Server package, follow the install on Linux tutorial and install the mongodb-enterprise server package. Alternatively, specify mongodb-enterprise-cryptd instead to install only the mongocryptd binary. The package manager installs the binaries to a location in the system PATH.

For OSX: To install the Server package, follow the install on MacOS tutorial. The package manager installs binaries to a location in the system PATH.

For Windows: To install the Server package, follow the install on Windows tutorial. You must add the mongocryptd package to your system PATH after installation. Follow the documented best practices for your Windows installation to add the mongocryptd binary to the system PATH.

To install from an official tarball / ZIP archive: To install from an official archive, follow the documented best practices for your operating system to add the mongocryptd binary to your system PATH.

2

Configure mongocryptd

If the driver has access to the mongocryptd process, it spawns the process by default. Your application must have write permissions on the working directory to create the mongocryptd.pid file.

Important

Start on Boot

If possible, start mongocryptd on boot, rather than launching it on demand.

Configure how the driver starts mongocryptd through the following parameters:

Name
Description

port

The port from which mongocryptd listens for messages.
Default: 27020

idleShutdownTimeoutSecs

Number of idle seconds the mongocryptd process waits before exiting.
Default: 60

mongocryptdURI

The URI on which to run the mongocryptd process.
Default: "mongodb://localhost:27020"

mongocryptdBypassSpawn

When true, prevents the driver from automatically spawning mongocryptd.
Default: false

mongocryptdSpawnPath

The full path to mongocryptd.
Default: Defaults to empty string and spawns from the system path.

If a mongocryptd process is already running on the port specified by the driver, the driver may log a warning and continue without spawning a new process. Any settings specified by the driver only apply once the existing process exits and a new encrypted client attempts to connect.

Example

The following code-snippet sets the listening port configuration of mongocryptd:

List<String> spawnArgs = new ArrayList<String>();
spawnArgs.add("--port=30000");
Map<String, Object> extraOpts = new HashMap<String, Object>();
extraOpts.put("mongocryptdSpawnArgs", spawnArgs);
AutoEncryptionSettings autoEncryptionSettings = AutoEncryptionSettings.builder()
    ...
    .extraOptions(extraOpts);

The following code-snippet sets the default timeout configuration of mongocryptd:

List<String> spawnArgs = new ArrayList<String>();
spawnArgs.add("--idleShutdownTimeoutSecs")
    .add("60");
Map<String, Object> extraOpts = new HashMap<String, Object>();
extraOpts.put("mongocryptdSpawnArgs", spawnArgs);
AutoEncryptionSettings autoEncryptionSettings = AutoEncryptionSettings.builder()
    ...
    .extraOptions(extraOpts);
1

Install mongocryptd

For supported Linux Operating Systems: To install the Server package, follow the install on Linux tutorial and install the mongodb-enterprise server package. Alternatively, specify mongodb-enterprise-cryptd instead to install only the mongocryptd binary. The package manager installs the binaries to a location in the system PATH.

For OSX: To install the Server package, follow the install on MacOS tutorial. The package manager installs binaries to a location in the system PATH.

For Windows: To install the Server package, follow the install on Windows tutorial. You must add the mongocryptd package to your system PATH after installation. Follow the documented best practices for your Windows installation to add the mongocryptd binary to the system PATH.

To install from an official tarball / ZIP archive: To install from an official archive, follow the documented best practices for your operating system to add the mongocryptd binary to your system PATH.

2

Configure mongocryptd

If the driver has access to the mongocryptd process, it spawns the process by default. Your application must have write permissions on the working directory to create the mongocryptd.pid file.

Important

Start on Boot

If possible, start mongocryptd on boot, rather than launching it on demand.

Configure how the driver starts mongocryptd through the following parameters:

Name
Description

port

The port from which mongocryptd listens for messages.
Default: 27020

idleShutdownTimeoutSecs

Number of idle seconds the mongocryptd process waits before exiting.
Default: 60

mongocryptdURI

The URI on which to run the mongocryptd process.
Default: "mongodb://localhost:27020"

mongocryptdBypassSpawn

When true, prevents the driver from automatically spawning mongocryptd.
Default: false

mongocryptdSpawnPath

The full path to mongocryptd.
Default: Defaults to empty string and spawns from the system path.

If a mongocryptd process is already running on the port specified by the driver, the driver may log a warning and continue without spawning a new process. Any settings specified by the driver only apply once the existing process exits and a new encrypted client attempts to connect.

Example

The following code-snippet sets the listening port configuration of mongocryptd:

auto_encryption_opts = AutoEncryptionOpts(mongocryptd_spawn_args=['--port=30000'])

The following code-snippet sets the default timeout configuration of mongocryptd:

auto_encryption_opts = AutoEncryptionOpts(mongocryptd_spawn_args=['--idleShutdownTimeoutSecs=75'])
1

Install mongocryptd

For supported Linux Operating Systems: To install the Server package, follow the install on Linux tutorial and install the mongodb-enterprise server package. Alternatively, specify mongodb-enterprise-cryptd instead to install only the mongocryptd binary. The package manager installs the binaries to a location in the system PATH.

For OSX: To install the Server package, follow the install on MacOS tutorial. The package manager installs binaries to a location in the system PATH.

For Windows: To install the Server package, follow the install on Windows tutorial. You must add the mongocryptd package to your system PATH after installation. Follow the documented best practices for your Windows installation to add the mongocryptd binary to the system PATH.

To install from an official tarball / ZIP archive: To install from an official archive, follow the documented best practices for your operating system to add the mongocryptd binary to your system PATH.

2

Configure mongocryptd

If the driver has access to the mongocryptd process, it spawns the process by default. Your application must have write permissions on the working directory to create the mongocryptd.pid file.

Important

Start on Boot

If possible, start mongocryptd on boot, rather than launching it on demand.

Configure how the driver starts mongocryptd through the following parameters:

Name
Description

port

The port from which mongocryptd listens for messages.
Default: 27020

idleShutdownTimeoutSecs

Number of idle seconds the mongocryptd process waits before exiting.
Default: 60

mongocryptdURI

The URI on which to run the mongocryptd process.
Default: "mongodb://localhost:27020"

mongocryptdBypassSpawn

When true, prevents the driver from automatically spawning mongocryptd.
Default: false

mongocryptdSpawnPath

The full path to mongocryptd.
Default: Defaults to empty string and spawns from the system path.

If a mongocryptd process is already running on the port specified by the driver, the driver may log a warning and continue without spawning a new process. Any settings specified by the driver only apply once the existing process exits and a new encrypted client attempts to connect.

The following code-snippet sets the listening port configuration of mongocryptd:

var extraOptions = new Dictionary<string, object>()
{
    { "mongocryptdSpawnArgs", new [] { "--port=30000" } },
};
autoEncryptionOptions.With(extraOptions: extraOptions);

The following code-snippet sets the default timeout configuration of mongocryptd:

var extraOptions = new Dictionary<string, object>()
{
    { "idleShutdownTimeoutSecs", 60 },
};
autoEncryptionOptions.With(extraOptions: extraOptions);
1

Install mongocryptd

For supported Linux Operating Systems: To install the Server package, follow the install on Linux tutorial and install the mongodb-enterprise server package. Alternatively, specify mongodb-enterprise-cryptd instead to install only the mongocryptd binary. The package manager installs the binaries to a location in the system PATH.

For OSX: To install the Server package, follow the install on MacOS tutorial. The package manager installs binaries to a location in the system PATH.

For Windows: To install the Server package, follow the install on Windows tutorial. You must add the mongocryptd package to your system PATH after installation. Follow the documented best practices for your Windows installation to add the mongocryptd binary to the system PATH.

To install from an official tarball / ZIP archive: To install from an official archive, follow the documented best practices for your operating system to add the mongocryptd binary to your system PATH.

2

Configure mongocryptd

If the driver has access to the mongocryptd process, it spawns the process by default. Your application must have write permissions on the working directory to create the mongocryptd.pid file.

Important

Start on Boot

If possible, start mongocryptd on boot, rather than launching it on demand.

Configure how the driver starts mongocryptd through the following parameters:

Name
Description

port

The port from which mongocryptd listens for messages.
Default: 27020

idleShutdownTimeoutSecs

Number of idle seconds the mongocryptd process waits before exiting.
Default: 60

mongocryptdURI

The URI on which to run the mongocryptd process.
Default: "mongodb://localhost:27020"

mongocryptdBypassSpawn

When true, prevents the driver from automatically spawning mongocryptd.
Default: false

mongocryptdSpawnPath

The full path to mongocryptd.
Default: Defaults to empty string and spawns from the system path.

If a mongocryptd process is already running on the port specified by the driver, the driver may log a warning and continue without spawning a new process. Any settings specified by the driver only apply once the existing process exits and a new encrypted client attempts to connect.

The following code-snippet sets the listening port configuration of mongocryptd:

extraOptions := map[string]interface{}{
    "mongocryptdSpawnArgs": []string{
        "--port=30000",
    },
}

The following code-snippet sets the default timeout configuration of mongocryptd:

extraOptions := map[string]interface{}{
    "mongocryptdSpawnArgs": []string{
        "--idleShutdownTimeoutSecs=75",
    },
}
Back
How CSFLE Decrypts Documents
Next
Install libmongocrypt
Rate this page

On this page