KeyVault.createKey()
New in version 4.2.
KeyVault.createKey(keyManagementService, customerMasterKey, ["keyAltName"])
Adds a data encryption key to the key vault associated to the database connection. Client-Side Field Level Encryption uses data encryption keys for supporting encryption and decryption of field values.
createKey()
has the following syntax:keyVault = db.getMongo().getKeyVault() keyVault.createKey( keyManagementService, customerMasterKey, [ "keyAltName" ] ) ParameterTypeDescriptionkeyManagementService
stringRequired
The Key Management Service (KMS) to use for retrieving the Customer Master Key (CMK). Accepts the following parameters:
aws
for Amazon Web Services KMS. Requires specifying a Customer Master Key (CMK) string forcustomerMasterKey
.azure
for Azure Key Vault. Requires specifying a Customer Master Key (CMK) document forcustomerMasterKey
.New in version 5.0.
gcp
for Google Cloud Platform KMS. Requires specifying a Customer Master Key (CMK) document forcustomerMasterKey
.New in version 5.0.
local
for a locally managed key.
If the
database connection
was not configured with the specified KMS, data encryption key creation fails.customerMasterKey
string or documentThe Customer Master Key (CMK) to use for encrypting the data encryption key. Required if
keyManagementService
isaws
,azure
, orgcp
.Provide the CMK as follows depending on your KMS provider:
For the Amazon Web Services KMS, specify the full Amazon Resource Name (ARN) of the master key as a single string.
For the Azure Key Vault KMS, specify a document containing the following key value pairs:
keyName
- The Azure Key Vault NamekeyVaultEndpoint
- The DNS name of the Azure Key Vault to usekeyVersion
- Optional. The version of the key specified inkeyName
, if applicable
New in version 5.0.
For the Google Cloud Platform KMS, specify a document containing the following key value pairs:
projectId
- The GCP project namelocation
- The location of the KMS keyringkeyRing
- The name of the KMS keyring (often 'global')keyName
- The name of the key to usekeyVersion
- Optional. The version of the key specified inkeyName
, if applicable
New in version 5.0.
createKey()
requests that the KMS encrypt the data encryption key material using the specified CMK. If the CMK does not exist or if theAutoEncryptionOpts
configuration does not have sufficient privileges to use the CMK,createKey()
returns an error.Changed in version 4.2.3: This parameter has no effect if
keyManagementService
islocal
and can be safely omitted. Prior to MongoDB 4.2.3, ifkeyManagementService
islocal
this parameter must be an empty string"
.keyAltName
array of stringsOptional
The alternative name for the data encryption key. Use
keyAltName
to improve findability of a specific data encryption key, or as an analog to a comment.The
getKeyVault()
method automatically creates a unique index on thekeyAltNames
field with a partial index filter for only documents wherekeyAltNames
exists.options
documentOptional
A document that specifies options for the new key.
options
has the following fields:masterKey
: the new master key to encrypt data.keyAltNames
: an array of alternate names, one per master key.keyMaterial
: bindata used to create the key.
Returns: The UUID
unique identifier of the created data encryption key.
Behavior
Requires Configuring Client-Side Field Level Encryption on Database Connection
The mongosh
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 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.
Example
The following example is intended for rapid evaluation of
client-side field level encryption. For specific examples of using
KeyVault.createKey()
with each supported
KMS provider, see
Create a Data Key.
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 keyVault
object and
use the KeyVault.createKey()
method to
create a new data encryption key using the locally managed key:
keyVault = encryptedClient.getKeyVault() keyVault.createKey("local", ["data-encryption-key"])
If successful, createKey()
returns the UUID
of
the new data encryption key. To retrieve the new data encryption
key document from the key vault, either:
Use
getKey()
to retrieve the created key byUUID
.-or-
Use
getKeyByAltName()
to retrieve the key by its alternate name.