getKeyVault()
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.
getKeyVault
()- Returns the
KeyVault
object for the current database connection. TheKeyVault
object supports data key management forClient-side field level encryption.
getKeyVault()
has the following syntax:
- keyVault = db.getMongo().getKeyVault();
returns: | The KeyVault object for current database connection. |
---|
Use the KeyVault
object to access the following data key managementmethods:
Behavior
Requires Configuring Client-Side Field Level Encryption on Database Connection
The following example uses a locally managed KMS for the client-sidefield level encryption configuration.
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 themongo
shell to establish a connection with the required client-side fieldlevel encryption options. TheMongo()
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.
Unique Partial Index on Key Vault
The getKeyVault()
method automatically creates aunique index on the keyAltNames
fieldwith a partial index filter for onlydocuments where keyAltNames
exists. getKeyVault()
creates this index in the key vault collection. This prevents any twodata encryption keys in the same key vault from having the same keyalternative name and therefore avoids ambiguity around which dataencryption key is appropriate for encryption/decryption.
Warning
Do not drop the unique index created by getKeyVault()
.Client-side field level encryption operations depend onserver-enforced uniqueness of keyAltNames
. Removing the indexmay lead to unexpected or unpredictable behavior.
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
- )
Use the getKeyVault()
method to retrieve thekey vault object:
- keyVault = encryptedClient.getKeyVault()
For complete documentation on initiating MongoDB connections withclient-side field level encryption enabled, see Mongo()
.