For AI agents: a documentation index is available at https://www.mongodb.com/pt-br/docs/llms.txt — markdown versions of all pages are available by appending .md to any URL path.

Best Practices for In-Use Encryption

Use these recommendations to harden production deployments that use Queryable Encryption or Client-Side Field Level Encryption (CSFLE).

Configure client-side schemas instead of relying on the remote schema from the server. Specify the encryptedFieldsMap option for Queryable Encryption or the schemaMap option for CSFLE in your client connection configuration. Client-side schemas catch the most common failure, where an application incorrectly sends a field in plaintext. For risks of remote schemas, see Security Considerations.

Queryable Encryption requires a server-side encryption schema by default. For CSFLE collections, you must configure server-side encryption schema enforcement. Server-side enforcement rejects any write where a protected field isn't encrypted. This is a second safeguard against a client sending plaintext writes. To learn how to configure server-side schema enforcement, see Schema Validation for Queryable Encryption or CSFLE Server-Side Field Level Encryption Enforcement for CSFLE.

Whenever possible, authenticate to your KMS with assumed roles and short-term session tokens instead of long-lived credentials. For example, on Amazon Web Services, use instance credentials rather than IAM user access keys. Drivers that support Queryable Encryption and CSFLE can fetch temporary AWS credentials automatically. If you must use long-lived KMS access keys, rotate them frequently.

To review credential management for your KMS, see Amazon Web Services KMS, Azure Key Vault, or Google Cloud Platform KMS.

Strictly separate the privileges of KMS key administrators from the KMS credentials that your application uses. Key administrators can create, revoke, and delete keys and manage KMS access policies. Grant your application a role that allows only encrypt and decrypt actions for the single Customer Master Key that it uses.

If you use MongoDB Atlas with a cloud KMS provider, enable audit logging for Customer Master Key usage. AWS KMS, Google Cloud KMS, and Azure Key Vault offer audit tooling, such as AWS CloudTrail. Monitor the logs, and consider adding key operations to the allowlist at the API level.

If you use a self-managed KMS, an HSM, or a KMIP server such as HashiCorp Vault, export key audit logs off the host. Store the logs in immutable storage and monitor them.

Take a full backup of your Key Vault collection before you rotate your Data Encryption Keys by rewrapping them with a new Customer Master Key.

To learn how to rotate keys, see Rotate and Rewrap Encryption Keys for Queryable Encryption or Encryption Key Management for CSFLE.

To learn about backup strategies, see Backup Methods for a Self-Managed Deployment.

Whenever possible, connect your Queryable Encryption or CSFLE-enabled application and your MongoDB Atlas cluster over private networks. Use VPC peering or a private endpoint rather than public internet.

To learn more, see the MongoDB Atlas documentation on VPC peering and private endpoints.

Keep a long-lived MongoClient per process or pod, rather than creating one per request or invocation. If your workload runs on AWS Lambda, initialize the client outside the handler so warm invocations can reuse it.

To learn more about connection management, see Connection Pool Overview.

Periodically audit your encrypted clusters to confirm that sensitive fields remain protected. Use centralized audit scripts that call db.getCollectionInfos() to query collection metadata across every database in one pass:

  • For Queryable Encryption collections, verify that the options.encryptedFields document still marks the expected fields for encryption.

  • For CSFLE collections, verify that the options.validator.$jsonSchema document still marks the expected fields with the encrypt keyword. To learn how to view a collection's validation rules, see View Existing Validation Rules.

If you run CSFLE on a self-managed deployment outside of a cloud provider, enable volume encryption on both the database host and the application host. On the application side, use a secrets manager, such as HashiCorp Vault, to manage access to key services. Do not use static or hard-coded access tokens in production applications.