Docs Home → Develop Applications → MongoDB Manual
getKeyVault()![](/zh-cn/docs/v5.2/assets/link.svg)
New in version 4.2.
getKeyVault()
Returns the
KeyVault
object for the current database connection. TheKeyVault
object supports data encryption key management for Client-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 encryption key
management methods:
Behavior![](/zh-cn/docs/v5.2/assets/link.svg)
Requires Configuring Client-Side Field Level Encryption on Database Connection![](/zh-cn/docs/v5.2/assets/link.svg)
The following example uses a locally managed key for the client-side field level encryption configuration.
The mongo
client-side field level encryption methods
require a database connection with client-side field level encryption
enabled. If the current database connection was not initiated with
client-side field level encryption enabled, either:
Use the
Mongo()
constructor from themongo
shell 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
mongo
shell 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.
Unique Partial Index on Key Vault![](/zh-cn/docs/v5.2/assets/link.svg)
The getKeyVault()
method automatically creates a
unique index on the keyAltNames
field
with a partial index filter for only
documents where keyAltNames
exists. getKeyVault()
creates this index in the key vault collection. This prevents any two
data encryption keys in the same key vault from having the same key
alternative name and therefore avoids ambiguity around which data
encryption key is appropriate for encryption/decryption.
Warning
Do not drop the unique index created by getKeyVault()
.
Client-side field level encryption operations depend on
server-enforced uniqueness of keyAltNames
. Removing the index
may lead to unexpected or unpredictable behavior.
Example![](/zh-cn/docs/v5.2/assets/link.svg)
The following example uses a locally managed key for the client-side field level encryption configuration.
Configuring client-side field level 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
the mongo
shell:
TEST_LOCAL_KEY=$(echo "$(head -c 96 /dev/urandom | base64 | tr -d '\n')") mongosh --nodb --shell --eval "var TEST_LOCAL_KEY='$TEST_LOCAL_KEY'"
Create the client-side field level encryption object using the generated local key string:
var ClientSideFieldLevelEncryptionOptions = { "keyVaultNamespace" : "encryption.__dataKeys", "kmsProviders" : { "local" : { "key" : BinData(0, TEST_LOCAL_KEY) } } }
Use the Mongo()
constructor to create a database connection
with the client-side field level 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", ClientSideFieldLevelEncryptionOptions )
Use the getKeyVault()
method to retrieve the
key vault object:
keyVault = encryptedClient.getKeyVault()
For complete documentation on initiating MongoDB connections with
client-side field level encryption enabled, see Mongo()
.