ClientEncryption.encrypt()

New in version 4.2.

beta

Client-Side Field Level Encryption is available as a beta. The contentsof this page may change during the beta period.

• ClientEncryption.encrypt(encryptionKeyId, value, encryptionAlgorithm)
• ClientEncryption.encrypt encrypts the value using thespecified encryptionKeyId and encryptionAlgorithm.encrypt supports explicit (manual) encryptionof field values.

encrypt has the following syntax:

clientEncryption = db.getMongo().getClientEncryption()
 
clientEncryption.encrypt(
  encryptionKeyId,
  value,
  encryptionAlgorithm
)

ParameterTypeDescriptionencryptionKeyIdUUIDThe data key to use for encrypting the value.

The UUID is a BSONbinary data object with subtype 4 that identifiesa specific data key. If the data key does not exist in thekey vault configured for the database connection,encrypt() returns an error.valueSee Unsupported BSON Types.The value to encrypt.encryptionAlgorithmstringThe encryption algorithm to use for encrypting the value.

• AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic
• AEAD_AES_256_CBC_HMAC_SHA_512-RandomFor complete documentation on the supported encryption algorithms,see Encryption Algorithms.

Behavior

Enable Client-Side Field Level Encryption on Database Connection

The mongo client-side field level encrytion methodsrequire a database connection with client-side field level encryptionenabled. If the current database connection was not initiated withclient-side field level encryption enabled, either:

• Use the Mongo() constructor from the mongoshell to establish a connection with the required client-side fieldlevel encryption options. The Mongo() method supports bothAmazon Web Services and Local Key Management Service (KMS) providersfor Customer Master Key (CMK) management.

or

• Use the mongo shell command line options to establish aconnection with the required options. The command line options onlysupport the AWS KMS provider for CMK management.

Unsupported BSON Types

encrypt() does not supports encryptingvalues with the following BSON types:

• minKey
• maxKey
• null
• undefined

If encrypting a field using AEADAES_256_CBC_HMAC_SHA_512-Deterministic,encrypt() does _not support the followingBSON types:

• double
• decimal128
• bool
• object
• array
• javascriptWithScope

Example

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

Configuring client-side field level encryption for a locallymanaged key requires specifying a base64-encoded 96-bytestring with no line breaks. The following operation generatesa key that meets the stated requirements and loads it intothe mongo shell:

TEST_LOCAL_KEY=$(echo "$(head -c 96 /dev/urandom | base64 | tr -d '\n')")
 
mongo --nodb --shell --eval "var TEST_LOCAL_KEY='$TEST_LOCAL_KEY'"

Create the client-side field level encryption object using thegenerated local key string:

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

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

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

Retrieve the ClientEncryption objectand use the ClientEncryption.encrypt() method to encrypta value using a specific data key UUID andencryption algorithm:

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

If sucessful, encrypt returns the encryptedvalue:

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

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