Docs Menu
Docs Home
/
MongoDB Manual
/
Reference
/
mongosh Methods
/
Client-Side Field Level Encryption Methods

ClientEncryption.encrypt()

On this page

  • Syntax
  • Behavior
  • Examples
  • Learn More

New in version 4.2.

ClientEncryption.encrypt(keyId, value, algorithm or encOptions)

ClientEncryption.encrypt() encrypts the value using the specified keyId and the algorithm specified by algorithm or encOptions. encrypt() supports explicit (manual) encryption of field values.

Returns:A binary data object with subtype 6.

Syntax

clientEncryption = db.getMongo().getClientEncryption()
clientEncryption.encrypt(
  keyId,
  value,
  algorithm or encOptions,
)
Parameter
Type
Description
keyId
UUID

The data encryption key to use for encrypting the value.

The UUID is a BSON binary data object with subtype 4 that identifies a specific data encryption key. If the data encryption key does not exist in the key vault configured for the database connection, encrypt() returns an error. See Key Vault Collections for more information on key vaults and data encryption keys.

value
The value to encrypt.
algorithm or encOptions
string or document

  • To explicitly encrypt fields with Client-Side Field Level Encryption:

    Specify the algorithm as a string or encOptions as a document containing the field algorithm.

    The supported algorithms are:

    • AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic

    • AEAD_AES_256_CBC_HMAC_SHA_512-Random

    For examples, see Set the Client-Side Field Level Encryption Algorithm.

    For complete documentation on the supported encryption algorithms, see Fields and Encryption Types.

  • To explicitly encrypt fields with Queryable Encryption:

    Specify the algorithm as a string or encOptions as a document containing the fields:

    • algorithm: The encryption algorithm to use for encrypting the value. The supported algorithms are:

      • Indexed

      • Unindexed

    • contentionFactor: Required when algorithm is set to Indexed. Related to the frequency of the values for this field.

    • queryType: The only query type currently supported is "equality". queryType must be set when algorithm is not Indexed.

    For examples, see Set the Queryable Encryption Algorithm.

    For details on the supported encryption algorithms, see Algorithm Choice.

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:

or

Unsupported BSON Types

You cannot use encrypt() to encrypt values with the following BSON types:

  • minKey

  • maxKey

  • null

  • undefined

If encrypting a field using AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic, encrypt() does not support the following BSON types:

  • double

  • decimal128

  • bool

  • object

  • array

  • javascriptWithScope (Deprecated in MongoDB 4.4)

Examples

Client-Side Field Level Encryption

The following example uses a locally managed KMS for the client-side field level encryption configuration.

1

Create Your Encrypted Connection

1
Start mongosh

Start the mongosh client.

mongosh --nodb
2
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")
3
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)
     }
   }
 }
4
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
)
2

Encrypt Your Data

Retrieve the ClientEncryption object and use the ClientEncryption.encrypt() method to encrypt a value using a specific data encryption key UUID and encryption algorithm:

clientEncryption = encryptedClient.getClientEncryption();
clientEncryption.encrypt(
  UUID("64e2d87d-f168-493c-bbdf-a394535a2cb9"),
  "123-45-6789",
  "AEAD_AES_256_CBC_HMAC_SHA_512-Random"
)

You can also specify the algorithm using a document with an algorithm field:

clientEncryption = encryptedClient.getClientEncryption();
clientEncryption.encrypt(
  UUID("64e2d87d-f168-493c-bbdf-a394535a2cb9"),
  "123-45-6789",
  { algorithm: "AEAD_AES_256_CBC_HMAC_SHA_512-Random" }
)

Example Results

If successful, encrypt() returns the encrypted value:

BinData(6,"AmTi2H3xaEk8u9+jlFNaLLkC3Q/+kmwDbbWrq+h9nuv9W+u7A5a0UnpULBNZH+Q21fAztPpU09wpKPrju9dKfpN1Afpj1/ZhFcH6LYZOWSBBOAuUNjPLxMNSYOOuITuuYWo=")

For complete documentation on initiating MongoDB connections with client-side field level encryption enabled, see Mongo().

Queryable Encryption

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

1

Create Your Encrypted Connection

1
Start mongosh

Start the mongosh client.

mongosh --nodb
2
Generate Your Key

To configure queryable 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")
3
Create the Queryable Encryption Options

Create the queryable encryption options using the generated local key string:

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

Use the Mongo() constructor with the queryable 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
)
2

Encrypt Your Data

Retrieve the ClientEncryption object and use the ClientEncryption.encrypt() method to encrypt a value using a specific data encryption key UUID and encryption algorithm:

const eDB = "encrypted"
const eKV = "__keyVault"
const clientEncryption = encryptedClient.getClientEncryption();
const keyVaultClient = Mongo().getDB(eDB).getCollection(eKV)
const dek = keyVaultClient.findOne({ keyAltNames: "dataKey1" })
clientEncryption.encrypt(
  dek._id,
  "123-45-6789",
  "Unindexed"
)

You can also specify the algorithm using a document containing the fields:

  • algorithm

  • queryType

  • contentionFactor

const eDB = "encrypted"
const eKV = "__keyVault"
const clientEncryption = encryptedClient.getClientEncryption();
const keyVaultClient = Mongo().getDB(eDB).getCollection(eKV)
const dek = keyVaultClient.findOne({ keyAltNames: "dataKey1" })
clientEncryption.encrypt(
  dek._id,
  "123-45-6789",
  {
    algorithm: "Indexed",
    queryType: "equality",
    contentionFactor: 4
  }
)

Example Results

If successful, encrypt() returns the encrypted value:

Binary(Buffer.from("05b100000005640020000000005ab3581a43e39a8e855b1ac87013e841735c09d19ae86535eea718dd56122ba50573002000000000703d2cba9832d90436c6c92eb232aa5b968cdcd7a3138570bc87ef0a9eb3a0e905630020000000009cb61df010b1bb54670a5ad979f25f4c48889059dfd8920782cf03dd27d1a50b05650020000000003f5acea703ea357d3eea4c6a5b19139a580089341424a247839fd4d5cf0d312a12636d00040000000000000000", "hex"), 6)

Learn More

For complete documentation on initiating MongoDB connections with client-side field level encryption enabled, see Mongo().

Back

ClientEncryption.createEncryptedCollection()