Struct Client

pub struct Client { /* private fields */ }

Implementations

impl Client

pub fn create_aws_kms_keyring(&self) -> CreateAwsKmsKeyringFluentBuilder

Constructs a fluent builder for the CreateAwsKmsKeyring operation.

• The fluent builder is configurable:
  • grant_tokens(impl Into<Option<::std::vec::Vec<::std::string::String>>>) / set_grant_tokens(Option<::std::vec::Vec<::std::string::String>>): (undocumented)
    
  • kms_client(impl Into<Option<crate::deps::com_amazonaws_kms::client::Client>>) / set_kms_client(Option<crate::deps::com_amazonaws_kms::client::Client>): (undocumented)
    
  • kms_key_id(impl Into<Option<::std::string::String>>) / set_kms_key_id(Option<::std::string::String>): (undocumented)
    
• On success, responds with CreateKeyringOutput with field(s):
  • keyring(Option<crate::deps::aws_cryptography_materialProviders::types::keyring::KeyringRef>): (undocumented)
• On failure, responds with SdkError<CreateAwsKmsKeyringError>

impl Client

pub fn create_aws_kms_discovery_keyring( &self, ) -> CreateAwsKmsDiscoveryKeyringFluentBuilder

Constructs a fluent builder for the CreateAwsKmsDiscoveryKeyring operation.

• The fluent builder is configurable:
  • discovery_filter(impl Into<Option<crate::deps::aws_cryptography_materialProviders::types::DiscoveryFilter>>) / set_discovery_filter(Option<crate::deps::aws_cryptography_materialProviders::types::DiscoveryFilter>): (undocumented)
    
  • grant_tokens(impl Into<Option<::std::vec::Vec<::std::string::String>>>) / set_grant_tokens(Option<::std::vec::Vec<::std::string::String>>): (undocumented)
    
  • kms_client(impl Into<Option<crate::deps::com_amazonaws_kms::client::Client>>) / set_kms_client(Option<crate::deps::com_amazonaws_kms::client::Client>): (undocumented)
    
• On success, responds with CreateKeyringOutput with field(s):
  • keyring(Option<crate::deps::aws_cryptography_materialProviders::types::keyring::KeyringRef>): (undocumented)
• On failure, responds with SdkError<CreateAwsKmsDiscoveryKeyringError>

impl Client

pub fn create_aws_kms_multi_keyring( &self, ) -> CreateAwsKmsMultiKeyringFluentBuilder

Constructs a fluent builder for the CreateAwsKmsMultiKeyring operation.

• The fluent builder is configurable:
  • client_supplier(impl Into<Option<crate::deps::aws_cryptography_materialProviders::types::client_supplier::ClientSupplierRef>>) / set_client_supplier(Option<crate::deps::aws_cryptography_materialProviders::types::client_supplier::ClientSupplierRef>): (undocumented)
    
  • generator(impl Into<Option<::std::string::String>>) / set_generator(Option<::std::string::String>): (undocumented)
    
  • grant_tokens(impl Into<Option<::std::vec::Vec<::std::string::String>>>) / set_grant_tokens(Option<::std::vec::Vec<::std::string::String>>): (undocumented)
    
  • kms_key_ids(impl Into<Option<::std::vec::Vec<::std::string::String>>>) / set_kms_key_ids(Option<::std::vec::Vec<::std::string::String>>): (undocumented)
    
• On success, responds with CreateKeyringOutput with field(s):
  • keyring(Option<crate::deps::aws_cryptography_materialProviders::types::keyring::KeyringRef>): (undocumented)
• On failure, responds with SdkError<CreateAwsKmsMultiKeyringError>

impl Client

pub fn create_aws_kms_discovery_multi_keyring( &self, ) -> CreateAwsKmsDiscoveryMultiKeyringFluentBuilder

Constructs a fluent builder for the CreateAwsKmsDiscoveryMultiKeyring operation.

• The fluent builder is configurable:
  • client_supplier(impl Into<Option<crate::deps::aws_cryptography_materialProviders::types::client_supplier::ClientSupplierRef>>) / set_client_supplier(Option<crate::deps::aws_cryptography_materialProviders::types::client_supplier::ClientSupplierRef>): (undocumented)
    
  • discovery_filter(impl Into<Option<crate::deps::aws_cryptography_materialProviders::types::DiscoveryFilter>>) / set_discovery_filter(Option<crate::deps::aws_cryptography_materialProviders::types::DiscoveryFilter>): (undocumented)
    
  • grant_tokens(impl Into<Option<::std::vec::Vec<::std::string::String>>>) / set_grant_tokens(Option<::std::vec::Vec<::std::string::String>>): (undocumented)
    
  • regions(impl Into<Option<::std::vec::Vec<::std::string::String>>>) / set_regions(Option<::std::vec::Vec<::std::string::String>>): (undocumented)
    
• On success, responds with CreateKeyringOutput with field(s):
  • keyring(Option<crate::deps::aws_cryptography_materialProviders::types::keyring::KeyringRef>): (undocumented)
• On failure, responds with SdkError<CreateAwsKmsDiscoveryMultiKeyringError>

impl Client

pub fn create_aws_kms_mrk_keyring(&self) -> CreateAwsKmsMrkKeyringFluentBuilder

Constructs a fluent builder for the CreateAwsKmsMrkKeyring operation.

• The fluent builder is configurable:
  • grant_tokens(impl Into<Option<::std::vec::Vec<::std::string::String>>>) / set_grant_tokens(Option<::std::vec::Vec<::std::string::String>>): (undocumented)
    
  • kms_client(impl Into<Option<crate::deps::com_amazonaws_kms::client::Client>>) / set_kms_client(Option<crate::deps::com_amazonaws_kms::client::Client>): (undocumented)
    
  • kms_key_id(impl Into<Option<::std::string::String>>) / set_kms_key_id(Option<::std::string::String>): (undocumented)
    
• On success, responds with CreateKeyringOutput with field(s):
  • keyring(Option<crate::deps::aws_cryptography_materialProviders::types::keyring::KeyringRef>): (undocumented)
• On failure, responds with SdkError<CreateAwsKmsMrkKeyringError>

impl Client

pub fn create_aws_kms_mrk_multi_keyring( &self, ) -> CreateAwsKmsMrkMultiKeyringFluentBuilder

Constructs a fluent builder for the CreateAwsKmsMrkMultiKeyring operation.

• The fluent builder is configurable:
  • client_supplier(impl Into<Option<crate::deps::aws_cryptography_materialProviders::types::client_supplier::ClientSupplierRef>>) / set_client_supplier(Option<crate::deps::aws_cryptography_materialProviders::types::client_supplier::ClientSupplierRef>): (undocumented)
    
  • generator(impl Into<Option<::std::string::String>>) / set_generator(Option<::std::string::String>): (undocumented)
    
  • grant_tokens(impl Into<Option<::std::vec::Vec<::std::string::String>>>) / set_grant_tokens(Option<::std::vec::Vec<::std::string::String>>): (undocumented)
    
  • kms_key_ids(impl Into<Option<::std::vec::Vec<::std::string::String>>>) / set_kms_key_ids(Option<::std::vec::Vec<::std::string::String>>): (undocumented)
    
• On success, responds with CreateKeyringOutput with field(s):
  • keyring(Option<crate::deps::aws_cryptography_materialProviders::types::keyring::KeyringRef>): (undocumented)
• On failure, responds with SdkError<CreateAwsKmsMrkMultiKeyringError>

Examples found in repository

examples/itemencryptor/item_encrypt_decrypt.rs (line 45)

pub async fn encrypt_decrypt() -> Result<(), crate::BoxError> {
    let kms_key_id = test_utils::TEST_KMS_KEY_ID;
    let ddb_table_name = test_utils::TEST_DDB_TABLE_NAME;

    // 1. Create a Keyring. This Keyring will be responsible for protecting the data keys that protect your data.
    //    For this example, we will create a AWS KMS Keyring with the AWS KMS Key we want to use.
    //    We will use the `CreateMrkMultiKeyring` method to create this keyring,
    //    as it will correctly handle both single region and Multi-Region KMS Keys.
    let provider_config = MaterialProvidersConfig::builder().build()?;
    let mat_prov = mpl_client::Client::from_conf(provider_config)?;
    let kms_keyring = mat_prov
        .create_aws_kms_mrk_multi_keyring()
        .generator(kms_key_id)
        .send()
        .await?;

    // 2. Configure which attributes are encrypted and/or signed when writing new items.
    //    For each attribute that may exist on the items we plan to write to our DynamoDbTable,
    //    we must explicitly configure how they should be treated during item encryption:
    //      - ENCRYPT_AND_SIGN: The attribute is encrypted and included in the signature
    //      - SIGN_ONLY: The attribute not encrypted, but is still included in the signature
    //      - DO_NOTHING: The attribute is not encrypted and not included in the signature
    let attribute_actions_on_encrypt = HashMap::from([
        ("partition_key".to_string(), CryptoAction::SignOnly),
        ("sort_key".to_string(), CryptoAction::SignOnly),
        ("attribute1".to_string(), CryptoAction::EncryptAndSign),
        ("attribute2".to_string(), CryptoAction::SignOnly),
        (":attribute3".to_string(), CryptoAction::DoNothing),
    ]);

    // 3. Configure which attributes we expect to be included in the signature
    //    when reading items. There are two options for configuring this:
    //
    //    - (Recommended) Configure `allowedUnsignedAttributesPrefix`:
    //      When defining your DynamoDb schema and deciding on attribute names,
    //      choose a distinguishing prefix (such as ":") for all attributes that
    //      you do not want to include in the signature.
    //      This has two main benefits:
    //      - It is easier to reason about the security and authenticity of data within your item
    //        when all unauthenticated data is easily distinguishable by their attribute name.
    //      - If you need to add new unauthenticated attributes in the future,
    //        you can easily make the corresponding update to your `attributeActionsOnEncrypt`
    //        and immediately start writing to that new attribute, without
    //        any other configuration update needed.
    //      Once you configure this field, it is not safe to update it.
    //
    //    - Configure `allowedUnsignedAttributes`: You may also explicitly list
    //      a set of attributes that should be considered unauthenticated when encountered
    //      on read. Be careful if you use this configuration. Do not remove an attribute
    //      name from this configuration, even if you are no longer writing with that attribute,
    //      as old items may still include this attribute, and our configuration needs to know
    //      to continue to exclude this attribute from the signature scope.
    //      If you add new attribute names to this field, you must first deploy the update to this
    //      field to all readers in your host fleet before deploying the update to start writing
    //      with that new attribute.
    //
    //   For this example, we have designed our DynamoDb table such that any attribute name with
    //   the ":" prefix should be considered unauthenticated.
    const UNSIGNED_ATTR_PREFIX: &str = ":";

    // 4. Create the configuration for the DynamoDb Item Encryptor
    let config = DynamoDbItemEncryptorConfig::builder()
        .logical_table_name(ddb_table_name)
        .partition_key_name("partition_key")
        .sort_key_name("sort_key")
        .attribute_actions_on_encrypt(attribute_actions_on_encrypt)
        .keyring(kms_keyring)
        .allowed_unsigned_attribute_prefix(UNSIGNED_ATTR_PREFIX)
        // Specifying an algorithm suite is not required,
        // but is done here to demonstrate how to do so.
        // We suggest using the
        // `ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY_ECDSA_P384_SYMSIG_HMAC_SHA384` suite,
        // which includes AES-GCM with key derivation, signing, and key commitment.
        // This is also the default algorithm suite if one is not specified in this config.
        // For more information on supported algorithm suites, see:
        //   https://docs.aws.amazon.com/database-encryption-sdk/latest/devguide/supported-algorithms.html
        .algorithm_suite_id(
            DbeAlgorithmSuiteId::AlgAes256GcmHkdfSha512CommitKeyEcdsaP384SymsigHmacSha384,
        )
        .build()?;

    // 5. Create the DynamoDb Item Encryptor
    let item_encryptor = enc_client::Client::from_conf(config)?;

    // 6. Directly encrypt a DynamoDb item using the DynamoDb Item Encryptor
    let original_item = HashMap::from([
        (
            "partition_key".to_string(),
            AttributeValue::S("ItemEncryptDecryptExample".to_string()),
        ),
        ("sort_key".to_string(), AttributeValue::N("0".to_string())),
        (
            "attribute1".to_string(),
            AttributeValue::S("encrypt and sign me!".to_string()),
        ),
        (
            "attribute2".to_string(),
            AttributeValue::S("sign me!".to_string()),
        ),
        (
            ":attribute3".to_string(),
            AttributeValue::S("ignore me!".to_string()),
        ),
    ]);

    let encrypted_item = item_encryptor
        .encrypt_item()
        .plaintext_item(original_item.clone())
        .send()
        .await?
        .encrypted_item
        .unwrap();

    // Demonstrate that the item has been encrypted
    assert_eq!(
        encrypted_item["partition_key"],
        AttributeValue::S("ItemEncryptDecryptExample".to_string())
    );
    assert_eq!(
        encrypted_item["sort_key"],
        AttributeValue::N("0".to_string())
    );
    assert!(encrypted_item["attribute1"].is_b());
    assert!(!encrypted_item["attribute1"].is_s());

    // 7. Directly decrypt the encrypted item using the DynamoDb Item Encryptor
    let decrypted_item = item_encryptor
        .decrypt_item()
        .encrypted_item(encrypted_item)
        .send()
        .await?
        .plaintext_item
        .unwrap();

    // Demonstrate that GetItem succeeded and returned the decrypted item
    assert_eq!(decrypted_item, original_item);
    println!("encrypt_decrypt successful.");
    Ok(())
}

examples/basic_get_put_example.rs (line 42)

pub async fn put_item_get_item() -> Result<(), crate::BoxError> {
    let kms_key_id = test_utils::TEST_KMS_KEY_ID;
    let ddb_table_name = test_utils::TEST_DDB_TABLE_NAME;

    // 1. Create a Keyring. This Keyring will be responsible for protecting the data keys that protect your data.
    //    For this example, we will create a AWS KMS Keyring with the AWS KMS Key we want to use.
    //    We will use the `CreateMrkMultiKeyring` method to create this keyring,
    //    as it will correctly handle both single region and Multi-Region KMS Keys.
    let provider_config = MaterialProvidersConfig::builder().build()?;
    let mat_prov = client::Client::from_conf(provider_config)?;
    let kms_keyring = mat_prov
        .create_aws_kms_mrk_multi_keyring()
        .generator(kms_key_id)
        .send()
        .await?;

    // 2. Configure which attributes are encrypted and/or signed when writing new items.
    //    For each attribute that may exist on the items we plan to write to our DynamoDbTable,
    //    we must explicitly configure how they should be treated during item encryption:
    //      - ENCRYPT_AND_SIGN: The attribute is encrypted and included in the signature
    //      - SIGN_ONLY: The attribute not encrypted, but is still included in the signature
    //      - DO_NOTHING: The attribute is not encrypted and not included in the signature
    let attribute_actions_on_encrypt = HashMap::from([
        ("partition_key".to_string(), CryptoAction::SignOnly),
        ("sort_key".to_string(), CryptoAction::SignOnly),
        ("attribute1".to_string(), CryptoAction::EncryptAndSign),
        ("attribute2".to_string(), CryptoAction::SignOnly),
        (":attribute3".to_string(), CryptoAction::DoNothing),
    ]);

    // 3. Configure which attributes we expect to be included in the signature
    //    when reading items. There are two options for configuring this:
    //
    //    - (Recommended) Configure `allowedUnsignedAttributesPrefix`:
    //      When defining your DynamoDb schema and deciding on attribute names,
    //      choose a distinguishing prefix (such as ":") for all attributes that
    //      you do not want to include in the signature.
    //      This has two main benefits:
    //      - It is easier to reason about the security and authenticity of data within your item
    //        when all unauthenticated data is easily distinguishable by their attribute name.
    //      - If you need to add new unauthenticated attributes in the future,
    //        you can easily make the corresponding update to your `attributeActionsOnEncrypt`
    //        and immediately start writing to that new attribute, without
    //        any other configuration update needed.
    //      Once you configure this field, it is not safe to update it.
    //
    //    - Configure `allowedUnsignedAttributes`: You may also explicitly list
    //      a set of attributes that should be considered unauthenticated when encountered
    //      on read. Be careful if you use this configuration. Do not remove an attribute
    //      name from this configuration, even if you are no longer writing with that attribute,
    //      as old items may still include this attribute, and our configuration needs to know
    //      to continue to exclude this attribute from the signature scope.
    //      If you add new attribute names to this field, you must first deploy the update to this
    //      field to all readers in your host fleet before deploying the update to start writing
    //      with that new attribute.
    //
    //   For this example, we have designed our DynamoDb table such that any attribute name with
    //   the ":" prefix should be considered unauthenticated.
    const UNSIGNED_ATTR_PREFIX: &str = ":";

    // 4. Create the DynamoDb Encryption configuration for the table we will be writing to.
    let table_config = DynamoDbTableEncryptionConfig::builder()
        .logical_table_name(ddb_table_name)
        .partition_key_name("partition_key")
        .sort_key_name("sort_key")
        .attribute_actions_on_encrypt(attribute_actions_on_encrypt)
        .keyring(kms_keyring)
        .allowed_unsigned_attribute_prefix(UNSIGNED_ATTR_PREFIX)
        // Specifying an algorithm suite is not required,
        // but is done here to demonstrate how to do so.
        // We suggest using the
        // `ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY_ECDSA_P384_SYMSIG_HMAC_SHA384` suite,
        // which includes AES-GCM with key derivation, signing, and key commitment.
        // This is also the default algorithm suite if one is not specified in this config.
        // For more information on supported algorithm suites, see:
        //   https://docs.aws.amazon.com/database-encryption-sdk/latest/devguide/supported-algorithms.html
        .algorithm_suite_id(
            DbeAlgorithmSuiteId::AlgAes256GcmHkdfSha512CommitKeyEcdsaP384SymsigHmacSha384,
        )
        .build()?;

    let table_configs = DynamoDbTablesEncryptionConfig::builder()
        .table_encryption_configs(HashMap::from([(ddb_table_name.to_string(), table_config)]))
        .build()?;

    // 5. Create a new AWS SDK DynamoDb client using the TableEncryptionConfigs
    let sdk_config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
    let dynamo_config = aws_sdk_dynamodb::config::Builder::from(&sdk_config)
        .interceptor(DbEsdkInterceptor::new(table_configs)?)
        .build();
    let ddb = aws_sdk_dynamodb::Client::from_conf(dynamo_config);

    // 6. Put an item into our table using the above client.
    //    Before the item gets sent to DynamoDb, it will be encrypted
    //    client-side, according to our configuration.
    let item = HashMap::from([
        (
            "partition_key".to_string(),
            AttributeValue::S("BasicPutGetExample".to_string()),
        ),
        ("sort_key".to_string(), AttributeValue::N("0".to_string())),
        (
            "attribute1".to_string(),
            AttributeValue::S("encrypt and sign me!".to_string()),
        ),
        (
            "attribute2".to_string(),
            AttributeValue::S("sign me!".to_string()),
        ),
        (
            ":attribute3".to_string(),
            AttributeValue::S("ignore me!".to_string()),
        ),
    ]);

    ddb.put_item()
        .table_name(ddb_table_name)
        .set_item(Some(item.clone()))
        .send()
        .await?;

    // 7. Get the item back from our table using the same client.
    //    The client will decrypt the item client-side, and return
    //    back the original item.
    let key_to_get = HashMap::from([
        (
            "partition_key".to_string(),
            AttributeValue::S("BasicPutGetExample".to_string()),
        ),
        ("sort_key".to_string(), AttributeValue::N("0".to_string())),
    ]);

    let resp = ddb
        .get_item()
        .table_name(ddb_table_name)
        .set_key(Some(key_to_get))
        // In this example we configure a strongly consistent read
        // because we perform a read immediately after a write (for demonstrative purposes).
        // By default, reads are only eventually consistent.
        // Read our docs to determine which read consistency to use for your application:
        // https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.ReadConsistency.html
        .consistent_read(true)
        .send()
        .await?;

    assert_eq!(resp.item, Some(item));
    println!("put_item_get_item successful.");
    Ok(())
}

examples/keyring/mrk_discovery_multi_keyring.rs (line 54)

pub async fn put_item_get_item() -> Result<(), crate::BoxError> {
    let ddb_table_name = test_utils::TEST_DDB_TABLE_NAME;
    let key_arn = test_utils::TEST_MRK_KEY_ID;
    let account_ids = vec![test_utils::TEST_AWS_ACCOUNT_ID.to_string()];
    let regions = vec![test_utils::TEST_AWS_REGION.to_string()];

    // 1. Create a single MRK multi-keyring using the key arn.
    //    Although this example demonstrates use of the MRK discovery multi-keyring,
    //    a discovery keyring cannot be used to encrypt. So we will need to construct
    //    a non-discovery keyring for this example to encrypt. For more information on MRK
    //    multi-keyrings, see the MultiMrkKeyringExample in this directory.
    //    Though this is an "MRK multi-keyring", we do not need to provide multiple keys,
    //    and can use single-region KMS keys. We will provide a single key here; this
    //    can be either an MRK or a single-region key.
    let mpl_config = MaterialProvidersConfig::builder().build()?;
    let mpl = mpl_client::Client::from_conf(mpl_config)?;
    let encrypt_keyring = mpl
        .create_aws_kms_mrk_multi_keyring()
        .generator(key_arn)
        .send()
        .await?;

    // 2. Configure which attributes are encrypted and/or signed when writing new items.
    //    For each attribute that may exist on the items we plan to write to our DynamoDbTable,
    //    we must explicitly configure how they should be treated during item encryption:
    //      - ENCRYPT_AND_SIGN: The attribute is encrypted and icncluded in the signature
    //      - SIGN_ONLY: The attribute not encrypted, but is still included in the signature
    //      - DO_NOTHING: The attribute is not encrypted and not included in the signature
    let attribute_actions_on_encrypt = HashMap::from([
        ("partition_key".to_string(), CryptoAction::SignOnly), // Our partition attribute must be SIGN_ONLY
        ("sort_key".to_string(), CryptoAction::SignOnly), // Our sort attribute must be SIGN_ONLY
        ("sensitive_data".to_string(), CryptoAction::EncryptAndSign),
    ]);

    // 3. Configure which attributes we expect to be included in the signature
    //    when reading items. There are two options for configuring this:
    //
    //    - (Recommended) Configure `allowedUnsignedAttributesPrefix`:
    //      When defining your DynamoDb schema and deciding on attribute names,
    //      choose a distinguishing prefix (such as ":") for all attributes that
    //      you do not want to include in the signature.
    //      This has two main benefits:
    //      - It is easier to reason about the security and authenticity of data within your item
    //        when all unauthenticated data is easily distinguishable by their attribute name.
    //      - If you need to add new unauthenticated attributes in the future,
    //        you can easily make the corresponding update to your `attributeActionsOnEncrypt`
    //        and immediately start writing to that new attribute, without
    //        any other configuration update needed.
    //      Once you configure this field, it is not safe to update it.
    //
    //    - Configure `allowedUnsignedAttributes`: You may also explicitly list
    //      a set of attributes that should be considered unauthenticated when encountered
    //      on read. Be careful if you use this configuration. Do not remove an attribute
    //      name from this configuration, even if you are no longer writing with that attribute,
    //      as old items may still include this attribute, and our configuration needs to know
    //      to continue to exclude this attribute from the signature scope.
    //      If you add new attribute names to this field, you must first deploy the update to this
    //      field to all readers in your host fleet before deploying the update to start writing
    //      with that new attribute.
    //
    //   For this example, we currently authenticate all attributes. To make it easier to
    //   add unauthenticated attributes in the future, we define a prefix ":" for such attributes.
    const UNSIGNED_ATTR_PREFIX: &str = ":";

    // 4. Create the DynamoDb Encryption configuration for the table we will be writing to.
    let table_config = DynamoDbTableEncryptionConfig::builder()
        .logical_table_name(ddb_table_name)
        .partition_key_name("partition_key")
        .sort_key_name("sort_key")
        .attribute_actions_on_encrypt(attribute_actions_on_encrypt.clone())
        .keyring(encrypt_keyring)
        .allowed_unsigned_attribute_prefix(UNSIGNED_ATTR_PREFIX)
        .build()?;

    let table_configs = DynamoDbTablesEncryptionConfig::builder()
        .table_encryption_configs(HashMap::from([(ddb_table_name.to_string(), table_config)]))
        .build()?;

    // 5. Create a new AWS SDK DynamoDb client using the config above
    let sdk_config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
    let dynamo_config = aws_sdk_dynamodb::config::Builder::from(&sdk_config)
        .interceptor(DbEsdkInterceptor::new(table_configs)?)
        .build();
    let ddb = aws_sdk_dynamodb::Client::from_conf(dynamo_config);

    // 6. Put an item into our table using the above client.
    //    Before the item gets sent to DynamoDb, it will be encrypted
    //    client-side using the MRK multi-keyring.
    let item = HashMap::from([
        (
            "partition_key".to_string(),
            AttributeValue::S("awsKmsMrkDiscoveryMultiKeyringItem".to_string()),
        ),
        ("sort_key".to_string(), AttributeValue::N("0".to_string())),
        (
            "sensitive_data".to_string(),
            AttributeValue::S("encrypt and sign me!".to_string()),
        ),
    ]);

    ddb.put_item()
        .table_name(ddb_table_name)
        .set_item(Some(item.clone()))
        .send()
        .await?;

    // 7. Construct a discovery filter.
    //    A discovery filter limits the set of encrypted data keys
    //    the keyring can use to decrypt data.
    //    We will only let the keyring use keys in the selected AWS accounts
    //    and in the `aws` partition.
    //    This is the suggested config for most users; for more detailed config, see
    //      https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/use-kms-keyring.html#kms-keyring-discovery
    let discovery_filter = DiscoveryFilter::builder()
        .partition("aws")
        .account_ids(account_ids)
        .build()?;

    // 8. Construct a discovery keyring.
    //    Note that we choose to use the MRK discovery multi-keyring, even though
    //    our original keyring used a single KMS key.

    let decrypt_keyring = mpl
        .create_aws_kms_mrk_discovery_multi_keyring()
        .discovery_filter(discovery_filter)
        .regions(regions)
        .send()
        .await?;

    // 9. Create new DDB config and client using the decrypt discovery keyring.
    //     This is the same as the above config, except we pass in the decrypt keyring.
    let table_config_for_decrypt = DynamoDbTableEncryptionConfig::builder()
        .logical_table_name(ddb_table_name)
        .partition_key_name("partition_key")
        .sort_key_name("sort_key")
        .attribute_actions_on_encrypt(attribute_actions_on_encrypt)
        .keyring(decrypt_keyring)
        .allowed_unsigned_attribute_prefix(UNSIGNED_ATTR_PREFIX)
        .build()?;

    let table_configs_for_decrypt = DynamoDbTablesEncryptionConfig::builder()
        .table_encryption_configs(HashMap::from([(
            ddb_table_name.to_string(),
            table_config_for_decrypt,
        )]))
        .build()?;

    let dynamo_config_for_decrypt = aws_sdk_dynamodb::config::Builder::from(&sdk_config)
        .interceptor(DbEsdkInterceptor::new(table_configs_for_decrypt)?)
        .build();
    let ddb_for_decrypt = aws_sdk_dynamodb::Client::from_conf(dynamo_config_for_decrypt);

    // 10. Get the item back from our table using the client.
    //     The client will retrieve encrypted items from the DDB table, then
    //     detect the KMS key that was used to encrypt their data keys.
    //     The client will make a request to KMS to decrypt with the encrypting KMS key.
    //     If the client has permission to decrypt with the KMS key,
    //     the client will decrypt the item client-side using the keyring
    //     and return the original item.
    let key_to_get = HashMap::from([
        (
            "partition_key".to_string(),
            AttributeValue::S("awsKmsMrkDiscoveryMultiKeyringItem".to_string()),
        ),
        ("sort_key".to_string(), AttributeValue::N("0".to_string())),
    ]);

    let resp = ddb_for_decrypt
        .get_item()
        .table_name(ddb_table_name)
        .set_key(Some(key_to_get))
        .consistent_read(true)
        .send()
        .await?;

    assert_eq!(resp.item, Some(item));

    println!("mrk_discovery_multi_keyring successful.");
    Ok(())
}

examples/keyring/multi_keyring.rs (line 68)

pub async fn put_item_get_item() -> Result<(), crate::BoxError> {
    let ddb_table_name = test_utils::TEST_DDB_TABLE_NAME;
    let key_arn = test_utils::TEST_KMS_KEY_ID;
    let aes_key_bytes = generate_aes_key_bytes();

    // 1. Create the raw AES keyring.
    let mpl_config = MaterialProvidersConfig::builder().build()?;
    let mpl = mpl_client::Client::from_conf(mpl_config)?;
    let raw_aes_keyring = mpl
        .create_raw_aes_keyring()
        .key_name("my-aes-key-name")
        .key_namespace("my-key-namespace")
        .wrapping_key(aes_key_bytes)
        .wrapping_alg(AesWrappingAlg::AlgAes256GcmIv12Tag16)
        .send()
        .await?;

    // 2. Create the AWS KMS keyring.
    //    We create a MRK multi keyring, as this interface also supports
    //    single-region KMS keys (standard KMS keys),
    //    and creates the KMS client for us automatically.
    let aws_kms_mrk_multi_keyring = mpl
        .create_aws_kms_mrk_multi_keyring()
        .generator(key_arn)
        .send()
        .await?;

    // 3. Create the multi-keyring.
    //    We will label the AWS KMS keyring as the generator and the raw AES keyring as the
    //        only child keyring.
    //    You must provide a generator keyring to encrypt data.
    //    You may provide additional child keyrings. Each child keyring will be able to
    //        decrypt data encrypted with the multi-keyring on its own. It does not need
    //        knowledge of any other child keyrings or the generator keyring to decrypt.

    let multi_keyring = mpl
        .create_multi_keyring()
        .generator(aws_kms_mrk_multi_keyring)
        .child_keyrings(vec![raw_aes_keyring.clone()])
        .send()
        .await?;

    // 4. Configure which attributes are encrypted and/or signed when writing new items.
    //    For each attribute that may exist on the items we plan to write to our DynamoDbTable,
    //    we must explicitly configure how they should be treated during item encryption:
    //      - ENCRYPT_AND_SIGN: The attribute is encrypted and included in the signature
    //      - SIGN_ONLY: The attribute not encrypted, but is still included in the signature
    //      - DO_NOTHING: The attribute is not encrypted and not included in the signature
    let attribute_actions_on_encrypt = HashMap::from([
        ("partition_key".to_string(), CryptoAction::SignOnly), // Our partition attribute must be SIGN_ONLY
        ("sort_key".to_string(), CryptoAction::SignOnly), // Our sort attribute must be SIGN_ONLY
        ("sensitive_data".to_string(), CryptoAction::EncryptAndSign),
    ]);

    // 5. Configure which attributes we expect to be included in the signature
    //    when reading items. There are two options for configuring this:
    //
    //    - (Recommended) Configure `allowedUnsignedAttributesPrefix`:
    //      When defining your DynamoDb schema and deciding on attribute names,
    //      choose a distinguishing prefix (such as ":") for all attributes that
    //      you do not want to include in the signature.
    //      This has two main benefits:
    //      - It is easier to reason about the security and authenticity of data within your item
    //        when all unauthenticated data is easily distinguishable by their attribute name.
    //      - If you need to add new unauthenticated attributes in the future,
    //        you can easily make the corresponding update to your `attributeActionsOnEncrypt`
    //        and immediately start writing to that new attribute, without
    //        any other configuration update needed.
    //      Once you configure this field, it is not safe to update it.
    //
    //    - Configure `allowedUnsignedAttributes`: You may also explicitly list
    //      a set of attributes that should be considered unauthenticated when encountered
    //      on read. Be careful if you use this configuration. Do not remove an attribute
    //      name from this configuration, even if you are no longer writing with that attribute,
    //      as old items may still include this attribute, and our configuration needs to know
    //      to continue to exclude this attribute from the signature scope.
    //      If you add new attribute names to this field, you must first deploy the update to this
    //      field to all readers in your host fleet before deploying the update to start writing
    //      with that new attribute.
    //
    //   For this example, we currently authenticate all attributes. To make it easier to
    //   add unauthenticated attributes in the future, we define a prefix ":" for such attributes.
    const UNSIGNED_ATTR_PREFIX: &str = ":";

    // 6. Create the DynamoDb Encryption configuration for the table we will be writing to.
    //    Note that this example creates one config/client combination for PUT, and another
    //        for GET. The PUT config uses the multi-keyring, while the GET config uses the
    //        raw AES keyring. This is solely done to demonstrate that a keyring included as
    //        a child of a multi-keyring can be used to decrypt data on its own.
    let table_config = DynamoDbTableEncryptionConfig::builder()
        .logical_table_name(ddb_table_name)
        .partition_key_name("partition_key")
        .sort_key_name("sort_key")
        .attribute_actions_on_encrypt(attribute_actions_on_encrypt.clone())
        .keyring(multi_keyring)
        .allowed_unsigned_attribute_prefix(UNSIGNED_ATTR_PREFIX)
        .build()?;

    let table_configs = DynamoDbTablesEncryptionConfig::builder()
        .table_encryption_configs(HashMap::from([(ddb_table_name.to_string(), table_config)]))
        .build()?;

    // 7. Create a new AWS SDK DynamoDb client using the config above
    let sdk_config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
    let dynamo_config = aws_sdk_dynamodb::config::Builder::from(&sdk_config)
        .interceptor(DbEsdkInterceptor::new(table_configs)?)
        .build();
    let ddb = aws_sdk_dynamodb::Client::from_conf(dynamo_config);

    // 8. Put an item into our table using the above client.
    //    Before the item gets sent to DynamoDb, it will be encrypted
    //    client-side using the multi-keyring.
    //    The item will be encrypted with all wrapping keys in the keyring,
    //    so that it can be decrypted with any one of the keys.
    let item = HashMap::from([
        (
            "partition_key".to_string(),
            AttributeValue::S("multiKeyringItem".to_string()),
        ),
        ("sort_key".to_string(), AttributeValue::N("0".to_string())),
        (
            "sensitive_data".to_string(),
            AttributeValue::S("encrypt and sign me!".to_string()),
        ),
    ]);

    ddb.put_item()
        .table_name(ddb_table_name)
        .set_item(Some(item.clone()))
        .send()
        .await?;

    // 9. Get the item back from our table using the above client.
    //     The client will decrypt the item client-side using the AWS KMS
    //     keyring, and return back the original item.
    //     Since the generator key is the first available key in the keyring,
    //     that is the key that will be used to decrypt this item.
    let key_to_get = HashMap::from([
        (
            "partition_key".to_string(),
            AttributeValue::S("multiKeyringItem".to_string()),
        ),
        ("sort_key".to_string(), AttributeValue::N("0".to_string())),
    ]);

    let resp = ddb
        .get_item()
        .table_name(ddb_table_name)
        .set_key(Some(key_to_get.clone()))
        .consistent_read(true)
        .send()
        .await?;

    assert_eq!(resp.item, Some(item.clone()));

    // 10. Create a new config and client with only the raw AES keyring to GET the item
    //     This is the same setup as above, except the config uses the `rawAesKeyring`.
    let only_aes_table_config = DynamoDbTableEncryptionConfig::builder()
        .logical_table_name(ddb_table_name)
        .partition_key_name("partition_key")
        .sort_key_name("sort_key")
        .attribute_actions_on_encrypt(attribute_actions_on_encrypt)
        .keyring(raw_aes_keyring)
        .allowed_unsigned_attribute_prefix(UNSIGNED_ATTR_PREFIX)
        .build()?;

    let only_aes_table_configs = DynamoDbTablesEncryptionConfig::builder()
        .table_encryption_configs(HashMap::from([(
            ddb_table_name.to_string(),
            only_aes_table_config,
        )]))
        .build()?;

    let only_aes_dynamo_config = aws_sdk_dynamodb::config::Builder::from(&sdk_config)
        .interceptor(DbEsdkInterceptor::new(only_aes_table_configs)?)
        .build();
    let only_aes_ddb = aws_sdk_dynamodb::Client::from_conf(only_aes_dynamo_config);

    // 11. Get the item back from our table using the client
    //     configured with only the raw AES keyring.
    //     The client will decrypt the item client-side using the raw
    //     AES keyring, and return back the original item.
    let resp = only_aes_ddb
        .get_item()
        .table_name(ddb_table_name)
        .set_key(Some(key_to_get.clone()))
        .consistent_read(true)
        .send()
        .await?;

    assert_eq!(resp.item, Some(item.clone()));

    println!("multi_keyring successful.");
    Ok(())
}

examples/multi_get_put_example.rs (line 42)

pub async fn multi_put_get() -> Result<(), crate::BoxError> {
    let kms_key_id = test_utils::TEST_KMS_KEY_ID;
    let ddb_table_name = test_utils::TEST_DDB_TABLE_NAME;

    // 1. Create a Keyring. This Keyring will be responsible for protecting the data keys that protect your data.
    //    For this example, we will create a AWS KMS Keyring with the AWS KMS Key we want to use.
    //    We will use the `CreateMrkMultiKeyring` method to create this keyring,
    //    as it will correctly handle both single region and Multi-Region KMS Keys.
    let provider_config = MaterialProvidersConfig::builder().build()?;
    let mat_prov = client::Client::from_conf(provider_config)?;
    let kms_keyring = mat_prov
        .create_aws_kms_mrk_multi_keyring()
        .generator(kms_key_id)
        .send()
        .await?;

    // 2. Configure which attributes are encrypted and/or signed when writing new items.
    //    For each attribute that may exist on the items we plan to write to our DynamoDbTable,
    //    we must explicitly configure how they should be treated during item encryption:
    //      - ENCRYPT_AND_SIGN: The attribute is encrypted and included in the signature
    //      - SIGN_ONLY: The attribute not encrypted, but is still included in the signature
    //      - DO_NOTHING: The attribute is not encrypted and not included in the signature
    let attribute_actions_on_encrypt = HashMap::from([
        ("partition_key".to_string(), CryptoAction::SignOnly),
        ("sort_key".to_string(), CryptoAction::SignOnly),
        ("attribute1".to_string(), CryptoAction::EncryptAndSign),
        ("attribute2".to_string(), CryptoAction::SignOnly),
        (":attribute3".to_string(), CryptoAction::DoNothing),
    ]);

    // 3. Configure which attributes we expect to be included in the signature
    //    when reading items. There are two options for configuring this:
    //
    //    - (Recommended) Configure `allowedUnsignedAttributesPrefix`:
    //      When defining your DynamoDb schema and deciding on attribute names,
    //      choose a distinguishing prefix (such as ":") for all attributes that
    //      you do not want to include in the signature.
    //      This has two main benefits:
    //      - It is easier to reason about the security and authenticity of data within your item
    //        when all unauthenticated data is easily distinguishable by their attribute name.
    //      - If you need to add new unauthenticated attributes in the future,
    //        you can easily make the corresponding update to your `attributeActionsOnEncrypt`
    //        and immediately start writing to that new attribute, without
    //        any other configuration update needed.
    //      Once you configure this field, it is not safe to update it.
    //
    //    - Configure `allowedUnsignedAttributes`: You may also explicitly list
    //      a set of attributes that should be considered unauthenticated when encountered
    //      on read. Be careful if you use this configuration. Do not remove an attribute
    //      name from this configuration, even if you are no longer writing with that attribute,
    //      as old items may still include this attribute, and our configuration needs to know
    //      to continue to exclude this attribute from the signature scope.
    //      If you add new attribute names to this field, you must first deploy the update to this
    //      field to all readers in your host fleet before deploying the update to start writing
    //      with that new attribute.
    //
    //   For this example, we have designed our DynamoDb table such that any attribute name with
    //   the ":" prefix should be considered unauthenticated.
    const UNSIGNED_ATTR_PREFIX: &str = ":";

    // 4. Create the DynamoDb Encryption configuration for the table we will be writing to.
    let table_config = DynamoDbTableEncryptionConfig::builder()
        .logical_table_name(ddb_table_name)
        .partition_key_name("partition_key")
        .sort_key_name("sort_key")
        .attribute_actions_on_encrypt(attribute_actions_on_encrypt)
        .keyring(kms_keyring)
        .allowed_unsigned_attribute_prefix(UNSIGNED_ATTR_PREFIX)
        // Specifying an algorithm suite is not required,
        // but is done here to demonstrate how to do so.
        // We suggest using the
        // `ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY_ECDSA_P384_SYMSIG_HMAC_SHA384` suite,
        // which includes AES-GCM with key derivation, signing, and key commitment.
        // This is also the default algorithm suite if one is not specified in this config.
        // For more information on supported algorithm suites, see:
        //   https://docs.aws.amazon.com/database-encryption-sdk/latest/devguide/supported-algorithms.html
        .algorithm_suite_id(
            DbeAlgorithmSuiteId::AlgAes256GcmHkdfSha512CommitKeyEcdsaP384SymsigHmacSha384,
        )
        .build()?;

    let table_configs = DynamoDbTablesEncryptionConfig::builder()
        .table_encryption_configs(HashMap::from([(ddb_table_name.to_string(), table_config)]))
        .build()?;

    // 5. Create a new AWS SDK DynamoDb client using the TableEncryptionConfigs
    let sdk_config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
    let dynamo_config = aws_sdk_dynamodb::config::Builder::from(&sdk_config)
        .interceptor(DbEsdkInterceptor::new(table_configs)?)
        .build();
    let ddb = aws_sdk_dynamodb::Client::from_conf(dynamo_config);

    // 6. Put an item into our table using the above client.
    //    Before the item gets sent to DynamoDb, it will be encrypted
    //    client-side, according to our configuration.
    let batch_write_item = HashMap::from([
        (
            "partition_key".to_string(),
            AttributeValue::S("BatchWriteItemExample".to_string()),
        ),
        ("sort_key".to_string(), AttributeValue::N("0".to_string())),
        (
            "attribute1".to_string(),
            AttributeValue::S("encrypt and sign me!".to_string()),
        ),
        (
            "attribute2".to_string(),
            AttributeValue::S("sign me!".to_string()),
        ),
        (
            ":attribute3".to_string(),
            AttributeValue::S("ignore me!".to_string()),
        ),
    ]);
    let put_request = aws_sdk_dynamodb::types::PutRequest::builder()
        .set_item(Some(batch_write_item))
        .build()?;

    let batch_write_request = aws_sdk_dynamodb::types::WriteRequest::builder()
        .put_request(put_request)
        .build();

    let transact_write_item = HashMap::from([
        (
            "partition_key".to_string(),
            AttributeValue::S("TransactWriteItemExample".to_string()),
        ),
        ("sort_key".to_string(), AttributeValue::N("0".to_string())),
        (
            "attribute1".to_string(),
            AttributeValue::S("encrypt and sign me!".to_string()),
        ),
        (
            "attribute2".to_string(),
            AttributeValue::S("sign me!".to_string()),
        ),
        (
            ":attribute3".to_string(),
            AttributeValue::S("ignore me!".to_string()),
        ),
    ]);
    let transact_put = aws_sdk_dynamodb::types::Put::builder()
        .table_name(ddb_table_name)
        .set_item(Some(transact_write_item))
        .build()?;

    let transact_item = aws_sdk_dynamodb::types::TransactWriteItem::builder()
        .put(transact_put)
        .build();

    ddb.batch_write_item()
        .request_items(ddb_table_name, vec![batch_write_request])
        .send()
        .await?;

    ddb.transact_write_items()
        .transact_items(transact_item)
        .send()
        .await?;

    // 7. Get the item back from our table using the same client.
    //    The client will decrypt the item client-side, and return
    //    back the original item.
    let batch_get_keys = HashMap::from([
        (
            "partition_key".to_string(),
            AttributeValue::S("BatchWriteItemExample".to_string()),
        ),
        ("sort_key".to_string(), AttributeValue::N("0".to_string())),
    ]);
    let keys_and_attr = aws_sdk_dynamodb::types::KeysAndAttributes::builder()
        .keys(batch_get_keys)
        .consistent_read(true)
        .build()?;

    let batch_get_response = ddb
        .batch_get_item()
        .request_items(ddb_table_name, keys_and_attr)
        .send()
        .await?;

    let returned_item = &batch_get_response.responses.unwrap()[ddb_table_name][0];
    assert_eq!(
        returned_item["attribute1"],
        AttributeValue::S("encrypt and sign me!".to_string())
    );

    let transact_get_keys = HashMap::from([
        (
            "partition_key".to_string(),
            AttributeValue::S("TransactWriteItemExample".to_string()),
        ),
        ("sort_key".to_string(), AttributeValue::N("0".to_string())),
    ]);
    let transact_get = aws_sdk_dynamodb::types::Get::builder()
        .table_name(ddb_table_name)
        .set_key(Some(transact_get_keys))
        .build()?;

    let transact_get_item = aws_sdk_dynamodb::types::TransactGetItem::builder()
        .get(transact_get)
        .build();

    let transact_get_response = ddb
        .transact_get_items()
        .transact_items(transact_get_item)
        .send()
        .await?;

    let the_item = transact_get_response.responses.as_ref().unwrap()[0]
        .item
        .as_ref()
        .unwrap();
    assert_eq!(
        the_item["attribute1"],
        AttributeValue::S("encrypt and sign me!".to_string())
    );

    println!("multi_put_get successful.");
    Ok(())
}

examples/clientsupplier/client_supplier_example.rs (line 61)

pub async fn put_item_get_item() -> Result<(), crate::BoxError> {
    let ddb_table_name = test_utils::TEST_DDB_TABLE_NAME;
    // Note that we pass in an MRK in us-east-1...
    let key_arn = test_utils::TEST_MRK_REPLICA_KEY_ID_US_EAST_1.to_string();
    let account_ids = vec![test_utils::TEST_AWS_ACCOUNT_ID.to_string()];
    // ...and access its replica in eu-west-1
    let regions = vec!["eu-west-1".to_string()];

    // 1. Create a single MRK multi-keyring.
    //    This can be either a single-region KMS key or an MRK.
    //    For this example to succeed, the key's region must either
    //    1) be in the regions list, or
    //    2) the key must be an MRK with a replica defined
    //    in a region in the regions list, and the client
    //    must have the correct permissions to access the replica.
    let mpl_config = MaterialProvidersConfig::builder().build()?;
    let mpl = mpl_client::Client::from_conf(mpl_config)?;

    // Create the multi-keyring using our custom client supplier
    // defined in the RegionalRoleClientSupplier class in this directory.
    // Note: RegionalRoleClientSupplier will internally use the key_arn's region
    // to retrieve the correct IAM role.

    let mrk_keyring_with_client_supplier = mpl
        .create_aws_kms_mrk_multi_keyring()
        .client_supplier(RegionalRoleClientSupplier {})
        .generator(key_arn)
        .send()
        .await?;

    // 2. Configure which attributes are encrypted and/or signed when writing new items.
    //    For each attribute that may exist on the items we plan to write to our DynamoDbTable,
    //    we must explicitly configure how they should be treated during item encryption:
    //      - ENCRYPT_AND_SIGN: The attribute is encrypted and included in the signature
    //      - SIGN_ONLY: The attribute is not encrypted, but is still included in the signature
    //      - DO_NOTHING: The attribute is not encrypted and not included in the signature
    let attribute_actions_on_encrypt = HashMap::from([
        ("partition_key".to_string(), CryptoAction::SignOnly), // Our partition attribute must be SIGN_ONLY
        ("sort_key".to_string(), CryptoAction::SignOnly), // Our sort attribute must be SIGN_ONLY
        ("sensitive_data".to_string(), CryptoAction::EncryptAndSign),
    ]);

    // 3. Configure which attributes we expect to be included in the signature
    //    when reading items. There are two options for configuring this:
    //
    //    - (Recommended) Configure `allowedUnsignedAttributesPrefix`:
    //      When defining your DynamoDb schema and deciding on attribute names,
    //      choose a distinguishing prefix (such as ":") for all attributes that
    //      you do not want to include in the signature.
    //      This has two main benefits:
    //      - It is easier to reason about the security and authenticity of data within your item
    //        when all unauthenticated data is easily distinguishable by their attribute name.
    //      - If you need to add new unauthenticated attributes in the future,
    //        you can easily make the corresponding update to your `attributeActionsOnEncrypt`
    //        and immediately start writing to that new attribute, without
    //        any other configuration update needed.
    //      Once you configure this field, it is not safe to update it.
    //
    //    - Configure `allowedUnsignedAttributes`: You may also explicitly list
    //      a set of attributes that should be considered unauthenticated when encountered
    //      on read. Be careful if you use this configuration. Do not remove an attribute
    //      name from this configuration, even if you are no longer writing with that attribute,
    //      as old items may still include this attribute, and our configuration needs to know
    //      to continue to exclude this attribute from the signature scope.
    //      If you add new attribute names to this field, you must first deploy the update to this
    //      field to all readers in your host fleet before deploying the update to start writing
    //      with that new attribute.
    //
    //   For this example, we currently authenticate all attributes. To make it easier to
    //   add unauthenticated attributes in the future, we define a prefix ":" for such attributes.
    const UNSIGNED_ATTR_PREFIX: &str = ":";

    // 4. Create the DynamoDb Encryption configuration for the table we will be writing to.
    let table_config = DynamoDbTableEncryptionConfig::builder()
        .logical_table_name(ddb_table_name)
        .partition_key_name("partition_key")
        .sort_key_name("sort_key")
        .attribute_actions_on_encrypt(attribute_actions_on_encrypt.clone())
        .keyring(mrk_keyring_with_client_supplier)
        .allowed_unsigned_attribute_prefix(UNSIGNED_ATTR_PREFIX)
        .build()?;

    let table_configs = DynamoDbTablesEncryptionConfig::builder()
        .table_encryption_configs(HashMap::from([(ddb_table_name.to_string(), table_config)]))
        .build()?;

    // 5. Create a new AWS SDK DynamoDb client using the DynamoDb Config above
    let sdk_config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
    let dynamo_config = aws_sdk_dynamodb::config::Builder::from(&sdk_config)
        .interceptor(DbEsdkInterceptor::new(table_configs)?)
        .build();
    let ddb = aws_sdk_dynamodb::Client::from_conf(dynamo_config);

    // 6. Put an item into our table using the above client.
    //    Before the item gets sent to DynamoDb, it will be encrypted
    //    client-side using the MRK multi-keyring.
    //    The data key protecting this item will be encrypted
    //    with all the KMS Keys in this keyring, so that it can be
    //    decrypted with any one of those KMS Keys.
    let item = HashMap::from([
        (
            "partition_key".to_string(),
            AttributeValue::S("clientSupplierItem".to_string()),
        ),
        ("sort_key".to_string(), AttributeValue::N("0".to_string())),
        (
            "sensitive_data".to_string(),
            AttributeValue::S("encrypt and sign me!".to_string()),
        ),
    ]);

    ddb.put_item()
        .table_name(ddb_table_name)
        .set_item(Some(item.clone()))
        .send()
        .await?;

    // 7. Get the item back from our table using the same keyring.
    //    The client will decrypt the item client-side using the MRK
    //    and return the original item.
    let key_to_get = HashMap::from([
        (
            "partition_key".to_string(),
            AttributeValue::S("clientSupplierItem".to_string()),
        ),
        ("sort_key".to_string(), AttributeValue::N("0".to_string())),
    ]);

    let resp = ddb
        .get_item()
        .table_name(ddb_table_name)
        .set_key(Some(key_to_get.clone()))
        .consistent_read(true)
        .send()
        .await?;

    assert_eq!(
        resp.item.unwrap()["sensitive_data"],
        AttributeValue::S("encrypt and sign me!".to_string())
    );

    // 8. Create a MRK discovery multi-keyring with a custom client supplier.
    //    A discovery MRK multi-keyring will be composed of
    //    multiple discovery MRK keyrings, one for each region.
    //    Each component keyring has its own KMS client in a particular region.
    //    When we provide a client supplier to the multi-keyring, all component
    //    keyrings will use that client supplier configuration.
    //    In our tests, we make `key_arn` an MRK with a replica, and
    //    provide only the replica region in our discovery filter.
    let discovery_filter = DiscoveryFilter::builder()
        .partition("aws")
        .account_ids(account_ids)
        .build()?;

    let mrk_discovery_client_supplier_keyring = mpl
        .create_aws_kms_mrk_discovery_multi_keyring()
        .client_supplier(RegionalRoleClientSupplier {})
        .discovery_filter(discovery_filter)
        .regions(regions)
        .send()
        .await?;

    // 9. Create a new config and client using the discovery keyring.
    //     This is the same setup as above, except we provide the discovery keyring to the config.
    let only_replica_table_config = DynamoDbTableEncryptionConfig::builder()
        .logical_table_name(ddb_table_name)
        .partition_key_name("partition_key")
        .sort_key_name("sort_key")
        .attribute_actions_on_encrypt(attribute_actions_on_encrypt)
        .keyring(mrk_discovery_client_supplier_keyring)
        .allowed_unsigned_attribute_prefix(UNSIGNED_ATTR_PREFIX)
        .build()?;

    let only_replica_table_configs = DynamoDbTablesEncryptionConfig::builder()
        .table_encryption_configs(HashMap::from([(
            ddb_table_name.to_string(),
            only_replica_table_config,
        )]))
        .build()?;

    let only_replica_dynamo_config = aws_sdk_dynamodb::config::Builder::from(&sdk_config)
        .interceptor(DbEsdkInterceptor::new(only_replica_table_configs)?)
        .build();
    let only_replica_ddb = aws_sdk_dynamodb::Client::from_conf(only_replica_dynamo_config);

    // 10. Get the item back from our table using the discovery keyring client.
    //     The client will decrypt the item client-side using the keyring,
    //     and return the original item.
    //     The discovery keyring will only use KMS keys in the provided regions and
    //     AWS accounts. Since we have provided it with a custom client supplier
    //     which uses different IAM roles based on the key region,
    //     the discovery keyring will use a particular IAM role to decrypt
    //     based on the region of the KMS key it uses to decrypt.

    let resp = only_replica_ddb
        .get_item()
        .table_name(ddb_table_name)
        .set_key(Some(key_to_get))
        .consistent_read(true)
        .send()
        .await?;

    assert_eq!(
        resp.item.unwrap()["sensitive_data"],
        AttributeValue::S("encrypt and sign me!".to_string())
    );

    println!("client_supplier_example successful.");
    Ok(())
}

Additional examples can be found in:

• examples/keyring/multi_mrk_keyring.rs

impl Client

pub fn create_aws_kms_mrk_discovery_keyring( &self, ) -> CreateAwsKmsMrkDiscoveryKeyringFluentBuilder

Constructs a fluent builder for the CreateAwsKmsMrkDiscoveryKeyring operation.

• The fluent builder is configurable:
  • discovery_filter(impl Into<Option<crate::deps::aws_cryptography_materialProviders::types::DiscoveryFilter>>) / set_discovery_filter(Option<crate::deps::aws_cryptography_materialProviders::types::DiscoveryFilter>): (undocumented)
    
  • grant_tokens(impl Into<Option<::std::vec::Vec<::std::string::String>>>) / set_grant_tokens(Option<::std::vec::Vec<::std::string::String>>): (undocumented)
    
  • kms_client(impl Into<Option<crate::deps::com_amazonaws_kms::client::Client>>) / set_kms_client(Option<crate::deps::com_amazonaws_kms::client::Client>): (undocumented)
    
  • region(impl Into<Option<::std::string::String>>) / set_region(Option<::std::string::String>): (undocumented)
    
• On success, responds with CreateKeyringOutput with field(s):
  • keyring(Option<crate::deps::aws_cryptography_materialProviders::types::keyring::KeyringRef>): (undocumented)
• On failure, responds with SdkError<CreateAwsKmsMrkDiscoveryKeyringError>

impl Client

pub fn create_aws_kms_mrk_discovery_multi_keyring( &self, ) -> CreateAwsKmsMrkDiscoveryMultiKeyringFluentBuilder

Constructs a fluent builder for the CreateAwsKmsMrkDiscoveryMultiKeyring operation.

• The fluent builder is configurable:
  • client_supplier(impl Into<Option<crate::deps::aws_cryptography_materialProviders::types::client_supplier::ClientSupplierRef>>) / set_client_supplier(Option<crate::deps::aws_cryptography_materialProviders::types::client_supplier::ClientSupplierRef>): (undocumented)
    
  • discovery_filter(impl Into<Option<crate::deps::aws_cryptography_materialProviders::types::DiscoveryFilter>>) / set_discovery_filter(Option<crate::deps::aws_cryptography_materialProviders::types::DiscoveryFilter>): (undocumented)
    
  • grant_tokens(impl Into<Option<::std::vec::Vec<::std::string::String>>>) / set_grant_tokens(Option<::std::vec::Vec<::std::string::String>>): (undocumented)
    
  • regions(impl Into<Option<::std::vec::Vec<::std::string::String>>>) / set_regions(Option<::std::vec::Vec<::std::string::String>>): (undocumented)
    
• On success, responds with CreateKeyringOutput with field(s):
  • keyring(Option<crate::deps::aws_cryptography_materialProviders::types::keyring::KeyringRef>): (undocumented)
• On failure, responds with SdkError<CreateAwsKmsMrkDiscoveryMultiKeyringError>

Examples found in repository

examples/keyring/mrk_discovery_multi_keyring.rs (line 160)

pub async fn put_item_get_item() -> Result<(), crate::BoxError> {
    let ddb_table_name = test_utils::TEST_DDB_TABLE_NAME;
    let key_arn = test_utils::TEST_MRK_KEY_ID;
    let account_ids = vec![test_utils::TEST_AWS_ACCOUNT_ID.to_string()];
    let regions = vec![test_utils::TEST_AWS_REGION.to_string()];

    // 1. Create a single MRK multi-keyring using the key arn.
    //    Although this example demonstrates use of the MRK discovery multi-keyring,
    //    a discovery keyring cannot be used to encrypt. So we will need to construct
    //    a non-discovery keyring for this example to encrypt. For more information on MRK
    //    multi-keyrings, see the MultiMrkKeyringExample in this directory.
    //    Though this is an "MRK multi-keyring", we do not need to provide multiple keys,
    //    and can use single-region KMS keys. We will provide a single key here; this
    //    can be either an MRK or a single-region key.
    let mpl_config = MaterialProvidersConfig::builder().build()?;
    let mpl = mpl_client::Client::from_conf(mpl_config)?;
    let encrypt_keyring = mpl
        .create_aws_kms_mrk_multi_keyring()
        .generator(key_arn)
        .send()
        .await?;

    // 2. Configure which attributes are encrypted and/or signed when writing new items.
    //    For each attribute that may exist on the items we plan to write to our DynamoDbTable,
    //    we must explicitly configure how they should be treated during item encryption:
    //      - ENCRYPT_AND_SIGN: The attribute is encrypted and icncluded in the signature
    //      - SIGN_ONLY: The attribute not encrypted, but is still included in the signature
    //      - DO_NOTHING: The attribute is not encrypted and not included in the signature
    let attribute_actions_on_encrypt = HashMap::from([
        ("partition_key".to_string(), CryptoAction::SignOnly), // Our partition attribute must be SIGN_ONLY
        ("sort_key".to_string(), CryptoAction::SignOnly), // Our sort attribute must be SIGN_ONLY
        ("sensitive_data".to_string(), CryptoAction::EncryptAndSign),
    ]);

    // 3. Configure which attributes we expect to be included in the signature
    //    when reading items. There are two options for configuring this:
    //
    //    - (Recommended) Configure `allowedUnsignedAttributesPrefix`:
    //      When defining your DynamoDb schema and deciding on attribute names,
    //      choose a distinguishing prefix (such as ":") for all attributes that
    //      you do not want to include in the signature.
    //      This has two main benefits:
    //      - It is easier to reason about the security and authenticity of data within your item
    //        when all unauthenticated data is easily distinguishable by their attribute name.
    //      - If you need to add new unauthenticated attributes in the future,
    //        you can easily make the corresponding update to your `attributeActionsOnEncrypt`
    //        and immediately start writing to that new attribute, without
    //        any other configuration update needed.
    //      Once you configure this field, it is not safe to update it.
    //
    //    - Configure `allowedUnsignedAttributes`: You may also explicitly list
    //      a set of attributes that should be considered unauthenticated when encountered
    //      on read. Be careful if you use this configuration. Do not remove an attribute
    //      name from this configuration, even if you are no longer writing with that attribute,
    //      as old items may still include this attribute, and our configuration needs to know
    //      to continue to exclude this attribute from the signature scope.
    //      If you add new attribute names to this field, you must first deploy the update to this
    //      field to all readers in your host fleet before deploying the update to start writing
    //      with that new attribute.
    //
    //   For this example, we currently authenticate all attributes. To make it easier to
    //   add unauthenticated attributes in the future, we define a prefix ":" for such attributes.
    const UNSIGNED_ATTR_PREFIX: &str = ":";

    // 4. Create the DynamoDb Encryption configuration for the table we will be writing to.
    let table_config = DynamoDbTableEncryptionConfig::builder()
        .logical_table_name(ddb_table_name)
        .partition_key_name("partition_key")
        .sort_key_name("sort_key")
        .attribute_actions_on_encrypt(attribute_actions_on_encrypt.clone())
        .keyring(encrypt_keyring)
        .allowed_unsigned_attribute_prefix(UNSIGNED_ATTR_PREFIX)
        .build()?;

    let table_configs = DynamoDbTablesEncryptionConfig::builder()
        .table_encryption_configs(HashMap::from([(ddb_table_name.to_string(), table_config)]))
        .build()?;

    // 5. Create a new AWS SDK DynamoDb client using the config above
    let sdk_config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
    let dynamo_config = aws_sdk_dynamodb::config::Builder::from(&sdk_config)
        .interceptor(DbEsdkInterceptor::new(table_configs)?)
        .build();
    let ddb = aws_sdk_dynamodb::Client::from_conf(dynamo_config);

    // 6. Put an item into our table using the above client.
    //    Before the item gets sent to DynamoDb, it will be encrypted
    //    client-side using the MRK multi-keyring.
    let item = HashMap::from([
        (
            "partition_key".to_string(),
            AttributeValue::S("awsKmsMrkDiscoveryMultiKeyringItem".to_string()),
        ),
        ("sort_key".to_string(), AttributeValue::N("0".to_string())),
        (
            "sensitive_data".to_string(),
            AttributeValue::S("encrypt and sign me!".to_string()),
        ),
    ]);

    ddb.put_item()
        .table_name(ddb_table_name)
        .set_item(Some(item.clone()))
        .send()
        .await?;

    // 7. Construct a discovery filter.
    //    A discovery filter limits the set of encrypted data keys
    //    the keyring can use to decrypt data.
    //    We will only let the keyring use keys in the selected AWS accounts
    //    and in the `aws` partition.
    //    This is the suggested config for most users; for more detailed config, see
    //      https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/use-kms-keyring.html#kms-keyring-discovery
    let discovery_filter = DiscoveryFilter::builder()
        .partition("aws")
        .account_ids(account_ids)
        .build()?;

    // 8. Construct a discovery keyring.
    //    Note that we choose to use the MRK discovery multi-keyring, even though
    //    our original keyring used a single KMS key.

    let decrypt_keyring = mpl
        .create_aws_kms_mrk_discovery_multi_keyring()
        .discovery_filter(discovery_filter)
        .regions(regions)
        .send()
        .await?;

    // 9. Create new DDB config and client using the decrypt discovery keyring.
    //     This is the same as the above config, except we pass in the decrypt keyring.
    let table_config_for_decrypt = DynamoDbTableEncryptionConfig::builder()
        .logical_table_name(ddb_table_name)
        .partition_key_name("partition_key")
        .sort_key_name("sort_key")
        .attribute_actions_on_encrypt(attribute_actions_on_encrypt)
        .keyring(decrypt_keyring)
        .allowed_unsigned_attribute_prefix(UNSIGNED_ATTR_PREFIX)
        .build()?;

    let table_configs_for_decrypt = DynamoDbTablesEncryptionConfig::builder()
        .table_encryption_configs(HashMap::from([(
            ddb_table_name.to_string(),
            table_config_for_decrypt,
        )]))
        .build()?;

    let dynamo_config_for_decrypt = aws_sdk_dynamodb::config::Builder::from(&sdk_config)
        .interceptor(DbEsdkInterceptor::new(table_configs_for_decrypt)?)
        .build();
    let ddb_for_decrypt = aws_sdk_dynamodb::Client::from_conf(dynamo_config_for_decrypt);

    // 10. Get the item back from our table using the client.
    //     The client will retrieve encrypted items from the DDB table, then
    //     detect the KMS key that was used to encrypt their data keys.
    //     The client will make a request to KMS to decrypt with the encrypting KMS key.
    //     If the client has permission to decrypt with the KMS key,
    //     the client will decrypt the item client-side using the keyring
    //     and return the original item.
    let key_to_get = HashMap::from([
        (
            "partition_key".to_string(),
            AttributeValue::S("awsKmsMrkDiscoveryMultiKeyringItem".to_string()),
        ),
        ("sort_key".to_string(), AttributeValue::N("0".to_string())),
    ]);

    let resp = ddb_for_decrypt
        .get_item()
        .table_name(ddb_table_name)
        .set_key(Some(key_to_get))
        .consistent_read(true)
        .send()
        .await?;

    assert_eq!(resp.item, Some(item));

    println!("mrk_discovery_multi_keyring successful.");
    Ok(())
}

examples/clientsupplier/client_supplier_example.rs (line 192)

pub async fn put_item_get_item() -> Result<(), crate::BoxError> {
    let ddb_table_name = test_utils::TEST_DDB_TABLE_NAME;
    // Note that we pass in an MRK in us-east-1...
    let key_arn = test_utils::TEST_MRK_REPLICA_KEY_ID_US_EAST_1.to_string();
    let account_ids = vec![test_utils::TEST_AWS_ACCOUNT_ID.to_string()];
    // ...and access its replica in eu-west-1
    let regions = vec!["eu-west-1".to_string()];

    // 1. Create a single MRK multi-keyring.
    //    This can be either a single-region KMS key or an MRK.
    //    For this example to succeed, the key's region must either
    //    1) be in the regions list, or
    //    2) the key must be an MRK with a replica defined
    //    in a region in the regions list, and the client
    //    must have the correct permissions to access the replica.
    let mpl_config = MaterialProvidersConfig::builder().build()?;
    let mpl = mpl_client::Client::from_conf(mpl_config)?;

    // Create the multi-keyring using our custom client supplier
    // defined in the RegionalRoleClientSupplier class in this directory.
    // Note: RegionalRoleClientSupplier will internally use the key_arn's region
    // to retrieve the correct IAM role.

    let mrk_keyring_with_client_supplier = mpl
        .create_aws_kms_mrk_multi_keyring()
        .client_supplier(RegionalRoleClientSupplier {})
        .generator(key_arn)
        .send()
        .await?;

    // 2. Configure which attributes are encrypted and/or signed when writing new items.
    //    For each attribute that may exist on the items we plan to write to our DynamoDbTable,
    //    we must explicitly configure how they should be treated during item encryption:
    //      - ENCRYPT_AND_SIGN: The attribute is encrypted and included in the signature
    //      - SIGN_ONLY: The attribute is not encrypted, but is still included in the signature
    //      - DO_NOTHING: The attribute is not encrypted and not included in the signature
    let attribute_actions_on_encrypt = HashMap::from([
        ("partition_key".to_string(), CryptoAction::SignOnly), // Our partition attribute must be SIGN_ONLY
        ("sort_key".to_string(), CryptoAction::SignOnly), // Our sort attribute must be SIGN_ONLY
        ("sensitive_data".to_string(), CryptoAction::EncryptAndSign),
    ]);

    // 3. Configure which attributes we expect to be included in the signature
    //    when reading items. There are two options for configuring this:
    //
    //    - (Recommended) Configure `allowedUnsignedAttributesPrefix`:
    //      When defining your DynamoDb schema and deciding on attribute names,
    //      choose a distinguishing prefix (such as ":") for all attributes that
    //      you do not want to include in the signature.
    //      This has two main benefits:
    //      - It is easier to reason about the security and authenticity of data within your item
    //        when all unauthenticated data is easily distinguishable by their attribute name.
    //      - If you need to add new unauthenticated attributes in the future,
    //        you can easily make the corresponding update to your `attributeActionsOnEncrypt`
    //        and immediately start writing to that new attribute, without
    //        any other configuration update needed.
    //      Once you configure this field, it is not safe to update it.
    //
    //    - Configure `allowedUnsignedAttributes`: You may also explicitly list
    //      a set of attributes that should be considered unauthenticated when encountered
    //      on read. Be careful if you use this configuration. Do not remove an attribute
    //      name from this configuration, even if you are no longer writing with that attribute,
    //      as old items may still include this attribute, and our configuration needs to know
    //      to continue to exclude this attribute from the signature scope.
    //      If you add new attribute names to this field, you must first deploy the update to this
    //      field to all readers in your host fleet before deploying the update to start writing
    //      with that new attribute.
    //
    //   For this example, we currently authenticate all attributes. To make it easier to
    //   add unauthenticated attributes in the future, we define a prefix ":" for such attributes.
    const UNSIGNED_ATTR_PREFIX: &str = ":";

    // 4. Create the DynamoDb Encryption configuration for the table we will be writing to.
    let table_config = DynamoDbTableEncryptionConfig::builder()
        .logical_table_name(ddb_table_name)
        .partition_key_name("partition_key")
        .sort_key_name("sort_key")
        .attribute_actions_on_encrypt(attribute_actions_on_encrypt.clone())
        .keyring(mrk_keyring_with_client_supplier)
        .allowed_unsigned_attribute_prefix(UNSIGNED_ATTR_PREFIX)
        .build()?;

    let table_configs = DynamoDbTablesEncryptionConfig::builder()
        .table_encryption_configs(HashMap::from([(ddb_table_name.to_string(), table_config)]))
        .build()?;

    // 5. Create a new AWS SDK DynamoDb client using the DynamoDb Config above
    let sdk_config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
    let dynamo_config = aws_sdk_dynamodb::config::Builder::from(&sdk_config)
        .interceptor(DbEsdkInterceptor::new(table_configs)?)
        .build();
    let ddb = aws_sdk_dynamodb::Client::from_conf(dynamo_config);

    // 6. Put an item into our table using the above client.
    //    Before the item gets sent to DynamoDb, it will be encrypted
    //    client-side using the MRK multi-keyring.
    //    The data key protecting this item will be encrypted
    //    with all the KMS Keys in this keyring, so that it can be
    //    decrypted with any one of those KMS Keys.
    let item = HashMap::from([
        (
            "partition_key".to_string(),
            AttributeValue::S("clientSupplierItem".to_string()),
        ),
        ("sort_key".to_string(), AttributeValue::N("0".to_string())),
        (
            "sensitive_data".to_string(),
            AttributeValue::S("encrypt and sign me!".to_string()),
        ),
    ]);

    ddb.put_item()
        .table_name(ddb_table_name)
        .set_item(Some(item.clone()))
        .send()
        .await?;

    // 7. Get the item back from our table using the same keyring.
    //    The client will decrypt the item client-side using the MRK
    //    and return the original item.
    let key_to_get = HashMap::from([
        (
            "partition_key".to_string(),
            AttributeValue::S("clientSupplierItem".to_string()),
        ),
        ("sort_key".to_string(), AttributeValue::N("0".to_string())),
    ]);

    let resp = ddb
        .get_item()
        .table_name(ddb_table_name)
        .set_key(Some(key_to_get.clone()))
        .consistent_read(true)
        .send()
        .await?;

    assert_eq!(
        resp.item.unwrap()["sensitive_data"],
        AttributeValue::S("encrypt and sign me!".to_string())
    );

    // 8. Create a MRK discovery multi-keyring with a custom client supplier.
    //    A discovery MRK multi-keyring will be composed of
    //    multiple discovery MRK keyrings, one for each region.
    //    Each component keyring has its own KMS client in a particular region.
    //    When we provide a client supplier to the multi-keyring, all component
    //    keyrings will use that client supplier configuration.
    //    In our tests, we make `key_arn` an MRK with a replica, and
    //    provide only the replica region in our discovery filter.
    let discovery_filter = DiscoveryFilter::builder()
        .partition("aws")
        .account_ids(account_ids)
        .build()?;

    let mrk_discovery_client_supplier_keyring = mpl
        .create_aws_kms_mrk_discovery_multi_keyring()
        .client_supplier(RegionalRoleClientSupplier {})
        .discovery_filter(discovery_filter)
        .regions(regions)
        .send()
        .await?;

    // 9. Create a new config and client using the discovery keyring.
    //     This is the same setup as above, except we provide the discovery keyring to the config.
    let only_replica_table_config = DynamoDbTableEncryptionConfig::builder()
        .logical_table_name(ddb_table_name)
        .partition_key_name("partition_key")
        .sort_key_name("sort_key")
        .attribute_actions_on_encrypt(attribute_actions_on_encrypt)
        .keyring(mrk_discovery_client_supplier_keyring)
        .allowed_unsigned_attribute_prefix(UNSIGNED_ATTR_PREFIX)
        .build()?;

    let only_replica_table_configs = DynamoDbTablesEncryptionConfig::builder()
        .table_encryption_configs(HashMap::from([(
            ddb_table_name.to_string(),
            only_replica_table_config,
        )]))
        .build()?;

    let only_replica_dynamo_config = aws_sdk_dynamodb::config::Builder::from(&sdk_config)
        .interceptor(DbEsdkInterceptor::new(only_replica_table_configs)?)
        .build();
    let only_replica_ddb = aws_sdk_dynamodb::Client::from_conf(only_replica_dynamo_config);

    // 10. Get the item back from our table using the discovery keyring client.
    //     The client will decrypt the item client-side using the keyring,
    //     and return the original item.
    //     The discovery keyring will only use KMS keys in the provided regions and
    //     AWS accounts. Since we have provided it with a custom client supplier
    //     which uses different IAM roles based on the key region,
    //     the discovery keyring will use a particular IAM role to decrypt
    //     based on the region of the KMS key it uses to decrypt.

    let resp = only_replica_ddb
        .get_item()
        .table_name(ddb_table_name)
        .set_key(Some(key_to_get))
        .consistent_read(true)
        .send()
        .await?;

    assert_eq!(
        resp.item.unwrap()["sensitive_data"],
        AttributeValue::S("encrypt and sign me!".to_string())
    );

    println!("client_supplier_example successful.");
    Ok(())
}

impl Client

pub fn create_aws_kms_hierarchical_keyring( &self, ) -> CreateAwsKmsHierarchicalKeyringFluentBuilder

Constructs a fluent builder for the CreateAwsKmsHierarchicalKeyring operation.

• The fluent builder is configurable:
  • branch_key_id(impl Into<Option<::std::string::String>>) / set_branch_key_id(Option<::std::string::String>): (undocumented)
    
  • branch_key_id_supplier(impl Into<Option<crate::deps::aws_cryptography_materialProviders::types::branch_key_id_supplier::BranchKeyIdSupplierRef>>) / set_branch_key_id_supplier(Option<crate::deps::aws_cryptography_materialProviders::types::branch_key_id_supplier::BranchKeyIdSupplierRef>): (undocumented)
    
  • cache(impl Into<Option<crate::deps::aws_cryptography_materialProviders::types::CacheType>>) / set_cache(Option<crate::deps::aws_cryptography_materialProviders::types::CacheType>): (undocumented)
    
  • key_store(impl Into<Option<crate::deps::aws_cryptography_keyStore::client::Client>>) / set_key_store(Option<crate::deps::aws_cryptography_keyStore::client::Client>): (undocumented)
    
  • partition_id(impl Into<Option<::std::string::String>>) / set_partition_id(Option<::std::string::String>): (undocumented)
    
  • ttl_seconds(impl Into<Option<::std::primitive::i64>>) / set_ttl_seconds(Option<::std::primitive::i64>): (undocumented)
    
• On success, responds with CreateKeyringOutput with field(s):
  • keyring(Option<crate::deps::aws_cryptography_materialProviders::types::keyring::KeyringRef>): (undocumented)
• On failure, responds with SdkError<CreateAwsKmsHierarchicalKeyringError>

Examples found in repository

examples/keyring/hierarchical_keyring.rs (line 115)

pub async fn put_item_get_item(
    tenant1_branch_key_id: &str,
    tenant2_branch_key_id: &str,
) -> Result<(), crate::BoxError> {
    let ddb_table_name = test_utils::TEST_DDB_TABLE_NAME;

    let keystore_table_name = test_utils::TEST_KEYSTORE_NAME;
    let logical_keystore_name = test_utils::TEST_LOGICAL_KEYSTORE_NAME;
    let kms_key_id = test_utils::TEST_KEYSTORE_KMS_KEY_ID;

    // Initial KeyStore Setup: This example requires that you have already
    // created your KeyStore, and have populated it with two new branch keys.
    // See the "Create KeyStore Table Example" and "Create KeyStore Key Example"
    // for an example of how to do this.

    // 1. Configure your KeyStore resource.
    //    This SHOULD be the same configuration that you used
    //    to initially create and populate your KeyStore.
    let sdk_config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
    let key_store_config = KeyStoreConfig::builder()
        .kms_client(aws_sdk_kms::Client::new(&sdk_config))
        .ddb_client(aws_sdk_dynamodb::Client::new(&sdk_config))
        .ddb_table_name(keystore_table_name)
        .logical_key_store_name(logical_keystore_name)
        .kms_configuration(KmsConfiguration::KmsKeyArn(kms_key_id.to_string()))
        .build()?;

    let key_store = keystore_client::Client::from_conf(key_store_config)?;

    // 2. Create a Branch Key ID Supplier. See ExampleBranchKeyIdSupplier in this directory.
    let dbesdk_config = DynamoDbEncryptionConfig::builder().build()?;
    let dbesdk = dbesdk_client::Client::from_conf(dbesdk_config)?;
    let supplier = ExampleBranchKeyIdSupplier::new(tenant1_branch_key_id, tenant2_branch_key_id);

    let branch_key_id_supplier = dbesdk
        .create_dynamo_db_encryption_branch_key_id_supplier()
        .ddb_key_branch_key_id_supplier(supplier)
        .send()
        .await?
        .branch_key_id_supplier
        .unwrap();

    // 3. Create the Hierarchical Keyring, using the Branch Key ID Supplier above.
    //    With this configuration, the AWS SDK Client ultimately configured will be capable
    //    of encrypting or decrypting items for either tenant (assuming correct KMS access).
    //    If you want to restrict the client to only encrypt or decrypt for a single tenant,
    //    configure this Hierarchical Keyring using `.branchKeyId(tenant1BranchKeyId)` instead
    //    of `.branchKeyIdSupplier(branchKeyIdSupplier)`.
    let mpl_config = MaterialProvidersConfig::builder().build()?;
    let mpl = mpl_client::Client::from_conf(mpl_config)?;

    let hierarchical_keyring = mpl
        .create_aws_kms_hierarchical_keyring()
        .branch_key_id_supplier(branch_key_id_supplier)
        .key_store(key_store)
        .ttl_seconds(600)
        .send()
        .await?;

    // 4. Configure which attributes are encrypted and/or signed when writing new items.
    //    For each attribute that may exist on the items we plan to write to our DynamoDbTable,
    //    we must explicitly configure how they should be treated during item encryption:
    //      - ENCRYPT_AND_SIGN: The attribute is encrypted and included in the signature
    //      - SIGN_ONLY: The attribute not encrypted, but is still included in the signature
    //      - DO_NOTHING: The attribute is not encrypted and not included in the signature
    let attribute_actions_on_encrypt = HashMap::from([
        ("partition_key".to_string(), CryptoAction::SignOnly), // Our partition attribute must be SIGN_ONLY
        ("sort_key".to_string(), CryptoAction::SignOnly), // Our sort attribute must be SIGN_ONLY
        (
            "tenant_sensitive_data".to_string(),
            CryptoAction::EncryptAndSign,
        ),
    ]);

    // 5. Configure which attributes we expect to be included in the signature
    //    when reading items. There are two options for configuring this:
    //
    //    - (Recommended) Configure `allowedUnsignedAttributesPrefix`:
    //      When defining your DynamoDb schema and deciding on attribute names,
    //      choose a distinguishing prefix (such as ":") for all attributes that
    //      you do not want to include in the signature.
    //      This has two main benefits:
    //      - It is easier to reason about the security and authenticity of data within your item
    //        when all unauthenticated data is easily distinguishable by their attribute name.
    //      - If you need to add new unauthenticated attributes in the future,
    //        you can easily make the corresponding update to your `attributeActionsOnEncrypt`
    //        and immediately start writing to that new attribute, without
    //        any other configuration update needed.
    //      Once you configure this field, it is not safe to update it.
    //
    //    - Configure `allowedUnsignedAttributes`: You may also explicitly list
    //      a set of attributes that should be considered unauthenticated when encountered
    //      on read. Be careful if you use this configuration. Do not remove an attribute
    //      name from this configuration, even if you are no longer writing with that attribute,
    //      as old items may still include this attribute, and our configuration needs to know
    //      to continue to exclude this attribute from the signature scope.
    //      If you add new attribute names to this field, you must first deploy the update to this
    //      field to all readers in your host fleet before deploying the update to start writing
    //      with that new attribute.
    //
    //   For this example, we currently authenticate all attributes. To make it easier to
    //   add unauthenticated attributes in the future, we define a prefix ":" for such attributes.
    const UNSIGNED_ATTR_PREFIX: &str = ":";

    // 6. Create the DynamoDb Encryption configuration for the table we will be writing to.
    let table_config = DynamoDbTableEncryptionConfig::builder()
        .logical_table_name(ddb_table_name)
        .partition_key_name("partition_key")
        .sort_key_name("sort_key")
        .attribute_actions_on_encrypt(attribute_actions_on_encrypt)
        .keyring(hierarchical_keyring)
        .allowed_unsigned_attribute_prefix(UNSIGNED_ATTR_PREFIX)
        .build()?;

    let table_configs = DynamoDbTablesEncryptionConfig::builder()
        .table_encryption_configs(HashMap::from([(ddb_table_name.to_string(), table_config)]))
        .build()?;

    // 7. Create a new AWS SDK DynamoDb client using the DynamoDb Encryption Interceptor above
    let sdk_config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
    let dynamo_config = aws_sdk_dynamodb::config::Builder::from(&sdk_config)
        .interceptor(DbEsdkInterceptor::new(table_configs)?)
        .build();
    let ddb = aws_sdk_dynamodb::Client::from_conf(dynamo_config);

    // 8. Put an item into our table using the above client.
    //    Before the item gets sent to DynamoDb, it will be encrypted
    //    client-side, according to our configuration.
    //    Because the item we are writing uses "tenantId1" as our partition value,
    //    based on the code we wrote in the ExampleBranchKeySupplier,
    //    `tenant1BranchKeyId` will be used to encrypt this item.
    let item = HashMap::from([
        (
            "partition_key".to_string(),
            AttributeValue::S("tenant1Id".to_string()),
        ),
        ("sort_key".to_string(), AttributeValue::N("0".to_string())),
        (
            "tenant_sensitive_data".to_string(),
            AttributeValue::S("encrypt and sign me!".to_string()),
        ),
    ]);

    ddb.put_item()
        .table_name(ddb_table_name)
        .set_item(Some(item.clone()))
        .send()
        .await?;

    // 9. Get the item back from our table using the same client.
    //     The client will decrypt the item client-side, and return
    //     back the original item.
    //     Because the returned item's partition value is "tenantId1",
    //     based on the code we wrote in the ExampleBranchKeySupplier,
    //     `tenant1BranchKeyId` will be used to decrypt this item.
    let key_to_get = HashMap::from([
        (
            "partition_key".to_string(),
            AttributeValue::S("tenant1Id".to_string()),
        ),
        ("sort_key".to_string(), AttributeValue::N("0".to_string())),
    ]);

    let resp = ddb
        .get_item()
        .table_name(ddb_table_name)
        .set_key(Some(key_to_get))
        .consistent_read(true)
        .send()
        .await?;

    assert_eq!(resp.item, Some(item));
    println!("hierarchical_keyring successful.");
    Ok(())
}

examples/searchableencryption/compound_beacon_searchable_encryption.rs (line 175)

pub async fn put_and_query_with_beacon(branch_key_id: &str) -> Result<(), crate::BoxError> {
    let ddb_table_name = test_utils::UNIT_INSPECTION_TEST_DDB_TABLE_NAME;
    let branch_key_wrapping_kms_key_arn = test_utils::TEST_BRANCH_KEY_WRAPPING_KMS_KEY_ARN;
    let branch_key_ddb_table_name = test_utils::TEST_BRANCH_KEYSTORE_DDB_TABLE_NAME;

    // 1. Create Beacons.
    //    These are the same beacons as in the "BasicSearchableEncryptionExample" in this directory.
    //    See that file to see details on beacon construction and parameters.
    //    While we will not directly query against these beacons,
    //      you must create standard beacons on encrypted fields
    //      that we wish to use in compound beacons.
    let last4_beacon = StandardBeacon::builder()
        .name("inspector_id_last4")
        .length(10)
        .build()?;

    let unit_beacon = StandardBeacon::builder().name("unit").length(30).build()?;

    let standard_beacon_list = vec![last4_beacon, unit_beacon];

    // 2. Define encrypted parts.
    //    Encrypted parts define the beacons that can be used to construct a compound beacon,
    //        and how the compound beacon prefixes those beacon values.

    // A encrypted part must receive:
    //  - name: Name of a standard beacon
    //  - prefix: Any string. This is plaintext that prefixes the beaconized value in the compound beacon.
    //            Prefixes must be unique across the configuration, and must not be a prefix of another prefix;
    //            i.e. for all configured prefixes, the first N characters of a prefix must not equal another prefix.
    // In practice, it is suggested to have a short value distinguishable from other parts served on the prefix.
    // For this example, we will choose "L-" as the prefix for "Last 4 digits of inspector ID".
    // With this prefix and the standard beacon's bit length definition (10), the beaconized
    //     version of the inspector ID's last 4 digits will appear as
    //     `L-000` to `L-3ff` inside a compound beacon.

    // For this example, we will choose "U-" as the prefix for "unit".
    // With this prefix and the standard beacon's bit length definition (30), a unit beacon will appear
    //     as `U-00000000` to `U-3fffffff` inside a compound beacon.
    let encrypted_parts_list = vec![
        EncryptedPart::builder()
            .name("inspector_id_last4")
            .prefix("L-")
            .build()?,
        EncryptedPart::builder().name("unit").prefix("U-").build()?,
    ];

    // 3. Define compound beacon.
    //    A compound beacon allows one to serve multiple beacons or attributes from a single index.
    //    A compound beacon must receive:
    //     - name: The name of the beacon. Compound beacon values will be written to `aws_ddb_e_[name]`.
    //     - split: A character separating parts in a compound beacon
    //    A compound beacon may also receive:
    //     - encrypted: A list of encrypted parts. This is effectively a list of beacons. We provide the list
    //                  that we created above.
    //     - constructors: A list of constructors. This is an ordered list of possible ways to create a beacon.
    //                     We have not defined any constructors here; see the complex example for how to do this.
    //                     The client will provide a default constructor, which will write a compound beacon as:
    //                     all signed parts in the order they are added to the signed list;
    //                     all encrypted parts in order they are added to the encrypted list; all parts required.
    //                     In this example, we expect compound beacons to be written as
    //                     `L-XXX.U-YYYYYYYY`, since our encrypted list looks like
    //                     [last4EncryptedPart, unitEncryptedPart].
    //     - signed: A list of signed parts, i.e. plaintext attributes. This would be provided if we
    //                     wanted to use plaintext values as part of constructing our compound beacon. We do not
    //                     provide this here; see the Complex example for an example.
    let compound_beacon_list = vec![CompoundBeacon::builder()
        .name("last4UnitCompound")
        .split(".")
        .encrypted(encrypted_parts_list)
        .build()?];

    // 4. Configure the Keystore
    //    These are the same constructions as in the Basic example, which describes these in more detail.

    let sdk_config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
    let key_store_config = KeyStoreConfig::builder()
        .kms_client(aws_sdk_kms::Client::new(&sdk_config))
        .ddb_client(aws_sdk_dynamodb::Client::new(&sdk_config))
        .ddb_table_name(branch_key_ddb_table_name)
        .logical_key_store_name(branch_key_ddb_table_name)
        .kms_configuration(KmsConfiguration::KmsKeyArn(
            branch_key_wrapping_kms_key_arn.to_string(),
        ))
        .build()?;

    let key_store = keystore_client::Client::from_conf(key_store_config)?;

    // 5. Create BeaconVersion.
    //    This is similar to the Basic example, except we have also provided a compoundBeaconList.
    //    We must also continue to provide all of the standard beacons that compose a compound beacon list.
    let beacon_version = BeaconVersion::builder()
        .standard_beacons(standard_beacon_list)
        .compound_beacons(compound_beacon_list)
        .version(1) // MUST be 1
        .key_store(key_store.clone())
        .key_source(BeaconKeySource::Single(
            SingleKeyStore::builder()
                // `keyId` references a beacon key.
                // For every branch key we create in the keystore,
                // we also create a beacon key.
                // This beacon key is not the same as the branch key,
                // but is created with the same ID as the branch key.
                .key_id(branch_key_id)
                .cache_ttl(6000)
                .build()?,
        ))
        .build()?;
    let beacon_versions = vec![beacon_version];

    // 6. Create a Hierarchical Keyring
    //    This is the same configuration as in the Basic example.

    let mpl_config = MaterialProvidersConfig::builder().build()?;
    let mpl = mpl_client::Client::from_conf(mpl_config)?;
    let kms_keyring = mpl
        .create_aws_kms_hierarchical_keyring()
        .branch_key_id(branch_key_id)
        .key_store(key_store)
        .ttl_seconds(6000)
        .send()
        .await?;

    // 7. Configure which attributes are encrypted and/or signed when writing new items.
    let attribute_actions_on_encrypt = HashMap::from([
        ("work_id".to_string(), CryptoAction::SignOnly), // Our partition attribute must be SIGN_ONLY
        ("inspection_date".to_string(), CryptoAction::SignOnly), // Our sort attribute must be SIGN_ONLY
        (
            "inspector_id_last4".to_string(),
            CryptoAction::EncryptAndSign,
        ), // Beaconized attributes must be encrypted
        ("unit".to_string(), CryptoAction::EncryptAndSign), // Beaconized attributes must be encrypted
    ]);

    // We do not need to define a crypto action on last4UnitCompound.
    // We only need to define crypto actions on attributes that we pass to PutItem.

    // 8. Create the DynamoDb Encryption configuration for the table we will be writing to.
    //    The beaconVersions are added to the search configuration.
    let table_config = DynamoDbTableEncryptionConfig::builder()
        .logical_table_name(ddb_table_name)
        .partition_key_name("work_id")
        .sort_key_name("inspection_date")
        .attribute_actions_on_encrypt(attribute_actions_on_encrypt)
        .keyring(kms_keyring)
        .search(
            SearchConfig::builder()
                .write_version(1) // MUST be 1
                .versions(beacon_versions)
                .build()?,
        )
        .build()?;

    // 9. Create config
    let encryption_config = DynamoDbTablesEncryptionConfig::builder()
        .table_encryption_configs(HashMap::from([(ddb_table_name.to_string(), table_config)]))
        .build()?;

    // 10. Create an item with both attributes used in the compound beacon.
    let item = HashMap::from([
        (
            "work_id".to_string(),
            AttributeValue::S("9ce39272-8068-4efd-a211-cd162ad65d4c".to_string()),
        ),
        (
            "inspection_date".to_string(),
            AttributeValue::S("2023-06-13".to_string()),
        ),
        (
            "inspector_id_last4".to_string(),
            AttributeValue::S("5678".to_string()),
        ),
        (
            "unit".to_string(),
            AttributeValue::S("011899988199".to_string()),
        ),
    ]);

    // 11. If developing or debugging, verify config by checking compound beacon values directly
    let trans = transform_client::Client::from_conf(encryption_config.clone())?;
    let resolve_output = trans
        .resolve_attributes()
        .table_name(ddb_table_name)
        .item(item.clone())
        .version(1)
        .send()
        .await?;

    // Verify that there are no virtual fields
    assert_eq!(resolve_output.virtual_fields.unwrap().len(), 0);

    // Verify that CompoundBeacons has the expected value
    let compound_beacons = resolve_output.compound_beacons.unwrap();
    assert_eq!(compound_beacons.len(), 1);
    assert_eq!(
        compound_beacons["last4UnitCompound"],
        "L-5678.U-011899988199"
    );
    // Note : the compound beacon actually stored in the table is not "L-5678.U-011899988199"
    // but rather something like "L-abc.U-123", as both parts are EncryptedParts
    // and therefore the text is replaced by the associated beacon

    // 12. Create a new AWS SDK DynamoDb client using the DynamoDb Encryption Interceptor above
    let dynamo_config = aws_sdk_dynamodb::config::Builder::from(&sdk_config)
        .interceptor(DbEsdkInterceptor::new(encryption_config)?)
        .build();
    let ddb = aws_sdk_dynamodb::Client::from_conf(dynamo_config);

    // 13. Write the item to the table
    ddb.put_item()
        .table_name(ddb_table_name)
        .set_item(Some(item.clone()))
        .send()
        .await?;

    // 14. Query for the item we just put.
    let expression_attribute_values = HashMap::from([
        // This query expression takes a few factors into consideration:
        //  - The configured prefix for the last 4 digits of an inspector ID is "L-";
        //    the prefix for the unit is "U-"
        //  - The configured split character, separating component parts, is "."
        //  - The default constructor adds encrypted parts in the order they are in the encrypted list, which
        //    configures `last4` to come before `unit``
        // NOTE: We did not need to create a compound beacon for this query. This query could have also been
        //       done by querying on the partition and sort key, as was done in the Basic example.
        //       This is intended to be a simple example to demonstrate how one might set up a compound beacon.
        //       For examples where compound beacons are required, see the Complex example.
        //       The most basic extension to this example that would require a compound beacon would add a third
        //       part to the compound beacon, then query against three parts.
        (
            ":value".to_string(),
            AttributeValue::S("L-5678.U-011899988199".to_string()),
        ),
    ]);

    // GSIs are sometimes a little bit delayed, so we retry if the query comes up empty.
    for _i in 0..10 {
        let query_response = ddb
            .query()
            .table_name(ddb_table_name)
            .index_name(GSI_NAME)
            .key_condition_expression("last4UnitCompound = :value")
            .set_expression_attribute_values(Some(expression_attribute_values.clone()))
            .send()
            .await?;

        // if no results, sleep and try again
        if query_response.items.is_none() || query_response.items.as_ref().unwrap().is_empty() {
            std::thread::sleep(std::time::Duration::from_millis(20));
            continue;
        }

        let attribute_values = query_response.items.unwrap();
        // Validate only 1 item was returned: the item we just put
        assert_eq!(attribute_values.len(), 1);
        let returned_item = &attribute_values[0];
        // Validate the item has the expected attributes
        assert_eq!(
            returned_item["inspector_id_last4"],
            AttributeValue::S("5678".to_string())
        );
        assert_eq!(
            returned_item["unit"],
            AttributeValue::S("011899988199".to_string())
        );
        break;
    }
    println!("compound_beacon_searchable_encryption successful.");
    Ok(())
}

examples/searchableencryption/beacon_styles_searchable_encryption.rs (line 165)

pub async fn put_and_query_with_beacon(branch_key_id: &str) -> Result<(), crate::BoxError> {
    let ddb_table_name = test_utils::UNIT_INSPECTION_TEST_DDB_TABLE_NAME;
    let branch_key_wrapping_kms_key_arn = test_utils::TEST_BRANCH_KEY_WRAPPING_KMS_KEY_ARN;
    let branch_key_ddb_table_name = test_utils::TEST_BRANCH_KEYSTORE_DDB_TABLE_NAME;

    // 1. Create Beacons.
    let standard_beacon_list = vec![
        // The fruit beacon allows searching on the encrypted fruit attribute
        // We have selected 30 as an example beacon length, but you should go to
        // https://docs.aws.amazon.com/database-encryption-sdk/latest/devguide/choosing-beacon-length.html
        // when creating your beacons.
        StandardBeacon::builder().name("fruit").length(30).build()?,
        // The basket beacon allows searching on the encrypted basket attribute
        // Basket is used as a Set, and therefore needs a beacon style to reflect that.
        // Further, we need to be able to compare the items in basket to the fruit attribute
        // so we `share` this beacon with `fruit`.
        // Since we need both of these things, we use the SharedSet style.
        StandardBeacon::builder()
            .name("basket")
            .length(30)
            .style(BeaconStyle::SharedSet(
                SharedSet::builder().other("fruit").build()?,
            ))
            .build()?,
        // The dessert beacon allows searching on the encrypted dessert attribute
        // We need to be able to compare the dessert attribute to the fruit attribute
        // so we `share` this beacon with `fruit`.
        StandardBeacon::builder()
            .name("dessert")
            .length(30)
            .style(BeaconStyle::Shared(
                Shared::builder().other("fruit").build()?,
            ))
            .build()?,
        // The veggieBeacon allows searching on the encrypted veggies attribute
        // veggies is used as a Set, and therefore needs a beacon style to reflect that.
        StandardBeacon::builder()
            .name("veggies")
            .length(30)
            .style(BeaconStyle::AsSet(AsSet::builder().build()?))
            .build()?,
        // The work_typeBeacon allows searching on the encrypted work_type attribute
        // We only use it as part of the compound work_unit beacon,
        // so we disable its use as a standalone beacon
        StandardBeacon::builder()
            .name("work_type")
            .length(30)
            .style(BeaconStyle::PartOnly(PartOnly::builder().build()?))
            .build()?,
    ];

    // Here we build a compound beacon from work_id and work_type
    // If we had tried to make a StandardBeacon from work_type, we would have seen an error
    // because work_type is "PartOnly"
    let encrypted_part_list = vec![EncryptedPart::builder()
        .name("work_type")
        .prefix("T-")
        .build()?];

    let signed_part_list = vec![SignedPart::builder().name("work_id").prefix("I-").build()?];

    let compound_beacon_list = vec![CompoundBeacon::builder()
        .name("work_unit")
        .split(".")
        .encrypted(encrypted_part_list)
        .signed(signed_part_list)
        .build()?];

    // 2. Configure the Keystore
    //    These are the same constructions as in the Basic example, which describes these in more detail.
    let sdk_config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
    let key_store_config = KeyStoreConfig::builder()
        .kms_client(aws_sdk_kms::Client::new(&sdk_config))
        .ddb_client(aws_sdk_dynamodb::Client::new(&sdk_config))
        .ddb_table_name(branch_key_ddb_table_name)
        .logical_key_store_name(branch_key_ddb_table_name)
        .kms_configuration(KmsConfiguration::KmsKeyArn(
            branch_key_wrapping_kms_key_arn.to_string(),
        ))
        .build()?;

    let key_store = keystore_client::Client::from_conf(key_store_config)?;

    // 3. Create BeaconVersion.
    //    This is similar to the Basic example
    let beacon_version = BeaconVersion::builder()
        .standard_beacons(standard_beacon_list)
        .compound_beacons(compound_beacon_list)
        .version(1) // MUST be 1
        .key_store(key_store.clone())
        .key_source(BeaconKeySource::Single(
            SingleKeyStore::builder()
                // `keyId` references a beacon key.
                // For every branch key we create in the keystore,
                // we also create a beacon key.
                // This beacon key is not the same as the branch key,
                // but is created with the same ID as the branch key.
                .key_id(branch_key_id)
                .cache_ttl(6000)
                .build()?,
        ))
        .build()?;
    let beacon_versions = vec![beacon_version];

    // 4. Create a Hierarchical Keyring
    //    This is the same configuration as in the Basic example.
    let mpl_config = MaterialProvidersConfig::builder().build()?;
    let mpl = mpl_client::Client::from_conf(mpl_config)?;
    let kms_keyring = mpl
        .create_aws_kms_hierarchical_keyring()
        .branch_key_id(branch_key_id)
        .key_store(key_store)
        .ttl_seconds(6000)
        .send()
        .await?;

    // 5. Configure which attributes are encrypted and/or signed when writing new items.
    let attribute_actions_on_encrypt = HashMap::from([
        ("work_id".to_string(), CryptoAction::SignOnly), // Our partition attribute must be SIGN_ONLY
        ("inspection_date".to_string(), CryptoAction::SignOnly), // Our sort attribute must be SIGN_ONLY
        ("dessert".to_string(), CryptoAction::EncryptAndSign), // Beaconized attributes must be encrypted
        ("fruit".to_string(), CryptoAction::EncryptAndSign), // Beaconized attributes must be encrypted
        ("basket".to_string(), CryptoAction::EncryptAndSign), // Beaconized attributes must be encrypted
        ("veggies".to_string(), CryptoAction::EncryptAndSign), // Beaconized attributes must be encrypted
        ("work_type".to_string(), CryptoAction::EncryptAndSign), // Beaconized attributes must be encrypted
    ]);

    // 6. Create the DynamoDb Encryption configuration for the table we will be writing to.
    //    The beaconVersions are added to the search configuration.
    let table_config = DynamoDbTableEncryptionConfig::builder()
        .logical_table_name(ddb_table_name)
        .partition_key_name("work_id")
        .sort_key_name("inspection_date")
        .attribute_actions_on_encrypt(attribute_actions_on_encrypt)
        .keyring(kms_keyring)
        .search(
            SearchConfig::builder()
                .write_version(1) // MUST be 1
                .versions(beacon_versions)
                .build()?,
        )
        .build()?;

    // 7. Create config
    let encryption_config = DynamoDbTablesEncryptionConfig::builder()
        .table_encryption_configs(HashMap::from([(ddb_table_name.to_string(), table_config)]))
        .build()?;

    // 8. Create item one, specifically with "dessert != fruit", and "fruit in basket".
    let item1 = HashMap::from([
        ("work_id".to_string(), AttributeValue::S("1".to_string())),
        (
            "inspection_date".to_string(),
            AttributeValue::S("2023-06-13".to_string()),
        ),
        ("dessert".to_string(), AttributeValue::S("cake".to_string())),
        ("fruit".to_string(), AttributeValue::S("banana".to_string())),
        (
            "basket".to_string(),
            AttributeValue::Ss(vec![
                "banana".to_string(),
                "apple".to_string(),
                "pear".to_string(),
            ]),
        ),
        (
            "veggies".to_string(),
            AttributeValue::Ss(vec![
                "beans".to_string(),
                "carrots".to_string(),
                "celery".to_string(),
            ]),
        ),
        (
            "work_type".to_string(),
            AttributeValue::S("small".to_string()),
        ),
    ]);

    // 9. Create item two, specifically with "dessert == fruit", and "fruit not in basket".
    let item2 = HashMap::from([
        ("work_id".to_string(), AttributeValue::S("2".to_string())),
        (
            "inspection_date".to_string(),
            AttributeValue::S("2023-06-13".to_string()),
        ),
        (
            "dessert".to_string(),
            AttributeValue::S("orange".to_string()),
        ),
        ("fruit".to_string(), AttributeValue::S("orange".to_string())),
        (
            "basket".to_string(),
            AttributeValue::Ss(vec![
                "strawberry".to_string(),
                "blueberry".to_string(),
                "blackberry".to_string(),
            ]),
        ),
        (
            "veggies".to_string(),
            AttributeValue::Ss(vec![
                "beans".to_string(),
                "carrots".to_string(),
                "peas".to_string(),
            ]),
        ),
        (
            "work_type".to_string(),
            AttributeValue::S("large".to_string()),
        ),
    ]);

    // 10. Create a new AWS SDK DynamoDb client using the DynamoDb Config above
    let dynamo_config = aws_sdk_dynamodb::config::Builder::from(&sdk_config)
        .interceptor(DbEsdkInterceptor::new(encryption_config)?)
        .build();
    let ddb = aws_sdk_dynamodb::Client::from_conf(dynamo_config);

    // 11. Add the two items
    ddb.put_item()
        .table_name(ddb_table_name)
        .set_item(Some(item1.clone()))
        .send()
        .await?;

    ddb.put_item()
        .table_name(ddb_table_name)
        .set_item(Some(item2.clone()))
        .send()
        .await?;

    // 12. Test the first type of Set operation :
    // Select records where the basket attribute holds a particular value
    let expression_attribute_values = HashMap::from([(
        ":value".to_string(),
        AttributeValue::S("banana".to_string()),
    )]);

    let scan_response = ddb
        .scan()
        .table_name(ddb_table_name)
        .filter_expression("contains(basket, :value)")
        .set_expression_attribute_values(Some(expression_attribute_values.clone()))
        .send()
        .await?;

    let attribute_values = scan_response.items.unwrap();
    // Validate only 1 item was returned: item1
    assert_eq!(attribute_values.len(), 1);
    let returned_item = &attribute_values[0];
    // Validate the item has the expected attributes
    assert_eq!(returned_item["work_id"], item1["work_id"]);

    // 13. Test the second type of Set operation :
    // Select records where the basket attribute holds the fruit attribute
    let scan_response = ddb
        .scan()
        .table_name(ddb_table_name)
        .filter_expression("contains(basket, fruit)")
        .send()
        .await?;

    let attribute_values = scan_response.items.unwrap();
    // Validate only 1 item was returned: item1
    assert_eq!(attribute_values.len(), 1);
    let returned_item = &attribute_values[0];
    // Validate the item has the expected attributes
    assert_eq!(returned_item["work_id"], item1["work_id"]);

    // 14. Test the third type of Set operation :
    // Select records where the fruit attribute exists in a particular set
    let basket3 = vec![
        "boysenberry".to_string(),
        "orange".to_string(),
        "grape".to_string(),
    ];
    let expression_attribute_values =
        HashMap::from([(":value".to_string(), AttributeValue::Ss(basket3))]);

    let scan_response = ddb
        .scan()
        .table_name(ddb_table_name)
        .filter_expression("contains(:value, fruit)")
        .set_expression_attribute_values(Some(expression_attribute_values.clone()))
        .send()
        .await?;

    let attribute_values = scan_response.items.unwrap();
    // Validate only 1 item was returned: item1
    assert_eq!(attribute_values.len(), 1);
    let returned_item = &attribute_values[0];
    // Validate the item has the expected attributes
    assert_eq!(returned_item["work_id"], item2["work_id"]);

    // 15. Test a Shared search. Select records where the dessert attribute matches the fruit attribute
    let scan_response = ddb
        .scan()
        .table_name(ddb_table_name)
        .filter_expression("dessert = fruit")
        .send()
        .await?;

    let attribute_values = scan_response.items.unwrap();
    // Validate only 1 item was returned: item1
    assert_eq!(attribute_values.len(), 1);
    let returned_item = &attribute_values[0];
    // Validate the item has the expected attributes
    assert_eq!(returned_item["work_id"], item2["work_id"]);

    // 15. Test the AsSet attribute 'veggies' :
    // Select records where the veggies attribute holds a particular value
    let expression_attribute_values =
        HashMap::from([(":value".to_string(), AttributeValue::S("peas".to_string()))]);

    let scan_response = ddb
        .scan()
        .table_name(ddb_table_name)
        .filter_expression("contains(veggies, :value)")
        .set_expression_attribute_values(Some(expression_attribute_values.clone()))
        .send()
        .await?;

    let attribute_values = scan_response.items.unwrap();
    // Validate only 1 item was returned: item1
    assert_eq!(attribute_values.len(), 1);
    let returned_item = &attribute_values[0];
    // Validate the item has the expected attributes
    assert_eq!(returned_item["work_id"], item2["work_id"]);

    // 16. Test the compound beacon 'work_unit' :
    let expression_attribute_values = HashMap::from([(
        ":value".to_string(),
        AttributeValue::S("I-1.T-small".to_string()),
    )]);

    let scan_response = ddb
        .scan()
        .table_name(ddb_table_name)
        .filter_expression("work_unit = :value")
        .set_expression_attribute_values(Some(expression_attribute_values.clone()))
        .send()
        .await?;

    let attribute_values = scan_response.items.unwrap();
    // Validate only 1 item was returned: item1
    assert_eq!(attribute_values.len(), 1);
    let returned_item = &attribute_values[0];
    // Validate the item has the expected attributes
    assert_eq!(returned_item["work_id"], item1["work_id"]);

    println!("beacon_styles_searchable_encryption successful.");
    Ok(())
}

examples/searchableencryption/virtual_beacon_searchable_encryption.rs (line 261)

pub async fn put_and_query_with_beacon(branch_key_id: &str) -> Result<(), crate::BoxError> {
    let ddb_table_name = test_utils::SIMPLE_BEACON_TEST_DDB_TABLE_NAME;
    let branch_key_wrapping_kms_key_arn = test_utils::TEST_BRANCH_KEY_WRAPPING_KMS_KEY_ARN;
    let branch_key_ddb_table_name = test_utils::TEST_BRANCH_KEYSTORE_DDB_TABLE_NAME;

    // 1. Construct a length-1 prefix virtual transform.
    //    `hasTestResult` is a binary attribute, containing either `true` or `false`.
    //    As an example to demonstrate virtual transforms, we will truncate the value
    //    of `hasTestResult` in the virtual field to the length-1 prefix of the binary value, i.e.:
    //     - "true" -> "t"
    //     - "false -> "f"
    //    This is not necessary. This is done as a demonstration of virtual transforms.
    //    Virtual transform operations treat all attributes as strings
    //    (i.e. the boolean value `true` is interpreted as a string "true"),
    //    so its length-1 prefix is just "t".

    let length1_prefix_virtual_transform_list = vec![VirtualTransform::Prefix(
        GetPrefix::builder().length(1).build()?,
    )];

    // 2. Construct the VirtualParts required for the VirtualField
    let has_test_result_part = VirtualPart::builder()
        .loc("hasTestResult")
        .trans(length1_prefix_virtual_transform_list)
        .build()?;

    let state_part = VirtualPart::builder().loc("state").build()?;
    // Note that we do not apply any transform to the `state` attribute,
    // and the virtual field will read in the attribute as-is.

    // 3. Construct the VirtualField from the VirtualParts
    //    Note that the order that virtual parts are added to the virtualPartList
    //    dictates the order in which they are concatenated to build the virtual field.
    //    You must add virtual parts in the same order on write as you do on read.
    let virtual_part_list = vec![state_part, has_test_result_part];

    let state_and_has_test_result_field = VirtualField::builder()
        .name("stateAndHasTestResult")
        .parts(virtual_part_list)
        .build()?;

    let virtual_field_list = vec![state_and_has_test_result_field];

    // 4. Configure our beacon.
    //    The virtual field is assumed to hold a US 2-letter state abbreviation
    //    (56 possible values = 50 states + 6 territories) concatenated with a binary attribute
    //    (2 possible values: true/false hasTestResult field), we expect a population size of
    //    56 * 2 = 112 possible values.
    //    We will also assume that these values are reasonably well-distributed across
    //    customer IDs. In practice, this will not be true. We would expect
    //    more populous states to appear more frequently in the database.
    //    A more complex analysis would show that a stricter upper bound
    //    is necessary to account for this by hiding information from the
    //    underlying distribution.
    //
    //    This link provides guidance for choosing a beacon length:
    //       https://docs.aws.amazon.com/database-encryption-sdk/latest/devguide/choosing-beacon-length.html
    //    We follow the guidance in the link above to determine reasonable bounds for beacon length:
    //     - min: log(sqrt(112))/log(2) ~= 3.4, round down to 3
    //     - max: log((112/2))/log(2) ~= 5.8, round up to 6
    //    You will somehow need to round results to a nearby integer.
    //    We choose to round to the nearest integer; you might consider a different rounding approach.
    //    Rounding up will return fewer expected "false positives" in queries,
    //       leading to fewer decrypt calls and better performance,
    //       but it is easier to identify which beacon values encode distinct plaintexts.
    //    Rounding down will return more expected "false positives" in queries,
    //       leading to more decrypt calls and worse performance,
    //       but it is harder to identify which beacon values encode distinct plaintexts.
    //    We can choose a beacon length between 3 and 6:
    //     - Closer to 3, we expect more "false positives" to be returned,
    //       making it harder to identify which beacon values encode distinct plaintexts,
    //       but leading to more decrypt calls and worse performance
    //     - Closer to 6, we expect fewer "false positives" returned in queries,
    //       leading to fewer decrypt calls and better performance,
    //       but it is easier to identify which beacon values encode distinct plaintexts.
    //    As an example, we will choose 5.
    //    Values stored in aws_dbe_b_stateAndHasTestResult will be 5 bits long (0x00 - 0x1f)
    //    There will be 2^5 = 32 possible HMAC values.
    //    With a well-distributed dataset (112 values), for a particular beacon we expect
    //    (112/32) = 3.5 combinations of abbreviation + true/false attribute
    //    sharing that beacon value.
    let standard_beacon_list = vec![StandardBeacon::builder()
        .name("stateAndHasTestResult")
        .length(5)
        .build()?];

    // 5. Configure Keystore.
    //    This example expects that you have already set up a KeyStore with a single branch key.
    //    See the "CreateKeyStoreTableExample" and "CreateKeyStoreKeyExample" files for how to do this.
    //    After you create a branch key, you should persist its ID for use in this example.
    let sdk_config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
    let key_store_config = KeyStoreConfig::builder()
        .kms_client(aws_sdk_kms::Client::new(&sdk_config))
        .ddb_client(aws_sdk_dynamodb::Client::new(&sdk_config))
        .ddb_table_name(branch_key_ddb_table_name)
        .logical_key_store_name(branch_key_ddb_table_name)
        .kms_configuration(KmsConfiguration::KmsKeyArn(
            branch_key_wrapping_kms_key_arn.to_string(),
        ))
        .build()?;

    let key_store = keystore_client::Client::from_conf(key_store_config)?;

    // 6. Create BeaconVersion.
    //    The BeaconVersion inside the list holds the list of beacons on the table.
    //    The BeaconVersion also stores information about the keystore.
    //    BeaconVersion must be provided:
    //      - keyStore: The keystore configured in the previous step.
    //      - keySource: A configuration for the key source.
    //        For simple use cases, we can configure a 'singleKeySource' which
    //        statically configures a single beaconKey. That is the approach this example takes.
    //        For use cases where you want to use different beacon keys depending on the data
    //        (for example if your table holds data for multiple tenants, and you want to use
    //        a different beacon key per tenant), look into configuring a MultiKeyStore:
    //          https://docs.aws.amazon.com/database-encryption-sdk/latest/devguide/searchable-encryption-multitenant.html
    //    We also provide our standard beacon list and virtual fields here.
    let beacon_version = BeaconVersion::builder()
        .standard_beacons(standard_beacon_list)
        .virtual_fields(virtual_field_list)
        .version(1) // MUST be 1
        .key_store(key_store.clone())
        .key_source(BeaconKeySource::Single(
            SingleKeyStore::builder()
                // `keyId` references a beacon key.
                // For every branch key we create in the keystore,
                // we also create a beacon key.
                // This beacon key is not the same as the branch key,
                // but is created with the same ID as the branch key.
                .key_id(branch_key_id)
                .cache_ttl(6000)
                .build()?,
        ))
        .build()?;
    let beacon_versions = vec![beacon_version];

    // 7. Create a Hierarchical Keyring
    //    This is a KMS keyring that utilizes the keystore table.
    //    This config defines how items are encrypted and decrypted.
    //    NOTE: You should configure this to use the same keystore as your search config.
    let mpl_config = MaterialProvidersConfig::builder().build()?;
    let mpl = mpl_client::Client::from_conf(mpl_config)?;
    let kms_keyring = mpl
        .create_aws_kms_hierarchical_keyring()
        .branch_key_id(branch_key_id)
        .key_store(key_store)
        .ttl_seconds(6000)
        .send()
        .await?;

    // 8. Configure which attributes are encrypted and/or signed when writing new items.
    //    For each attribute that may exist on the items we plan to write to our DynamoDbTable,
    //    we must explicitly configure how they should be treated during item encryption:
    //      - ENCRYPT_AND_SIGN: The attribute is encrypted and included in the signature
    //      - SIGN_ONLY: The attribute not encrypted, but is still included in the signature
    //      - DO_NOTHING: The attribute is not encrypted and not included in the signature
    //    Any attributes that will be used in beacons must be configured as ENCRYPT_AND_SIGN.
    let attribute_actions_on_encrypt = HashMap::from([
        ("customer_id".to_string(), CryptoAction::SignOnly), // Our partition attribute must be SIGN_ONLY
        ("create_time".to_string(), CryptoAction::SignOnly), // Our sort attribute must be SIGN_ONLY
        ("state".to_string(), CryptoAction::EncryptAndSign), // Beaconized attributes must be encrypted
        ("hasTestResult".to_string(), CryptoAction::EncryptAndSign), // Beaconized attributes must be encrypted
    ]);

    // 9. Create the DynamoDb Encryption configuration for the table we will be writing to.
    //    The beaconVersions are added to the search configuration.
    let table_config = DynamoDbTableEncryptionConfig::builder()
        .logical_table_name(ddb_table_name)
        .partition_key_name("customer_id")
        .sort_key_name("create_time")
        .attribute_actions_on_encrypt(attribute_actions_on_encrypt)
        .keyring(kms_keyring)
        .search(
            SearchConfig::builder()
                .write_version(1) // MUST be 1
                .versions(beacon_versions)
                .build()?,
        )
        .build()?;

    // 10. Create config
    let encryption_config = DynamoDbTablesEncryptionConfig::builder()
        .table_encryption_configs(HashMap::from([(ddb_table_name.to_string(), table_config)]))
        .build()?;

    // 11. Create test items

    // Create item with hasTestResult=true
    let item_with_has_test_result = HashMap::from([
        (
            "customer_id".to_string(),
            AttributeValue::S("ABC-123".to_string()),
        ),
        (
            "create_time".to_string(),
            AttributeValue::N("1681495205".to_string()),
        ),
        ("state".to_string(), AttributeValue::S("CA".to_string())),
        ("hasTestResult".to_string(), AttributeValue::Bool(true)),
    ]);

    // Create item with hasTestResult=false
    let item_with_no_has_test_result = HashMap::from([
        (
            "customer_id".to_string(),
            AttributeValue::S("DEF-456".to_string()),
        ),
        (
            "create_time".to_string(),
            AttributeValue::N("1681495205".to_string()),
        ),
        ("state".to_string(), AttributeValue::S("CA".to_string())),
        ("hasTestResult".to_string(), AttributeValue::Bool(false)),
    ]);

    // 12. If developing or debugging, verify config by checking virtual field values directly
    let trans = transform_client::Client::from_conf(encryption_config.clone())?;
    let resolve_output = trans
        .resolve_attributes()
        .table_name(ddb_table_name)
        .item(item_with_has_test_result.clone())
        .version(1)
        .send()
        .await?;

    // CompoundBeacons is empty because we have no Compound Beacons configured
    assert_eq!(resolve_output.compound_beacons.unwrap().len(), 0);

    // Verify that VirtualFields has the expected value
    let virtual_fields = resolve_output.virtual_fields.unwrap();
    assert_eq!(virtual_fields.len(), 1);
    assert_eq!(virtual_fields["stateAndHasTestResult"], "CAt");

    // 13. Create a new AWS SDK DynamoDb client using the DynamoDb Encryption Interceptor above
    let dynamo_config = aws_sdk_dynamodb::config::Builder::from(&sdk_config)
        .interceptor(DbEsdkInterceptor::new(encryption_config)?)
        .build();
    let ddb = aws_sdk_dynamodb::Client::from_conf(dynamo_config);

    // 14. Put two items into our table using the above client.
    //     The two items will differ only in their `customer_id` attribute (primary key)
    //         and their `hasTestResult` attribute.
    //     We will query against these items to demonstrate how to use our setup above
    //         to query against our `stateAndHasTestResult` beacon.
    //     Before the item gets sent to DynamoDb, it will be encrypted
    //         client-side, according to our configuration.
    //     Since our configuration includes a beacon on a virtual field named
    //         `stateAndHasTestResult`, the client will add an attribute
    //         to the item with name `aws_dbe_b_stateAndHasTestResult`.
    //         Its value will be an HMAC truncated to as many bits as the
    //         beacon's `length` parameter; i.e. 5.

    ddb.put_item()
        .table_name(ddb_table_name)
        .set_item(Some(item_with_has_test_result.clone()))
        .send()
        .await?;

    ddb.put_item()
        .table_name(ddb_table_name)
        .set_item(Some(item_with_no_has_test_result.clone()))
        .send()
        .await?;

    // 15. Query by stateAndHasTestResult attribute.
    //     Note that we are constructing the query as if we were querying on plaintext values.
    //     However, the DDB encryption client will detect that this attribute name has a beacon configured.
    //     The client will add the beaconized attribute name and attribute value to the query,
    //         and transform the query to use the beaconized name and value.
    //     Internally, the client will query for and receive all items with a matching HMAC value in the beacon field.
    //     This may include a number of "false positives" with different ciphertext, but the same truncated HMAC.
    //     e.g. if truncate(HMAC("CAt"), 5) == truncate(HMAC("DCf"), 5), the query will return both items.
    //     The client will decrypt all returned items to determine which ones have the expected attribute values,
    //         and only surface items with the correct plaintext to the user.
    //     This procedure is internal to the client and is abstracted away from the user;
    //     e.g. the user will only see "CAt" and never "DCf", though the actual query returned both.
    let expression_attribute_values = HashMap::from([
        // We are querying for the item with `state`="CA" and `hasTestResult`=`true`.
        // Since we added virtual parts as `state` then `hasTestResult`,
        //     we must write our query expression in the same order.
        // We constructed our virtual field as `state`+`hasTestResult`,
        //     so we add the two parts in that order.
        // Since we also created a virtual transform that truncated `hasTestResult`
        //     to its length-1 prefix, i.e. "true" -> "t",
        //     we write that field as its length-1 prefix in the query.
        (
            ":stateAndHasTestResult".to_string(),
            AttributeValue::S("CAt".to_string()),
        ),
    ]);

    // GSIs are sometimes a little bit delayed, so we retry if the query comes up empty.
    for _i in 0..10 {
        let query_response = ddb
            .query()
            .table_name(ddb_table_name)
            .index_name(GSI_NAME)
            .key_condition_expression("stateAndHasTestResult = :stateAndHasTestResult")
            .set_expression_attribute_values(Some(expression_attribute_values.clone()))
            .send()
            .await?;

        // if no results, sleep and try again
        if query_response.items.is_none() || query_response.items.as_ref().unwrap().is_empty() {
            std::thread::sleep(std::time::Duration::from_millis(20));
            continue;
        }

        let attribute_values = query_response.items.unwrap();
        // Validate only 1 item was returned: the item we just put
        assert_eq!(attribute_values.len(), 1);
        let returned_item = &attribute_values[0];
        // Validate the item has the expected attributes
        assert_eq!(returned_item["state"], AttributeValue::S("CA".to_string()));
        assert_eq!(returned_item["hasTestResult"], AttributeValue::Bool(true));
        break;
    }
    println!("virtual_beacon_searchable_encryption successful.");
    Ok(())
}

examples/searchableencryption/basic_searchable_encryption.rs (line 207)

pub async fn put_and_query_with_beacon(branch_key_id: &str) -> Result<(), crate::BoxError> {
    // The whole thing is wrapped in a future to ensure that everything is Send and Sync
    let future = async move {
        let ddb_table_name = test_utils::UNIT_INSPECTION_TEST_DDB_TABLE_NAME;
        let branch_key_wrapping_kms_key_arn = test_utils::TEST_BRANCH_KEY_WRAPPING_KMS_KEY_ARN;
        let branch_key_ddb_table_name = test_utils::TEST_BRANCH_KEYSTORE_DDB_TABLE_NAME;

        // 1. Configure Beacons.
        //    The beacon name must be the name of a table attribute that will be encrypted.
        //    The `length` parameter dictates how many bits are in the beacon attribute value.
        //    The following link provides guidance on choosing a beacon length:
        //        https://docs.aws.amazon.com/database-encryption-sdk/latest/devguide/choosing-beacon-length.html

        // The configured DDB table has a GSI on the `aws_dbe_b_inspector_id_last4` AttributeName.
        // This field holds the last 4 digits of an inspector ID.
        // For our example, this field may range from 0 to 9,999 (10,000 possible values).
        // For our example, we assume a full inspector ID is an integer
        //     ranging from 0 to 99,999,999. We do not assume that the full inspector ID's
        //     values are uniformly distributed across its range of possible values.
        //     In many use cases, the prefix of an identifier encodes some information
        //     about that identifier (e.g. zipcode and SSN prefixes encode geographic
        //     information), while the suffix does not and is more uniformly distributed.
        //     We will assume that the inspector ID field matches a similar use case.
        //     So for this example, we only store and use the last
        //     4 digits of the inspector ID, which we assume is uniformly distributed.
        // Since the full ID's range is divisible by the range of the last 4 digits,
        //     then the last 4 digits of the inspector ID are uniformly distributed
        //     over the range from 0 to 9,999.
        // See our documentation for why you should avoid creating beacons over non-uniform distributions
        //  https://docs.aws.amazon.com/database-encryption-sdk/latest/devguide/searchable-encryption.html#are-beacons-right-for-me
        // A single inspector ID suffix may be assigned to multiple `work_id`s.
        //
        // This link provides guidance for choosing a beacon length:
        //    https://docs.aws.amazon.com/database-encryption-sdk/latest/devguide/choosing-beacon-length.html
        // We follow the guidance in the link above to determine reasonable bounds
        // for the length of a beacon on the last 4 digits of an inspector ID:
        //  - min: log(sqrt(10,000))/log(2) ~= 6.6, round up to 7
        //  - max: log((10,000/2))/log(2) ~= 12.3, round down to 12
        // You will somehow need to round results to a nearby integer.
        // We choose to round to the nearest integer; you might consider a different rounding approach.
        // Rounding up will return fewer expected "false positives" in queries,
        //    leading to fewer decrypt calls and better performance,
        //    but it is easier to identify which beacon values encode distinct plaintexts.
        // Rounding down will return more expected "false positives" in queries,
        //    leading to more decrypt calls and worse performance,
        //    but it is harder to identify which beacon values encode distinct plaintexts.
        // We can choose a beacon length between 7 and 12:
        //  - Closer to 7, we expect more "false positives" to be returned,
        //    making it harder to identify which beacon values encode distinct plaintexts,
        //    but leading to more decrypt calls and worse performance
        //  - Closer to 12, we expect fewer "false positives" returned in queries,
        //    leading to fewer decrypt calls and better performance,
        //    but it is easier to identify which beacon values encode distinct plaintexts.
        // As an example, we will choose 10.
        //
        // Values stored in aws_dbe_b_inspector_id_last4 will be 10 bits long (0x000 - 0x3ff)
        // There will be 2^10 = 1,024 possible HMAC values.
        // With a sufficiently large number of well-distributed inspector IDs,
        //    for a particular beacon we expect (10,000/1,024) ~= 9.8 4-digit inspector ID suffixes
        //    sharing that beacon value.
        let last4_beacon = StandardBeacon::builder()
            .name("inspector_id_last4")
            .length(10)
            .build()?;

        // The configured DDB table has a GSI on the `aws_dbe_b_unit` AttributeName.
        // This field holds a unit serial number.
        // For this example, this is a 12-digit integer from 0 to 999,999,999,999 (10^12 possible values).
        // We will assume values for this attribute are uniformly distributed across this range.
        // A single unit serial number may be assigned to multiple `work_id`s.
        //
        // This link provides guidance for choosing a beacon length:
        //    https://docs.aws.amazon.com/database-encryption-sdk/latest/devguide/choosing-beacon-length.html
        // We follow the guidance in the link above to determine reasonable bounds
        // for the length of a beacon on a unit serial number:
        //  - min: log(sqrt(999,999,999,999))/log(2) ~= 19.9, round up to 20
        //  - max: log((999,999,999,999/2))/log(2) ~= 38.9, round up to 39
        // We can choose a beacon length between 20 and 39:
        //  - Closer to 20, we expect more "false positives" to be returned,
        //    making it harder to identify which beacon values encode distinct plaintexts,
        //    but leading to more decrypt calls and worse performance
        //  - Closer to 39, we expect fewer "false positives" returned in queries,
        //    leading to fewer decrypt calls and better performance,
        //    but it is easier to identify which beacon values encode distinct plaintexts.
        // As an example, we will choose 30.
        //
        // Values stored in aws_dbe_b_unit will be 30 bits long (0x00000000 - 0x3fffffff)
        // There will be 2^30 = 1,073,741,824 ~= 1.1B possible HMAC values.
        // With a sufficiently large number of well-distributed inspector IDs,
        //    for a particular beacon we expect (10^12/2^30) ~= 931.3 unit serial numbers
        //    sharing that beacon value.
        let unit_beacon = StandardBeacon::builder().name("unit").length(30).build()?;

        let standard_beacon_list = vec![last4_beacon, unit_beacon];

        // 2. Configure Keystore.
        //    The keystore is a separate DDB table where the client stores encryption and decryption materials.
        //    In order to configure beacons on the DDB client, you must configure a keystore.
        //
        //    This example expects that you have already set up a KeyStore with a single branch key.
        //    See the "Create KeyStore Table Example" and "Create KeyStore Key Example" for how to do this.
        //    After you create a branch key, you should persist its ID for use in this example.
        let sdk_config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
        let key_store_config = KeyStoreConfig::builder()
            .kms_client(aws_sdk_kms::Client::new(&sdk_config))
            .ddb_client(aws_sdk_dynamodb::Client::new(&sdk_config))
            .ddb_table_name(branch_key_ddb_table_name)
            .logical_key_store_name(branch_key_ddb_table_name)
            .kms_configuration(KmsConfiguration::KmsKeyArn(
                branch_key_wrapping_kms_key_arn.to_string(),
            ))
            .build()?;

        let key_store = keystore_client::Client::from_conf(key_store_config)?;

        // 3. Create BeaconVersion.
        //    The BeaconVersion inside the list holds the list of beacons on the table.
        //    The BeaconVersion also stores information about the keystore.
        //    BeaconVersion must be provided:
        //      - keyStore: The keystore configured in step 2.
        //      - keySource: A configuration for the key source.
        //        For simple use cases, we can configure a 'singleKeySource' which
        //        statically configures a single beaconKey. That is the approach this example takes.
        //        For use cases where you want to use different beacon keys depending on the data
        //        (for example if your table holds data for multiple tenants, and you want to use
        //        a different beacon key per tenant), look into configuring a MultiKeyStore:
        //          https://docs.aws.amazon.com/database-encryption-sdk/latest/devguide/searchable-encryption-multitenant.html

        let beacon_version = BeaconVersion::builder()
            .standard_beacons(standard_beacon_list)
            .version(1) // MUST be 1
            .key_store(key_store.clone())
            .key_source(BeaconKeySource::Single(
                SingleKeyStore::builder()
                    // `keyId` references a beacon key.
                    // For every branch key we create in the keystore,
                    // we also create a beacon key.
                    // This beacon key is not the same as the branch key,
                    // but is created with the same ID as the branch key.
                    .key_id(branch_key_id)
                    .cache_ttl(6000)
                    .build()?,
            ))
            .build()?;
        let beacon_versions = vec![beacon_version];

        // 4. Create a Hierarchical Keyring
        //    This is a KMS keyring that utilizes the keystore table.
        //    This config defines how items are encrypted and decrypted.
        //    NOTE: You should configure this to use the same keystore as your search config.
        let provider_config = MaterialProvidersConfig::builder().build()?;
        let mat_prov = client::Client::from_conf(provider_config)?;
        let kms_keyring = mat_prov
            .create_aws_kms_hierarchical_keyring()
            .branch_key_id(branch_key_id)
            .key_store(key_store)
            .ttl_seconds(6000)
            .send()
            .await?;

        // 5. Configure which attributes are encrypted and/or signed when writing new items.
        //    For each attribute that may exist on the items we plan to write to our DynamoDbTable,
        //    we must explicitly configure how they should be treated during item encryption:
        //      - ENCRYPT_AND_SIGN: The attribute is encrypted and included in the signature
        //      - SIGN_ONLY: The attribute not encrypted, but is still included in the signature
        //      - DO_NOTHING: The attribute is not encrypted and not included in the signature
        //    Any attributes that will be used in beacons must be configured as ENCRYPT_AND_SIGN.
        let attribute_actions_on_encrypt = HashMap::from([
            ("work_id".to_string(), CryptoAction::SignOnly), // Our partition attribute must be SIGN_ONLY
            ("inspection_date".to_string(), CryptoAction::SignOnly), // Our sort attribute must be SIGN_ONLY
            (
                "inspector_id_last4".to_string(),
                CryptoAction::EncryptAndSign,
            ), // Beaconized attributes must be encrypted
            ("unit".to_string(), CryptoAction::EncryptAndSign), // Beaconized attributes must be encrypted
        ]);

        // 6. Create the DynamoDb Encryption configuration for the table we will be writing to.
        //    The beaconVersions are added to the search configuration.
        let table_config = DynamoDbTableEncryptionConfig::builder()
            .logical_table_name(ddb_table_name)
            .partition_key_name("work_id")
            .sort_key_name("inspection_date")
            .attribute_actions_on_encrypt(attribute_actions_on_encrypt)
            .keyring(kms_keyring)
            .search(
                SearchConfig::builder()
                    .write_version(1) // MUST be 1
                    .versions(beacon_versions)
                    .build()?,
            )
            .build()?;

        let table_configs = DynamoDbTablesEncryptionConfig::builder()
            .table_encryption_configs(HashMap::from([(ddb_table_name.to_string(), table_config)]))
            .build()?;

        // 7. Create a new AWS SDK DynamoDb client using the TableEncryptionConfigs
        let sdk_config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
        let dynamo_config = aws_sdk_dynamodb::config::Builder::from(&sdk_config)
            .interceptor(DbEsdkInterceptor::new(table_configs)?)
            .build();
        let ddb = aws_sdk_dynamodb::Client::from_conf(dynamo_config);

        // 8. Put an item into our table using the above client.
        //    Before the item gets sent to DynamoDb, it will be encrypted
        //        client-side, according to our configuration.
        //    Since our configuration includes beacons for `inspector_id_last4` and `unit`,
        //        the client will add two additional attributes to the item. These attributes will have names
        //        `aws_dbe_b_inspector_id_last4` and `aws_dbe_b_unit`. Their values will be HMACs
        //        truncated to as many bits as the beacon's `length` parameter; e.g.
        //    aws_dbe_b_inspector_id_last4 = truncate(HMAC("4321"), 10)
        //    aws_dbe_b_unit = truncate(HMAC("123456789012"), 30)

        let item = HashMap::from([
            (
                "work_id".to_string(),
                AttributeValue::S("1313ba89-5661-41eb-ba6c-cb1b4cb67b2d".to_string()),
            ),
            (
                "inspection_date".to_string(),
                AttributeValue::S("2023-06-13".to_string()),
            ),
            (
                "inspector_id_last4".to_string(),
                AttributeValue::S("4321".to_string()),
            ),
            (
                "unit".to_string(),
                AttributeValue::S("123456789012".to_string()),
            ),
        ]);

        ddb.put_item()
            .table_name(ddb_table_name)
            .set_item(Some(item.clone()))
            .send()
            .await?;

        // 9. Query for the item we just put.
        //     Note that we are constructing the query as if we were querying on plaintext values.
        //     However, the DDB encryption client will detect that this attribute name has a beacon configured.
        //     The client will add the beaconized attribute name and attribute value to the query,
        //         and transform the query to use the beaconized name and value.
        //     Internally, the client will query for and receive all items with a matching HMAC value in the beacon field.
        //     This may include a number of "false positives" with different ciphertext, but the same truncated HMAC.
        //     e.g. if truncate(HMAC("123456789012"), 30)
        //          == truncate(HMAC("098765432109"), 30),
        //     the query will return both items.
        //     The client will decrypt all returned items to determine which ones have the expected attribute values,
        //         and only surface items with the correct plaintext to the user.
        //     This procedure is internal to the client and is abstracted away from the user;
        //     e.g. the user will only see "123456789012" and never
        //        "098765432109", though the actual query returned both.
        let expression_attributes_names = HashMap::from([
            ("#last4".to_string(), "inspector_id_last4".to_string()),
            ("#unit".to_string(), "unit".to_string()),
        ]);

        let expression_attribute_values = HashMap::from([
            (":last4".to_string(), AttributeValue::S("4321".to_string())),
            (
                ":unit".to_string(),
                AttributeValue::S("123456789012".to_string()),
            ),
        ]);

        // GSIs do not update instantly
        // so if the results come back empty
        // we retry after a short sleep
        for _i in 0..10 {
            let query_response = ddb
                .query()
                .table_name(ddb_table_name)
                .index_name(GSI_NAME)
                .key_condition_expression("#last4 = :last4 and #unit = :unit")
                .set_expression_attribute_names(Some(expression_attributes_names.clone()))
                .set_expression_attribute_values(Some(expression_attribute_values.clone()))
                .send()
                .await?;

            // if no results, sleep and try again
            if query_response.items.is_none() || query_response.items.as_ref().unwrap().is_empty() {
                std::thread::sleep(std::time::Duration::from_millis(20));
                continue;
            }

            let attribute_values = query_response.items.unwrap();
            // Validate only 1 item was returned: the item we just put
            assert_eq!(attribute_values.len(), 1);
            let returned_item = &attribute_values[0];
            // Validate the item has the expected attributes
            assert_eq!(
                returned_item["inspector_id_last4"],
                AttributeValue::S("4321".to_string())
            );
            assert_eq!(
                returned_item["unit"],
                AttributeValue::S("123456789012".to_string())
            );
            break;
        }
        println!("basic_searchable_encryption successful.");
        Ok(())
    };
    future.await
}

examples/searchableencryption/complexexample/beacon_config.rs (line 486)

pub async fn setup_beacon_config(
    ddb_table_name: &str,
    branch_key_id: &str,
    branch_key_wrapping_kms_key_arn: &str,
    branch_key_ddb_table_name: &str,
) -> Result<aws_sdk_dynamodb::Client, crate::BoxError> {
    // 1. Create keystore and branch key
    //    These are the same constructions as in the Basic examples, which describe this in more detail.
    let sdk_config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
    let key_store_config = KeyStoreConfig::builder()
        .kms_client(aws_sdk_kms::Client::new(&sdk_config))
        .ddb_client(aws_sdk_dynamodb::Client::new(&sdk_config))
        .ddb_table_name(branch_key_ddb_table_name)
        .logical_key_store_name(branch_key_ddb_table_name)
        .kms_configuration(KmsConfiguration::KmsKeyArn(
            branch_key_wrapping_kms_key_arn.to_string(),
        ))
        .build()?;

    let key_store = keystore_client::Client::from_conf(key_store_config)?;

    // 2. Create standard beacons
    //    For this example, we use a standard beacon length of 4.
    //    The BasicSearchableEncryptionExample gives a more thorough consideration of beacon length.
    //    For production applications, one should always exercise rigor when deciding beacon length, including
    //        examining population size and considering performance.
    let standard_beacon_list = vec![
        StandardBeacon::builder()
            .name("EmployeeID")
            .length(4)
            .build()?,
        StandardBeacon::builder()
            .name("TicketNumber")
            .length(4)
            .build()?,
        StandardBeacon::builder()
            .name("ProjectName")
            .length(4)
            .build()?,
        StandardBeacon::builder()
            .name("EmployeeEmail")
            .length(4)
            .build()?,
        StandardBeacon::builder()
            .name("CreatorEmail")
            .length(4)
            .build()?,
        StandardBeacon::builder()
            .name("ProjectStatus")
            .length(4)
            .build()?,
        StandardBeacon::builder()
            .name("OrganizerEmail")
            .length(4)
            .build()?,
        StandardBeacon::builder()
            .name("ManagerEmail")
            .length(4)
            .build()?,
        StandardBeacon::builder()
            .name("AssigneeEmail")
            .length(4)
            .build()?,
        StandardBeacon::builder()
            .name("Severity")
            .length(4)
            .build()?,
        StandardBeacon::builder()
            .name("City")
            .loc("Location.City")
            .length(4)
            .build()?,
        StandardBeacon::builder()
            .name("Building")
            .loc("Location.Building")
            .length(4)
            .build()?,
        StandardBeacon::builder()
            .name("Floor")
            .loc("Location.Floor")
            .length(4)
            .build()?,
        StandardBeacon::builder()
            .name("Room")
            .loc("Location.Room")
            .length(4)
            .build()?,
        StandardBeacon::builder()
            .name("Desk")
            .loc("Location.Desk")
            .length(4)
            .build()?,
    ];

    // 3. Define encrypted parts
    //    Note that some of the prefixes are modified from the suggested prefixes in Demo.md.
    //    This is because all prefixes must be unique in a configuration.
    //    Encrypted parts are described in more detail in the CompoundBeaconSearchableEncryptionExample.
    let encrypted_parts_list = vec![
        EncryptedPart::builder()
            .name("EmployeeID")
            .prefix("E-")
            .build()?,
        EncryptedPart::builder()
            .name("TicketNumber")
            .prefix("T-")
            .build()?,
        EncryptedPart::builder()
            .name("ProjectName")
            .prefix("P-")
            .build()?,
        EncryptedPart::builder()
            .name("EmployeeEmail")
            .prefix("EE-")
            .build()?,
        EncryptedPart::builder()
            .name("CreatorEmail")
            .prefix("CE-")
            .build()?,
        EncryptedPart::builder()
            .name("OrganizerEmail")
            .prefix("OE-")
            .build()?,
        EncryptedPart::builder()
            .name("ManagerEmail")
            .prefix("ME-")
            .build()?,
        EncryptedPart::builder()
            .name("AssigneeEmail")
            .prefix("AE-")
            .build()?,
        EncryptedPart::builder()
            .name("ProjectStatus")
            .prefix("PSts-")
            .build()?,
        EncryptedPart::builder().name("City").prefix("C-").build()?,
        EncryptedPart::builder()
            .name("Severity")
            .prefix("S-")
            .build()?,
        EncryptedPart::builder()
            .name("Building")
            .prefix("B-")
            .build()?,
        EncryptedPart::builder()
            .name("Floor")
            .prefix("F-")
            .build()?,
        EncryptedPart::builder().name("Room").prefix("R-").build()?,
        EncryptedPart::builder().name("Desk").prefix("D-").build()?,
    ];

    // 4. Define signed parts
    //    These are unencrypted attributes we would like to use in beacon queries.
    //    In this example, all of these represent dates or times.
    //    Keeping these attributes unencrypted allows us to use them in comparison-based queries. If a signed
    //        part is the first part in a compound beacon, then that part can be used in comparison for sorting.
    let signed_parts_list = vec![
        SignedPart::builder()
            .name("TicketModTime")
            .prefix("M-")
            .build()?,
        SignedPart::builder()
            .name("MeetingStart")
            .prefix("MS-")
            .build()?,
        SignedPart::builder()
            .name("TimeCardStart")
            .prefix("TC-")
            .build()?,
        SignedPart::builder()
            .name("ProjectStart")
            .prefix("PS-")
            .build()?,
    ];

    // 5. Create constructor parts
    //    Constructor parts are used to assemble constructors (constructors described more in next step).
    //    For each attribute that will be used in a constructor, there must be a corresponding constructor part.
    //    A constructor part must receive:
    //     - name: Name of a standard beacon
    //     - required: Whether this attribute must be present in the item to match a constructor
    //    In this example, we will define each constructor part once and re-use it across multiple constructors.
    //    The parts below are defined by working backwards from the constructors in "PK Constructors",
    //        "SK constructors", etc. sections in Demo.md.
    let employee_id_constructor_part = ConstructorPart::builder()
        .name("EmployeeID")
        .required(true)
        .build()?;
    let ticket_number_constructor_part = ConstructorPart::builder()
        .name("TicketNumber")
        .required(true)
        .build()?;
    let project_name_constructor_part = ConstructorPart::builder()
        .name("ProjectName")
        .required(true)
        .build()?;
    let ticket_mod_time_constructor_part = ConstructorPart::builder()
        .name("TicketModTime")
        .required(true)
        .build()?;
    let meeting_start_constructor_part = ConstructorPart::builder()
        .name("MeetingStart")
        .required(true)
        .build()?;
    let timecard_start_constructor_part = ConstructorPart::builder()
        .name("TimeCardStart")
        .required(true)
        .build()?;
    let employee_email_constructor_part = ConstructorPart::builder()
        .name("EmployeeEmail")
        .required(true)
        .build()?;
    let creator_email_constructor_part = ConstructorPart::builder()
        .name("CreatorEmail")
        .required(true)
        .build()?;
    let project_status_constructor_part = ConstructorPart::builder()
        .name("ProjectStatus")
        .required(true)
        .build()?;
    let organizer_email_constructor_part = ConstructorPart::builder()
        .name("OrganizerEmail")
        .required(true)
        .build()?;
    let project_start_constructor_part = ConstructorPart::builder()
        .name("ProjectStart")
        .required(true)
        .build()?;
    let manager_email_constructor_part = ConstructorPart::builder()
        .name("ManagerEmail")
        .required(true)
        .build()?;
    let assignee_email_constructor_part = ConstructorPart::builder()
        .name("AssigneeEmail")
        .required(true)
        .build()?;
    let city_constructor_part = ConstructorPart::builder()
        .name("City")
        .required(true)
        .build()?;
    let severity_constructor_part = ConstructorPart::builder()
        .name("Severity")
        .required(true)
        .build()?;
    let building_constructor_part = ConstructorPart::builder()
        .name("Building")
        .required(true)
        .build()?;
    let floor_constructor_part = ConstructorPart::builder()
        .name("Floor")
        .required(true)
        .build()?;
    let room_constructor_part = ConstructorPart::builder()
        .name("Room")
        .required(true)
        .build()?;
    let desk_constructor_part = ConstructorPart::builder()
        .name("Desk")
        .required(true)
        .build()?;

    // 6. Define constructors
    //    Constructors define how encrypted and signed parts are assembled into compound beacons.
    //    The constructors below are based off of the "PK Constructors", "SK constructors", etc. sections in Demo.md.

    // The employee ID constructor only requires an employee ID.
    // If an item has an attribute with name "EmployeeID", it will match this constructor.
    // If this is the first matching constructor in the constructor list (constructor list described more below),
    //     the compound beacon will use this constructor, and the compound beacon will be written as `E-X`.

    let employee_id_constructor = Constructor::builder()
        .parts(vec![employee_id_constructor_part])
        .build()?;
    let ticket_number_constructor = Constructor::builder()
        .parts(vec![ticket_number_constructor_part])
        .build()?;
    let project_name_constructor = Constructor::builder()
        .parts(vec![project_name_constructor_part])
        .build()?;
    let ticket_mod_time_constructor = Constructor::builder()
        .parts(vec![ticket_mod_time_constructor_part])
        .build()?;
    let building_constructor = Constructor::builder()
        .parts(vec![building_constructor_part.clone()])
        .build()?;

    // This constructor requires all of "MeetingStart", "Location.Floor", and "Location.Room" attributes.
    // If an item has all of these attributes, it will match this constructor.
    // If this is the first matching constructor in the constructor list (constructor list described more below),
    //     the compound beacon will use this constructor, and the compound beacon will be written as `MS-X~F-Y~R-Z`.
    // In a constructor with multiple constructor parts, the order the constructor parts are added to
    //     the constructor part list defines how the compound beacon is written.
    // We can rearrange the beacon parts by changing the order the constructors were added to the list.
    let meeting_start_floor_room_constructor = Constructor::builder()
        .parts(vec![
            meeting_start_constructor_part,
            floor_constructor_part.clone(),
            room_constructor_part,
        ])
        .build()?;

    let timecard_start_constructor = Constructor::builder()
        .parts(vec![timecard_start_constructor_part.clone()])
        .build()?;
    let timecard_start_employee_email_constructor = Constructor::builder()
        .parts(vec![
            timecard_start_constructor_part,
            employee_email_constructor_part.clone(),
        ])
        .build()?;
    let creator_email_constructor = Constructor::builder()
        .parts(vec![creator_email_constructor_part])
        .build()?;
    let project_status_constructor = Constructor::builder()
        .parts(vec![project_status_constructor_part])
        .build()?;
    let employee_email_constructor = Constructor::builder()
        .parts(vec![employee_email_constructor_part])
        .build()?;
    let organizer_email_constructor = Constructor::builder()
        .parts(vec![organizer_email_constructor_part])
        .build()?;
    let project_start_constructor = Constructor::builder()
        .parts(vec![project_start_constructor_part])
        .build()?;
    let manager_email_constructor = Constructor::builder()
        .parts(vec![manager_email_constructor_part])
        .build()?;
    let assignee_email_constructor = Constructor::builder()
        .parts(vec![assignee_email_constructor_part])
        .build()?;
    let city_constructor = Constructor::builder()
        .parts(vec![city_constructor_part])
        .build()?;
    let severity_constructor = Constructor::builder()
        .parts(vec![severity_constructor_part])
        .build()?;
    let building_floor_desk_constructor = Constructor::builder()
        .parts(vec![
            building_constructor_part,
            floor_constructor_part,
            desk_constructor_part,
        ])
        .build()?;

    // 7. Add constructors to the compound beacon constructor list in desired construction order
    //    In a compound beacon with multiple constructors, the order the constructors are added to
    //        the constructor list determines their priority.
    //    The first constructor added to a constructor list will be the first constructor that is executed.
    //    The client will evaluate constructors until one matches, and will use the first one that matches.
    //    If no constructors match, an attribute value is not written for that beacon.
    //    A general strategy is to add constructors with unique conditions at the beginning of the list,
    //       and add constructors with general conditions at the end of the list. This would allow a given
    //       item to trigger the constructor most specific to its attributes.
    let pk0_constructor_list = vec![
        employee_id_constructor.clone(),
        building_constructor,
        ticket_number_constructor,
        project_name_constructor.clone(),
    ];
    let sk0_constructor_list = vec![
        ticket_mod_time_constructor.clone(),
        meeting_start_floor_room_constructor.clone(),
        timecard_start_employee_email_constructor,
        project_name_constructor,
        employee_id_constructor.clone(),
    ];
    let pk1_constructor_list = vec![
        creator_email_constructor,
        employee_email_constructor,
        project_status_constructor,
        organizer_email_constructor,
    ];
    let sk1_constructor_list = vec![
        meeting_start_floor_room_constructor,
        timecard_start_constructor,
        ticket_mod_time_constructor.clone(),
        project_start_constructor,
        employee_id_constructor,
    ];
    let pk2_constructor_list = vec![manager_email_constructor, assignee_email_constructor];
    let pk3_constructor_list = vec![city_constructor, severity_constructor];
    let sk3_constructor_list = vec![building_floor_desk_constructor, ticket_mod_time_constructor];

    // 8. Define compound beacons
    //    Compound beacon construction is defined in more detail in CompoundBeaconSearchableEncryptionExample.
    //    Note that the split character must be a character that is not used in any attribute value.
    let compound_beacon_list = vec![
        CompoundBeacon::builder()
            .name("PK")
            .split("~")
            .constructors(pk0_constructor_list)
            .build()?,
        CompoundBeacon::builder()
            .name("SK")
            .split("~")
            .constructors(sk0_constructor_list)
            .build()?,
        CompoundBeacon::builder()
            .name("PK1")
            .split("~")
            .constructors(pk1_constructor_list)
            .build()?,
        CompoundBeacon::builder()
            .name("SK1")
            .split("~")
            .constructors(sk1_constructor_list)
            .build()?,
        CompoundBeacon::builder()
            .name("PK2")
            .split("~")
            .constructors(pk2_constructor_list)
            .build()?,
        CompoundBeacon::builder()
            .name("PK3")
            .split("~")
            .constructors(pk3_constructor_list)
            .build()?,
        CompoundBeacon::builder()
            .name("SK3")
            .split("~")
            .constructors(sk3_constructor_list)
            .build()?,
    ];

    // 9. Create BeaconVersion
    let beacon_versions = BeaconVersion::builder()
        .standard_beacons(standard_beacon_list)
        .compound_beacons(compound_beacon_list)
        .encrypted_parts(encrypted_parts_list)
        .signed_parts(signed_parts_list)
        .version(1)
        .key_store(key_store.clone())
        .key_source(BeaconKeySource::Single(
            SingleKeyStore::builder()
                .key_id(branch_key_id)
                .cache_ttl(6000)
                .build()?,
        ))
        .build()?;
    let beacon_versions = vec![beacon_versions];

    // 10. Create a Hierarchical Keyring
    let mpl_config = MaterialProvidersConfig::builder().build()?;
    let mpl = mpl_client::Client::from_conf(mpl_config)?;
    let kms_keyring = mpl
        .create_aws_kms_hierarchical_keyring()
        .branch_key_id(branch_key_id)
        .key_store(key_store)
        .ttl_seconds(600)
        .send()
        .await?;

    // 11. Define crypto actions
    let attribute_actions_on_encrypt = HashMap::from([
        // Our partition key must be configured as SIGN_ONLY
        ("partition_key".to_string(), CryptoAction::SignOnly),
        // Attributes used in beacons must be configured as ENCRYPT_AND_SIGN
        ("EmployeeID".to_string(), CryptoAction::EncryptAndSign),
        ("TicketNumber".to_string(), CryptoAction::EncryptAndSign),
        ("ProjectName".to_string(), CryptoAction::EncryptAndSign),
        ("EmployeeName".to_string(), CryptoAction::EncryptAndSign),
        ("EmployeeEmail".to_string(), CryptoAction::EncryptAndSign),
        ("CreatorEmail".to_string(), CryptoAction::EncryptAndSign),
        ("ProjectStatus".to_string(), CryptoAction::EncryptAndSign),
        ("OrganizerEmail".to_string(), CryptoAction::EncryptAndSign),
        ("ManagerEmail".to_string(), CryptoAction::EncryptAndSign),
        ("AssigneeEmail".to_string(), CryptoAction::EncryptAndSign),
        ("City".to_string(), CryptoAction::EncryptAndSign),
        ("Severity".to_string(), CryptoAction::EncryptAndSign),
        ("Location".to_string(), CryptoAction::EncryptAndSign),
        // These are not beaconized attributes, but are sensitive data that must be encrypted
        ("Attendees".to_string(), CryptoAction::EncryptAndSign),
        ("Subject".to_string(), CryptoAction::EncryptAndSign),
        // Signed parts and unencrypted attributes can be configured as SIGN_ONLY or DO_NOTHING
        // For this example, we will set these to SIGN_ONLY to ensure authenticity
        ("TicketModTime".to_string(), CryptoAction::SignOnly),
        ("MeetingStart".to_string(), CryptoAction::SignOnly),
        ("TimeCardStart".to_string(), CryptoAction::SignOnly),
        ("EmployeeTitle".to_string(), CryptoAction::SignOnly),
        ("Description".to_string(), CryptoAction::SignOnly),
        ("ProjectTarget".to_string(), CryptoAction::SignOnly),
        ("Hours".to_string(), CryptoAction::SignOnly),
        ("Role".to_string(), CryptoAction::SignOnly),
        ("Message".to_string(), CryptoAction::SignOnly),
        ("ProjectStart".to_string(), CryptoAction::SignOnly),
        ("Duration".to_string(), CryptoAction::SignOnly),
    ]);

    // 12. Set up table config
    let table_config = DynamoDbTableEncryptionConfig::builder()
        .logical_table_name(ddb_table_name)
        .partition_key_name("partition_key")
        .attribute_actions_on_encrypt(attribute_actions_on_encrypt)
        .keyring(kms_keyring)
        .search(
            SearchConfig::builder()
                .write_version(1)
                .versions(beacon_versions)
                .build()?,
        )
        .build()?;

    let table_configs = DynamoDbTablesEncryptionConfig::builder()
        .table_encryption_configs(HashMap::from([(ddb_table_name.to_string(), table_config)]))
        .build()?;

    // 13. Create a new AWS SDK DynamoDb client using the config above
    let sdk_config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
    let dynamo_config = aws_sdk_dynamodb::config::Builder::from(&sdk_config)
        .interceptor(DbEsdkInterceptor::new(table_configs)?)
        .build();

    Ok(aws_sdk_dynamodb::Client::from_conf(dynamo_config))
}

impl Client

pub fn create_aws_kms_rsa_keyring(&self) -> CreateAwsKmsRsaKeyringFluentBuilder

Constructs a fluent builder for the CreateAwsKmsRsaKeyring operation.

• The fluent builder is configurable:
  • encryption_algorithm(impl Into<Option<aws_sdk_kms::types::EncryptionAlgorithmSpec>>) / set_encryption_algorithm(Option<aws_sdk_kms::types::EncryptionAlgorithmSpec>): (undocumented)
    
  • grant_tokens(impl Into<Option<::std::vec::Vec<::std::string::String>>>) / set_grant_tokens(Option<::std::vec::Vec<::std::string::String>>): (undocumented)
    
  • kms_client(impl Into<Option<crate::deps::com_amazonaws_kms::client::Client>>) / set_kms_client(Option<crate::deps::com_amazonaws_kms::client::Client>): (undocumented)
    
  • kms_key_id(impl Into<Option<::std::string::String>>) / set_kms_key_id(Option<::std::string::String>): (undocumented)
    
  • public_key(impl Into<Option<::aws_smithy_types::Blob>>) / set_public_key(Option<::aws_smithy_types::Blob>): (undocumented)
    
• On success, responds with CreateKeyringOutput with field(s):
  • keyring(Option<crate::deps::aws_cryptography_materialProviders::types::keyring::KeyringRef>): (undocumented)
• On failure, responds with SdkError<CreateAwsKmsRsaKeyringError>

Examples found in repository

examples/keyring/kms_rsa_keyring.rs (line 82)

pub async fn put_item_get_item() -> Result<(), crate::BoxError> {
    let ddb_table_name = test_utils::TEST_DDB_TABLE_NAME;
    let rsa_key_arn = test_utils::TEST_KMS_RSA_KEY_ID;

    // You may provide your own RSA public key at EXAMPLE_RSA_PUBLIC_KEY_FILENAME.
    // This must be the public key for the RSA key represented at rsaKeyArn.
    // If this file is not present, this will write a UTF-8 encoded PEM file for you.
    if should_get_new_public_key(DEFAULT_EXAMPLE_RSA_PUBLIC_KEY_FILENAME) {
        write_public_key_pem_for_rsa_key(
            test_utils::TEST_KMS_RSA_KEY_ID,
            DEFAULT_EXAMPLE_RSA_PUBLIC_KEY_FILENAME,
        )
        .await?;
    }

    // 1. Load UTF-8 encoded public key PEM file.
    //    You may have an RSA public key file already defined.
    //    If not, the main method in this class will call
    //    the KMS RSA key, retrieve its public key, and store it
    //    in a PEM file for example use.
    let mut file = File::open(Path::new(DEFAULT_EXAMPLE_RSA_PUBLIC_KEY_FILENAME))?;
    let mut public_key_utf8_bytes = Vec::new();
    file.read_to_end(&mut public_key_utf8_bytes)?;

    // 2. Create a KMS RSA keyring.
    //    This keyring takes in:
    //     - kmsClient
    //     - kmsKeyId: Must be an ARN representing a KMS RSA key
    //     - publicKey: A ByteBuffer of a UTF-8 encoded PEM file representing the public
    //                  key for the key passed into kmsKeyId
    //     - encryptionAlgorithm: Must be either RSAES_OAEP_SHA_256 or RSAES_OAEP_SHA_1
    let mpl_config = MaterialProvidersConfig::builder().build()?;
    let mpl = mpl_client::Client::from_conf(mpl_config)?;
    let sdk_config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
    let kms_rsa_keyring = mpl
        .create_aws_kms_rsa_keyring()
        .kms_key_id(rsa_key_arn)
        .public_key(public_key_utf8_bytes)
        .encryption_algorithm(aws_sdk_kms::types::EncryptionAlgorithmSpec::RsaesOaepSha256)
        .kms_client(aws_sdk_kms::Client::new(&sdk_config))
        .send()
        .await?;

    // 3. Configure which attributes are encrypted and/or signed when writing new items.
    //    For each attribute that may exist on the items we plan to write to our DynamoDbTable,
    //    we must explicitly configure how they should be treated during item encryption:
    //      - ENCRYPT_AND_SIGN: The attribute is encrypted and included in the signature
    //      - SIGN_ONLY: The attribute not encrypted, but is still included in the signature
    //      - DO_NOTHING: The attribute is not encrypted and not included in the signature
    let attribute_actions_on_encrypt = HashMap::from([
        ("partition_key".to_string(), CryptoAction::SignOnly), // Our partition attribute must be SIGN_ONLY
        ("sort_key".to_string(), CryptoAction::SignOnly), // Our sort attribute must be SIGN_ONLY
        ("sensitive_data".to_string(), CryptoAction::EncryptAndSign),
    ]);

    // 4. Configure which attributes we expect to be included in the signature
    //    when reading items. There are two options for configuring this:
    //
    //    - (Recommended) Configure `allowedUnsignedAttributesPrefix`:
    //      When defining your DynamoDb schema and deciding on attribute names,
    //      choose a distinguishing prefix (such as ":") for all attributes that
    //      you do not want to include in the signature.
    //      This has two main benefits:
    //      - It is easier to reason about the security and authenticity of data within your item
    //        when all unauthenticated data is easily distinguishable by their attribute name.
    //      - If you need to add new unauthenticated attributes in the future,
    //        you can easily make the corresponding update to your `attributeActions`
    //        and immediately start writing to that new attribute, without
    //        any other configuration update needed.
    //      Once you configure this field, it is not safe to update it.
    //
    //    - Configure `allowedUnsignedAttributes`: You may also explicitly list
    //      a set of attributes that should be considered unauthenticated when encountered
    //      on read. Be careful if you use this configuration. Do not remove an attribute
    //      name from this configuration, even if you are no longer writing with that attribute,
    //      as old items may still include this attribute, and our configuration needs to know
    //      to continue to exclude this attribute from the signature scope.
    //      If you add new attribute names to this field, you must first deploy the update to this
    //      field to all readers in your host fleet before deploying the update to start writing
    //      with that new attribute.
    //
    //   For this example, we currently authenticate all attributes. To make it easier to
    //   add unauthenticated attributes in the future, we define a prefix ":" for such attributes.
    const UNSIGNED_ATTR_PREFIX: &str = ":";

    // 5. Create the DynamoDb Encryption configuration for the table we will be writing to.
    //    Note: To use the KMS RSA keyring, your table config must specify an algorithmSuite
    //    that does not use asymmetric signing.
    let table_config = DynamoDbTableEncryptionConfig::builder()
        .logical_table_name(ddb_table_name)
        .partition_key_name("partition_key")
        .sort_key_name("sort_key")
        .attribute_actions_on_encrypt(attribute_actions_on_encrypt)
        .keyring(kms_rsa_keyring)
        .allowed_unsigned_attribute_prefix(UNSIGNED_ATTR_PREFIX)
        // Specify algorithmSuite without asymmetric signing here
        // As of v3.0.0, the only supported algorithmSuite without asymmetric signing is
        // ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY_SYMSIG_HMAC_SHA384.
        .algorithm_suite_id(DbeAlgorithmSuiteId::AlgAes256GcmHkdfSha512CommitKeySymsigHmacSha384)
        .build()?;

    let table_configs = DynamoDbTablesEncryptionConfig::builder()
        .table_encryption_configs(HashMap::from([(ddb_table_name.to_string(), table_config)]))
        .build()?;

    // 6. Create a new AWS SDK DynamoDb client using the DynamoDb Encryption Interceptor above
    let dynamo_config = aws_sdk_dynamodb::config::Builder::from(&sdk_config)
        .interceptor(DbEsdkInterceptor::new(table_configs)?)
        .build();
    let ddb = aws_sdk_dynamodb::Client::from_conf(dynamo_config);

    // 7. Put an item into our table using the above client.
    //    Before the item gets sent to DynamoDb, it will be encrypted
    //    client-side, according to our configuration.
    let item = HashMap::from([
        (
            "partition_key".to_string(),
            AttributeValue::S("awsKmsRsaKeyringItem".to_string()),
        ),
        ("sort_key".to_string(), AttributeValue::N("0".to_string())),
        (
            "sensitive_data".to_string(),
            AttributeValue::S("encrypt and sign me!".to_string()),
        ),
    ]);

    ddb.put_item()
        .table_name(ddb_table_name)
        .set_item(Some(item.clone()))
        .send()
        .await?;

    // 8. Get the item back from our table using the client.
    //    The client will decrypt the item client-side using the RSA keyring
    //    and return the original item.
    let key_to_get = HashMap::from([
        (
            "partition_key".to_string(),
            AttributeValue::S("awsKmsRsaKeyringItem".to_string()),
        ),
        ("sort_key".to_string(), AttributeValue::N("0".to_string())),
    ]);

    let resp = ddb
        .get_item()
        .table_name(ddb_table_name)
        .set_key(Some(key_to_get))
        .consistent_read(true)
        .send()
        .await?;

    assert_eq!(resp.item, Some(item));
    println!("kms_rsa_keyring successful.");
    Ok(())
}

impl Client

pub fn create_aws_kms_ecdh_keyring( &self, ) -> CreateAwsKmsEcdhKeyringFluentBuilder

Constructs a fluent builder for the CreateAwsKmsEcdhKeyring operation.

• The fluent builder is configurable:
  • key_agreement_scheme(impl Into<Option<crate::deps::aws_cryptography_materialProviders::types::KmsEcdhStaticConfigurations>>) / set_key_agreement_scheme(Option<crate::deps::aws_cryptography_materialProviders::types::KmsEcdhStaticConfigurations>): (undocumented)
    
  • curve_spec(impl Into<Option<crate::deps::aws_cryptography_primitives::types::EcdhCurveSpec>>) / set_curve_spec(Option<crate::deps::aws_cryptography_primitives::types::EcdhCurveSpec>): (undocumented)
    
  • grant_tokens(impl Into<Option<::std::vec::Vec<::std::string::String>>>) / set_grant_tokens(Option<::std::vec::Vec<::std::string::String>>): (undocumented)
    
  • kms_client(impl Into<Option<crate::deps::com_amazonaws_kms::client::Client>>) / set_kms_client(Option<crate::deps::com_amazonaws_kms::client::Client>): (undocumented)
    
• On success, responds with CreateKeyringOutput with field(s):
  • keyring(Option<crate::deps::aws_cryptography_materialProviders::types::keyring::KeyringRef>): (undocumented)
• On failure, responds with SdkError<CreateAwsKmsEcdhKeyringError>

impl Client

pub fn create_multi_keyring(&self) -> CreateMultiKeyringFluentBuilder

Constructs a fluent builder for the CreateMultiKeyring operation.

• The fluent builder is configurable:
  • child_keyrings(impl Into<Option<::std::vec::Vec<crate::deps::aws_cryptography_materialProviders::types::keyring::KeyringRef>>>) / set_child_keyrings(Option<::std::vec::Vec<crate::deps::aws_cryptography_materialProviders::types::keyring::KeyringRef>>): (undocumented)
    
  • generator(impl Into<Option<crate::deps::aws_cryptography_materialProviders::types::keyring::KeyringRef>>) / set_generator(Option<crate::deps::aws_cryptography_materialProviders::types::keyring::KeyringRef>): (undocumented)
    
• On success, responds with CreateKeyringOutput with field(s):
  • keyring(Option<crate::deps::aws_cryptography_materialProviders::types::keyring::KeyringRef>): (undocumented)
• On failure, responds with SdkError<CreateMultiKeyringError>

Examples found in repository

examples/keyring/multi_keyring.rs (line 82)

pub async fn put_item_get_item() -> Result<(), crate::BoxError> {
    let ddb_table_name = test_utils::TEST_DDB_TABLE_NAME;
    let key_arn = test_utils::TEST_KMS_KEY_ID;
    let aes_key_bytes = generate_aes_key_bytes();

    // 1. Create the raw AES keyring.
    let mpl_config = MaterialProvidersConfig::builder().build()?;
    let mpl = mpl_client::Client::from_conf(mpl_config)?;
    let raw_aes_keyring = mpl
        .create_raw_aes_keyring()
        .key_name("my-aes-key-name")
        .key_namespace("my-key-namespace")
        .wrapping_key(aes_key_bytes)
        .wrapping_alg(AesWrappingAlg::AlgAes256GcmIv12Tag16)
        .send()
        .await?;

    // 2. Create the AWS KMS keyring.
    //    We create a MRK multi keyring, as this interface also supports
    //    single-region KMS keys (standard KMS keys),
    //    and creates the KMS client for us automatically.
    let aws_kms_mrk_multi_keyring = mpl
        .create_aws_kms_mrk_multi_keyring()
        .generator(key_arn)
        .send()
        .await?;

    // 3. Create the multi-keyring.
    //    We will label the AWS KMS keyring as the generator and the raw AES keyring as the
    //        only child keyring.
    //    You must provide a generator keyring to encrypt data.
    //    You may provide additional child keyrings. Each child keyring will be able to
    //        decrypt data encrypted with the multi-keyring on its own. It does not need
    //        knowledge of any other child keyrings or the generator keyring to decrypt.

    let multi_keyring = mpl
        .create_multi_keyring()
        .generator(aws_kms_mrk_multi_keyring)
        .child_keyrings(vec![raw_aes_keyring.clone()])
        .send()
        .await?;

    // 4. Configure which attributes are encrypted and/or signed when writing new items.
    //    For each attribute that may exist on the items we plan to write to our DynamoDbTable,
    //    we must explicitly configure how they should be treated during item encryption:
    //      - ENCRYPT_AND_SIGN: The attribute is encrypted and included in the signature
    //      - SIGN_ONLY: The attribute not encrypted, but is still included in the signature
    //      - DO_NOTHING: The attribute is not encrypted and not included in the signature
    let attribute_actions_on_encrypt = HashMap::from([
        ("partition_key".to_string(), CryptoAction::SignOnly), // Our partition attribute must be SIGN_ONLY
        ("sort_key".to_string(), CryptoAction::SignOnly), // Our sort attribute must be SIGN_ONLY
        ("sensitive_data".to_string(), CryptoAction::EncryptAndSign),
    ]);

    // 5. Configure which attributes we expect to be included in the signature
    //    when reading items. There are two options for configuring this:
    //
    //    - (Recommended) Configure `allowedUnsignedAttributesPrefix`:
    //      When defining your DynamoDb schema and deciding on attribute names,
    //      choose a distinguishing prefix (such as ":") for all attributes that
    //      you do not want to include in the signature.
    //      This has two main benefits:
    //      - It is easier to reason about the security and authenticity of data within your item
    //        when all unauthenticated data is easily distinguishable by their attribute name.
    //      - If you need to add new unauthenticated attributes in the future,
    //        you can easily make the corresponding update to your `attributeActionsOnEncrypt`
    //        and immediately start writing to that new attribute, without
    //        any other configuration update needed.
    //      Once you configure this field, it is not safe to update it.
    //
    //    - Configure `allowedUnsignedAttributes`: You may also explicitly list
    //      a set of attributes that should be considered unauthenticated when encountered
    //      on read. Be careful if you use this configuration. Do not remove an attribute
    //      name from this configuration, even if you are no longer writing with that attribute,
    //      as old items may still include this attribute, and our configuration needs to know
    //      to continue to exclude this attribute from the signature scope.
    //      If you add new attribute names to this field, you must first deploy the update to this
    //      field to all readers in your host fleet before deploying the update to start writing
    //      with that new attribute.
    //
    //   For this example, we currently authenticate all attributes. To make it easier to
    //   add unauthenticated attributes in the future, we define a prefix ":" for such attributes.
    const UNSIGNED_ATTR_PREFIX: &str = ":";

    // 6. Create the DynamoDb Encryption configuration for the table we will be writing to.
    //    Note that this example creates one config/client combination for PUT, and another
    //        for GET. The PUT config uses the multi-keyring, while the GET config uses the
    //        raw AES keyring. This is solely done to demonstrate that a keyring included as
    //        a child of a multi-keyring can be used to decrypt data on its own.
    let table_config = DynamoDbTableEncryptionConfig::builder()
        .logical_table_name(ddb_table_name)
        .partition_key_name("partition_key")
        .sort_key_name("sort_key")
        .attribute_actions_on_encrypt(attribute_actions_on_encrypt.clone())
        .keyring(multi_keyring)
        .allowed_unsigned_attribute_prefix(UNSIGNED_ATTR_PREFIX)
        .build()?;

    let table_configs = DynamoDbTablesEncryptionConfig::builder()
        .table_encryption_configs(HashMap::from([(ddb_table_name.to_string(), table_config)]))
        .build()?;

    // 7. Create a new AWS SDK DynamoDb client using the config above
    let sdk_config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
    let dynamo_config = aws_sdk_dynamodb::config::Builder::from(&sdk_config)
        .interceptor(DbEsdkInterceptor::new(table_configs)?)
        .build();
    let ddb = aws_sdk_dynamodb::Client::from_conf(dynamo_config);

    // 8. Put an item into our table using the above client.
    //    Before the item gets sent to DynamoDb, it will be encrypted
    //    client-side using the multi-keyring.
    //    The item will be encrypted with all wrapping keys in the keyring,
    //    so that it can be decrypted with any one of the keys.
    let item = HashMap::from([
        (
            "partition_key".to_string(),
            AttributeValue::S("multiKeyringItem".to_string()),
        ),
        ("sort_key".to_string(), AttributeValue::N("0".to_string())),
        (
            "sensitive_data".to_string(),
            AttributeValue::S("encrypt and sign me!".to_string()),
        ),
    ]);

    ddb.put_item()
        .table_name(ddb_table_name)
        .set_item(Some(item.clone()))
        .send()
        .await?;

    // 9. Get the item back from our table using the above client.
    //     The client will decrypt the item client-side using the AWS KMS
    //     keyring, and return back the original item.
    //     Since the generator key is the first available key in the keyring,
    //     that is the key that will be used to decrypt this item.
    let key_to_get = HashMap::from([
        (
            "partition_key".to_string(),
            AttributeValue::S("multiKeyringItem".to_string()),
        ),
        ("sort_key".to_string(), AttributeValue::N("0".to_string())),
    ]);

    let resp = ddb
        .get_item()
        .table_name(ddb_table_name)
        .set_key(Some(key_to_get.clone()))
        .consistent_read(true)
        .send()
        .await?;

    assert_eq!(resp.item, Some(item.clone()));

    // 10. Create a new config and client with only the raw AES keyring to GET the item
    //     This is the same setup as above, except the config uses the `rawAesKeyring`.
    let only_aes_table_config = DynamoDbTableEncryptionConfig::builder()
        .logical_table_name(ddb_table_name)
        .partition_key_name("partition_key")
        .sort_key_name("sort_key")
        .attribute_actions_on_encrypt(attribute_actions_on_encrypt)
        .keyring(raw_aes_keyring)
        .allowed_unsigned_attribute_prefix(UNSIGNED_ATTR_PREFIX)
        .build()?;

    let only_aes_table_configs = DynamoDbTablesEncryptionConfig::builder()
        .table_encryption_configs(HashMap::from([(
            ddb_table_name.to_string(),
            only_aes_table_config,
        )]))
        .build()?;

    let only_aes_dynamo_config = aws_sdk_dynamodb::config::Builder::from(&sdk_config)
        .interceptor(DbEsdkInterceptor::new(only_aes_table_configs)?)
        .build();
    let only_aes_ddb = aws_sdk_dynamodb::Client::from_conf(only_aes_dynamo_config);

    // 11. Get the item back from our table using the client
    //     configured with only the raw AES keyring.
    //     The client will decrypt the item client-side using the raw
    //     AES keyring, and return back the original item.
    let resp = only_aes_ddb
        .get_item()
        .table_name(ddb_table_name)
        .set_key(Some(key_to_get.clone()))
        .consistent_read(true)
        .send()
        .await?;

    assert_eq!(resp.item, Some(item.clone()));

    println!("multi_keyring successful.");
    Ok(())
}

impl Client

pub fn create_raw_aes_keyring(&self) -> CreateRawAesKeyringFluentBuilder

Constructs a fluent builder for the CreateRawAesKeyring operation.

• The fluent builder is configurable:
  • key_name(impl Into<Option<::std::string::String>>) / set_key_name(Option<::std::string::String>): (undocumented)
    
  • key_namespace(impl Into<Option<::std::string::String>>) / set_key_namespace(Option<::std::string::String>): (undocumented)
    
  • wrapping_alg(impl Into<Option<crate::deps::aws_cryptography_materialProviders::types::AesWrappingAlg>>) / set_wrapping_alg(Option<crate::deps::aws_cryptography_materialProviders::types::AesWrappingAlg>): (undocumented)
    
  • wrapping_key(impl Into<Option<::aws_smithy_types::Blob>>) / set_wrapping_key(Option<::aws_smithy_types::Blob>): (undocumented)
    
• On success, responds with CreateKeyringOutput with field(s):
  • keyring(Option<crate::deps::aws_cryptography_materialProviders::types::keyring::KeyringRef>): (undocumented)
• On failure, responds with SdkError<CreateRawAesKeyringError>

Examples found in repository

examples/keyring/raw_aes_keyring.rs (line 49)

pub async fn put_item_get_item() -> Result<(), crate::BoxError> {
    let ddb_table_name = test_utils::TEST_DDB_TABLE_NAME;
    let aes_key_bytes = generate_aes_key_bytes();

    // 1. Create the keyring.
    //    The DynamoDb encryption client uses this to encrypt and decrypt items.
    let mpl_config = MaterialProvidersConfig::builder().build()?;
    let mpl = mpl_client::Client::from_conf(mpl_config)?;
    let raw_aes_keyring = mpl
        .create_raw_aes_keyring()
        .key_name("my-aes-key-name")
        .key_namespace("my-key-namespace")
        .wrapping_key(aes_key_bytes)
        .wrapping_alg(AesWrappingAlg::AlgAes256GcmIv12Tag16)
        .send()
        .await?;

    // 2. Configure which attributes are encrypted and/or signed when writing new items.
    //    For each attribute that may exist on the items we plan to write to our DynamoDbTable,
    //    we must explicitly configure how they should be treated during item encryption:
    //      - ENCRYPT_AND_SIGN: The attribute is encrypted and included in the signature
    //      - SIGN_ONLY: The attribute not encrypted, but is still included in the signature
    //      - DO_NOTHING: The attribute is not encrypted and not included in the signature
    let attribute_actions_on_encrypt = HashMap::from([
        ("partition_key".to_string(), CryptoAction::SignOnly), // Our partition attribute must be SIGN_ONLY
        ("sort_key".to_string(), CryptoAction::SignOnly), // Our sort attribute must be SIGN_ONLY
        ("sensitive_data".to_string(), CryptoAction::EncryptAndSign),
    ]);

    // 3. Configure which attributes we expect to be included in the signature
    //    when reading items. There are two options for configuring this:
    //
    //    - (Recommended) Configure `allowedUnsignedAttributesPrefix`:
    //      When defining your DynamoDb schema and deciding on attribute names,
    //      choose a distinguishing prefix (such as ":") for all attributes that
    //      you do not want to include in the signature.
    //      This has two main benefits:
    //      - It is easier to reason about the security and authenticity of data within your item
    //        when all unauthenticated data is easily distinguishable by their attribute name.
    //      - If you need to add new unauthenticated attributes in the future,
    //        you can easily make the corresponding update to your `attributeActionsOnEncrypt`
    //        and immediately start writing to that new attribute, without
    //        any other configuration update needed.
    //      Once you configure this field, it is not safe to update it.
    //
    //    - Configure `allowedUnsignedAttributes`: You may also explicitly list
    //      a set of attributes that should be considered unauthenticated when encountered
    //      on read. Be careful if you use this configuration. Do not remove an attribute
    //      name from this configuration, even if you are no longer writing with that attribute,
    //      as old items may still include this attribute, and our configuration needs to know
    //      to continue to exclude this attribute from the signature scope.
    //      If you add new attribute names to this field, you must first deploy the update to this
    //      field to all readers in your host fleet before deploying the update to start writing
    //      with that new attribute.
    //
    //   For this example, we currently authenticate all attributes. To make it easier to
    //   add unauthenticated attributes in the future, we define a prefix ":" for such attributes.
    const UNSIGNED_ATTR_PREFIX: &str = ":";

    // 4. Create the DynamoDb Encryption configuration for the table we will be writing to.
    let table_config = DynamoDbTableEncryptionConfig::builder()
        .logical_table_name(ddb_table_name)
        .partition_key_name("partition_key")
        .sort_key_name("sort_key")
        .attribute_actions_on_encrypt(attribute_actions_on_encrypt)
        .keyring(raw_aes_keyring)
        .allowed_unsigned_attribute_prefix(UNSIGNED_ATTR_PREFIX)
        .build()?;

    let table_configs = DynamoDbTablesEncryptionConfig::builder()
        .table_encryption_configs(HashMap::from([(ddb_table_name.to_string(), table_config)]))
        .build()?;

    // 5. Create a new AWS SDK DynamoDb client using the Config above
    let sdk_config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
    let dynamo_config = aws_sdk_dynamodb::config::Builder::from(&sdk_config)
        .interceptor(DbEsdkInterceptor::new(table_configs)?)
        .build();
    let ddb = aws_sdk_dynamodb::Client::from_conf(dynamo_config);

    // 6. Put an item into our table using the above client.
    //    Before the item gets sent to DynamoDb, it will be encrypted
    //    client-side, according to our configuration.
    let item = HashMap::from([
        (
            "partition_key".to_string(),
            AttributeValue::S("rawAesKeyringItem".to_string()),
        ),
        ("sort_key".to_string(), AttributeValue::N("0".to_string())),
        (
            "sensitive_data".to_string(),
            AttributeValue::S("encrypt and sign me!".to_string()),
        ),
    ]);

    ddb.put_item()
        .table_name(ddb_table_name)
        .set_item(Some(item.clone()))
        .send()
        .await?;

    // 7. Get the item back from our table using the same client.
    //    The client will decrypt the item client-side, and return
    //    back the original item.
    let key_to_get = HashMap::from([
        (
            "partition_key".to_string(),
            AttributeValue::S("rawAesKeyringItem".to_string()),
        ),
        ("sort_key".to_string(), AttributeValue::N("0".to_string())),
    ]);

    let resp = ddb
        .get_item()
        .table_name(ddb_table_name)
        .set_key(Some(key_to_get))
        // In this example we configure a strongly consistent read
        // because we perform a read immediately after a write (for demonstrative purposes).
        // By default, reads are only eventually consistent.
        // Read our docs to determine which read consistency to use for your application:
        // https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.ReadConsistency.html
        .consistent_read(true)
        .send()
        .await?;

    assert_eq!(resp.item, Some(item));

    println!("raw_aes_keyring successful.");
    Ok(())
}

examples/keyring/multi_keyring.rs (line 55)

pub async fn put_item_get_item() -> Result<(), crate::BoxError> {
    let ddb_table_name = test_utils::TEST_DDB_TABLE_NAME;
    let key_arn = test_utils::TEST_KMS_KEY_ID;
    let aes_key_bytes = generate_aes_key_bytes();

    // 1. Create the raw AES keyring.
    let mpl_config = MaterialProvidersConfig::builder().build()?;
    let mpl = mpl_client::Client::from_conf(mpl_config)?;
    let raw_aes_keyring = mpl
        .create_raw_aes_keyring()
        .key_name("my-aes-key-name")
        .key_namespace("my-key-namespace")
        .wrapping_key(aes_key_bytes)
        .wrapping_alg(AesWrappingAlg::AlgAes256GcmIv12Tag16)
        .send()
        .await?;

    // 2. Create the AWS KMS keyring.
    //    We create a MRK multi keyring, as this interface also supports
    //    single-region KMS keys (standard KMS keys),
    //    and creates the KMS client for us automatically.
    let aws_kms_mrk_multi_keyring = mpl
        .create_aws_kms_mrk_multi_keyring()
        .generator(key_arn)
        .send()
        .await?;

    // 3. Create the multi-keyring.
    //    We will label the AWS KMS keyring as the generator and the raw AES keyring as the
    //        only child keyring.
    //    You must provide a generator keyring to encrypt data.
    //    You may provide additional child keyrings. Each child keyring will be able to
    //        decrypt data encrypted with the multi-keyring on its own. It does not need
    //        knowledge of any other child keyrings or the generator keyring to decrypt.

    let multi_keyring = mpl
        .create_multi_keyring()
        .generator(aws_kms_mrk_multi_keyring)
        .child_keyrings(vec![raw_aes_keyring.clone()])
        .send()
        .await?;

    // 4. Configure which attributes are encrypted and/or signed when writing new items.
    //    For each attribute that may exist on the items we plan to write to our DynamoDbTable,
    //    we must explicitly configure how they should be treated during item encryption:
    //      - ENCRYPT_AND_SIGN: The attribute is encrypted and included in the signature
    //      - SIGN_ONLY: The attribute not encrypted, but is still included in the signature
    //      - DO_NOTHING: The attribute is not encrypted and not included in the signature
    let attribute_actions_on_encrypt = HashMap::from([
        ("partition_key".to_string(), CryptoAction::SignOnly), // Our partition attribute must be SIGN_ONLY
        ("sort_key".to_string(), CryptoAction::SignOnly), // Our sort attribute must be SIGN_ONLY
        ("sensitive_data".to_string(), CryptoAction::EncryptAndSign),
    ]);

    // 5. Configure which attributes we expect to be included in the signature
    //    when reading items. There are two options for configuring this:
    //
    //    - (Recommended) Configure `allowedUnsignedAttributesPrefix`:
    //      When defining your DynamoDb schema and deciding on attribute names,
    //      choose a distinguishing prefix (such as ":") for all attributes that
    //      you do not want to include in the signature.
    //      This has two main benefits:
    //      - It is easier to reason about the security and authenticity of data within your item
    //        when all unauthenticated data is easily distinguishable by their attribute name.
    //      - If you need to add new unauthenticated attributes in the future,
    //        you can easily make the corresponding update to your `attributeActionsOnEncrypt`
    //        and immediately start writing to that new attribute, without
    //        any other configuration update needed.
    //      Once you configure this field, it is not safe to update it.
    //
    //    - Configure `allowedUnsignedAttributes`: You may also explicitly list
    //      a set of attributes that should be considered unauthenticated when encountered
    //      on read. Be careful if you use this configuration. Do not remove an attribute
    //      name from this configuration, even if you are no longer writing with that attribute,
    //      as old items may still include this attribute, and our configuration needs to know
    //      to continue to exclude this attribute from the signature scope.
    //      If you add new attribute names to this field, you must first deploy the update to this
    //      field to all readers in your host fleet before deploying the update to start writing
    //      with that new attribute.
    //
    //   For this example, we currently authenticate all attributes. To make it easier to
    //   add unauthenticated attributes in the future, we define a prefix ":" for such attributes.
    const UNSIGNED_ATTR_PREFIX: &str = ":";

    // 6. Create the DynamoDb Encryption configuration for the table we will be writing to.
    //    Note that this example creates one config/client combination for PUT, and another
    //        for GET. The PUT config uses the multi-keyring, while the GET config uses the
    //        raw AES keyring. This is solely done to demonstrate that a keyring included as
    //        a child of a multi-keyring can be used to decrypt data on its own.
    let table_config = DynamoDbTableEncryptionConfig::builder()
        .logical_table_name(ddb_table_name)
        .partition_key_name("partition_key")
        .sort_key_name("sort_key")
        .attribute_actions_on_encrypt(attribute_actions_on_encrypt.clone())
        .keyring(multi_keyring)
        .allowed_unsigned_attribute_prefix(UNSIGNED_ATTR_PREFIX)
        .build()?;

    let table_configs = DynamoDbTablesEncryptionConfig::builder()
        .table_encryption_configs(HashMap::from([(ddb_table_name.to_string(), table_config)]))
        .build()?;

    // 7. Create a new AWS SDK DynamoDb client using the config above
    let sdk_config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
    let dynamo_config = aws_sdk_dynamodb::config::Builder::from(&sdk_config)
        .interceptor(DbEsdkInterceptor::new(table_configs)?)
        .build();
    let ddb = aws_sdk_dynamodb::Client::from_conf(dynamo_config);

    // 8. Put an item into our table using the above client.
    //    Before the item gets sent to DynamoDb, it will be encrypted
    //    client-side using the multi-keyring.
    //    The item will be encrypted with all wrapping keys in the keyring,
    //    so that it can be decrypted with any one of the keys.
    let item = HashMap::from([
        (
            "partition_key".to_string(),
            AttributeValue::S("multiKeyringItem".to_string()),
        ),
        ("sort_key".to_string(), AttributeValue::N("0".to_string())),
        (
            "sensitive_data".to_string(),
            AttributeValue::S("encrypt and sign me!".to_string()),
        ),
    ]);

    ddb.put_item()
        .table_name(ddb_table_name)
        .set_item(Some(item.clone()))
        .send()
        .await?;

    // 9. Get the item back from our table using the above client.
    //     The client will decrypt the item client-side using the AWS KMS
    //     keyring, and return back the original item.
    //     Since the generator key is the first available key in the keyring,
    //     that is the key that will be used to decrypt this item.
    let key_to_get = HashMap::from([
        (
            "partition_key".to_string(),
            AttributeValue::S("multiKeyringItem".to_string()),
        ),
        ("sort_key".to_string(), AttributeValue::N("0".to_string())),
    ]);

    let resp = ddb
        .get_item()
        .table_name(ddb_table_name)
        .set_key(Some(key_to_get.clone()))
        .consistent_read(true)
        .send()
        .await?;

    assert_eq!(resp.item, Some(item.clone()));

    // 10. Create a new config and client with only the raw AES keyring to GET the item
    //     This is the same setup as above, except the config uses the `rawAesKeyring`.
    let only_aes_table_config = DynamoDbTableEncryptionConfig::builder()
        .logical_table_name(ddb_table_name)
        .partition_key_name("partition_key")
        .sort_key_name("sort_key")
        .attribute_actions_on_encrypt(attribute_actions_on_encrypt)
        .keyring(raw_aes_keyring)
        .allowed_unsigned_attribute_prefix(UNSIGNED_ATTR_PREFIX)
        .build()?;

    let only_aes_table_configs = DynamoDbTablesEncryptionConfig::builder()
        .table_encryption_configs(HashMap::from([(
            ddb_table_name.to_string(),
            only_aes_table_config,
        )]))
        .build()?;

    let only_aes_dynamo_config = aws_sdk_dynamodb::config::Builder::from(&sdk_config)
        .interceptor(DbEsdkInterceptor::new(only_aes_table_configs)?)
        .build();
    let only_aes_ddb = aws_sdk_dynamodb::Client::from_conf(only_aes_dynamo_config);

    // 11. Get the item back from our table using the client
    //     configured with only the raw AES keyring.
    //     The client will decrypt the item client-side using the raw
    //     AES keyring, and return back the original item.
    let resp = only_aes_ddb
        .get_item()
        .table_name(ddb_table_name)
        .set_key(Some(key_to_get.clone()))
        .consistent_read(true)
        .send()
        .await?;

    assert_eq!(resp.item, Some(item.clone()));

    println!("multi_keyring successful.");
    Ok(())
}

impl Client

pub fn create_raw_rsa_keyring(&self) -> CreateRawRsaKeyringFluentBuilder

Constructs a fluent builder for the CreateRawRsaKeyring operation.

• The fluent builder is configurable:
  • key_name(impl Into<Option<::std::string::String>>) / set_key_name(Option<::std::string::String>): (undocumented)
    
  • key_namespace(impl Into<Option<::std::string::String>>) / set_key_namespace(Option<::std::string::String>): (undocumented)
    
  • padding_scheme(impl Into<Option<crate::deps::aws_cryptography_materialProviders::types::PaddingScheme>>) / set_padding_scheme(Option<crate::deps::aws_cryptography_materialProviders::types::PaddingScheme>): (undocumented)
    
  • private_key(impl Into<Option<::aws_smithy_types::Blob>>) / set_private_key(Option<::aws_smithy_types::Blob>): (undocumented)
    
  • public_key(impl Into<Option<::aws_smithy_types::Blob>>) / set_public_key(Option<::aws_smithy_types::Blob>): (undocumented)
    
• On success, responds with CreateKeyringOutput with field(s):
  • keyring(Option<crate::deps::aws_cryptography_materialProviders::types::keyring::KeyringRef>): (undocumented)
• On failure, responds with SdkError<CreateRawRsaKeyringError>

Examples found in repository

examples/keyring/raw_rsa_keyring.rs (line 86)

pub async fn put_item_get_item() -> Result<(), crate::BoxError> {
    let ddb_table_name = test_utils::TEST_DDB_TABLE_NAME;

    // You may provide your own RSA key pair in the files located at
    //  - EXAMPLE_RSA_PRIVATE_KEY_FILENAME
    //  - EXAMPLE_RSA_PUBLIC_KEY_FILENAME
    // If these files are not present, this will generate a pair for you
    if should_generate_new_rsa_key_pair()? {
        generate_rsa_key_pair()?;
    }

    // 1. Load key pair from UTF-8 encoded PEM files.
    //    You may provide your own PEM files to use here.
    //    If you do not, the main method in this class will generate PEM
    //    files for example use. Do not use these files for any other purpose.

    let mut file = File::open(Path::new(EXAMPLE_RSA_PUBLIC_KEY_FILENAME))?;
    let mut public_key_utf8_bytes = Vec::new();
    file.read_to_end(&mut public_key_utf8_bytes)?;

    let mut file = File::open(Path::new(EXAMPLE_RSA_PRIVATE_KEY_FILENAME))?;
    let mut private_key_utf8_bytes = Vec::new();
    file.read_to_end(&mut private_key_utf8_bytes)?;

    // 2. Create the keyring.
    //    The DynamoDb encryption client uses this to encrypt and decrypt items.
    let mpl_config = MaterialProvidersConfig::builder().build()?;
    let mpl = mpl_client::Client::from_conf(mpl_config)?;
    let raw_rsa_keyring = mpl
        .create_raw_rsa_keyring()
        .key_name("my-rsa-key-name")
        .key_namespace("my-key-namespace")
        .padding_scheme(PaddingScheme::OaepSha256Mgf1)
        .public_key(public_key_utf8_bytes)
        .private_key(private_key_utf8_bytes)
        .send()
        .await?;

    // 3. Configure which attributes are encrypted and/or signed when writing new items.
    //    For each attribute that may exist on the items we plan to write to our DynamoDbTable,
    //    we must explicitly configure how they should be treated during item encryption:
    //      - ENCRYPT_AND_SIGN: The attribute is encrypted and included in the signature
    //      - SIGN_ONLY: The attribute not encrypted, but is still included in the signature
    //      - DO_NOTHING: The attribute is not encrypted and not included in the signature
    let attribute_actions_on_encrypt = HashMap::from([
        ("partition_key".to_string(), CryptoAction::SignOnly), // Our partition attribute must be SIGN_ONLY
        ("sort_key".to_string(), CryptoAction::SignOnly), // Our sort attribute must be SIGN_ONLY
        ("sensitive_data".to_string(), CryptoAction::EncryptAndSign),
    ]);

    // 4. Configure which attributes we expect to be included in the signature
    //    when reading items. There are two options for configuring this:
    //
    //    - (Recommended) Configure `allowedUnsignedAttributesPrefix`:
    //      When defining your DynamoDb schema and deciding on attribute names,
    //      choose a distinguishing prefix (such as ":") for all attributes that
    //      you do not want to include in the signature.
    //      This has two main benefits:
    //      - It is easier to reason about the security and authenticity of data within your item
    //        when all unauthenticated data is easily distinguishable by their attribute name.
    //      - If you need to add new unauthenticated attributes in the future,
    //        you can easily make the corresponding update to your `attributeActionsOnEncrypt`
    //        and immediately start writing to that new attribute, without
    //        any other configuration update needed.
    //      Once you configure this field, it is not safe to update it.
    //
    //    - Configure `allowedUnsignedAttributes`: You may also explicitly list
    //      a set of attributes that should be considered unauthenticated when encountered
    //      on read. Be careful if you use this configuration. Do not remove an attribute
    //      name from this configuration, even if you are no longer writing with that attribute,
    //      as old items may still include this attribute, and our configuration needs to know
    //      to continue to exclude this attribute from the signature scope.
    //      If you add new attribute names to this field, you must first deploy the update to this
    //      field to all readers in your host fleet before deploying the update to start writing
    //      with that new attribute.
    //
    //   For this example, we currently authenticate all attributes. To make it easier to
    //   add unauthenticated attributes in the future, we define a prefix ":" for such attributes.
    const UNSIGNED_ATTR_PREFIX: &str = ":";

    // 5. Create the DynamoDb Encryption configuration for the table we will be writing to.
    let table_config = DynamoDbTableEncryptionConfig::builder()
        .logical_table_name(ddb_table_name)
        .partition_key_name("partition_key")
        .sort_key_name("sort_key")
        .attribute_actions_on_encrypt(attribute_actions_on_encrypt)
        .keyring(raw_rsa_keyring)
        .allowed_unsigned_attribute_prefix(UNSIGNED_ATTR_PREFIX)
        .build()?;

    let table_configs = DynamoDbTablesEncryptionConfig::builder()
        .table_encryption_configs(HashMap::from([(ddb_table_name.to_string(), table_config)]))
        .build()?;

    // 6. Create a new AWS SDK DynamoDb client using the config above
    let sdk_config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
    let dynamo_config = aws_sdk_dynamodb::config::Builder::from(&sdk_config)
        .interceptor(DbEsdkInterceptor::new(table_configs)?)
        .build();
    let ddb = aws_sdk_dynamodb::Client::from_conf(dynamo_config);

    // 7. Put an item into our table using the above client.
    //    Before the item gets sent to DynamoDb, it will be encrypted
    //    client-side, according to our configuration.
    let item = HashMap::from([
        (
            "partition_key".to_string(),
            AttributeValue::S("rawRsaKeyringItem".to_string()),
        ),
        ("sort_key".to_string(), AttributeValue::N("0".to_string())),
        (
            "sensitive_data".to_string(),
            AttributeValue::S("encrypt and sign me!".to_string()),
        ),
    ]);

    ddb.put_item()
        .table_name(ddb_table_name)
        .set_item(Some(item.clone()))
        .send()
        .await?;

    // 8. Get the item back from our table using the same client.
    //    The client will decrypt the item client-side, and return
    //    back the original item.

    let key_to_get = HashMap::from([
        (
            "partition_key".to_string(),
            AttributeValue::S("rawRsaKeyringItem".to_string()),
        ),
        ("sort_key".to_string(), AttributeValue::N("0".to_string())),
    ]);

    let resp = ddb
        .get_item()
        .table_name(ddb_table_name)
        .set_key(Some(key_to_get))
        // In this example we configure a strongly consistent read
        // because we perform a read immediately after a write (for demonstrative purposes).
        // By default, reads are only eventually consistent.
        // Read our docs to determine which read consistency to use for your application:
        // https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.ReadConsistency.html
        .consistent_read(true)
        .send()
        .await?;

    assert_eq!(resp.item, Some(item));
    println!("raw_rsa_keyring successful.");
    Ok(())
}

impl Client

pub fn create_raw_ecdh_keyring(&self) -> CreateRawEcdhKeyringFluentBuilder

Constructs a fluent builder for the CreateRawEcdhKeyring operation.

• The fluent builder is configurable:
  • key_agreement_scheme(impl Into<Option<crate::deps::aws_cryptography_materialProviders::types::RawEcdhStaticConfigurations>>) / set_key_agreement_scheme(Option<crate::deps::aws_cryptography_materialProviders::types::RawEcdhStaticConfigurations>): (undocumented)
    
  • curve_spec(impl Into<Option<crate::deps::aws_cryptography_primitives::types::EcdhCurveSpec>>) / set_curve_spec(Option<crate::deps::aws_cryptography_primitives::types::EcdhCurveSpec>): (undocumented)
    
• On success, responds with CreateKeyringOutput with field(s):
  • keyring(Option<crate::deps::aws_cryptography_materialProviders::types::keyring::KeyringRef>): (undocumented)
• On failure, responds with SdkError<CreateRawEcdhKeyringError>

impl Client

pub fn create_default_cryptographic_materials_manager( &self, ) -> CreateDefaultCryptographicMaterialsManagerFluentBuilder

Constructs a fluent builder for the CreateDefaultCryptographicMaterialsManager operation.

• The fluent builder is configurable:
  • keyring(impl Into<Option<crate::deps::aws_cryptography_materialProviders::types::keyring::KeyringRef>>) / set_keyring(Option<crate::deps::aws_cryptography_materialProviders::types::keyring::KeyringRef>): (undocumented)
    
• On success, responds with CreateCryptographicMaterialsManagerOutput with field(s):
  • materials_manager(Option<crate::deps::aws_cryptography_materialProviders::types::cryptographic_materials_manager::CryptographicMaterialsManagerRef>): (undocumented)
• On failure, responds with SdkError<CreateDefaultCryptographicMaterialsManagerError>

impl Client

pub fn create_required_encryption_context_cmm( &self, ) -> CreateRequiredEncryptionContextCmmFluentBuilder

Constructs a fluent builder for the CreateRequiredEncryptionContextCMM operation.

• The fluent builder is configurable:
  • keyring(impl Into<Option<crate::deps::aws_cryptography_materialProviders::types::keyring::KeyringRef>>) / set_keyring(Option<crate::deps::aws_cryptography_materialProviders::types::keyring::KeyringRef>): (undocumented)
    
  • required_encryption_context_keys(impl Into<Option<::std::vec::Vec<::std::string::String>>>) / set_required_encryption_context_keys(Option<::std::vec::Vec<::std::string::String>>): (undocumented)
    
  • underlying_cmm(impl Into<Option<crate::deps::aws_cryptography_materialProviders::types::cryptographic_materials_manager::CryptographicMaterialsManagerRef>>) / set_underlying_cmm(Option<crate::deps::aws_cryptography_materialProviders::types::cryptographic_materials_manager::CryptographicMaterialsManagerRef>): (undocumented)
    
• On success, responds with CreateRequiredEncryptionContextCmmOutput with field(s):
  • materials_manager(Option<crate::deps::aws_cryptography_materialProviders::types::cryptographic_materials_manager::CryptographicMaterialsManagerRef>): (undocumented)
• On failure, responds with SdkError<CreateRequiredEncryptionContextCmmError>

impl Client

pub fn create_cryptographic_materials_cache( &self, ) -> CreateCryptographicMaterialsCacheFluentBuilder

Constructs a fluent builder for the CreateCryptographicMaterialsCache operation.

• The fluent builder is configurable:
  • cache(impl Into<Option<crate::deps::aws_cryptography_materialProviders::types::CacheType>>) / set_cache(Option<crate::deps::aws_cryptography_materialProviders::types::CacheType>): (undocumented)
    
• On success, responds with CreateCryptographicMaterialsCacheOutput with field(s):
  • materials_cache(Option<crate::deps::aws_cryptography_materialProviders::types::cryptographic_materials_cache::CryptographicMaterialsCacheRef>): (undocumented)
• On failure, responds with SdkError<CreateCryptographicMaterialsCacheError>

impl Client

pub fn create_default_client_supplier( &self, ) -> CreateDefaultClientSupplierFluentBuilder

Constructs a fluent builder for the CreateDefaultClientSupplier operation.

• The fluent builder is configurable:
• On success, responds with CreateDefaultClientSupplierOutput with field(s):
  • client(Option<crate::deps::aws_cryptography_materialProviders::types::client_supplier::ClientSupplierRef>): (undocumented)
• On failure, responds with SdkError<CreateDefaultClientSupplierError>

impl Client

pub fn initialize_encryption_materials( &self, ) -> InitializeEncryptionMaterialsFluentBuilder

Constructs a fluent builder for the InitializeEncryptionMaterials operation.

• The fluent builder is configurable:
  • algorithm_suite_id(impl Into<Option<crate::deps::aws_cryptography_materialProviders::types::AlgorithmSuiteId>>) / set_algorithm_suite_id(Option<crate::deps::aws_cryptography_materialProviders::types::AlgorithmSuiteId>): (undocumented)
    
  • encryption_context(impl Into<Option<::std::collections::HashMap<::std::string::String, ::std::string::String>>>) / set_encryption_context(Option<::std::collections::HashMap<::std::string::String, ::std::string::String>>): (undocumented)
    
  • required_encryption_context_keys(impl Into<Option<::std::vec::Vec<::std::string::String>>>) / set_required_encryption_context_keys(Option<::std::vec::Vec<::std::string::String>>): (undocumented)
    
  • signing_key(impl Into<Option<::aws_smithy_types::Blob>>) / set_signing_key(Option<::aws_smithy_types::Blob>): (undocumented)
    
  • verification_key(impl Into<Option<::aws_smithy_types::Blob>>) / set_verification_key(Option<::aws_smithy_types::Blob>): (undocumented)
    
• On success, responds with EncryptionMaterials with field(s):
  • algorithm_suite(Option<crate::deps::aws_cryptography_materialProviders::types::AlgorithmSuiteInfo>): (undocumented)
  • encrypted_data_keys(Option<::std::vec::Vec<crate::deps::aws_cryptography_materialProviders::types::EncryptedDataKey>>): (undocumented)
  • encryption_context(Option<::std::collections::HashMap<::std::string::String, ::std::string::String>>): (undocumented)
  • plaintext_data_key(Option<::aws_smithy_types::Blob>): (undocumented)
  • required_encryption_context_keys(Option<::std::vec::Vec<::std::string::String>>): (undocumented)
  • signing_key(Option<::aws_smithy_types::Blob>): (undocumented)
  • symmetric_signing_keys(Option<::std::vec::Vec<::aws_smithy_types::Blob>>): (undocumented)
• On failure, responds with SdkError<InitializeEncryptionMaterialsError>

impl Client

pub fn initialize_decryption_materials( &self, ) -> InitializeDecryptionMaterialsFluentBuilder

Constructs a fluent builder for the InitializeDecryptionMaterials operation.

• The fluent builder is configurable:
  • algorithm_suite_id(impl Into<Option<crate::deps::aws_cryptography_materialProviders::types::AlgorithmSuiteId>>) / set_algorithm_suite_id(Option<crate::deps::aws_cryptography_materialProviders::types::AlgorithmSuiteId>): (undocumented)
    
  • encryption_context(impl Into<Option<::std::collections::HashMap<::std::string::String, ::std::string::String>>>) / set_encryption_context(Option<::std::collections::HashMap<::std::string::String, ::std::string::String>>): (undocumented)
    
  • required_encryption_context_keys(impl Into<Option<::std::vec::Vec<::std::string::String>>>) / set_required_encryption_context_keys(Option<::std::vec::Vec<::std::string::String>>): (undocumented)
    
• On success, responds with DecryptionMaterials with field(s):
  • algorithm_suite(Option<crate::deps::aws_cryptography_materialProviders::types::AlgorithmSuiteInfo>): (undocumented)
  • encryption_context(Option<::std::collections::HashMap<::std::string::String, ::std::string::String>>): (undocumented)
  • plaintext_data_key(Option<::aws_smithy_types::Blob>): (undocumented)
  • required_encryption_context_keys(Option<::std::vec::Vec<::std::string::String>>): (undocumented)
  • symmetric_signing_key(Option<::aws_smithy_types::Blob>): (undocumented)
  • verification_key(Option<::aws_smithy_types::Blob>): (undocumented)
• On failure, responds with SdkError<InitializeDecryptionMaterialsError>

impl Client

pub fn valid_encryption_materials_transition( &self, ) -> ValidEncryptionMaterialsTransitionFluentBuilder

Constructs a fluent builder for the ValidEncryptionMaterialsTransition operation.

• The fluent builder is configurable:
  • start(impl Into<Option<crate::deps::aws_cryptography_materialProviders::types::EncryptionMaterials>>) / set_start(Option<crate::deps::aws_cryptography_materialProviders::types::EncryptionMaterials>): (undocumented)
    
  • stop(impl Into<Option<crate::deps::aws_cryptography_materialProviders::types::EncryptionMaterials>>) / set_stop(Option<crate::deps::aws_cryptography_materialProviders::types::EncryptionMaterials>): (undocumented)
    
• On success, responds with Unit with field(s):
• On failure, responds with SdkError<ValidEncryptionMaterialsTransitionError>

impl Client

pub fn valid_decryption_materials_transition( &self, ) -> ValidDecryptionMaterialsTransitionFluentBuilder

Constructs a fluent builder for the ValidDecryptionMaterialsTransition operation.

• The fluent builder is configurable:
  • start(impl Into<Option<crate::deps::aws_cryptography_materialProviders::types::DecryptionMaterials>>) / set_start(Option<crate::deps::aws_cryptography_materialProviders::types::DecryptionMaterials>): (undocumented)
    
  • stop(impl Into<Option<crate::deps::aws_cryptography_materialProviders::types::DecryptionMaterials>>) / set_stop(Option<crate::deps::aws_cryptography_materialProviders::types::DecryptionMaterials>): (undocumented)
    
• On success, responds with Unit with field(s):
• On failure, responds with SdkError<ValidDecryptionMaterialsTransitionError>

impl Client

pub fn encryption_materials_has_plaintext_data_key( &self, ) -> EncryptionMaterialsHasPlaintextDataKeyFluentBuilder

Constructs a fluent builder for the EncryptionMaterialsHasPlaintextDataKey operation.

• The fluent builder is configurable:
  • algorithm_suite(impl Into<Option<crate::deps::aws_cryptography_materialProviders::types::AlgorithmSuiteInfo>>) / set_algorithm_suite(Option<crate::deps::aws_cryptography_materialProviders::types::AlgorithmSuiteInfo>): (undocumented)
    
  • encrypted_data_keys(impl Into<Option<::std::vec::Vec<crate::deps::aws_cryptography_materialProviders::types::EncryptedDataKey>>>) / set_encrypted_data_keys(Option<::std::vec::Vec<crate::deps::aws_cryptography_materialProviders::types::EncryptedDataKey>>): (undocumented)
    
  • encryption_context(impl Into<Option<::std::collections::HashMap<::std::string::String, ::std::string::String>>>) / set_encryption_context(Option<::std::collections::HashMap<::std::string::String, ::std::string::String>>): (undocumented)
    
  • plaintext_data_key(impl Into<Option<::aws_smithy_types::Blob>>) / set_plaintext_data_key(Option<::aws_smithy_types::Blob>): (undocumented)
    
  • required_encryption_context_keys(impl Into<Option<::std::vec::Vec<::std::string::String>>>) / set_required_encryption_context_keys(Option<::std::vec::Vec<::std::string::String>>): (undocumented)
    
  • signing_key(impl Into<Option<::aws_smithy_types::Blob>>) / set_signing_key(Option<::aws_smithy_types::Blob>): (undocumented)
    
  • symmetric_signing_keys(impl Into<Option<::std::vec::Vec<::aws_smithy_types::Blob>>>) / set_symmetric_signing_keys(Option<::std::vec::Vec<::aws_smithy_types::Blob>>): (undocumented)
    
• On success, responds with Unit with field(s):
• On failure, responds with SdkError<EncryptionMaterialsHasPlaintextDataKeyError>

impl Client

pub fn decryption_materials_with_plaintext_data_key( &self, ) -> DecryptionMaterialsWithPlaintextDataKeyFluentBuilder

Constructs a fluent builder for the DecryptionMaterialsWithPlaintextDataKey operation.

• The fluent builder is configurable:
  • algorithm_suite(impl Into<Option<crate::deps::aws_cryptography_materialProviders::types::AlgorithmSuiteInfo>>) / set_algorithm_suite(Option<crate::deps::aws_cryptography_materialProviders::types::AlgorithmSuiteInfo>): (undocumented)
    
  • encryption_context(impl Into<Option<::std::collections::HashMap<::std::string::String, ::std::string::String>>>) / set_encryption_context(Option<::std::collections::HashMap<::std::string::String, ::std::string::String>>): (undocumented)
    
  • plaintext_data_key(impl Into<Option<::aws_smithy_types::Blob>>) / set_plaintext_data_key(Option<::aws_smithy_types::Blob>): (undocumented)
    
  • required_encryption_context_keys(impl Into<Option<::std::vec::Vec<::std::string::String>>>) / set_required_encryption_context_keys(Option<::std::vec::Vec<::std::string::String>>): (undocumented)
    
  • symmetric_signing_key(impl Into<Option<::aws_smithy_types::Blob>>) / set_symmetric_signing_key(Option<::aws_smithy_types::Blob>): (undocumented)
    
  • verification_key(impl Into<Option<::aws_smithy_types::Blob>>) / set_verification_key(Option<::aws_smithy_types::Blob>): (undocumented)
    
• On success, responds with Unit with field(s):
• On failure, responds with SdkError<DecryptionMaterialsWithPlaintextDataKeyError>

impl Client

pub fn get_algorithm_suite_info(&self) -> GetAlgorithmSuiteInfoFluentBuilder

Constructs a fluent builder for the GetAlgorithmSuiteInfo operation.

• The fluent builder is configurable:
  • binary_id(impl Into<Option<::aws_smithy_types::Blob>>) / set_binary_id(Option<::aws_smithy_types::Blob>): (undocumented)
    
• On success, responds with AlgorithmSuiteInfo with field(s):
  • binary_id(Option<::aws_smithy_types::Blob>): (undocumented)
  • commitment(Option<crate::deps::aws_cryptography_materialProviders::types::DerivationAlgorithm>): (undocumented)
  • edk_wrapping(Option<crate::deps::aws_cryptography_materialProviders::types::EdkWrappingAlgorithm>): (undocumented)
  • encrypt(Option<crate::deps::aws_cryptography_materialProviders::types::Encrypt>): (undocumented)
  • id(Option<crate::deps::aws_cryptography_materialProviders::types::AlgorithmSuiteId>): (undocumented)
  • kdf(Option<crate::deps::aws_cryptography_materialProviders::types::DerivationAlgorithm>): (undocumented)
  • message_version(Option<::std::primitive::i32>): (undocumented)
  • signature(Option<crate::deps::aws_cryptography_materialProviders::types::SignatureAlgorithm>): (undocumented)
  • symmetric_signature(Option<crate::deps::aws_cryptography_materialProviders::types::SymmetricSignatureAlgorithm>): (undocumented)
• On failure, responds with SdkError<GetAlgorithmSuiteInfoError>

impl Client

pub fn valid_algorithm_suite_info(&self) -> ValidAlgorithmSuiteInfoFluentBuilder

Constructs a fluent builder for the ValidAlgorithmSuiteInfo operation.

• The fluent builder is configurable:
  • binary_id(impl Into<Option<::aws_smithy_types::Blob>>) / set_binary_id(Option<::aws_smithy_types::Blob>): (undocumented)
    
  • commitment(impl Into<Option<crate::deps::aws_cryptography_materialProviders::types::DerivationAlgorithm>>) / set_commitment(Option<crate::deps::aws_cryptography_materialProviders::types::DerivationAlgorithm>): (undocumented)
    
  • edk_wrapping(impl Into<Option<crate::deps::aws_cryptography_materialProviders::types::EdkWrappingAlgorithm>>) / set_edk_wrapping(Option<crate::deps::aws_cryptography_materialProviders::types::EdkWrappingAlgorithm>): (undocumented)
    
  • encrypt(impl Into<Option<crate::deps::aws_cryptography_materialProviders::types::Encrypt>>) / set_encrypt(Option<crate::deps::aws_cryptography_materialProviders::types::Encrypt>): (undocumented)
    
  • id(impl Into<Option<crate::deps::aws_cryptography_materialProviders::types::AlgorithmSuiteId>>) / set_id(Option<crate::deps::aws_cryptography_materialProviders::types::AlgorithmSuiteId>): (undocumented)
    
  • kdf(impl Into<Option<crate::deps::aws_cryptography_materialProviders::types::DerivationAlgorithm>>) / set_kdf(Option<crate::deps::aws_cryptography_materialProviders::types::DerivationAlgorithm>): (undocumented)
    
  • message_version(impl Into<Option<::std::primitive::i32>>) / set_message_version(Option<::std::primitive::i32>): (undocumented)
    
  • signature(impl Into<Option<crate::deps::aws_cryptography_materialProviders::types::SignatureAlgorithm>>) / set_signature(Option<crate::deps::aws_cryptography_materialProviders::types::SignatureAlgorithm>): (undocumented)
    
  • symmetric_signature(impl Into<Option<crate::deps::aws_cryptography_materialProviders::types::SymmetricSignatureAlgorithm>>) / set_symmetric_signature(Option<crate::deps::aws_cryptography_materialProviders::types::SymmetricSignatureAlgorithm>): (undocumented)
    
• On success, responds with Unit with field(s):
• On failure, responds with SdkError<ValidAlgorithmSuiteInfoError>

impl Client

pub fn validate_commitment_policy_on_encrypt( &self, ) -> ValidateCommitmentPolicyOnEncryptFluentBuilder

Constructs a fluent builder for the ValidateCommitmentPolicyOnEncrypt operation.

• The fluent builder is configurable:
  • algorithm(impl Into<Option<crate::deps::aws_cryptography_materialProviders::types::AlgorithmSuiteId>>) / set_algorithm(Option<crate::deps::aws_cryptography_materialProviders::types::AlgorithmSuiteId>): (undocumented)
    
  • commitment_policy(impl Into<Option<crate::deps::aws_cryptography_materialProviders::types::CommitmentPolicy>>) / set_commitment_policy(Option<crate::deps::aws_cryptography_materialProviders::types::CommitmentPolicy>): (undocumented)
    
• On success, responds with Unit with field(s):
• On failure, responds with SdkError<ValidateCommitmentPolicyOnEncryptError>

impl Client

pub fn validate_commitment_policy_on_decrypt( &self, ) -> ValidateCommitmentPolicyOnDecryptFluentBuilder

Constructs a fluent builder for the ValidateCommitmentPolicyOnDecrypt operation.

• The fluent builder is configurable:
  • algorithm(impl Into<Option<crate::deps::aws_cryptography_materialProviders::types::AlgorithmSuiteId>>) / set_algorithm(Option<crate::deps::aws_cryptography_materialProviders::types::AlgorithmSuiteId>): (undocumented)
    
  • commitment_policy(impl Into<Option<crate::deps::aws_cryptography_materialProviders::types::CommitmentPolicy>>) / set_commitment_policy(Option<crate::deps::aws_cryptography_materialProviders::types::CommitmentPolicy>): (undocumented)
    
• On success, responds with Unit with field(s):
• On failure, responds with SdkError<ValidateCommitmentPolicyOnDecryptError>

impl Client

pub fn from_conf(input: MaterialProvidersConfig) -> Result<Self, Error>

Creates a new client from the service Config.

Examples found in repository

examples/keyring/raw_aes_keyring.rs (line 47)

pub async fn put_item_get_item() -> Result<(), crate::BoxError> {
    let ddb_table_name = test_utils::TEST_DDB_TABLE_NAME;
    let aes_key_bytes = generate_aes_key_bytes();

    // 1. Create the keyring.
    //    The DynamoDb encryption client uses this to encrypt and decrypt items.
    let mpl_config = MaterialProvidersConfig::builder().build()?;
    let mpl = mpl_client::Client::from_conf(mpl_config)?;
    let raw_aes_keyring = mpl
        .create_raw_aes_keyring()
        .key_name("my-aes-key-name")
        .key_namespace("my-key-namespace")
        .wrapping_key(aes_key_bytes)
        .wrapping_alg(AesWrappingAlg::AlgAes256GcmIv12Tag16)
        .send()
        .await?;

    // 2. Configure which attributes are encrypted and/or signed when writing new items.
    //    For each attribute that may exist on the items we plan to write to our DynamoDbTable,
    //    we must explicitly configure how they should be treated during item encryption:
    //      - ENCRYPT_AND_SIGN: The attribute is encrypted and included in the signature
    //      - SIGN_ONLY: The attribute not encrypted, but is still included in the signature
    //      - DO_NOTHING: The attribute is not encrypted and not included in the signature
    let attribute_actions_on_encrypt = HashMap::from([
        ("partition_key".to_string(), CryptoAction::SignOnly), // Our partition attribute must be SIGN_ONLY
        ("sort_key".to_string(), CryptoAction::SignOnly), // Our sort attribute must be SIGN_ONLY
        ("sensitive_data".to_string(), CryptoAction::EncryptAndSign),
    ]);

    // 3. Configure which attributes we expect to be included in the signature
    //    when reading items. There are two options for configuring this:
    //
    //    - (Recommended) Configure `allowedUnsignedAttributesPrefix`:
    //      When defining your DynamoDb schema and deciding on attribute names,
    //      choose a distinguishing prefix (such as ":") for all attributes that
    //      you do not want to include in the signature.
    //      This has two main benefits:
    //      - It is easier to reason about the security and authenticity of data within your item
    //        when all unauthenticated data is easily distinguishable by their attribute name.
    //      - If you need to add new unauthenticated attributes in the future,
    //        you can easily make the corresponding update to your `attributeActionsOnEncrypt`
    //        and immediately start writing to that new attribute, without
    //        any other configuration update needed.
    //      Once you configure this field, it is not safe to update it.
    //
    //    - Configure `allowedUnsignedAttributes`: You may also explicitly list
    //      a set of attributes that should be considered unauthenticated when encountered
    //      on read. Be careful if you use this configuration. Do not remove an attribute
    //      name from this configuration, even if you are no longer writing with that attribute,
    //      as old items may still include this attribute, and our configuration needs to know
    //      to continue to exclude this attribute from the signature scope.
    //      If you add new attribute names to this field, you must first deploy the update to this
    //      field to all readers in your host fleet before deploying the update to start writing
    //      with that new attribute.
    //
    //   For this example, we currently authenticate all attributes. To make it easier to
    //   add unauthenticated attributes in the future, we define a prefix ":" for such attributes.
    const UNSIGNED_ATTR_PREFIX: &str = ":";

    // 4. Create the DynamoDb Encryption configuration for the table we will be writing to.
    let table_config = DynamoDbTableEncryptionConfig::builder()
        .logical_table_name(ddb_table_name)
        .partition_key_name("partition_key")
        .sort_key_name("sort_key")
        .attribute_actions_on_encrypt(attribute_actions_on_encrypt)
        .keyring(raw_aes_keyring)
        .allowed_unsigned_attribute_prefix(UNSIGNED_ATTR_PREFIX)
        .build()?;

    let table_configs = DynamoDbTablesEncryptionConfig::builder()
        .table_encryption_configs(HashMap::from([(ddb_table_name.to_string(), table_config)]))
        .build()?;

    // 5. Create a new AWS SDK DynamoDb client using the Config above
    let sdk_config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
    let dynamo_config = aws_sdk_dynamodb::config::Builder::from(&sdk_config)
        .interceptor(DbEsdkInterceptor::new(table_configs)?)
        .build();
    let ddb = aws_sdk_dynamodb::Client::from_conf(dynamo_config);

    // 6. Put an item into our table using the above client.
    //    Before the item gets sent to DynamoDb, it will be encrypted
    //    client-side, according to our configuration.
    let item = HashMap::from([
        (
            "partition_key".to_string(),
            AttributeValue::S("rawAesKeyringItem".to_string()),
        ),
        ("sort_key".to_string(), AttributeValue::N("0".to_string())),
        (
            "sensitive_data".to_string(),
            AttributeValue::S("encrypt and sign me!".to_string()),
        ),
    ]);

    ddb.put_item()
        .table_name(ddb_table_name)
        .set_item(Some(item.clone()))
        .send()
        .await?;

    // 7. Get the item back from our table using the same client.
    //    The client will decrypt the item client-side, and return
    //    back the original item.
    let key_to_get = HashMap::from([
        (
            "partition_key".to_string(),
            AttributeValue::S("rawAesKeyringItem".to_string()),
        ),
        ("sort_key".to_string(), AttributeValue::N("0".to_string())),
    ]);

    let resp = ddb
        .get_item()
        .table_name(ddb_table_name)
        .set_key(Some(key_to_get))
        // In this example we configure a strongly consistent read
        // because we perform a read immediately after a write (for demonstrative purposes).
        // By default, reads are only eventually consistent.
        // Read our docs to determine which read consistency to use for your application:
        // https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.ReadConsistency.html
        .consistent_read(true)
        .send()
        .await?;

    assert_eq!(resp.item, Some(item));

    println!("raw_aes_keyring successful.");
    Ok(())
}

examples/itemencryptor/item_encrypt_decrypt.rs (line 43)

pub async fn encrypt_decrypt() -> Result<(), crate::BoxError> {
    let kms_key_id = test_utils::TEST_KMS_KEY_ID;
    let ddb_table_name = test_utils::TEST_DDB_TABLE_NAME;

    // 1. Create a Keyring. This Keyring will be responsible for protecting the data keys that protect your data.
    //    For this example, we will create a AWS KMS Keyring with the AWS KMS Key we want to use.
    //    We will use the `CreateMrkMultiKeyring` method to create this keyring,
    //    as it will correctly handle both single region and Multi-Region KMS Keys.
    let provider_config = MaterialProvidersConfig::builder().build()?;
    let mat_prov = mpl_client::Client::from_conf(provider_config)?;
    let kms_keyring = mat_prov
        .create_aws_kms_mrk_multi_keyring()
        .generator(kms_key_id)
        .send()
        .await?;

    // 2. Configure which attributes are encrypted and/or signed when writing new items.
    //    For each attribute that may exist on the items we plan to write to our DynamoDbTable,
    //    we must explicitly configure how they should be treated during item encryption:
    //      - ENCRYPT_AND_SIGN: The attribute is encrypted and included in the signature
    //      - SIGN_ONLY: The attribute not encrypted, but is still included in the signature
    //      - DO_NOTHING: The attribute is not encrypted and not included in the signature
    let attribute_actions_on_encrypt = HashMap::from([
        ("partition_key".to_string(), CryptoAction::SignOnly),
        ("sort_key".to_string(), CryptoAction::SignOnly),
        ("attribute1".to_string(), CryptoAction::EncryptAndSign),
        ("attribute2".to_string(), CryptoAction::SignOnly),
        (":attribute3".to_string(), CryptoAction::DoNothing),
    ]);

    // 3. Configure which attributes we expect to be included in the signature
    //    when reading items. There are two options for configuring this:
    //
    //    - (Recommended) Configure `allowedUnsignedAttributesPrefix`:
    //      When defining your DynamoDb schema and deciding on attribute names,
    //      choose a distinguishing prefix (such as ":") for all attributes that
    //      you do not want to include in the signature.
    //      This has two main benefits:
    //      - It is easier to reason about the security and authenticity of data within your item
    //        when all unauthenticated data is easily distinguishable by their attribute name.
    //      - If you need to add new unauthenticated attributes in the future,
    //        you can easily make the corresponding update to your `attributeActionsOnEncrypt`
    //        and immediately start writing to that new attribute, without
    //        any other configuration update needed.
    //      Once you configure this field, it is not safe to update it.
    //
    //    - Configure `allowedUnsignedAttributes`: You may also explicitly list
    //      a set of attributes that should be considered unauthenticated when encountered
    //      on read. Be careful if you use this configuration. Do not remove an attribute
    //      name from this configuration, even if you are no longer writing with that attribute,
    //      as old items may still include this attribute, and our configuration needs to know
    //      to continue to exclude this attribute from the signature scope.
    //      If you add new attribute names to this field, you must first deploy the update to this
    //      field to all readers in your host fleet before deploying the update to start writing
    //      with that new attribute.
    //
    //   For this example, we have designed our DynamoDb table such that any attribute name with
    //   the ":" prefix should be considered unauthenticated.
    const UNSIGNED_ATTR_PREFIX: &str = ":";

    // 4. Create the configuration for the DynamoDb Item Encryptor
    let config = DynamoDbItemEncryptorConfig::builder()
        .logical_table_name(ddb_table_name)
        .partition_key_name("partition_key")
        .sort_key_name("sort_key")
        .attribute_actions_on_encrypt(attribute_actions_on_encrypt)
        .keyring(kms_keyring)
        .allowed_unsigned_attribute_prefix(UNSIGNED_ATTR_PREFIX)
        // Specifying an algorithm suite is not required,
        // but is done here to demonstrate how to do so.
        // We suggest using the
        // `ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY_ECDSA_P384_SYMSIG_HMAC_SHA384` suite,
        // which includes AES-GCM with key derivation, signing, and key commitment.
        // This is also the default algorithm suite if one is not specified in this config.
        // For more information on supported algorithm suites, see:
        //   https://docs.aws.amazon.com/database-encryption-sdk/latest/devguide/supported-algorithms.html
        .algorithm_suite_id(
            DbeAlgorithmSuiteId::AlgAes256GcmHkdfSha512CommitKeyEcdsaP384SymsigHmacSha384,
        )
        .build()?;

    // 5. Create the DynamoDb Item Encryptor
    let item_encryptor = enc_client::Client::from_conf(config)?;

    // 6. Directly encrypt a DynamoDb item using the DynamoDb Item Encryptor
    let original_item = HashMap::from([
        (
            "partition_key".to_string(),
            AttributeValue::S("ItemEncryptDecryptExample".to_string()),
        ),
        ("sort_key".to_string(), AttributeValue::N("0".to_string())),
        (
            "attribute1".to_string(),
            AttributeValue::S("encrypt and sign me!".to_string()),
        ),
        (
            "attribute2".to_string(),
            AttributeValue::S("sign me!".to_string()),
        ),
        (
            ":attribute3".to_string(),
            AttributeValue::S("ignore me!".to_string()),
        ),
    ]);

    let encrypted_item = item_encryptor
        .encrypt_item()
        .plaintext_item(original_item.clone())
        .send()
        .await?
        .encrypted_item
        .unwrap();

    // Demonstrate that the item has been encrypted
    assert_eq!(
        encrypted_item["partition_key"],
        AttributeValue::S("ItemEncryptDecryptExample".to_string())
    );
    assert_eq!(
        encrypted_item["sort_key"],
        AttributeValue::N("0".to_string())
    );
    assert!(encrypted_item["attribute1"].is_b());
    assert!(!encrypted_item["attribute1"].is_s());

    // 7. Directly decrypt the encrypted item using the DynamoDb Item Encryptor
    let decrypted_item = item_encryptor
        .decrypt_item()
        .encrypted_item(encrypted_item)
        .send()
        .await?
        .plaintext_item
        .unwrap();

    // Demonstrate that GetItem succeeded and returned the decrypted item
    assert_eq!(decrypted_item, original_item);
    println!("encrypt_decrypt successful.");
    Ok(())
}

examples/keyring/raw_rsa_keyring.rs (line 84)

pub async fn put_item_get_item() -> Result<(), crate::BoxError> {
    let ddb_table_name = test_utils::TEST_DDB_TABLE_NAME;

    // You may provide your own RSA key pair in the files located at
    //  - EXAMPLE_RSA_PRIVATE_KEY_FILENAME
    //  - EXAMPLE_RSA_PUBLIC_KEY_FILENAME
    // If these files are not present, this will generate a pair for you
    if should_generate_new_rsa_key_pair()? {
        generate_rsa_key_pair()?;
    }

    // 1. Load key pair from UTF-8 encoded PEM files.
    //    You may provide your own PEM files to use here.
    //    If you do not, the main method in this class will generate PEM
    //    files for example use. Do not use these files for any other purpose.

    let mut file = File::open(Path::new(EXAMPLE_RSA_PUBLIC_KEY_FILENAME))?;
    let mut public_key_utf8_bytes = Vec::new();
    file.read_to_end(&mut public_key_utf8_bytes)?;

    let mut file = File::open(Path::new(EXAMPLE_RSA_PRIVATE_KEY_FILENAME))?;
    let mut private_key_utf8_bytes = Vec::new();
    file.read_to_end(&mut private_key_utf8_bytes)?;

    // 2. Create the keyring.
    //    The DynamoDb encryption client uses this to encrypt and decrypt items.
    let mpl_config = MaterialProvidersConfig::builder().build()?;
    let mpl = mpl_client::Client::from_conf(mpl_config)?;
    let raw_rsa_keyring = mpl
        .create_raw_rsa_keyring()
        .key_name("my-rsa-key-name")
        .key_namespace("my-key-namespace")
        .padding_scheme(PaddingScheme::OaepSha256Mgf1)
        .public_key(public_key_utf8_bytes)
        .private_key(private_key_utf8_bytes)
        .send()
        .await?;

    // 3. Configure which attributes are encrypted and/or signed when writing new items.
    //    For each attribute that may exist on the items we plan to write to our DynamoDbTable,
    //    we must explicitly configure how they should be treated during item encryption:
    //      - ENCRYPT_AND_SIGN: The attribute is encrypted and included in the signature
    //      - SIGN_ONLY: The attribute not encrypted, but is still included in the signature
    //      - DO_NOTHING: The attribute is not encrypted and not included in the signature
    let attribute_actions_on_encrypt = HashMap::from([
        ("partition_key".to_string(), CryptoAction::SignOnly), // Our partition attribute must be SIGN_ONLY
        ("sort_key".to_string(), CryptoAction::SignOnly), // Our sort attribute must be SIGN_ONLY
        ("sensitive_data".to_string(), CryptoAction::EncryptAndSign),
    ]);

    // 4. Configure which attributes we expect to be included in the signature
    //    when reading items. There are two options for configuring this:
    //
    //    - (Recommended) Configure `allowedUnsignedAttributesPrefix`:
    //      When defining your DynamoDb schema and deciding on attribute names,
    //      choose a distinguishing prefix (such as ":") for all attributes that
    //      you do not want to include in the signature.
    //      This has two main benefits:
    //      - It is easier to reason about the security and authenticity of data within your item
    //        when all unauthenticated data is easily distinguishable by their attribute name.
    //      - If you need to add new unauthenticated attributes in the future,
    //        you can easily make the corresponding update to your `attributeActionsOnEncrypt`
    //        and immediately start writing to that new attribute, without
    //        any other configuration update needed.
    //      Once you configure this field, it is not safe to update it.
    //
    //    - Configure `allowedUnsignedAttributes`: You may also explicitly list
    //      a set of attributes that should be considered unauthenticated when encountered
    //      on read. Be careful if you use this configuration. Do not remove an attribute
    //      name from this configuration, even if you are no longer writing with that attribute,
    //      as old items may still include this attribute, and our configuration needs to know
    //      to continue to exclude this attribute from the signature scope.
    //      If you add new attribute names to this field, you must first deploy the update to this
    //      field to all readers in your host fleet before deploying the update to start writing
    //      with that new attribute.
    //
    //   For this example, we currently authenticate all attributes. To make it easier to
    //   add unauthenticated attributes in the future, we define a prefix ":" for such attributes.
    const UNSIGNED_ATTR_PREFIX: &str = ":";

    // 5. Create the DynamoDb Encryption configuration for the table we will be writing to.
    let table_config = DynamoDbTableEncryptionConfig::builder()
        .logical_table_name(ddb_table_name)
        .partition_key_name("partition_key")
        .sort_key_name("sort_key")
        .attribute_actions_on_encrypt(attribute_actions_on_encrypt)
        .keyring(raw_rsa_keyring)
        .allowed_unsigned_attribute_prefix(UNSIGNED_ATTR_PREFIX)
        .build()?;

    let table_configs = DynamoDbTablesEncryptionConfig::builder()
        .table_encryption_configs(HashMap::from([(ddb_table_name.to_string(), table_config)]))
        .build()?;

    // 6. Create a new AWS SDK DynamoDb client using the config above
    let sdk_config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
    let dynamo_config = aws_sdk_dynamodb::config::Builder::from(&sdk_config)
        .interceptor(DbEsdkInterceptor::new(table_configs)?)
        .build();
    let ddb = aws_sdk_dynamodb::Client::from_conf(dynamo_config);

    // 7. Put an item into our table using the above client.
    //    Before the item gets sent to DynamoDb, it will be encrypted
    //    client-side, according to our configuration.
    let item = HashMap::from([
        (
            "partition_key".to_string(),
            AttributeValue::S("rawRsaKeyringItem".to_string()),
        ),
        ("sort_key".to_string(), AttributeValue::N("0".to_string())),
        (
            "sensitive_data".to_string(),
            AttributeValue::S("encrypt and sign me!".to_string()),
        ),
    ]);

    ddb.put_item()
        .table_name(ddb_table_name)
        .set_item(Some(item.clone()))
        .send()
        .await?;

    // 8. Get the item back from our table using the same client.
    //    The client will decrypt the item client-side, and return
    //    back the original item.

    let key_to_get = HashMap::from([
        (
            "partition_key".to_string(),
            AttributeValue::S("rawRsaKeyringItem".to_string()),
        ),
        ("sort_key".to_string(), AttributeValue::N("0".to_string())),
    ]);

    let resp = ddb
        .get_item()
        .table_name(ddb_table_name)
        .set_key(Some(key_to_get))
        // In this example we configure a strongly consistent read
        // because we perform a read immediately after a write (for demonstrative purposes).
        // By default, reads are only eventually consistent.
        // Read our docs to determine which read consistency to use for your application:
        // https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.ReadConsistency.html
        .consistent_read(true)
        .send()
        .await?;

    assert_eq!(resp.item, Some(item));
    println!("raw_rsa_keyring successful.");
    Ok(())
}

examples/basic_get_put_example.rs (line 40)

pub async fn put_item_get_item() -> Result<(), crate::BoxError> {
    let kms_key_id = test_utils::TEST_KMS_KEY_ID;
    let ddb_table_name = test_utils::TEST_DDB_TABLE_NAME;

    // 1. Create a Keyring. This Keyring will be responsible for protecting the data keys that protect your data.
    //    For this example, we will create a AWS KMS Keyring with the AWS KMS Key we want to use.
    //    We will use the `CreateMrkMultiKeyring` method to create this keyring,
    //    as it will correctly handle both single region and Multi-Region KMS Keys.
    let provider_config = MaterialProvidersConfig::builder().build()?;
    let mat_prov = client::Client::from_conf(provider_config)?;
    let kms_keyring = mat_prov
        .create_aws_kms_mrk_multi_keyring()
        .generator(kms_key_id)
        .send()
        .await?;

    // 2. Configure which attributes are encrypted and/or signed when writing new items.
    //    For each attribute that may exist on the items we plan to write to our DynamoDbTable,
    //    we must explicitly configure how they should be treated during item encryption:
    //      - ENCRYPT_AND_SIGN: The attribute is encrypted and included in the signature
    //      - SIGN_ONLY: The attribute not encrypted, but is still included in the signature
    //      - DO_NOTHING: The attribute is not encrypted and not included in the signature
    let attribute_actions_on_encrypt = HashMap::from([
        ("partition_key".to_string(), CryptoAction::SignOnly),
        ("sort_key".to_string(), CryptoAction::SignOnly),
        ("attribute1".to_string(), CryptoAction::EncryptAndSign),
        ("attribute2".to_string(), CryptoAction::SignOnly),
        (":attribute3".to_string(), CryptoAction::DoNothing),
    ]);

    // 3. Configure which attributes we expect to be included in the signature
    //    when reading items. There are two options for configuring this:
    //
    //    - (Recommended) Configure `allowedUnsignedAttributesPrefix`:
    //      When defining your DynamoDb schema and deciding on attribute names,
    //      choose a distinguishing prefix (such as ":") for all attributes that
    //      you do not want to include in the signature.
    //      This has two main benefits:
    //      - It is easier to reason about the security and authenticity of data within your item
    //        when all unauthenticated data is easily distinguishable by their attribute name.
    //      - If you need to add new unauthenticated attributes in the future,
    //        you can easily make the corresponding update to your `attributeActionsOnEncrypt`
    //        and immediately start writing to that new attribute, without
    //        any other configuration update needed.
    //      Once you configure this field, it is not safe to update it.
    //
    //    - Configure `allowedUnsignedAttributes`: You may also explicitly list
    //      a set of attributes that should be considered unauthenticated when encountered
    //      on read. Be careful if you use this configuration. Do not remove an attribute
    //      name from this configuration, even if you are no longer writing with that attribute,
    //      as old items may still include this attribute, and our configuration needs to know
    //      to continue to exclude this attribute from the signature scope.
    //      If you add new attribute names to this field, you must first deploy the update to this
    //      field to all readers in your host fleet before deploying the update to start writing
    //      with that new attribute.
    //
    //   For this example, we have designed our DynamoDb table such that any attribute name with
    //   the ":" prefix should be considered unauthenticated.
    const UNSIGNED_ATTR_PREFIX: &str = ":";

    // 4. Create the DynamoDb Encryption configuration for the table we will be writing to.
    let table_config = DynamoDbTableEncryptionConfig::builder()
        .logical_table_name(ddb_table_name)
        .partition_key_name("partition_key")
        .sort_key_name("sort_key")
        .attribute_actions_on_encrypt(attribute_actions_on_encrypt)
        .keyring(kms_keyring)
        .allowed_unsigned_attribute_prefix(UNSIGNED_ATTR_PREFIX)
        // Specifying an algorithm suite is not required,
        // but is done here to demonstrate how to do so.
        // We suggest using the
        // `ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY_ECDSA_P384_SYMSIG_HMAC_SHA384` suite,
        // which includes AES-GCM with key derivation, signing, and key commitment.
        // This is also the default algorithm suite if one is not specified in this config.
        // For more information on supported algorithm suites, see:
        //   https://docs.aws.amazon.com/database-encryption-sdk/latest/devguide/supported-algorithms.html
        .algorithm_suite_id(
            DbeAlgorithmSuiteId::AlgAes256GcmHkdfSha512CommitKeyEcdsaP384SymsigHmacSha384,
        )
        .build()?;

    let table_configs = DynamoDbTablesEncryptionConfig::builder()
        .table_encryption_configs(HashMap::from([(ddb_table_name.to_string(), table_config)]))
        .build()?;

    // 5. Create a new AWS SDK DynamoDb client using the TableEncryptionConfigs
    let sdk_config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
    let dynamo_config = aws_sdk_dynamodb::config::Builder::from(&sdk_config)
        .interceptor(DbEsdkInterceptor::new(table_configs)?)
        .build();
    let ddb = aws_sdk_dynamodb::Client::from_conf(dynamo_config);

    // 6. Put an item into our table using the above client.
    //    Before the item gets sent to DynamoDb, it will be encrypted
    //    client-side, according to our configuration.
    let item = HashMap::from([
        (
            "partition_key".to_string(),
            AttributeValue::S("BasicPutGetExample".to_string()),
        ),
        ("sort_key".to_string(), AttributeValue::N("0".to_string())),
        (
            "attribute1".to_string(),
            AttributeValue::S("encrypt and sign me!".to_string()),
        ),
        (
            "attribute2".to_string(),
            AttributeValue::S("sign me!".to_string()),
        ),
        (
            ":attribute3".to_string(),
            AttributeValue::S("ignore me!".to_string()),
        ),
    ]);

    ddb.put_item()
        .table_name(ddb_table_name)
        .set_item(Some(item.clone()))
        .send()
        .await?;

    // 7. Get the item back from our table using the same client.
    //    The client will decrypt the item client-side, and return
    //    back the original item.
    let key_to_get = HashMap::from([
        (
            "partition_key".to_string(),
            AttributeValue::S("BasicPutGetExample".to_string()),
        ),
        ("sort_key".to_string(), AttributeValue::N("0".to_string())),
    ]);

    let resp = ddb
        .get_item()
        .table_name(ddb_table_name)
        .set_key(Some(key_to_get))
        // In this example we configure a strongly consistent read
        // because we perform a read immediately after a write (for demonstrative purposes).
        // By default, reads are only eventually consistent.
        // Read our docs to determine which read consistency to use for your application:
        // https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.ReadConsistency.html
        .consistent_read(true)
        .send()
        .await?;

    assert_eq!(resp.item, Some(item));
    println!("put_item_get_item successful.");
    Ok(())
}

examples/keyring/kms_rsa_keyring.rs (line 79)

pub async fn put_item_get_item() -> Result<(), crate::BoxError> {
    let ddb_table_name = test_utils::TEST_DDB_TABLE_NAME;
    let rsa_key_arn = test_utils::TEST_KMS_RSA_KEY_ID;

    // You may provide your own RSA public key at EXAMPLE_RSA_PUBLIC_KEY_FILENAME.
    // This must be the public key for the RSA key represented at rsaKeyArn.
    // If this file is not present, this will write a UTF-8 encoded PEM file for you.
    if should_get_new_public_key(DEFAULT_EXAMPLE_RSA_PUBLIC_KEY_FILENAME) {
        write_public_key_pem_for_rsa_key(
            test_utils::TEST_KMS_RSA_KEY_ID,
            DEFAULT_EXAMPLE_RSA_PUBLIC_KEY_FILENAME,
        )
        .await?;
    }

    // 1. Load UTF-8 encoded public key PEM file.
    //    You may have an RSA public key file already defined.
    //    If not, the main method in this class will call
    //    the KMS RSA key, retrieve its public key, and store it
    //    in a PEM file for example use.
    let mut file = File::open(Path::new(DEFAULT_EXAMPLE_RSA_PUBLIC_KEY_FILENAME))?;
    let mut public_key_utf8_bytes = Vec::new();
    file.read_to_end(&mut public_key_utf8_bytes)?;

    // 2. Create a KMS RSA keyring.
    //    This keyring takes in:
    //     - kmsClient
    //     - kmsKeyId: Must be an ARN representing a KMS RSA key
    //     - publicKey: A ByteBuffer of a UTF-8 encoded PEM file representing the public
    //                  key for the key passed into kmsKeyId
    //     - encryptionAlgorithm: Must be either RSAES_OAEP_SHA_256 or RSAES_OAEP_SHA_1
    let mpl_config = MaterialProvidersConfig::builder().build()?;
    let mpl = mpl_client::Client::from_conf(mpl_config)?;
    let sdk_config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
    let kms_rsa_keyring = mpl
        .create_aws_kms_rsa_keyring()
        .kms_key_id(rsa_key_arn)
        .public_key(public_key_utf8_bytes)
        .encryption_algorithm(aws_sdk_kms::types::EncryptionAlgorithmSpec::RsaesOaepSha256)
        .kms_client(aws_sdk_kms::Client::new(&sdk_config))
        .send()
        .await?;

    // 3. Configure which attributes are encrypted and/or signed when writing new items.
    //    For each attribute that may exist on the items we plan to write to our DynamoDbTable,
    //    we must explicitly configure how they should be treated during item encryption:
    //      - ENCRYPT_AND_SIGN: The attribute is encrypted and included in the signature
    //      - SIGN_ONLY: The attribute not encrypted, but is still included in the signature
    //      - DO_NOTHING: The attribute is not encrypted and not included in the signature
    let attribute_actions_on_encrypt = HashMap::from([
        ("partition_key".to_string(), CryptoAction::SignOnly), // Our partition attribute must be SIGN_ONLY
        ("sort_key".to_string(), CryptoAction::SignOnly), // Our sort attribute must be SIGN_ONLY
        ("sensitive_data".to_string(), CryptoAction::EncryptAndSign),
    ]);

    // 4. Configure which attributes we expect to be included in the signature
    //    when reading items. There are two options for configuring this:
    //
    //    - (Recommended) Configure `allowedUnsignedAttributesPrefix`:
    //      When defining your DynamoDb schema and deciding on attribute names,
    //      choose a distinguishing prefix (such as ":") for all attributes that
    //      you do not want to include in the signature.
    //      This has two main benefits:
    //      - It is easier to reason about the security and authenticity of data within your item
    //        when all unauthenticated data is easily distinguishable by their attribute name.
    //      - If you need to add new unauthenticated attributes in the future,
    //        you can easily make the corresponding update to your `attributeActions`
    //        and immediately start writing to that new attribute, without
    //        any other configuration update needed.
    //      Once you configure this field, it is not safe to update it.
    //
    //    - Configure `allowedUnsignedAttributes`: You may also explicitly list
    //      a set of attributes that should be considered unauthenticated when encountered
    //      on read. Be careful if you use this configuration. Do not remove an attribute
    //      name from this configuration, even if you are no longer writing with that attribute,
    //      as old items may still include this attribute, and our configuration needs to know
    //      to continue to exclude this attribute from the signature scope.
    //      If you add new attribute names to this field, you must first deploy the update to this
    //      field to all readers in your host fleet before deploying the update to start writing
    //      with that new attribute.
    //
    //   For this example, we currently authenticate all attributes. To make it easier to
    //   add unauthenticated attributes in the future, we define a prefix ":" for such attributes.
    const UNSIGNED_ATTR_PREFIX: &str = ":";

    // 5. Create the DynamoDb Encryption configuration for the table we will be writing to.
    //    Note: To use the KMS RSA keyring, your table config must specify an algorithmSuite
    //    that does not use asymmetric signing.
    let table_config = DynamoDbTableEncryptionConfig::builder()
        .logical_table_name(ddb_table_name)
        .partition_key_name("partition_key")
        .sort_key_name("sort_key")
        .attribute_actions_on_encrypt(attribute_actions_on_encrypt)
        .keyring(kms_rsa_keyring)
        .allowed_unsigned_attribute_prefix(UNSIGNED_ATTR_PREFIX)
        // Specify algorithmSuite without asymmetric signing here
        // As of v3.0.0, the only supported algorithmSuite without asymmetric signing is
        // ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY_SYMSIG_HMAC_SHA384.
        .algorithm_suite_id(DbeAlgorithmSuiteId::AlgAes256GcmHkdfSha512CommitKeySymsigHmacSha384)
        .build()?;

    let table_configs = DynamoDbTablesEncryptionConfig::builder()
        .table_encryption_configs(HashMap::from([(ddb_table_name.to_string(), table_config)]))
        .build()?;

    // 6. Create a new AWS SDK DynamoDb client using the DynamoDb Encryption Interceptor above
    let dynamo_config = aws_sdk_dynamodb::config::Builder::from(&sdk_config)
        .interceptor(DbEsdkInterceptor::new(table_configs)?)
        .build();
    let ddb = aws_sdk_dynamodb::Client::from_conf(dynamo_config);

    // 7. Put an item into our table using the above client.
    //    Before the item gets sent to DynamoDb, it will be encrypted
    //    client-side, according to our configuration.
    let item = HashMap::from([
        (
            "partition_key".to_string(),
            AttributeValue::S("awsKmsRsaKeyringItem".to_string()),
        ),
        ("sort_key".to_string(), AttributeValue::N("0".to_string())),
        (
            "sensitive_data".to_string(),
            AttributeValue::S("encrypt and sign me!".to_string()),
        ),
    ]);

    ddb.put_item()
        .table_name(ddb_table_name)
        .set_item(Some(item.clone()))
        .send()
        .await?;

    // 8. Get the item back from our table using the client.
    //    The client will decrypt the item client-side using the RSA keyring
    //    and return the original item.
    let key_to_get = HashMap::from([
        (
            "partition_key".to_string(),
            AttributeValue::S("awsKmsRsaKeyringItem".to_string()),
        ),
        ("sort_key".to_string(), AttributeValue::N("0".to_string())),
    ]);

    let resp = ddb
        .get_item()
        .table_name(ddb_table_name)
        .set_key(Some(key_to_get))
        .consistent_read(true)
        .send()
        .await?;

    assert_eq!(resp.item, Some(item));
    println!("kms_rsa_keyring successful.");
    Ok(())
}

examples/keyring/hierarchical_keyring.rs (line 112)

pub async fn put_item_get_item(
    tenant1_branch_key_id: &str,
    tenant2_branch_key_id: &str,
) -> Result<(), crate::BoxError> {
    let ddb_table_name = test_utils::TEST_DDB_TABLE_NAME;

    let keystore_table_name = test_utils::TEST_KEYSTORE_NAME;
    let logical_keystore_name = test_utils::TEST_LOGICAL_KEYSTORE_NAME;
    let kms_key_id = test_utils::TEST_KEYSTORE_KMS_KEY_ID;

    // Initial KeyStore Setup: This example requires that you have already
    // created your KeyStore, and have populated it with two new branch keys.
    // See the "Create KeyStore Table Example" and "Create KeyStore Key Example"
    // for an example of how to do this.

    // 1. Configure your KeyStore resource.
    //    This SHOULD be the same configuration that you used
    //    to initially create and populate your KeyStore.
    let sdk_config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
    let key_store_config = KeyStoreConfig::builder()
        .kms_client(aws_sdk_kms::Client::new(&sdk_config))
        .ddb_client(aws_sdk_dynamodb::Client::new(&sdk_config))
        .ddb_table_name(keystore_table_name)
        .logical_key_store_name(logical_keystore_name)
        .kms_configuration(KmsConfiguration::KmsKeyArn(kms_key_id.to_string()))
        .build()?;

    let key_store = keystore_client::Client::from_conf(key_store_config)?;

    // 2. Create a Branch Key ID Supplier. See ExampleBranchKeyIdSupplier in this directory.
    let dbesdk_config = DynamoDbEncryptionConfig::builder().build()?;
    let dbesdk = dbesdk_client::Client::from_conf(dbesdk_config)?;
    let supplier = ExampleBranchKeyIdSupplier::new(tenant1_branch_key_id, tenant2_branch_key_id);

    let branch_key_id_supplier = dbesdk
        .create_dynamo_db_encryption_branch_key_id_supplier()
        .ddb_key_branch_key_id_supplier(supplier)
        .send()
        .await?
        .branch_key_id_supplier
        .unwrap();

    // 3. Create the Hierarchical Keyring, using the Branch Key ID Supplier above.
    //    With this configuration, the AWS SDK Client ultimately configured will be capable
    //    of encrypting or decrypting items for either tenant (assuming correct KMS access).
    //    If you want to restrict the client to only encrypt or decrypt for a single tenant,
    //    configure this Hierarchical Keyring using `.branchKeyId(tenant1BranchKeyId)` instead
    //    of `.branchKeyIdSupplier(branchKeyIdSupplier)`.
    let mpl_config = MaterialProvidersConfig::builder().build()?;
    let mpl = mpl_client::Client::from_conf(mpl_config)?;

    let hierarchical_keyring = mpl
        .create_aws_kms_hierarchical_keyring()
        .branch_key_id_supplier(branch_key_id_supplier)
        .key_store(key_store)
        .ttl_seconds(600)
        .send()
        .await?;

    // 4. Configure which attributes are encrypted and/or signed when writing new items.
    //    For each attribute that may exist on the items we plan to write to our DynamoDbTable,
    //    we must explicitly configure how they should be treated during item encryption:
    //      - ENCRYPT_AND_SIGN: The attribute is encrypted and included in the signature
    //      - SIGN_ONLY: The attribute not encrypted, but is still included in the signature
    //      - DO_NOTHING: The attribute is not encrypted and not included in the signature
    let attribute_actions_on_encrypt = HashMap::from([
        ("partition_key".to_string(), CryptoAction::SignOnly), // Our partition attribute must be SIGN_ONLY
        ("sort_key".to_string(), CryptoAction::SignOnly), // Our sort attribute must be SIGN_ONLY
        (
            "tenant_sensitive_data".to_string(),
            CryptoAction::EncryptAndSign,
        ),
    ]);

    // 5. Configure which attributes we expect to be included in the signature
    //    when reading items. There are two options for configuring this:
    //
    //    - (Recommended) Configure `allowedUnsignedAttributesPrefix`:
    //      When defining your DynamoDb schema and deciding on attribute names,
    //      choose a distinguishing prefix (such as ":") for all attributes that
    //      you do not want to include in the signature.
    //      This has two main benefits:
    //      - It is easier to reason about the security and authenticity of data within your item
    //        when all unauthenticated data is easily distinguishable by their attribute name.
    //      - If you need to add new unauthenticated attributes in the future,
    //        you can easily make the corresponding update to your `attributeActionsOnEncrypt`
    //        and immediately start writing to that new attribute, without
    //        any other configuration update needed.
    //      Once you configure this field, it is not safe to update it.
    //
    //    - Configure `allowedUnsignedAttributes`: You may also explicitly list
    //      a set of attributes that should be considered unauthenticated when encountered
    //      on read. Be careful if you use this configuration. Do not remove an attribute
    //      name from this configuration, even if you are no longer writing with that attribute,
    //      as old items may still include this attribute, and our configuration needs to know
    //      to continue to exclude this attribute from the signature scope.
    //      If you add new attribute names to this field, you must first deploy the update to this
    //      field to all readers in your host fleet before deploying the update to start writing
    //      with that new attribute.
    //
    //   For this example, we currently authenticate all attributes. To make it easier to
    //   add unauthenticated attributes in the future, we define a prefix ":" for such attributes.
    const UNSIGNED_ATTR_PREFIX: &str = ":";

    // 6. Create the DynamoDb Encryption configuration for the table we will be writing to.
    let table_config = DynamoDbTableEncryptionConfig::builder()
        .logical_table_name(ddb_table_name)
        .partition_key_name("partition_key")
        .sort_key_name("sort_key")
        .attribute_actions_on_encrypt(attribute_actions_on_encrypt)
        .keyring(hierarchical_keyring)
        .allowed_unsigned_attribute_prefix(UNSIGNED_ATTR_PREFIX)
        .build()?;

    let table_configs = DynamoDbTablesEncryptionConfig::builder()
        .table_encryption_configs(HashMap::from([(ddb_table_name.to_string(), table_config)]))
        .build()?;

    // 7. Create a new AWS SDK DynamoDb client using the DynamoDb Encryption Interceptor above
    let sdk_config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
    let dynamo_config = aws_sdk_dynamodb::config::Builder::from(&sdk_config)
        .interceptor(DbEsdkInterceptor::new(table_configs)?)
        .build();
    let ddb = aws_sdk_dynamodb::Client::from_conf(dynamo_config);

    // 8. Put an item into our table using the above client.
    //    Before the item gets sent to DynamoDb, it will be encrypted
    //    client-side, according to our configuration.
    //    Because the item we are writing uses "tenantId1" as our partition value,
    //    based on the code we wrote in the ExampleBranchKeySupplier,
    //    `tenant1BranchKeyId` will be used to encrypt this item.
    let item = HashMap::from([
        (
            "partition_key".to_string(),
            AttributeValue::S("tenant1Id".to_string()),
        ),
        ("sort_key".to_string(), AttributeValue::N("0".to_string())),
        (
            "tenant_sensitive_data".to_string(),
            AttributeValue::S("encrypt and sign me!".to_string()),
        ),
    ]);

    ddb.put_item()
        .table_name(ddb_table_name)
        .set_item(Some(item.clone()))
        .send()
        .await?;

    // 9. Get the item back from our table using the same client.
    //     The client will decrypt the item client-side, and return
    //     back the original item.
    //     Because the returned item's partition value is "tenantId1",
    //     based on the code we wrote in the ExampleBranchKeySupplier,
    //     `tenant1BranchKeyId` will be used to decrypt this item.
    let key_to_get = HashMap::from([
        (
            "partition_key".to_string(),
            AttributeValue::S("tenant1Id".to_string()),
        ),
        ("sort_key".to_string(), AttributeValue::N("0".to_string())),
    ]);

    let resp = ddb
        .get_item()
        .table_name(ddb_table_name)
        .set_key(Some(key_to_get))
        .consistent_read(true)
        .send()
        .await?;

    assert_eq!(resp.item, Some(item));
    println!("hierarchical_keyring successful.");
    Ok(())
}

Additional examples can be found in:

• examples/keyring/mrk_discovery_multi_keyring.rs
• examples/keyring/multi_keyring.rs
• examples/multi_get_put_example.rs
• examples/clientsupplier/client_supplier_example.rs
• examples/keyring/multi_mrk_keyring.rs
• examples/searchableencryption/compound_beacon_searchable_encryption.rs
• examples/searchableencryption/beacon_styles_searchable_encryption.rs
• examples/searchableencryption/virtual_beacon_searchable_encryption.rs
• examples/searchableencryption/basic_searchable_encryption.rs
• examples/searchableencryption/complexexample/beacon_config.rs

Trait Implementations

impl Clone for Client

fn clone(&self) -> Client

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Client

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq for Client

fn eq(&self, other: &Client) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for Client