Class ClientEncryption

Namespace

MongoDB.Driver.Encryption

Assembly

MongoDB.Driver.dll

Explicit client encryption.

public sealed class ClientEncryption : IDisposable

Inheritance

object

ClientEncryption

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Constructors

ClientEncryption(ClientEncryptionOptions)

Initializes a new instance of the ClientEncryption class.

public ClientEncryption(ClientEncryptionOptions clientEncryptionOptions)

Parameters

clientEncryptionOptions ClientEncryptionOptions

The client encryption options.

Methods

AddAlternateKeyName(Guid, string, CancellationToken)

Adds an alternate key name to the keyAltNames array of the key document in the key vault collection with the given UUID (BSON binary subtype 0x04).

public BsonDocument AddAlternateKeyName(Guid id, string alternateKeyName, CancellationToken cancellationToken = default)

Parameters

id Guid

The id.

alternateKeyName string

The alternate key name.

cancellationToken CancellationToken

The cancellation token.

Returns

BsonDocument

Returns the previous version of the key document.

AddAlternateKeyNameAsync(Guid, string, CancellationToken)

Adds an alternate key name to the keyAltNames array of the key document in the key vault collection with the given UUID (BSON binary subtype 0x04).

public Task<BsonDocument> AddAlternateKeyNameAsync(Guid id, string alternateKeyName, CancellationToken cancellationToken = default)

Parameters

id Guid

The id.

alternateKeyName string

The key alter name.

cancellationToken CancellationToken

The cancellation token.

Returns

Task<BsonDocument>

Returns the previous version of the key document.

CreateDataKey(string, DataKeyOptions, CancellationToken)

An alias function equivalent to createKey.

public Guid CreateDataKey(string kmsProvider, DataKeyOptions dataKeyOptions, CancellationToken cancellationToken = default)

Parameters

kmsProvider string

The kms provider.

dataKeyOptions DataKeyOptions

The data key options.

cancellationToken CancellationToken

The cancellation token.

Returns

Guid

A data key.

CreateDataKeyAsync(string, DataKeyOptions, CancellationToken)

An alias function equivalent to createKey.

public Task<Guid> CreateDataKeyAsync(string kmsProvider, DataKeyOptions dataKeyOptions, CancellationToken cancellationToken = default)

Parameters

kmsProvider string

The kms provider.

dataKeyOptions DataKeyOptions

The data key options.

cancellationToken CancellationToken

The cancellation token.

Returns

Task<Guid>

A data key.

CreateEncryptedCollection(IMongoDatabase, string, CreateCollectionOptions, string, BsonDocument, CancellationToken)

Create encrypted collection.

public CreateEncryptedCollectionResult CreateEncryptedCollection(IMongoDatabase database, string collectionName, CreateCollectionOptions createCollectionOptions, string kmsProvider, BsonDocument masterKey, CancellationToken cancellationToken = default)

Parameters

database IMongoDatabase

The database.

collectionName string

The collection name.

createCollectionOptions CreateCollectionOptions

The create collection options.

kmsProvider string

The kms provider.

masterKey BsonDocument

The master key.

cancellationToken CancellationToken

The cancellation token.

Returns

CreateEncryptedCollectionResult

The operation result.

Remarks

If EncryptionFields contains a keyId with a null value, a data key will be automatically generated and returned in EncryptedFields.

CreateEncryptedCollection(IMongoDatabase, string, CreateCollectionOptions, string, DataKeyOptions, CancellationToken)

Create encrypted collection.

[Obsolete("Use the overload with masterKey instead.")]
public CreateEncryptedCollectionResult CreateEncryptedCollection(IMongoDatabase database, string collectionName, CreateCollectionOptions createCollectionOptions, string kmsProvider, DataKeyOptions dataKeyOptions, CancellationToken cancellationToken = default)

Parameters

database IMongoDatabase

The database.

collectionName string

The collection name.

createCollectionOptions CreateCollectionOptions

The create collection options.

kmsProvider string

The kms provider.

dataKeyOptions DataKeyOptions

The datakey options.

cancellationToken CancellationToken

The cancellation token.

Returns

CreateEncryptedCollectionResult

The operation result.

Remarks

If EncryptionFields contains a keyId with a null value, a data key will be automatically generated and returned in EncryptedFields.

CreateEncryptedCollectionAsync(IMongoDatabase, string, CreateCollectionOptions, string, BsonDocument, CancellationToken)

Create encrypted collection.

public Task<CreateEncryptedCollectionResult> CreateEncryptedCollectionAsync(IMongoDatabase database, string collectionName, CreateCollectionOptions createCollectionOptions, string kmsProvider, BsonDocument masterKey, CancellationToken cancellationToken = default)

Parameters

database IMongoDatabase

The database.

collectionName string

The collection name.

createCollectionOptions CreateCollectionOptions

The create collection options.

kmsProvider string

The kms provider.

masterKey BsonDocument

The master key.

cancellationToken CancellationToken

The cancellation token.

Returns

Task<CreateEncryptedCollectionResult>

The operation result.

Remarks

If EncryptionFields contains a keyId with a null value, a data key will be automatically generated and returned in EncryptedFields.

CreateEncryptedCollectionAsync(IMongoDatabase, string, CreateCollectionOptions, string, DataKeyOptions, CancellationToken)

Create encrypted collection.

[Obsolete("Use the overload with masterKey instead.")]
public Task<CreateEncryptedCollectionResult> CreateEncryptedCollectionAsync(IMongoDatabase database, string collectionName, CreateCollectionOptions createCollectionOptions, string kmsProvider, DataKeyOptions dataKeyOptions, CancellationToken cancellationToken = default)

Parameters

database IMongoDatabase

The database.

collectionName string

The collection name.

createCollectionOptions CreateCollectionOptions

The create collection options.

kmsProvider string

The kms provider.

dataKeyOptions DataKeyOptions

The datakey options.

cancellationToken CancellationToken

The cancellation token.

Returns

Task<CreateEncryptedCollectionResult>

The operation result.

Remarks

If EncryptionFields contains a keyId with a null value, a data key will be automatically generated and returned in EncryptedFields.

Decrypt(BsonBinaryData, CancellationToken)

Decrypts the specified value.

public BsonValue Decrypt(BsonBinaryData value, CancellationToken cancellationToken = default)

Parameters

value BsonBinaryData

The value.

cancellationToken CancellationToken

The cancellation token.

Returns

BsonValue

The decrypted value.

DecryptAsync(BsonBinaryData, CancellationToken)

Decrypts the specified value.

public Task<BsonValue> DecryptAsync(BsonBinaryData value, CancellationToken cancellationToken = default)

Parameters

value BsonBinaryData

The value.

cancellationToken CancellationToken

The cancellation token.

Returns

Task<BsonValue>

The decrypted value.

DeleteKey(Guid, CancellationToken)

Removes the key document with the given UUID (BSON binary subtype 0x04) from the key vault collection.

public DeleteResult DeleteKey(Guid id, CancellationToken cancellationToken = default)

Parameters

id Guid

The id.

cancellationToken CancellationToken

The cancellation token.

Returns

DeleteResult

Returns the result of the internal deleteOne() operation on the key vault collection.

DeleteKeyAsync(Guid, CancellationToken)

Removes the key document with the given UUID (BSON binary subtype 0x04) from the key vault collection.

public Task<DeleteResult> DeleteKeyAsync(Guid id, CancellationToken cancellationToken = default)

Parameters

id Guid

The id.

cancellationToken CancellationToken

The cancellation token.

Returns

Task<DeleteResult>

Returns the result of the internal deleteOne() operation on the key vault collection.

Dispose()

public void Dispose()

Encrypt(BsonValue, EncryptOptions, CancellationToken)

Encrypts the specified value.

public BsonBinaryData Encrypt(BsonValue value, EncryptOptions encryptOptions, CancellationToken cancellationToken = default)

Parameters

value BsonValue

The value.

encryptOptions EncryptOptions

The encrypt options.

cancellationToken CancellationToken

The cancellation token.

Returns

BsonBinaryData

The encrypted value.

EncryptAsync(BsonValue, EncryptOptions, CancellationToken)

Encrypts the specified value.

public Task<BsonBinaryData> EncryptAsync(BsonValue value, EncryptOptions encryptOptions, CancellationToken cancellationToken = default)

Parameters

value BsonValue

The value.

encryptOptions EncryptOptions

The encrypt options.

cancellationToken CancellationToken

The cancellation token.

Returns

Task<BsonBinaryData>

The encrypted value.

EncryptExpression(BsonDocument, EncryptOptions, CancellationToken)

Encrypts a Match Expression or Aggregate Expression to query a range index.

public BsonDocument EncryptExpression(BsonDocument expression, EncryptOptions encryptOptions, CancellationToken cancellationToken = default)

Parameters

expression BsonDocument

The expression that is expected to be a BSON document of one of the following forms: 1. A Match Expression of this form: {$and: [{"field": {$gt: "value1"}}, {"field": {$lt: "value2" }}]} 2. An Aggregate Expression of this form: {$and: [{$gt: ["fieldpath", "value1"]}, {$lt: ["fieldpath", "value2"]}] $gt may also be $gte. $lt may also be $lte.

encryptOptions EncryptOptions

The encryption options.

cancellationToken CancellationToken

The cancellation token.

Returns

BsonDocument

The encrypted expression.

Remarks

Only supported for queryType "rangePreview" The Range algorithm is experimental only. It is not intended for public use. It is subject to breaking changes.

EncryptExpressionAsync(BsonDocument, EncryptOptions, CancellationToken)

Encrypts a Match Expression or Aggregate Expression to query a range index.

public Task<BsonDocument> EncryptExpressionAsync(BsonDocument expression, EncryptOptions encryptOptions, CancellationToken cancellationToken = default)

Parameters

expression BsonDocument

The expression that is expected to be a BSON document of one of the following forms: 1. A Match Expression of this form: {$and: [{"field": {$gt: "value1"}}, {"field": {$lt: "value2" }}]} 2. An Aggregate Expression of this form: {$and: [{$gt: ["fieldpath", "value1"]}, {$lt: ["fieldpath", "value2"]}] $gt may also be $gte. $lt may also be $lte.

encryptOptions EncryptOptions

The encryption options.

cancellationToken CancellationToken

The cancellation token.

Returns

Task<BsonDocument>

the encrypted expression.

Remarks

Only supported for queryType "rangePreview" The Range algorithm is experimental only. It is not intended for public use. It is subject to breaking changes.

GetKey(Guid, CancellationToken)

Finds a single key document with the given UUID (BSON binary subtype 0x04).

public BsonDocument GetKey(Guid id, CancellationToken cancellationToken = default)

Parameters

id Guid

The id.

cancellationToken CancellationToken

The cancellation token.

Returns

BsonDocument

Returns the result of the internal find() operation on the key vault collection.

GetKeyAsync(Guid, CancellationToken)

Finds a single key document with the given UUID (BSON binary subtype 0x04).

public Task<BsonDocument> GetKeyAsync(Guid id, CancellationToken cancellationToken = default)

Parameters

id Guid

The id.

cancellationToken CancellationToken

The cancellation token.

Returns

Task<BsonDocument>

Returns the result of the internal find() operation on the key vault collection.

GetKeyByAlternateKeyName(string, CancellationToken)

Finds a single key document with the given alter name.

public BsonDocument GetKeyByAlternateKeyName(string alternateKeyName, CancellationToken cancellationToken = default)

Parameters

alternateKeyName string

The alternate key name.

cancellationToken CancellationToken

The cancellation token.

Returns

BsonDocument

Returns a key document in the key vault collection with the given alternateKeyName.

GetKeyByAlternateKeyNameAsync(string, CancellationToken)

Finds a single key document with the given UUID (BSON binary subtype 0x04).

public Task<BsonDocument> GetKeyByAlternateKeyNameAsync(string alternateKeyName, CancellationToken cancellationToken = default)

Parameters

alternateKeyName string

The alternate key name.

cancellationToken CancellationToken

The cancellation token.

Returns

Task<BsonDocument>

Returns a key document in the key vault collection with the given alternateKeyName.

GetKeys(CancellationToken)

Finds all documents in the key vault collection.

public IReadOnlyList<BsonDocument> GetKeys(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

The cancellation token.

Returns

IReadOnlyList<BsonDocument>

Returns the result of the internal find() operation on the key vault collection.

GetKeysAsync(CancellationToken)

Finds all documents in the key vault collection.

public Task<IReadOnlyList<BsonDocument>> GetKeysAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

The cancellation token.

Returns

Task<IReadOnlyList<BsonDocument>>

Returns the result of the internal find() operation on the key vault collection.

RemoveAlternateKeyName(Guid, string, CancellationToken)

Removes an alternateKeyName from the keyAltNames array of the key document in the key vault collection with the given UUID (BSON binary subtype 0x04).

public BsonDocument RemoveAlternateKeyName(Guid id, string alternateKeyName, CancellationToken cancellationToken = default)

Parameters

id Guid

The id.

alternateKeyName string

The alternate key name.

cancellationToken CancellationToken

The cancellation token.

Returns

BsonDocument

Returns the previous version of the key document.

RemoveAlternateKeyNameAsync(Guid, string, CancellationToken)

Removes an alternateKeyName from the keyAltNames array of the key document in the key vault collection with the given UUID (BSON binary subtype 0x04).

public Task<BsonDocument> RemoveAlternateKeyNameAsync(Guid id, string alternateKeyName, CancellationToken cancellationToken = default)

Parameters

id Guid

The id.

alternateKeyName string

The alternate key name.

cancellationToken CancellationToken

The cancellation token.

Returns

Task<BsonDocument>

Returns the previous version of the key document.

RewrapManyDataKey(FilterDefinition<BsonDocument>, RewrapManyDataKeyOptions, CancellationToken)

Decrypts multiple data keys and (re-)encrypts them with a new masterKey, or with their current masterKey if a new one is not given.

public RewrapManyDataKeyResult RewrapManyDataKey(FilterDefinition<BsonDocument> filter, RewrapManyDataKeyOptions options, CancellationToken cancellationToken = default)

Parameters

filter FilterDefinition<BsonDocument>

The filter.

options RewrapManyDataKeyOptions

The options.

cancellationToken CancellationToken

The cancellation token.

Returns

RewrapManyDataKeyResult

The result.

RewrapManyDataKeyAsync(FilterDefinition<BsonDocument>, RewrapManyDataKeyOptions, CancellationToken)

Decrypts multiple data keys and (re-)encrypts them with a new masterKey, or with their current masterKey if a new one is not given.

public Task<RewrapManyDataKeyResult> RewrapManyDataKeyAsync(FilterDefinition<BsonDocument> filter, RewrapManyDataKeyOptions options, CancellationToken cancellationToken = default)

Parameters

filter FilterDefinition<BsonDocument>

The filter.

options RewrapManyDataKeyOptions

The options.

cancellationToken CancellationToken

The cancellation token.

Returns

Task<RewrapManyDataKeyResult>

The result.