Struct mongodb::client_encryption::ClientEncryption

pub struct ClientEncryption { /* private fields */ }

Available on crate feature in-use-encryption-unstable only.

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

Implementations

impl ClientEncryption

pub fn new( key_vault_client: Client, key_vault_namespace: Namespace, kms_providers: impl IntoIterator<Item = (KmsProvider, Document, Option<TlsOptions>)> ) -> Result<Self>

Initialize a new ClientEncryption.

let enc = ClientEncryption::new(
    kv_client,
    kv_namespace,
    [
        (KmsProvider::Local, doc! { "key": local_key }, None),
        (KmsProvider::Kmip, doc! { "endpoint": "localhost:5698" }, None),
    ]
)?;

pub fn create_data_key(&self, master_key: MasterKey) -> CreateDataKeyAction<'_>

Creates a new key document and inserts into the key vault collection. CreateDataKeyAction::run returns a Binary (subtype 0x04) with the _id of the created document as a UUID.

The returned CreateDataKeyAction must be executed via run, e.g.

let key = client_encryption
    .create_data_key(master_key)
    .key_alt_names(["altname1".to_string(), "altname2".to_string()])
    .run().await?;

pub async fn delete_key(&self, id: &Binary) -> Result<DeleteResult>

Removes the key document with the given UUID (BSON binary subtype 0x04) from the key vault collection. Returns the result of the internal deleteOne() operation on the key vault collection.

pub async fn get_key(&self, id: &Binary) -> Result<Option<RawDocumentBuf>>

Finds a single key document with the given UUID (BSON binary subtype 0x04). Returns the result of the internal find() operation on the key vault collection.

pub async fn get_keys(&self) -> Result<Cursor<RawDocumentBuf>>

Finds all documents in the key vault collection. Returns the result of the internal find() operation on the key vault collection.

pub async fn add_key_alt_name( &self, id: &Binary, key_alt_name: &str ) -> Result<Option<RawDocumentBuf>>

Adds a keyAltName to the keyAltNames array of the key document in the key vault collection with the given UUID (BSON binary subtype 0x04). Returns the previous version of the key document.

pub async fn remove_key_alt_name( &self, id: &Binary, key_alt_name: &str ) -> Result<Option<RawDocumentBuf>>

Removes a keyAltName from the keyAltNames array of the key document in the key vault collection with the given UUID (BSON binary subtype 0x04). Returns the previous version of the key document.

pub async fn get_key_by_alt_name( &self, key_alt_name: impl AsRef<str> ) -> Result<Option<RawDocumentBuf>>

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

pub fn encrypt( &self, value: impl Into<RawBson>, key: impl Into<EncryptKey>, algorithm: Algorithm ) -> EncryptAction<'_>

Encrypts a BsonValue with a given key and algorithm. EncryptAction::run returns a Binary (subtype 6) containing the encrypted value.

To insert or query with an “Indexed” encrypted payload, use a Client configured with AutoEncryptionOptions. AutoEncryptionOptions.bypass_query_analysis may be true. AutoEncryptionOptions.bypass_auto_encryption must be false.

The returned EncryptAction must be executed via run, e.g.

let encrypted = client_encryption
    .encrypt(
        "plaintext",
        key,
        Algorithm::AeadAes256CbcHmacSha512Deterministic,
    )
    .contention_factor(10)
    .run().await?;

pub fn encrypt_expression( &self, expression: RawDocumentBuf, key: impl Into<EncryptKey> ) -> EncryptExpressionAction<'_>

NOTE: This method is experimental only. It is not intended for public use.

Encrypts a match or aggregate expression with the given key. EncryptExpressionAction::run returns a Document containing the encrypted expression.

The expression will be encrypted using the Algorithm::RangePreview algorithm and the “rangePreview” query type.

The returned EncryptExpressionAction must be executed via run, e.g.

let expression  = rawdoc! {
    "$and": [
        { "field": { "$gte": 5 } },
        { "field": { "$lte": 10 } },
    ]
};
let encrypted_expression = client_encryption
    .encrypt_expression(
        expression,
        key,
    )
    .contention_factor(10)
    .run().await?;

pub async fn decrypt<'a>(&self, value: RawBinaryRef<'a>) -> Result<RawBson>

Decrypts an encrypted value (BSON binary of subtype 6). Returns the original BSON value.

pub async fn create_encrypted_collection( &self, db: &Database, name: impl AsRef<str>, master_key: MasterKey, options: CreateCollectionOptions ) -> (Document, Result<()>)

Creates a new collection with encrypted fields, automatically creating new data encryption keys when needed based on the configured CreateCollectionOptions::encrypted_fields.

Returns the potentially updated encrypted_fields along with status, as keys may have been created even when a failure occurs.

Does not affect any auto encryption settings on existing MongoClients that are already configured with auto encryption.