Struct ClientEncryption

pub struct ClientEncryption { /* private fields */ }

Available on crate feature in-use-encryption 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 create_data_key( &self, master_key: impl Into<MasterKey>, ) -> CreateDataKey<'_>

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

await will return Result<Binary> (subtype 0x04) with the _id of the created document as a UUID.

These methods can be chained before .await to set options:

• with_options
• key_alt_names
• key_material

impl ClientEncryption

pub fn create_encrypted_collection<'a>( &'a self, db: &'a Database, name: &'a str, master_key: MasterKey, ) -> CreateEncryptedCollection<'a>

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

await will return (Document, Result<()>) containing the potentially updated encrypted_fields along with the collection creation 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.

These methods can be chained before .await to set options:

• with_options
• capped
• size
• max
• storage_engine
• validator
• validation_level
• validation_action
• view_on
• pipeline
• collation
• write_concern
• index_option_defaults
• timeseries
• expire_after_seconds
• change_stream_pre_and_post_images
• clustered_index
• comment
• encrypted_fields

impl ClientEncryption

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

Encrypts a BsonValue with a given key and algorithm.

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.

await will return a Result<Binary> (subtype 6) containing the encrypted value.

These methods can be chained before .await to set options:

• with_options
• contention_factor
• range_options
• query_type

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

Encrypts a Match Expression or Aggregate Expression to query a range index. expression 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>]}]

For either expression, $gt may also be $gte, and $lt may also be $lte.

The expression will be encrypted using the Algorithm::Range algorithm and the “range” query type. It is not valid to set a query type in EncryptOptions when calling this method.

await will return a Result<Document> containing the encrypted expression.

These methods can be chained before .await to set options:

• with_options
• contention_factor
• range_options

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 builder( key_vault_client: Client, key_vault_namespace: Namespace, kms_providers: impl IntoIterator<Item = (KmsProvider, Document, Option<TlsOptions>)>, ) -> ClientEncryptionBuilder

Initialize a builder to construct a ClientEncryption. Methods on ClientEncryptionBuilder can be chained to set options.

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

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 async fn decrypt(&self, value: RawBinaryRef<'_>) -> Result<RawBson>

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