In MongoDB, how does automatic encryption differ from explicit encryption, which editions run each, and what do crypt_shared and mongocryptd do?
answer
- who decides which fields to encrypt
- Community gets one of the two
- query analysis, not cryptography
- a library replaces a process
basics
~20 sAutomatic encryption has the driver encrypt fields from a schema and needs Enterprise or Atlas; explicit encryption has your code encrypt each value and also runs on Community. crypt_shared, or mongocryptd which 9.0 deprecates, only analyses commands.
solid answer
~40 sWith automatic encryption, you give the client a schema and it encrypts and decrypts in normal reads and writes. That needs MongoDB Enterprise or Atlas. With explicit encryption, your code calls `ClientEncryption.encrypt` for each value, naming the key and algorithm, and it works on Community too, as does automatic decryption. Automatic mode needs a query analysis component to mark what to encrypt and to reject unsupported operations. `crypt_shared` is a dynamic library loaded in-process; `mongocryptd` is a separate process the driver spawns, deprecated in MongoDB 9.0. Neither touches keys or performs encryption; `libmongocrypt` does that. By default a driver tries `crypt_shared` and falls back to spawning `mongocryptd`, while `cryptSharedLibRequired: true` turns a missing library into an error.
code
javascript · 11 lines// Node.js driver 7.8: fail at start-up instead of falling back to mongocryptd
const client = new MongoClient(uri, {
autoEncryption: {
keyVaultNamespace: "encryption.__keyVault",
kmsProviders,
extraOptions: {
cryptSharedLibPath: "/opt/mongodb/lib/mongo_crypt_v1.so",
cryptSharedLibRequired: true
}
}
})go deeper
Recall that automatic mode uses a schema and explicit mode uses encrypt calls in your code. Remember Community can run explicit encryption and automatic decryption, but not automatic encryption.
Explain what query analysis does and does not do, how crypt_shared differs from mongocryptd, and the order in which a driver tries them.
Set cryptSharedLibRequired so a packaging error fails loudly. Ship a local schema so a tampered server cannot unmark a field, and name the explicit-mode failures that query analysis would have caught.
Choose a fleet standard for mode and edition. Weigh the licence requirement of automatic mode against the review burden of explicit calls spread across services, and plan the move off mongocryptd before it becomes urgent.
## Two ways to encrypt Both CSFLE and Queryable Encryption offer the same two modes. **Automatic encryption** puts the rules in configuration. You give the client a schema, and the driver finds the fields to encrypt in each command. Application code stays ordinary `find` and `insert` calls, which is why the manual recommends it in most situations. **Explicit encryption** puts the rules in code. You create a `ClientEncryption` object and call `encrypt` for every value, naming the data key, the algorithm and its parameters, on writes and on query values alike. It gives finer control at the cost of logic spread through the application. ## Which edition runs which | Product | Automatic encryption | Explicit encryption | Automatic decryption | |---|---|---|---| | MongoDB Atlas | Yes | Yes | Yes | | MongoDB Enterprise Advanced | Yes | Yes | Yes | | MongoDB Community Edition | No | Yes | Yes | Decryption needs no schema, because the ciphertext carries the ID of its data key and its algorithm. So a client that encrypts by hand can still decrypt automatically: - On CSFLE, you set `bypassAutoEncryption: true`, which disables automatic encryption and keeps automatic decryption. - On Queryable Encryption with Community Server, you set `bypassQueryAnalysis: true`. The minimum server versions differ: 4.2 for CSFLE and 7.0 for Queryable Encryption, each on a replica set or sharded cluster and not a standalone. ## Query analysis Automatic mode must parse every command before it leaves the process, to decide which values to encrypt and to refuse what cannot work on ciphertext. A **query analysis component** does this. | | `crypt_shared` | `mongocryptd` | |---|---|---| | Form | Dynamic library, `mongo_crypt_v1` | Separate local process | | Lifecycle | Loaded by `libmongocrypt` | Spawned by the driver; shuts itself down when idle | | Status in 9.0 | Recommended | Deprecated | | Where it comes from | Enterprise download | Installed with Enterprise Server | Both do the same limited job: - read the encryption schema - mark the fields to encrypt in each command - block unsupported operations on encrypted fields Neither encrypts or decrypts, and neither accesses key material. The difference is packaging: `crypt_shared` runs inside your process and listens for nothing, while the driver connects to `mongocryptd` as a local server, by default at `mongodb://localhost:27020`. The cryptography lives in **`libmongocrypt`**, the Apache-licensed library the drivers and `mongosh` use. It coordinates fetching data keys from the vault and calling the KMS, and it encrypts and decrypts values. Keeping these roles apart matters when something breaks: a missing library is a query analysis problem, while a KMS error is a key access problem. ## How a driver picks The driver specification and the manual describe this order: 1. The driver tries to load `crypt_shared`, from its search path or the `cryptSharedLibPath` you give. 2. If that fails and `cryptSharedLibRequired` is `false`, its default, the driver tries to spawn and connect to `mongocryptd`. 3. If `cryptSharedLibRequired` is `true`, the driver refuses to continue and never connects to `mongocryptd`. A path that fails to load is a hard error. `mongocryptdBypassSpawn`, `bypassAutoEncryption` and `bypassQueryAnalysis` each stop the driver from spawning the process. On MongoDB 9.0, the sensible setting is `cryptSharedLibRequired: true`, so a packaging mistake fails at start-up and never falls back to a deprecated process. In `mongosh`, pass `--cryptSharedLibPath`; prefix, suffix and substring queries there need `crypt_shared` 9.0 or later. On 8.0, `mongocryptd` is not yet deprecated. ## Traps in each mode **Automatic mode trusts its schema source.** Without a local `schemaMap` (CSFLE) or `encryptedFieldsMap` (Queryable Encryption) entry for a collection, the client downloads the remote schema. Nothing verifies that schema's integrity, so a compromised server could unmark a field and the client would then send plaintext. Prefer a local schema. Automatic encryption also applies only to collection-level operations, errors on a database or view, and requires the `listCollections` privilege action for the authenticated user. **Explicit mode trusts your code.** A forgotten `encrypt` call on a CSFLE field sends plaintext unless a server-side schema rejects it, and no query analysis stops an operator that makes no sense on ciphertext. A range comparison on deterministic `BinData` can succeed and return wrong results. For Queryable Encryption, the `Indexed`, `Range` and `String` algorithms also need the contention factor and their parameters on every call, and the collection must have been created with `encryptedFields`.
- Can a Community Server application still search an encrypted field?Yes, with explicit encryption. It encrypts the query value itself with `ClientEncryption`, using a deterministic algorithm for CSFLE, or `Indexed`, `Range` or `String` with a matching `queryType` for Queryable Encryption, and with `bypassQueryAnalysis` on the client. What it loses is the driver finding fields and rejecting unsupported operations for it.
- Why does a client without a local schema count as a security risk?It downloads the collection's schema from the server to decide what to encrypt, and neither scheme can verify that schema's integrity. Someone who compromises the server could remove a field's encryption marking, and the client would send that field as plaintext. A local `schemaMap` or `encryptedFieldsMap` prevents this.
- crypt_shared encrypts the values and needs access to the data keys.
- MongoDB Community Server cannot use client-side encryption at all.
- Automatic decryption is an Enterprise feature, just as automatic encryption is.
- mongocryptd must run next to mongod on the database server.
- With no local schema configured, automatic encryption leaves the client safe from a tampered server.
Assumes MongoDB 9.0, which deprecates mongocryptd in favour of crypt_shared; on 8.0 mongocryptd is not yet deprecated.