KeyVault.addKeyAlternateName()

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.addKeyAlternateName(UUID, keyAltName)
  • Adds the keyAltName to the keyAltNames array of the data keywith UUID.

keyAltName must be unique among all keys in the key vault.getKeyVault creates a unique index onkeyAltNames to enforce uniqueness of keyAltName.

addKeyAlternateName() has the following syntax:

  1. keyVault = db.getMongo().getKeyVault()
  2.  
  3. keyVault.addKeyAlternateName(
  4.   UUID("<UUID string>"),
  5.   "keyAltName"
  6. )
returns:Returns the previous version of the data key document.Returns null if no data key has the specified UUID().

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 the mongoshell to establish a connection with the required client-side fieldlevel encryption options. The Mongo() 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, seeManage a data encryption key’s alternate name.

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:

  1. TEST_LOCAL_KEY=$(echo "$(head -c 96 /dev/urandom | base64 | tr -d '\n')")
  2.  
  3. mongo --nodb --shell --eval "var TEST_LOCAL_KEY='$TEST_LOCAL_KEY'"

Create the client-side field level encryption object using thegenerated local key string:

  1. var ClientSideFieldLevelEncryptionOptions = {
  2.   "keyVaultNamespace" : "encryption.__dataKeys",
  3.   "kmsProviders" : {
  4.     "local" : {
  5.       "key" : BinData(0, TEST_LOCAL_KEY)
  6.     }
  7.   }
  8. }

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.

  1. encryptedClient = Mongo(
  2.   "mongodb://myMongo.example.net:27017/?replSetName=myMongo",
  3.   ClientSideFieldLevelEncryptionOptions
  4. )

Retrieve the KeyVault object and usethe KeyVault.addKeyAlternateName() method to add a newkey alternate name to the data key with matching UUID. The specifiedkey alternate name must be unique:

  1. keyVault = encryptedClient.getKeyVault()
  2. keyVault.addKeyAlternateName(UUID("b4b41b33-5c97-412e-a02b-743498346079"),"Other-Data-Encryption-Key")

If successful, addKeyAlternateName() returns theprevious version of data key document:

  1. {
  2.     "_id" : UUID("b4b41b33-5c97-412e-a02b-743498346079"),
  3.     "keyMaterial" : BinData(0,"PXRsLOAYxhzTS/mFQAI8486da7BwZgqA91UI7NKz/T/AjB0uJZxTvhvmQQsKbCJYsWVS/cp5Rqy/FUX2zZwxJOJmI3rosPhzV0OI5y1cuXhAlLWlj03CnTcOSRzE/YIrsCjMB0/NyiZ7MRWUYzLAEQnE30d947XCiiHIb8a0kt2SD0so8vZvSuP2n0Vtz4NYqnzF0CkhZSWFa2e2yA=="),
  4.     "creationDate" : ISODate("2019-08-12T21:21:30.569Z"),
  5.     "updateDate" : ISODate("2019-08-12T21:21:30.569Z"),
  6.     "status" : 0,
  7.     "version" : NumberLong(0),
  8.     "masterKey" : {
  9.         "provider" : "local"
  10.     },
  11.     "keyAltNames" : [
  12.     ]
  13. }

To view the current version of the data key document, useKeyVault.getKey() specifying the id of the returneddocument _orKeyVault.getKeyByAltName() specifying one of thekeyAltNames.

See also

Manage a data encryption key’s alternate name