Mongoose 8.15.0 has been released, which adds support for the industry-leading encryption solutions available from MongoDB. With this update, it’s simpler than ever to create documents leveraging MongoDB Queryable Encryption (QE) and Client-Side Level Field Encryption (CSFLE), keeping your data secure when it is in use. Read on to learn more about approaches to encrypting your data when building with MongoDB and Mongoose.
What is Mongoose?
Mongoose is a library that enables elegant object modeling for Node.js applications working with MongoDB. Similar to an Object-Relational Mapper (ORM), the Mongoose Object Document Mapper (ODM) simplifies programmatic data interaction through schemas and models. It allows developers to define data structures with validation and provides a rich API for CRUD operations, abstracting away many of the complexities of the underlying MongoDB driver. This integration enhances productivity by enabling developers to work with JavaScript objects instead of raw database queries, making it easier to manage data relationships and enforce data integrity.
What is QE and CSFLE?
Securing sensitive data is paramount. It must be protected at every stage—whether in transit, at rest, or in use. However, implementing in-use encryption can be complex. MongoDB offers two approaches to make it easier: Queryable Encryption (QE) and Client-Side Level Field Encryption (CSFLE). QE allows customers to encrypt sensitive application data, store it securely in an encrypted state in the MongoDB database, and perform equality and range queries directly on the encrypted data.
An industry-first innovation, QE eliminates the need for costly custom encryption solutions, complex third-party tools, or specialized cryptography knowledge. It employs a unique structured encryption schema, developed by the MongoDB Cryptography Research Group, that simplifies the encryption of sensitive data while enabling equality and range queries to be performed directly on data without having to decrypt it.
The data remains encrypted at all stages, with decryption occurring only on the client side. This architecture supports solidified strict access controls, where MongoDB and even an organization’s own database administrators (DBAs) don’t have access to sensitive data. This design enhances security by keeping the server unaware of the data it processes, further mitigating the risk of exposure and minimizing the potential for unauthorized access.
Adding QE/CSFLE auto-encryption support for Mongoose
The primary goal of the Mongoose integration with QE and CSFLE is to provide idiomatic support for automatic encryption, simplifying the process of creating encrypted models. With native support for QE and CSFLE, Mongoose allows developers to define encryption options directly within their schemas without the need for separate configurations. This first-class API enables developers to work within Mongoose without dropping down to the driver level, minimizing the need for significant code changes when adopting QE and CSFLE.
Mongoose streamlines configuration by automatically generating the encrypted field map. This ensures that encrypted fields align perfectly with the schema and simplifies the three-step process typically associated with encryption setup, shown below. Mongoose also keeps the schema and encrypted fields in sync, reducing the risk of mismatches.
Developers can easily declare fields with the encrypt property and configure encryption settings, using all field types and encryption schemes supported by QE and CSFLE. Additionally, users can manage their own encryption keys, enhancing control over their encryption processes. This comprehensive approach empowers developers to implement robust encryption effortlessly while maintaining operational efficiency.
Pre-integration experience
const kmsProviders = { 
 local: { key: Buffer.alloc(96)
};
const keyVaultNamespace = 'data.keys';
const extraOptions = {};
const encryptedDatabaseName = 'encrypted';
const uri = '<mongodb URI>';

const encryptedFieldsMap = {
 'encrypted.patent': {
 encryptedFields: EJSON.parse('<EJSON string containing encrypted fields, either output from manual creation or createEncryptedCollection>', { relaxed: false }),
 }
};

const autoEncryptionOptions = {
 keyVaultNamespace,
 kmsProviders,
 extraOptions,
 encryptedFieldsMap
};

const schema = new Schema({
 patientName: String,
 patientId: Number,
 field: String,
 patientRecord: {
 ssn: String,
 billing: String
 }
}, { collection: 'patent' });

const connection = await createConnection(uri, {
 dbName: encryptedDatabaseName,
 autoEncryption: autoEncryptionOptions,
 autoCreate: false, // If using createEncryptedCollection, this is false. If manually creating the keyIds for each field, this is true.
}).asPromise();
const PatentModel = connection.model('Patent', schema);

const result = await PatentModel.find({}).exec();
console.log(result);
This example demonstrates the manual configuration required to set up a Mongoose model for QE and CSFLE, requiring three different steps to:
-
Define an
encryptedFieldsMapto specify which fields to encrypt -
Configure
autoEncryptionOptionswith key management settings
Create a Mongoose connection that incorporates these options
This process can be cumbersome, as it requires explicit setup for encryption.
New experience with Mongoose 8.15.0
const schema = new Schema({
 patientName: String,
 patientId: Number,
 field: String,
 patientRecord: {
 ssn: {
 type: String,
 encrypt: {
 keyId: '<uuid string of key id>',
 queries: 'equality'
 }
 },
 billing: {
 type: String,
 encrypt: {
 keyId: '<uuid string of key id>',
 queries: 'equality'
 }
 },
 }
}, { encryptionType: 'queryableEncryption', collection: 'patent' });

const connection = mongoose.createConnection();

const PatentModel = connection.model('Patent', schema);

const keyVaultNamespace = 'client.encryption';
const kmsProviders = { local: { key: Buffer.alloc(96) };
const uri = '<mongodb URI>';
const keyVaultNamespace = 'data.keys';
const autoEncryptionOptions = {
 keyVaultNamespace, 
 kmsProviders,
 extraOptions: {}
};

await connection.openUri(uri, {
 autoEncryption: autoEncryptionOptions});

const result = await PatentModel.find({}).exec();
console.log(result);
This “after experience” example showcases how the integration of QE and CSFLE into Mongoose simplifies the encryption setup process. Instead of the previous three-step approach, developers can now define encryption directly within the schema.
In this implementation, fields like ssn and billing are marked with an encrypt property, allowing for straightforward configuration of encryption settings, including the keyId and query types. The connection to the database is established with a single call that includes the necessary auto-encryption options, eliminating the need for a separate encrypted fields map and complex configurations. This streamlined approach enables developers to work natively within Mongoose, enhancing usability and reducing setup complexity while maintaining robust encryption capabilities.
Learn more about QE/CSFLE for Mongoose
We’re excited for you to build secure applications with QE/CSFLE for Mongoose. Here are some resources to get started with:
-
Learn how to set up use Mongoose with MongoDB through our tutorial.
-
Check out our documentation to learn when to choose QE vs. CSFLE.
-
Read Mongoose CSFLE documentation.
Source: Read More
