ClientEncryption.encrypt()
On this page
ClientEncryption.encrypt(keyId, value, algorithm or encOptions)
ClientEncryption.encrypt()
encrypts thevalue
using the specifiedkeyId
and the algorithm specified byalgorithm
orencOptions
.encrypt()
supports explicit (manual) encryption of field values.Returns: A binary data
object with subtype 6.
Compatibility
This command is available in deployments hosted in the following environments:
MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud
MongoDB Enterprise: The subscription-based, self-managed version of MongoDB
MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB
Syntax
clientEncryption = db.getMongo().getClientEncryption() clientEncryption.encrypt( keyId, value, algorithm or encOptions, )
Parameter | Type | Description |
---|---|---|
|
| The data encryption key to use for encrypting the The UUID is a BSON
|
| The value to encrypt. | |
| string or document |
|
Behavior
Create an Encrypted Database Connection
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 themongosh
to establish a connection with the required client-side field level encryption options. TheMongo()
method supports the following Key Management Service (KMS) providers for Customer Master Key (CMK) management:
or
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.
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
Examples
Client-Side Field Level Encryption
The following example uses a locally managed KMS for the client-side field level encryption configuration.
To configure client-side field level encryption for a locally managed key:
generate a base64-encoded 96-byte string with no line breaks
use
mongosh
to load the key
export TEST_LOCAL_KEY=$(echo "$(head -c 96 /dev/urandom | base64 | tr -d '\n')") mongosh --nodb
Create the client-side field level encryption object using the generated local key string:
var autoEncryptionOpts = { "keyVaultNamespace" : "encryption.__dataKeys", "kmsProviders" : { "local" : { "key" : BinData(0, process.env["TEST_LOCAL_KEY"]) } } }
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 )
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" } )
If sucessful, 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.
Configuring queryable encryption for a locally managed key requires
specifying a base64-encoded 96-byte string with no line breaks. The
following operation generates a key that meets the stated requirements
and loads it into mongosh
:
TEST_LOCAL_KEY=$(echo "$(head -c 96 /dev/urandom | base64 | tr -d '\n')") mongosh --nodb
Create the client-side field level encryption object using the generated local key string:
var autoEncryptionOpts = { "keyVaultNamespace" : "encryption.__keyVault", "kmsProviders" : { "local" : { "key" : BinData(0, process.env["TEST_LOCAL_KEY"]) } } }
Use the Mongo()
constructor to create a database connection
with the queryable encryption options. 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 )
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 } )
If sucessful, encrypt()
returns the encrypted
value:
Binary(Buffer.from("05b100000005640020000000005ab3581a43e39a8e855b1ac87013e841735c09d19ae86535eea718dd56122ba50573002000000000703d2cba9832d90436c6c92eb232aa5b968cdcd7a3138570bc87ef0a9eb3a0e905630020000000009cb61df010b1bb54670a5ad979f25f4c48889059dfd8920782cf03dd27d1a50b05650020000000003f5acea703ea357d3eea4c6a5b19139a580089341424a247839fd4d5cf0d312a12636d00040000000000000000", "hex"), 6)