Navigation

Manage Client-Side Encryption Data Keys

beta

Client-Side Field Level Encryption is available as a beta. The contents of this page may change during the beta period.

Client-side field level encryption uses data keys for encryption and decryption. The mongo shell getKeyVault() method returns a key vault object for creating, modifying, and deleting data keys.

Create a Data Key

The following procedure uses the mongo shell to create a data key for use with client-side field level encryption and decryption. For guidance on data key management using a 4.2-compatible driver, see the documentation for that driver.

1

Create the database connection.

Use the Mongo() constructor to create a database connection configured for client-side field level encryption.

Client-side field level encryption requires a Key Management Service (KMS). Each tab corresponds to a supported KMS.

Create a mongo shell session. To mitigate the risk of the AWS Access Key or Secret leaking into logs, specify environmental variables containing the required values as part of the mongo --eval startup option.

mongo --eval "
    var AWS_ACCESS_KEY_ID = '$AWS_ACCESS_KEY_ID'
    var AWS_SECRET_ACCESS_KEY = '$AWS_SECRET_ACCESS_KEY'
  " \
  --shell --nodb

Use the Mongo() constructor from the mongo shell to establish the database connection:

var ClientSideFieldLevelEncryptionOptions = {
  "keyVaultClient" : Mongo("mongodb://keyVaultCluster.example.net:27017"),
  "keyVaultNamespace" : "encryption.dataKeys",
  "kmsProviders" : {
    "aws" : {
      "accessKeyId" : AWS_ACCESS_KEY_ID,
      "secretAccessKey" : AWS_SECRET_ACCESS_KEY
    }
  }
}

csfleDatabaseConnection = Mongo(
  "mongodb://mymongo.example.net:27017/?replicaSet="myMongoCluster",
  ClientSideFieldLevelEncryptionOptions
)

Replace the keyVaultClient connection string with the URI of the remote key vault cluster. Alternatively, omit keyVaultClient to use the Mongo() database connection as the key vault host.

Use the csfleDatabaseConnection object to access client-side field level encryption shell methods.

Development or Evaluation Only

The local KMS is best suited for development or evaluation of client-side field level encryption. Secure the local key from unauthorized access regardless of the deployment environment.

Create a mongo shell session. To mitigate the risk of the local key leaking into logs, specify environmental variables containing the required values as part of the mongo --eval startup option.

mongo --eval "var LOCAL_KEY = '$LOCAL_KEY' " \
  --shell --nodb

The LOCAL_KEY must be at 96 bytes in length.

Use the Mongo() constructor from the mongo shell to establish the database connection:

var ClientSideFieldLevelEncryptionOptions = {
  "keyVaultClient" : Mongo("mongodb://keyVaultCluster.example.net:27017"),
  "keyVaultNamespace" : "encryption.dataKeys",
  "kmsProviders" : {
    "local" : {
      "key" : LOCAL_KEY
    }
  }
}

csfleDatabaseConnection = Mongo(
  "mongodb://mymongo.example.net:27017/?replicaSet="myMongoCluster",
  ClientSideFieldLevelEncryptionOptions
)

Replace the keyVaultClient connection string with the URI of the remote key vault cluster. Alternatively, omit keyVaultClient to use the Mongo() database connection as the key vault host.

Use the csfleDatabaseConnection object to access client-side field level encryption shell methods.

For complete documentation on establishing database connections configured for client-side field level encryption, see the Mongo() constructor reference.

2

Create the key vault object.

Use the getKeyVault() method on the csfleDatabaseConnection database connection object to create the key vault object:

keyVault = csfleDatabaseConnection.getKeyVault();
3

Create the data key.

Use the KeyVault.createKey() method on the keyVault object to create a new data key in the key vault.

 keyVault.createKey(
   "aws",
   "arn:aws:kms:region:account:key/keystring",
   [ "keyAlternateName" ]
)

The first parameter must be "aws" to specify the configured Amazon Web Services KMS.

The second parameter must be the full Amazon Resource Name (ARN) of the Customer Master Key (CMK). MongoDB uses the specified CMK to encrypt the data key.

The third parameter may be an array of one or more keyAltNames for the data key. Each key alternate name must be unique. getKeyVault() creates a unique index on keyAltNames to enforce uniqueness of key alternate names. Consider assigning at least one alternate name to faciliate data key findability.

 keyVault.createKey(
   "local",
   "CustomerMasterKeyString",
   [ "keyAlternateName" ]
)

The first parameter must be local to specify the configured local KMS.

The second parameter must be a string of any length. MongoDB uses the specified key and the local keyfile string to encrypt the data key.

The third parameter may be an array of one or more keyAltNames for the data key. Each key alternate name must be unique. getKeyVault() creates a unique index on keyAltNames to enforce uniqueness of key alternate names. Consider assigning at least one alternate name to faciliate data key findability.

4

Retrieve the created data key.

Use the KeyVault.getKeyByAltName() method on the keyVault object to retrieve the created data key by its alternate name.

keyVault.getKeyByAltName("keyAlternateName")

The method returns output similar to the following:

{
    "_id" : UUID("b4b41b33-5c97-412e-a02b-743498346079"),
    "keyMaterial" : BinData(0,"PXRsLOAYxhzTS/mFQAI8486da7BwZgqA91UI7NKz/T/AjB0uJZxTvhvmQQsKbCJYsWVS/cp5Rqy/FUX2zZwxJOJmI3rosPhzV0OI5y1cuXhAlLWlj03CnTcOSRzE/YIrsCjMB0/NyiZ7MRWUYzLAEQnE30d947XCiiHIb8a0kt2SD0so8vZvSuP2n0Vtz4NYqnzF0CkhZSWFa2e2yA=="),
    "creationDate" : ISODate("2019-08-12T21:21:30.569Z"),
    "updateDate" : ISODate("2019-08-12T21:21:30.569Z"),
    "status" : 0,
    "version" : NumberLong(0),
    "masterKey" : {
        "provider" : "local"
    },
    "keyAltNames" : [
        "keyAlternateName"
    ]
}

The UUID is a BSON Binary (BinData) object with subtype 4 that uniquely identifies the data key. The UUID string is the base64-decoded representation of the Binary $binary.base64 field.

For a key created without an alternate name, issue the KeyVault.getKeys() method with the sort() modifier to sort on creationDate descending:

keyVault.getKeys().sort({"creationDate" : -1})

The operation returns all data keys starting from the most recently inserted data key.

Manage a Data Key’s Alternate Name

The following procedure uses the mongo shell to manage the alternate names of a data key. For guidance on data key management using a 4.2-compatible driver, see the documentation for that driver.

1

Create the database connection.

Use the Mongo() constructor to create a database connection configured for client-side field level encryption.

Client-side field level encryption requires a Key Management Service (KMS). Each tab corresponds to a supported KMS.

Create a mongo shell session. To mitigate the risk of the AWS Access Key or Secret leaking into logs, specify environmental variables containing the required values as part of the mongo --eval startup option.

mongo --eval "
    var AWS_ACCESS_KEY_ID = '$AWS_ACCESS_KEY_ID'
    var AWS_SECRET_ACCESS_KEY = '$AWS_SECRET_ACCESS_KEY'
  " \
  --shell --nodb

Use the Mongo() constructor from the mongo shell to establish the database connection:

var ClientSideFieldLevelEncryptionOptions = {
  "keyVaultClient" : Mongo("mongodb://keyVaultCluster.example.net:27017"),
  "keyVaultNamespace" : "encryption.dataKeys",
  "kmsProviders" : {
    "aws" : {
      "accessKeyId" : AWS_ACCESS_KEY_ID,
      "secretAccessKey" : AWS_SECRET_ACCESS_KEY
    }
  }
}

csfleDatabaseConnection = Mongo(
  "mongodb://mymongo.example.net:27017/?replicaSet="myMongoCluster",
  ClientSideFieldLevelEncryptionOptions
)

Replace the keyVaultClient connection string with the URI of the remote key vault cluster. Alternatively, omit keyVaultClient to use the Mongo() database connection as the key vault host.

Use the csfleDatabaseConnection object to access client-side field level encryption shell methods.

Development or Evaluation Only

The local KMS is best suited for development or evaluation of client-side field level encryption. Secure the local key from unauthorized access regardless of the deployment environment.

Create a mongo shell session. To mitigate the risk of the local key leaking into logs, specify environmental variables containing the required values as part of the mongo --eval startup option.

mongo --eval "var LOCAL_KEY = '$LOCAL_KEY' " \
  --shell --nodb

The LOCAL_KEY must be at 96 bytes in length.

Use the Mongo() constructor from the mongo shell to establish the database connection:

var ClientSideFieldLevelEncryptionOptions = {
  "keyVaultClient" : Mongo("mongodb://keyVaultCluster.example.net:27017"),
  "keyVaultNamespace" : "encryption.dataKeys",
  "kmsProviders" : {
    "local" : {
      "key" : LOCAL_KEY
    }
  }
}

csfleDatabaseConnection = Mongo(
  "mongodb://mymongo.example.net:27017/?replicaSet="myMongoCluster",
  ClientSideFieldLevelEncryptionOptions
)

Replace the keyVaultClient connection string with the URI of the remote key vault cluster. Alternatively, omit keyVaultClient to use the Mongo() database connection as the key vault host.

Use the csfleDatabaseConnection object to access client-side field level encryption shell methods.

For complete documentation on establishing database connections configured for client-side field level encryption, see the Mongo() constructor reference.

2

Create the key vault object.

Use the getKeyVault() method on the csfleDatabaseConnection database connection object to create the key vault object:

keyVault = csfleDatabaseConnection.getKeyVault();
3

Manage the data key’s alternate name.

Add Key Alternate Name

Use the KeyVault.addKeyAlternateName() to add a new alternate name to a data key:

keyVault.addKeyAlternateName(
  UUID("b4b41b33-5c97-412e-a  02b-743498346079),
  "myNewKeyAlternateName"
)

The first parameter must be the UUID of the data key to modify.

The second parameter must be a unique string. getKeyVault() creates a unique index on keyAltNames to enforce uniqueness of key alternate names.

KeyVault.addKeyAlternateName() returns the data key document prior to modification. Use KeyVault.getKey() to retrive the modified data key.

Remove Key Alternate Name

Use the KeyVault.removeKeyAlternateName() to remove a key alternate name from a data key:

keyVault.removeKeyAlternateName(
  UUID("b4b41b33-5c97-412e-a02b-743498346079"),
  "myNewKeyAlternateName"
)

The first parameter must be the UUID of the data key to modify.

The second parameter must be a string key alternate name.

KeyVault.removeKeyAlternateName() returns the data key prior to modification. Use KeyVault.getKey() to retrieve the modified data key.

Remove a Data Key

Warning

Deleting a data key renders all fields encrypted using that key as permanently unreadable.

The following procedure uses the mongo shell to remove a data key from the key vault. For guidance on data key management using a 4.2-compatible driver, see the documentation for that driver.

1

Create the database connection.

Use the Mongo() constructor to create a database connection configured for client-side field level encryption.

Client-side field level encryption requires a Key Management Service (KMS). Each tab corresponds to a supported KMS.

Create a mongo shell session. To mitigate the risk of the AWS Access Key or Secret leaking into logs, specify environmental variables containing the required values as part of the mongo --eval startup option.

mongo --eval "
    var AWS_ACCESS_KEY_ID = '$AWS_ACCESS_KEY_ID'
    var AWS_SECRET_ACCESS_KEY = '$AWS_SECRET_ACCESS_KEY'
  " \
  --shell --nodb

Use the Mongo() constructor from the mongo shell to establish the database connection:

var ClientSideFieldLevelEncryptionOptions = {
  "keyVaultClient" : Mongo("mongodb://keyVaultCluster.example.net:27017"),
  "keyVaultNamespace" : "encryption.dataKeys",
  "kmsProviders" : {
    "aws" : {
      "accessKeyId" : AWS_ACCESS_KEY_ID,
      "secretAccessKey" : AWS_SECRET_ACCESS_KEY
    }
  }
}

csfleDatabaseConnection = Mongo(
  "mongodb://mymongo.example.net:27017/?replicaSet="myMongoCluster",
  ClientSideFieldLevelEncryptionOptions
)

Replace the keyVaultClient connection string with the URI of the remote key vault cluster. Alternatively, omit keyVaultClient to use the Mongo() database connection as the key vault host.

Use the csfleDatabaseConnection object to access client-side field level encryption shell methods.

Development or Evaluation Only

The local KMS is best suited for development or evaluation of client-side field level encryption. Secure the local key from unauthorized access regardless of the deployment environment.

Create a mongo shell session. To mitigate the risk of the local key leaking into logs, specify environmental variables containing the required values as part of the mongo --eval startup option.

mongo --eval "var LOCAL_KEY = '$LOCAL_KEY' " \
  --shell --nodb

The LOCAL_KEY must be at 96 bytes in length.

Use the Mongo() constructor from the mongo shell to establish the database connection:

var ClientSideFieldLevelEncryptionOptions = {
  "keyVaultClient" : Mongo("mongodb://keyVaultCluster.example.net:27017"),
  "keyVaultNamespace" : "encryption.dataKeys",
  "kmsProviders" : {
    "local" : {
      "key" : LOCAL_KEY
    }
  }
}

csfleDatabaseConnection = Mongo(
  "mongodb://mymongo.example.net:27017/?replicaSet="myMongoCluster",
  ClientSideFieldLevelEncryptionOptions
)

Replace the keyVaultClient connection string with the URI of the remote key vault cluster. Alternatively, omit keyVaultClient to use the Mongo() database connection as the key vault host.

Use the csfleDatabaseConnection object to access client-side field level encryption shell methods.

For complete documentation on establishing database connections configured for client-side field level encryption, see the Mongo() constructor reference.

2

Create the key vault object.

Use the getKeyVault() method on the csfleDatabaseConnection database connection object to create the key vault object:

keyVault = csfleDatabaseConnection.getKeyVault();
3

Delete the data key using its UUID.

Use the KeyVault.deleteKey() method on the keyVault object to delete a data key from the key vault:

keyVault.deleteKey(UUID("b4b41b33-5c97-412e-a02b-743498346079"))