ClientEncryption.createEncryptedCollection()

On this page

Syntax

Command Fields
Behavior
Example
Learn More

New in version 7.0.

ClientEncryption.createEncryptedCollection(dbName, collName, clientEncOpts): ClientEncryption.createEncryptedCollection creates an encrypted collection specified by collName on the database specified by dbName.

Syntax

ClientEncryption.createEncryptedCollection has the following syntax:

clientEncryption = db.getMongo().getClientEncryption()
clientEncryption.createEncryptedCollection(
  dbName,
  collName,
  {
    provider: kmsProviderName,
    createCollectionOptions: encryptedFieldsMap,
    masterKey: customerMasterKeyCredentials
  }
)

Command Fields

createEncryptedCollection takes these fields:

Field	Type	Necessity	Description
`dbName`	string	Required	Name of the database to encrypt.
`collName`	string	Required	Name of the collection to encrypt.
`clientEncOpts`	document	Required	Options to configure the encrypted collection.
`clientEncOpts.provider`	string	Required	KMS you are using to store your Customer Master Key.
`clientEncOpts.createCollectionOptions`	document	Required	Fields to encrypt. See Specify Fields for Encryption for details on how to configure the `encryptedFieldsMap` object.
`clientEncOpts.masterKey`	document	Optional	How to get the master key when the KMS Provider is AWS, GCP, or Azure.

Behavior

The mongosh client-side field level and queryable encryption methods require a database connection configured for client-side encryption. If the current database connection was not initiated with client-side field level encryption enabled, either:

Use the Mongo() constructor from the mongosh to establish a connection with the required client-side field level encryption options. The Mongo() method supports the following Key Management Service (KMS) providers for Customer Master Key (CMK) management:

Use the mongosh command line options to establish a connection with the required options. The command line options only support the Amazon Web Services KMS provider for CMK management.

Example

The following example uses a locally managed KMS for the queryable encryption configuration.

Create Your Encrypted Connection

Start mongosh

Start the mongosh client.

mongosh --nodb

Generate Your Key

To configure client-side field level encryption for a locally managed key, generate a base64-encoded 96-byte string with no line breaks.

const TEST_LOCAL_KEY = require("crypto").randomBytes(96).toString("base64")

Create the Client-Side Field Level Encryption Options

Create the client-side field level encryption options using the generated local key string:

 var autoEncryptionOpts = {
   "keyVaultNamespace" : "encryption.__dataKeys",
   "kmsProviders" : {
     "local" : {
       "key" : BinData(0, TEST_LOCAL_KEY)
     }
   }
 }

Create Your Encrypted Client

Use the Mongo() constructor with the client-side field level encryption options configured to create a database connection. Replace the mongodb://myMongo.example.net URI with the connection string URI of the target cluster.

encryptedClient = Mongo(
  "mongodb://myMongo.example.net:27017/?replSetName=myMongo",
   autoEncryptionOpts
)

Specify which Fields to Encrypt

Create an encryptedFieldsMaps to specify which fields to encrypt:

const encryptedFieldsMap = {
  encryptedFields: {
    fields: [
      {
        path: "secretField",
        bsonType: "string",
        queries: { queryType: "equality" },
      },
    ],
  },
};

Create Your Encrypted Collection

Create an encrypted enc.users collection:

clientEncryption = encryptedClient.getClientEncryption();
var result = clientEncryption.createEncryptedCollection(
  "enc",
  "users",
  {
    provider: "local",
    createCollectionOptions: encryptedFieldsMap,
    masterKey: {} // masterKey is optional when provider is local
  }
)

Check Your Result Object

createEncryptedCollection returns a large result object with many fields. Check the value of result.collection to confirm the collection was created in the desired location.

enc> result.collection
enc.users

Learn More

For complete documentation on initiating MongoDB connections with client-side field level encryption enabled, see Mongo().
For a complete example of how to create and query an encrypted collection, see Quick Start.

Back

getClientEncryption()

ClientEncryption.encrypt()