Install and Configure a Queryable Encryption Library
MongoDB uses one of two libraries for translating queries into encrypted queries, and for encrypting and decrypting data. The latest is the Automatic Encryption Shared Library.
Before You Start
Follow the preceding tasks to install a Queryable Encryption compatible driver and dependencies before continuing.
Choose a Library
Automatic Encryption Shared Library
The Automatic Encryption Shared Library is a dynamic library that enables your client application to perform automatic encryption. A dynamic library is a set of functionality accessed by an application at runtime rather than compile time. The Automatic Encryption Shared Library performs the following tasks:
Reads the encryption schema to determine which fields to encrypt or decrypt
Prevents your application from executing unsupported operations on encrypted fields
The Automatic Encryption Shared Library does not do any of the following:
Perform data encryption or decryption
Access the encryption key material
Listen for data over the network
The Automatic Encryption Shared Library is a preferred alternative to mongocryptd
and doesn't require you to start another process to perform automatic encryption.
mongocryptd
Important
Use the Automatic Encryption Shared Library
If you are starting a new project, use the Automatic Encryption Shared Library. The
Automatic Encryption Shared Library replaces mongocryptd
and does not require
you to start a new process.
mongocryptd
is installed with MongoDB Enterprise
Server.
When you create a MongoDB client with In-Use Encryption, 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 decryptionmongocryptd
doesn't access any encryption key materialmongocryptd
doesn't listen over the network
To perform field encryption and automatic decryption, the drivers use the Apache-licensed libmongocrypt library.
Procedure
To download the Automatic Encryption Shared Library from the MongoDB Download Center, select the version and platform, then the library.
Tip
To view an expanded list of available releases and packages, see MongoDB Enterprise Downloads.
In the Version dropdown, select 7.0.0 (current)
.
In the Platform dropdown, select your platform.
In the Package dropdown, select crypt_shared
.
Click Download.
To configure how your driver searches for the Automatic Encryption Shared Library, use the following parameters:
Name | Description |
---|---|
cryptSharedLibPath | Specifies the absolute path to the Automatic Encryption Shared Library
package, Default: |
cryptSharedLibRequired | Specifies if the driver must use the Automatic Encryption Shared Library. If
Default: |
To view an example demonstrating how to configure these parameters, see the Quick Start.
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.
Configure the library:
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.
Examples
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'])
Next Steps
After installing a library, create a Customer Master Key in your Key Management System of choice.