Package com.mongodb.client.vault

Interface ClientEncryption

All Superinterfaces:
AutoCloseable, Closeable
public interface ClientEncryption extends Closeable
The Key vault.

Used to create data encryption keys, and to explicitly encrypt and decrypt values when auto-encryption is not an option.

Since:
3.11

  • Method Summary

    Modifier and Type
    Method
    Description
    org.bson.BsonDocument
    addKeyAltName(org.bson.BsonBinary id, String keyAltName)
    Adds a keyAltName to the keyAltNames array of the key document in the key vault collection with the given UUID.
    void
    close()
     
    org.bson.BsonBinary
    createDataKey(String kmsProvider)
    Create a data key with the given KMS provider.
    org.bson.BsonBinary
    createDataKey(String kmsProvider, com.mongodb.client.model.vault.DataKeyOptions dataKeyOptions)
    Create a data key with the given KMS provider and options.
    org.bson.BsonDocument
    createEncryptedCollection(MongoDatabase database, String collectionName, com.mongodb.client.model.CreateCollectionOptions createCollectionOptions, com.mongodb.client.model.CreateEncryptedCollectionParams createEncryptedCollectionParams)
    Create a new collection with encrypted fields, automatically creating new data encryption keys when needed based on the configured encryptedFields, which must be specified.
    org.bson.BsonValue
    decrypt(org.bson.BsonBinary value)
    Decrypt the given value.
    com.mongodb.client.result.DeleteResult
    deleteKey(org.bson.BsonBinary id)
    Removes the key document with the given data key from the key vault collection.
    org.bson.BsonBinary
    encrypt(org.bson.BsonValue value, com.mongodb.client.model.vault.EncryptOptions options)
    Encrypt the given value with the given options.
    org.bson.BsonDocument
    encryptExpression(org.bson.conversions.Bson expression, com.mongodb.client.model.vault.EncryptOptions options)
    Encrypts a Match Expression or Aggregate Expression to query a range index.
    org.bson.BsonDocument
    getKey(org.bson.BsonBinary id)
    Finds a single key document with the given UUID (BSON binary subtype 0x04).
    org.bson.BsonDocument
    getKeyByAltName(String keyAltName)
    Returns a key document in the key vault collection with the given keyAltName.
    FindIterable<org.bson.BsonDocument>
    getKeys()
    Finds all documents in the key vault collection.
    org.bson.BsonDocument
    removeKeyAltName(org.bson.BsonBinary id, String keyAltName)
    Removes a keyAltName from the keyAltNames array of the key document in the key vault collection with the given id.
    com.mongodb.client.model.vault.RewrapManyDataKeyResult
    rewrapManyDataKey(org.bson.conversions.Bson filter)
    Decrypts multiple data keys and (re-)encrypts them with the current masterKey.
    com.mongodb.client.model.vault.RewrapManyDataKeyResult
    rewrapManyDataKey(org.bson.conversions.Bson filter, com.mongodb.client.model.vault.RewrapManyDataKeyOptions options)
    Decrypts multiple data keys and (re-)encrypts them with a new masterKey, or with their current masterKey if a new one is not given.

  • Method Details

    • createDataKey

      org.bson.BsonBinary createDataKey(String kmsProvider)
      Create a data key with the given KMS provider.

      Creates a new key document and inserts into the key vault collection.

      Parameters:
      kmsProvider - the KMS provider
      Returns:
      the identifier for the created data key

    • createDataKey

      org.bson.BsonBinary createDataKey(String kmsProvider, com.mongodb.client.model.vault.DataKeyOptions dataKeyOptions)
      Create a data key with the given KMS provider and options.

      Creates a new key document and inserts into the key vault collection.

      Parameters:
      kmsProvider - the KMS provider
      dataKeyOptions - the options for data key creation
      Returns:
      the identifier for the created data key

    • encrypt

      org.bson.BsonBinary encrypt(org.bson.BsonValue value, com.mongodb.client.model.vault.EncryptOptions options)
      Encrypt the given value with the given options.

      The driver may throw an exception for prohibited BSON value types

      Parameters:
      value - the value to encrypt
      options - the options for data encryption
      Returns:
      the encrypted value, a BSON binary of subtype 6

    • encryptExpression

      org.bson.BsonDocument encryptExpression(org.bson.conversions.Bson expression, com.mongodb.client.model.vault.EncryptOptions options)
      Encrypts a Match Expression or Aggregate Expression to query a range index.

      The expression is expected to be in one of the following forms:

      • A Match Expression of this form: {$and: [{<field>: {$gt: <value1>}}, {<field>: {$lt: <value2> }}]}
      • An Aggregate Expression of this form: {$and: [{$gt: [<fieldpath>, <value1>]}, {$lt: [<fieldpath>, <value2>]}] }
      $gt may also be $gte. $lt may also be $lte.

      Only supported when queryType is "range" and algorithm is "Range".

      Parameters:
      expression - the Match Expression or Aggregate Expression
      options - the options
      Returns:
      the encrypted queryable range expression
      Since:
      4.9
      MongoDB documentation
      queryable encryption
      $match
      Since server release
      8.0

    • decrypt

      org.bson.BsonValue decrypt(org.bson.BsonBinary value)
      Decrypt the given value.
      Parameters:
      value - the value to decrypt, which must be of subtype 6
      Returns:
      the decrypted value

    • deleteKey

      com.mongodb.client.result.DeleteResult deleteKey(org.bson.BsonBinary id)
      Removes the key document with the given data key from the key vault collection.
      Parameters:
      id - the data key UUID (BSON binary subtype 0x04)
      Returns:
      the result
      Since:
      4.7

    • getKey

      @Nullable org.bson.BsonDocument getKey(org.bson.BsonBinary id)
      Finds a single key document with the given UUID (BSON binary subtype 0x04).
      Parameters:
      id - the data key UUID (BSON binary subtype 0x04)
      Returns:
      the single key document or null if there is no match
      Since:
      4.7

    • getKeys

      FindIterable<org.bson.BsonDocument> getKeys()
      Finds all documents in the key vault collection.
      Returns:
      a find iterable for the documents in the key vault collection
      Since:
      4.7

    • addKeyAltName

      @Nullable org.bson.BsonDocument addKeyAltName(org.bson.BsonBinary id, String keyAltName)
      Adds a keyAltName to the keyAltNames array of the key document in the key vault collection with the given UUID.
      Parameters:
      id - the data key UUID (BSON binary subtype 0x04)
      keyAltName - the alternative key name to add to the keyAltNames array
      Returns:
      the previous version of the key document or null if no match
      Since:
      4.7

    • removeKeyAltName

      @Nullable org.bson.BsonDocument removeKeyAltName(org.bson.BsonBinary id, String keyAltName)
      Removes a keyAltName from the keyAltNames array of the key document in the key vault collection with the given id.
      Parameters:
      id - the data key UUID (BSON binary subtype 0x04)
      keyAltName - the alternative key name
      Returns:
      the previous version of the key document or null if no match
      Since:
      4.7

    • getKeyByAltName

      @Nullable org.bson.BsonDocument getKeyByAltName(String keyAltName)
      Returns a key document in the key vault collection with the given keyAltName.
      Parameters:
      keyAltName - the alternative key name
      Returns:
      a matching key document or null
      Since:
      4.7

    • rewrapManyDataKey

      com.mongodb.client.model.vault.RewrapManyDataKeyResult rewrapManyDataKey(org.bson.conversions.Bson filter)
      Decrypts multiple data keys and (re-)encrypts them with the current masterKey.
      Parameters:
      filter - the filter
      Returns:
      the result
      Since:
      4.7

    • rewrapManyDataKey

      com.mongodb.client.model.vault.RewrapManyDataKeyResult rewrapManyDataKey(org.bson.conversions.Bson filter, com.mongodb.client.model.vault.RewrapManyDataKeyOptions options)
      Decrypts multiple data keys and (re-)encrypts them with a new masterKey, or with their current masterKey if a new one is not given.
      Parameters:
      filter - the filter
      options - the options
      Returns:
      the result
      Since:
      4.7

    • createEncryptedCollection

      org.bson.BsonDocument createEncryptedCollection(MongoDatabase database, String collectionName, com.mongodb.client.model.CreateCollectionOptions createCollectionOptions, com.mongodb.client.model.CreateEncryptedCollectionParams createEncryptedCollectionParams)
      Create a new collection with encrypted fields, automatically creating new data encryption keys when needed based on the configured encryptedFields, which must be specified. This method does not modify the configured encryptedFields when creating new data keys, instead it creates a new configuration if needed.
      Parameters:
      database - The database to use for creating the collection.
      collectionName - The name for the collection to create.
      createCollectionOptions - Options for creating the collection.
      createEncryptedCollectionParams - Auxiliary parameters for creating an encrypted collection.
      Returns:
      The (potentially updated) encryptedFields configuration that was used to create the collection. A user may use this document to configure AutoEncryptionSettings.getEncryptedFieldsMap().
      Throws:
      com.mongodb.MongoUpdatedEncryptedFieldsException - If an exception happens after creating at least one data key. This exception makes the updated encryptedFields available to the caller.
      Since:
      4.9
      MongoDB documentation
      Create Command
      Since server release
      7.0

    • close

      void close()
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable