Docs Menu
Docs Home
/
MongoDB Manual
/ / / / /

Install and Configure mongocryptd for CSFLE

On this page

  • Overview
  • Installation
  • Configuration
  • Examples

Note

Enterprise Feature

The automatic feature of field level encryption is only available in MongoDB Enterprise 4.2 or later, and MongoDB Atlas 4.2 or later clusters.

mongocryptd is installed with MongoDB Enterprise Server.

When you create a CSFLE-enabled MongoDB client, the mongocryptd process starts automatically by default.

The mongocryptd process:

  • Uses the specified automatic encryption rules to mark fields in read and write operations for encryption.

  • Prevents unsupported operations from executing on encrypted fields.

  • Parses the encryption schema specified for the database connection. Automatic encryption rules use a strict subset of JSON schema syntax. If the rules contain invalid automatic encryption syntax or any document validation syntax, mongocryptd returns an error.

mongocryptd only performs the previous functions, and doesn't perform any of the following:

  • mongocryptd doesn't perform encryption or decryption

  • mongocryptd doesn't access any encryption key material

  • mongocryptd doesn't listen over the network

To perform field encryption and automatic decryption, the drivers use the Apache-licensed libmongocrypt library.

The official MongoDB drivers, mongosh, and the legacy mongo shell require access to the mongocryptd process on the client host machine. These clients search for the mongocryptd process in the system PATH by default.

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.

If the driver has access to the mongocryptd process, it spawns the process by default.

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.

To view examples of how to configure your mongocryptd process, click the tab corresponding to the driver you are using in your application:

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);

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

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);

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"]
}

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'])

Back

Shared Library