KeyVault.createKey()
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.
KeyVault.
createKey
(keyManagementService, customerMasterKey[, "keyAltName"])- Adds a data key to the key vault associated to the database connection.Client-side field level encryption uses data keys for supportingencryption and decryption of field values.
createKey()
has the following syntax:
- keyVault = db.getMongo().getKeyVault()
- keyVault.createKey(
- keyManagementService,
- customerMasterKey,
- [ "keyAltName" ]
- )
ParameterTypeDescriptionkeyManagementService
stringRequired
The Key Managmenet Service (KMS) to use forretrieving the Customer Master Key (CMK).
Specify aws
for Amazon Web Service KMS.
Specify local
for a locally managed single-key KMS.
If the database connection
was notconfigured with the specified KMS, data key creation fails.customerMasterKey
stringRequired
The identifier for the CMK to use for encryptingthe data key.
- For
keyManagementService.aws
, specify the fullAmazon Resource Name (ARN)of the master key.createKey()
requests the AWS KMS encrypt the data key material with thespecified CMK.
If the CMK does not exist or if the KMS configuration doesnot provide access to that CMK,createKey()
returns an error.
- For
keyManagementService.local
, specify an empty string""
. The local KMS uses only the localkey specified as part of the database connectionfor encrypting data keys.keyAltName
array of stringsOptional
The alternative name for the data key. Use keyAltName
toimprove findability of a specific data key, or as an analog to acomment.
keyAltName
must be unique. getKeyVault
creates aunique index on keyAltName
to enforce uniqueness ofkeyAltName
.
returns: | The UUID unique identifier of the created data key. |
---|
Behavior
Requires Configuring 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 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.
Example
The following example is intended for rapid evaluation ofclient-side field level encryption. For more complete examplesappropriate for development and production environments, seeCreate a data encryption key.
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 keyVault
object anduse the KeyVault.createKey()
method tocreate a new data key using the locally managed key:
- keyVault = encryptedClient.getKeyVault()
- keyVault.createKey("local", "", ["data-encryption-key"]
If successfull, createKey()
returns theUUID
of the created data key. To retrieve the created data keydocument from the key vault, either:
- Use
getKey()
to retrieve the created key byUUID
.
-or-
- Use
getKeyByAltName()
to retrieve the key by itsalternative name.