- Reference >
mongo
Shell Methods >- Client-Side Field Level Encryption Methods >
- KeyVault.createKey()
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:Parameter Type Description keyManagementService
string Required
The Key Managmenet Service (KMS) to use for retrieving the Customer Master Key (CMK).
Specify
aws
for Amazon Web Service KMS.Specify
local
for a locally managed key.If the
database connection
was not configured with the specified KMS, data encryption key creation fails.customerMasterKey
string Required
The identifier for the Customer Master Key (CMK) to use for encrypting the data encryption key.
For
keyManagementService.aws
, specify the full Amazon Resource Name (ARN) of the master key.createKey()
requests the AWS KMS encrypt the data encryption key material with the specified CMK.If the CMK does not exist or if the KMS configuration does not provide access to that CMK,
createKey()
returns an error.For
keyManagementService.local
, specify an empty string""
. The local KMS uses only the local key specified as part of the database connection for encrypting data encryption keys.
keyAltName
array of strings Optional
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.
returns: | The UUID unique identifier of the created data encryption
key. |
---|
Behavior¶
Requires Configuring Client-Side Field Level Encryption on Database Connection¶
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 both Amazon Web Services and Local 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 AWS KMS provider for CMK management.
Example¶
The following example is intended for rapid evaluation of client-side field level encryption. For more complete examples appropriate for development and production environments, see Create a data encryption key.
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:
Create the client-side field level encryption object using the generated local key string:
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.
Retrieve the keyVault
object and
use the KeyVault.createKey()
method to
create a new data encryption key using the locally managed key:
If successfull, createKey()
returns the UUID
of
the created data encryption key. To retrieve the created 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.